チーム向けAGENTS.mdテンプレート：権限・禁止操作・テスト手順・レビュー基準の書き方

このテーマをもう少し広げて見るなら、チーム向けAGENTS.mdテンプレート：Codex・Claude Code・Cursorで権限とテスト手順をそろえる と CodexとClaude Codeを同じリポジトリで併用する前に決めること も合わせて確認してください。複数エージェントでAGENTS.md/CLAUDE.md/Rulesをそろえる時の実務テンプレートとして接続する。

3行まとめ

作業契約

AGENTS.mdは、エージェントへ期待する作業手順と報告形式を伝える文書です。

実行境界

危険操作は、sandbox、approval、hooks、CI、ブランチ保護で別に止めます。

継続更新

失敗ログとレビュー指摘をもとに、テンプレートを短く保ちながら更新します。

AGENTS.mdだけで安全を完成させず、設定とレビューを組み合わせて使います。

• AGENTS.mdは、AIコーディングエージェントにチームの作業前提を渡すための文書です。禁止操作を書く価値はありますが、それだけで危険操作を技術的に止められるわけではありません。
• 2026年5月28日時点の公式情報では、CodexとCursorはAGENTS.mdを直接扱い、GitHub Copilotは機能ごとに対応範囲が違い、Claude CodeはCLAUDE.mdから@AGENTS.mdを取り込む設計が現実的です。
• 実務では、AGENTS.mdに権限範囲、禁止操作、テスト手順、レビュー基準、承認フローを書き、Codexのsandboxやapproval、hooks、CI、ブランチ保護などで強制境界を別に置きます。

本文の事実確認には、公式ドキュメント、公式ヘルプ、関連する仕様・SDKドキュメントを使っています。実リポジトリでの性能ベンチマークや更新代行は、本文で明記した場合を除き実施していません。

この記事でわかること

書く内容

権限範囲、禁止操作、テスト手順、レビュー基準、承認フローを整理できます。

分ける内容

自然言語の指示と、設定で強制する権限管理を切り分けられます。

読み替え

Codex、Cursor、GitHub Copilot、Claude Codeで共通方針をどう扱うか確認できます。

運用更新

導入後にテンプレートを見直すタイミングを決められます。

テンプレートを置くことより、チームで守れる境界を決めることが目的です。

• AGENTS.mdに書く内容と、書くだけでは不十分な内容
• チーム向けAGENTS.mdの最小テンプレート
• 権限範囲、禁止操作、テスト手順、レビュー基準の書き方
• Codex、Cursor、GitHub Copilot、Claude Codeでの読み替え
• 導入後にテンプレートを更新するタイミング

前提知識

項目	内容	見方
AGENTS.md		テスト手順、レビュー基準、禁止操作、報告形式などの作業前提を共有します。
ツール設定		sandbox、approval policy、hooks、rulesで実行範囲を制限します。
リポジトリ設定		branch protection、required checks、CODEOWNERSでマージの入口を守ります。
実行環境		read-only token、短命認証、環境分離で秘密情報とネットワークを分けます。

「本番DBに触らない」と書くだけではなく、接続できない環境を用意する発想が必要です。

AGENTS.mdは、AIコーディングエージェント向けの作業説明書です。人間向けのREADME.mdがプロジェクト概要や使い方を説明するのに対し、AGENTS.mdには、エージェントが作業前に知るべきビルド手順、テスト手順、コード規約、レビュー観点、触ってよい範囲を書きます。

ただし、ここで最初に線を引きます。AGENTS.mdは自然言語の指示です。指示として有用でも、OS権限、ネットワーク権限、GitHub権限、CI権限、APIキーへのアクセスを自動的に制限するものではありません。

たとえば「本番DBに触らない」と書くことには意味があります。しかし、エージェントの実行環境が本番DBへ接続できる認証情報を持ち、ネットワークも許可されているなら、文書だけでは最後の防波堤になりません。必要なのは、作業指示と実行境界の二段構えです。

層	役割	例
AGENTS.md	期待する作業手順を共有する	テスト手順、レビュー基準、禁止操作、報告形式
ツール設定	エージェントの実行範囲を制限する	sandbox、approval policy、hooks、rules
リポジトリ設定	マージやCIの入口を守る	branch protection、required checks、CODEOWNERS
実行環境	秘密情報とネットワークを分離する	read-only token、短命認証、環境分離

この前提で、テンプレートを作ります。

まずAGENTS.mdで決めること、決めないこと

