TL;DR
- AI を安定させる起点は、長いプロンプトではなく リポジトリ側の責務分離 にある
CLAUDE.mdは入口であって本体ではない。役割分担はsubagents、強制はhooks、継続知識はmemory、外部参照はMCPに分けたほうが迷いにくい- OpenAI がいう
agent legibilityは、人間向け可読性の上位互換ではなく、AI が推測せずに業務ドメインを辿れる構造 に近い - 最小構成でも「入口ファイル」「局所ルール」「決定論的ガード」「真実の置き場」の 4 点を分けるだけで、AI の誤作動はかなり減る
はじめに
Claude Code や Codex を使い始めると、多くのチームが最初にやるのは「AI にちゃんと読ませるための長い指示文」を作ることです。
もちろん、それ自体は間違いではありません。ただ、そこで止まると、だいたい次の症状が出ます。
- 同じ repo なのにセッションごとに判断がぶれる
- 安全ルールを書いたのに、たまに無視される
- 何をどこで参照すべきかが曖昧で、AI が推測で埋め始める
- 人間向け docs はあるのに、AI には業務ドメインの境界が見えていない
ここで必要なのは、プロンプト改善ではなく環境設計です。
すでにこのサイトでは、CLAUDE.md 最適化の本質 や、Codex の subagents 入門、MCP ガードレール設計 を個別論点として扱ってきました。本記事ではそれらを 1 つ上のレイヤーで束ねます。テーマは「AI が迷わない repo は、どう設計すべきか」です。
2026-04-04 時点の一次情報を見ると、Anthropic 側では memory、subagents、hooks、MCP がそれぞれ明確な責務を持つ機能として整理されています。OpenAI 側でも、Codex の agent loop や harness engineering の文脈で、エージェントが作業しやすい構造をどう作るかが前に出てきています。
結論を先に言うと、AI が迷わない repo は「全部を 1 つの指示ファイルに書いた repo」ではありません。
何を入口に置くか、何を分業させるか、何を機械的に強制するか、何を外部参照に逃がすか。
この分離ができている repo です。
1. なぜ AI は repo の中で迷うのか
AI が迷う原因は、能力不足よりも 構造不足 であることが多いです。
具体的には、次の 4 つが混ざっていると誤作動が増えます。
| 混ざっているもの | 起きやすい症状 |
|---|---|
| 目的と手順 | 何のための作業かより、目先の作法に引っ張られる |
| ルールと祈り | 「守ってほしい」が「守らせる」に変換されない |
| 永続知識と一時文脈 | セッションごとに必要な説明を毎回やり直す |
| 真実の所在と要約 | 古いまとめを信じて、一次情報を取りに行かない |
AI は、曖昧な repo でもそれっぽく埋めて前進できます。だから厄介です。止まるならまだ良くて、実際には推測で進むことが多い。
この問題は、人間のオンボーディングに似ています。新メンバーに「たぶんこのへん見れば分かるよ」と言うチームでは、最初の数週間ずっと判断コストが高いままです。AI も同じで、業務ドメインの地図と作業境界が見えていない repo では、精度より先に迷いが増えます。
OpenAI が Codex の agent loop を説明するときも、中心にあるのは「ユーザー入力 -> モデル推論 -> ツール実行 -> 観測 -> 次の判断」の反復です。つまり、AI は常に今ある観測結果から次の行動を決める作業者です。repo 側に観測しやすい構造がなければ、良いループは回りません。
2. CLAUDE.md 最適化だけでは足りない理由
これは Claude Code 利用者が最初にぶつかる壁です。
Anthropic の memory ドキュメントでは、セッションは毎回新しい文脈から始まり、継続的な知識は CLAUDE.md や memory files で持つと説明されています。ここから分かるのは、CLAUDE.md は重要だけれど、万能ではないということです。
CLAUDE.md に向いているのは、たとえば次のような情報です。
- この repo は何を作っているのか
- 主要ディレクトリの責務は何か
- 全体に効く禁止事項や基本コマンドは何か
- どの文書が真実の置き場か
逆に、CLAUDE.md に全部を入れると崩れます。
- 領域ごとの詳細ルール
- たまにしか使わない手順
- 機械的に必ず守らせたい制約
- 外部システムの最新状態
この話は、すでに CLAUDE.md最適化の本質は、長いプロンプトを書くことではない でも触れました。今回さらに強調したいのは、CLAUDE.md を良くするだけでは、AI が迷わない repo にはならないという点です。
なぜなら、迷わない repo には「入口」以外の設計が必要だからです。
3. 役割分担は subagents に逃がす
Anthropic は custom subagents を、タスク特化のワークフローとコンテキスト管理を改善する仕組みとして案内しています。OpenAI 側でも、Codex の subagents は「親エージェントを要件整理と最終判断に集中させるための分業」として説明されています。
この 2 つを並べると、かなり強い原則が見えてきます。
AI に全部考えさせない。仕事の種類ごとに、読む文脈と返す出力を分ける。
実務では、たとえば次の分離が有効です。
| 役割 | 主な責務 | 親に返すもの |
|---|---|---|
| 設計レビュー担当 | 要件との整合、責務分離、依存方向の確認 | リスク一覧、設計差分、代替案 |
| 実装担当 | コード変更、影響範囲の把握、最小修正 | 修正結果、未解決論点 |
| テスト担当 | 不足ケース、回帰検知、検証観点 | テストギャップ、追加候補 |
| ドキュメント担当 | README / spec / runbook 整合 | 更新箇所、欠落箇所 |
ここで大事なのは、subagent を「速くする機能」とだけ見ないことです。むしろ効いているのは、ノイズの隔離です。
探索ログ、grep 結果、テスト出力、関連ファイル読み込みのメモを親スレッドに全部流し込むと、メインエージェントの判断文脈が汚れます。OpenAI が agent loop や subagent 概念で繰り返し強調しているのも、この文脈管理です。
repo 設計に翻訳すると、subagents は「人員追加」ではなく、責務分離の実装手段です。
4. ガードレールは hooks に置く
自然言語で「絶対に守ってください」と書いても、それは文脈です。強制ではありません。
Anthropic の hooks は、Claude Code のライフサイクルの特定タイミングで自動実行される仕組みです。ここで考え方を切り替える必要があります。
CLAUDE.md: 守ってほしい背景と方針hooks: 必ず実行される制御
この分離をしないと、repo はすぐ祈りの塊になります。
hooks に向いているのは、たとえば次のようなものです。
- 危険な書き込みや破壊的コマンドの遮断
- 特定パス変更時の lint / test 実行
- 監査ログの追記
- 作業前後の定型チェック
言い換えると、判断は AI に任せても、境界は AI に任せないということです。
Growth Lab のように品質ゲートを重視する運用では、この考え方は特に重要です。レビュー基準や作法をファイルに書くだけではなく、「どの地点で何を強制するか」を repo に配線しておくと、AI の再現性がかなり上がります。
5. 継続知識は memory、最新状態は MCP に分ける
ここも混ざりやすいポイントです。
memory が持つべきもの
memory は、毎セッション繰り返し説明したくない継続知識です。
- チームの編集方針
- よく使う判断基準
- repo の暗黙ルール
- 継続中の設計方針
要するに、「知らないと毎回ぶれるが、頻繁には変わらないもの」です。
MCP が持つべきもの
MCP は逆で、取りに行くべき最新情報に向いています。Anthropic の MCP 説明でも、Claude Code を外部ツールやデータソースにつなぐ手段として位置づけられています。
向いているのは次のような情報です。
- GitHub の PR / Issue 状態
- DB や社内 API の実データ
- Notion や docs の最新版
- 外部サービスの current state
この 2 つを混ぜると、repo はすぐ壊れます。最新状態を手書きの指示ファイルへ埋め込むと腐りますし、毎回同じ背景説明を API から引いてくるのも非効率です。
設計原則としてはこうです。
長く効く知識は memory に。変わる事実は MCP 越しに取りに行く。
AI が迷わない repo は、「何を覚えるべきか」と「何を都度参照すべきか」の境界が明確です。
6. Codex の agent legibility から見た共通原則
OpenAI の harness engineering と agent loop の文脈で重要なのは、AI が動きやすい構造を後付けのプロンプトではなく、実行環境として作るという発想です。
ここでいう agent legibility は、単なる人間向け可読性と少し違います。もちろん読みやすいコードは大事です。ただ、それだけでは足りません。
AI にとって legible な repo には、少なくとも次の条件があります。
- 何が SSoT なのかが明示されている
- どこまで編集してよいかが境界として見える
- 意思決定の根拠が docs や spec に残っている
- 作業フローが再利用可能な単位に分かれている
- 観測結果をどこへ返せばいいかが分かる
この観点で見ると、Anthropic の subagents / hooks / memory / MCP も、OpenAI の agent loop / agent legibility も、実は同じ方向を向いています。
どちらも「AI を賢くする」より、「AI が迷いにくい構造を作る」に寄っています。
7. 最小導入パターンは 4 分割で十分
ここまで読むと大がかりに見えるかもしれませんが、最初から全部やる必要はありません。
最小構成なら、次の 4 分割だけで効果が出ます。
1. 入口ファイルを短くする
CLAUDE.md や AGENTS.md には、目的、地図、全体ルール、真実の置き場だけを書く。
たとえば最初の叩き台は、このくらいで十分です。
repo-root/
├── AGENTS.md # 目的 / 全体ルール / SSoT の案内
├── spec/ # requirements / design / tasks
├── docs/ # ADR / runbook / architecture
├── .claude/
│ ├── hooks/ # 強制実行するガードレール
│ └── agents/ # 役割分担した subagent 定義
└── src/
├── billing/AGENTS.md # 危険領域の局所ルール
└── auth/AGENTS.md # 危険領域の局所ルール
2. 局所ルールを危険地帯に置く
認証、課金、DB migration、公開フローのような事故りやすい領域だけ、子ディレクトリのルールや補助ドキュメントを置く。
3. 強制事項を hooks に逃がす
「守ってほしい」ではなく「実行される」に変換する。
4. 最新状態を MCP から取りに行かせる
repo に書き込むのは構造化された知識だけにして、変動情報はツール経由で参照する。
この 4 点だけでも、AI の迷い方はかなり変わります。
8. よくあるアンチパターン
全部を 1 ファイルに押し込む
入口ファイルが長文化すると、重要度の差が消えます。AI にとっては「全部大事」に見えやすく、結果として本当に大事なルールが埋もれます。
docs はあるが SSoT が分からない
README、spec、Notion、Issue、Wiki に情報が散っていて、どれが正本か不明な状態です。AI は散在した情報を平均化してしまいがちなので、正解率よりそれっぽさが上がってしまいます。
手順だけ書いて責務を分けていない
「まずこれして、次にこれして」はあっても、誰が何を判断するかが曖昧な状態です。subagents や担当分離を入れても、返却物が曖昧だと親が統合できません。
最新状態を repo に書いてしまう
PR 状態、運用メモ、外部データの current state を Markdown に埋め込み続けると、repo が stale な運用台帳になります。MCP や外部ツールで取るべき情報まで抱え込まないことが大事です。
9. まずやるべきチェックリスト
最後に、導入前後でそのまま使えるチェックリストを置いておきます。
CLAUDE.md/AGENTS.mdは「入口」に徹していて、長文化しすぎていないか- 目的、repo map、禁止事項、真実の置き場が 1 画面で見えるか
- 危険操作や品質ゲートが hooks 等で機械的に強制されているか
- 役割ごとの返却物が定義され、subagent の責務が狭く保たれているか
- 継続知識と最新状態の境界があり、MCP に逃がすべき情報を repo に書いていないか
- specs / ADR / runbook のどれが SSoT か AI から見て分かるか
- AI が迷ったとき、どの docs を読み、どこへ報告すべきかが明示されているか
この 7 項目が揃うと、AI は「なんとなくそれっぽく動く存在」から、「境界が見えた作業者」に変わっていきます。
まとめ
AI が迷わない repo を作るうえで、いちばん大事なのは魔法のプロンプトではありません。
大事なのは、repo そのものを作業環境として設計することです。
- 入口は短く
- 責務は分ける
- 強制は機械に寄せる
- 最新状態は取りに行く
この原則で見ると、Claude Code の subagents / hooks / memory / MCP と、Codex の agent legibility はきれいにつながります。
「AI に何を書かせるか」より先に、「AI がどこで迷うか」を repo 側で潰す。
ここから始めると、AI 開発環境はかなり壊れにくくなります。
次に読むなら、入口設計は CLAUDE.md最適化の本質は、長いプロンプトを書くことではない、分業設計は Codexのsubagents入門、外部参照の安全設計は MCPガードレールと権限制御の設計 がつながります。
