Japanese Translation:

本文では、生成された Rust コードがコンパイル失敗したり構造を失った ("スパゲッティ") という初期の困難を経て、LLM 支援によるコード品質を改善するためのプロンプトベースのソリューション"Agent.md"を紹介する。2026 年 3 月に agentic IDE が導入されて反復が可能になったとしても、まだ「マジックナンバーを避ける」「関数名を短くする」などの手動で繰り返し提案が必要だった。一方、Agent.md はプロンプトに直接注入されることで、簡潔なコメント/コミットメッセージを使用する；マジックナンバーではなく定数または列挙型として再帰的な値を抽出する；関数名は 30 キャラ以内とする；パラメータに対してはブール値よりも列挙型を優先する；そして制御層・UI がデータベースクエリや生ハードウェアを直接呼び出さないよう層境界階層を厳守するなど、スタイル好悪とルールを直接的にコード化する。コミットメッセージの規約は、主題と本文を分けること、主題は 50 キャラ以下（絶対値 72 キャラ）であり命令法で記述し、本文は 72 キャラで折り返し、実行内容・理由の説明を行うが「どのように」ではなく「何を・なぜ」に焦点を当てることで定義される。文脈の希薄化を軽減するためには、機能ごとに新しいセッションを開始するか、コード品質が低下した際にハネスに agent.md を再読み込みすることを明示的に依頼することが推奨される。さらに、エージェントに agent.md の自動更新を依頼し、手動編集を回避することも可能である。これにより、Agent.md は人間の手間を最小限に抑えつつ高品質なコード維持を実現する、自律的かつ持続可能な AI 支援開発プロセスへと開発を簡素化する。

LLM を活用してコード品質を向上させるための「agent.md」実践記

1. 経緯：期待と課題の浮き沈み

2025 年中頃（第 1 次挑戦）
- Rust で書かれた mDNS インプリメンテーション
```
libadbmdns
```
  を対象に試行。
- 結果: LLM が生成したコードはコンパイルすらできない状態でした。期待外れの結果となりました。
2026 年 1 月（第 2 次挑戦）
- 結果改善: コード品質が格段に向上。
  - 複雑なインデックス付きバイナリーヒープクラスの記述が可能に。
  - Windows IOCP インプリメンテーションにおける極めて稀なバグまで特定できた。
課題の再発見（2026 年春）
- コード品質は依然として低水準。スパゲッティ・コード（コメントなし、構造不備）。
- 開発速度の向上メリットが、生成後のクリーンアップ作業で相殺されてしまう現実。

2. 転換点：反復的なレビューによる改善

2026 年 3 月からの取り組み
- Antigravity や VS Code の Claude Code プラグインなどのエージェント型 IDEを活用開始。
- 「ステージ化されたコード」に対して「反復的に処理」というワークフローへ移行。
手法：無限の忍耐力を持つレビュアーの模倣
- マジックナンバーの使用禁止
- 部分へのコメント追加指示（自己説明）
- 関数名の短縮指示
成果と残る課題
- コード品質は劇的に改善し、手作業作成レベルに近づく。
- しかし、同じ指摘を各セッションで繰り返すため、プロセス自体が面倒。

3. 「agent.md」の導入による自動化

基本コンセプト

ハネス（コーディング支援環境）は
```
agent.md
```
を読み込み、プロンプトにインジェクトする。
コーディングスタイルの好みを微調整するための最適な場所。
必要に応じてプロジェクトルートディレクトリに配置するか、
```
gemini.md
```
や
```
claude.md
```
をシンmlink することで有効化可能。

設定ファイル：FAB's AGENT.MD

以下のルールを定義し、生成されるコード品質を著しく向上させる。

コーディングスタイルの徹底

文章と記述:
- 人間向けの文書（コメント、コミットメッセージなど）は言葉を節約する。
- 要点のみを伝え、「少なくても多くが生まれる」意識を持つ。
- 超絶表現や称賛は避け、冷たい事実だけを提示する。
定数と変数:
- マジックナンバーや文字列を避ける。
- 反復利用される値は説明的な定数(
```
const
```
  ) または
```
enum
```
  に抽出する。
- 仕様由来の値（例：HTTP 200 OK）は例外なく定数とする。
制御フロー:
- インデント量を削減し、Arrow パターンを避ける。
- 早期リターンと継続 (
```
continue
```
  ) を活用する。
- 単一行の
```
if
```
  文であっても必ず
```
{}
```
  を使用する。
関数・パラメータ:
- 関数名は30 文字以内に収める（短くする）。
- パラメータにはブール値ではなく
```
enum
```
  を使用し、意味を明確にする。
可読性:
- 論理的なコードブロックの間に空行を挿入する。
- ブロックの説明は簡潔かつ要点を押さえたコメントで付ける（例示や ASCII 図案も推奨）。

アーキテクチャと設計原則

メンバー可視性:
- 全てのフィールドと関数はデフォルトで
```
private
```
  と保つ。
- 外部アクセスが必要な場合は明確な理由を示す。
- ```
private
```
  から
```
internal/public
```
  への変更は、ユーザーからの明確な承認を得るまで行わない。
アブストラクション:
- 下位機構（ハードウェア I/O、セクタ解析など）は専用ドライバまたはレイヤーにカプセル化し、上層にはクリーンな API を公開する。
レイヤー境界の厳守:
- 各レイヤーは直下の近接レイヤーのみと通信する。
- 「穴を開ける」行為（コントローラーが直接 DB クエリを実行するなど）は一切禁止。常に中間サービス経由とする。
保守性:
- 実装する機能以外のコードブロックには手を触れない（既存ブロックへのコメント追加も避ける）。
- 変更行数を可能な限り最小化する。

コミットメッセージの規則

Git コミットメッセージを作成する際は、以下の7 つのルールを厳守する：

サブジェクト行と本文は単一空白行で区切る。
サブジェクト行は50 文字以内（上限 72 文字）に制限し厳格に守る。
サブジェクト行の頭文字を大文字にする。
サブジェクト行は句読点で終わらせない。
命令法を用いる（例：「修正済みの」ではなく「修正する」）。検証式文脈に適合する必要がある。
本文は手動で72 文字ごとに改行し、Git フォーマティング問題を回避する。
「何をして、なぜやったか」を説明。「どのように」はコード自体が担当する。

重要なワークフローの「トリック」

バグ修正時の手順:
- プロンプトにバグ修正指示が出た場合、即座に修正コードを書くのを待つ。
- まずテストを書き、失敗を確認してから、修正コードを追加しテストをパスさせる。

4. 注意点と限界

LLM の性質:
- コード品質向上は「魔法」ではなく、検証と反復作業が常に必要。
- LLM は幻覚を起こしやすいため、完全な自動依存は非現実的。
アーキテクチャへの集中:
- この手法により、低レベルのコード確認から解放され、アーキテクチャや設計に焦点を当てられるようになった。

5. 「コンテキスト希薄化」への対処法

現象:
- コンテキストが長くなるほど、モデルは指示よりも前後の部分を重視する（Lost in the Middle）。
対策策:
- コンテキストを短く保つ: 各機能ごとに新しいセッションを開始する。
- 明示的なリロード: ハネスに
```
agent.md
```
  を再読み込みさせる。
  - コード品質が低下している場合、**「agent.md を再読み込み」**と入力することで改善可能。

6. まとめ：agent.md の自動更新

新しいルールを追加しても、エディタを頻繁に開く必要はありません。
アーティスト（エージェント）に対して
```
agent.md
```
の更新を直接依頼するだけで、最新の実践規則が適用されます。

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