agent.md による LLM 支援コード品質の向上

agent.md ファイルを使用することで、開発者は永続的なスタイルの好みやアーキテクチャの制約を LLM のプロンプトに直接注入でき、人間の役割を基本的なコードスタイルの修正から、高レベルな設計に集中させることへとシフトさせることができます。このアプローチは、AI 支援によるコーディングセッション中の、退屈な手動フィードバックの繰り返しを軽減します。

agent.md フレームワーク

agent.md ファイルは、プロジェクトルートの構成ファイルであり、agentic IDE やコーディングハーネスによって自動的に読み込まれ、LLM の動作を微調整するために使用されます。新しいセッションごとに同じスタイルの修正を繰り返す代わりに、開発者はこれらの要件を単一の真実のソース（single source of truth）としてコード化できます。

コアコーディング標準

プロダクションレベルのコード品質を確保するために、agent.md ファイルには以下のルールを推奨します：

簡潔さ: コメント、コミットメッセージ、およびプロンプトへの返答において、できるだけ少ない言葉を使用してください。賞賛や最上級表現は避けてください。
クリーンコードの実践:
- 「マジックナンバー」を避けるため、繰り返し使用される値や意味のある値を、記述的な定数または enum に抽出してください。
- 「Arrow Anti-Pattern」を避けるため、早期リターン（early returns）や continue 文を活用してインデントを減らしてください。
- 可視性: すべてのフィールドと関数はデフォルトで private にしてください。アクセス修飾子を internal または public に変更する場合は、明示的な承認を求めてください。
アーキテクチャと抽象化:
- 低レベルのメカニズム（例：生のハードウェア I/O、ソケットストリーム）を、専用のドライバレイヤーにカプセル化してください。
- 各レイヤーが直下の隣接レイヤーとだけ通信する、厳格なレイヤー境界の階層に従ってください。
ドキュメンテーション: ブロックが「何」を行い、「なぜ」行うのかを簡潔に説明するコメントを追加してください。複雑なシステムについては、例や ASCII アートを使用してください。
テスト: バグを修正する場合、LLM はまず失敗するテストを書き、失敗を確認した後、修正を書き、それがパスすることを確認しなければなりません。

コミットメッセージ標準

クリーンな Git 履歴を維持するために、agent.md ファイルではコミットメッセージに関する 7 つのルールを強制できます：

件名行と本文を空行で区切ってください。
件名行を 50 文字以内に制限してください（最大 72 文字）。
件名行の最初の文字は大文字にしてください。
件名行をピリオドで終わらせないでください。
命令形（例：「Fix bug」）を使用してください（「Fixed bug」ではなく）。
本文を 72 文字で手動で折り返してください。
本文を使用して、「どのように」ではなく「何」と「なぜ」を説明してください。

コンテキストと希釈化の管理

コンテキストウィンドウが大きくなるにつれて、LLM は「コンテキストの希釈化」（または「アテンションの希釈化」）に陥ります。これは、プロンプトの中間に位置する指示に対して、モデルが注意を払わなくなる現象です。この現象は「Lost in the Middle」の研究論文で記録されています。

これを軽減するために、開発者は以下のことを行うべきです：

セッションの長さを制限する: コンテキストを短く保つため、個々の機能ごとに新しいセッションを開始してください。
強制リロード: コード品質が低下し始めたら、エージェントに対して明示的に「Reload agent.md」と命じてください。
自動更新: セッション中に新しいルールが発見された場合、AI エージェント自身に agent.md ファイルを更新するよう求めてください。

コミュニティの視点と批判

agent.md のアプローチは一部の人には効果的ですが、開発者コミュニティからは、その実装に関するいくつかの反論が提起されています：

"A bunch of these should be enforce with linting... The what is the code."

批判的な意見を持つ人々は、多くのルール（例：1 行の if 文に中括弧を使用することや、関数名の長さを制限することなど）は、プロンプトの指示よりも自動化されたリンターによって処理されるべきであると主張しています。他の開発者は、agent.md ファイルが肥大化しすぎると、実際にコンテキストの消費を増やし、パフォーマンスを低下させると示唆しています。

コミュニティからの追加の提案は以下の通りです：

関心の分離: コーディング標準を CODING_STANDARDS.md ファイルに移動し、agent.md はインタラクションの好みに特化したものにします。
収束ルール: AI が際限なく脆いパッチを生成し続けるのを防ぐため、すべてのタスクが「成功（Success）」、「意味のある進展（Meaningful Progression）」、または「正直な停止（Honest Stop）」のいずれかの状態のいずれかで終了しなければならないという「収束ルール（Convergence rule）」を実装する開発者もいます。
簡略化されたテクニカル・イングリッシュ: AI の冗長さをさらに抑えるために、「ASD-STE100 Simplified Technical English」に従うよう指示を出します。