团队协作 SOP 与技术实践

本页说明团队在使用 Heicode 进行真实项目开发时，如何组织 AI Code 协作、如何准备项目规范、如何控制代码一致性，以及如何通过 AIE 审核机制降低大型团队中的协作风险。

Heicode 并不要求所有团队都采用同一种开发流程。不同团队的规模、技术栈、项目阶段和管理方式都不一样，因此团队可以继续保留自己的工单方式、代码提交方式和审核习惯。本文提供的是一套推荐实践，重点解决大型团队在引入 AI Code 后容易出现的上下文不一致、标准分裂、Code Review 滞后和 E2E 对齐困难等问题。

适用场景

当一个项目只有少数开发者参与时，AI Code 带来的主要收益通常是提高个人开发效率。但当项目进入多人协作、多个模块并行、多个仓库共同交付的阶段后，问题就不再只是“AI 能不能写代码”，而是“所有 AI 和所有开发者是否在按照同一套项目认知工作”。

因此，本文更适合已经开始在团队中使用 AI Code 或 Agent 的项目，尤其是存在前后端协作、多个服务协作、接口联调、权限控制、部署发布、E2E 测试等要求的团队。对于小型团队，可以只采用其中一部分机制，例如分层 CLAUDE.md、基于 Git 的任务追踪和 PR 审查；对于大型或超大型团队，则建议逐步建立完整的团队规范、知识库、AIE 审核和双审机制。

大型团队中 AI Code 协作的常见问题

AI Code 可以显著提升开发速度，但在大型团队里，如果缺少统一规范和统一审查机制，开发速度越快，协作风险也会越快暴露。每个开发者可能使用不同的 AI Code 产品，每个 AI Code 读取到的项目资料、代码上下文和任务背景也不完全一样。一个模块可能按照自己的理解定义接口，另一个模块可能按照另一个标准处理字段、状态码、错误格式或权限逻辑。等到 E2E 阶段才发现这些问题时，往往已经产生了大量返工。

传统 Code Review 依赖人工经验，但 AI Code 提升代码产出速度后，人工 Review 很容易跟不上。一个 PR 还没有完成审核，代码可能已经迭代了多轮；一个评审意见还没有被回复，新的提交又改变了原来的判断基础。久而久之，工单会积压，PR 状态会变得混乱，团队成员和不同 AI Agent 之间会形成各自的理解，最终出现“各定义各的标准”的情况。

这些问题的核心不是 AI 不会写代码，而是团队没有把项目全貌、统一规范、代码变更、评审意见和工单状态放在同一条协作主线上。Heicode 推荐团队以 Git 为主线组织 AI 开发流程，并通过团队规范、分层 CLAUDE.md、工单、PR、CI 和 AIE 审核建立一致性控制。

基于 Git 的协作主线

团队协作中的 AI 开发流程应基于 Git 进行控制。Heicode 不替代 Git，而是在 Git 既有流程上增加 AI 协作能力。工单用于定义任务目标，分支用于隔离代码修改，Commit 用于记录每次变更，PR 用于组织审核，CI 用于自动检查，Review 用于沉淀意见，Merge 和 Release 用于进入交付阶段。

推荐主线如下：

Issue / 工单
  ↓
Branch / 分支
  ↓
Commit / 提交
  ↓
Pull Request / 合并请求
  ↓
CI / 自动检查
  ↓
Review / 审核意见
  ↓
Merge / 合并
  ↓
Release / 发布

Heicode 在这个流程中的作用，是帮助团队读取项目规范和任务上下文，启动 AI Code 或 Agent 执行任务，记录任务过程中的关键决策，将代码变更与工单、PR、CI 关联，并在评审阶段进入 AIE 角色进行一致性审核。团队应尽量避免脱离 Git 的临时协作方式，因为没有工单、没有分支、没有 PR、没有评论记录的 AI 修改，很难被后续审查、复盘和追踪。

Teams Claude.md 与分层规范机制

