LLM支援のコード品質を向上させるためのagent.md

Fabien Sanglard - ウェブサイト 2026年8月21日 LLM支援のコード品質を向上させるためのagent.md 初めてLLMを使ってコーディングをスピードアップしようとしたのは2025年半ばでした。 私は感銘を受けませんでした。 当時、RustでmDNS実装であるlibadbmdnsに取り組んでいました。 生成されたコードはコンパイルすらできませんでした。 2026年1月にLLMを再訪しました。 今回はうまくいきました。 複雑なインデックス付きバイナリヒープクラスを書けただけでなく、Windows IOCP実装によるポーリングクレートのあいまいなバグを特定することもできました。 しかし、コード品質はひどいものでした。 コメントや構造のないスパゲッティコードでした。 クールでしたが、コードをクリーニングして本番レベルのバーを満たすためにスピードアップを失うのであれば、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）から来ている場合は、常に定数を使用してください。 コードのインデントを減らしてください。 アローアンチパターンを避けてください。 早期リターンと継続を活用してください。 関数名を短くしてください。 30文字未満。 関数パラメータにはブール値の代わりに列挙型を使用してください。 コードの読者に息抜きさせてください。 コードの論理ブロックの間に空行を追加してください。 ブロックが何をするのか、そしてなぜそうするのかを説明する、短く要点を押さえたコメントを追加してください。 可能な場合は例を使用してください。 完全なシステムを説明するためにASCII描画を提案してください。 メンバーの可視性変更は、破壊的な設計変更として扱ってください。 外部アクセスが設計によって厳密に要求されない限り、すべてのフィールドと関数をプライベートに保ってください。 プライベートから内部またはパブリックへのアクセス修飾子の変更を変更する前に、ユーザーに明示的な承認を求めてください。 抽象化のレベルでプログラムしてください。 低レベルのメカニズム（例：生のハードウェアI/O、セクター解析、直接ソケットストリーム）は、専用のドライバ/抽象化レイヤーにカプセル化する必要があります。 アプリケーションの残りの部分にクリーンで高レベルのAPIを公開して、呼び出しコードが生の実際の実装詳細ではなく、ドメインコンセプトで動作するようにしてください。 実装する機能に関係のないコードブロックには触れないでください。 例：作成または変更していないコードブロックにコメントを追加しないでください。 機能実装時に変更行数を最小限に抑えるようにしてください。 レイヤー境界階層に厳密に従ってください：各レイヤーは、そのすぐ下のレイヤーと直接通信できるだけです。 決してレイヤーを「穴を開けて」通過しないでください（例：コントローラーまたはUIコンポーネントは、データベースクエリ、生のハードウェアドライバ、または低レベルネットワーククライアントを直接呼び出してはなりません。常に中間サービス/抽象化レイヤーを経由してください）。 1行の「if」ステートメントでも、常に{}を使用してください。 コミットメッセージを書くときは、次の7つのルールに従ってください。 ルール1：件名行と本文を1つの空白行で区切ってください。 ルール2：件名行は50文字（絶対的なハードリミットは72文字）に制限してください。 ルール3：件名行の最初の文字を大文字にしてください。 ルール4：件名行の末尾にピリオドを付けないでください。 ルール5：件名行では命令法を使用してください（例：「バグを修正」、「機能を追加」、ではなく「修正済み」または「追加」）。 テスト式：それは文を完成させる必要があります：「適用される場合、このコミットは[あなたの件名行]を行います。」 ルール6：Gitフォーマットの問題を防ぐために、本文のテキストを手動で72文字で折り返してください。 ルール7：本文を使用して、何と理由を説明してください。コードが「どのように」を説明していると仮定してください。メッセージはコンテキストと理由を説明する必要があります。 プロンプトがバグが修正されていることを示している場合、すぐに修正を書き込まないでください。 まずテストを書いてください。 それが失敗するのを確認してください。 次に修正を書いてください。 そしてテストがパスするのを確認してください。 この「トリック」は生成されたコードを大幅に改善しましたが、コードを読むのを避けられる魔法の弾丸ではありません。 LLMは常に幻覚を起こし、信頼できません。 私はまだ検証とイテレーションをたくさん行う必要がありますが、今では通常、コードスタイルではなくアーキテクチャとデザインに焦点を当てています。 希釈への対処方法 「Lost in the Middle」論文で概説されているように、LLMには「コンテキスト希釈」または「アテンション希釈」と呼ばれる迷惑な現象があります。 コンテキストが長くなるにつれて、モデルはコンテキストの途中にある指示への注意を、最初と最後にあるものに有利に払わなくなります。 これが起こる理由は、現時点ではよく理解されていません。 影響を最小限に抑える方法は2つしか見つかりませんでした。 コンテキストを短く保ちます。これは、機能ごとに新しいセッションを開始することを意味します。 エージェントにagent.mdを再ロードするように明示的に依頼します。「agent.mdを再ロード」は、コード品質が低下しているのを確認したときに十分です。 agent.mdの自動更新 新しいルールを追加したいときに毎回エディタを開く必要はありません。 私が今やっていることは、エージェントにagent.mdを更新するように依頼することです。 *