AGENTS.mdの書き方|AIに開発ルールとテスト手順を伝える

公開 約19分で読む著者:admin

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
目的・対象・完了条件
実際に確かめること
テスト・差分・レビュー
結果と残った問題
図1:作業のルール、今回の依頼、結果の確認は別々に必要です。AGENTS.mdだけで残りの2つを置き換えることはできません。

まずは短いAGENTS.mdを1つ作る

最初は、Gitで管理しているプロジェクトの最上位フォルダーに、大文字のAGENTS.mdという名前で作成します。Windowsでは拡張子が隠れていると、意図せずAGENTS.md.txtになることがあるため、ファイル名を確認してください。

PLAINTEXT
my-project/
├── AGENTS.md
├── README.md
└── src/

いきなり大きなテンプレートを埋める必要はありません。例えば、次のような短い内容から始められます。これは本記事の出発点の例であり、見出しや項目が仕様で必須という意味ではありません。

MARKDOWN
# 作業ルール

## 変更前
- 対象の実装と関連テストを読んでから変更する。
- 今回の依頼と無関係な修正や一括整形を混ぜない。
- 作業開始時に存在する未コミットの変更を上書き・巻き戻ししない。

## 確認が必要な操作
- 依存パッケージの追加・更新、公開APIの変更は先に提案する。
- push、公開、デプロイ、データ削除は個別の許可を得る。

## 検証と報告
- READMEとプロジェクト設定で、実在する検証コマンドを確認する。
- 実行したコマンド、結果、未実行の確認と理由を分けて報告する。
- 実行していないテストを「成功」「確認済み」と書かない。

この例はまだ一般的です。次に、自分のプロジェクトで繰り返し説明していることを足します。「このフォルダーは自動生成」「このコマンドは外部サービスへの接続が必要」といった、そのリポジトリ固有の事情が候補です。

一方、コードや設定を見ればすぐ分かることを大量に転記すると、更新する場所が増えます。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を導入済みの小さな学習記録アプリを例にします。実在するサイトの構成を調査したものではありません。自分のプロジェクトへ使う場合は、フォルダー名、実行環境、検証コマンドを置き換えてください。

PLAINTEXT
study-log/
├── AGENTS.md
├── README.md
├── .nvmrc
├── .env.example
├── package.json
├── package-lock.json
├── tsconfig.json
├── index.html
├── src/
│   ├── main.ts
│   └── stats.ts
└── tests/
    └── stats.test.ts

先にpackage.jsonのscriptsを確かめる

npm run typecheckは、すべてのTypeScriptプロジェクトに最初から存在するコマンドではありません。package.jsonのscriptsで定義されている必要があります。引数なしのnpm runで、利用可能なスクリプトを一覧できます。npmの公式リファレンス

次は、この例で想定するscriptsの部分です。既存のpackage.json全体を、この断片で上書きしないでください。TypeScript・Vite・Vitestの導入と設定も別途必要です。

JSON
{
  "scripts": {
    "dev": "vite",
    "typecheck": "tsc --noEmit",
    "test": "vitest run",
    "build": "vite build"
  }
}

テストには、変更を監視し続けるモードではなく、一度実行して終了するvitest runを指定しています。エージェントが作業の完了を判断するときも、待機中なのか、実行が終わったのかを区別しやすくなります。Vitestの実行方法

AGENTS.mdの記入例

MARKDOWN
# Study Logの開発ルール

## 目的と構成
- ブラウザで学習時間を記録・集計するアプリ。
- 画面の入口はsrc/main.ts、集計処理はsrc/stats.ts。
- 集計処理のテストはtests/stats.test.ts。
- 対象の実装とテストを読み、必要な範囲だけ変更する。

## 環境
- Node.jsの指定は.nvmrc、依存関係はpackage-lock.jsonを参照する。
- パッケージ管理はnpm。別のロックファイルを追加しない。
- 初期セットアップは、READMEと依存関係を確認してからnpm ci。
- 依存追加・更新が必要なら、理由を示して先に確認を得る。

## 変更時の約束
- 依頼と無関係なリファクタリングや全体の整形を混ぜない。
- src/stats.tsにはDOM操作を持ち込まない。
- 外部入力は実行時にも検証する。型アサーションだけで済ませない。
- 不具合修正では、その不具合を再現するテストを追加する。
- テストを通すためだけに検証条件や型チェックを弱めない。
- ユーザーの未コミットの変更は保持する。

