Nullstead

AI

AGENTS.mdは新しいREADMEではなく、AIコーディングの“管制塔”になりつつある

2026年夏のCodex・Copilot・Claude Code周辺の最新動向を踏まえ、AGENTS.mdやCLAUDE.md、PLANS.mdを使ってAIコーディング運用を安定化する実践ポイントを整理します。

約11分

2026年のAIコーディング周りを追っていると、モデル性能の話よりも先に「そのエージェント、どの指示ファイルを読むんですか？」という地味だけれど大事な論点にぶつかります。派手さはありません。プロダクト紹介動画でここがバズることもたぶんありません。ですが、実務ではかなり効きます。冷蔵庫の製氷機くらい静かに効きます。

最近は、OpenAI Codex系では AGENTS.md、GitHub Copilotでは AGENTS.md や copilot-instructions.md、Claude Codeでは CLAUDE.md のように、「リポジトリに置く指示ファイル」がエージェント運用の中心へ寄ってきました。しかも2026年6月から7月にかけて、その流れがさらにはっきりしています。GitHub Copilot code review はリポジトリルートの AGENTS.md を読むようになり、CopilotのIDE体験は並列セッションやコスト可視化を強め、OpenAI Codexは AGENTS.md と PLANS.md を組み合わせた長時間タスク運用を前面に押し出しています。

つまり今の論点は「どのモデルが最強か」だけではありません。むしろ「どうやって複数のエージェントに、同じ現場ルールを安定して食べさせるか」が本題です。本記事では、その中心にある AGENTS.md を“新しいREADME”としてではなく、“AIコーディングの管制塔”として扱う考え方を整理します。

なぜ今、指示ファイルが重要なのか

AIコーディングエージェントは賢くなりましたが、賢いだけでは足りません。賢い新卒が会社のルールを知らずに本番DBへ突撃すると、賢さが事故の燃料になります。エージェントもだいたい同じです。便利ですが、何を優先し、どこまで自動で進め、何を確認すべきかは、リポジトリごとに違います。

OpenAIのCodexドキュメントでは、AGENTS.md を起動時に読み込み、グローバル設定とプロジェクト設定を階層的にマージする仕組みが説明されています。さらにCookbookでは、複雑な仕事には PLANS.md を併用し、長時間タスクを“生きた設計書”で回す方法が紹介されています。これは単なるメモではなく、「このリポジトリでは何が正しい進め方か」を毎回ゼロから説明しなくてよくする仕組みです。

GitHub側も同じ方向です。2026年6月の changelog で、Copilot code review がリポジトリルートの AGENTS.md を読めるようになりました。つまり、実装エージェントだけでなくレビュー側にも同じルールを渡せるようになったわけです。人間の開発でも、実装担当とレビュー担当のルールがズレていると悲劇が起きます。AIでも当然ズレます。しかもAIは遠慮なくズレます。

Claude Codeはファイル名こそ CLAUDE.md ですが、考え方はかなり近いです。プロジェクト共通の指示を毎セッション読み込み、必要に応じて階層やルール分割で整理する設計になっています。ここから見えてくるのは、ベンダーごとの細かなUI差分よりも、「永続的なリポジトリ指示を中心に据える」という設計思想の収束です。

2026年夏の変化は、モデル競争より“運用競争”っぽい

2026年7月のGitHub Copilot for VS Code更新は象徴的でした。並列セッション、サブエージェントの利用量表示、モデル選択の改善、ブラウザ操作の強化など、要するに「エージェントを本気で働かせると管理コストが発生するので、そこをUIで支えます」という方向です。華やかに言い換えるとエージェント時代の統合開発環境、率直に言うと“AI現場監督ツール”です。

JetBrains向けCopilot更新でも、実行中セッションへのメッセージ追加、Steer with Message、エージェントのデバッグログ要約、組織配布エージェントなどが入りました。ここで重要なのは、もはやAIコーディングが単発の補完ではなく、途中介入・方針修正・複数担当の束ねを前提にしていることです。

この文脈で AGENTS.md が効く理由は単純です。セッションが増え、サブエージェントが増え、レビューも別レイヤーで走ると、口頭指示だけでは統制不能になるからです。Slackで「今回はテスト忘れないで」と書いても、次のセッションはだいたい忘れます。人も忘れますし、AIも忘れます。ファイルに書いたルールだけが、しぶとく生き残ります。

AGENTS.mdを“プロンプト置き場”にすると失敗します

ここはかなり大事です。AGENTS.md を魔法の呪文集にすると、だいたい壊れます。

例えば次のような書き方です。

- 最高品質でお願いします
- セキュアにしてください
- いい感じに設計してください
- なるべく賢く判断してください

気持ちはわかります。全部その通りです。でも、これでは現場ルールになりません。上司が「うまくやっといて」と言うのと同じで、言われた側は困ります。しかも相手は人間よりさらに文字面に忠実です。

GitHubの instructions 設計ガイドも、短く具体的で検証可能なルールを勧めています。Claude Codeのドキュメントでも、簡潔で構造化された指示ほど従いやすいと明記されています。OpenAI Codexの AGENTS.md ガイドも同様で、テスト手順、依存追加時の確認、使用ツールの優先順位といった“行動に落ちるルール”を書くことが前提です。

自分は AGENTS.md に最低でも次の4種類を書くのがよいと思っています。

  1. 実行前の前提: 使うパッケージマネージャー、作業ディレクトリ、参照すべき設計資料
  2. 変更時の必須行動: lint、test、build、スクリーンショット確認など
  3. 禁止事項: main直push禁止、本番データ変更禁止、秘密情報の出力禁止
  4. エスカレーション条件: 外部送信、課金増、破壊的変更、権限変更は確認必須

