AIに小さな修正を頼んだだけなのに、関係のないファイルまで書き換えられた。使っていないライブラリを追加された。「テストしました」と言われたものの、何を確かめたのか分からない。
こうした食い違いを減らすために、毎回のチャットとは別に、プロジェクトの作業ルールを書いておく方法があります。それがAGENTS.mdです。
AGENTS.mdは、AIコーディングエージェントに、そのリポジトリでの作業方法を伝えるMarkdownファイルです。特別なプログラミング言語ではなく、見出しと文章で「どこを変更するか」「何を実行するか」「何を確認して完了とするか」を記述します。AGENTS.mdの公式サイトでも、エージェント向けの文脈と指示を置くためのオープンな形式として説明されています。
ただし、ファイルを置くだけで、すべてのAIが同じように読み、必ず従うわけではありません。この記事では、最小構成からTypeScript・Rustの記入例、Codex・Claude Code・GitHub Copilot CLIの扱いの違い、実際の読み込み確認までを順に紹介します。
仕様確認日:2026年11月15日。対応状況はツール・バージョン・利用環境によって変わります。テンプレートは記事用の架空プロジェクトを前提にした記入例です。
AGENTS.mdとは?READMEやチャットとの違い
READMEが「このプロジェクトは何か、どう使うか」を説明する入口なら、AGENTS.mdは「このプロジェクトを変更するとき、どう作業してほしいか」を伝える引き継ぎメモです。READMEをAIが読めないという意味ではなく、情報の役割を分けると整理しやすい、という考え方です。公式サイトの説明
| 置き場所 | 主な役割 | 書く内容の例 |
|---|---|---|
| README.md | 人にもAIにも必要なプロジェクトの案内 | 目的、導入方法、使い方、ライセンス |
| AGENTS.md | 繰り返し使う、エージェント向けの作業ルール | 変更範囲、検証コマンド、確認が必要な操作、完了報告 |
| 今回のチャット・Issue | 今回だけの作業依頼 | 直したい不具合、期待する動作、今回は扱わないこと |
| テスト・CIの設定 | 機械的に確認する仕組み | 型チェック、テスト、ビルド、マージ前の必須チェック |
例えば「APIのエラー形式を変えない」は継続的なルールなのでAGENTS.mdへ、「今回の検索画面で、空欄なら検索しない」は今回の依頼へ書く、と分けます。詳しい仕様が別の文書にあるなら、すべて複製するより、参照するファイルと読む場面を示す方が更新しやすくなります。
AGENTS.md
作業範囲・確認方法・報告
チャット・Issue
目的・対象・完了条件
テスト・差分・レビュー
結果と残った問題
まずは短いAGENTS.mdを1つ作る
最初は、Gitで管理しているプロジェクトの最上位フォルダーに、大文字のAGENTS.mdという名前で作成します。Windowsでは拡張子が隠れていると、意図せずAGENTS.md.txtになることがあるため、ファイル名を確認してください。
いきなり大きなテンプレートを埋める必要はありません。例えば、次のような短い内容から始められます。これは本記事の出発点の例であり、見出しや項目が仕様で必須という意味ではありません。
この例はまだ一般的です。次に、自分のプロジェクトで繰り返し説明していることを足します。「このフォルダーは自動生成」「このコマンドは外部サービスへの接続が必要」といった、そのリポジトリ固有の事情が候補です。
一方、コードや設定を見ればすぐ分かることを大量に転記すると、更新する場所が増えます。OpenAIのCodexのベストプラクティスでも、曖昧なルールを長く並べるより、短く正確な内容から始める方針が示されています。
書くべき内容は「判断できる情報」にする
「きれいに書いて」「しっかりテストして」だけでは、期待する行動が読み取れません。次の6項目を、実際のファイル名やコマンドに結び付けて書くと、作業後にも確認しやすくなります。
| 項目 | 曖昧な指示 | 具体的な書き方の例 |
|---|---|---|
| プロジェクトの目的 | 便利なアプリにする | ブラウザで学習時間を記録する。今回サーバー機能は追加しない |
| 実装の場所 | 適切な場所に実装 | 集計処理はsrc/stats.ts、対応するテストはtests/stats.test.ts |
| 作業環境 | いつもの環境で動かす | Node.jsの指定は.nvmrcを参照。パッケージ管理はnpm |
| 検証方法 | テストしてから終わる | ルートでnpm run typecheck、npm test、npm run buildを実行 |
| 変更の制約 | 勝手に大きく変えない | 依存追加、公開API変更、データ形式変更は実装前に提案 |
| 完了報告 | 問題がないか教える | 実行コマンド、終了結果、未実行項目、既存の失敗を分ける |
ここで大切なのは、指示を増やすことより、確認可能な内容にすることです。
例えば、APIの互換性を守りたいなら「既存機能を壊さない」だけでなく、「既存のレスポンス項目名とHTTPステータスを維持する。変更が必要なら互換性への影響を先に示す」と書きます。さらに、その仕様をテストでも確認します。
TypeScriptのWebアプリ向けAGENTS.mdテンプレート
ここでは、Vite・TypeScript・Vitestを導入済みの小さな学習記録アプリを例にします。実在するサイトの構成を調査したものではありません。自分のプロジェクトへ使う場合は、フォルダー名、実行環境、検証コマンドを置き換えてください。
先にpackage.jsonのscriptsを確かめる
npm run typecheckは、すべてのTypeScriptプロジェクトに最初から存在するコマンドではありません。package.jsonのscriptsで定義されている必要があります。引数なしのnpm runで、利用可能なスクリプトを一覧できます。npmの公式リファレンス
次は、この例で想定するscriptsの部分です。既存のpackage.json全体を、この断片で上書きしないでください。TypeScript・Vite・Vitestの導入と設定も別途必要です。
テストには、変更を監視し続けるモードではなく、一度実行して終了するvitest runを指定しています。エージェントが作業の完了を判断するときも、待機中なのか、実行が終わったのかを区別しやすくなります。Vitestの実行方法
AGENTS.mdの記入例
このテンプレートは、「TypeScriptを使う」という情報よりも、集計処理と画面を分けること、検証結果を区別して報告することに重点を置いています。
npm ciを初期セットアップに書いていても、毎回必ず実行させる必要はありません。また、信頼できないリポジトリでインストールを無条件に許可する運用にも使わないでください。依存関係やスクリプトの確認は別の作業です。
Rustの小さなCLI向けAGENTS.mdテンプレート
Rustでは、cargo checkとcargo testを混同しないことが重要です。前者はコードを検査するコマンド、後者はテストをコンパイル・実行するコマンドです。cargo checkが成功しても、テストを実行したことにはなりません。Cargoのcheck/Cargoのtest
ここでは、Cargo.lockを管理している単一パッケージのCLIを想定します。ワークスペース、独自features、外部サービスが必要なテストを使う場合は、それぞれの設定に合わせて変更します。
rust-toolchain.tomlがないプロジェクトには、そのままこの記述を持ち込まないでください。READMEなど、実際にバージョンを管理している場所へ合わせます。
また、Clippyの-D warningsは警告をエラーとして扱う指定です。既存の警告が大量にあるプロジェクトへ、説明なく導入すると、今回の修正と無関係な対応まで必要になります。既存のCIと同じ基準にそろえるのが出発点です。Clippyの公式説明
Codex・Claude Code・GitHub Copilotで扱いは違う
AGENTS.mdは共通の形式として使えますが、読み込む名前、探索する場所、複数の指示の扱いはツール側の仕様です。特に、同じサービスでもCLI、IDE、クラウドの機能を一括りにしないようにします。
| 対象 | 公式資料で確認できる扱い | 最初に行うこと |
|---|---|---|
| Codex | 起動時にAGENTS.mdなどから指示を組み立てる。グローバル設定や作業ディレクトリが関係する | プロジェクト内の適切な場所から起動し、読み込まれた指示の確認を行う |
| Claude Code | 通常の指示ファイルはCLAUDE.md。AGENTS.mdを共有する場合はインポートを使える | CLAUDE.mdに@AGENTS.mdを記載し、新しいセッションで確認する |
| GitHub Copilot CLI | AGENTS.mdに対応。複数の指示ファイルを併用する仕組みがある | /instructionsで検出されたファイルと有効・無効を確認する |
出典:CodexのAGENTS.md、Claude Codeのメモリ、GitHub Copilot CLIのカスタム指示。この表はCopilotのすべての画面・機能で同じ動作を保証するものではありません。
Claude Codeと共有する場合
プロジェクト直下のCLAUDE.mdに、次の1行を入れる方法が公式に案内されています。
ここでの@はClaude Codeが対応しているインポート記法です。Markdown一般の機能でも、すべてのエージェントに共通する記法でもありません。既存のCLAUDE.mdがある場合は上書きせず、重複や矛盾を確認して追加します。Claude Codeの公式説明
共通ルールはAGENTS.mdへ、Claude Code固有の補足はCLAUDE.mdへ置くと、同じ文章を2か所で修正し続けずに済みます。ただし、読み込んだことと、すべての内容に従ったことは別なので、実際の変更と検証ログも確認します。
大きなプロジェクトでは、指示をフォルダーごとに分ける
フロントエンドとCLIを同じリポジトリで管理する場合、すべての指示をルートへ詰め込むと、どのコマンドがどこに対応するのか分かりにくくなります。次は役割を分ける配置例です。
子フォルダー側には、例えば「作業ディレクトリはapps/web。検証はその場所で行う」と、どこで実行するかも書きます。ルートでしか動かないコマンドと、子フォルダーで実行するコマンドを混在させないことが重要です。
ただし、「編集するファイルに一番近い指示だけを読めばよい」と一律に決めつけないでください。Codexの公式資料では、起動時の探索はプロジェクトのルートから現在の作業ディレクトリまでの経路をたどり、上位から下位へ指示を組み合わせると説明されています。ルートで起動しただけで、全子フォルダーの指示が最初から一括で入るとは限りません。Codexの探索方法
また、GitHub Copilot CLIの公式資料は、適用対象の複数ファイルを組み合わせる一方、ファイル間の一般的な優先順序を定めていないと説明しています。矛盾を優先順位で解決させるのではなく、共通ルールと個別ルールを矛盾させないことを基本にします。Copilot CLIの指示の扱い
実践:ルールを読ませてから、小さな修正を頼む
1.最初は編集せず、指示を確認する
新しい指示ファイルを置いたら、すぐに大きな変更を依頼せず、例えば次のように確認します。
これは確認を促すための依頼例で、特別な設定コマンドではありません。回答だけを証拠にせず、ツールが表示する読み込み情報や参照ファイルも照合します。指示を変更した後の再読み込み方法も、利用中のツールの仕様を確認してください。
2.今回の完了条件はチャットで具体化する
AGENTS.mdに毎回の修正内容を書き足すのではなく、今回の課題はチャットやIssueへ置きます。先ほどのTypeScriptアプリなら、次のような依頼が考えられます。
「何を直すか」だけでなく、「今回は何を変えないか」があると、結果をレビューするときの基準にもなります。なお、範囲を狭くしすぎると適切な修正を妨げる場合もあるので、必要な変更を提案できる余地は残します。
3.「終わりました」ではなく、検証結果を見る
以下は報告形式の記入例であり、この記事で実測したログではありません。
この状況なら、変更案ができていても、検証まで完了したとは言えません。失敗が作業前からあったのか、変更によって生じたのかも区別し、必要な確認を人が引き継げる形にします。
対象と手順を共有
実装と再現テスト
コマンド・差分・動作
繰り返す問題だけ反映
AGENTS.mdが効かない・守られないときの確認点
まず、ファイルが読み込まれていない問題と、読み込まれた指示が曖昧・不適切な問題を分けます。
| 症状 | 確認すること | 見直し方 |
|---|---|---|
| 存在するのに参照されない | ファイル名、保存場所、起動場所、ツールの対応状況 | 正しい場所へ置き、ツールの読み込み情報を確認する |
| 更新前のルールで作業する | セッション開始時に読む仕様か | 再読み込みや新しいセッションで確かめる |
| npm testが失敗する | scripts、依存関係、実行ディレクトリ | 実際の設定とコマンドを一致させる |
| Web変更でRustの検証まで始める | 共通指示とフォルダー固有の指示の混在 | 適用範囲と作業ディレクトリを明記する |
| 関係のない修正が増える | 目的、変更範囲、完了条件の曖昧さ | 今回の依頼と恒久的なルールを分ける |
| 未実行なのに検証済みと報告する | 報告内容と実際のログの不一致 | 実行結果を照合し、失敗・未実行の報告を求める |
さらに、AGENTS.md、CLAUDE.md、Copilot向けの指示などへ同じ内容をコピーしていると、片方だけ古いままになりがちです。共通部分の置き場所を決め、ツールが対応する参照方法を利用します。
ルールを増やす前に削る
次のような内容は、そのまま足すより見直す候補です。
- 「最高品質にする」「絶対に間違えない」など、具体的な行動に結び付かない言葉。
- 実在しないコマンド、削除済みのフォルダー、すでに変わった仕様。
- 1回だけの不具合対応や、過去のチャットを丸ごと転記した長文。
長ければよいわけではありません。既存の設定に書いてある細かな整形ルールは、その設定と実行コマンドを参照する形にまとめる、といった整理ができます。
AGENTS.mdはアクセス制御ではない
「秘密ファイルを読まないで」と書くことと、秘密ファイルを読めなくすることは別です。Claude Codeの公式資料でも、指示文は振る舞いを導くもので、ツールの許可そのものは権限設定が制御すると明記されています。権限設定の公式説明
| 守りたいこと | 指示ファイルに書くこと | 別途用意する仕組み |
|---|---|---|
| 秘密情報を漏らさない | 実値を表示・転記しない | 不要な秘密情報を渡さない。アクセス可能範囲と権限を限定する |
| 勝手に公開しない | pushやデプロイは個別確認 | 公開用の認証情報を渡さない。承認を必要にする |
| 不正な変更を取り込まない | テストと差分確認を行う | CIの必須チェック、レビュー、ブランチ保護 |
AGENTS.md自体にもAPIキーやパスワードを書かないでください。例として書くべきなのは、設定名や設定方法であって、実際の認証情報ではありません。
他人のリポジトリから受け取った指示やコマンドも、無条件に信用する対象ではありません。依存関係の導入やテストにはコード実行が伴うため、何が実行されるのかを確認し、必要に応じて隔離された環境を使います。
よくある質問
AGENTS.mdを書くと、AIは必ずテストする?
実行してほしい確認を伝える場所にはなりますが、コマンドの存在、依存関係、権限、利用するエージェントの対応などが前提です。ファイルに書いたことだけを根拠にせず、実行ログと結果を確認してください。
日本語で書いてもよい?
AGENTS.mdの形式に、英語だけで書くという制約はありません。日本語の説明と、実際のコマンド・パス・識別子を組み合わせて構いません。ただし、言語別の遵守率を本記事で比較したわけではありません。チームが見直しやすい言語を使い、曖昧な表現を避けます。形式についての公式説明
何行くらい書けばよい?
「この行数なら効く」という基準は設けません。まずは目的、実在する検証コマンド、変更時の制約、報告方法を読める量にまとめます。特定の作業にしか必要ない詳細は別文書へ分け、読む場面を示します。
READMEをコピーすればよい?
READMEを参照することは有効ですが、全文の複製は更新漏れにつながります。AGENTS.mdには、作業時に毎回必要な判断材料と、詳しい説明への案内を置く構成がおすすめです。
AGENTS.md自体をAIに作らせてもよい?
下書きを作らせることはできます。Codex CLIの/initは、AGENTS.mdのひな形を作る方法として公式に案内されています。ただし、生成されたフォルダー名、コマンド、権限に関する方針は、人が実際のプロジェクトと照合してから採用します。Codexの公式ガイド
まとめ:AIへのお願いを、確認できる作業ルールへ変える
AGENTS.mdで大切なのは、「優秀に振る舞って」と強く命令することではありません。作業する場所、守る制約、実行する確認、完了の判断材料を具体的に共有することです。
最初はプロジェクトのルートに短いファイルを置き、実在するコマンドを書き、小さな修正で試してください。その際、指示の読み込み、変更内容、検証結果を別々に確認します。繰り返し同じ説明が必要になったところだけを追記すれば、実際の開発に合った引き継ぎメモへ育てられます。
AGENTS.mdは、テストやレビューの代わりではありません。それらをAIにどう進めてもらい、結果をどう確かめるかを、プロジェクトのそばに残すためのファイルです。
関連記事
Claude Codeの使い方では導入と基本操作を、AI開発ツールの比較では操作環境や権限の見方を扱っています。変更内容を確認する基礎はGit入門、Rust側のコマンドに不慣れな場合はRustの環境構築とCargoも参照してください。
参考資料と検証範囲
ツールの仕様は以下の一次資料を確認しました。本文のテンプレート、依頼文、報告例は本記事の記入例です。掲載した検証コマンドを実際のアプリで実行する確認や、AIエージェント間の遵守率・作業時間の比較実験は行っていません。コマンドは実際の構成と照合してから使用してください。