最近、CLAUDE.md や AGENTS.md に、Repositoryで守ってほしいルールを書くことが増えました。
自分も使っています。
- 変更後は必ずテストを実行する
- lint / typecheckを実行する
- 既存のテストを壊さない
- public APIを変更する場合は影響範囲を確認する
こういう指示を書いておくと、毎回Promptで説明しなくていい。
かなり便利です。
ただ、使っているうちに気になることも出てきました。
書いたからといって、必ず守られるわけではない。
テストを実行してほしいと書いてあっても、実行せずに作業を終えることがある。
変更範囲を限定していても、必要だと判断すれば別の場所まで変更することがある。
長い作業の途中で、最初に与えた条件の一部が抜けることもある。
では、もっと強く書けばいいのでしょうか。
IMPORTANT:
必ずテストしてください。
VERY IMPORTANT:
絶対にテストしてください。
CRITICAL:
テストせずに完了してはいけません。
たぶん、これは本質的な解決ではないと思っています。
問題はPromptの書き方ではありません。
そもそも、守られなければ困る条件をPromptに置いていることです。
Instructionは保証ではない
CLAUDE.md や AGENTS.md はとても便利です。
Repositoryの構造、Coding Convention、Testの実行方法、設計上の注意点などをAgentに伝える用途ではかなり有効です。
ただし、それはあくまでInstructionです。
ここにはAgentによる解釈があります。
OpenAIのCodexでも、AGENTS.md は探索されたあとConversationへInstructionとして注入されます。階層ごとのAGENTS.mdを読み込み、より深いDirectoryのInstructionが後から渡される仕組みです。
つまり、
テストを実行してください
と書くことと、
テストが成功しなければMergeできない
ことは違います。
前者はAgentへの要求です。
後者はSystemによるControlです。
この二つは分けて考えた方がいいと思っています。
「書いてあるから、すべてのAgentが守る」とも限らない
これは単に「LLMは気まぐれだから」という話でもありません。
Agentを取り巻く仕組み自体が複雑になっています。
例えばGitHub Copilot CLIでは、Custom AgentをSubagentとして実行した場合、RepositoryのCustom Instructionsはデフォルトでは適用されません。
必要ならCustom Agent側で、
include-custom-instructions: true
を指定する必要があります。
つまり、
RepositoryにAGENTS.mdが存在する
ことと、
すべてのAgent実行で
そのInstructionが適用される
ことは同義ではありません。
Agentが高度になり、SubagentやToolを使うようになるほど、
どのInstructionが、どの実行経路まで届いているのか
も設計上の関心事になります。
だから品質保証では、
書いてあるから守られるはず
を前提にしない方がいい。
これは人間相手にも、ずっとやってきた話だった
考えてみると、これはAI特有の話でもありません。
昔からREADMEやWikiには、いろいろなルールを書いてきました。
Commit前にlintしてください。
PRを出す前にテストしてください。
Migrationを忘れずに確認してください。
mainへ直接pushしないでください。
もちろん必要です。
でも、人間は忘れます。
忙しければ飛ばすこともある。
知らない人が参加することもある。
だからSoftware Engineeringでは、少しずつ「気をつけてください」を仕組みに移してきました。
Formatterを自動化する。
Static AnalysisをCIで実行する。
TestをPRごとに実行する。
Required Checkにする。
Branch Protectionで直接Mergeできなくする。
人間を信用していないからではありません。
毎回確実にやる必要があることを、人間の注意力へ依存させないためです。
それなのにAI Coding Agentを導入した途端、
必ずテストしてください
と書いて安心するなら、少し逆戻りしています。
人間への「気をつけて」をAutomationへ移してきたのなら、
AIへの「気をつけて」も同じように扱った方がいい。
「お願いする」と「止める」を分ける
ここで、Agentに与えるものを全部CIへ移せばいい、という話でもありません。
InstructionにはInstructionの役割があります。
例えば、
| 仕組み | 主な役割 |
|---|---|
CLAUDE.md / AGENTS.md
|
Context、設計方針、Coding Conventionを伝える |
| Skills | 特定の作業方法や判断手順を再利用する |
| Hooks | Agentの特定の行動へ介入する |
| Static / Unit / Integration Test | 実際の振る舞いからEvidenceを得る |
| CI | Verificationを継続的に実行する |
| Required Check / Quality Gate | 条件を満たさない変更を止める |
| Observability | Productionで実際に起きていることを観測する |
同じ「ルール」に見えても、責務が違います。
ここを一つのPromptへ押し込まない。
自分が特に意識しているのは、
Agentが無視しても困らないものと、無視されたら困るものを分けること
です。
HooksはPromptより強い。でもTestではない
例えばClaude CodeにはHooksがあります。
PreToolUseを使えば、Toolが実行される前に処理へ介入し、条件によってTool Callを拒否できます。
Claude Codeの公式Documentationでは、HookとSkillについてかなり明確に役割を分けています。
SkillはClaudeがInstructionを読み、解釈して使う。
一方HookはLifecycle Eventで実行される。
さらに、毎回適用する必要があるGuardrailはInstructionではなくHookへ置く、という考え方まで明示されています。
例えば、
Production DBへの書き込みは禁止
とPromptに書くことと、
Production DBへのWrite操作そのものを拒否する
ことは違います。
自分なら後者にできるものは、後者へ寄せます。
ただし、HookもTestの代わりではありません。
Hookが保証できるのは、
このToolを使わせない
このCommandを実行させない
この操作の前後で処理を実行する
といったControlです。
一方で、
Transaction Boundaryが正しいか
Retry時に二重処理されないか
この変更がBusiness Contractを満たしているか
は別の問題です。
そこにはTestやStatic AnalysisなどのVerificationが必要です。
Testを実行させることと、正しさを保証することも違う
ここでもう一段分ける必要があります。
例えばAgentに、
実装後にIntegration Testを実行してください
と指示したとします。
Agentがちゃんと実行した。
全部Greenだった。
それでも、
Quality = OK
とは限りません。
以前の記事でも書きましたが、GreenはQualityそのものではなくSignalです。
Testが見ているRiskがズレていれば、何件Greenでも守りたいものは守れません。
だから構造としては、
になります。
Agentはこの中のかなりの部分を手伝えます。
Riskを調査する。
既存Testを探す。
Testを書く。
Testを実行する。
失敗を分析する。
修正する。
ここはどんどん任せればいいと思っています。
でも、
どのRiskを、何をもって止めるのか
という構造までAgentへのInstructionだけに閉じ込めてしまうと、品質保証そのものがAgentの判断に依存します。
そこは分けたい。
「AIを信用するか」という話ではない
こういう話をすると、
AIを信用していないのか
という方向へ行きがちですが、自分はそうは考えていません。
むしろかなり使っています。
調査も実装もTestもReviewも、AIによって速くできるところは多い。
自分が気にしているのは、信用ではなく責務です。
人間でもAIでも、
絶対に守る必要がある条件を、誰かの注意力や判断だけへ置かない。
これは昔から変わっていません。
AIが強くなるほど、Promptの外側が重要になる
Coding Agentがまだ単純なコード補完だった頃なら、
AIが書く
↓
人間が確認する
くらいでも成立していました。
今は違います。
Agent自身がRepositoryを調査し、実装し、Testを書き、実行し、修正し、場合によっては複数Agentへ仕事を分解します。
Anthropicも、長時間動作するCoding Agentについて、PromptだけではなくHarness全体をどう設計するかを継続的に研究しています。
2026年3月に公開されたHarness Designの記事では、Prompt EngineeringとHarness Designによる改善を進めたうえで、さらにAgentの性能を引き出すために周囲の構造そのものを見直しています。
これは品質保証でも同じだと思っています。
Agentに何を書くかだけではなく、
Agentの外側に何を置くか。
Coding Agentが強くなるほど、こちらの設計の方が重要になってくると思っています。
Promptを書く前に考えること
最近はCLAUDE.mdやAGENTS.mdを整備する機会も増えました。
そのとき自分は、
このルールは、
Agentに知っていてほしいのか。
それとも、
絶対に破ってはいけないのか。
を分けて考えたいと思っています。
知っていてほしいなら、Instructionでいい。
特定の操作を禁止したいなら、HookやPermissionの方が適切かもしれない。
Codeの性質を保証したいなら、Static AnalysisやTestかもしれない。
変更を通してはいけないなら、CIのQuality Gateまで必要になる。
Productionでしか分からないなら、Observabilityが必要になる。
全部をPromptに書く必要はありません。
AIは指示を無視することがあります。
人間も忘れます。
だから、そこを責めても仕方がない。
何度も、
絶対に守ってください。
と書くより、
守らなければ先へ進めない仕組みにできないか考える。
人間に対してやってきたことを、AIに対してもやるだけです。
AI Coding Agentが強くなるほど、Prompt Engineeringだけではなく、その外側にあるSoftware Engineeringの設計が効いてくる。
自分は、そんなふうに考えています。
参考資料
- OpenAI — Codex Prompting Guide Codex Prompting Guide
- GitHub Docs — Creating and using custom agents for GitHub Copilot CLI GitHub Copilot CLI Custom Agents
- GitHub Docs — GitHub Copilot CLI command reference Copilot CLI command reference
- Claude Code Docs — Extend Claude Code Claude Code features overview
- Claude Code Docs — Permissions Claude Code permissions
- Anthropic Engineering — Harness design for long-running application development Harness design for long-running application development