AGENTS.md に書くべきは「リポジトリを読んでも分からないこと」だけ

ドキュメントを書く時、最も悪いのは「無駄に長いこと」じゃなくて「実物とズレること」だ。この著者は10個のリポジトリにAGENTS.mdを置いているが、行数は24行から309行までばらばらだった。調べたら長いほうには「リポジトリを読めば分かることが入っていて、短いほうには入っていない」ことに気づいた。309行のポートフォリオサイトのドキュメントは、ディレクトリツリー50行、実装済み機能22行。全部、エージェントがlsやfindで手に入る情報だ。実装一覧はコミットログにある。毎回書いた瞬間から古くなる。エージェントが古いツリーを信じて存在しないパスを触りに行く。そしてこの種の記述は絶対に腐るのに、メンテナンスされない。コードを変えたときに309行のドキュメントを直す気力が湧かないからだ。

一方で効いているのは、短いドキュメントだけだった。3種類に分かれる。第一に、決定とその理由。コードを読んでも「今こう書いてある」までは出てくるが「この先もこう書き続ける約束」は出てこない。設計方針がないと、エージェントは目の前の1件を最短で通す実装を提案してくる。第二に、禁止事項。やっていいことは無限だが、やってはいけないことは数える。スクレイピング禁止、説明文のコピペ禁止、ドキュメントの逐語転載時のライセンス表記必須、みたいな。第三に、現在のフェーズ。「縦切りプロトタイプ着手前。要件はこのファイル、次はこのタスク」と書くだけで、粒度が揃う。ただしいちばん腐りやすいので「1段落だけ」に留める。

中小企業がAIにドキュメントを渡すなら、判定基準は1問だけ。その情報は、ファイルシステムを読めば手に入るか？ 入るなら、書くな。入らないなら書け。