項目	内容	見方
AGENTS.mdに書く		リポジトリ概要、許可する作業、禁止操作、テスト手順、レビュー基準、報告形式を書きます。
設定で強制する		ファイル書き込み、外部通信、秘密情報、本番影響、破壊的操作は権限や承認で止めます。
レビューで補う		依存関係追加、CI/CD変更、運用影響は人間レビューとrequired checksで確認します。

禁止操作を書いたら、その操作がどの設定で止まるかまで対応表にします。

Codexの公式ドキュメントでは、Codexは作業前にAGENTS.mdを読み、グローバル、プロジェクト、下位ディレクトリの指示を結合して扱うと説明されています。CursorのRulesドキュメントでも、AGENTS.mdは簡単なエージェント指示のためのMarkdownファイルとして扱われています。AGENTS.md open formatのサイトも、セットアップ、テスト、コードスタイル、PR指示を書く場所として説明しています。

一方で、Claude Codeのmemoryドキュメントは、CLAUDE.mdを文脈として扱い、行動を確実にブロックしたい場合はhookなど別の仕組みを使うべきだと説明しています。CodexのHooksドキュメントも、PreToolUseをguardrailとして説明しつつ、完全な強制境界ではないと明記しています。

AGENTS.mdに書くべきこと

AGENTS.mdに向いているのは、毎回チャットで説明している作業前提です。

書く項目	例	書く理由
リポジトリ概要	このrepoの責務、主要ディレクトリ	初手の探索時間を減らす
許可する作業	read-only調査、差分作成、テスト実行	何を任せてよいかを明確にする
禁止操作	無断push、履歴破壊、秘密情報表示	事故につながる行動を先に伝える
テスト手順	変更範囲ごとのlint、typecheck、unit test	「テストしました」の曖昧さを減らす
レビュー基準	セキュリティ、互換性、運用影響	人間レビューの観点と揃える
報告形式	実行コマンド、結果、未検証項目	レビューしやすい最終報告にする

AGENTS.mdは、長ければよい文書ではありません。エージェントに守らせたいルールほど、短く、具体的で、実行可能な文にします。

確認項目

• その指示は、リポジトリ固有の前提か。
• 誰が読んでも同じ行動に落ちるか。
• 失敗時の報告方法まで書かれているか。
• 古いコマンドや存在しないディレクトリが残っていないか。

AGENTS.mdに閉じ込めないこと

次の項目は、AGENTS.mdにも書きますが、文書だけに任せないほうが安全です。

論点	AGENTS.mdの役割	別に必要な制御
ファイル書き込み	変更前に差分計画を出す	sandbox、権限付きワークスペース
外部通信	必要性とURLを報告する	network allowlist、承認
依存関係追加	理由、代替案、影響を書く	PRレビュー、lockfile検査、CI
秘密情報	表示、保存、ログ出力を禁止する	secret scanning、環境変数分離
本番影響	人間承認へ回す	本番認証情報を渡さない、保護ルール
破壊的操作	原則禁止と代替手順を書く	hooks、権限、ブランチ保護

Codexでは、sandbox modeとapproval policyで「読めるだけ」「workspaceに書ける」「ネットワークは承認が必要」といった段階を作れます。公式の承認とセキュリティのページでも、危険な全権限モードは推奨されていません。AGENTS.mdの禁止文は、こうした設定と組み合わせて初めて運用ルールになります。

評価基準

「禁止操作を書いたから安心」ではなく、「禁止操作がどの設定で止まるか」を対応表にできるかで確認します。対応表に空白がある場合、そこは人間レビューやCIで補う必要があります。

チーム向けテンプレートの全体像

Repository expectations

技術スタック、主要ディレクトリ、変更単位など、repoの前提を伝えます。

Allowed operations

read-only調査、差分作成、テスト実行など、任せてよい作業を明確にします。

Forbidden operations

無断push、履歴破壊、秘密情報表示など、事故につながる操作を止めます。

Testing instructions

lint、typecheck、unit、E2Eなど、変更範囲ごとの検証を指定します。

Review criteria

セキュリティ、互換性、運用影響など、人間レビューの観点と揃えます。

Human approval

依存関係追加、課金、本番影響など、人間へ戻す境界を決めます。

ルートには共通ルール、下位ディレクトリには差分だけを書くと更新漏れを減らせます。

チーム向けのAGENTS.mdは、最初から巨大な運用規程にしないほうが使われます。最小構成は次の6つです。

