最近、CLAUDE.md や AGENTS.md に、Repositoryで守ってほしいルールを書くことが増えました。
自分も使っています。
- 変更後は必ずテストを実行する
- lint / typecheckを実行する
- 既存のテストを壊さない
- public APIを変更する場合は影響範囲を確認する
こういう指示を書いておくと、毎回Promptで説明しなくていい。
かなり便利です。
ただ、使っていると困ることもあります。
書いたからといって、必ず守られるわけではない。
テストを実行してほしいと書いてあるのに、実行せずに作業を終える。
変更範囲を限定したつもりでも、別の場所まで変更する。
長い作業になると、最初に渡した条件の一部が抜ける。
そんなことは普通に起きます。
では、もっと強く書けばいいのでしょうか。
IMPORTANT:
必ずテストしてください。
VERY IMPORTANT:
絶対にテストしてください。
CRITICAL:
テストせずに完了してはいけません。
自分は、これは違うと思っています。
問題は書き方ではない。
守られなければ困ることを、「守ってください」という指示だけに置いていることです。
「やってください」と「やらないと進めない」は違う
CLAUDE.md や AGENTS.md は、AgentにRepositoryのことを伝える場所として便利です。
例えば、
- このRepositoryではどういう設計をしているか
- どのコマンドでテストするか
- どこまで変更してよいか
- どんな書き方をしてほしいか
こういう情報を渡す用途には向いています。
ただ、最後にそれをどう扱うかはAgentが判断します。
だから、
変更後はテストしてください
と、
テストが成功しなければMergeできない
は似ているようで、かなり違います。
前者はお願いできます。
後者は、守らなければ先へ進めません。
品質保証として考えるなら、この差は大きいです。
OpenAIのCodexでも、AGENTS.md はAgentへ渡す指示として読み込まれます。
またGitHub Copilot CLIでは、Subagentを使った場合にRepositoryの指示が自動では引き継がれず、明示的な設定が必要になるケースがあります。
Repositoryにルールを書いたからといって、
すべての実行経路で、そのルールが必ず適用される
とは限らないわけです。
Agentが単独でコードを書くくらいなら、まだ分かりやすい。
でも複数のAgentやToolを組み合わせるようになると、
この指示は、実際にはどこまで届いているんだろう
という問題が出てきます。
品質を守る仕組みを、その前提の上には置きづらいです。
その前に、ルール自体が矛盾していないか
ここでもう一つあります。
「そのルールをどこで守るのか」を考える前に、
そもそも、そのルールはちゃんと決まっているのか
を見た方がいい。
この記事を公開したあと、コメントで面白い例を教えてもらいました。
あるUI向けのSkill（Agentに特定の作業方針や手順を与える仕組み）では、
gradientは使わない
と書いてある一方で、同じファイルの後半では、
radial-gradientを使った薄い背景表現
が選択肢として挙げられています。
これだと、Agentがgradientを使っても、使わなくても、それぞれファイルの中に根拠があります。
この場合、
AIが指示を無視した
という話ではない。
人間側が、矛盾した指示を渡しています。
ここで、
IMPORTANT:
gradientは禁止
と強く書いても、根本的には何も解決していません。
先に、
gradientは禁止なのか
薄いradial-gradientなら許可するのか
を人間側で決める必要があります。
そして、決まったルールの中には、Agentへ伝えるだけでなく、機械的に確認できるものもあります。
例えば、
shadow-mdは禁止
のように比較的はっきり判定できるものなら、毎回Agentへ注意するより、lintや静的解析、CIで検出した方が確実です。
逆に、
読みやすいUIにする
のようなルールは、単純なチェックには落としづらい。
だから自分の中では、
まず、何を守るのか決める。
次に、ルール同士が矛盾していないか見る。
そのあとで、
どこまで仕組みで確認できるかを考える。
くらいの順番になっています。
「どこで守るか」を考える前に、
何を守るのかを、自分たちで決められているか。
そこはAgentに任せる前に、人間側で片付けておきたいところです。
これ、人間相手にも同じことをやってきた
考えてみれば、特別新しい話でもありません。
昔からREADMEやWikiには、こんなことを書いてきました。
Commit前にlintしてください。
PRを出す前にテストしてください。
Migrationを忘れずに確認してください。
mainへ直接pushしないでください。
必要な説明です。
でも、人間は忘れます。
忙しければ抜けます。
ルールを知らない人が参加することもあります。
だから少しずつ、こういうものを仕組みに移してきました。
lintをCIで実行する。
テストをPRごとに実行する。
必要なチェックが落ちていたらMergeできなくする。
mainへの直接pushを禁止する。
人を信用していないからではありません。
毎回確実にやる必要があることを、誰かが覚えているかどうかに依存させたくないからです。
なのにAIになった途端、
必ずテストしてください
と書くだけに戻るのは、少し不思議です。
人間への「気をつけてください」を仕組みに変えてきたのなら、AIに対しても同じでいいはずです。
指示する、止める、確かめる
もちろん、何でもCIに入れればいいわけではありません。
Agentに伝えた方がいいこともあります。
例えば、
このRepositoryでは、この設計方針を守ってほしい
これは指示でいい。
一方で、
本番DBには絶対に書き込ませたくない
なら、できるだけ「書き込まないでください」で終わらせたくありません。
実行しようとした時点で止めたい。
Claude Codeでは、AgentがToolを実行する前に処理を挟み、条件に合わなければその操作を拒否できます。
この仕組みがHooksで、実行前に使えるものの一つがPreToolUseです。
こうなると、
本番DBには書き込まないでください
とは意味が変わります。
一方は「やらないように頼む」。
もう一方は「やろうとしても通さない」。
自分なら、絶対に破ってほしくないものは、できるだけ後者へ寄せます。
ただ、これも何でも解決できるわけではありません。
操作を止める仕組みで、
Retryしても二重処理されないか
DB更新とQueueへの登録が期待した順序になっているか
失敗したあとに正しい状態へ戻れるか
までは確認できません。
そこはテストで見る話です。
さらに、そのテストを変更のたびに実行したいならCIへ置く。
失敗した変更をMergeしたくないなら、必須のチェックにする。
本番でしか分からないものなら、監視する。
一つの仕組みに全部背負わせる必要はありません。
こうして見ると、CLAUDE.mdに何を書くかより、
そのルールをどこで守るのか
の方が大事になってきます。
テストしたから大丈夫、でもない
もう一つあります。
Agentに、
実装後にIntegration Testを実行してください
と書いた。
ちゃんと実行した。
全部Greenだった。
これで終わりかというと、そうでもありません。
テストが見ているもの自体がズレていたら、Greenでも守りたいものは守れていません。
以前の記事で、
Greenは品質そのものではない
という話を書きました。
ここは今回も同じです。
テストを実行したかどうかより先に、
何が壊れたら困るのか
何を正しい状態とするのか
が必要です。
Agentには、このかなりの部分を任せられます。
既存のコードやテストを調べてもらい、不足しているテストを書いて実行する。失敗すれば原因を調べて修正する。
ここはどんどん任せたい。
でも、
何が壊れたら止めるのかまで、Agent自身の判断だけに任せたくはない。
そこは別の話です。
AIを信用するかどうかではない
AIを信用していないから、こうしているわけではありません。
自分もかなり使っています。
調査も、実装も、テストも、レビューも速くなる。
任せられるところは任せた方がいいと思っています。
ただ、
絶対に守らないと困ること
まで、AIが覚えていてくれるかどうかには賭けたくない。
これは人間でも同じです。
人が作業するならCIが必要なのに、AIならPromptだけで大丈夫、という理由もありません。
誰が作業しても、同じところで止まる。
誰が作業しても、同じ確認が走る。
その方が、自分には自然に見えます。
Agentが強くなるほど、外側の仕組みも必要になる
今のCoding Agentは、Repositoryを調べて実装し、テストを書いて実行し、失敗すれば原因を調べて修正するところまで自律的に進められます。場合によっては、別のAgentへ作業を分けることもあります。
Anthropicも、長時間動作するCoding Agentについて、Promptの書き方だけではなく、Agentを取り巻く仕組み全体をどう作るかを研究しています。
何を渡し、どう引き継ぎ、どう評価するか。さらに、どんな環境で動かし、どのToolを使わせるか。
Agentができることが増えるほど、Agentの外側で決めなければならないことも増えていきます。
品質保証も同じだと思っています。
Agentに何を言うかだけを考えるのではなく、
Agentがどう判断するかだけに、品質を預けない。
CLAUDE.mdに書く前に、一度考える
最近はCLAUDE.mdやAGENTS.mdを整備すること自体が、かなり普通になってきました。
自分も今後使い続けると思います。
ただ、何かルールを書こうとしたとき、
これはAgentに知っていてほしいことなのか。
それとも、
絶対に破られてはいけないことなのか。
は、一度分けて考えたい。
知っていてほしいことなら、指示に書けばいい。
危険な操作なら、実行しようとした時点で止める。
コードの振る舞いなら、テストする。
変更のたびに確認したいなら、CIで自動化する。
満たしていなければMergeしてはいけないなら、そこで止める。
本番でしか分からないことなら、監視する。
全部をPromptに背負わせなくていい。
AIは指示を無視することがあります。
人間も忘れます。
なので、
絶対に守ってください。
を何度も強くするより、
守らなかったら、そこで止まるようにする。
自分はその方が好きです。
人間相手にやってきたSoftware Engineeringを、AI相手にもやる。
結局、それだけの話なのかもしれません。