Coding with Agents

Appearance

为什么团队级开发更需要工程化 ​

Last updated: 2026-07-27

一个人用编码智能体，可以靠提示词、经验和即时纠偏把事情做成。一个团队用编码智能体，就不能只靠个人手感了。

原因很简单：AI 让代码产出变快，也会让不一致变快。一个人多写了几百行代码，问题通常还在一个上下文里；十个人同时让多个智能体改代码，问题会扩散到产品边界、架构决策、接口约定、测试覆盖、评审标准和上线风险里。

所以团队级 AI 开发的核心不是“让每个人都会提示词”，而是把决策、规范、上下文、验证和复盘工程化。做不好，团队会得到一堆局部能跑、整体难维护的代码；做得好，团队会变成一台不断学习、不断沉淀、不断进化的研发机器。

从个人工作流到团队工程化 ​

在 Level 1 的可规模化的结构化工作流里，我们已经看到高效团队正在形成的基本模式：

  1. 先设计，再编码。
  2. 拆解任务，再移交执行。
  3. 先写测试，再写实现。
  4. 所有改动都要评审。

这套流程对个人也有帮助，但在团队场景里，它不再只是“好习惯”，而是底层工程机制。

个人开发时，很多上下文存在你的脑子里。你知道这个接口为什么不能改，知道某个模块为什么不能引入新依赖，也知道某个边界场景为什么必须兼容。团队开发时，这些隐性知识如果没有写下来，就不会稳定传递给其他人，更不会稳定传递给每一次新的智能体会话。

AI 不会自动继承团队共识。它只会根据当前上下文做出看似合理的局部决策。团队工程化要解决的，就是把人的共识转成智能体可读取、可执行、可验证的资产。

团队要做的事情更多 ​

AI 加速编码以后，瓶颈会从“谁来写代码”转移到“写什么、怎么写、怎么证明写对了”。这就是团队级开发更难的地方。

一个完整交付至少包含这些问题：

  • 产品边界：本期做什么，不做什么，哪些能力必须有，哪些能力可以延后。
  • 架构取舍：模块如何划分，数据如何流转，哪些地方要预留演进空间，哪些复杂度现在不引入。
  • 数据模型：核心实体是什么，状态如何拆分，哪些字段稳定，哪些配置需要扩展。
  • 部署约束：系统运行在哪里，预期并发是多少，缓存、超时、重试、可观测性如何设计。
  • 代码规范：分层职责、命名、错误码、日志、异常、外部调用、依赖边界如何统一。
  • 验证闭环：哪些测试必须有，哪些验收路径必须跑，review 按什么清单判断。
  • 复盘沉淀：这次踩过的坑，下一次如何不再踩。

这些事情如果不前置，AI 不会消除混乱，只会把混乱更快地生成出来。模糊的需求会变成模糊的实现；缺失的架构约束会变成随意的模块依赖；没有验收标准的任务会变成“看起来做完了”的代码。

方法论：把团队活动沉淀成资产 ​

团队级工程化的关键动作，是把每一次开发活动都变成可复用资产。资产不是漂亮文档，而是下一次能直接约束智能体行为、降低沟通成本、提高验证质量的东西。

团队活动要沉淀的资产为什么重要
产品定义范围边界、用户故事、非目标防止智能体顺手扩展范围，也防止团队对“完成”的理解不一致
技术设计架构决策、模块边界、数据模型防止局部实现正确，但整体结构混乱
编码执行CLAUDE.md、任务清单、接口约定保持多人、多智能体输出的一致性
验证交付测试、验收用例、review checklist把质量从个人感觉变成可重复机制
复盘改进新规则、新模板、新流程让一次错误只发生一次，让一次交付能复利到下一次

这张表背后的设计原则是：团队不要只管理代码，要管理产生代码的上下文。

代码是结果。上下文、规范、测试和评审标准才是生产代码的系统。AI 让“写代码”变得便宜以后，真正贵的是错误决策、重复返工、接口不一致、边界没覆盖、团队共识丢失。

为什么先定边界 ​

边界回答两个问题：我们要解决什么问题？我们明确不解决什么问题？

在 AI 开发里，“不做什么”往往比“做什么”更重要。因为智能体很擅长补全。你让它做删除接口，它可能顺手加软删除、操作日志、审计表、批量删除和权限模型。这些东西不一定错，但如果没有经过产品和架构判断，就是范围漂移。

个人项目里，范围漂移只是多写一点代码。团队项目里，范围漂移会制造连锁成本：

  • 产品验收时，大家对交付范围理解不同。
  • 后端多做了能力，前端不一定接得住。
  • 数据库多了表和字段，迁移、回滚、权限都要处理。
  • review 变难，因为评审者先要判断“这是不是本来就该做”。
  • 后续维护者会默认这些能力是正式设计的一部分。