セクション	目的	具体例
Repository expectations	repoの前提を伝える	技術スタック、主要ディレクトリ、変更単位
Allowed operations	任せてよい作業を明確にする	read-only調査、差分作成、テスト実行
Forbidden operations	事故につながる操作を止める	無断push、履歴破壊、秘密情報表示
Testing instructions	変更に応じた検証を指定する	lint、typecheck、unit、E2E
Review criteria	自己レビューと人間レビューを揃える	セキュリティ、互換性、運用影響
Human approval	判断を人間へ戻す境界を決める	依存関係追加、課金、本番影響

この6項目があれば、小規模チームでも「エージェントに何を任せてよいか」と「どこで止めるべきか」を共有できます。

ルート用とサブディレクトリ用を分ける

モノレポでは、ルートのAGENTS.mdに全ルールを詰めると読みにくくなります。Codexはルートから現在の作業ディレクトリまでの指示を結合し、近い階層の指示を後に置きます。Cursorも、ドキュメント上ではルートとサブディレクトリのAGENTS.mdを扱えると説明しています。

基本方針は、上位に共通ルール、下位に差分だけです。

repo/
  AGENTS.md
  frontend/
    AGENTS.md
  backend/
    AGENTS.md
  infra/
    AGENTS.md

ルートには、全体の禁止操作、報告形式、共通テスト方針を書きます。frontend/にはUI変更時のテストやアクセシビリティ確認、backend/にはAPI互換性やDB migrationの承認条件、infra/にはより強い人間承認を置きます。

注意点

サブディレクトリごとに長いファイルを置くと、更新漏れが増えます。下位ファイルは、上位と異なる点だけに絞ります。

ツール固有設定を混ぜすぎない

AGENTS.mdは、複数のエージェントが読む共通方針に向いています。ツール固有の設定値を大量に入れると、別ツールの読者にとってノイズになります。

