想让AI写代码更规范？先读懂这份AGENTS.md文件

AI编程工具能生成代码，但如果不加约束，输出可能不符合项目规范。一份名为 AGENTS.md 的说明文件可以缓解这个问题——它把编码标准、文档要求、测试方式写清楚，让AI按规则工作。但这套文件有明确前提：它针对特定某个人的工作流，不会自动适用于别人的项目。

别直接复制

拿到一份现成的 AGENTS.md，直接复制扔进工具里，不会突然让AI代理写出更好的代码。规范只有和项目匹配才有用。如果不确定手里的文件在做什么，可以把文件粘贴到对话模型里，问清楚每一条的含义，再让它根据具体用途重写这份 markdown。

引导文件与测试验证

性价比最高的做法，是建立一套引导文件。具体来说，要求AI在文件夹层级维护 README.md、AGENTS.md 和 CONTRIBUTORS.md，所有AI创建的文件夹也必须有文件夹级别的 README.md。编码标准要写进 AGENTS.md 和 CONTRIBUTORS.md——比如 Python 项目遵循 PEP-8 和 PEP-257，其他语言找类似的编码和文档标准。这样一来，每次写代码时上下文都在手边，不用反复交代。

测试环节有两个技巧。一是尽量避免使用 mocks 和 fakes 这类模拟对象，除非出于安全或极端计算成本的考虑。二是每次写完测试，故意在代码里引入一个bug，确认测试产生准确的FAIL结果，再恢复bug。这样才能确保测试真的能抓到bug，减少回归风险。

注释的价值与边界

要求模型在代码里写注释，对代码质量和稳定性也有帮助。有开发者认为它能显著减少模型犯错的次数。确切机制还不清楚，可能和训练数据中注释良好的代码质量普遍更高有关，也可能是注释确保了相关上下文始终存在。这些技巧不保证适用于所有模型和所有项目。冗长问题就是一个例子：训练已经把这个问题消除了相当一部分，但对 Qwen 3.8 27b 来说，输出冗长是它的特性。模型的编码标准可以自己发现并记录，前提是给它一个足够清晰的工作框架。代码质量来自规划，而在LLM的语境里，规划就是对话。AGENTS.md 让这种对话变得可重复。