3行まとめ
AGENTS.mdは、AIコーディングエージェントにプロジェクトの文脈、作業範囲、テスト、レビュー観点を渡すためのファイルです。
禁止事項はAGENTS.mdに書き、実際の制御はsandbox、permissions、hooks、CI、人間承認へ分けます。
CodexはAGENTS.md、Claude CodeはCLAUDE.mdからのimport、CursorはProject Rulesとの使い分けで整理します。
AGENTS.mdは安全の始まりであり、安全の完成ではありません。
- AGENTS.mdは、AIコーディングエージェントに読ませる作業前提をそろえるファイルです。権限そのものを閉じる仕組みではないので、sandbox、permissions、hooks、CI、人間承認と分けて設計します。
- 最初のテンプレートは、プロジェクト概要、作業範囲、許可操作、禁止操作、テスト手順、レビュー基準、報告フォーマットの7項目だけで十分です。
- CodexはAGENTS.mdを中心に置き、Claude CodeはCLAUDE.mdからAGENTS.mdをimportし、CursorはAGENTS.mdとProject Rulesを使い分けると、同じチームルールを散らかさずに運用できます。
この記事では、2026年6月5日にOpenAI Codex、Claude Code、Cursor、GitHub Copilot、AGENTS.md open formatの公式情報を確認しました。Xの投稿は需要シグナルとして確認しましたが、tracked accountの直近72時間投稿本文は安定して取得できなかったため、本文の仕様説明には使っていません。スポンサー、アフィリエイト、検証環境提供はありません。
この記事でわかること
チーム向けAGENTS.mdに入れるべき項目と、入れない方がよい項目を分けられます。
「禁止」と書くだけでは止まらない操作を、どの設定やレビューへ移すべきか判断できます。
Codex、Claude Code、Cursor、Copilotを同じリポジトリで使う時の配置を整理できます。
変更種別ごとのテスト手順と、未実行時の報告方法を書けます。
AGENTS.md導入後に、競合やinstruction driftをレビューで見つけやすくなります。
テンプレートそのものより、自分のリポジトリに合わせて削れることが重要です。
- チーム向けAGENTS.mdに最初から入れるべき項目と、入れない方がよい項目
- 「禁止」と書くだけでは止まらない操作を、どの設定やレビューへ移すべきか
- Codex、Claude Code、Cursor、Copilotを同じリポジトリで使う時のファイル配置
- テスト手順と未実行理由をエージェント向けに書く方法
- AGENTS.md導入後に、変更レビューで見るべき競合とdrift
すでにAGENTS.mdを置いているチームは、導入後の見直しとしてAGENTS.md変更レビューの記事も合わせて読むと、この記事のテンプレートをレビュー運用へつなげやすくなります。
前提知識
AGENTS.mdは合意を伝える場所で、接続権限や秘密情報へのアクセスを自動で消す場所ではありません。
AGENTS.mdはREADMEではなく、エージェント向けの作業メモ
AGENTS.md open formatは、AI coding agentにプロジェクトの文脈や作業手順を渡すためのMarkdownファイルとして説明されています。READMEは人間向けの概要や導入手順を置く場所、AGENTS.mdはエージェントが作業前に知るべきビルド手順、テスト、規約、注意点を置く場所、と分けると扱いやすくなります。
ここで大事なのは、AGENTS.mdが「自然文の指示」であることです。たとえば「本番DBを変更しない」と書くのは必要ですが、それだけで本番DBへの接続権限が消えるわけではありません。AGENTS.mdは、作業前に読ませる合意です。実行を止めるには、権限、ネットワーク、秘密情報、CI、レビューの仕組みが別に必要です。
Codex、Claude Code、Cursorで読み込み方が違う
OpenAI Codexの公式ガイドでは、Codexが作業前にAGENTS.mdを読み、グローバル、プロジェクト、作業ディレクトリに近いファイルを順に組み合わせることが説明されています。近い階層の指示ほど後に入り、実務上はより具体的な指示として扱われます。
Claude CodeはAGENTS.mdではなくCLAUDE.mdを読む、と公式Docsに明記されています。ただし、既存のAGENTS.mdを共通ソースにするため、CLAUDE.mdから@AGENTS.mdでimportする方法が示されています。つまり、AGENTS.mdをチーム共通の作業前提、CLAUDE.mdをClaude固有の補足にできます。
Cursorは、Project Rules、User Rules、AGENTS.mdなどのrules系機能を持ちます。Project Rulesは.cursor/rulesに置き、パスや用途に応じた細かいスコープに向きます。一方で、AGENTS.mdはシンプルな共通指示に向きます。
権限の話は、指示ファイルだけで終わらせない
Codexの安全運用ドキュメントでは、sandbox modeとapproval policyが別の層として説明されています。Claude Codeのsettingsでも、allow、ask、deny、sandbox filesystem、network制限などが別に扱われます。
したがって、AGENTS.mdの設計では次の線引きを最初に決めます。
| 分類 | AGENTS.mdに書くこと | 強制する場所 |
|---|---|---|
| 作業前提 | package manager、ディレクトリ構成、レビュー観点 | AGENTS.md、CLAUDE.md、Cursor Rules |
| 実行権限 | どの操作は承認が必要か | Codex permissions、Claude Code settings、OS sandbox |
| 秘密情報 | 読まないファイル、使わない値 | .gitignore、deny rules、secret manager、CI secrets |
| 品質確認 | 変更種別ごとのテスト | CI、pre-commit、PR template |
| 本番操作 | 原則任せない、人間承認が必要 | IAM、環境分離、手動承認、監査ログ |
AGENTS.mdを強く書くことは必要です。ただし、止めたい操作ほど自然文から設定へ移します。
結果: 最初のAGENTS.mdは7項目でよい
プロダクトの種類、主要ユーザー、壊してはいけない領域を書きます。
触ってよいpackage、app、生成物、迷うファイルの扱いを決めます。
通常の開発タスクで必要な読み取り、編集、テスト実行を小さく書きます。
秘密情報、本番操作、破壊的操作、未承認の外部送信を避ける方針を書きます。
変更種別ごとの最低限の確認と、未実行時の報告方法を書きます。
小さく、説明でき、失敗を隠さない変更に寄せます。
変更内容、テスト結果、残リスク、必要な次の確認をそろえます。
毎回読むべき内容に絞るほど、レビューでも運用でも使いやすくなります。
1. プロジェクト概要
エージェントは、リポジトリ名だけでは何を守るべきか判断できません。最初に、プロダクトの種類、主要ユーザー、壊してはいけない領域を書きます。
# AGENTS.md
### Project Overview
- This repository is a TypeScript web application for internal operations.
- Prioritize correctness and auditability over fast rewrites.
- Do not change authentication, billing, or production data flows without human approval.日本語チームなら日本語で構いません。英語で書く必要はありませんが、ツールやコマンド名は実際の表記に合わせます。
2. 作業範囲
「どこを触ってよいか」は、エージェントにとってかなり重要です。モノレポでは特に、変更対象のpackageやappを指定しないと、隣のチームのコードに修正が広がります。
### Working Scope
- Primary app: `apps/admin`
- Shared UI: `packages/ui`
- Do not edit generated files under `dist/`, `build/`, `.next/`, or `coverage/`.
- If a change appears to require another package, explain why before editing it.生成物の扱い、schema生成ファイル、lockfile、migration fileはチームごとに判断が分かれます。迷うファイルほど、AGENTS.mdで「先に説明する」「人間確認を取る」と書いておく方がレビューしやすくなります。
3. 許可操作
許可操作は、広く書くより、よく使う操作を小さく書く方が効きます。
### Allowed Work
- Read source files, tests, docs, and configuration needed for the assigned task.
- Edit application code and tests inside the working scope.
- Add tests when changing behavior.
- Run local validation commands listed in this file.「必要なら何でもやってよい」と書くと、レビュー時に作業境界を説明できません。許可操作は、通常の開発タスクで本当に必要なものから始めます。
4. 禁止操作
禁止操作は、コピペ事故を避けるために、危険な実コマンドを長く列挙しすぎない方がよいです。代わりに、操作の種類と代替手順を書きます。
### Prohibited Work
- Do not read `.env`, `.env.*`, secret files, private keys, or credential stores.
- Do not modify production infrastructure, production databases, billing settings, or access control settings.
- Do not run destructive cleanup commands. If cleanup is needed, propose the exact target files first.
- Do not add new runtime dependencies without explaining why an existing dependency is insufficient.
- Do not send repository code, logs, or customer data to external services unless the task explicitly allows it.「禁止」だけだと止まりません。Codexならsandbox/approval、Claude Codeならpermissions denyやsandbox filesystem/network、CIならsecretsやenvironment protectionで止める必要があります。詳しくはCodexのpermissionsとrulesを分ける記事が近いです。
5. テスト手順
テスト手順は、単にnpm testと書くだけでは足りません。変更種別ごとに、最低限の確認とfull確認を分けます。
### Validation
- After TypeScript changes, run `npm run typecheck`.
- After UI logic changes, run `npm test -- --runInBand` or the closest package-level test.
- After formatting-sensitive changes, run `npm run lint`.
- If a command cannot be run, report the reason, the command you intended to run, and the risk left unverified.ここで重要なのは、未実行時の報告です。AIエージェントに任せると、テストを実行できなかった時に「未確認」の粒度が粗くなりがちです。AGENTS.mdに報告フォーマットを置くと、レビューする人が残リスクを見つけやすくなります。
6. レビュー基準
エージェントの作業は、PRでレビューできる形に寄せます。レビュー基準は、品質だけでなく説明責任のために書きます。
### Review Expectations
- Keep changes small and focused on the requested task.
- Explain behavior changes, test coverage, and known remaining risks.
- Mention files or areas intentionally not changed.
- Do not hide failing checks. Summarize the failure and next action.「よいコードを書く」では曖昧です。小さく、説明でき、失敗を隠さない、というレビュー可能な条件に落とします。
7. 報告フォーマット
最後に、作業完了時の報告フォーマットを決めます。これはPR説明にも、チャットでの作業報告にも使えます。
### Final Response Format
- Summary: what changed and why.
- Tests: commands run and results.
- Risks: what was not verified or needs human review.
- Follow-up: optional next steps, only when useful.この程度で十分です。長くしすぎると、毎回の報告が冗長になり、重要な失敗が埋もれます。
権限、禁止操作、人間承認の書き方
セキュリティや本番操作は単純な勝敗ではなく、チームのリスクに合わせて境界を決めます。
「お願い」と「強制」を分ける
確認項目
AGENTS.mdに「秘密情報を読まない」と書くのはよい出発点です。ただし、秘密情報を本当に読ませたくないなら、読み取り権限を閉じる、deny ruleに入れる、.envをgit管理外に置く、CI secretsをPRから読めないようにする、といった設定が必要です。
同じ考え方で、外部通信、本番操作、課金、アクセス権限変更も分けます。
| 操作 | AGENTS.mdの書き方 | 追加で必要な制御 |
|---|---|---|
.envの読み取り | 読まない。必要な値はダミー名で説明する | deny rule、secret manager、git管理外 |
| 外部API呼び出し | 明示許可がある時だけ使う | network allowlist、mock、dry-run |
| 依存関係追加 | 代替案と理由を説明してから行う | package review、lockfile review |
| DB migration | expand/contract、rollback、backfill計画を書く | staging適用、review、backup |
| 本番操作 | 原則として任せない | IAM、環境分離、手動承認 |
人間承認が必要な境界を先に書く
判断基準
「必要なら確認してください」では、確認すべきタイミングが曖昧です。AGENTS.mdでは、承認が必要な境界を具体的に書きます。
### Human Approval Required
Ask for human approval before:
- Changing authentication, authorization, billing, or data retention behavior.
- Adding a new runtime dependency or external service.
- Modifying database schema or migration files.
- Changing CI/CD, deployment, infrastructure, or secret management.
- Performing any operation that may delete user data or production data.このリストは、チームのリスクに合わせて削って構いません。個人開発ならbillingや本番DBがないこともあります。逆に法人や受託では、認証、個人情報、監査ログ、契約上の保存期間まで広げた方がよいです。
代替手順まで書く
禁止事項だけを書くと、エージェントは作業を止めるしかありません。代替手順もセットで書きます。
### If Blocked
- If a task requires secrets, ask for a redacted sample or mock response.
- If a task requires production data, request an anonymized fixture.
- If a validation command fails due to missing local services, report the command and the missing service.
- If you are unsure whether a file is safe to edit, summarize the reason before changing it.これで、危険な操作を避けながらも作業が前に進みます。
テスト手順をエージェント向けに書く
未実行時は、理由、代わりに確認したこと、残リスク、次に走らせる確認を残します。
変更種別ごとにコマンドを分ける
確認項目
エージェントにテストを任せるなら、コマンドの一覧ではなく「どの変更で何を走らせるか」を書きます。
| 変更種別 | 最低限の確認 | 追加確認 |
|---|---|---|
| UI component | lint、unit test | visual regression、Playwright |
| API handler | typecheck、unit test | integration test、mocked external API |
| DB migration | migration lint、schema diff | staging apply、rollback plan |
| config | config validation | CI dry-run |
| documentation | link check | sample command check |
| dependency update | lockfile diff、test | changelog確認、security advisory確認 |
この表は、そのままテンプレートに貼るより、リポジトリの実コマンドへ置き換えて使います。たとえばpnpm workspaceならpnpm --filter <package> test、npm scripts中心ならnpm run test --workspace <name>のように、実際に使う形にします。
未実行をレビュー可能にする
報告基準
テストが走らなかった時の報告ルールは、最初から書いておきます。
### Test Reporting
When validation is incomplete, report:
- Command not run:
- Reason:
- What was checked instead:
- Remaining risk:
- Suggested next check:これを入れておくと、「テスト未実行です」だけで終わる報告を減らせます。レビュー担当者は、残リスクが環境依存なのか、時間切れなのか、実装上の不具合なのかを判断できます。
CIを正にする
AGENTS.mdのテスト手順は、人間とエージェントの作業をそろえるための説明です。最終的な品質ゲートはCIに寄せます。
たとえば、AGENTS.mdに「型チェックを実行する」と書くだけでなく、PRで型チェックが必ず走るようにします。AGENTS.mdに「生成ファイルを編集しない」と書くだけでなく、生成差分やformat checkをCIで検出できると強いです。
AGENTS.mdは、CIで何が落ちるのかを先に知らせるファイル。CIは、それを実際に止める仕組み。この分担ができていると、エージェントに任せる範囲を広げてもレビューしやすくなります。
Codex、Claude Code、Cursorで置き場所をそろえる
- 1AGENTS.md
チーム共通の作業前提、安全ルール、テスト、報告フォーマットを置きます。
- 2CLAUDE.md
@AGENTS.mdで共通ルールを読み、Claude固有のplan mode、permissions、hooksだけを足します。
- 3.cursor/rules/*
Cursor固有、パス固有、Agent Requestedの細かいルールを分けます。
- 4.github/copilot-instructions.md
Copilotのrepository-wide instructionsとして、補足的な共通文脈を置きます。
- 5CIとレビュー
AGENTS.mdに書いた品質確認を、実際に落ちるチェックとPRレビューへつなげます。
rootのAGENTS.mdを短く保ち、必要な時だけ下位ディレクトリやツール固有ファイルへ足します。
CodexはAGENTS.mdを中心にする
根拠
Codexでは、AGENTS.mdを共通の入口にします。公式ガイドでは、Codex home側のグローバル指示、プロジェクトrootから作業ディレクトリまでのプロジェクト指示、近い階層の指示が後に入る読み込み順が説明されています。
おすすめは、rootのAGENTS.mdを短く保ち、必要な時だけ下位ディレクトリに追加AGENTS.mdを置く形です。
repo/
AGENTS.md
apps/
admin/
AGENTS.md
packages/
ui/
AGENTS.mdrootには共通の安全ルール、apps/admin/AGENTS.mdにはadmin固有のテスト、packages/ui/AGENTS.mdにはUI componentの規約を書く、と分けます。下位ファイルに全ルールをコピーしないのがポイントです。
Claude CodeはCLAUDE.mdからAGENTS.mdをimportする
Claude Codeの公式Docsでは、Claude CodeはCLAUDE.mdを読むので、AGENTS.mdを使うリポジトリではCLAUDE.mdからimportする方法が示されています。
@AGENTS.md
### Claude Code
- Use plan mode before changing authentication or billing logic.
- Follow project permissions in `.claude/settings.json`.
- Prefer path-scoped rules for large, directory-specific guidance.この形なら、共通ルールはAGENTS.mdに残し、Claude固有のplan mode、permissions、hooks、auto memoryの扱いだけCLAUDE.mdに足せます。symlinkでもできますが、Claude固有の補足を足したい場合はimportの方が扱いやすいです。
Claude Codeでは、CLAUDE.mdはcontextであり、強制設定ではないと公式Docsに書かれています。アクションを止めるにはPreToolUse hookやpermissionsを使う、という分担を崩さない方が安全です。
CursorはAGENTS.mdとProject Rulesを使い分ける
条件
CursorのRules docsでは、Project Rulesは.cursor/rulesに置くversion-controlledなルールとして説明されています。AGENTS.mdは、よりシンプルな共通指示として使えます。
実務では、AGENTS.mdには全エージェント共通の最小ルールを置き、Cursor固有の細かいルールは.cursor/rulesへ逃がします。
repo/
AGENTS.md
.cursor/
rules/
frontend.mdc
api.mdc
review.mdcたとえばReact componentの作り方、特定ディレクトリのUI規約、review agentへの期待値などは、Project Rulesの方が向いています。AGENTS.mdに全部書くと、CodexやClaude Codeにも不要なCursor固有文脈を読ませることになります。
Copilotは補足として扱う
GitHub Copilotも同じリポジトリで使うなら、.github/copilot-instructions.mdや.github/instructions/*.instructions.mdがあります。GitHub Docsでは、repository-wide instructionsとpath-specific instructionsが説明されています。
ただし、この記事の主役はAGENTS.md、Codex、Claude Code、Cursorです。Copilotまで完全に同一化しようとすると、全ツールの差分を1ファイルに詰め込みすぎます。Copilotを併用する場合は、AGENTS.mdを共通ソースにしつつ、Copilot固有の適用範囲はCopilot custom instructionsの記事へ分けて考えるのが現実的です。
競合したルールをレビューで見つける
AGENTS.md、CLAUDE.md、CIでnpm、pnpm、npm ciなどがずれていないか見ます。
AGENTS.mdの確認手順とCIで実際に走るチェックがずれていないか見ます。
下位ディレクトリで生成物の編集方針が逆になっていないか確認します。
依存追加禁止と、必要なら追加してよいという指示が同時に存在しないか見ます。
本番操作、認証、課金、権限、本番データの承認者が書かれているか確認します。
CI、package manager、workspace構成、権限モデルが変わった時に古い指示を直します。
AGENTS.mdは置いた瞬間から少しずつ古くなるため、運用変更のたびに見直します。
package managerの不一致を見る
確認項目
AGENTS.mdにnpm install、CLAUDE.mdにpnpm install、CIにnpm ciがあると、エージェントはどれを使うべきかわかりません。結果としてlockfileが壊れたり、不要な差分が出たりします。
レビューでは、次のような不一致を見ます。
- package managerがファイルごとに違う
- テストコマンドがCIと違う
- 生成物の扱いが下位ディレクトリで逆になっている
- 「依存追加禁止」と「必要なら追加してよい」が同時に存在する
- 本番操作の承認者が書かれていない
権限を広げる変更は理由を見る
注意点
AGENTS.mdの変更で見落としやすいのは、文章が増えた時ではなく、境界が広がった時です。
たとえば、「外部APIは使わない」から「必要なら外部APIを使ってよい」に変わるなら、どのAPIか、どのデータを送るのか、誰が承認するのかを説明する必要があります。CodexのネットワークアクセスやMCP連携まで含めて考える場合は、ネットワークallowlistの記事も参考になります。
instruction driftを定期的に直す
AGENTS.mdは、置いた瞬間から少しずつ古くなります。CIが変わる、package managerが変わる、monorepoが分割される、外部APIが増える、権限モデルが変わる。こうした変化があるたびに、古い正解が残ります。
見直しのタイミングは、次の4つで十分です。
- CIやtest commandを変えた時
- package managerやworkspace構成を変えた時
- 認証、課金、権限、本番データの扱いを変えた時
- AIエージェントが同じ失敗を2回以上繰り返した時
AGENTS.mdは、ドキュメントとして完成させるものではなく、運用と一緒に小さく直すものです。
導入初日の配置パターン
- 11人開発
rootにAGENTS.mdだけ置き、禁止操作、テスト、未実行報告から始めます。
- 2複数ツール併用
AGENTS.mdを共通ソースにし、CLAUDE.mdや.cursor/rulesへツール固有の差分だけを足します。
- 3Copilot補足
.github/copilot-instructions.mdにはrepository-wide instructionsを置きます。
- 4法人や受託
.claude/settings.json、.cursor/rules、CI workflow、CODEOWNERS、PR templateも同じPRで見ます。
- 5レビュー対象
共通ルール、ツール固有設定、CI、権限、承認者のずれをまとめて確認します。
同じ禁止事項を4か所へ手でコピーすると、必ずずれます。
1人開発ならAGENTS.mdだけで始める
個人開発や検証段階なら、rootにAGENTS.mdだけ置く形で十分です。
repo/
AGENTS.mdこの段階では、禁止操作、テスト、未実行報告だけ入れます。CLAUDE.mdやCursor rulesまで最初から増やすと、どこを正とするかが曖昧になります。
複数ツール併用なら共通ソースとアダプタを分ける
Codex、Claude Code、Cursorを同じリポジトリで使うなら、次の配置が扱いやすいです。
repo/
AGENTS.md
CLAUDE.md
.cursor/
rules/
frontend.mdc
api.mdc
.github/
copilot-instructions.md責務は次のように分けます。
| ファイル | 役割 |
|---|---|
AGENTS.md | チーム共通の作業前提、安全ルール、テスト、報告 |
CLAUDE.md | @AGENTS.mdをimportし、Claude固有の運用だけ追加 |
.cursor/rules/* | Cursor固有、パス固有、Agent Requestedの細かいルール |
.github/copilot-instructions.md | Copilotのrepository-wide instructions |
同じ禁止事項を4か所へ手でコピーすると、必ずずれます。共通ルールはAGENTS.mdに置き、ツール固有ファイルでは「AGENTS.mdを読む」「このツールだけの差分」を書く設計にします。
法人や受託なら設定ファイルもレビュー対象にする
チームや法人導入では、AGENTS.mdだけをレビューしても足りません。次のファイルを同じPRで見るようにします。
AGENTS.mdCLAUDE.md.claude/settings.json.cursor/rules/*.github/copilot-instructions.md- CI workflow
- CODEOWNERS
- PR template
AGENTS.mdが「本番操作は禁止」と書いているのに、CIやIAMが本番操作を許しているなら、実際には止まりません。逆に、settings側で強くdenyしているのにAGENTS.mdが「必要なら実行」と書いていると、エージェントは失敗を繰り返します。
失敗点: AGENTS.mdに書けば安全、という誤解
長すぎる指示、矛盾した指示、古い指示が混ざるほど守られにくくなります。
プロダクトの歴史、全ディレクトリの説明、全npm scriptsの一覧を詰めると重要事項が埋もれます。
「読まない」と書くことと、ファイル権限やdeny rulesで実際に読めない状態にすることは別です。
長い背景、runbook、ADR、障害対応手順は、AGENTS.mdではなく別ドキュメントへ逃がします。
外部送信や本番操作は、AGENTS.mdだけでなくallowlist、approval、IAM、監査ログで扱います。
AGENTS.mdは作業前の合意であり、強制設定や品質ゲートの代わりにはなりません。
自然文は万能ではない
AIエージェントは、AGENTS.mdを読んでも必ず完全に従うとは限りません。長すぎる指示、矛盾した指示、古い指示、タスクと関係の薄い指示が混ざるほど、守られにくくなります。
GitHub Copilotの公式Docsでも、custom instructionsは非決定的なAIの性質上、常に同じように従われるとは限らないと説明されています。Claude CodeのDocsでも、CLAUDE.mdはcontextであり、アクションを止めるにはhookなどを使う、と整理されています。
つまり、AGENTS.mdは安全の始まりです。安全の完成ではありません。
長すぎるテンプレートは逆効果になる
よくある失敗は、最初から全部入れることです。
- プロダクトの歴史
- 全ディレクトリの説明
- 全npm scriptsの一覧
- 過去の障害対応メモ
- 例外の例外
- ツールごとの細かいtips
これらをAGENTS.mdに詰めると、毎回読むべき重要事項が埋もれます。AGENTS.mdには、毎回必要な判断基準を置きます。長い背景、詳細なrunbook、設計ADR、障害対応手順はリンク先に分けます。
「禁止」と「できない」を混同する
AGENTS.mdに「秘密情報を読まない」と書くのは、エージェントへの指示です。実際に読めない状態にするには、ファイル権限やdeny rulesが必要です。
AGENTS.mdに「ネットワークを使わない」と書くのは、作業方針です。実際に外部通信を止めるには、sandboxやnetwork設定が必要です。
AGENTS.mdに「本番操作をしない」と書くのは、レビューの基準です。実際に本番操作を止めるには、IAM、環境分離、手動承認、監査ログが必要です。
この分離をチームで共有しておくと、AGENTS.mdを過信しなくなります。
実務で使うなら
- AGENTS.mdだけのPR
導入初日のPRでは、AGENTS.mdの追加だけにして変更の効き方を見ます。
- 小さなタスクで試す
Codexに読ませて、テスト報告と禁止事項への反応を確認します。
- ツール固有ファイルを足す
Claude CodeはCLAUDE.mdからimportし、Cursor固有のルールは.cursor/rulesへ分けます。
- 危険操作を設定へ移す
settings、sandbox、CI、reviewへ、秘密情報、本番操作、外部通信の制御を寄せます。
- オーナーを決める
default reviewer、セキュリティ関連項目の承認者、テスト手順の承認者、棚卸し日を決めます。
テンプレートは貼って終わりではなく、リポジトリに合わせて削って育てます。
最初のPRは「テンプレート追加」だけにする
導入順序
導入初日のPRでは、AGENTS.mdの追加だけにします。permissions、CI、Cursor rules、CLAUDE.mdを同時に大きく変えると、どの変更が効いたのか分かりません。
おすすめの順番は次です。
- rootにAGENTS.mdを追加する
- 小さなタスクでCodexに読ませて、テスト報告と禁止事項の反応を見る
- Claude Codeを使うならCLAUDE.mdから
@AGENTS.mdをimportする - Cursor固有のルールだけ
.cursor/rulesへ分ける - 危険操作をsettings、sandbox、CI、reviewへ移す
AGENTS.mdのオーナーを決める
AGENTS.mdは、誰でも編集できるようで、誰も責任を持たないファイルになりがちです。少なくとも次のどれかは決めます。
- default reviewer
- セキュリティ関連項目の承認者
- テスト手順の承認者
- 例外を追加できる条件
- 半年ごとの棚卸し日
小規模チームなら、CODEOWNERSでAGENTS.mdだけownerを置くだけでも効きます。
テンプレートは自分のリポジトリに合わせて削る
この記事のテンプレートをそのまま貼る必要はありません。むしろ、使わない項目は消した方がよいです。
たとえばDBを持たないフロントエンドだけのリポジトリなら、DB migrationの承認ルールは不要です。外部APIを使わないなら、外部通信の項目は短くできます。個人開発なら承認者名ではなく「実行前にチャットで確認」と書くだけで足ります。
重要なのは、チームが実際に守れる短さです。
セキュリティ・コスト注意
実APIキー、社内URL、非公開リポジトリ名、顧客名、個人情報はAGENTS.mdにも記事にも書きません。
必要な値はEXAMPLE_API_KEYのようなplaceholderやmocked responseで説明します。
外部API、MCP server、Web search、package registryを使う条件を書き、allowlistやapprovalを使います。
tool allowlistを置き、ログに秘密情報を残さない前提で始めます。
料金、利用上限、モデル名は変わるため、AGENTS.mdに固定しすぎないようにします。
高コストな長時間タスクは事前確認する、という運用ルールに留めるとdriftしにくくなります。
APIキーと秘密情報は記事にもAGENTS.mdにも書かない
注意点
AGENTS.mdに実APIキー、社内URL、非公開リポジトリ名、顧客名、個人情報を入れてはいけません。エージェントが読む前提のファイルなので、広く共有される可能性があります。
必要なら、次のようにダミー値で書きます。
- Use `EXAMPLE_API_KEY` as a placeholder in docs and tests.
- Never paste real API keys, customer data, or private repository URLs into prompts.
- Use mocked responses under `tests/fixtures/` when external data is needed.外部通信はコストと漏えいの両方を見る
AIエージェントが外部API、MCP server、Web search、package registryにアクセスできると、便利になる一方で、コストとデータ送信のリスクが増えます。
AGENTS.mdには「外部通信を使う条件」を書き、実行環境ではallowlistやapprovalを使います。MCPを使う場合は、read-onlyから始める、tool allowlistを置く、ログに秘密情報を残さない、という基本も同じです。
料金プランやモデル名はAGENTS.mdに固定しすぎない
料金、利用上限、モデル名は変わります。AGENTS.mdに「必ずこのモデルを使う」「このプランなら無制限」といった古くなりやすい前提を書くと、すぐdriftします。
モデルや料金の判断は、運用ドキュメントや定期更新記事へ分けるのが無難です。必要なら「高コストな長時間タスクは事前確認する」くらいの運用ルールに留めます。
次に読むなら
AIコーディングエージェントの運用ルールや検証記事の更新は、ニュースレターでも案内しています。チーム導入、権限設計、AGENTS.mdやMCP設定のレビュー相談は、お問い合わせからどうぞ。
更新履歴
- 2026-06-05
OpenAI Codex、Claude Code、Cursor、GitHub Copilot、AGENTS.md open formatの公式情報を確認し、初版を作成しました。
仕様や料金、モデル名は変わるため、確認日を残しておくと見直しやすくなります。
- 2026-06-05: OpenAI CodexのAGENTS.md guide、agent approvals and security、Claude Codeのmemory/settings、Cursor Rules、GitHub Copilot response customization、AGENTS.md open formatを確認し、初版を作成しました。
参照した主な情報源
- https://developers.openai.com/codex/guides/agents-md
- https://developers.openai.com/codex/agent-approvals-security
- https://docs.claude.com/en/docs/claude-code/memory
- https://docs.claude.com/en/docs/claude-code/settings
- https://cursor.com/docs/rules
- https://docs.github.com/en/copilot/concepts/prompting/response-customization
- https://agents.md/