工程师实测：一份AGENTS.md让AI写出更好代码

一位工程师分享了他用大语言模型辅助编程的实战体会。2025年年中他开始尝试让LLM生成代码，早期效果能用但并不稳定：模型能写出功能，但输出通常缺乏注释和组织，改起来比重写还费劲。到2026年1月，换了新模型后能力明显提升——能生成复杂的数据结构实现，甚至定位到Windows IOCP实现里一个难以察觉的轮询库bug——但代码整洁度仍是短板。

到了2026年3月，他又开始用带智能体功能的编辑器（例如Google Antigravity、带智能编码功能的VS Code、Claude Code等）。这类工具生成的代码质量跃升，接近“有耐心的计算机系大三学生”水平，很多时候不需要从零开始手写。但新问题浮现：每次新会话AI会重复犯以前的错，需要不停纠正，极为耗时。

为了解决会话不一致的问题，他把期望的编码风格和行为写成了一份给AI阅读的说明文档，命名为AGENTS.md，放在项目根目录或用符号链接指向各个智能体的配置文件，这样每次新会话时AI都会先读取并遵循这些规则。文档把“什么是好代码”具体化，包含了多条明确的编码规范，例如： 龙8头号玩家国际

- 面向人的文字（注释、提交信息、回复）要精炼，少即是多 - 避免夸张或赞美性的描述，给出干净、客观的反馈 - 不使用魔法数字或魔法字符串，重复值应抽成常量或枚举 - 尽量减少嵌套与缩进，优先使用提前返回和 continue，避免“箭头”反模式 - 函数名简短明了，一般不超过30字符 - 函数参数若表达多种状态，优先用枚举而非布尔值 - 逻辑块间留空行，提升可读性 - 注释应说明做什么和为什么，必要时用ASCII图示整体结构 - 默认把字段和方法设为私有，修改可见性需明确征求同意 - 按抽象层级编程，底层细节封装到驱动或抽象层，只暴露简洁高层API - 不改与当前任务无关的代码，尽量减少改动行数 - 严格遵守分层边界，各层仅与相邻层通信，避免“打洞”式的跨层调用

他的结论很直接：LLM写代码的能力已经不低，但稳定性不足。与其在每次会话里不断手动纠正，不如把团队或项目的编码规则写清楚，让AI在每次开始新会话时先“读说明书”。把风格和约束写成文件后，AI生成的代码更统一、可维护性也大幅提升。对于依赖AI辅助开发的团队，这是一种把不确定性转为可控性的实用策略。