AIが迷わないリポジトリ設計

TL;DR

• AIエージェントの出力が安定しない原因は、プロンプトではなくリポジトリ構造側にあることが多い
• ルール階層 / エージェント定義 / スキル・フック配置 / 作業コンテキストの 4パターンで整理すると、どこに何を置くかの判断が一意になる
• うち3つは Claude Code / Codex の公式機能ベース、1つは doc/Working/ を使った 独自応用
• 今日やる1アクション: AGENTS.md の冒頭に 優先順位宣言（SSoT行）を1行追加する

なぜ「プロンプト」ではなく「リポジトリ構造」なのか

プロンプトエンジニアリングが行き詰まる3つの理由

Claude Code や Codex を本格導入した現場でよく聞くのは「プロンプトをいくら練っても出力が安定しない」という声です。背景にはだいたい3つの限界があります。

1. 同じ指示を毎回書き直している――プロンプト単発では "ルール" が残らず、別セッションでは無視される
2. CLAUDE.md が肥大化して参照品質が落ちる――すべて1ファイルに詰めると、AIも人間も読み飛ばす
3. エージェント・ツール・作業状態の置き場所が混在している――どこを見るか迷ったAIは、一番最初に見つけた古い情報を使う

この3つはどれもプロンプト側では解けません。構造側で解く必要があるのが出発点です。

構造で精度が上がる観測指標

「構造で精度が上がる」と言うとき、計測できるシグナルは以下あたりです。

• 同じ指示を複数セッションで再記述する頻度
• AIが古い情報を参照して手戻りした回数
• PRレビューで AI 由来の一貫性欠如（命名ぶれ・ポリシー違反）が指摘された回数

Growth Lab（本ブログのリポジトリ）では、AGENTS.md を SSoT として宣言し、ツール固有設定を分離したあとに、これらの数が体感で大きく下がりました。一次情報ベースではありますが、「プロンプト改善では動かなかった指標が構造変更で動いた」という観察自体は再現性があります。

agent legibility という発想

Anthropic は Claude Code のメモリ機構 や sub-agents 機能 を通じて、「AIが読むファイルを役割で分ける」設計を推しています。OpenAI Codex 側もエージェントが可読な（legible な）リポジトリ構造を前提に据え、命名規則・ドキュメント配置の規範を段階的に整えてきました。

両者に共通するのは「プロンプトの工夫で乗り切るのではなく、リポジトリ構造を AI への指示書として設計する」という立場です。これを agent legibility（エージェント可読性）と呼び、本記事では以降この表記で統一します。

恒久ルール vs 揮発的な作業状態の分離原則

4パターンに入る前に、置き場所の判断軸を先に固定します。

恒久か揮発的か、ルールか実行時かで分解するとほぼ迷いません。以降はこの原則を前提に、4パターンを順に見ていきます。

本記事が扱う4パターンの全体像

[AGENTS.md (SSoT)]
       │
       ├── パターン① ルール階層の設計
       │     └─ CLAUDE.md / .cursor/rules / .agents/rules/
       │
       ├── パターン② エージェント定義の配置
       │     └─ .agents/agents/ / .claude/agents/（シンボリックリンク）
       │
       ├── パターン③ スキル・フック・ツールの棲み分け
       │     └─ hooks / memory / MCP / skills
       │
       └── パターン④（応用） 作業コンテキストの外部化
             └─ doc/Working/<task-id>/

パターン① ルール階層の設計

AGENTS.md を SSoT に据える

リポジトリ直下に AGENTS.md を置き、冒頭の3行でルール優先順位を宣言します。Growth Lab の例は以下です。

# Agent Guide
> **優先順位**: SSoT > 安全 > 品質。迷ったらこの順に従う。
> **言語**: すべての出力・ログ・PR文面・コメントは日本語で行う。
> **SSoT**: このファイルが全エージェント・全自動化ツールの共通規範。ツール固有の設定は各ラッパー（`CLAUDE.md` / `GEMINI.md` 等）に書く。

この宣言があるだけで、Claude Code / Codex / Cursor のどれが動いても「最初に AGENTS.md を読む」状態が作れます。

CLAUDE.md / .cursor/rules との書き分け

