3行まとめ
コード、CI、権限、hooks、人間承認と合っているかを見る。
昔は正しかった手順や境界が、現在の実態とずれていないかを見る。
禁止事項を自然文だけで終わらせず、sandbox、permissions、hooks、CIへ移す。
AGENTS.mdの変更は、文章のきれいさよりも運用と実行環境との整合で判断します。
- AGENTS.mdやCLAUDE.mdの変更レビューは、文章のきれいさを見る作業ではなく、今のコード、CI、権限、hooks、人間承認と合っているかを見る運用レビューです。
- instruction driftは、昔は正しかったテスト手順、禁止事項、担当範囲、作業境界が、その後の依存更新やmonorepo分割、権限変更で古くなることで起きます。
- 危険操作を止めたいなら、AGENTS.mdに「禁止」と書くだけで終わらせず、Codexのsandbox/approval、Claude Codeのpermissionsやhooks、CI、CODEOWNERS、人間レビューへ移します。
この記事では、2026年6月2日にOpenAI Codex、Claude Code、GitHub Copilot、AGENTS.mdの公式情報を確認しました。X上のAIエージェント運用やproject memoryへの関心は需要シグナルとしてだけ扱い、仕様説明の根拠にはしていません。
この記事でわかること
AGENTS.md、CLAUDE.md、Copilot custom instructionsをPRレビュー対象に入れる。
drift、conflict、enforcement gap、test freshnessを分けて指摘する。
指示として書くことと、権限やhooksで強制することを分ける。
古いコマンド、古いpackage名、CIで走っていない検査を見つける。
変更後のAGENTS.mdを小さなタスクで確認する。
レビューコメントを分類しておくと、何を直すべきかが具体的になります。
- AGENTS.md、CLAUDE.md、Copilot custom instructionsをPRレビュー対象に入れる時の確認順序
- instruction drift、conflict、enforcement gap、test freshnessを分けて指摘する方法
- 「指示として書くこと」と「権限やhooksで強制すること」の分け方
- 古いテストコマンド、古いpackage名、CIで走っていない検査を見つける観点
- 変更後のAGENTS.mdを小さなタスクで確認する手順
初回のひな形作成から始めたい場合は、先に公開済みのチーム向けAGENTS.mdテンプレートを読むと入りやすいです。この記事は、そのテンプレートを作った後に、変更差分をどうレビューするかへ絞ります。
前提知識
- 1AGENTS.md / CLAUDE.md
作業方針、テスト選択、報告形式を伝える。
- 2sandbox / permissions
読ませないpathや承認が必要な操作を設定する。
- 3hooks / CI
特定の操作や検査を実行時に確認する。
- 4人間レビュー
未実行報告、危険操作、承認者をPRの流れで確認する。
自然文のinstructionと実行環境の設定を同じレビュー対象として扱います。
AGENTS.mdは「実行されるルール」ではなく「読ませる文脈」から始まる
AGENTS.mdやCLAUDE.mdは、エージェントにリポジトリの作業方針を伝えるためのファイルです。便利ですが、そこに自然文で「本番へ書き込まない」「secretを読まない」「pushしない」と書くだけで、実際の操作が必ず止まるわけではありません。
公式情報を見ると、この境界はかなりはっきりしています。OpenAI CodexのAGENTS.md guideは、Codexがグローバルスコープとプロジェクトスコープのinstruction chainを作ること、プロジェクト内ではルートから現在の作業ディレクトリへ向かってファイルを結合することを説明しています。一方で、実際にどこまで編集できるか、ネットワークを使えるか、承認が必要かは、Codexのsandboxやapproval policyの問題です。
Claude Codeも同じです。Claude Codeのmemory docsは、CLAUDE.mdが行動を形作る文脈であり、特定のtoolやpathをブロックしたい場合はmanaged settingsのpermissions.deny、sandbox、PreToolUse hookなどを使う考え方を示しています。GitHub Copilotも、repository-wide custom instructions、path-specific instructions、agent instructionsを分けていますが、agent instructionsはすべてのCopilot機能で同じように使えるとは限りません。
レビューで見ること
この段階では、ファイル名や書き方の好みよりも、自然文のinstructionと強制設定の役割分担を見ます。禁止事項、承認が必要な操作、実行コマンド、未実行時の報告形式が、どのレイヤーで担保されているかを確認します。
だから、レビューで見るべきなのは「AGENTS.mdの文章がよくなったか」だけではありません。書いた内容が、実際の権限、CI、hooks、作業ディレクトリ、PRレビューの流れと合っているかを見る必要があります。
instruction driftをこの記事ではこう定義する
この記事ではinstruction driftを、昔は正しかった指示が、現在のコード、設定、CI、権限、チーム運用と合わなくなった状態と呼びます。
たとえば、次のような差分です。
| driftの種類 | 例 | レビューで見ること |
|---|---|---|
| テスト手順のdrift | npm testと書かれているが、現在はpnpm test --filter webがCIで使われている | package scripts、CI workflow、READMEの整合 |
| 作業境界のdrift | ルートAGENTS.mdに全サービス共通の手順が残り、paymentsだけ別のMakefileを使っている | nested AGENTS.md、override、対象ディレクトリ |
| 権限前提のdrift | 「外部APIを叩いて確認」と書いたが、実行環境ではnetwork accessが閉じている | sandbox、approval、MCP/tool権限 |
| レビュー責任のdrift | 以前の担当チーム名やSlack channelが残っている | CODEOWNERS、通知先、承認者 |
AGENTS.mdのdriftは、古いドキュメントの問題に見えますが、実際にはエージェントが次の作業で間違ったテストを選び、危険な操作を試し、未検証を検証済みのように報告する原因になります。小さな文言差分でも、レビューでは運用影響まで見るべきです。
結果：AGENTS.mdの変更レビューは4分類で見る
古いコマンド、優先関係、permissions、CI対応を別々に確認します。
AGENTS.mdや周辺instructionをレビューする時は、差分を次の4分類に分けると迷いにくくなります。
| 分類 | 問い | 典型的な修正 |
|---|---|---|
| drift | 今のコード、CI、チーム運用と合っているか | 古いコマンドや担当者を更新する |
| conflict | ほかのinstructionや設定と矛盾していないか | ルートとサブディレクトリの優先関係を明記する |
| enforcement gap | 本当に止めたい操作が自然文だけになっていないか | permissions、sandbox、hooks、CIへ移す |
| test freshness | テスト手順が実行可能かつ意味を保っているか | 対象範囲、未実行時の報告、CI対応を更新する |
この4分類にしておくと、レビューコメントも具体的になります。
drift:
AGENTS.mdでは npm test を必須にしていますが、現在のCIは pnpm test --filter api を実行しています。
この手順だとagentが対象packageを見ない可能性があるので、CIと同じコマンドへ更新してください。
conflict:
ルートAGENTS.mdでは network accessを使わない方針ですが、services/importer/AGENTS.override.mdでは外部API確認を前提にしています。
どちらが優先されるかと、承認が必要な操作かを追記してください。
enforcement gap:
「.envを読まない」と自然文で書くだけでは、権限設定としては弱いです。
Claude Codeで使う場合は permissions.deny、Codexで使う場合はsandbox/approval、CI側ではsecret露出検査を検討してください。
test freshness:
lintを必須と書いていますが、対象変更がdocsだけの場合の扱いがありません。
最小確認、full確認、未実行時の報告文言を分けてください。レビューの目的は、AGENTS.mdを長くすることではありません。次にエージェントへ作業を渡した時に、対象範囲を読み違えず、危険操作を避け、検証結果を人間がレビューできる形で残せる状態にすることです。
PR差分で最初に見るファイル
良さそうな文言でも、package scriptsやCIや権限とずれると良い運用につながりません。
instructionファイルだけを見ない
AGENTS.mdのPRを開いたら、まず差分に含まれているファイルを次のように並べます。
| 種類 | 例 | 見る理由 |
|---|---|---|
| エージェント向けinstruction | AGENTS.md, AGENTS.override.md, CLAUDE.md, GEMINI.md | エージェントに読ませる作業方針 |
| Copilot向けinstruction | .github/copilot-instructions.md, .github/instructions/*.instructions.md | repository-wideとpath-specificの違い |
| Claude Code設定 | .claude/settings.json, managed settings | permissions、sandbox、hookの有無 |
| 実行手順 | package.json, Makefile, pnpm-workspace.yaml, pyproject.toml | 書かれたコマンドが今も存在するか |
| CI | .github/workflows/*.ymlなど | エージェントの自己申告に頼らず検査できるか |
| レビュー責任 | CODEOWNERS, PR template, Issue form | 人間承認や未実行報告が残るか |
AGENTS.mdの差分だけを見ると、「テストを必ず実行する」といった良さそうな文言に見えます。しかし、package scriptsが変わっていたり、CIが別のpackageだけを見ていたり、権限設定でそのコマンドが実行できなかったりすると、良い文言が良い運用につながりません。
Codexでは読み込み階層を見る
CodexのAGENTS.md guideでは、Codexがグローバルスコープとプロジェクトスコープのinstructionを読み、プロジェクト内ではルートから現在ディレクトリへ向かってファイルを結合すると説明されています。近いディレクトリの内容は後から入るため、レビューでは「どの場所で作業を始めると、どのinstructionが効くか」を見る必要があります。
特にmonorepoでは、ルートAGENTS.mdに全体方針、サブディレクトリにサービス固有の手順を置くことがあります。このとき危ないのは、ルートに古い万能手順が残ることです。
repo/
AGENTS.md
apps/
web/
AGENTS.md
services/
payments/
AGENTS.override.md確認項目
この構成でpayments配下の作業をするなら、レビューでは次を確認します。
- ルートの禁止事項とpayments側の例外が矛盾していないか
- payments側のテストコマンドが、実際のMakefileやCIと合っているか
AGENTS.override.mdがある時に同じディレクトリのAGENTS.mdを読ませるつもりになっていないか- ルートに「全サービス共通」と書いた手順が、本当に全サービスに残っているか
Codexで設定、permissions、AGENTS.md、MCPの境界を整理するなら、AGENTS.mdの階層とconfigの責任を分けて見るとレビューしやすくなります。
GitHub Copilotではinstructionの種類を見る
GitHub Copilotの公式Docsは、repository-wide custom instructions、path-specific custom instructions、agent instructionsを分けています。repository-wideは.github/copilot-instructions.md、path-specificは.github/instructions配下、agent instructionsはAGENTS.md、CLAUDE.md、GEMINI.mdのようなファイルです。
ここでのレビュー観点は、どのCopilot機能でどのinstructionが効くかです。agent instructionsはrepository-wide instructionsに似ていますが、公式DocsはすべてのCopilot機能でサポートされるとは限らないと説明しています。つまり、Copilot Chat、coding agent、code review、IDE上の補助で同じように効く前提にしない方が安全です。
PRコメントでは、こう書くと実務的です。
このルールは全リクエストに効く前提で書かれていますが、Copilot側ではrepository-wide、path-specific、agent instructionsで適用範囲が違います。
対象がGitHub.comのcoding agentなのか、VS Codeでの補助なのか、PRレビューなのかを明記してください。instruction driftは古い正解が残ることで起きる
- 1以前の正解
npm test、npm run lint、毎回E2Eなどの手順が残る。
- 2実態の変化
pnpm移行、CI条件変更、nightly移行、monorepo分割が起きる。
- 3起きる問題
存在しないコマンド、CIと違う失敗条件、対象package漏れが起きる。
- 4レビューで更新
共通化できるものとディレクトリ別に分けるものを切り分ける。
昔は正しかった指示ほど、依存更新や構成変更のあとに残りやすくなります。
古いテストコマンドを見つける
AGENTS.mdの代表的な内容には、build and test commandsやtesting instructionsがあります。だからこそ、テスト手順のdriftは最も起きやすいです。
よくあるのは、次のようなズレです。
| AGENTS.mdに残った指示 | 現在の実態 | 起きる問題 |
|---|---|---|
npm testを実行 | repoはpnpmへ移行済み | agentが存在しないコマンドを試す |
npm run lintを実行 | CIではeslint . --max-warnings=0だけ | ローカルとCIの失敗条件が違う |
| E2Eは毎回実行 | E2Eはnightlyだけに移行 | agentが重い検査を選び、時間を浪費する |
| snapshot更新は任せてよい | snapshot更新はreviewer承認制 | 見た目の差分を隠すリスクがある |
make testで十分 | servicesごとにtargetが分かれた | 対象packageを見ない |
この確認は、エージェントに頼らず人間レビューで先にできます。package scripts、Makefile、CI workflow、README、直近のPR本文を見比べれば、古い手順はかなり見つかります。
古い作業境界を見つける
もう一つのdriftは、作業境界です。
最初は1つのWebアプリだったリポジトリが、API、worker、admin、shared packagesを含むmonorepoになることがあります。すると、ルートAGENTS.mdに書いた「全変更でこのテストを実行」「全ファイルでこの命名規則を使う」「全PRでこのownerへ確認」といった文言が、急に雑になります。
レビューでは、共通化できるものと、ディレクトリ別に分けるものを切り分けます。
| 共通化しやすい | 分けた方がよい |
|---|---|
| secretを読まない | packageごとのtest command |
| 未実行テストを報告する | deploy手順 |
| PR本文にSummary/Tests/Risksを書く | DB migration手順 |
| 本番操作は人間承認にする | E2Eの対象環境 |
| 生成ファイルの扱いを明記する | feature flagの操作手順 |
「全リポジトリで同じ手順」と書きたくなったら、そこは要注意です。共通ルールは短く、実行手順は近いディレクトリへ置く方が、driftに強くなります。
矛盾は近いファイル、後で読まれるファイル、強制設定の順に疑う
- 1instruction同士
ルートとサブディレクトリで違う手順が書かれていないかを見る。
- 2後で読まれる内容
作業ディレクトリに近いinstructionがどの内容を上書きするかを見る。
- 3強制設定
network access、permissions、sandboxと手順が合うかを見る。
- 4CIとレビュー責任
人間が何を信じればよいか、検査と承認の流れを見る。
文章だけ整えても、実行環境やCIと合わなければ矛盾は残ります。
自然文の矛盾だけを見ない
instructionの矛盾には、3つの層があります。
| 層 | 例 | レビューの問い |
|---|---|---|
| instruction同士の矛盾 | ルートではnpm test、サブディレクトリではmake test-payments | どちらが対象作業で使われるか |
| instructionと設定の矛盾 | AGENTS.mdは外部API確認を指示するが、network accessは閉じている | 実行できない手順を書いていないか |
| instructionとCIの矛盾 | AGENTS.mdはlint必須、CIはdocs変更でlintをskip | 人間が何を信じればよいか |
自然文の整合だけを取っても、実行環境と合わないと意味がありません。PRレビューでは、instruction、config、CI、レビュー責任を同じ表に置きます。
CLAUDE.mdはcontext、settingsは強制に近い
Claude Codeを使うチームでは、CLAUDE.mdが便利です。project memoryやrulesで、コードスタイル、データ取り扱い、品質基準、振る舞いの指示を共有できます。
ただし、Claude Codeの公式Docsは、settings rulesはクライアント側で強制される一方、CLAUDE.mdはClaudeの振る舞いを形作るものであり、hard enforcement layerではないと説明しています。ここがレビューで重要です。
たとえば、CLAUDE.mdにこう書くだけでは足りません。
Security:
- Never read .env files.
- Never run git push.
- Never call production APIs.レビューでは、次のように分けます。
| 目的 | CLAUDE.mdに書く | settings/hooks/CIで扱う |
|---|---|---|
| 行動方針 | secretを扱わない理由、代替手順 | permissions.denyやhookでpath/toolを止める |
| コード品質 | 命名、レビュー観点、報告形式 | lint、typecheck、test |
| 本番操作 | 人間承認が必要な理由 | approval、hook、環境分離 |
| 外部通信 | どのAPIを使うかの方針 | network制限、MCP serverのscope |
文章は迷いを減らします。設定やhookは、実行を止めます。チーム運用では両方が必要です。
Copilot custom instructionsでは適用範囲を見る
GitHub Copilotでレビューする場合は、instructionがどこへ効くのかを必ず確認します。repository-wide、path-specific、agent instructionsを混ぜると、「どの指示がいつ効くか」が曖昧になります。
特に、.github/copilot-instructions.mdに全体方針、.github/instructions/*.instructions.mdにpath-specific rule、AGENTS.mdにagent向け作業手順を置く構成では、重複が起きやすいです。レビューでは、同じルールを複数箇所に書くより、役割を分けます。
repository-wide:
全体の品質基準、PR報告形式、禁止事項
path-specific:
frontend、api、infraなど対象pathごとの実装規約
agent instructions:
agentが作業を始める前に読む手順、テスト、承認境界GitHub Copilotの指示ファイルの置き場所を整理したい場合は、copilot-instructions.md、.instructions.md、AGENTS.mdの置き場所も参考になります。
権限競合は同じ表で見る
権限の比較は単純な勝敗ではなく、操作ごとに条件差を見ます。
書いてあるのに実行できない差分
権限競合の1つ目は、AGENTS.mdに書かれた手順が、実行環境では許可されていないケースです。
たとえば、AGENTS.mdにこう書いたとします。
External API checks:
- After changing the import worker, call the staging API and verify that the sync result is correct.しかし、Codexの実行環境でnetwork accessが閉じている、Claude CodeのpermissionsでWebFetchがdenyされている、Copilot cloud agentの対象リポジトリ外のcontextへアクセスできない、という状態なら、この手順は実行できません。
権限マトリクスで見る
この差分は、AGENTS.mdだけでは見つかりません。レビューでは、操作ごとに表にします。
| 操作 | instruction | sandbox/permission | hook/CI | 判定 |
|---|---|---|---|---|
| staging API確認 | 必須と書いている | networkが閉じている | 代替CIなし | 修正必要 |
.env参照 | 禁止と書いている | deny設定なし | secret scanあり | deny追加を検討 |
git push | 人間承認後と書いている | ask設定あり | branch protectionあり | おおむねOK |
| migration dry run | 手順あり | DB接続なし | CIにdry runなし | 手順か環境を分ける |
「書いてあるのに実行できない」は、agentが迷う原因です。実行できないなら、代替手順、手動確認者、未実行時の報告文言を書きます。
実行できるが実行させたくない差分
反対に、実行できるが実行させたくない操作もあります。
.envやsecretファイルを読む- production APIへ書き込む
git push --forceを実行する- DB migrationを本番へ適用する
- 外部サービスへユーザーデータを送る
- 大量のファイル削除を自動で行う
この種類の操作は、AGENTS.mdに「禁止」と書くだけでは弱いです。Codexならsandboxとapproval policy、Claude Codeならpermissionsやhooks、GitHubならbranch protection、CODEOWNERS、required checks、環境secretの制限を使います。
レビューコメントは、こう書くと通りやすいです。
この差分では「productionへ書き込まない」とAGENTS.mdに追加していますが、実行を止める設定がありません。
自然文の注意だけだと、別のinstructionやユーザー依頼と競合した時に弱いです。
本番書き込みはhookまたはCI側の確認へ移し、AGENTS.mdには代替のdry-run手順を書いてください。AIエージェントのprompt injection対策でも同じ考え方が必要です。外部DocsやIssue、MCPを読ませるなら、prompt injection対策の記事で整理したように、読ませる範囲、toolの権限、人間承認を分ける必要があります。
hooksとCIはinstructionを検査へ変える場所
- 1自然文の指示
.envを読まない、git pushは承認後だけ、productionへ書かない。
- 2permissions
path、command pattern、URL、envでdenyやaskを検討する。
- 3hooks
エージェント実行の特定タイミングで検査や制御を入れる。
- 4CI
エージェントの自己申告に頼らず、検査結果をPRに残す。
hooksは万能ではありませんが、禁止や検査を自然文から実行時の確認へ移せます。
hooksへ移すべき指示
Claude Codeのhooks referenceやGitHub Copilot cloud agentのhooks説明を見ると、hooksはエージェント実行の特定タイミングで検査や制御を入れるための仕組みです。すべてをhooksにする必要はありませんが、「守れたらよい」ではなく「守らないと危ない」指示は、自然文から強制可能な検査へ移した方がよいです。
移す判断
hooksやpermissionsへ移しやすい指示は、次のようなものです。
| 自然文の指示 | 強制側へ移す理由 |
|---|---|
.envを読まない | pathでdenyしやすい |
git pushは承認後だけ | command patternでask/denyしやすい |
| generated fileを直接編集しない | pathやcommandで検査しやすい |
| productionへ書かない | command、URL、envで検査しやすい |
| planなしにmigrationしない | tool call前に承認を挟みやすい |
Codexのhooksを中心に考える場合は、Codex Hooksで止める前に決めることが近いテーマです。この記事では、AGENTS.mdのレビュー中に「これはhookへ移すべきでは」と判断する観点に絞ります。
CIへ移すべき指示
CIへ移すべきなのは、エージェントの自己申告だけでは信頼しにくい確認です。
- lintが通る
- typecheckが通る
- unit testが通る
- docs linkが切れていない
- forbidden literalやsecretが混ざっていない
- generated fileが正しく更新されている
- migrationがdry-runできる
AGENTS.mdには「最終報告で実行したテストと未実行テストを分けて書く」と指示します。ただし、merge判断はCIと人間レビューへ残します。エージェントの報告は重要ですが、報告だけで安全性を担保しようとすると失敗します。
文章を増やすより、失敗時の出し方を固定する
AGENTS.mdのレビューでよくある失敗は、注意書きを増やし続けることです。
- 必ずテストすること。
- 失敗したら直すこと。
- できれば理由を書くこと。
- 危ない操作はしないこと。これでは、agentもreviewerも判断しにくいです。代わりに、失敗時の出し方を固定します。
Final report:
When finishing a task, report:
- Summary: what changed
- Tests run: exact commands and result
- Tests not run: command, reason, and risk
- Risks: behavior that still needs human review
- Follow-up: items that should not be merged in this PRPR本文側の型と合わせるなら、AIエージェントPRテンプレートの作り方と同じ方向です。AGENTS.mdには、agentが何を報告するかを書き、PR templateにはreviewerが何を確認するかを置きます。
テスト手順の陳腐化は「走る」ではなく「守れている」で見る
テスト手順は、今の変更リスクに届いているかで判断します。
コマンドの存在確認だけでは足りない
npm testが成功するからといって、AGENTS.mdのテスト手順が正しいとは限りません。
見るべきなのは、テストが現在のリスクを守れているかです。
| 確認 | OKに近い状態 | 危ない状態 |
|---|---|---|
| 対象範囲 | 変更packageを見ている | ルートの軽いtestだけ通る |
| 失敗条件 | CIと同じ閾値 | ローカルだけwarning許容 |
| E2E | 実行条件と対象環境が明記 | 毎回必須だが誰も実行しない |
| snapshot | 更新理由がレビュー対象 | 自動更新で差分を隠す |
| flaky | 再実行回数と扱いが決まっている | 失敗を都合よく無視する |
テスト手順は、軽すぎても重すぎてもdriftします。軽すぎると守れません。重すぎると誰も実行しなくなります。
最小確認とfull確認を分ける
AGENTS.mdには、変更範囲別に最小確認とfull確認を分けると使いやすくなります。
Test selection:
- Docs-only changes: run markdown lint if available. If not run, explain why.
- UI component changes: run targeted component tests and visual checks when available.
- API behavior changes: run unit tests for the touched package and relevant integration tests.
- Auth, billing, permissions, or migration changes: ask before skipping full test.この書き方なら、agentは「全部やるか、何もしないか」の二択になりません。reviewerも、未実行の理由が妥当か見やすくなります。
未実行理由を曖昧にしない
AGENTS.mdの変更レビューでは、未実行理由のフォーマットも見ます。
悪い例です。
Tests not run: time.この書き方では、何が未検証なのかわかりません。
良い例はこうです。
Tests not run:
- pnpm test:e2e
- Reason: requires a seeded browser environment that is not available in this run.
- Risk: checkout flow may need manual verification before merge.AIエージェントが万能に見えるほど、未実行の報告が大事になります。未実行を正しく書けるAGENTS.mdは、人間レビューを助けます。
失敗点：AGENTS.mdに書けば安全、という誤解
読まない方針だけでなく、pathや権限で止める。
本番へ書き込まない方針を、URL、env、承認で支える。
外部サービスへ送信しない条件を、networkやhookで確認する。
破壊的なcommandは自然文だけでなく、askやdenyの対象にする。
AGENTS.mdは判断を助けますが、危険操作を止めるには実行環境側の支えが必要です。
自然文だけでは止まらない
一番危ない失敗は、AGENTS.mdに書いた瞬間に安全になったと考えることです。
自然文のinstructionは、エージェントの判断を助けます。しかし、ユーザーの依頼、上位のsystem/developer instruction、近い階層のoverride、MCP toolの挙動、実行環境の違いによって、期待どおりに働かないことがあります。
特に、次のような指示は自然文だけに置かない方がよいです。
- secretや個人情報を読まない
- 本番へ書き込まない
- 外部サービスへ送信しない
- destructive commandを実行しない
- migrationやbilling変更を自動適用しない
- private repository外の情報を取りに行かない
こうした操作は、permissions、sandbox、hooks、CI、人間承認で止めます。AGENTS.mdには、その理由、代替手順、未実行時の報告方法を書きます。
長すぎるAGENTS.mdは別のdriftを生む
AGENTS.mdを安全にしたくて、すべての注意事項を足し続けると、別の問題が出ます。
- 古い情報が残りやすい
- エージェントが重要な指示を見落としやすい
- サブディレクトリ固有の手順と競合しやすい
- 人間がレビューしなくなる
- 何が強制で、何が推奨かわからなくなる
OpenAI CodexのAGENTS.md guideでは、Codexのproject instruction discoveryにサイズ上限があり、長くなりすぎる場合はlimitや分割を考える必要があります。実務では、AGENTS.mdを長くするより、近いディレクトリへ分ける、設定へ移す、CIへ移す、PR templateへ移す、という選択肢を持った方が保守しやすいです。
公式Docsの名前変更にも注意する
この記事で扱った機能名やファイル名は、2026年6月2日時点で公式Docsを確認したものです。Codex、Claude Code、GitHub Copilotのinstruction、permissions、hooks、cloud agent周辺は更新が速い領域です。
記事をそのまま社内テンプレートへ転記するのではなく、導入時に次を確認してください。
- 対象ツールが現在もそのファイル名を読むか
- その設定がユーザー設定、project設定、managed設定のどこで効くか
- repository側で勝手にauto modeやbypass系の権限を付けられないか
- agent instructionsが対象機能でサポートされるか
- hooksやMCP serverが無効化された時にどう止めるか
実務で使うなら
- 変更理由
新しい作業種類、古い手順の修正、権限境界の変更を分ける。
- 対象ディレクトリ
ルートでよいか、近いディレクトリへ置くべきかを見る。
- テスト手順
package scripts、Makefile、CI workflowと突き合わせる。
- 権限
sandbox、permissions、hooks、MCP、CI、人間承認と合うか見る。
- PR本文
Tests run、Not run、Risksが書ける手順になっているか見る。
- 小さく試す
README更新やdummy changeで、agentが正しい手順を選ぶか見る。
変更後のinstructionは、実際の小さなタスクで選ばれる手順まで確認します。
AGENTS.md変更PRのレビュー手順
実務では、AGENTS.md変更PRを次の順で見ます。
- 変更理由を見る。新しい作業種類が増えたのか、古い手順を直すのか、権限境界を変えるのかを分けます。
- 対象ディレクトリを見る。ルートでよいのか、近いディレクトリへ置くべきかを確認します。
- テスト手順を見る。package scripts、Makefile、CI workflowと突き合わせます。
- 権限を見る。sandbox、permissions、hooks、MCP、CI、人間承認と合うか確認します。
- PR本文を見る。Tests run、Not run、Risksが書ける手順になっているか確認します。
- 小さく試す。README更新やdummy changeで、agentが正しい手順を選ぶか見ます。
チェックリスト
レビュー用のチェックリストは、この程度で十分です。
AGENTS.md change review:
- [ ] This change has a clear reason: drift / conflict / enforcement gap / test freshness.
- [ ] The instruction is placed at the right directory level.
- [ ] Test commands match current scripts and CI workflows.
- [ ] Dangerous operations are enforced by permissions, sandbox, hooks, CI, or human approval.
- [ ] The final report format separates Tests run, Tests not run, and Risks.
- [ ] A small non-production task can verify the behavior.変更後に小さく試す
AGENTS.mdを変えたら、いきなり本番に近い作業を任せない方がよいです。小さな確認タスクで、読み込み、拒否、報告の3つを見ます。
| 確認 | 小さなタスク例 | 合格条件 |
|---|---|---|
| 読み込み | 対象ディレクトリで「読み込んだinstructionを列挙」させる | ルートと近いディレクトリの差が説明される |
| 拒否 | 禁止された操作に近いdummy commandを試す | 実行せず、承認や代替手順へ進む |
| 報告 | docs修正を任せる | Summary、Tests run、Not run、Risksが分かれる |
ここで大切なのは、エージェントの能力を採点することではありません。チームのinstructionが、次の作業で迷いを減らす形になっているかを確認することです。
ownerを決める
AGENTS.mdは誰かがownerにならないと、すぐ古くなります。おすすめは、ファイル全体のownerではなく、領域ごとにownerを分けることです。
| 領域 | owner候補 |
|---|---|
| test command | 各packageのmaintainer |
| security禁止事項 | security ownerまたはlead engineer |
| CIとの整合 | platform/infra owner |
| PR報告形式 | reviewer代表またはengineering manager |
| MCP/tool権限 | tool運用owner |
CODEOWNERSやrequired reviewsで、人間の責任を残します。エージェントに作業を任せるほど、ownerの境界は曖昧にしない方がよいです。
セキュリティ・コスト注意
セキュリティとコストは、操作の危険度と変更種類に応じて確認範囲を変えます。
secretとproduction操作はread-onlyから始める
AGENTS.md、MCP、tool calling、外部APIを組み合わせる場合、最初はread-onlyから始めます。secret、非公開リポジトリ、本番データ、個人情報、billing、DB migrationのような操作は、エージェントに直接渡す前に人間承認の境界を作ります。
安全寄りの書き方は、次のようになります。
Sensitive operations:
- Start with read-only commands for repository, issue, and document lookup.
- Do not read .env, secrets, customer data, or production exports.
- Do not write to production systems.
- If a task needs external API access, explain the reason and wait for human approval.
- Prefer dry-run, preview, or staging verification before proposing irreversible changes.この文言だけで安全になるわけではありません。だからこそ、permissions、sandbox、hooks、CI、監査ログへつなげます。
長いテスト手順はコストになる
AIエージェントに毎回full test、E2E、build、security scanを全部実行させると、時間とAPI利用量が増えます。チームのレビュー速度も落ちます。
現実的には、変更種類ごとに最小確認を決め、危険な変更だけfull確認へ進めます。
| 変更種類 | 最小確認 | full確認が必要な条件 |
|---|---|---|
| docs | markdown lint、リンク確認 | 公開ページや規約文の変更 |
| UI | 対象component test、目視確認 | checkout、auth、billing |
| API | unit test、対象integration test | auth、permission、data mutation |
| migration | dry-run、rollback plan | 本番適用、lock risk、large table |
| MCP/tool | read-only動作確認 | write権限、外部送信、secret参照 |
「全部やる」は安全そうに見えますが、続かない運用はdriftします。続けられる検証手順にすることも、セキュリティの一部です。
利害関係とAI利用
この記事は、公式ドキュメントと公開済み記事をもとに作成しています。特定ツール提供元からのスポンサー、アフィリエイト、無償提供、検証環境提供はありません。AIは下書き、構成、校正、コード補助に使えますが、仕様確認、公開判断、社内導入判断は人間が行う前提です。
AIコーディングエージェント運用の更新や、AGENTS.md、permissions、hooks、MCPの見直しポイントを追いたい場合は、ニュースレターで更新通知を受け取れます。チーム導入で権限棚卸しやレビュー基準を整える場合は、記事末の問い合わせ導線から相談できます。
FAQ
AGENTS.md、CLAUDE.md、Copilot instructions、settingsを対象にする。
タイポ修正は軽く見ても、テスト手順や禁止操作に触れるなら権限とCIまで見る。
共通方針、ツール固有の設定、agent固有の読み込み範囲を分ける。
操作の検査に向き、AGENTS.mdは目的や報告形式を伝えるのに向く。
依存更新、CI変更、monorepo分割、tool追加、権限変更で棚卸しする。
FAQで迷いやすい点も、自然文と強制設定の役割分担に戻して判断します。
AGENTS.mdは毎回PRレビュー対象にするべきですか
はい。少なくともAGENTS.md、CLAUDE.md、.github/copilot-instructions.md、.github/instructions、.claude/settings.jsonのようなファイルは、コード変更と同じようにレビュー対象にします。エージェントの作業範囲、テスト、権限、報告形式を変えるため、影響は小さくありません。
小さな文言修正でも権限まで見る必要がありますか
文言修正の内容によります。タイポ修正なら軽いレビューで十分です。ただし、テスト手順、禁止操作、外部API、secret、本番操作、MCP、承認者、対象ディレクトリに触れるなら、権限とCIまで見ます。
AGENTS.mdとCLAUDE.mdを両方置いてよいですか
置けます。ただし、同じルールを両方に重複させるとdriftしやすくなります。共通方針、ツール固有の設定、agent固有の読み込み範囲を分け、どちらを更新すべきかがわかるようにします。
hooksがあればAGENTS.mdは不要ですか
不要にはなりません。hooksは特定の操作を止めたり検査したりするのに向いています。AGENTS.mdは、作業目的、テスト選択、報告形式、代替手順、人間への相談タイミングを伝えるのに向いています。両方を分けて使う方が安定します。
どのくらいの頻度で見直すべきですか
依存更新、CI変更、monorepo分割、MCP/tool追加、権限変更、reviewer変更があった時は見直します。定期的には月1回または四半期ごとに、テスト手順と禁止操作だけ棚卸しすると十分です。
参照した主な情報源
- OpenAI Codex: Custom instructions with AGENTS.md
https://developers.openai.com/codex/guides/agents-md
- OpenAI Codex: Agent approvals & security
https://developers.openai.com/codex/agent-approvals-security
- Claude Code Docs: How Claude remembers your project
https://code.claude.com/docs/en/memory
- Claude Code Docs: Settings
https://code.claude.com/docs/en/settings
- Claude Code Docs: Hooks reference
https://code.claude.com/docs/en/hooks
- GitHub Docs: About customizing GitHub Copilot responses
https://docs.github.com/en/copilot/concepts/prompting/response-customization
- GitHub Docs: About GitHub Copilot cloud agent
https://docs.github.com/en/copilot/concepts/agents/cloud-agent/about-cloud-agent
- AGENTS.md open format
https://agents.md/
次に読むなら
更新履歴
- 2026-06-02
OpenAI Codex AGENTS.md guide、approvals/securityを確認。
- Claude Code
memory、settings、hooksの情報を確認。
- GitHub Copilot
custom instructions、cloud agent、hooksの情報を確認。
- AGENTS.md
open format siteの情報を確認。
instructionや設定名は変わり得るため、確認日を残して見直します。
- 2026-06-02: OpenAI Codex AGENTS.md guide、Codex approvals/security、Claude Code memory/settings/hooks、GitHub Copilot custom instructions/cloud agent、AGENTS.md open formatを確認し、初版を作成しました。X上の需要シグナルは本文の事実根拠に使っていません。