たとえば、Codexのapproval_policyやsandboxの細かい設定、Cursorの.cursor/rulesのmetadata、Copilotの.github/instructions/*/.instructions.mdの適用条件は、専用ファイルに置くほうが管理しやすいです。AGENTS.mdには「外部通信は承認が必要」「依存関係追加は理由と代替案を書く」といった共通方針を書きます。

権限範囲と禁止操作の書き方

項目	内容	見方
read-only調査		コード、設定、テスト、ドキュメントを読んでよい範囲を明示します。
workspace内編集		依頼されたIssueに関係するファイルだけを編集してよい、と対象範囲を添えます。
外部通信		必要性と宛先を報告し、network allowlistやapprovalで制限します。
依存関係追加		理由、代替案、影響、lockfile差分を示し、人間レビューへ回します。
破壊的操作		履歴破壊、削除、本番データ変更は原則禁止とし、代替手順を指定します。
本番影響		本番認証情報を渡さず、必要な場合は承認者とrollback案を明記します。

禁止操作は、理由と代替手順まで書くほどレビューで扱いやすくなります。

禁止操作から始めると、読み手は「何をしてよいか」が分からなくなります。先に許可する操作を書き、その後で禁止操作を書きます。

許可する操作を先に書く

許可する操作は、できるだけ作業単位で書きます。

操作	AGENTS.mdに書く文	補足
read-only調査	コード、設定、テスト、ドキュメントを読んでよい	秘密情報ファイルは読まない
差分作成	workspace内の対象ファイルを編集してよい	生成物だけの変更は理由を書く
テスト実行	変更範囲に応じた検証コマンドを実行する	失敗時は原因を残す
ドキュメント更新	挙動変更に伴うREADMEやdocs更新を提案する	仕様変更と実装差分を揃える
PR説明作成	変更内容、テスト結果、残リスクをまとめる	人間が最終確認する

条件

許可する操作には、対象範囲を添えます。「ファイルを編集してよい」ではなく、「workspace内で、依頼されたIssueに関係するファイルだけを編集してよい」と書きます。

禁止操作は理由と代替手順まで書く

禁止操作は、単語だけのリストにしないほうが守られます。理由と代替手順をセットにします。

禁止操作	理由	代替手順
無断push、無断merge	人間レビューを飛ばすため	patchを残し、PR説明だけ作る
履歴を破壊するGit操作	他メンバーの作業を壊すため	状態を報告し、人間に確認する
秘密情報の表示やログ出力	漏えいにつながるため	値を伏せ、キー名だけ報告する
本番データの変更	事業影響が大きいため	read-only確認に留める
無断の依存関係追加	供給網リスクと保守コストが増えるため	代替案、理由、影響を提示する
CI/CD設定の大幅変更	デプロイ経路を変えるため	変更理由とrollback案を出す

確認項目

禁止文ごとに、強制手段を紐づけます。

禁止したいこと	強制手段の例
workspace外の編集	sandbox、ファイル権限
外部通信	network allowlist、approval
危険なshell実行	hooks、approval、実行ユーザー分離
本番認証情報の利用	認証情報を渡さない、短命token
main branchへの直接push	branch protection、required reviews

ここで空白があるなら、AGENTS.mdではなく運用か設定を見直す場所です。

テスト手順と検証コマンドの書き方

1. 1変更範囲を判定

   TypeScript、UI、依存関係、DB schema、CI workflow、docsのみの変更を分けます。

2. 2最低限の確認を実行

   typecheck、unit test、lint、リンク確認など、範囲に合うコマンドを実行します。

3. 3追加確認を判断

   UI差分、E2E、migration dry run、secret参照など、影響に応じた確認を足します。

4. 4未実行を記録

   実行できない検証は、コマンド、理由、残リスクを最終報告に残します。

人間レビュー時に、何を実行し、何が未実行で、なぜ未実行かが分かる状態を合格にします。

AIエージェントに「テストして」とだけ書くと、軽いコマンドだけで終わることがあります。チーム向けテンプレートでは、変更範囲と実行コマンドを紐づけます。

変更範囲ごとに実行コマンドを分ける

以下はTypeScript/Next.js系リポジトリの例です。実際のコマンドは自分のrepoに合わせます。

変更範囲	最低限の確認	追加確認
src/*/.ts	npm run typecheck、npm test	関連unit test
src/*/.tsx	npm run typecheck、npm test	UI差分確認、E2E対象確認
package.json、lockfile	npm install相当の整合性確認、npm test	依存関係の変更理由
DB schema	migration dry run相当の確認	rollback手順、人間承認
CI workflow	YAML lint相当の確認	実行権限とsecret参照の確認
docsのみ	markdown lintまたはリンク確認	実装との矛盾確認

確認項目

• コマンドの実行ディレクトリが書かれているか。
• どの変更でどのコマンドを走らせるかが分かるか。
• 失敗した時に、修正するのか、報告だけにするのかが分かるか。
• 実行できない時の報告形式があるか。

テストできない時の報告ルールを書く

実務では、外部サービスの認証情報がない、時間が足りない、ローカル環境がない、権限がない、といった理由で検証できないことがあります。大事なのは、未検証を成功扱いにしないことです。

最終報告の形式を決めておきます。

Report format:
- Summary: 変更内容を3行以内で説明する
- Commands run: 実行したコマンドと結果を書く
- Not run: 実行できなかった検証と理由を書く
- Risk: 残っているリスクを書く
- Human review needed: 人間に確認してほしい点を書く

評価基準

人間レビュー時に「何を実行し、何が未実行で、なぜ未実行か」がすぐ分かるなら合格です。逆に「テスト済みです」だけなら、AGENTS.mdのテスト手順はまだ弱いです。

レビュー基準と人間承認フローの書き方

1. 1自動作業

   依頼範囲に沿って調査、差分作成、テスト実行、報告準備を進めます。

2. 2自己レビュー

   変更範囲、コード品質、テスト、セキュリティ、互換性、運用影響を確認します。

3. 3人間承認

   依存関係追加、DB migration、CI/CD変更、本番影響、外部API書き込みを確認に戻します。

4. 4マージ前確認

   実行コマンド、未検証項目、残リスク、承認内容をそろえて最終判断します。

承認フローは、誰に、何を、どの粒度で確認するかまで書くと運用に乗ります。

AGENTS.mdは、エージェントの自己レビューにも使えます。ここでは、エージェントが最終報告前に確認する観点と、人間へ戻す条件を分けます。

エージェントの自己レビュー基準

自己レビュー基準は、以下の観点に分けると使いやすくなります。

観点	確認内容
変更範囲	依頼範囲外の変更が混ざっていないか
コード品質	既存パターンに沿っているか
テスト	変更範囲に必要な検証を実行したか
セキュリティ	秘密情報、認可、入力検証、ログを確認したか
互換性	API、DB schema、設定の破壊的変更がないか
運用影響	デプロイ、監視、rollbackに影響しないか
レビュー容易性	差分と理由を説明できるか

評価基準

レビューコメントや最終報告に、ファイル、理由、影響、修正案、残リスクが含まれるようにします。エージェントの出力が自然文だけになりがちな場合は、表形式で報告させると確認しやすくなります。

人間承認が必要な境界

承認が必要な境界は、最初から書きます。

人間承認が必要な変更	承認前に出す情報
依存関係追加、major update	理由、代替案、lockfile差分、ライセンス確認
DB migration	影響範囲、rollback、データ保持
CI/CD変更	secret参照、権限、失敗時の影響
本番影響のある設定	対象環境、戻し方、監視項目
外部API書き込み	対象API、実行回数、料金影響
秘密情報に触れる作業	値を表示せず、必要な権限だけ説明

注意点

「人間承認を求める」とだけ書いても、承認フローとしては弱いです。誰に、何を、どの粒度で確認するかまで書きます。Codexならapproval policy、Claude Codeならhook、CopilotならGitHub上のレビューやbranch protection、CursorならRulesやチーム設定と組み合わせます。

Codex、Cursor、Copilot、Claude Codeでの読み替え

項目	内容	見方
Codex		AGENTS系ファイルで、全体と下位ディレクトリの指示を扱います。
Cursor		RulesとAGENTS.mdで、個人、チーム、プロジェクトの方針を分けます。
GitHub Copilot		Copilot用instructionsとAGENTS.mdは、機能ごとの対応範囲を確認します。
Claude Code		CLAUDE.mdを中心にし、共通方針は取り込みで扱います。

複数ツールで同じ禁止文をコピーし続けると更新漏れが起きるため、共通方針と実装設定を分けます。

同じAGENTS.mdを書いても、各ツールの読み方は同じではありません。2026年5月28日時点の公式情報を前提に、実務での扱いを整理します。

ツール	主な指示ファイル	スコープ	注意点
Codex	AGENTS.md、AGENTS.override.md	グローバル、repo、下位ディレクトリ	結合サイズ上限と近い階層の優先を意識する
Cursor	.cursor/rules、AGENTS.md	project rules、team rules、user rules、下位AGENTS.md	複雑な条件はRulesに寄せる
GitHub Copilot	.github/copilot-instructions.md、.github/instructions/*/.instructions.md、AGENTS.mdなど	機能と環境により異なる	code reviewやIDEごとに対応範囲が違う
Claude Code	CLAUDE.md、.claude/rules/	project、subdirectory、rules	AGENTS.mdは直接ではなくCLAUDE.mdから取り込む設計