所以团队级任务必须先写清楚边界。一个好的边界说明至少包含：

  • 本期目标：这次交付完成后，用户能做什么。
  • 非目标：哪些能力明确不做，避免智能体自动扩展。
  • 成功标准：什么行为出现，才算完成。
  • 取舍理由：为什么现在这样切，不是更大或更小。

边界不是为了限制创造力，而是为了保护团队注意力。只有边界清楚，AI 的速度才会变成产能，而不是噪音。

为什么先做技术设计 ​

技术设计的目的不是写一份正式文档，而是提前做那些不能交给 AI 代替团队负责的决策。

AI 可以帮你比较方案、画模块图、列风险、估算瓶颈。但架构决策的责任必须在人这里。原因是架构不是“当前代码怎么写最顺”，而是“未来几个月甚至几年，团队愿意承担什么维护成本”。

例如：

  • 选择模块化单体，就意味着要明确模块边界，禁止跨模块直接访问底层存储。
  • 选择缓存，就意味着要定义一致性策略、失效策略和哪些数据不能缓存。
  • 选择异步任务，就意味着要处理幂等、重试、死信和可观测性。
  • 选择不引入新依赖，也是一种设计，用来控制长期复杂度。

这些决策如果不写清楚，智能体会在每个任务里重新猜一次。不同的人启动不同会话，就会得到不同风格的实现。短期看都能跑，长期看就是一团乱麻。

技术设计应该沉淀成可执行约束，而不是停留在抽象原则：

markdown
架构决策：当前采用模块化单体，为后续拆分服务保留边界。

执行规则：
- 跨模块调用必须通过 Service 接口。
- Controller 只做参数校验和路由转发，不写业务逻辑。
- Mapper/Repository 只属于本模块，其他模块不得直接引用。

这样的规则能被人 review，也能被智能体执行。它把“我们为什么这样设计”转成了“每次写代码必须怎么做”。

为什么维护 CLAUDE.md ​

CLAUDE.md 不是项目简介，也不是给新人看的长篇说明书。它是团队给编码智能体的持久上下文层。

智能体每次会话都会重新开始。它不会天然记得上次 review 中指出的问题，也不会天然知道某个接口不能改、某个模块不能引入依赖、某个异常必须保持兼容。团队必须把这些稳定约束写进上下文资产里。

CLAUDE.md 最适合承载四类内容：

  • 项目上下文：这是什么系统，服务谁，核心边界是什么。
  • 架构规则：模块怎么分层，依赖方向是什么，哪些地方不能绕过。
  • 代码约定：命名、返回体、错误码、日志、异常、事务、外部调用的统一方式。
  • 历史禁区：哪些地方踩过坑，为什么不能那样写。

真正有效的 CLAUDE.md 不是越长越好，而是每条规则都能追溯到一个真实问题或架构决策。

差的规则是：

markdown
代码要简洁，接口要规范。

好的规则是：

markdown
Controller 只做参数校验、权限检查和调用 Service，不写业务逻辑。
原因：业务逻辑需要被定时任务、消息消费者和测试复用，放在 Controller 会导致重复实现。

前者让 AI 猜，后者让 AI 执行。团队级上下文工程的目标，就是减少智能体需要猜的地方。

为什么规范要从踩坑中生长 ​

很多团队写 CLAUDE.md 的第一个错误，是试图一次写完所有规范。结果通常是一份很长、很泛、没人维护、AI 也抓不住重点的文档。

更好的方式是：先写最小可用版本，然后让规范从真实开发中长出来。

判断一条规则该不该写进去，可以用三个问题：

  1. AI 是否反复在这里跑偏？
  2. 这个错误是否会造成维护成本、线上风险或团队不一致？
  3. 写成明确规则后，下一次是否能直接避免？

如果答案是肯定的，就写。否则先不要写。

规范颗粒度也要跟着问题走。AI 基本不会错的地方，不必占上下文窗口；AI 经常错、且错了成本高的地方，要写得非常具体。

例如：

问题不够好的规则更好的规则
业务逻辑乱放保持代码分层清晰Controller 不写业务逻辑；业务逻辑放 Service；跨模块只能调用对方 Service
返回结构不一致接口返回要统一所有接口返回 { code, message, data }；空列表返回 []，不返回 null
依赖随意增加不要乱加依赖不得引入现有技术栈之外的新依赖；确需引入时，先说明替代方案和长期维护成本
更新逻辑粗暴更新要注意安全更新集合关系时使用差异比对；不得先全量删除再插入，避免并发窗口中读到空关系

规范不是为了追求整齐，而是为了降低重复沟通。每一次 AI 跑偏，都是一次发现缺失规则的机会。把它沉淀下来，团队就少了一类未来错误。

为什么必须验证和复盘 ​

