8月21日、Fabien Sanglardが「My agent.md to improve LLM-assisted code quality」と題した記事を公開した。「マジックナンバーを使うな」「ここにコメントを追加しろ」——セッションをまたぐたびに同じ指摘を繰り返すことへの疲弊が、この手法を生んだ。agent.mdというファイル一つで、その繰り返しを断ち切れる。

LLMが生成するコードの「品質問題」

Fabien Sanglardは2025年半ばにLLMを使ったコーディングを初めて試みたが、生成されたコードはコンパイルすら通らなかったと振り返る。2026年1月の再挑戦では複雑なデータ構造の実装や難解なバグの特定など実用的な成果が出たが、コード品質は惨憺たるものだった。コメントもなく、構造もないスパゲッティコード。

その後、Antigravity（エージェント型コーディング環境の一つ）やVS Code の Claude Code プラグインといったツールを使うことで、生成されたコードに対して繰り返しフィードバックを与えながら改善するワークフローを確立した。しかし問題が残った。「マジックナンバーを使うな」「ここにコメントを追加しろ」といった指摘を、セッションが変わるたびに毎回繰り返す必要があったのだ。

agent.mdが解決策になった

多くのエージェント型IDEは、コーディングセッション開始時にプロジェクトルートのagent.md（またはgemini.md、claude.md）を読み込み、プロンプトに自動注入する仕組みを持っている。Sanglardはここに注目し、自分が繰り返し指摘していたルールを全てこのファイルに書き込んだ。

彼のagent.mdはプロジェクトルートに配置するだけで機能する。gemini.mdやclaude.mdはシンボリックリンクで一つのagent.mdに向けることで、どのプロジェクトでも共通設定を使い回せる。

ルールの中身：何が効いているか

ファイルに記載されているルールのうち、特に設計上の判断を要するものが面白い。

アクセス修飾子の変更を「設計上の破壊的変更」として扱うというルールがその一つだ。

Treat member visibility changes as a breaking design shift. Keep all fields and functions private unless external access is strictly required by the design. Prompt the user for explicit approval before changing any access modifier from private to internal or public.

LLMは何気なくprivateをpublicに変えがちだが、このルールがあると変更前に必ず確認を求めてくる。

関係のないコードに触れさせないというルールも実用的だ。

Don't touch blocks of code unrelated to the feature you implement. Don't add comments to a block of code if you did not create it or modify it. Minimize the number of changed lines when implementing a feature.

LLMはスコープ外のコードを「改善」しようとする傾向があり、レビューの負担が増える。このルールで差分を最小化できる。

その他のルールを列挙する：

• コメント・コミットメッセージは言葉を絞り、余計な賞賛を省く
• マジックナンバーは定数やenumに切り出す（ただし自明な一回限りの値はインラインのまま）
• ネストを減らす。Arrow Anti-Pattern（ネストが深くなるアンチパターン）を避け、early returnを活用する
• 関数名は30文字未満に
• boolean引数の代わりにenumを使う
• 論理ブロック間に空行を入れて読みやすくする
• if文が一行でも必ず{}を使う
• レイヤードアーキテクチャを守る：各レイヤーは直下のレイヤーとのみ通信し、UIがDBを直接叩くような「穴あけ」を禁止する
• バグ修正時はまずテストを書いて失敗を確認してから修正する（TDDの強制）

コミットメッセージについては7つのルールが明記されており、subject行を50文字以内に収める、命令形を使う、bodyには「何を・なぜ」を書くといった内容だ。

「コンテキスト希釈」という落とし穴

記事ではagent.mdの限界についても言及されている。会話が長くなるにつれてモデルがプロンプト中盤の指示に注意を払わなくなる現象だ。これは2つの話題を分けて理解するとわかりやすい。一方は、長いコンテキストの中盤に置かれた情報が見落とされやすいという現象で、Lost in the Middle（Liu et al., 2023）として論文に記録されている。もう一方は、Sanglardが実運用の中で感じた「会話が長くなるほど序盤のルール指示が薄まっていく」という経験的な観察であり、記事中では「コンテキスト希釈（attention dilution）」と表現されている。両者は密接に関連する現象だが、後者はSanglardが自らの言葉で整理した実感に近いものだ。なぜ起きるかはまだ十分に解明されていない。

Sanglardが見つけた対処法は2つ：

1. セッションを短く保つ。機能ごとに新しいセッションを開始する
2. コード品質が落ちてきたら「Reload agent.md」と打つ。これだけでルールが再注入される

また、agent.md自体のメンテナンスも手間にならないよう工夫している。新しいルールを追加したいときは、エディタを開かずにエージェント自身にagent.mdを更新させる。

まとめ

この手法の本質は、LLMへの繰り返しフィードバックを「知識として蓄積する場所」を作ることにある。Sanglard自身も「魔法の解決策ではない。LLMは依然としてハルシネーションを起こすし、コードは全て読まなければならない」と明言している。ただし集中すべき場所がアーキテクチャや設計に移った点が大きな変化だという。

agent.mdは仕組みとして単純だ。しかしその単純さが強みでもある。新しいツールを導入するのではなく、既存のワークフローにファイル一枚を差し込むだけで機能する。ルールは育てるものであり、セッションを重ねるほど自分のコーディングスタイルに合った設定が蓄積されていく。LLMとの共同作業を長期的に続けるなら、この「ルールの外部化」という発想は一度試す価値がある。

詳細はMy agent.md to improve LLM-assisted code qualityを参照していただきたい。