共通AGENTS.mdを中心にする場合

複数ツールを使うチームでは、まず共通方針をAGENTS.mdに置きます。その上で、Claude Code用にCLAUDE.mdから@AGENTS.mdをimportし、Copilot用に.github/copilot-instructions.mdから同じ方針へ誘導し、Cursorでは複雑なスコープを.cursor/rulesへ分けます。

この方式の良さは、同じ禁止事項を4か所にコピーしないことです。コピーが増えるほど、古いテストコマンドや廃止した承認者が残ります。

ツール固有の設定へ逃がす場合

条件付きで読み込むルール、チームで強制する設定、特定パスだけに効く指示は、各ツールの仕組みへ逃がします。たとえばCursorのRulesはパス条件やTeam Rulesを扱えます。Copilotはリポジトリ全体、パス別、agent instructionsの対応が環境によって異なります。Claude Codeは.claude/rules/でpath-specific rulesを扱えます。

AGENTS.mdは、共通の作業契約として短く保ちます。細かい適用条件は、各ツールの正式な設定へ分けます。

そのまま使えるAGENTS.mdテンプレート案

Repository expectations

チーム名、作業前の確認、変更範囲、差分の大きさ、不明点の扱いを書きます。

Allowed operations

読んでよいファイル、編集してよい範囲、実行してよい検証、更新してよいドキュメントを書きます。

Forbidden operations

push、merge、履歴破壊、秘密情報表示、本番変更、CI/CD権限変更の禁止を書きます。

Testing instructions

TypeScript、UI、依存関係、docsのみの変更ごとに確認方法を書きます。

Review and approval

自己レビュー観点と、人間承認が必要な変更を分けて書きます。

Final report format

Summary、Files changed、Commands run、Not run、Riskを固定します。

社内URL、実在の承認者、秘密情報名、本番環境名は公開リポジトリへ書きすぎないようにします。

ここからは、最小テンプレートです。公開用に、社内URL、実在の承認者、秘密情報名、プロジェクト固有の本番環境名はすべてプレースホルダーにしています。

# AGENTS.md

 ## Repository expectations

