AI エージェントが即座に活躍できるコードベース設計図
新しく入ったメンバーが初日から本番コードに変更を入れられるリポジトリ。これは多くの開発組織にとって理想ですが、現実には数週間のオンボーディング期間が必要です。ところが Claude Code のような AI エージェントの場合、その『数週間』は10分に圧縮できます。条件は一つだけ。コードベースが、エージェントが読むことを前提に設計されていることです。
私はこの一年、Claude Code に大規模リポジトリを触らせる中で、エージェントが詰まる箇所と滑らかに動く箇所には明確なパターンがあることに気づきました。ここではその観察から導いた設計原則を、すぐに実装できる形でお伝えします。
なぜ『AI エージェント向け設計』が新しい技術領域なのか
従来のコードベース設計は、人間の開発者が長期的に保守することを前提にしてきました。ディレクトリ構造、命名規則、テスト戦略、すべてが『慣れれば理解できる』という前提に立っています。慣れるまでに時間がかかるのは当然のコストとして受け入れられてきたのです。
ところが AI エージェントには『慣れる』というプロセスがありません。毎回がゼロからのスタートです。エージェントが読み取れる情報は、その時点でリポジトリに書かれていることだけ。暗黙知や口伝で伝わっていた『この関数はこういう意図で書かれた』『この設定はあのバグの対策だ』といった情報は、エージェントには見えません。
この制約は逆に、コードベースの真の品質を測る試金石にもなります。AI エージェントが10分で全体像を掴めるリポジトリは、新しい人間の開発者にとっても優れたリポジトリです。エージェント向けの設計を突き詰めると、結果的に組織全体の開発生産性が向上するのです。
第一原則：トップレベルに『地図』を置く
リポジトリのルートに CLAUDE.md を置く。これが最初に取り組むべきことです。Claude Code は起動時にこのファイルを自動的に読み込みます。エージェントにとっての『最初の説明』にあたる重要な役割を担います。
ただし、ここで多くの組織が間違えます。CLAUDE.md に詳細な API 仕様や個別のクラス説明を書いてしまうのです。それは間違いです。CLAUDE.md は『地図』であって『辞書』ではありません。
地図に書くべきは、こういった内容です。
- このリポジトリが何を解決するためのプロジェクトか（1〜2文）
- 主要なディレクトリの役割（src/, tests/, scripts/ などの責務）
- ビルド・テスト・デプロイの一行コマンド（実行可能な形で）
- 開発時に絶対守るべきルール（破壊的変更の制約・テスト必須箇所など）
- 詳細を読みたい時の参照先（_documents/ への誘導）
逆に書いてはいけないのは、特定の関数の詳細実装、頻繁に変わる API レスポンス形式、個別バグの修正履歴などです。これらは別ファイルに分離し、CLAUDE.md からはリンクで誘導する形にします。
# プロジェクト名
## 一行サマリー
ユーザーの〇〇を解決する、〇〇基盤の SaaS。
## ディレクトリの役割
- src/api/ — REST エンドポイント定義
- src/domain/ — ビジネスロジック（外部依存なし）
- src/infra/ — DB・外部 API のアダプタ
- _documents/ — 設計書・運用ガイド
## 開発コマンド
- 開発サーバー起動: `npm run dev`
- 全テスト実行: `npm test`
- 型チェック: `npm run typecheck`
## 重要ルール
- src/domain/ から src/infra/ への直接依存は禁止（依存逆転）
- 新規エンドポイント追加時は tests/integration/ にテスト必須
- マイグレーション変更時は _documents/MIGRATIONS.md を更新このシンプルさが鍵です。エージェントは CLAUDE.md を読み終えた瞬間に『この後どこを読めばよいか』が判断できる状態でなければなりません。
第二原則：契約境界（Contract Boundaries）を明示する
AI エージェントが恐れず変更を加えられる範囲と、加えてはいけない範囲を、コード自体に書き込みます。これを私は『契約境界』と呼んでいます。
具体的には、以下のような仕組みを組み合わせます。
型システムによる境界定義
TypeScript なら、変更されては困る公開 API を専用の型ファイルに分離します。types/contracts.ts のように、ファイル名自体に意図を込めるのです。エージェントは「contracts」という名前から、この型定義は他のコードから依存される契約であり、軽々に変更してはいけないと判断できます。
// types/contracts.ts
// このファイルの型は外部公開 API です。変更時は v2 ブランチで段階的に行うこと。
export interface UserPublicProfile {
readonly id: string;
readonly displayName: string;
readonly joinedAt: string; // ISO 8601
}コメントによる意図の明示
実装の意図がコードから読み取れない箇所には、必ずコメントを残します。エージェントは『なぜこう書かれているか』が分からない時、最も誤った変更をします。
// 意図: ここで await を使わないのは、レート制限ヒット時に
// 即座にレスポンスを返すため。並列実行は意図的。
results.forEach(item => fireAndForget(item));ディレクトリ単位の README
src/payment/ のような重要なディレクトリには、その配下に短い README.md を置きます。3〜5行で十分です。「このディレクトリの責務」「変更時の注意点」「依存している外部サービス」を書きます。
第三原則：テストが仕様書として機能する状態にする
AI エージェントがコードを変更した時、最も恐ろしいのは『動いているように見えて壊れている』状態です。これを防ぐ唯一の方法は、テストが仕様書として機能していることです。
エージェントが動かしやすいテスト環境には、明確な特徴があります。
第一に、npm test のような一行コマンドで全テストが実行できること。引数を覚えなくても全件実行できる設計が必要です。第二に、テストが失敗した時、どの仕様が破綻したかが一目で分かるテスト名であること。test('should return 400 when email format is invalid') のように、英文として読めるテスト名にします。第三に、テストの実行時間が短いこと。エージェントは試行錯誤を重ねるため、1回のテスト実行に5分かかると効率が大きく落ちます。
私のおすすめは、ピラミッド型のテスト戦略です。ユニットテストを下層に大量に置き（実行時間1分未満）、統合テストを中層に（5分未満）、E2E テストを上層に少数置く（10分未満）。エージェントには通常ユニットと統合まで実行させ、E2E は CI に任せる運用が現実的です。
第四原則：エージェント専用のスクリプトを用意する
人間の開発者にとっては自明な手順でも、エージェントには見えません。だからこそ、頻出する操作はスクリプト化します。
# scripts/ai-onboarding.sh
# 新しい AI セッションが最初に実行すべきコマンド集
#!/bin/bash
echo "=== Repository status ==="
git status --short
echo ""
echo "=== Recent commits ==="
git log --oneline -10
echo ""
echo "=== Current branch ==="
git branch --show-current
echo ""
echo "=== Test status ==="
npm test --silent 2>&1 | tail -5このような『環境を一望するスクリプト』をリポジトリに含めておくと、エージェントは最初にこれを実行することで現状を把握できます。CLAUDE.md にも「最初に bash scripts/ai-onboarding.sh を実行すること」と書いておきましょう。
他にも、よくあるタスクをスクリプト化しておくと便利です。新規ファイル生成のテンプレート（scripts/new-endpoint.sh）、データベースマイグレーションの実行手順（scripts/migrate.sh）、ローカル環境のリセット（scripts/reset-local.sh）など。エージェントはこれらを発見し、適切に呼び出すことができます。
第五原則：ガードレールを CI に組み込む
最後の砦は CI です。エージェントが間違った変更を加えても、CI で必ず捕まる仕組みを作ります。
最低限組み込むべきチェックは以下の通りです。
# .github/workflows/ci.yml の主要ジョブ
# - lint: コードスタイル違反の検出
# - typecheck: 型エラーの検出
# - test: 全テストの実行
# - build: 本番ビルドが通ることの確認
# - secret-scan: APIキー漏洩の検出
# - bundle-size: バンドルサイズの肥大化警告特に重要なのが secret-scan です。AI エージェントは時々、コード例にプレースホルダーのつもりで実フォーマットの API キーを書いてしまうことがあります。GitHub の Secret Scanning や TruffleHog などを CI に組み込み、リポジトリに混入する前に止めます。
bundle-size のチェックも侮れません。エージェントは依存ライブラリを気軽に追加することがあるため、バンドルサイズが急増していないか監視する仕組みが必要です。
段階的な導入ロードマップ
ここまでお話しした原則を、いきなり全て導入するのは現実的ではありません。私が実際に試した中で、効果的だった順序があります。
最初の一週間で取り組むべきは CLAUDE.md の整備です。これだけでもエージェントの初動が劇的に改善します。次の二週間で、ディレクトリ単位の README とエージェント専用スクリプトを整備します。これで日常的な作業がスムーズになります。
その後の一ヶ月で、契約境界の明示とテスト戦略の見直しを行います。これが最も時間がかかりますが、長期的なリターンも最大です。最後に CI のガードレール強化に取り組みます。
この順序で進めると、各段階で目に見える改善があるため、組織全体の理解と協力が得やすくなります。
効果測定の指標
設計改善の効果は、以下の指標で測れます。
エージェントが PR を出すまでの平均時間。改善前後で半減することが多いです。エージェントの PR が一発で通る率（人間のレビューで大きな修正なしにマージされる割合）。これは50%から80%程度まで上がります。リポジトリに新しく入った人間の開発者が、最初のコミットを作るまでの時間。これも大幅に短縮されます。
これらの指標は、AI エージェントだけでなく、人間の開発者の生産性向上を表す指標でもあります。コードベースが『読まれることを前提に設計されている』状態は、誰にとっても歓迎すべきものなのです。
次の一歩
このガイドを読み終えた今、まず取り組むべきは自リポジトリの CLAUDE.md を見直すことです。今ある CLAUDE.md（あれば）を以下の三つの観点で点検してみてください。
ディレクトリの役割が3行以内で分かるか。開発コマンドが実行可能な形で書かれているか。詳細情報への参照（_documents/ など）が明示されているか。この三点を満たすだけでも、AI エージェントの初動は大きく変わります。