没有验证闭环，AI 生成代码的速度越快，风险越大。

团队不能只问“代码写完了吗”，要问“我们如何证明它符合意图、符合规范、覆盖边界、不会破坏已有行为”。这就是测试、review 和验收存在的原因。

验证至少分三层：

  1. 意图验证：它做的是不是我们要求的事，有没有扩大范围。
  2. 质量验证：命名、分层、返回体、错误处理、日志、事务、依赖是否符合规范。
  3. 边界验证：空数据、权限不足、并发、超时、外部服务失败、旧数据兼容是否覆盖。

复盘则负责把验证中发现的问题变成下一次的资产。一次 review 里发现“AI 总把业务逻辑写进 Controller”，就补一条分层规则；一次上线发现“空列表返回 null 导致前端白屏”，就补一条返回约定；一次迁移发现“全量删除再插入导致并发读异常”，就补一条更新策略。

这就是团队级 AI 开发的复利：

  • 错误第一次发生时，靠人发现。
  • 第二次之前，规则已经进入 CLAUDE.md、测试或 review checklist。
  • 第三次开始，它应该被流程自动挡住。

如果没有复盘，团队只是更快地写代码。如果有复盘，团队会越来越会写代码。

一套可复用的研发交付流程 ​

把上面的原则落到日常工作，可以收敛成一条固定流程：

AI 调研理清边界，数据模型先行打底；分层自底向上开发，前端组件快速适配；库到浏览器闭环验收，交付完成沉淀复用。

这条流程不绑定具体业务。新模块、后台配置、存量系统改造都可以套。

1. Discovery：编码前完成需求调研 ​

先明确模块服务谁、解决什么问题、本期交付到哪里。把“必须做”和“以后再说”分开，把跨模块依赖和高风险边界列出来。

AI 在这里适合做调研和归纳：行业常见方案、核心实体、通用字段、接口风格、兼容规则、可能的异常场景。但最终取舍必须由人决定。

为什么这样设计：编码前越清楚，编码后返工越少。AI 很适合扩展选项，不适合替团队承担取舍责任。

2. Data First：先数据，后接口 ​

数据模型是业务理解的地基。先拆清楚主业务实体、附属配置实体、状态衍生实体，再设计接口和页面。

常见原则：

  • 高频筛选、稳定查询条件用独立字段。
  • 多变配置可以用 JSON/KV，但要有类型和结构约束。
  • 高频变化的运行状态和低频变化的主数据尽量拆开。
  • 为未来扩展预留少量明确入口，而不是到处加万能字段。

为什么这样设计：接口和页面都可以调整，错误的数据模型会拖累整个系统。先把数据想清楚，AI 后续生成的代码才有稳定地基。

3. Layered Implementation：自底向上分层开发 ​

后端可以按固定顺序推进：Entity/Mapper → Service → DTO/Facade → Controller。

层职责
Entity/Mapper只处理存储映射和查询，不写业务逻辑
Service放领域逻辑、事务、缓存、跨模块协作
DTO/Facade做前后端防腐、数据聚合和裁剪
Controller只做参数校验、权限检查、统一返回和路由转发

为什么这样设计：分层顺序让每一步都能独立验证，也让智能体不容易把逻辑散落到随机位置。团队越大，分层越不是形式主义，而是降低协作成本的边界。

4. Verification：从数据库到浏览器闭环验收 ​

每个可交付功能都至少跑一条完整链路：新增、查询、编辑、删除，或对应业务里的核心动作。涉及外部调用、导入、计算、状态流转的功能，要单独验收。

验收覆盖三类场景：

  • 正常流程：主路径能跑通。
  • 异常流程：错误提示清晰，不暴露底层堆栈。
  • 边界场景：无数据、权限不足、超时、重复提交、并发冲突。

为什么这样设计：AI 能写出看起来完整的代码，但它不知道你的系统在哪些边界上最脆弱。验收流程就是把隐性风险显性化。

5. Retrospective：把一次交付变成资产 ​

交付结束后，不要只关 PR。要把本次产生的可复用内容收进团队资产：

  • 新增或修订 CLAUDE.md 规则。
  • 沉淀任务拆解模板和 review checklist。
  • 把高频样板抽成脚手架、命令或 Skill。
  • 为容易回归的行为补测试。
  • 把本次踩坑写成下一次智能体能读懂的约束。

为什么这样设计：团队进化不是靠记忆，而是靠沉淀。每一次交付都应该让下一次交付更快、更稳、更少返工。

本章接下来解决什么 ​

这一章只是入口。后面的章节会把团队级工程化拆开：

团队级开发更难，不是因为 AI 不够强，而是因为团队必须管理更多隐性知识、更多协作边界和更多长期成本。工程化的价值，就是把这些东西从人的脑子里取出来，变成团队和智能体都能持续使用的系统。