## 変更後の確認(リポジトリのルートで実行)
- npm run typecheck
- npm test
- npm run build
- 画面に触れた場合は、確認した操作と未確認の操作も報告する。
- コマンドが使えない場合は勝手に置き換えず、理由を報告する。

## 秘密情報と公開操作
- .envや認証情報の実値を読んで転記しない。設定名は.env.exampleで確認する。
- 明示的な依頼なしにpush、公開、デプロイを行わない。

## 完了報告
- 変更内容と対象ファイル。
- 実行した確認のコマンドと結果。
- 実行できなかった確認、その理由、残っている懸念。

このテンプレートは、「TypeScriptを使う」という情報よりも、集計処理と画面を分けること、検証結果を区別して報告することに重点を置いています。

npm ciを初期セットアップに書いていても、毎回必ず実行させる必要はありません。また、信頼できないリポジトリでインストールを無条件に許可する運用にも使わないでください。依存関係やスクリプトの確認は別の作業です。

Rustの小さなCLI向けAGENTS.mdテンプレート

Rustでは、cargo checkとcargo testを混同しないことが重要です。前者はコードを検査するコマンド、後者はテストをコンパイル・実行するコマンドです。cargo checkが成功しても、テストを実行したことにはなりません。Cargoのcheck/Cargoのtest

ここでは、Cargo.lockを管理している単一パッケージのCLIを想定します。ワークスペース、独自features、外部サービスが必要なテストを使う場合は、それぞれの設定に合わせて変更します。

MARKDOWN
# Study Stats CLIの開発ルール

## 目的と構成
- 学習時間の記録を読み取り、端末に集計結果を表示するCLI。
- 引数と入出力はsrc/main.rs、集計処理はsrc/lib.rs。
- 振る舞いを変える前に関連するテストを確認する。

## 環境
- Rustの指定はrust-toolchain.toml、EditionはCargo.tomlに従う。
- このプロジェクトではCargo.lockをGitで管理する。
- 依存追加・更新、featuresの変更は先に理由を示して確認を得る。

## 実装上の約束
- 外部入力やファイル操作の失敗を、理由なくunwrapで処理しない。
- エラー型とエラー表示は既存の設計に合わせる。
- unsafeが必要なら、実装前に理由と代案を示す。
- 不具合修正には再現テストを追加する。
- 型・検証・既存テストを弱めて失敗を隠さない。
- ユーザーの未コミットの変更は保持する。

## 確認(リポジトリのルートで実行)
- cargo fmt --all -- --check
- cargo test --locked
- cargo clippy --locked --all-targets -- -D warnings
- cargo checkだけで「テスト済み」としない。
- ツール不足や既存の失敗は、新たな不具合と分けて報告する。

## 作業範囲と報告
- 出力形式や終了コードの変更が必要なら、互換性への影響を先に示す。
- 明示的な依頼なしにpush、公開、データ削除を行わない。
- 変更内容、実行コマンドと結果、未実行の確認を報告する。

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 CLIAGENTS.mdに対応。複数の指示ファイルを併用する仕組みがある/instructionsで検出されたファイルと有効・無効を確認する

出典:CodexのAGENTS.md、Claude Codeのメモリ、GitHub Copilot CLIのカスタム指示。この表はCopilotのすべての画面・機能で同じ動作を保証するものではありません。

Claude Codeと共有する場合

プロジェクト直下のCLAUDE.mdに、次の1行を入れる方法が公式に案内されています。

MARKDOWN
@AGENTS.md

ここでの@はClaude Codeが対応しているインポート記法です。Markdown一般の機能でも、すべてのエージェントに共通する記法でもありません。既存のCLAUDE.mdがある場合は上書きせず、重複や矛盾を確認して追加します。Claude Codeの公式説明

共通ルールはAGENTS.mdへ、Claude Code固有の補足はCLAUDE.mdへ置くと、同じ文章を2か所で修正し続けずに済みます。ただし、読み込んだことと、すべての内容に従ったことは別なので、実際の変更と検証ログも確認します。

大きなプロジェクトでは、指示をフォルダーごとに分ける

フロントエンドとCLIを同じリポジトリで管理する場合、すべての指示をルートへ詰め込むと、どのコマンドがどこに対応するのか分かりにくくなります。次は役割を分ける配置例です。

PLAINTEXT
repository/
├── AGENTS.md                 # 共通の変更方針・報告・公開操作の扱い
├── apps/
│   └── web/
│       ├── AGENTS.md         # Webアプリ固有の構成と確認方法
│       └── package.json
└── tools/
    └── cli/
        ├── AGENTS.md         # CLI固有の構成と確認方法
        └── Cargo.toml

