AI 编程工具进入团队以后，一个很现实的问题是：同一个需求交给不同的人和不同的 Agent，可能会得到完全不同的目录结构、命名方式和实现方案。
这些代码单独看也许都能运行，放进同一个项目后却容易出现另一种形式的混乱：相同能力被重复实现、公共组件无人复用、错误处理各写一套、测试和日志标准不一致，最后维护成本仍然回到团队身上。
在《Agent 协作最佳实践》里，我整理了一套“方案—实施—检视—修正”的双 Agent 协作流程。它解决的是一次任务如何形成质量闭环。这篇文章想继续往前一步：当 AI 编程从个人实践变成部门能力，怎样让每次协作都建立在同一套工程基线上。
我的结论是把约束分成三层：
部门级 Skill：统一所有项目都要遵守的工程规范
↓
项目级 Skill：告诉 Agent 这个项目已经有什么、代码应该放在哪里
↓
任务级上下文：描述这一次具体要解决的问题和验收标准Skill 让 Agent 理解团队的做事方式，工具链和代码门禁则负责验证结果。两者缺一不可。
为什么只有规范文档还不够
很多团队已经有编码规范，只是它们通常散落在 Wiki、README、历史邮件和 Code Review 评论里。人未必会在每次开发前重新阅读，Agent 更不会自动知道应该参考哪一份。
即使把整份规范都放进上下文，也不代表它会被稳定执行。文档过长时，真正重要的约束容易被淹没；规范只描述结果、不提供检查命令时，也很难判断生成代码是否合格。
因此，一份适合 AI 协作的规范不能只是“知识集合”，还应该是一份可执行的工作说明：
- 什么场景必须读取它；
- 开始编码前要先检查什么；
- 哪些模式应该优先使用；
- 哪些做法明确禁止；
- 完成后必须运行哪些命令；
- 无法确定时应该向谁确认，而不是自行创造新约定。
Skill 正好可以承担这个入口。它不替代原有文档，而是把最重要的规则、查找路径和验证动作组织成 Agent 能稳定执行的流程。
部门级 Skill：建立共同的工程底线
部门级 Skill 应该是每位开发者和每个编程 Agent 的基础配置。它只包含跨项目都成立的规则，不要塞入某个业务的特殊实现。
1. 先统一能被机器判断的规则
最适合首先沉淀的是确定性高、争议少的规则，例如：
- 文件、变量、类型、常量和组件的命名规范；
- 大小写、缩进、引号和导入顺序；
- TypeScript 类型约束；
- React Hook、异步请求和错误处理规则；
- 日志中不得出现密钥和敏感信息；
- 新增逻辑必须补充对应测试；
- 提交前必须执行的 lint、format、typecheck 和 test 命令。
能交给 ESLint、Prettier、TypeScript 或测试框架判断的规则，就不要只写成自然语言。自然语言负责解释意图，工具负责给出唯一结果。
例如，Skill 可以要求 Agent 在结束前执行：
npm run lint
npm run typecheck
npm test但真正阻止不合格代码入库的，应该是 CI 和分支保护。因为 Agent 可能遗漏指令、误读输出，也可能只验证了局部代码。Skill 是导航，代码门禁才是底线。
2. 明确团队偏好的实现方式
并非所有规范都能写成 lint 规则。比如：
- 优先使用组合而不是复制一个相似组件；
- 不为了“可能的未来需求”提前增加抽象层；
- 错误信息需要包含可定位问题的上下文；
- 修改公共模块时必须说明影响范围；
- 不允许用
any或忽略异常来绕过类型和测试； - 对架构方向存在疑问时先暴露假设，不自行扩大改动范围。
这类规则适合写进 Skill，并配上少量正反例。示例比“保持代码优雅”这样的抽象描述更容易被执行。
3. 把检查流程写进 Skill
部门级 Skill 不应该只告诉 Agent“代码要规范”，还要约束它的工作顺序。一份最小的 Skill 可以包含：
# 部门工程规范
## 编码前
- 阅读仓库中的项目级 Skill 和贡献指南
- 检查已有实现、测试和公共能力
- 明确改动范围与验收方式
## 编码中
- 遵循命名、类型、错误处理和测试规范
- 保持最小改动，不顺手重构无关代码
- 新增公共抽象前，先证明存在重复需求
## 编码后
- 检查 Git Diff 中是否混入无关修改
- 运行 lint、typecheck、test 和项目规定的构建命令
- 汇报已验证内容、未覆盖场景和剩余风险这里最重要的不是文件格式，而是把团队共识变成每次任务都会触发的行为。
项目级 Skill：让 Agent 先复用，再创造
部门级 Skill 解决“代码应该符合什么标准”，项目级 Skill 则解决“在这个仓库里应该怎样实现”。
项目维护时间越长，越容易积累只有老成员知道的隐性知识：公共组件放在哪里、请求层怎样封装、哪个 Hook 已经解决过类似问题、哪些目录即将废弃、埋点和权限应该从哪里接入。
人不知道这些信息会重复造轮子，Agent 也一样。区别只是 Agent 造得更快。
一份有效的项目级 Skill 至少应该包含：
| 内容 | 需要回答的问题 |
|---|---|
| 目录与边界 | 页面、组件、服务、状态和测试分别放在哪里？ |
| 公共组件 | 表格、表单、弹窗、空状态等应该优先复用什么？ |
| 公共方法 | 请求、缓存、日期、权限、日志和埋点从哪里调用？ |
| 推荐模式 | 新页面或新接口应该参考哪个现有实现？ |
| 禁止模式 | 哪些旧目录、旧 API 或历史方案不能继续使用？ |
| 验证方式 | 这个项目需要运行哪些检查和端到端场景？ |
不要把项目级 Skill 写成静态组件清单
组件和方法会持续变化，手工维护一份完整清单很快就会过期。Skill 更适合保存稳定的地图和查找策略，例如：
实现弹窗前：
1. 搜索 packages/ui 中已有的 Dialog、Drawer 和 Form 组件；
2. 搜索业务目录中相似交互的调用方式；
3. 确认现有组件无法满足需求后，才允许新增；
4. 新增公共组件时同步补充示例、测试和导出入口。这样即使目录内容发生变化，Agent 仍然知道去哪里找、按什么顺序判断。对于稳定且高频的能力，再补充具体文件位置和示例即可。
从仓库生成，但必须由项目成员确认
项目级 Skill 可以让 Agent 基于真实仓库生成初稿：扫描目录、依赖、公共组件、工具方法、测试命令和典型实现，再整理出项目地图。
但自动扫描只能看到“代码现在是什么样”，无法判断它是不是团队希望继续推广的做法。历史遗留实现可能恰好出现得最多，却不应该成为推荐模式。因此，初稿必须由熟悉项目的人审核，明确标注：
- 推荐复用；
- 仅维护、不再新增；
- 正在迁移；
- 明确禁止。
没有这一步，Skill 可能会把技术债复制得更快。
从生成代码到保证质量
有了部门级和项目级 Skill，并不意味着 Agent 生成的代码天然可靠。质量仍然要靠完整流程建立证据。
结合我之前的双 Agent 协作方式，可以把一次开发拆成下面几个阶段。
1. 编码前：同时加载规则、项目事实和任务目标
主 Agent 在制定 Plan 前，应该获得三类上下文：
部门级 Skill：哪些规则不能破坏
项目级 Skill：已有能力和推荐路径是什么
需求文档：这一次为什么改、做到什么算完成然后先读取真实代码，验证 Skill 中的信息是否仍然有效。Skill 提供方向，仓库才是当前事实。
Plan 里不仅要列出准备修改的文件，还应说明准备复用哪些公共能力、哪些行为需要测试、可能影响哪些调用方。人工确认的重点也从“这段代码写得像不像”前移到“方案有没有走在正确的项目路径上”。
2. 编码中：控制 Diff，持续运行局部检查
复杂任务应拆成可以独立验证的小步骤。每完成一部分就运行最相关的测试和静态检查，避免最后一次性面对大量错误。
同时要求 Agent 保持 Diff 聚焦：不修改无关格式，不顺手升级依赖，不借功能需求进行大范围重构。改动越集中，后续人工和副 Agent Review 越容易发现真正的问题。
3. 编码后：让主 Agent 自检，但不止于自检
主 Agent 完成代码后，应对照两级 Skill 和任务验收标准检查实际 Diff，并明确汇报：
- 复用了哪些现有组件和方法；
- 新增了哪些抽象，为什么不能复用已有能力；
- 执行了哪些检查，结果是什么；
- 哪些边界场景还没有验证；
- 是否改变了公共接口或项目约定。
自检能够消除一部分低级问题，但实现者容易延续自己的思考前提，因此还需要独立视角。
4. 副 Agent 基于 Diff 独立 Review
副 Agent 应读取相同的部门规范、项目知识和需求基线，然后直接检查 Git Diff，而不是只看主 Agent 的完成总结。
它需要重点验证：
- 实现是否真正满足需求和验收标准；
- 是否绕开公共能力、制造了重复实现；
- 是否违反类型、错误处理、安全和兼容性规范；
- 测试是否覆盖失败路径和边界条件；
- 修改公共模块后是否检查了所有调用方。
Review 意见仍然要经过主 Agent 和人工逐条判断，再由副 Agent 复检。两个 Agent 的价值是提供不同视角，不是互相投票决定正确答案。
5. CI 用同一套标准做最终门禁
本地执行过检查，不代表入库前可以跳过 CI。部门应统一最小门禁，再由项目增加自己的检查项：
格式与 Lint
→ 类型检查
→ 单元测试
→ 构建
→ 必要的集成或端到端测试
→ Code Review 通过
→ 允许合并如果某条规范经常在 Review 中被重复指出，就应该考虑把它升级为 ESLint 规则、测试、脚本或 CI 检查。能自动化验证的规则越多，人工和 Agent 就越能专注于业务正确性和设计取舍。
Skill 本身也需要版本和评测
Skill 不是写完就不再变化的制度文件。它和代码一样会过期，也可能互相冲突。
部门级 Skill 应由明确的负责人维护和发布版本；项目级 Skill 则跟随仓库演进，在公共能力、目录结构和验证命令变化时同步更新。项目规则可以补充部门规范，但不能悄悄降低部门底线。
还可以定期用真实任务评估 Skill 是否有效：
- Agent 是否能找到并复用正确的公共组件；
- 重复实现的数量是否下降；
- Review 中命名、类型和工程规范类问题是否减少；
- CI 首次通过率是否提高；
- Skill 是否引用了已经失效的路径和命令；
- 为遵守 Skill 增加的流程成本是否合理。
如果规则经常被忽略，先不要简单地继续加长文档。更应该检查它是否足够明确、是否在正确场景触发、是否能由工具自动验证，以及是否存在互相矛盾的要求。
一套可落地的推进顺序
如果部门刚开始建立 AI 协作规范，可以按下面的顺序逐步推进：
- 先收敛现有规范。 整理命名、类型、错误处理、测试和提交要求，删除已经失效或互相冲突的内容。
- 把确定性规则工具化。 统一 ESLint、Prettier、TypeScript、测试和 CI 门禁，保证人和 Agent 面对同一结果。
- 发布最小部门级 Skill。 只保留高频、稳定、跨项目成立的规则，以及编码前后的检查流程。
- 选择一个项目生成项目级 Skill。 补充目录地图、公共能力、推荐实现、禁用方案和验证命令，由项目成员审核。
- 接入双 Agent 闭环。 主 Agent 负责计划和实施，副 Agent 基于需求、Skill 和 Diff 独立审查，人工负责最终取舍。
- 从 Review 和失败中迭代。 重复出现的问题转成自动化规则，已经失效的约定及时删除。
不要一开始就试图写出覆盖所有场景的“超级 Skill”。先让最常见的开发任务稳定下来，再用实际问题扩充规范，通常更容易长期维护。
总结
部门级 AI 协作规范的目标，不是让所有 Agent 生成一模一样的代码，而是让它们在共同的工程边界内做出可解释、可验证的选择。
这套机制可以概括为：
部门级 Skill 统一底线
→ 项目级 Skill 提供仓库地图和复用路径
→ 任务上下文明确目标与验收标准
→ 主 Agent 计划、实施和自检
→ 副 Agent 基于 Diff 独立 Review
→ 工具链和 CI 提供客观证据
→ 人负责关键取舍和最终验收Skill 解决的是“Agent 是否知道应该怎样做”，代码门禁解决的是“结果是否真的符合要求”，双 Agent Review 解决的是“有没有被实现者自己的思路遮住的问题”，而人始终负责判断“我们做的是不是正确的事情”。
当规范、项目知识、自动化验证和协作流程形成闭环以后，AI 带来的就不只是更快的代码生成，而是可以被团队复用和持续改进的工程能力。