- This repository is maintained by <TEAM_NAME>.
- Before editing, inspect the related files, tests, and existing conventions.
- Keep changes scoped to the user request. Do not refactor unrelated code.
- Prefer small, reviewable diffs over broad rewrites.
- If requirements are unclear, ask before making irreversible changes.

 ## Allowed operations

- You may read source code, tests, documentation, and configuration files needed for the task.
- You may edit files inside this workspace when the requested task requires it.
- You may run local lint, typecheck, unit test, and build commands listed below.
- You may update documentation when behavior or commands change.

 ## Forbidden operations

- Do not push, merge, tag, release, or deploy without explicit human approval.
- Do not rewrite Git history or discard user changes.
- Do not print, copy, store, or log secrets, tokens, credentials, or private personal data.
- Do not modify production data or production infrastructure.
- Do not add new production dependencies without explaining the reason, alternatives, and risk.
- Do not change CI/CD permissions, secret references, or deployment settings without human approval.
- Do not edit files outside this workspace.

 ## Testing instructions

- For TypeScript source changes, run:
  - `npm run typecheck`
  - `npm test`
- For UI changes, also run the relevant component or E2E test if available.
- For dependency changes, explain the lockfile change and run the normal test suite.
- For documentation-only changes, check that commands and links are still accurate.
- If a command cannot be run, report the command, the reason, and the risk.

 ## Review criteria

Before finishing, check:

- The diff stays within the requested scope.
- Existing code style and architecture are followed.
- Input validation, authorization, logging, and error handling are not weakened.
- Tests were added or updated when behavior changed.
- Backward compatibility and migration impact were considered.
- Generated files and lockfiles are changed only when necessary.

 ## Human approval required

Ask for approval before:

- Adding or upgrading production dependencies.
- Changing database schema or migration behavior.
- Changing authentication, authorization, billing, or security-sensitive code.
- Changing CI/CD, deployment, infrastructure, or secret configuration.
- Running commands that affect external services.
- Performing any action that cannot be safely reviewed as a local diff.

 ## Final report format

- Summary: What changed and why.
- Files changed: Important files and the purpose of each change.
- Commands run: Command, result, and any failure.
- Not run: Checks that were skipped and why.
- Risk: Remaining risk or human review points.

モノレポ用の追加テンプレート

下位ディレクトリには、差分だけを書きます。

# frontend/AGENTS.md

 ## Frontend-specific rules

- Use the existing component patterns in this directory.
- For UI changes, include the relevant test or explain why no test is needed.
- Do not introduce a new UI library without human approval.
- Confirm loading, error, and empty states when changing data-driven screens.

# infra/AGENTS.md

 ## Infrastructure-specific rules

- Treat every infrastructure change as human-approval required.
- Do not modify deployment, secret, network, or permission settings without approval.
- Provide a rollback plan for every proposed change.
- Prefer read-only inspection and written recommendations unless the user explicitly approves an edit.

使う前の置き換え項目

• <TEAM_NAME>を実チーム名へ置き換える。
• テストコマンドを自分のrepoのコマンドへ置き換える。
• 承認者、CODEOWNERS、PRルールは社内運用に合わせる。
• 本番環境や秘密情報の具体名は、公開リポジトリに書きすぎない。

導入時のチェックリストと更新運用

1. 1読み込み確認

   対象ツールに、読み込んだ指示ファイルを確認させます。

2. 2コマンド確認

   AGENTS.mdに書いたlint、typecheck、testが実際に動くか確認します。

3. 3権限確認

   workspace外編集、外部通信、本番操作が設定で制限されているか見ます。

4. 4スモークテスト

   小さなIssueで、最終報告が期待形式になるか確認します。

5. 5更新レビュー

   同じミス、テスト漏れ、承認漏れ、コマンド変更をきっかけに見直します。

長文化した時は、使われていないルールや古いワークフローを削るレビューも行います。

テンプレートは置いて終わりではありません。最初の導入時に、読み込まれるか、守れるか、強制設定と矛盾しないかを確認します。

初回導入チェック

チェック	合格条件
読み込み確認	対象ツールに「読み込んだ指示ファイル」を確認させる
コマンド確認	書いたlint、typecheck、testが実際に動く
権限確認	workspace外編集、外部通信、本番操作が設定で制限されている
レビュー確認	人間が最終報告を見て判断できる
更新責任	誰がAGENTS.mdを保守するか決まっている

最初のスモークテストは、小さなIssueで十分です。エージェントにAGENTS.mdを読ませ、1つの軽い修正を依頼し、最終報告が期待形式になるかを見ます。

失敗から更新する

