LLM生成コードの品質を劇的に上げた「agent.md」——Fabien Sanglardが公開した設定ファイルの中身

コードスタイル関連のすべてをCONTRIBUTING.mdに、「どう話しかけるか」をAGENTS.mdに入れることに何か欠点があるだろうか？コードスタイルは人間の貢献にも適用されるからだ。同様に、「どう話しかけるか」は個人的なものであり、リポジトリに属するものではないのではないか？

> - 関数名は短く保つ。30文字未満。

最近、GPTにブラウザゲームをRustに移植するよう頼んだんだ。そしたらこんな素晴らしい関数名を自ら提案してきた：

draw_image_with_html_image_element_and_sw_and_sh_and_dx_and_dy_and_dw_and_dh(...)

なにか良いものでも吸ってるのかと思ったよ。でも、それが実際に関数の名前だったんだ！

https://docs.rs/web-sys/latest/web_sys/struct.CanvasRenderin...

内容の割にコンテキストが多いね。私はだいたいこんな感じで始める：

- ドキュメントはコードとして書くことを好む

- コメントは「なぜ」を書く、「何」を書かない

- 公開APIを文書化する

- 可読性が最優先

これでだいたい80%は達成できる。残りはlinterがカバーしてくれる。

ただ、特に計画を編集するときに、以前の状態を説明しすぎることが多いのが欠けている点だ。でも、それに対する良い言い回しはまだ見つけていない。

AGENTS.mdを共有しているので、私も自分のものを共有しようと思う。ほとんどの場合、LLMに良いコードを書かせるにはこれだけで十分で、それ以外はプロジェクトごとに追加すればいい：

----

*収束ルール*

すべての実質的なタスクは、次の3つの状態のいずれかで終了しなければならない：

A. 成功

意図した機能が実際のパスで動作し、実際の動機となるケースが実質的に改善される。

B. 意味のある前進

機能は完了していないが、真のブロッカーが1つ取り除かれ、次のブロッカーが証拠とともに特定されている。

C. 正直な停止

さらなる作業には、過度に広い範囲の拡大、過剰な負債、脆いパッチ、または絡み合ったロジックが必要となる。停止し、具体的な証拠とともに理由を報告する。

作業が収束しなくなったら、パッチを生成し続けてはならない。

活動と進歩を混同してはならない。失敗した試みは、より狭い問題、より強い証拠、または正当な停止を残す場合にのみ許容される。

部分的な作業は、コードベースを以前よりもクリーンで、読みやすく、診断しやすい状態にしなければならない。

----

記事のAGENTS.mdの多くは、LLMエージェントに既に知っていることを伝えているだけ（例えば、ほとんどの場合、「アローアンチパターン」の代わりに網羅的なswitch/match文を使うことを知っている）か、あるいは積極的に有害に見える（「関数名を短く保つ」は恣意的で、LLMが読みにくくレビューしにくい奇妙な略語を書く原因になるかもしれない）。

「人間が読むことを意図したもの（コメント、コミットメッセージ、プロンプトへの返答）を書くときは、できるだけ少ない言葉を使うこと。すべての単語を細心の注意を払って選び、量を厳格な最小限に減らすこと。要点を簡潔に。少ない方が良い。」

この最初の段落が、簡潔さについて同じメッセージを伝えるために多くの言葉と多くの方法を使っているのは皮肉だ。しかし、このファイルは人間が消費するためのものではないので、異なるルールが（まだ？）適用されるべきかもしれない。

私はプロンプトでこれをやっている自分に気づく。おそらく、強調が必要だと思うコンテキストの部分に重みを加える方法であり、一度言っただけではLLMがメッセージを理解できないという信頼の欠如を示している。

こういうのを読むのは面白いね。

これは13のコード記述ルール（少なくとも16と解釈される - コードのインデントを減らすことから始まる）と、コミットメッセージの指示セットと表現できるだろう。コミットメッセージの指示は、スタイル固有で私には興味がないので無視することにした。

これらのルールのうち8つか9つは必要ない。基本的なCSは、私が使うエージェントに従うように頼んだことはない。例えば、明示的なインターフェースが必要だと説明することは必要な指示ではないし、早期リターンを活用することも同様だ。

不明確な指示は限られた有用性しかない。「コードを読む人に呼吸させろ」や「コードのインデントを減らせ」が何を意味するかは主観的で、効果的であることはめったにないだろう。おそらく、使用している言語のトレーニングにギャップがあり、他の言語にはないのかもしれない。測定したいなら、ルールを適用したときに文字列を出力するように頼めばいい。何が機能し、何が機能しないか、そしてどのくらいの頻度でかをすぐに理解できるだろう。

含まれているスタイルの選択肢は3つか4つある。

残りは私が使うようなものではないが、私たちは皆、異なることで痛い目に遭うので、理解はできる。

素晴らしい内容だ。ただし、AGENTS.mdはそのほとんどにとって理想的な場所ではない。この記事で示されているもののほとんどはCODING_STANDARDS.mdに入れることができる。私が使っているスキルは、このドキュメントを必要なとき（コードの作成とレビュー）に見つけるので、コードを読んでいるときにコンテキストを汚染することはない。

また、サブエージェントによるレビュー（計画フェーズと生成されたコードの両方）もあり、これらの問題のいくつかを検出して修正を要求するだろう。[1]

> - プロンプトがバグ修正を示している場合、すぐに修正を書かないでください。まずテストを書いて、それが失敗するのを確認してください。それから修正を書いて、テストが通るのを確認してください。

私はいつも/tdd [2]を使う。時々、ばかげたテストになることもあるが、はるかに欠陥の少ないコードを生成する。バグだけのためではない。

[1] https://github.com/gregwebs/skills-sdlc/

[2] https://github.com/mattpocock/skills/blob/main/skills/engine...