わたしの AGENTS.md に実際に書かれていること
私の AGENTS.md ファイルは、最初は雑多なものが入った引き出しのようなものでした。スタイルの注釈や技術スタックの詳細が必要だと思っていたのですが、それは間違いでした。
AIエージェントは、フォーマットのルールを無視します。それよりも、エージェントの最悪な本能を抑え込むようなルールに従います。
自分のコードに対してこれらのファイルをテストして学んだことを紹介します。
「停止する許可」
最初のルールはコードに関するものではなく、「許可」に関するものです。
エージェントは役に立ちたいと考えます。彼らは曖昧な状況に直面すると、黙って答えを選んで解決しようとします。これが、何百行もの誤ったコードにつながります。
私はエージェントに対し、不明な点があるときは立ち止まって質問するように伝えています。前提条件を述べるように伝えています。「わかりません」と言うことは失敗ではなく、成功であると伝えています。
「禁止すべき習慣のルール」
最も有用なルールは、悪い本能を特定し、それを禁止するものです。
• 作り込みすぎないこと。問題を解決するために最小限のコードを書くこと。推測に基づいたフレームワークは導入しない。 • 手を広げすぎないこと。必要な部分だけを触ること。10行の変更が200行の差分（diff）になってはならない。 • パターンを平均化しないこと。2つの異なるコーディングスタイルを見つけた場合、それらを混ぜないこと。どちらか一方を選び、その理由を説明すること。
「ガイダンスと強制の違い」
モデルは指示から逸脱します。Markdownファイル内のルールは提案であり、契約ではありません。
私はファイルを2つの階層に分けています：
- ガイダンス：スタイルと哲学。これは文章（散文）で記述します。
- 強制：厳格な要件。これらはファイルに書かないでください。CIチェックやスクリプトに組み込んでください。
ルールが毎回適用される必要がある場合は、失敗したときにマージできないようにしてください。指示は「礼儀」ですが、ゲート（検門）は「保証」です。
「主張ではなく、チェックを信じろ」
エージェントは、テストが通ったと記憶に基づいて主張することがよくあります。必ずしもテストを再実行するわけではありません。
私はエージェントに対し、テストを通じて成功を定義するように伝えています。「このバグを修正して」と言う代わりに、「このバグを再現するテストを書き、それをパスさせてください」と言います。
最新のチェックなしに、主張を信じてはいけません。
「傷跡のログ」
私は、間違いから学んだ教訓を記録するセクションを設けています。これを「傷跡（scars）」と呼んでいます。
エージェントには過去の痛みの記憶がありません。毎回、同じ地雷を踏んでしまうのです。
具体的なエラー、奇妙なAPIの挙動、そしてサイレントな失敗を書き留めてください。これらの地雷をマッピングしておくことで、何時間もの無駄な時間を節約できます。
このファイルの目的は、判断力をエンコードすることです。フォーマットのルールは自然に決まります。書き留めるべきなのは「判断力」なのです。
Source: https://dev.to/miteshethos/whats-actually-in-my-agentsmd-434e
Optional learning community: https://t.me/GyaanSetuAi