子フォルダー側には、例えば「作業ディレクトリはapps/web。検証はその場所で行う」と、どこで実行するかも書きます。ルートでしか動かないコマンドと、子フォルダーで実行するコマンドを混在させないことが重要です。

ただし、「編集するファイルに一番近い指示だけを読めばよい」と一律に決めつけないでください。Codexの公式資料では、起動時の探索はプロジェクトのルートから現在の作業ディレクトリまでの経路をたどり、上位から下位へ指示を組み合わせると説明されています。ルートで起動しただけで、全子フォルダーの指示が最初から一括で入るとは限りません。Codexの探索方法

また、GitHub Copilot CLIの公式資料は、適用対象の複数ファイルを組み合わせる一方、ファイル間の一般的な優先順序を定めていないと説明しています。矛盾を優先順位で解決させるのではなく、共通ルールと個別ルールを矛盾させないことを基本にします。Copilot CLIの指示の扱い

実践:ルールを読ませてから、小さな修正を頼む

1.最初は編集せず、指示を確認する

新しい指示ファイルを置いたら、すぐに大きな変更を依頼せず、例えば次のように確認します。

PLAINTEXT
まだファイルの変更や、ビルド・テスト・インストールは行わないでください。
読み取り専用の操作で、今回の作業に適用される指示ファイルを確認し、パスを挙げてください。
そのうえで、変更してよい範囲、検証コマンド、事前確認が必要な操作を要約してください。
読み込めていないものや不明点は、推測せず区別してください。

これは確認を促すための依頼例で、特別な設定コマンドではありません。回答だけを証拠にせず、ツールが表示する読み込み情報や参照ファイルも照合します。指示を変更した後の再読み込み方法も、利用中のツールの仕様を確認してください。

2.今回の完了条件はチャットで具体化する

AGENTS.mdに毎回の修正内容を書き足すのではなく、今回の課題はチャットやIssueへ置きます。先ほどのTypeScriptアプリなら、次のような依頼が考えられます。

PLAINTEXT
src/stats.tsにある集計処理を修正してください。

目的:
空配列を渡したとき、合計学習時間が0になるようにする。

今回の範囲:
src/stats.tsとtests/stats.test.tsだけを変更する。
画面、依存パッケージ、データ保存形式は変更しない。

完了条件:
- 空配列の合計が0になる。
- [25, 15]の合計は40のまま。
- この2ケースをテストで確認する。
- AGENTS.mdに書かれた検証を行い、実行結果と未実行項目を区別する。

範囲外の変更が必要と分かった場合は、実装前に理由を説明してください。

「何を直すか」だけでなく、「今回は何を変えないか」があると、結果をレビューするときの基準にもなります。なお、範囲を狭くしすぎると適切な修正を妨げる場合もあるので、必要な変更を提案できる余地は残します。

3.「終わりました」ではなく、検証結果を見る

以下は報告形式の記入例であり、この記事で実測したログではありません。

PLAINTEXT
変更:
- 空配列の合計が0になるよう修正
- 空配列と通常入力のテストを追加

検証:
- npm run typecheck:実行し、終了コード0を確認
- npm test:実行できず。Vitestがインストールされていない
- npm run build:未実行

未完了:
- 依存関係を準備した環境で、テストとビルドの確認が必要
- すべての完了条件を満たしたとは報告しない

この状況なら、変更案ができていても、検証まで完了したとは言えません。失敗が作業前からあったのか、変更によって生じたのかも区別し、必要な確認を人が引き継げる形にします。

① 指示の確認
対象と手順を共有
② 小さく変更
実装と再現テスト
③ 結果を確認
コマンド・差分・動作
④ ルールを見直す
繰り返す問題だけ反映
図2:AGENTS.mdは一度作って終わりではありません。実際の作業で不足した情報を見つけ、必要な項目だけを更新します。

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エージェント間の遵守率・作業時間の比較実験は行っていません。コマンドは実際の構成と照合してから使用してください。

  1. AGENTS.md公式サイト
  2. OpenAI:Custom instructions with AGENTS.md
  3. OpenAI:Codexのベストプラクティス
  4. Anthropic:How Claude remembers your project
  5. GitHub:Copilot CLIのカスタム指示
  6. npm:npm run
  7. Vitest:コマンドライン
  8. Rust:cargo check/cargo test/Clippy
  9. Anthropic:Configure permissions

\ 最新情報をチェック /

記事一覧に戻る

コメントを書く

メールアドレスが公開されることはありません。 ※ が付いている欄は必須項目です