リンドくんたなべさん、最近エージェントの調子が悪い気がするんです。前は一発で通っていたのに、変なコマンドを実行して失敗することが増えて。
たなべモデルを疑う前に、ひとつ確認していい？
AGENTS.md、最後に更新したのはいつ？
リンドくん……えっと、最初に書いたきりです。内容は間違ってないはずですけど。
たなべ書いた時点では正しかったんだよ。そのあとリポジトリのほうが動いた。
書き方の記事は足りている
AGENTS.md の書き方についての情報は、もう十分にあります。コマンドを書く、規約を書く、完了の定義を書く。どれも正しく、そのとおりに書けば、最初の一週間はうまく動きます。
問題はその後です。
文書は変わらない。リポジトリは変わる
リンドくんそういえば先月、npm から pnpm に変えました。AGENTS.md は……触ってないです。
たなべそれで CI は通ったし、ビルドも通ったよね。文書を直さなくても、誰も困らなかった。
困っているのはエージェントだけで、しかも報告してこない。
AGENTS.md を書いた時点では、内容はリポジトリと一致しています。そして、次のことが起きます。
- パッケージマネージャを npm から pnpm に変えた
- テストランナーを入れた、あるいは外した
- ディレクトリ構成を変えた
- CI を追加した
コードは変わり、文書は変わりません。どれも文書を更新しないと壊れないわけではないからです。CIは通り、ビルドも通り、誰も困りません。
困るのはエージェントだけです。そして、エージェントは困っていることを報告しません。
これが厄介さの正体
文書とリポジトリが食い違っても、エラーは一切出ません。エージェントは書いてあるとおりに npm install を実行し、ロックファイルと矛盾した依存を入れ、なぜか動かないコードを書き始めます。原因は「指示書が古い」ことですが、そう見える形では現れません。
自分のリポジトリで実行したら、2件出ました
リンドくんFRKZ 自身は大丈夫だったんですか？
たなべ……2件見つかった。しかも1件は、CIを強制しろと書いた運用キットを売っているリポジトリに、CIもテストも無かったというやつ。
リンドくんそれは……。
たなべ言い訳のしようがないよね。すぐ直した。
FRKZ には、リポジトリの実態と AGENTS.md を突き合わせるレビュー機能があります。作った後、自分のリポジトリに対して実行しました。
2件の本物の食い違いが見つかりました。 仮定の話ではなく、売り物のドキュメントを含むリポジトリで、です。
そのうち1件は、こういうものでした。FRKZ は「typecheck・lint・テストをCIで強制する」と書いた運用キットを販売していました。そして当のリポジトリには、テストもCIも存在しませんでした。
これはレビュー機能が見つけるために作られた種類の食い違いそのものであり、しかも売っている製品の中で起きていました。修正して、Vitest と GitHub Actions を入れました。入れてすぐ、過去に出荷したバグを固定するテストが60件書けました。
人間のレビューでは見つからない理由
リンドくんでも、自分の書いた文書なんだから、読み返せば気づきませんか？
たなべそれが気づかないんだ。人は文書を読むとき、書いてあることが正しいかを見る。
「テストは pnpm test で実行する」は、文としては正しいよね。誤りになるのは、リポジトリに test スクリプトが無い場合だけ。それは読んでいる間には分からない。
「ちゃんと読めばいい」と思えますが、これは人間が苦手な作業です。
文書を読むとき、人は書いてあることの正しさを見ます。「テストは pnpm test で実行する」は、読めば正しい文です。これが誤りになるのは、リポジトリに test スクリプトが無い場合だけで、それは文書を読んでいる間には分かりません。
必要なのは、次の2つを同時に持って突き合わせることです。
- 文書が主張していること
- リポジトリが実際にそうなっているか
自分のプロジェクトほど、2を「知っているつもり」で読み飛ばします。
突き合わせに必要な材料
自動化する場合でも、手でやる場合でも、見る場所は同じです。
| 文書の記述 | 突き合わせる先 |
|---|---|
| パッケージマネージャ | コミットされているロックファイル |
| コマンド | マニフェストのスクリプト定義 |
| テストの有無 | テストファイルの実在 |
| CI の有無 | ワークフローファイルの実在 |
| ADR を書く運用 | docs/adr/ の実在 |
| フレームワーク | 設定ファイルまたは依存 |
ロックファイルが pnpm-lock.yaml なのに文書が npm install と書いていれば、それは食い違いです。判定に推測は要りません。
検出結果に既定値を混ぜないこと
ここで重要な注意があります。突き合わせの材料に「たぶんこうだろう」という既定値を混ぜると、存在しないコマンドを根拠に矛盾を指摘するという、最悪の誤報が生まれます。検出は、ファイル名を挙げられるものだけを事実として扱ってください。
見つけた後、直るところまで持っていく
食い違いを見つけても、直らなければ意味がありません。そして、指摘を1件ずつ手で文書に反映する作業は、たいてい途中で止まります。
FRKZ のレビューは、結果をそのままエージェントに渡せる指示文として出力します。矛盾を先頭に、重大度順の指摘、提案する文面という順番の1ブロックです。Claude Code や Codex、Cursor に貼れば、修正はエージェントの仕事になります。
指示書の修正を、指示書を読むエージェントにやらせる、という形です。
いつ実行するか
リンドくんこれ、どのくらいの頻度でやればいいですか？毎日は無理そうです。
たなべ毎日はやらなくていい。ツールチェーンを変えたときと、「最近エージェントの調子が悪い」と感じたとき。
ちょうど今日の君みたいなときだね。
毎日やる必要はありません。効くのは次のタイミングです。
- パッケージマネージャやツールチェーンを変えたとき
- ディレクトリ構成を大きく変えたとき
- 「エージェントの挙動が最近おかしい」と感じたとき
3つ目が実は一番多い入口です。モデルのせいに見えて、指示書が古いだけ、ということがあります。
まとめ
AGENTS.mdの本当の問題は、書き方ではなく古くなること- 食い違いはエラーを出さない。だから気づくのが遅れる
- 見つけるには、文書とリポジトリの実態を同時に持つ必要がある
- 自分のリポジトリは「知っているつもり」で読み飛ばす
FRKZ のレビューは、ご自身の API キーで実行します。キーはサーバーに保存しません。まずリポジトリの実態だけを見たい場合は、解析ツールだけでも使えます。
