「テストは pnpm で動かして」「generated/ は触らないで」を毎回打ち込んでいるなら、それはエージェントの性能の問題ではありません。設定していないだけです。
リポジトリに置く、道具向けの説明書
AGENTS.mdは、リポジトリ直下に置くエージェント向けの手引きです。READMEが人に向けた案内だとすれば、こちらは自動で読まれることを前提にしています。2025年ごろから複数のコーディングエージェントがこのファイル名を見るようになり、置き場所として定着してきました。
中身はただのMarkdownで、決まった項目はありません。作業に入る前に読まれる短い文書、という以上の仕様はない形です。
効くのは、実行できる指示
書いて効果があるのは、そのまま実行できるものです。
- 動かし方: ビルド、テスト、lintのコマンド。npmかpnpmかまで明記します
- 触らない場所: 生成物、移行中のディレクトリ、手で書き換えてはいけない設定
- 終わりの条件: 変更したら何を通してから完了とするか
- やられて困った解決策: 「型が合わないときに
as anyで黙らせない」のような、過去に実際に踏んだもの
逆に効かないのは、心構えと、コードを読めば分かることです。「品質の高いコードを書く」は、何も指示していないのと変わりません。
ファイルだから効く
プロンプトに書いた注意は、その会話にしか効きません。翌日の作業にも、他の人の作業にも引き継がれません。ファイルは毎回読まれます。
運用としては、レビューで指摘した内容をその場で書き足すのが早い方法です。同じ指摘が二度出たら、手引きに漏れがあるという合図になります。
長く書くと壊れる
長いほど効くわけではありません。読まれる量を食い潰すのと、古くなって嘘が混ざるのと、二つの壊れ方があります。
コマンドは実物を、意図は一行で。半年後に更新されていない記述は、無いほうがましになります。
効いたかを測る
手引きを足したら、生成されるコードが実際に変わったかを見たいところです。指摘の回数ではなく、出てきたコードが後から直される割合を見るのが実際的です。
Aid-Onが開発している言語Almideについては、生成されたコードがそのまま通る率を毎日測る仕組み（almide-dojo）を回しており、手引きを変えたときはその数字で判断しています。手応えでは分かりません。
学習データにない言語ほど効く
広く使われている言語であれば、モデルは作法をだいたい知っています。新しい言語や社内独自の枠組みでは、そこが空白のままになります。空白は手引きで埋めるほかありません。
Almideでは、この手引き一式をalmide-agentsとして公開しています。リポジトリに置くだけで、どのエージェントを使っても書き方が揃う形です。
社内でコーディングエージェントを使っているなら、まず同じ注意を何度も打ち込んでいないかを見直してみてください。二度以上出た指摘がそのままAGENTS.mdに書くべき項目で、書いたあとに手直しの量が変わったかどうかが、効き目の判断材料になります。
