LLMのコード品質を爆上げする！「agent.md」活用術

LLMによるコード生成の品質に不満はありませんか？この「agent.md」を活用することで、AIに適切なコンテキストとガイドラインを与え、より実用的で高品質なコードを引き出すことができます。AIエージェントのパフォーマンスを最大化させるための設定ファイルとして、ぜひ導入してみてください。

これは結局、自分で解決しなきゃいけない問題だよ。例えばClaudeをもう1年近く使ってるけど、「アロー・アンチパターン」なんてコードを書くところは一度も見たことがない。それ以外の多くのことも、自分のプロジェクトでは単なる無駄な情報になりそうだし。エージェントへの指示っていうのは、プロジェクトごとに経験しながら学ぶのが一番だね。

こういうのはlintで強制すべきだよ。そうすれば手書きでコードを書いている人にも同じようなフィードバックが行くからね。例えば「if文が1行でも必ず{}を使う」とか「関数名は30文字以内で短く保つ」とか。あと、これが本当に作業の手戻りを生む原因になってる：「ブロックが『何』をするのか『なぜ』そうするのか、的を絞った小さなコメントを書く。可能な限り具体例を使って。システム全体を説明するならASCIIアートを提案して」……いや、「何」をやるかなんてコードを見れば分かるだろ。

AGENTS.mdにこの一行を入れるだけで、冗長な表現や仰々しい説明を減らす（あるいは無くす）のにかなり効果があったよ。

**常にASD-STE100（簡略化技術英語）を使用すること

補足：これ、どっかのHNの投稿で見かけたやつなんだけど、今すぐには見つけられないや。

せっかくAGENTS.mdを共有してるなら、自分のも載せておくよ。LLMにいいコードを書かせるなら、基本的にはこれで十分で、あとはプロジェクトごとに必要なものを追加すればいいからね。

収束ルール
全ての重要なタスクは、以下の3つの状態のいずれかで終了させること：

A. 成功：意図した機能が実際のパスで動作し、動機となるケースが具体的に改善された状態。

B. 有意義な進捗：機能は未完成だが、真のブロッカーが一つ取り除かれ、次のブロッカーが特定された状態。

C. 誠実な停止：これ以上の作業が過度なスコープ拡大、技術的負債、場当たり的なパッチ、あるいは複雑なロジックを招く場合。停止し、具体的な根拠とともに報告すること。

作業が収束しなくなったらパッチの作成を継続しないこと。

活動を成果と勘違いしないこと。失敗した試みが許されるのは、より狭い問題を残すか、より強力な証拠が得られたか、あるいは正当な停止理由がある場合のみ。

部分的な作業であっても、コードベースを以前よりクリーンで、読みやすく、診断しやすい状態にすること。

記事内のAGENTS.mdは、LLMエージェントがすでに知っていることを指示しているだけ（例えば「アロー・アンチパターン」より網羅的なswitch/match文を使うべきなのは大抵知っている）か、あるいは有害なもの（「関数名を短く」は恣意的で、読みにくくてレビューしづらい変な略称をLLMに書かせる原因になる）が多いように感じる。

素晴らしい記事だね。

特にここが気に入った：

「実装している機能に関係のないコードブロックには触れないこと。例えば、自分が作成も修正もしていないコードにコメントを追加しない。機能実装時は、変更行数を可能な限り最小限に抑えるよう努めること」

LLMに一つだけ修正を頼んだのに三つも勝手に変えちゃう現象、diffを見てるとよく気づくよ。

コードベースに対してLLMを使うなら、そもそもAGENTS.mdなんて意味あるの？

「あとは他の部分と同じように完成させて」って言えばいいだけじゃない？

それでも結局うまくやってくれないんだけどね。LLMのベストな使い方は、すごく具体的な指示だよ。「このバイトコードの評価器を書いて。もし書けなければ質問して」みたいに。

結局のところ究極の仕様言語はコードなんだから、TODOを書いて、関数のセマンティクスを記述するコメントを添えて、「よし、Codex、このTODOを埋めてくれ」ってやるのが一番だ。

読んでて面白いね。

これは13個のコード執筆ルール（「コードのインデントを減らす」から始めると最低16個になるけど）に、コミットメッセージの指示セットを足したものだね。コミットメッセージの方はスタイル特有で興味ないから無視したけど。

ルールの中の8～9個は不要だよ。基本的なCSの概念は、あえてエージェントに守らせる必要なんてない。例えば、明示的なインターフェースが必要だとか、早期リターンを活用せよなんて指示は不要だし。

曖昧な指示は役に立たない。「コードを読む人に呼吸をさせる」とか「インデントを減らす」なんて主観的すぎて、滅多に効果はないよ。使ってる言語の学習データに欠落があるのかもしれないけど、もし効果を測りたいなら、ルールを適用した時に文字列を出力させるようにしてみなよ。何が効いて何が効かないか、すぐにわかるから。

スタイルに関する選択肢が3～4個含まれてるのはいいと思う。

残りは自分が使うようなものじゃないけど、人それぞれ痛い目を見るポイントは違うから、言いたいことは分かるよ。

昔はAGENTS.mdファイルに熱を入れてたけど、最近のSOTA（最先端）モデルならもう必要ないって読んだよ。みんなまだ活用してるのかな？

これの一部は一般的なソフトウェア工学のアドバイスだよね。

最近のフロンティアモデル（Fable/Opus/Solとか）は、初期のモデルに比べれば手順ごとのコーチングは少なくて済むようになったと感じる。

本当にそれでコード品質が上がるのか、確証はあるのかな？

記事ではAGENT.mdとなってるけど、標準的な名前はAGENTS.md（複数形）だよ。