なぜAIコーディングエージェントには人間とは異なる取扱説明書が必要なのか

誰かにコードベースを渡し、「ドキュメントを更新して、でも何も壊さないで」と言うことを想像してみてください。人間の開発者ならREADMEを読み、あちこち調べ、ルールを理解します。AIコーディングエージェントは？推測するしかありません。

今日は2026年7月6日。AIエージェントのコード記述能力は向上していますが、依然として繰り返し発生する問題に直面しています。タスクとREADMEを与えられた後、本来なら尋ねる必要のない質問の答えを即座に考え出さなければなりません。このプロジェクトはどのパッケージマネージャーを使っているのか？それらの自動生成されたファイルは触っても安全か？何をもって「完了」とするのか？そこでAGENTS.mdの出番です。これは驚くほど実用的です。

READMEとエージェント向け指示のギャップ

READMEは「このプロジェクトは何ですか？」という質問に答えます。人間向けに書かれており、コードが何をするのか、ローカルでどうやって実行するのか、残りのドキュメントはどこにあるのかを知ることができます。

しかし、コーディングエージェントには別のものが必要です。「このリポジトリに触れる前に何を知っておくべきか？」という質問に答える必要があります。そこにAGENTS.mdが介入します。

フォーマットに関するガイダンスによると、AGENTS.mdはコーディングエージェント向けの指示を置くための予測可能な場所です。セットアップコマンド、テストコマンド、コードスタイル、セキュリティ上の考慮事項、大規模なモノレポジトリのためのネストされた指示などです。READMEとAGENTS.mdファイルは全く異なる読者を対象としているため、この分割は有用です。READMEは構築し学ぶ人々のためのものです。AGENTS.mdは作業を行うツールのためのものです。

実際に何がうまくいかないのか

具体例を挙げましょう。プロジェクトの同じディレクトリ内にソースファイルと自動生成されたファイルの両方があるとします。明確な境界が文書化されていなければ、AIエージェントは編集すべきでないものを喜んで編集してしまうかもしれません。あるいはテストを実行するかもしれませんが、適切なものではないかもしれません。リンティングが重要だと何も伝えられていないため、リンティングステップをスキップしてしまうかもしれません。

典型的な回避策は？より長く、より詳細なプロンプトを書くことです。

「ドキュメントを更新して。ただし、生成されたファイルには触れず、pnpmを使用し、lintとtestコマンドを実行し、PRを小さく保ち、検証できなかったことを教えて。」

AGENTS.mdがあれば、そのプロンプトは次のように縮小されます。

「新しい設定フラグのためにクイックスタートのドキュメントを更新して。」

エージェントは残りのことをすでにファイルから知っています。

Goose（および他のエージェント）はそれをどのように使うのか

これは理論上の話ではありません。デスクトップアプリ、CLI、API、MCP拡張機能、スキルを備えたオープンソースのAIエージェントであるGooseというツールは、これが実際に重要である理由を示しています。AGENTS.mdがないと、すべてのタスクでエージェントは基本的なことについてあなたに尋ねる（または推測する）必要があります。リポジトリにAGENTS.mdがあれば、Gooseは基本ルールを一度読み、すべてのタスクに適用することができます。

このパターンは1つのツールにとどまりません。ファイルを読めるほど賢いコーディングエージェントなら、明確な指示が書かれていればそれに従うことができます。

クリーンな分割：AGENTS.mdとスキル

1つの重要な境界：AGENTS.mdは基本ルール、つまりリポジトリのほぼすべてのタスクに適用されるものに焦点を当てるべきです。しかし、どのチームにも繰り返し可能なワークフローがあります。それらによってAGENTS.mdをガラクタ入れのように肥大化させるべきではありません。

よりクリーンなアプローチ：AGENTS.mdは短く保ち、特定の種類の作業に対する再利用可能な指示セットである「スキル」を指し示すようにします。バックエンドサービスの場合、AGENTS.mdはデータベースのマイグレーション、APIの変更、リリースを別々のスキルにルーティングするかもしれません。ファイルは読みやすいままで、詳細なタスクルーチンは適切な場所に配置されます。

区別は簡単です。ルールがほぼすべてのタスクに適用されるべきなら、AGENTS.mdに入れます。1つの種類の作業のためのワークフローなら、スキルにします。

実際にAGENTS.mdに何を入れるか

ここに実用的な出発点を示します。

プロジェクトマップ

何がどこにあるかをエージェントに伝えます。

• src/ アプリケーションコードが含まれています。
• tests/ テストが含まれています。
• docs/ ユーザー向けドキュメントが含まれています。
• generated/ ツールによって生成されます。手動で編集しないでください。

コマンド

物事を行うための推奨される方法をリストアップします。

• インストール： pnpm install
• テスト： pnpm test
• Lint： pnpm lint
• 型チェック： pnpm typecheck

作業ルール

境界を設定します。