Teams Claude.md 是团队级 AI 开发规范文件。它不是单一提示词入口，也不是替代所有项目文档的总文档。它主要用于定义 Heicode 在任务启动时需要读取哪些文件、文件夹和项目资料，以及团队统一的最高级约束。

在一个大型项目中，Teams Claude.md 不应该承载所有细节。它更像一份团队级的最高规范，告诉 Heicode 和 AI Code：启动任务前必须读取哪些资料，哪些规范不能被突破，哪些目录需要谨慎处理，哪些操作需要人工审批。更细的规则应该跟随项目目录、模块目录或服务目录放置。这样既能避免一个大文件无限膨胀，也能让 AI 在处理具体任务时读取更准确的局部上下文。

推荐分层如下：

Teams Claude.md
  ↓
团队级最高规范：定义必须读取的资料范围、统一约束、禁止事项、协作边界。

项目目录 / 模块目录中的规范文件
  ↓
定义某个项目、模块、服务或目录下的具体规则。

开发者自己的 CLAUDE.md
  ↓
根据当前任务和个人工作流细化执行方式，但不能突破 Teams Claude.md 的约束。

Issue / 工单 / PR
  ↓
描述当前任务目标、期望返回结果、修改边界和验收方式。

每个开发者可以根据自己的任务和工作方式制定自己的 CLAUDE.md，但这个文件只能细化执行方式，不能突破 Teams Claude.md 的约束。例如，开发者可以补充当前模块的开发命令、本地测试方式、负责目录说明和临时注意事项，但不能绕过团队审批规则，不能自行改变统一接口定义，也不能要求 AI 忽略 Teams Claude.md 中规定必须读取的文件。当 Teams Claude.md、项目目录规范和开发者 CLAUDE.md 出现冲突时，应以 Teams Claude.md 和项目级规范为准。

项目资料与知识库准备

大型项目不能依赖一次性把所有文档直接交给 AI。项目资料通常很多，AI 的上下文可能无法完整读取；文档也会持续变化，静态投喂容易过期；多个开发节点并行时，不同 AI Code 读取到的资料版本也可能不一致。因此，团队需要根据项目规模准备资料访问机制。

如果项目资料不多，可以直接放在 Git 仓库中，由 Heicode 在任务启动前读取。如果项目资料较多，建议准备团队 MCP、项目文档库、向量数据库、接口文档、数据库设计文档、权限和安全规则、部署说明，以及工单、PR、CI 的实时记录。向量数据库可以有多个，用于存放不同类型的项目资料，例如产品说明、接口文档、技术设计、历史问题、FAQ 和部署手册等。

在这个机制下，AI 不再依赖一次性读取全部资料，而是通过统一入口获取与当前任务相关的上下文。Heicode 可以在任务执行和审核时帮助 AI 检索相关信息，从而降低不同开发节点之间的信息差。

工单不是填表，而是定义 AI 的输出

Heicode 不要求用户使用固定工单模板。不同团队、不同项目、不同场景可以有不同的工单格式。工单的核心不是字段多，而是让 AI 明确知道最终应该返回什么。

一个有效工单至少应让 AI 明白四件事：我要你做什么，你最后应该交付什么，哪些内容不要做，以及完成后我如何判断你做对了。工单越模糊，AI 越容易自由发挥；工单越能描述返回结果，团队越容易执行、评审和验收。

例如，下面这样的工单不够清楚：

帮我优化一下这个模块。

更好的写法是：

请检查用户登录模块，并返回：

1. 当前登录流程的问题列表；
2. 建议修改的文件；
3. 修改后的代码或 PR；
4. 测试方法；
5. 不要改动注册、权限和账务模块。

这个示例并不是要求所有用户都必须按固定模板写工单，而是说明工单应该尽量定义 AI 的输出。对 Heicode 来说，工单不是为了填表，而是为了让 AI 的执行结果可以被追踪、被审核、被验收。

AIE：AI-Assisted Integrity Engineer

AIE 是一种推荐的协作方式（让 Heicode 切换到审核者视角做二次检查），不是一个独立的产品功能或系统组件。

