その"不調"、実はClaude Codeのせいじゃない
プロジェクトが大きくなるほど、AIに渡す文脈は濁っていきます。README、仕様、議事録、チケット、過去のドラフト……すべてを読み込ませると、Claude Codeは「何を優先すべきか」を判断しにくくなり、遅い・見当違い・やり直しが増えます。 よくあるのは次のパターンです。
- 仕様書より過去メモを優先し、古い前提で作業を進める
- 一つのPRに対して、関係ないドキュメントの修正提案を大量に出す
- 「全部見たうえで要約して」が重すぎて、重要な条件が消える
原因はシンプル。文脈が"広すぎる"ことです。
解決策：フォルダごとに"役割特化AGENTS.md"を置く
やることはひとつ。タスク単位のフォルダに、そこ専用のAGENTS.mdを置くだけです。 例：
build/AGENTS.md… ビルド設定・最適化・依存ライブラリの見直し専用report/AGENTS.md… レポート原稿・図版指示・目次構成専用docs/AGENTS.md… ドキュメント構成・用語統一・更新方針専用
Claude Codeに「このフォルダのAGENTS.mdから読んでね」と入口を固定すると、AIの"注意"が一点に合うようになります。結果、速度・精度・再現性が上がり、やり直しが減ります。
AGENTS.mdの中身はミニマムに
長文化は禁物。次の5点だけで十分です。
- 役割宣言：このフォルダで"だけ"解く問題は何か
- 対象/非対象：やらないことを明記（例「設計方針の再発明はしない」）
- 入力：AIが読むべきファイルの範囲
- 出力：完成物の粒度・形式（例「見出しはh2から」「図はキャプション必須」）
- 終了条件：完了の定義（例「差分の要約＋根拠の列挙まで」）
ポイントは境界線。「ここから外には出ない」をはっきり書くと、AIの探索空間が閉じ、ブレが消えます。
導入は3ステップで足りる
- 棚卸し：いま走っているタスクの"まとまり"をフォルダに整理
- 骨子を書く：上の5点だけ書いたAGENTS.mdを各フォルダに配置
- 入口を固定：Claude Codeの最初のメッセージで、そのフォルダのAGENTS.mdを必ず参照
これで、「どこから読み始めるか問題」が解消します。
失敗しがちな落とし穴と回避策
- 指示の欲張り：1枚に全部詰め込むと、結局"広い文脈"に逆戻り。フォルダを分ける勇気。
- 禁止事項の欠落：「やらないこと」を書かないと暴走しやすい。明記する。
- 上位ルールとの矛盾：プロジェクト共通の作法（見出しレベル、命名規則など）と整合させる。
- 放置：AGENTS.mdは"生もの"。スプリント始めと終わりに5分で棚卸しする。
小さな島宇宙で、AIは強くなる
人間のチームでも"役割"が揃うと強いのと同じ。AIにも「スコープの小さな島」を与えると、判断が速く・一貫します。特に、リライト／体裁調整／証跡の列挙のような"定型の工芸"に、サブエージェントは抜群に効きます。
具体シーン別のサンプルプロンプト
（そのまま投げてOK。必要に応じてファイル名や用語を置換してください）
ビルド最適化（build/）
- 「
build/AGENTS.mdの方針に従い、現行設定のリスクを3項目だけ挙げ、採用・保留・却下の判定と根拠を短文で示して。」 - 「変更提案は"1コミット＝1論点"。差分の要約文も同時に書いて。」
レポート作成（report/）
- 「
report/AGENTS.mdに沿って本文をh2から構成。見出し→要点→根拠→次アクションの順で、各節300〜500字に整えて。」 - 「図は"本文→図→キャプション→出典"の順で配置。図の説明は二文以内。」
ドキュメント整備（docs/）
- 「
docs/AGENTS.mdの用語集を基準に、用語ブレの洗い出しと一括置換提案をリスト化して。」 - 「更新履歴の書式に合わせて、今回の変更点を"目的・範囲・影響"の3見出しで要約して。」
コミュニケーション整理（communication/）
- 「
communication/AGENTS.mdのテンプレに沿って、ステークホルダー別の要約（経営、開発、サポート）をそれぞれ150字以内で。」
個人でもSaaSに届く理由
この"サブエージェント化"は、コード量や特殊なツールを増やさずに、作業の再現性を底上げします。UIを磨く、文章を整える、差分を説明する――こうした"人が時間を溶かしがちな部分"を役割ごとに型化できるからです。 実際、ローカルファーストで軽量に動く管理会計系のツール（たとえばMonerionのような方向性）を個人で作るときも、この分割は威力を発揮します。AIにすべてを任せるのではなく、小さなルールを並べるだけで"迷子にならない開発体験"に近づけます。
今日からできるチェックリスト
- タスクの"まとまり"ごとにフォルダを切る
- 各フォルダにAGENTS.mdを置き、役割・非対象・入出力・終了条件だけを書く
- 最初のプロンプトで入口フォルダを宣言する
- スプリントの始まり/終わりに5分だけAGENTS.mdを見直す
- PRでは「どのAGENTS.mdで検討したか」をコメントに残す
まとめ
「AIが賢くなる魔法」より、迷子にさせない設計が効きます。 たった1ファイルをフォルダごとに置くだけで、Claude Codeの注意は一点に集まり、判断は速く、作業は揺れません。結果として、個人でも"作れる・届けられる"SaaSの距離が縮む。 まずは一つのフォルダから、AGENTS.mdの小さな島を作ってみてください。そこで得た静かな成功体験が、プロジェクト全体に伝播していきます。