これなら、モデルや製品が変わっても意味が通ります。逆に「この比喩表現で褒めてください」みたいな装飾は、後回しで十分です。AIに文才を期待する前に、事故らない導線を作るほうが先です。地味ですが、ここを飛ばすと後で盛大に請求書が光ります。

まずは1枚、次に階層化。それで十分戦えます

OpenAI Codexはルートから現在ディレクトリまで AGENTS.md を積み上げる仕組みを案内していますし、Claude Codeも全体指示と局所ルールの分割を勧めています。つまり大規模リポジトリでは、最初から完璧な一枚岩を目指す必要はありません。

実務では、まずルートに短い AGENTS.md を置き、特殊な領域だけ下位ディレクトリで補強するのが扱いやすいです。たとえば決済、認証、インフラなど“触ると胃が痛くなる場所”だけ局所ルールを足します。全部を最初から詳細化すると、読む側も維持する側も疲れます。AIのために書いたのに、人間が先に倒れるやつです。

最小構成の例はこんな感じです。

# AGENTS.md

## Working Agreements
- 依存追加前に理由を説明する
- JavaScript/TypeScript変更後は `pnpm test` と `pnpm lint` を実行する
- UI変更後は差分説明とスクリーンショット確認を書く
- 本番環境の設定変更、外部送信、課金を伴う操作は確認を取る

## Repository Map
- Webアプリ本体は `apps/web`
- APIは `apps/api`
- 共有UIは `packages/ui`

## Do Not
- `main` へ直接pushしない
- 秘密情報をログへ出さない
- 失敗したテストをスキップでごまかさない

これだけでも、かなり効きます。READMEが「このプロジェクトは何か」を説明する文書だとすれば、AGENTS.md は「このプロジェクトでどう振る舞うべきか」を定義する文書です。似ているようで、役割は別物です。READMEが観光案内なら、AGENTS.md は空港の管制塔です。飛行機はロマンですが、離着陸はルールがないと終わります。

長時間タスクはPLANS.mdを組み合わせると急に安定します

もう一歩進めるなら、OpenAI Cookbookで紹介されている PLANS.md 型の運用が参考になります。要点は単純で、「大きな仕事は、その場の勢いではなく、更新される計画書に従わせる」ということです。

特にAIは、30分前の方針と今の方針が静かにズレることがあります。人間なら会議で揉めますが、AIは無言で進みます。そこが少し怖い。だからこそ、長時間タスクでは以下のようなルールが有効です。

  • 複雑な改修は PLANS.md を作ってから着手する
  • 進捗、決定、未解決点を計画書へ追記する
  • 次の担当エージェントが読んでも再開できる粒度で書く
  • 完了条件を「テストが通る」「画面で確認できる」など観測可能な形にする

サンプルはこんな雰囲気です。

# ExecPlans
- 複雑な機能追加や大規模リファクタでは `.agent/PLANS.md` を使う
- 実装前に対象ファイル、検証手順、完了条件を書く
- 途中で方針変更したら理由を残す

これの良いところは、モデルをまたいでも効くことです。実装担当がCodexでも、レビュー担当がCopilotでも、別の検証担当がClaude系でも、共通の“紙”があれば引き継げます。エージェントは賢いですが、テレパシーはまだ実装されていません。たぶん次の課金プランにも入りません。

2026年後半に向けて、個人開発者がやるべきこと

ここまでの流れを見ると、今後の差分はモデル単体よりも「複数エージェントをどう束ねるか」に寄っていくはずです。すでにCopilotはセッション並列化やコスト可視化を進め、Codexは AGENTS.md とサブエージェント運用を押し出し、Claude Codeはプロジェクト記憶とルール分割を整えています。要するに、AIに仕事を振る時代の課題が、だんだん人間のチーム運営と似てきたわけです。

個人開発でも、いまや“ひとり開発”ではありません。実態としては「自分 + 数体のエージェント + ときどき請求通知」です。だから個人ほど、ルールを明文化したほうが得です。人数が少ないほど阿吽の呼吸で回したくなりますが、相手がAIだと阿吽が通じません。空気を読むより、Markdownを読ませたほうが早いです。

最初の一歩としては、次の順で十分です。

  1. ルートに短い AGENTS.md を置く
  2. テスト・lint・禁止事項・確認必須条件を書く
  3. 事故りやすいディレクトリだけ局所ルールを足す
  4. 長時間タスク用に PLANS.md テンプレートを作る
  5. レビュー系ツールでも同じルールが参照されるか確認する

これだけで、エージェントの“たまに天才、たまに自由すぎる”問題はかなり減ります。

まとめ

AGENTS.md は、もう単なる補助ファイルではありません。2026年夏のアップデート群を見る限り、これはAIコーディング運用の共通インターフェースになりつつあります。READMEが人間の onboarding 文書なら、AGENTS.md はエージェントの operational contract ※運用上の取り決めです。

モデル選びに目が向きがちな時期ですが、実務では「賢いモデル」より「毎回同じ地雷を踏まない仕組み」のほうが効きます。しかも後者は、明日モデルを乗り換えても資産として残ります。そこが強い。

もし今、Copilot、Codex、Claude Codeのような複数系統を並行で試しているなら、先に比較すべきはベンチマークではなく、どの指示ファイルをどう読ませ、どう統制するかです。AIコーディングの本番運用は、プロンプト芸より管制設計。派手ではないですが、たぶんこちらのほうが長生きします。

参考リンク

Tags #AI #コーディングエージェント #AGENTS.md #個人開発 #自動化
← 記事一覧に戻る ページの先頭へ ↑