CLAUDE.md は Claude Code 固有の差分だけを書く場所に絞ります。肥大化を避けるため、書くのは "Claude Code を動かす上でここでしか指定できないもの" に限定するのがコツです（詳細は CLAUDE.md最適化の本質 参照）。

.agents/rules/ への分解

恒久ルールは細目別にファイル分割します。Growth Lab の .agents/rules/ には 21 本のルールファイルがあり、10-coding-guidelines.md / 30-prompt-and-output-contracts.md / 60-branch-and-pr.md のように番号プレフィックスで読み順を固定しています。AGENTS.md はこれらの索引として機能させます。

Codex ではどうなるか

Codex は AGENTS.md を一次規範として読む思想で揃っています。Claude 側の CLAUDE.md に書いていた内容を AGENTS.md に引き上げると、両陣営で同じ規範が効く状態になります。

Mini ケース：CLAUDE.md に全部書いた失敗例

ある時期、ルール・運用・コード規約をすべて CLAUDE.md に詰めていました。結果、Claude Code が序盤の「使用禁止コマンド一覧」だけ参照して後半を無視するケースが多発。AGENTS.md に優先順位と索引を切り出したところ、参照品質が目に見えて安定しました。

パターン② エージェント定義の配置

.agents/agents/ に集約してシンボリックリンクで配る

Claude Code の sub-agents は .claude/agents/ から読まれますが、定義本体は .agents/agents/ に置き、.claude/agents/ はシンボリックリンクで実体を共有する構成が保守しやすいです。

.agents/agents/          ← 実体（23本）
├── article-conductor.md
├── article-writer.md
└── ...
.claude/agents/          ← シンボリックリンク

Codex や Cursor を追加したときも、リンクを張り直すだけで同じ定義を使い回せます。

命名規則を1つに揃える

エージェント名は「責務ベース」で命名します。Growth Lab では article-conductor（司令塔）/ article-writer（実装）/ article-reviewer（レビュー）のように 動詞的な役割名で統一。helper-1 のような汎用名は使いません。

Mini ケース：粒度バラバラで親がボトルネック化

初期は「タスク1つに1エージェント」を原則に 40 以上のエージェントを作りましたが、親エージェントがすべての調停を抱えて遅くなりました。責務の大きさで束ね、役割別に統合して 23 本に収束。親の判断負荷が下がり、並列度も上がりました（詳細は Claude Code subagents の実運用パターン）。

パターン③ スキル・フック・ツールの棲み分け

4要素の役割マップ

Claude Code まわりで混同されやすい 4 要素を整理します。

恒久ルールは AGENTS.md、実行時の挙動は hooks、セッション状態は memory、外部接続は MCP、という分離が基本形です。skills は「手順の塊」なので、上記いずれにも属さない再利用可能なワークフローを束ねる場所として使います（Growth Lab では 85 本の skills を運用）。

使い分けフローチャート

その情報は...
├─ プロジェクト全体の恒久規範 ?        → AGENTS.md
├─ ライフサイクルでの強制制御 ?        → hooks
├─ セッション横断で保持したい ?        → memory
├─ 外部サービス・ツールへの接続 ?      → MCP
└─ 再利用可能な手順セット ?            → skills

Codex 側の対応物

Codex では hooks / memory に相当する機構は別のインターフェイスで提供されますが、役割別に場所を分ける原則は同じです。ツールを変えても配置の考え方は移植できます。

Mini ケース：hooks に副作用を詰めてデバッグ困難化

pre-commit 相当のフックに「チェック + 自動修正 + ログ送信」を全部入れたところ、失敗時にどこで落ちたかが追えなくなりました。hooks は決定論的チェックだけに絞り、修正処理は skills、通知は MCP 経由に分離したら、原因切り分けが 10 分以内で済むようになりました。

パターン④（応用）作業コンテキストの外部化

⚠️ このパターンは Claude Code / Codex の公式機能ではなく、Growth Lab の独自運用です。公式機能と誤認しないようご注意ください。

なぜ CLAUDE.md に書くべきでないか

進行中のタスクの brief や plan、途中メモを CLAUDE.md に追記していくと、恒久ルールと揮発的な作業状態が混ざって、すぐに参照品質が落ちます。パターン①で SSoT を宣言しても、中身がノイズだらけでは意味がありません。

