LLM支援のコード品質を向上させるためのagent.md
My agent.md to improve LLM-assisted code quality (fabiensanglard.net)
要約
LLMによるコーディング支援の初期はコンパイルエラーや低品質なコードに悩まされたが、2026年初頭には複雑なデータ構造の実装やバグ発見が可能になった。しかし、コードの可読性や保守性が課題であった。その後、エージェント型IDEの導入により、コード品質は向上したが、定型的な指示の繰り返しが煩雑だった。この問題を解決するため、プロジェクトのルートに配置する「agent.md」ファイルにコーディングスタイルや指示を記述することで、LLMの出力を一貫して高品質に保つ手法が提案されている。
全文翻訳
LLM支援コード品質向上のためのagent.md
2026年8月21日
LLM支援コード品質向上のためのagent.md
LLMを使ってコーディングを高速化しようとしたのは、2025年半ばが初めてでした。感銘は受けませんでした。当時はRustでmDNS実装であるlibadbmdnsに取り組んでいました。生成されたコードはコンパイルすらできませんでした。
2026年1月にLLMを再検討しました。今回はよりうまく機能しました。複雑なインデックス付きバイナリヒープクラスを作成できただけでなく、Windows IOCP実装によるpollingクレートのあいまいなバグを特定することさえできました。
しかし、コード品質はひどいものでした。コメントも構造もなく、スパゲッティコードでした。クールではありましたが、LLMで得られる速度向上が、コードを本番レベルの基準に達するまでクリーンアップするのに費やされてしまうのであれば、現実的ではありませんでした。
繰り返し、何度も繰り返す
2026年3月、AntigravityやVS CodeのClaude CodeプラグインのようなエージェントIDEを試しました。「ステージング」されたコードを「イテレート」できるようになりました。「マジックナンバーを使わないで」「ここに短いコメントを追加して説明して」「短い関数名を使って」といった提案を、無限に忍耐強いジュニアCS専攻の学生にレビューしてもらうような状況になりました。
コード品質は劇的に向上しました。私が「手作業」で作成したものに非常に近いものでしたが、退屈でした。新しいセッションごとに、何度も同じことを繰り返すことになりました。
agent.mdが救世主に
コーディングセッションが開始されると、コーディングハーネスはagent.mdという名前のファイルをロードし、それをプロンプトに注入します。これは、コーディングスタイルの好みを微調整するのに最適な場所です。コードを改善するために同じ提案を繰り返していることに気づいたとき、私はそれをそこに加えました。
必要であれば、私のagent.mdバージョンを起点として利用できます。プロジェクトのルートに配置するだけで十分なはずです。あるいは、gemini.md/claude.mdをagent.mdにシンボリックリンクすることで、どこでもアクティブにすることができます。
# FAB's AGENT.MD
- 人間が消費することを意図したものを書くとき(コメント、コミットメッセージ、プロンプトへの返信)、可能な限り少ない言葉を使用してください。音量を厳密な最小限に抑えるために、すべての単語を慎重に選択してください。要点を押さえてください。少ないほど良いです。
- 最上級や賞賛を避けてください。私が絶対に正しいと言うのをやめてください。冷徹な真実を教えてください。
- 繰り返し現れる、または意味のある値を説明的な定数(const)または列挙型(enum)に抽出して、マジックナンバーや文字列を避けてください。自己説明的な、一度限りの値は、乱雑さを避けるためにインラインで保持してください。値が仕様(例: HTTP 200 OK)から来る場合、いずれにせよ定数を使用してください。
- コードのインデントを減らしてください。アローアンチパターンを避けてください。早期リターンとcontinueを活用してください。
- 関数名を短く保ってください。30文字未満。
- 関数パラメータには、ブール値の代わりに列挙型を使用してください。
- コードの読者が呼吸できるようにしてください。コードの論理的なブロックの間に空行を追加してください。
- ブロックが*何*をするのか、そして*なぜ*するのかを説明する、短く要点を押さえたコメントを追加してください。可能な場合は例を使用してください。完全なシステムを説明するためにASCII描画を提案してください。
- メンバーの可視性の変更は、破壊的な設計変更として扱ってください。外部アクセスが設計によって厳密に要求されない限り、すべてのフィールドと関数をプライベートに保ってください。アクセス修飾子をプライベートから内部またはパブリックに変更する前に、ユーザーに明示的な承認を求めてください。
- 抽象化のレベルでプログラムしてください。低レベルのメカニズム(例: 生のハードウェアI/O、セクター解析、直接ソケットストリーム)は、専用のドライバ/抽象化レイヤーにカプセル化する必要があります。アプリケーションの残りの部分には、クリーンで高レベルなAPIを公開して、呼び出しコードが生の С implementação details ではなく、ドメインコンセプトで動作するようにしてください。
- 実装する機能に関連しないコードブロックには触れないでください。例: コードブロックを作成または変更しなかった場合、そのコードブロックにコメントを追加しないでください。可能な限り、機能を実装する際に変更される行数を最小限に抑えるようにしてください。
- レイヤー境界階層に厳密に従ってください: 各レイヤーは、直接下の隣接レイヤーとのみ通信できます。レイヤーを「穴を開けて」通過しないでください(例: コントローラーまたはUIコンポーネントは、データベースクエリ、生のハードウェアドライバ、または低レベルネットワーククライアントを直接呼び出すことは決してありません。常に中間サービス/抽象化レイヤーを経由してください)。
- 1行の「if」ステートメントでも、常に{}を使用してください。
コミットメッセージを書くときは、次の7つのルールに従ってください:
ルール1: 件名行と本文を1つの空行で区切ってください。
ルール2: 件名行は50文字に制限してください(72文字が絶対的なハードリミットです)。
ルール3: 件名行の最初の文字を大文字にしてください。
ルール4: 件名行の末尾にピリオドを付けないでください。
ルール5: 件名行では命令法を使用してください(例: 「バグを修正」「機能を追加」ではなく、「修正済み」や「追加」ではありません)。テスト式: 「適用された場合、このコミットは[あなたの件名行]を行います」という文を完了する必要があります。
ルール6: Gitフォーマットの問題を防ぐために、本文テキストを72文字で手動で折り返してください。
ルール7: 本文を使用して、何と理由を説明してください。コードが「どのように」を説明すると仮定してください。メッセージはコンテキストと理由を説明する必要があります。
- プロンプトでバグが修正されていることが示されている場合、すぐに修正を記述しないでください。まずテストを記述してください。それが失敗するのを観察してください。次に修正を記述してください。そしてテストがパスするのを観察してください。
この「トリック」は生成されたコードを大幅に改善しましたが、コードを読むことを避けられる魔法の弾丸ではありません。LLMは常に幻覚を見ますし、信頼できません。私はまだ検証と多くのイテレーションを行う必要がありますが、今ではコードスタイルではなく、アーキテクチャとデザインに焦点を当てることが多いです。
希釈への対処方法
LLMには「コンテキストの希薄化」または「注意の希薄化」と呼ばれる厄介な現象があり、Lost in the Middle論文で概説されています。コンテキストが長くなるにつれて、モデルはコンテキストの途中にある指示への注意を、最初と最後にあるものに有利に払わなくなります。これが起こる理由は、私がこれを書いている時点ではよく理解されていません。影響を最小限に抑える方法は2つしか見つかっていません。
- コンテキストを短く保ちます。これは、機能ごとに新しいセッションを開始することを意味します。
- 明示的にハーネスにagent.mdをリロードするように依頼します。コード品質が低下しているのを見たら、「agent.mdをリロード」で十分です。
agent.mdの自動更新
新しいルールを追加したいときに毎回エディタを開く必要はありません。私が今やっていることは、エージェントにagent.mdを更新するように依頼することです。