AIE 是 AI-Assisted Integrity Engineer，可以理解为 AI 辅助一致性工程师。它不是普通开发者，也不是单纯的 Code Review Bot。AIE 的核心职责，是帮助团队检查 AI Code 生成的代码是否与项目目标、团队规范、工单要求和整体架构保持一致。

在传统开发流程中，Code Review 主要由人完成。但当 AI Code 大幅提升开发速度后，人工 Review 的质量和效率都会受到挑战。团队不能简单地再启动一个 AI Code 去审核，因为这样可能只是引入另一个“脑袋”。如果这个审核 AI 没有基于统一的项目资料、团队规范、工单和 PR，它可能形成自己的理解，引入新的标准，甚至偏离原始目标。

AIE 的价值在于，它不是自由发挥的 Reviewer，而是在统一上下文下进行一致性审核。它需要基于 Teams Claude.md、项目目录规范、工单内容、PR 内容、CI 结果、项目资料和团队评论来判断代码变更是否合理。它关注的不只是代码能不能运行，还包括是否超出任务边界、是否重复定义已有标准、是否影响其他模块、是否缺少测试、是否存在权限或安全风险，以及是否可以进入 E2E 阶段。

双审制度：对接人审核 + AIE 审核

在重要任务、跨模块任务、生产相关任务和大型团队协作中，建议采用“对接人审核 + AIE 审核”的双审制度。对接人审核主要负责业务目标，确认工单目标是否正确、用户需求是否被满足、返回结果是否符合预期、是否可以进入下一阶段。AIE 审核主要负责工程一致性，确认代码是否符合团队规范、项目规范、CI 要求、安全要求和跨模块协作要求。

只有人工审核，容易漏掉技术细节和跨模块一致性问题；只有 AIE 审核，又容易缺少业务判断和需求判断。双审制度的目的不是增加流程负担，而是让业务目标和工程一致性分别被检查，避免一个角色承担所有判断。

当 Heicode 进入 AIE 角色后，应根据团队规范自动读取相关项目文件、项目资料、工单信息、PR 内容和 CI 结果，并围绕代码变更进行评审。AIE 的审核意见应尽量落在可执行问题上，例如哪个文件不符合规范，哪个接口可能与已有定义冲突，哪个测试缺失，哪个修改超出了工单范围，哪个 CI 失败需要修复，哪个问题需要人工对接人确认。AIE 不应只输出“代码质量一般”“建议优化”“需要加强测试”这类笼统意见。

推荐流程如下：

开发者提交 PR
  ↓
CI 自动运行
  ↓
Heicode 进入 AIE 角色
  ↓
AIE 读取 Teams Claude.md、项目规范、工单、PR 和 CI 结果
  ↓
AIE 输出审核意见
  ↓
开发者在 PR 或工单中回复、修复或解释
  ↓
对接人进行业务审核
  ↓
满足条件后合并或进入 E2E

PR、评论和工单状态同步

AI Code 参与开发后，团队更需要及时维护工单和 PR 状态。因为 AI 的判断依赖上下文，如果工单状态、PR 评论和 CI 结果没有及时更新，AIE 和其他开发者可能会基于过期信息继续判断，导致重复审核、重复修改或错误合并。

开发者应在工单中说明当前进度，在 PR 中回复审核意见，对 AIE 提出的明确问题进行修复或解释，并及时标记已经解决的问题。已经完成的工单应及时关闭，不再推进的工单应说明原因并暂停或锁定。大型团队中，沟通延迟会直接影响 AI 协作质量。Code Review 还没有完成，代码已经迭代多轮，是 AI 协作中非常常见的风险。

因此，团队应把 PR 评论、工单状态和 CI 结果视为实时协作记录，而不是事后补充材料。Heicode 需要基于这些记录理解当前任务状态，AIE 也需要基于这些记录判断代码是否仍然符合目标。

E2E 前的一致性检查

E2E 阶段不应该是第一次发现标准不一致的地方。如果等到 E2E 才发现前后端字段不一致、状态码不一致、权限逻辑不一致、接口约定不一致或部署环境不一致，修复成本通常会很高。大型团队中，越晚发现一致性问题，牵涉的工单、分支、PR 和人员就越多。

