我的 agent.md：提升 LLM 代码质量
My agent.md to improve LLM-assisted code quality
2025 年我第一次尝试用 LLM 加速编码时，生成的代码甚至无法编译。2026 年初情况好转，但代码质量依然糟糕，全是缺乏注释的意大利面代码。后来我尝试了 Antigravity 和 VS Code 的 Claude Code 插件，虽然能迭代改进，却不得不反复重复同样的建议。最终，我通过定制 agent.md 文件解决了这个问题。我在项目根目录放置了这份配置文件，详细规定了代码风格、命名规范、分层架构以及 Commit 消息的七条铁律。现在，LLM 能生成接近生产级别的代码，让我能专注于架构设计而非琐碎的格式调整。虽然 LLM 仍会幻觉，但 agent.md 显著减少了上下文稀释的影响，让协作更高效。
虽然这个技巧显著提升了生成的代码质量，但它并非让我可以跳过阅读代码的灵丹妙药。
HN 评论区
171- OptionOfT
其中不少规则应该通过 linting 来强制执行，这样那些仍然手写代码的人也能得到同样的反馈，例如：始终使用 {}，哪怕是在单行的 if 语句中。以及：保持函数名简短，少于 30 个字符。
但下面这条规则确实制造了大量无谓的改动：
- 添加简短、切题的注释，解释代码块的作用和原因。尽可能使用示例。提议用 ASCII 绘图来解释完整系统。
代码本身就已经说明了“是什么”。
- imjonse
“在撰写供人类阅读的内容时（注释、提交信息、对提示的回复），请使用尽可能少的词。精心挑选每一个词，将篇幅压缩到严格的最小值。直奔主题。少即是多。”
讽刺的是，第一段话本身就用了很多词，用多种方式传达了关于简洁性的同一信息。不过这份文件并非供人类阅读，所以不同的规则或许（仍然）适用。
我发现自己在写提示时也会这样做，我想这是一种给我们认为需要强调的上下文部分增加权重的方法，同时也表明我们不信任 LLM 在只提及一次时就能领会意图的能力。
- andai
> - 保持函数名简短。少于 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...
- YuechenLi
既然我们在分享 AGENTS.md，我也想分享一下我的，因为大多数时候，这些内容就足以让 LLM 写出好代码，其他内容可以按项目添加：
----
*收敛规则*
每个实质性任务必须最终处于以下三种状态之一：
A. 成功
预期的功能在实际路径中正常工作，且实际驱动用例得到了实质性改善。
B. 有意义的进展
功能尚未完成，但已移除一个真正的阻碍，并隔离了下一个阻碍，且有证据支持。
C. 诚实的停止
进一步工作将需要过度扩大范围、产生过多债务、打脆弱的补丁或导致逻辑纠缠。停止工作并报告具体原因及证据。
一旦工作不再收敛，就不要继续生成补丁。
不要将活动误认为进展。失败的尝试只有在留下了更窄的问题、更强的证据或合理的停止理由时才是可接受的。
任何部分工作都必须使代码库比之前更干净、更易读、更易于诊断。
----
文章中提到的很多 AGENTS.md 内容，感觉要么是在告诉 LLM 代理它们已经知道的事情（例如，大多数时候它们知道要使用穷尽的 switch/match 语句，而不是“箭头反模式”），要么似乎具有主动危害性（“保持函数名简短”显得武断，可能导致 LLM 写出难以阅读和审查的怪异缩写函数名）。
- gregwebs
很棒的内容。不过 AGENTS.md 并不是放置其中大部分内容的理想位置。本文展示的大部分内容都可以放在 CODING_STANDARDS.md 中。我使用的技能会在需要时（编写和审查代码）找到这份文档，因此不会在读取代码时污染上下文。
我还有子代理审查（包括规划阶段和生成的代码），它们能发现其中一些问题并要求修改。[1]
> - 如果提示表明正在修复一个 bug，不要立即写修复代码。先写测试。观察它失败。然后写修复代码。再观察测试通过。
我总是使用 /tdd [2]。偶尔会产生一些愚蠢的测试，但它产生的代码缺陷要少得多。这不仅适用于 bug。
[1] https://github.com/gregwebs/skills-sdlc/
[2] https://github.com/mattpocock/skills/blob/main/skills/engine...
- Supermancho
读这些东西挺有意思的。
我会把这描述为 13 条代码编写规则（解读为至少 16 条——从“减少代码缩进”开始），外加一套我选择忽略的提交信息指令集，因为它是风格特定的，对我没什么兴趣。
其中 8 或 9 条规则是不必要的。基础计算机科学并不是我需要向代理询问的内容，而是我用来遵循的准则。例如，解释你需要显式接口并不是必要的指令，利用提前返回也不是。
模糊的指令效用有限。“让代码读者喘口气”或“减少代码缩进”意味着什么是很主观的，而且很少有效。也许所用语言的训练存在某些其他人没有的空白。如果你想衡量效果，可以让它在应用规则时输出一个字符串。你会很快弄清楚什么有效、什么无效以及频率如何。
其中包含了 3 或 4 个风格选择。
其余的我都不会用，但我们都被不同的东西坑过，所以我理解。
- getnormality
这个问题主要是人们必须自己解决。比如，我用 Claude 工作快一年了，从未见过它写出“箭头反模式”代码。那以及其余大部分内容，在我的项目中都是废话。代理指令最好是通过项目逐个经验积累习得的。
- oumua_don17
仅仅 AGENTS.md 中的这一行，就显著减少了甚至消除了冗长和浮夸。
**始终使用 ASD-STE100 简化技术英语**
免责声明：我在另一个 HN 帖子里见过这个，但一时找不到链接了。