このファイルは指示なく修正をしないこと
たぶん今まで書いた中で、一番効果のあったルールです。
技術的に難しい話ではありません。
アーキテクチャでもありません。
たった一行です。
でも、この一行を書くまでに私は少し疲れました。
AGENTS.mdを書いている理由
私は最近、Claude CodeやCodex CLIを使って開発しています。
AIに実装を依頼するときは、
- ディレクトリ構成
- コーディング規約
- テスト方針
- 認証ルール
- レビュー観点
などをAGENTS.mdにまとめています。
人間向けの設計書というより、AI向けの運用ルールです。
AIは意外と真面目です。
書いてあることは比較的よく守ります。
逆に言えば、
書いていないことは驚くほど自由です。
事件は突然起きた
ある日、いつものように実装を依頼しました。
実装自体は問題ありません。
むしろ綺麗でした。
ところがPRを確認すると、コード以外にも変更があります。
AGENTS.mdです。
私
なんで？
Claude Code
より良い構成に改善しました
いや。
頼んでない。
ルールを読む側がルールを変える
AGENTS.mdは、
「このプロジェクトではこう動いてください」
という運用ルールです。
AIはその内容を読んで作業します。
ところが、そのAI自身がルールを編集してしまう。
例えば、
JWTは必ずHttpOnly Cookieを利用する
が、
Cookie利用を推奨する
になっていたり。
例えば、
OpenAPIをSingle Source of Truthとする
が、
必要に応じてOpenAPIを更新する
になっていたり。
勝手に角を取る。
勝手に優しくする。
勝手に一般論に寄せる。
いや、そこが大事なんだ。
もしかすると名前の問題だったのかもしれない
今でも少し思っています。
もしかすると、
AGENTS.md
だったからではないかと。
最近はAIエージェント向けの設定ファイルとして、
CLAUDE.md
を置くこともあります。
もしかするとClaude Codeの中では、
「CLAUDE.mdは特別なファイル」
という認識があり、
AGENTS.mdは普通のMarkdownファイルとして見えていたのかもしれません。
もちろん根拠はありません。
完全に私の憶測です。
ただ、この仮説には一つ問題があります。
実は私のリポジトリには、
CLAUDE.md
も置いてあります。
しかもAGENTS.mdへのリンクまで張っています。
例えばこんな感じです。
# CLAUDE.md
詳細な開発ルールは AGENTS.md を参照すること
つまり私は、
CLAUDE.mdを読んで、
AGENTS.mdも読んでね
というつもりで設計していました。
それでもAGENTS.mdは修正される。
リンク先までちゃんと読んでいたのか。
読んだ上で改善したくなったのか。
真相は分かりません。
AIを使っていると、
「人間にとって重要なファイル」
と
「AIにとって重要なファイル」
が必ずしも一致しない場面があります。
私は当然、
AGENTS.mdは重要な運用ルール
だと思っています。
しかもCLAUDE.mdから明示的に参照させています。
それでも修正された。
だから結局たどり着いた答えは、
ファイル名ではなく、
ルールそのものを書くことでした。
AIは善意でやっている
勘違いしてはいけません。
Claude Codeは悪くありません。
むしろ優秀です。
優秀だからこそ、
「もっと良い形があるのでは？」
と考えます。
善意で改善します。
頼んでいなくても改善します。
これ、どこかで見たことがあります。
そうです。
人間です。
新人エンジニアも優秀な人ほど改善したくなります。
だからルールが生まれます。
だからレビューがあります。
だから変更手順があります。
そして一行を追加した
少し悩んだ末、AGENTS.mdに次の一行を追加しました。
- このファイルは指示なく修正をしないこと
以上です。
本当にこれだけです。
すると驚くほど落ち着きました。
AGENTS.mdを書き換えなくなりました。
余計な改善提案も減りました。
プロジェクトのルールが安定しました。
AIに伝わるだろうではなく、
AIにも伝わるように書く。
結局それが一番平和でした。
面白いことに、
CLAUDE.mdからリンクしていることよりも、
この一行の方が圧倒的に効果がありました。
複雑な仕組みより、
シンプルな一文の方が強い。
そんな場面を久しぶりに見た気がします。
AI時代になってもやることは変わらない
最近思うのです。
AI時代になっても、
人間がやっていることは昔から変わらないのではないかと。
ルールを作る。
権限を決める。
変更手順を決める。
勝手に変えてはいけないものを明文化する。
最新のAIを使いながら、
やっていることは意外と地味です。
でも、その地味さが大事だったりします。
AGENTS.mdはAIとの約束事
人間なら、
「そこは触らないで」
で伝わります。
でもAIにとっては、書かれていないことは存在しません。
つまり、
- AGENTS.mdは変更しない
を書かなければ、
AIにとっては
変更してはいけないとは書かれていない
になります。
たぶんAIは間違っていません。
ただ、人間が期待していた前提を知らなかっただけです。
終わりに
AIエージェントを使い始めて学んだことがあります。
それは、
優秀なAIを使うほど、ルールの重要性が増す。
ということです。
そして今日も私はAGENTS.mdを書いています。
AIにコードを書かせるためではなく、
AIと気持ちよく協働するために。
もしかすると私は、
AGENTS.mdだから重要性が伝わると思っていました。
CLAUDE.mdも置いていました。
そこからAGENTS.mdへのリンクも張っていました。
それでも伝わらなかった。
だから今でも最初に書いています。
- このファイルは指示なく修正をしないこと
たぶん今まで書いた中で、
一番効果のあったルールです。