因此，在进入 E2E 前，团队应通过 AIE 和人工对接人提前检查模块之间的接口、字段、状态码、错误格式、权限、审计、账务、测试环境、部署环境和未解决评论。如果发现问题，应优先回到工单、PR 和规范文件中修正，而不是只在测试阶段临时补丁。

AIE 在这里的作用，是帮助团队提前发现跨模块冲突和标准分裂问题。它不是替代 E2E 测试，而是让很多本该在 PR 阶段解决的问题不要拖到 E2E 阶段。

技术实践建议

在多人同时使用 AI Code 前，团队应先准备 Teams Claude.md、项目目录规范和基础资料入口。没有统一规范时，AI Code 越高效，越容易产生更多不一致实现。重要规范不应只存在于聊天记录或个人经验中，而应写入 Git 或可追踪的文档库，让 Heicode、AIE 和团队成员都可以读取同一份资料。

团队也不应把所有规则都写进一个文件。Teams Claude.md 应保持团队级最高规范，具体项目和模块规则应放在对应目录中。这样可以减少大文件失控，也能让 AI 在处理具体任务时读取更准确的局部上下文。

复杂任务不建议一次性交给 AI 完成。团队可以按阶段拆分为需求确认、技术方案、代码实现、测试修复、预发验证和生产发布；也可以按模块拆分为用户模块、权限模块、账务模块、通知模块和审计模块；还可以按风险拆分为低风险代码修改、测试环境部署、预发验证和生产审批。拆分后的任务更容易被 AI 理解，也更容易被 AIE 和对接人审核。

推荐最小流程

对于刚开始使用 Heicode 的团队，可以先采用一套最小流程。团队先准备 Teams Claude.md，并在项目目录中放置必要的局部规范。每个任务通过工单说明期望返回结果，然后使用 Heicode 启动 AI Code 或 Agent。代码变更通过 PR 提交，CI 自动检查后，由 AIE 进行一致性审核，再由对接人进行业务审核，最后合并或进入 E2E。

这套流程不要求团队一次性建立完整体系，但可以先保证三个关键点：规范可读取，结果可追踪，审核可对齐。

常见反例

一种常见反例是只有任务，没有返回结果。例如“帮我把这个系统优化一下”。这种工单看似表达了方向，但 AI 不知道最终应该交付什么，对接人也不知道如何验收，AIE 更难判断 PR 是否完成了目标。更好的方式是让工单明确返回问题列表、修改方案、PR、测试方法和不允许修改的范围。

另一种常见反例是每个开发者各写各的规则。如果不同 CLAUDE.md 之间互相冲突，AI 就可能按照局部规则突破团队规范，最终在 E2E 阶段出现接口、权限和部署不一致。正确做法是使用 Teams Claude.md 定义团队最高规范，项目和模块规则放在对应目录，开发者 CLAUDE.md 只能细化，不能突破团队规范。

还有一种反例是 PR 审核只看代码 diff。代码能运行并不代表它符合工单目标，也不代表它没有破坏跨模块约定。PR 审核应同时参考工单、Teams Claude.md、项目规范和 CI 结果。对于重要任务，应使用对接人审核和 AIE 审核共同完成判断。

最后一种反例是 E2E 阶段才开始统一标准。这个时候各模块往往已经形成不同实现，修复成本高，责任边界也不清楚。团队应尽量在 PR 阶段通过 AIE 提前检查一致性，并在进入 E2E 前完成接口、权限、测试和部署检查。

总结

AI Code 提升的是开发速度，但大型团队真正需要控制的是一致性。Heicode 推荐团队围绕 Git 建立协作主线，通过 Teams Claude.md 定义团队最高规范，通过项目目录规范承接局部细节，通过工单定义 AI 的期望输出，通过 PR 和 CI 记录代码变化，通过 AIE 和对接人双审机制保证代码、目标和项目整体一致。

最终目标不是让团队填写更多流程，而是让 AI 开发过程具备三个能力：规范可读取，过程可追踪，结果可审查。