AIエージェント時代のコーディングテクニック「コーディングルールをAGENTS.mdにまとめる」「品質が低下したらAGENTS.mdの読み直しを指示」

AIエージェント時代向けのコーディングテクニックを、エンジニアのファビアン・サングラール氏が紹介しています。

My agent.md to improve LLM-assisted code quality
https://fabiensanglard.net/agent.md/index.html

2025年半ば頃から大規模言語モデル(LLM)を用いたコーディングに取り組むようになったというサングラール氏は、「当時は(AIによる効果に)感銘を受けなかった」と記しています。しかし、2026年1月に使用するLLMを再検討したところ、複雑なインデックス付きバイナリヒープクラスを生成できただけでなく、Windows IOCPの実装に起因するポーリングクレートの分かりにくいバグを特定することにも成功したと報告しています。

それでもコードの品質はひどいもので、「コメントも構造もないスパゲッティコードだった」とサングラール氏は語りました。当時を振り返り、「LLMを使うのは確かに魅力的でしたが、本番環境レベルの基準を満たすまでコードを整理すると、せっかくのスピードアップ効果がほとんど無駄になってしまいました。つまり、実用には現実的ではありませんでした」と記しています。

2026年3月、サングラール氏はGoogle AntigravityやVS Code、Claude Codeといったエージェント型の統合開発環境(IDE)を利用してみたそうです。エージェント型IDEの使用により、ステージングされたコードを反復できるようになったとサングラール氏は述べました。

すると、AIエージェントの生成するコードのレベルは「忍耐強いコンピュータサイエンス専攻の大学3年生の学生が書いたコード」にまでパワーアップ。自動生成されるコードの品質は劇的に向上し、手作業で作成したものとほぼ同等のレベルに達したそうです。ただし、新しいセッションごとに同じことを何度も繰り返すなど、「非常に面倒だった」とサングラール氏は評しています。

そこで、サングラール氏はAIコーディングエージェント向けのREADMEとなる「AGENTS.md」を自作。AGENTS.mdはプロジェクトのルートディレクトリに配置するか、gemini.md/claude.mdからAGENTS.mdへのシンボリックリンクを作成することで、どこからでもAGENTS.mdを有効にすることができます。

サングラール氏が自作したAGENTS.mdは以下からチェック可能です。

fabiensanglard.net/agent.md/agent.md
https://fabiensanglard.net/agent.md/agent.md

サングラール氏が自作したAGENTS.mdには以下のようなルールが設定されています。

・人間が読むことを目的とした文章(コメント、コミット メッセージ、プロンプトへの返信)を書くときは、できるだけ少ない言葉を使用してください。すべての言葉を慎重に選び、量を厳密かつ最小限に抑えます。要点を絞ってください。少ないほど良いです。
・最上級や賞賛は避けてください。私が完全に正しいと言うのもやめてください。冷酷な真実を教えてください。
・繰り返し出現する値や意味のある値を記述定数(const)または列挙型に抽出して、マジックナンバーやマジックストリングを避けてください。自己説明的な一回限りの値はインラインで保持し、煩雑さは避けてください。値が仕様(例：HTTP 200 OK)から取得される場合、定数を使用してください。
・コードのインデントを減らしてください。アローアンチパターンを避けてください。早期リターンと継続を活用してください。
・関数名は短くしてください。30文字未満です。
・関数パラメータにはブール値ではなく列挙型を使用してください。
・コードの読者に息抜きをさせてください。論理的なコードブロックの間に空行を追加してください。
・ブロックが何をするのか、なぜそうするのかを説明する簡潔で要点を押さえたコメントを追加してください。可能な場合は例を使用し、システム全体を説明するためにアスキー図を提案してください。
・メンバーの可視性の変更は、破壊的な設計変更として扱います。外部からのアクセスが設計上厳密に必要な場合を除き、すべてのフィールドと関数をプライベートにします。アクセス修飾子をプライベートから内部またはパブリックに変更する前に、ユーザーに明示的な承認を求めます。
・抽象化レベルに合わせてプログラミングします。低レベルのメカニズム(例：生のハードウェアI/O、セクター解析、直接ソケットストリーム)は、専用のドライバ/抽象化レイヤーにカプセル化する必要があります。呼び出し元のコードが生の実装の詳細ではなく、ドメインの概念で動作するように、クリーンで高レベルのAPIをアプリケーションの残りの部分に公開します。
・実装する機能に関係のないコードブロックには手を加えません。例えば、作成または変更していないコードブロックにはコメントを追加しません。機能を実装するときは、変更する行数をできるだけ最小限に抑えます。
・階層化された境界レイヤーに厳密に従います。各レイヤーは、その直下の隣接レイヤーとのみ通信できます。レイヤーに「穴を開ける」ことは決してしないでください。(例：コントローラーやUIコンポーネントは、データベースクエリ、ハードウェアドライバ、低レベルのネットワーククライアントを直接呼び出してはいけません。常に中間サービス/抽象化レイヤーを介してルーティングします)
・コミットメッセージを作成する場合は、以下のルールに従ってください。
ルール 1：件名行と本文を1行の空白行で区切る。
ルール 2：件名行は50文字に制限する。
ルール 3：件名行の最初の文字を大文字にする。
ルール 4：件名行をピリオドで終了しない。
ルール 5：件名行では命令法を使用する。
ルール 6：Gitの書式設定の問題を防ぐため、本文を72文字で手動で折り返す。
ルール 7：本文を使用して、方法ではなく、何となぜを説明するようにする。コードが方法を説明すると想定し、メッセージはコンテキストと理由を説明する必要がある。
・プロンプトがバグ修正中であることを示している場合、すぐに修正を書かないでください。まずテストを書いて、それが失敗することを確認してから修正を書き、テストが合格することを確認してください。

サングラール氏は「AGENTS.mdを自作することでコードの質は大幅に向上した」と説明していますが、コードを読む手間を省ける魔法の解決策ではないそうです。「LLMは常に誤った情報に基づいて動作するため、検証と反復作業は依然として必要ですが、コードスタイルよりもアーキテクチャと設計に重点を置くようになりました」と記しています。

また、LLMには「コンテキスト希釈(context dilution)」と呼ばれる厄介な現象があります。これは、コンテキストが大きくなるにつれ、モデルはコンテキストの中間の指示への注意を減らし、最初と最後の指示を優先するようになるというものです。なぜコンテキスト希釈が起きるのかは記事作成時点では明らかになっていませんが、影響を最小限に抑える方法は以下の2つしか見つかっていません。

1：コンテキストは簡潔にしてください。つまり、機能ごとに新しいセッションを開始してください。
2：ハーネスにAGENTS.mdの再読み込みを明示的に指示してください。コード品質が低下している場合は、「AGENTS.mdを再読み込み」と入力するだけで十分です。

そして、新しいルールを追加するたび、エージェントにAGENTS.mdを更新するよう指示することで、AGENTS.mdを手動で更新する必要もなくなります。