doc/Working/<task-id>/ に外部化する

Growth Lab では、1つの記事やタスクごとに doc/Working/<task-id>/ ディレクトリを掘り、brief.md / plan.md / todo.md / status.md / review-*.md を束ねて格納します。タスクが終わったら、必要な部分だけ恒久ドキュメント（spec/ や content/posts/<slug>/）に昇格させ、作業ディレクトリは残骸として残すか削除します。

Mini ケース：CLAUDE.md に作業メモを追記し続けた失敗例

初期は「今週やってること」を CLAUDE.md に書き足していましたが、3週間分溜まったあたりで Claude が古い作業メモを「現在のルール」として読むようになり、挙動が壊れました。doc/Working/ に切り出し、CLAUDE.md から参照リンクだけ残す形に変えたところ、混線が消えました（作業ディレクトリ運用の詳細は Spec ファイル管理の設計 を参照）。

Claude Code と Codex の思想差

ざっくり整理すると以下です。

両方を併用する場合は、AGENTS.md を最上位 SSoT に据え、ツール固有差分のみを CLAUDE.md に切り出すのが一番事故が少ない構成です。

詳細な階層化手法は Claude Code のコンテキスト階層化 で掘り下げています。

明日から始めるチェックリスト

リポジトリ直下

• AGENTS.md が存在する
• 冒頭3行に優先順位宣言（SSoT / 安全 / 品質）がある
• CLAUDE.md はツール固有差分のみに絞られている

.agents/ ディレクトリ

• rules/ に恒久ルールが番号プレフィックスで並んでいる
• agents/ に責務ベースの命名でエージェント定義が置かれている
• ツール固有ディレクトリ（.claude/agents/ 等）は実体ではなくシンボリックリンク

運用

• 揮発的な作業状態は doc/Working/<task-id>/ に外部化している
• hooks は決定論的チェックのみ（副作用を詰めていない）
• エージェント・ルール変更時に索引（AGENTS.md や README）を更新するルールが明文化されている
• 同じ規範を2箇所に書いていない（重複は SSoT 違反）

FAQ

CLAUDE.md と AGENTS.md はどう書き分ける？

AGENTS.md が全ツール共通の SSoT、CLAUDE.md が Claude Code 固有差分のみ。Codex や Cursor でも同じ規範を使いたい場合は AGENTS.md に書きます。

sub-agents と hooks はどう使い分ける？

sub-agents は役割・責務の分離、hooks はライフサイクルでの決定論的強制。判断が必要な処理は sub-agents、失敗させたいチェックは hooks です。

AIが参照するドキュメントはどこに置けばいい？

恒久規範は AGENTS.md / .agents/rules/、エージェント定義は .agents/agents/、作業中のメモは doc/Working/<task-id>/。この3層を混ぜないのが最優先です。

agent legibility とは何ですか？

プロンプトではなくリポジトリ構造側で AI エージェントが読みやすい状態を作るという設計原則です。Anthropic / OpenAI 両者が 2025〜2026 年にかけて推してきた考え方で、命名規則・ドキュメント配置・ツール分離が中核になります。

まとめ

AI エージェントの出力を安定させる鍵は、プロンプトを磨くことではなく、リポジトリ構造で可読性を担保することです。ルール階層 / エージェント定義 / スキル・フック・ツールの棲み分け / 作業コンテキスト外部化の4パターンで整理すると、どこに何を置くかの判断が一意になります。

今日やる1アクションとしては、AGENTS.md の冒頭に優先順位宣言を1行追加するところから始めてみてください。残りのパターンは、実運用で詰まった箇所から順に手を入れれば十分です。

本記事の仕様・バージョン前提: 2026年4月時点の Claude Code / Codex の公式ドキュメントに基づきます。

関連記事

リポジトリ可読性を実装に落とす際は、サブエージェントの責務分離・コンテキスト負債・共通基盤の観点を併せて押さえると判断がぶれません。

• Claude Code subagents の実運用パターン — 粒度設計と責務分離で精度を上げる
• コンテキスト負債とは何か — 「当てる力」を上げる Issue 設計
• AIエージェント開発を支える共通基盤 — MCP と Context 管理の土台