AGENTS.mdは、失敗ログから育てます。

更新タイミング	更新内容
同じミスが2回出た	具体的な禁止文や確認項目を追加する
テスト漏れが出た	変更範囲とコマンドの対応表を直す
承認漏れが出た	人間承認が必要な境界を追加する
コマンドが変わった	古いコマンドを削り、現行コマンドへ更新する
サブシステムが増えた	下位AGENTS.mdやtool固有rulesを追加する

長文化したら、削るレビューも必要です。使われていないルール、個人の好み、古いワークフローは消します。短い文書ほど、エージェントにも人間にも読まれます。

結果

採用する

権限範囲、禁止操作、テスト手順、レビュー基準、承認フローを短く書きます。

分ける

sandbox、approval、hooks、CI、branch protectionは別設定で管理します。

避ける

全ツールの細かい設定をAGENTS.mdに詰め込みすぎないようにします。

続ける

失敗ログとレビュー指摘から、AGENTS.mdと強制設定を更新します。

AGENTS.mdは期待する動きを伝え、設定とレビューはやってはいけない動きを止めます。

今回の結論は、チーム向けAGENTS.mdを「安全設定の代替」ではなく「作業契約」として使うことです。

判断	内容
採用する	権限範囲、禁止操作、テスト手順、レビュー基準、承認フローを短く書く
分ける	sandbox、approval、hooks、CI、branch protectionは別設定で管理する
避ける	全ツールの細かい設定をAGENTS.mdに詰め込む
続ける	失敗ログとレビュー指摘から更新する

AIコーディングエージェントは、文書があれば必ず同じ行動をするわけではありません。だからこそ、AGENTS.mdは「期待する動き」を伝え、設定とレビューで「やってはいけない動き」を止めます。

失敗点

項目	内容	見方
禁止だけ多い		何を任せてよいか分からないため、Allowed operationsを先に書きます。
抽象的すぎる		毎回違う解釈を避けるため、コマンド、条件、報告形式まで書きます。
強制設定がない		文書上は禁止でも実行できるため、sandbox、approval、CIで止めます。
更新されない		古いコマンドや担当者が残るため、レビュー指摘を更新トリガーにします。

特に危ないのは、AGENTS.mdに書いたことを実行権限そのものと見なすことです。

導入時に起きやすい失敗は、次の4つです。

失敗	起きること	対策
禁止だけ多い	何を任せてよいか分からない	Allowed operationsを先に書く
抽象的すぎる	エージェントが毎回違う解釈をする	コマンド、条件、報告形式まで書く
強制設定がない	文書上は禁止でも実行できてしまう	sandbox、approval、CIで止める
更新されない	古いコマンドや担当者が残る	レビュー指摘を更新トリガーにする

特に危ないのは、「AGENTS.mdに書いたから安全」と見なすことです。公式情報を見ても、自然言語の指示は文脈であり、実行権限そのものではありません。

実務で使うなら

1. 1. ルートに置く

   短いAGENTS.mdをrepoの入口に置きます。

2. 2. 最小項目を書く

   許可する操作、禁止操作、テスト手順、報告形式だけから始めます。

3. 3. 読み込みを確認

   対象ツールでAGENTS.mdが読まれるか確認します。

4. 4. 設定で制限

   workspace外編集、外部通信、依存関係追加、本番影響を設定で制限します。

5. 5. 小さく試す

   1つの小さなIssueでスモークテストします。

6. 6. 更新する

   レビュー指摘をもとにテンプレートを見直します。

複数ツールを使う場合は、AGENTS.mdを共通の作業契約にし、各ツール設定は補助に回します。

小さく始めるなら、次の順番が現実的です。

1. ルートに短いAGENTS.mdを置く。
2. 許可する操作、禁止操作、テスト手順、報告形式だけを書く。
3. 対象ツールで読み込まれるか確認する。
4. workspace外編集、外部通信、依存関係追加、本番影響を設定で制限する。
5. 1つの小さなIssueでスモークテストする。
6. レビュー指摘をもとにテンプレートを更新する。

AIコーディングエージェントを複数使うチームでは、AGENTS.mdを共通の作業契約にし、CLAUDE.md、.cursor/rules、.github/copilot-instructions.mdなどは補助に回すと管理しやすくなります。外部ツール連携やMCPの権限設計まで広げる場合は、MCPカテゴリで扱うようなtool権限の考え方も同じ線で見ます。

AI開発ツールの運用テンプレートや検証メモを追いたい場合は、記事の読了後にニュースレターで更新を受け取れるようにしておくと、仕様変更の確認漏れを減らせます。