• 変更はユーザーの要求の範囲内に留めてください。
• 抽象化を追加する前に、既存のヘルパーを優先してください。
• 明示的な承認なしに、データのデプロイ、公開、マイグレーション、削除を行わないでください。
• コミットするファイルにシークレット、プライベートデータ、ローカル専用パスを含めないでください。

完了

「完了」がどのような状態かを定義します。

• 関連するチェックを実行するか、なぜ実行されなかったのかを説明してください。
• 変更された動作を要約してください。
• 残念なリスクやフォローアップをリストアップしてください。

スキル

タスク固有のワークフローにルーティングします。

• データベースマイグレーションには、migration reviewスキルを使用してください。
• APIの変更には、contract-checkingスキルを使用してください。
• リリースの前に、release-notesスキルを使用してください。

役立つにはこれで十分です。また、誰かが実際に保守するかもしれないほど短いです。アーキテクチャに関するエッセイ、熱望的な価値観、リポジトリ内のすべてのコマンド、そしてプロンプトの記録に残したくないプライベートなコンテキストは避けてください。指示がエージェントの行動を変えないのであれば、削ってください。

機能しているかどうかを知る方法

すでにエージェントと連携しているリスクの低いリポジトリでこれを試してみてください。

ステップ1：AGENTS.mdなしでタスクを実行する

エージェントに簡単な仕事を与えてみましょう。例えば、「新しい設定フラグの例を追加して」といった具合です。プロンプトで何を説明しなければならないか観察してください。

ステップ2：AGENTS.mdファイルを作成する

上記のテンプレートを使用します。5つのセクションに収めてください。短く、実行可能な内容にします。

ステップ3：同じタスクを再度実行する

プロンプトには中核となるタスクのみを含めて、エージェントに同じ仕事を与えます。

ステップ4：次の3つのことを確認する

エージェントは適切なチェックを実行しましたか？生成されたファイルを回避しましたか？プロンプトは短くなりましたか？

3つすべてが「はい」なら、リポジトリの曖昧さが減ったことになります。そうでない場合は、ファイルをおそらくより具体的にするか、よりシンプルにする必要があります。

結論

AGENTS.mdは魔法の安全レイヤーやトレンディな新しいベストプラクティスではありません。セットアップ、チェック、境界、完了の意味など、あなたがすでに繰り返していた指示を置くための、シンプルで退屈な場所です。実用的な基準は次のとおりです。エージェントがより少ないプロンプトで小さなタスクを実行でき、なおかつ実行したチェックを示すことができるか？もし「はい」なら、ファイルはその役割を果たしています。

メリット

• プロンプトが短くなり、実際のタスクにより集中できるようになる。
• 毎回リマインドされなくても、エージェントが一貫したチェックを実行する。
• ファイルと境界がより明確に保たれる。生成されたコードかソースコードかについての推測が減る。
• 1つのツールに縛られることなく、どのコーディングエージェントでも機能する。
• 短く焦点を絞って保てば、メンテナンスが容易である。
• エージェントが誤って何かを壊す可能性を減らす。

デメリット

• プロジェクトの進化に合わせてファイルを最新の状態に保つための規律が必要。
• すでに詳細なプロンプトを使用しているチームは、すぐにメリットを感じられないかもしれない。
• エージェントの信頼性に関する問題をすべて解決するわけではなく、不必要な推測を減らすだけ。
• 非常に小規模なプロジェクトや使い捨てのコードには過剰である。
• 実際にファイルフォーマットを読み取り、尊重するエージェントツールが必要。

注意

この記事は教育目的であり、コーディングエージェントがプロジェクトドキュメントとどのように連携するかを説明することを意図しています。プレースホルダー値（パスやコマンドなど）を使用してAGENTS.mdファイルを作成する場合は、実際のプロジェクトのセットアップに置き換えてください。エージェントが行動を起こす前に、プロジェクトの実際の構造とツールに対してすべての指示を検証してください。ここでの例は説明のためのものであり、リポジトリの具体的なルールは異なる場合があります。

よくある質問

• AGENTS.mdと通常のREADMEファイルの違いは何ですか？
• AGENTS.mdはどのコーディングエージェントでも使えますか、それとも特定のツール専用ですか？
• AGENTS.mdファイルがエージェントが従えるほど明確かどうかはどうすればわかりますか？
• AGENTS.mdにセキュリティポリシーやアクセス制御を含めるべきですか？
• AGENTS.mdファイルが長くなりすぎた場合はどうすればいいですか？
• AGENTS.mdはコードコメントやインラインドキュメントの代わりになりますか？
• プロジェクトの進化に合わせて、どのくらいの頻度でAGENTS.mdを更新すべきですか？
• エージェントがAGENTS.mdの中で理解できない指示に遭遇した場合はどうなりますか？

タグ

#AIAgents #CodingAutomation #Documentation #SoftwareDevelopment #DeveloperTools #CodingEfficiency #InstructionDesign