导语
随着工程组织规模扩大，让所有人遵循统一的软件开发规范变得越来越困难。每个人都有自己的习惯和风格，工单系统、Scrum 和部署流水线等机制应运而生，试图为开发流程注入一致性。而在代码层面，则通过编码标准和规范来实现。
到了 2026 年，软件工程师手写代码的比例越来越低，越来越多地依赖编码代理（coding agents）根据设计意图生成代码。这些代理若要参与企业代码库，就必须遵守既定的标准和规范。幸运的是，市面上大多数代码生成器已经支持为代理配置标准和规范。
代理不是初级开发者
然而，为代理制定编码规范与 onboarding 一名初级开发者完全不同——你不能丢几份文档给它然后放任探索。代理执行速度快，却缺乏对代码上下文的深入理解。而人类程序员的大量上下文认知，其实来自对特定形式、风格和模式的隐性积累。代码中的"红旗"被称为"代码异味"（smells），这个说法本身就揭示了人类代码理解中那种直觉性的本质。尽管外界讨论热烈，编码代理至少在专业场景下并不是靠直觉运行的。
随着代理生成的代码越来越多，软件工程的认知负担正在向设计和架构层面转移。代码审核&查验也将成为大多数工程师首次审视代码的窗口——因为代码并非由他们亲手写出，他们只知道需求是什么，却不掌握代码的来龙去脉。为代理制定的编码指南，可以为这个本质上非确定性的过程注入一定的确定性。
代理编码指南的特殊性
为代理（或人）制定的编码标准和规范（本文统称"指南"），需要比传统版本略有不同——更明确、更具示范性、更一目了然。但也不会相差太多，因为好的文档本来就应该服务于所有编码实体。
基本原则
代理生成的代码需要能够与大量已在线上运行的既有代码协同工作（除非你有幸只做全新的绿地项目）。这意味着代理需要：
- 使用相同的语言和库
- 接入既有的构建和部署系统
- 适配平台工程系统和范式
如果你的前端用的是 Express，就不能让代理用 React 来写代码。
除了技术栈本身，工程团队还有一整套方法论和最佳实践，用以维护共享代码库。其中有些是通用最佳实践，有些是团队文化，有些则是团队对最佳实践的有意偏离。这些对人类同事而言可能被视为"常识"，但对代理则不能想当然。
Vish Abrams（Heroku 首席架构师）指出："需要考虑的是，你到底给了它什么样的提示，比如 DRY 原则？有些经典的编程原则对资深工程师来说是常识，部署方面也是如此——你希望把配置和代码分离来构建应用。你可以告诉 LLM 用这种方式构建，也可以简单地说'给我写个贪吃蛇游戏'，然后它爱怎么写怎么写，完全不管后续可维护性。" 这可能正是重新审视编码指南的时机。许多最佳实践诞生于代码还是"手工艺品"的年代。如果你现在只在代码审核&查验阶段接触代码，也许某些规范需要调整——比如为了便于审核&查验，代码中是否应该保留更多功能副本（随 PR 一起展示）？这没有标准答案，但许多最佳实践的本质目的是让代码对人类更易读、更易维护。
代码层面的具体决策
编码和写作一样，存在大量因组织而异的小决策。这些对外部人来说可能显得微小随意，却可能产生下游影响，并拖慢习惯特定约定的同事的审核&查验速度。以 Stack Overflow 博客的编辑规范为例：我们使用序列逗号（serial comma），而有些人不用——并且他们是错的。
和风格指南一样，代理编码指南应该明确说明团队在语言结构选择上的决策及其理由。以下是值得纳入的几个决策点：
- 变量和方法命名：命名是软件工程中的经典难题。你希望代理自由发挥创建
FactoryBuilderBuilderFactory，或者混用 camelCase 和 underscore_style 吗？如果代码库内存在不同风格（例如 C++ 和 SQL 代码风格不同），应分别说明。同时明确如何识别和解决重复命名问题。 - Tab 还是空格：如果团队对此有明确立场，让代理知道即可。有些 IDE 和语言可能让这个争论变得毫无意义——但无论怎样，确保代理清楚规则。
- 代码布局：某些编程语言（如 Python）对缩进和格式有严格要求，而另一些语言（尤其是花括号语言）则允许更自由的布局方式。研究表明，布局方式会影响代码理解的速度。
- 异常处理和日志：代码需要优雅地失败，代理需要了解你对线上软件故障处理的预期和数据收集方式。理想情况下这些能自动完成，但大多数时候需要在代码中显式编写相关逻辑——不如让代理顺手写了。
- 注释规范：代理可以写注释，但应该在方法之前还是之后？注释是否遵循缩进规则？你使用 API 文档生成器吗？注释要详细到什么程度？这些人类程序员可能靠直觉判断的事，代理需要明确指引。
以上并非代理编码指南的完整清单，你大概率会在使用过程中发现代理的各种恼人小癖好。
导语
想让 AI 编程代理按照你的期望工作？光有技术栈不够——你还需要一套结构清晰的编码规范文档。本文综合了多位工程负责人的实战经验，总结出面向 AI 编程代理的规范撰写方法论，涵盖指南设计原则、示例写法、错误反馈机制以及落地步骤。
指南设计原则
清晰一致，避免歧义
规范文档的首要标准是「显而易见」：任何人都能一眼看懂如何执行。撰写完毕后，试着以最挑剔、最不讲道理的方式去测试它——只要你能找到一种方式曲解它，就说明它还不够清楚，需要重写。
风格上不必追求完美，但必须保持可预测性。整套文档使用简单、重复的句式结构，AI 对模式化的表达有明显偏好。
语言要直白，别给 AI 设陷阱
工程师写文档时，默认读者英文水平参差不齐，可能是非母语者。相应地，应避免使用习语（idiomatic expressions）或其他需要二次解读的语言结构。
"Don't confuse the AI. Be simple, explicit, and boring."
代码示例同理。覆盖所有边界情况，不给 AI 留下任何「自行判断」的空间。每个决定都要有明确的理由——哪怕这个理由只是「我们是 Python 团队，用 Tab 缩进保持一致性」这样的标准约定。
Graphite CTO Greg Foster 指出，工程师通常会潜移默化地吸收代码库的隐性上下文：花一晚上写一堆新函数时，也在同时吸收整个代码库的氛围与规范。规范的职责正是把这种隐性知识显式化。
示例：展示模式的艺术
为什么示例比步骤清单更有效
作者坦承自己曾一度排斥在文档中加示例——直到不得不用文档解决问题的那一刻，才恍然大悟。截图、示例代码、API 调试台……这些比编号步骤清单更能教会用户如何上手工具。
代码示例的本质是一个模板：CTRL+C 后 CTRL+V 就能改出自己的版本。AI 同样需要一个可复制的模式。
正确与错误的对比示例
同时展示「正确实现」和「错误实现」两种示例。AI 可以通过对比判断大多数场景下代码应该如何编写。每条规则配多个示例也无妨，但务必确保示例之间风格统一。
还可以提供一份「黄金标准文件」——即完整遵循所有规范的代码范例。单个示例类似单元测试，黄金标准文件则是端到端测试。团队可以测试哪种方式效果更好。
错误即反馈：持续优化规范
把失败当作迭代素材
如果你和 AI 编程代理打过足够多交道，大概已经明白——第一版规范不可能一次到位。Charity Majors 在其博客中提到，CI/CD 的核心价值在于缩短反馈循环；AI 代理也不例外。
代码中出现的错误，是更新 standards 文件的绝佳机会。这些错误往往能揭示那些你原本没意识到的隐性规范——那些「secret requirements」。
Sourcegraph CEO Quinn Slack 打了个比方：
"有一种人只是随手敲 prompt，'chicken-type'，他们并不真正想让 AI 赢。另一种人会花大量时间定义规则、写
agents.md文件，把 AI 应该如何运作说得明明白白。出了错，他们就更新文档，让它转起来形成飞轮。"
人类反馈同样重要
另一个不可忽视的反馈来源是你的工程团队。将 standards 文件放在 Stack Internal 或其他文档库中，让所有人都能编辑、评论、更新。毕竟，这份代码规范最终会影响所有人的日常开发与 code review，每个人都应该有发言权。
落地：让规范与 AI 共存
写入 agents.md 或封装为 Skill
规范写完之后，关键是让它「活在代码旁边、活在代理上下文中」。将所有规则显式写入 agents.md 或打包为 Claude Skill，并纳入标准代码仓库管理——就像管理部署流水线一样管理它。
不过，这不意味着放弃其他确定性工具。Linter、Formatter、静态分析工具在构建流程中仍有其一席之地——它们负责捕捉 AI 最容易搞砸的基础问题。
大公司已经走在前面
DeepMind/Google 高级产品经理 Logan Kilpatrick 指出，已经在管理数百乃至数千名工程师代码风格的大公司，在这方面有先天优势：
"大公司有完善的形式指南、最佳实践、软件开发流程。所有这些都是完美的上下文，可以喂给模型，让它真正为你所用。缺少这些上下文，你基本就是在盲猜。"
这意味着：越早把隐性规范显式化、文档化，就越早能让 AI 成为真正的开发助力。
评论