セキュリティ・コスト注意

項目	内容	見方
秘密情報		エージェントに渡す環境から外し、ログに値を出さないようにします。
ネットワーク		既定で閉じ、必要な宛先だけ承認します。
MCPや外部API		read-onlyから始め、書き込みは承認制にします。
依存関係		追加理由、代替案、ライセンス、lockfile差分を確認します。
コスト		長い調査、再試行、外部API呼び出しには上限を置きます。
監査		コマンド、tool call、PR差分、未検証項目を残します。

全権限モードは、必要な時だけ、短い時間、限定された作業で使う前提にします。

AGENTS.mdはセキュリティ対策の一部ですが、単独の対策ではありません。

注意点	実務対応
秘密情報	エージェントに渡す環境から外す。ログに値を出さない
ネットワーク	既定で閉じ、必要な宛先だけ承認する
MCPや外部API	read-onlyから始め、書き込みは承認制にする
依存関係	追加理由、代替案、ライセンス、lockfile差分を確認する
コスト	長い調査、再試行、外部API呼び出しには上限を置く
監査	コマンド、tool call、PR差分、未検証項目を残す

Codexの危険な全権限モードのように、sandboxもapprovalも外す設定は便利に見えますが、チーム運用では避けるのが基本です。必要な時だけ、短い時間、限定された作業で、人間が意図を確認して使います。

FAQ

READMEとの分担

READMEは人間向け、AGENTS.mdはエージェント向けの作業ルールに分けます。

全部は書かない

全員に効く共通方針だけを書き、パス別や強制設定は専用の仕組みに分けます。

Copilotの対応差

Copilot Chat、cloud agent、code review、IDEごとに対応範囲を確認します。

Claude Codeの共通化

CLAUDE.mdからAGENTS.mdを取り込む方法で共通方針を扱います。

守られない禁止操作

文を強くするだけでなく、sandbox、approval、hooks、CI、ブランチ保護で止めます。

迷った時は、共通方針か、パス別ルールか、強制設定かに分けて考えます。

AGENTS.mdとREADME.mdは分けるべきですか

分けるほうが管理しやすいです。READMEは人間向けの概要と導入手順、AGENTS.mdはエージェント向けの作業ルールにします。ただし、セットアップコマンドが二重管理になるなら、READMEを参照させても構いません。

AGENTS.mdに全部のルールを書けばよいですか

いいえ。全員に効く共通方針だけを書きます。パス別、チーム別、ツール別、強制設定は専用の仕組みに分けます。

CopilotでもAGENTS.mdだけで足りますか

機能や環境によります。GitHubの公式サポート表では、Copilot Chat、cloud agent、code review、IDEごとに対応が違います。Copilot中心のチームなら、.github/copilot-instructions.mdや.github/instructions/*/.instructions.mdも確認してください。

Claude CodeではAGENTS.mdをそのまま読ませられますか

Claude Codeの公式ドキュメントでは、Claude CodeはCLAUDE.mdを読み、AGENTS.mdそのものではないと説明されています。共通化したい場合は、CLAUDE.mdに@AGENTS.mdを書いて取り込む方法が示されています。

禁止操作を書いても守られない時はどうしますか

文を強くするだけでは不十分です。該当操作をsandbox、approval、hooks、CI、GitHub権限、ブランチ保護で止められるかを確認します。

更新履歴

1. 2026年5月28日

   OpenAI Codex、Claude Code、GitHub Copilot、VS Code、Cursor、AGENTS.md open formatの公式情報を確認し、チーム向けテンプレートを作成しました。

AIコーディングエージェント周辺の仕様は変わりやすいため、更新日と確認範囲を残します。

日付	内容
2026年5月28日	初版。OpenAI Codex、Claude Code、GitHub Copilot、VS Code、Cursor、AGENTS.md open formatの公式情報を確認し、チーム向けテンプレートを作成

次に読むなら

---

次に読むなら

参照した主な情報源

• https://developers.openai.com/codex/guides/agents-md
• https://developers.openai.com/codex/permissions
• https://developers.openai.com/codex/hooks
• https://developers.openai.com/codex/agent-approvals-security
• https://code.claude.com/docs/en/memory
• https://docs.github.com/en/copilot/concepts/prompting/response-customization
• https://docs.github.com/en/copilot/reference/custom-instructions-support
• https://code.visualstudio.com/docs/copilot/customization/custom-instructions
• https://cursor.com/docs/rules
• https://agents.md/