Claude Code 团队协作工作流
我在团队中落地 Harness Engineering 的实践经验------从让 Agent 看得懂项目，到让一群人 + 一群 Agent 高效协作。
我的理解
Harness Engineering 的本质是一个闭环：约束 → 告知 → 验证 → 纠正。不需要一次搭完所有基础设施，渐进式落地就行。
但我读了十多篇文章、做完交叉分析后发现，大部分实操指南（包括我之前写的）都在解决"怎么让 Agent 干活"，忽略了两个更关键的问题：
- 怎么知道 Agent 干对了------背压机制（lint、测试、CI）只能捕获结构性错误，行为正确性是盲区
- 怎么让团队协作不堵------PR 体积 +154%，评审时间 +91%，你加速的可能不是瓶颈
这篇文章是我把理论和实践交叉后重新整理的工作流。
我是怎么落地的
第一步：信息层（1-2 天）
让 Agent "看得懂"项目结构。
| 实践 | 我怎么做的 |
|---|---|
| AGENTS.md 地图模式 | 控制在 50-100 行，"你想做什么→去哪里看"表格，硬性规则单独列出。本质是前馈------在 Agent 行动之前引导它 |
| docs/ 结构化目录 | architecture / conventions / design / plans / reference 五层，每篇加 front-matter 元信息 |
| 设计文档模板 | 含目标、非目标、技术方案、验收标准、Status 标记 |
踩过的坑：AGENTS.md 一开始写了 300 行，以为越详细越好。结果 Agent 的上下文被挤占，反而表现更差。后来砍到 80 行，详细内容全移到 docs/，效果好很多。
第二步：约束层（3-5 天）
让 Agent "不得不"写好代码。
| 实践 | 我怎么做的 |
|---|---|
| 分层架构 + Linter | ESLint no-restricted-imports 锁死依赖方向；Python 用 import-linter |
| 错误信息三要素 | 每条 Linter 报错包含：问题 + FIX 代码片段 + 文档链接。Agent 能自我纠正的关键就在这里 |
| CI 管线 7 道门 | 类型检查 → Lint → 单元测试 → 覆盖率阈值 → 架构约束 → 文件大小 → 文档新鲜度 |
| 主观品味机械化 | Code Review 中被提过 3 次以上的规则 → 写成 Linter 规则 |
踩过的坑：Linter 规则一次加太多，报错信息没给 FIX 片段，Agent 陷入"改了又错、错了又改"的死循环。后来逐条添加，每条都附带修复示例，问题消失。
第三步：自动化层（1-2 周）
让 Agent 自我验证和自我修复。
| 实践 | 我怎么做的 |
|---|---|
| Git Worktree 隔离 | 创建独立分支验证，不污染主分支 |
| 后台清理 Agent | 定时扫描：超长文件、缺失测试、未用 import、TODO/FIXME、重复代码、过时文档 |
| 可观测性接入 | Loki + Prometheus + Grafana 轻量堆栈，Agent 排错时有据可查 |
交叉分析后发现的六个盲区
前三步解决的是"让 Agent 干活"。但深入研究后，我发现团队协作中还有六个更容易被忽视的问题。
1. 团队角色应该按"学派"分工，而不是按技术栈
大部分实操指南暗示所有人都在做同一件事------"搭 harness"。但读完全部文章后，我发现其实有四个完全不同的视角：
| 角色 | 应该侧重什么 | 具体做什么 |
|---|---|---|
| Tech Lead / 架构师 | 控制论视角 | 设计前馈（AGENTS.md）和反馈（Linter/CI）的闭环，确保不缺腿 |
| Senior Engineer | 架构视角 | 保持 harness 可替换，避免对特定模型 overfit |
| DevOps / 平台工程师 | 约束视角 | 把 Code Review 中反复出现的规则写成 Linter |
| EM / PM | 怀疑视角 | 定期质疑"这些约束真的在解决瓶颈吗？" |
最危险的情况是整个团队都是约束派思维------不断加 linter，但没人问"这些 linter 真的在守卫正确的行为吗？"
2. Harness 有保质期------需要"园艺日"
三阶段落地不是一次性的。一个模型代际（3-6 个月）后，之前有效的 harness 组件可能变成死重。Anthropic 的时间线就是例子：V1 的 context reset 在 Opus 上变死重，V2 直接砍掉了 Sprint 合同。
我现在做的调整：
- 每次模型大版本升级后，做一次 harness 压测------哪些规则还在承重？哪些已经是死重？
- CI 中加了一条：Lint 规则连续 90 天未触发 → 自动创建 Issue 审查是否还有必要
- 团队日历中固定了月度"Harness 园艺日"
3. 不是所有需求都应该走同一套验证
CI 七道门只能捕获结构性和回归性错误。对于"代码能编译和通过测试，但做错了事"的情况，整个体系没有可靠答案。
所以我开始给每个需求标注"可测试性等级"：
| 工作类型 | 验证策略 | 例子 |
|---|---|---|
| 需求明确 + 可测试 | CI 七道门足够 | API 实现、CRUD、数据管道 |
| 需求明确 + 不可测试 | Agent 做 + 关键节点人工审查 | UI 设计、用户体验 |
| 需求模糊 + 不可测试 | 人主导 + Agent 辅助 | 架构决策、产品方向 |
不加这个分级，所有需求都走七道门，结果就是：可测试的需求验证充分，不可测试的需求也"看起来通过"了------但行为可能完全是错的。
4. 真正的瓶颈在评审和集成，不在编码
自动化层主要优化的是"Agent 产出代码的速度"。但数据很直接------PR 体积 +154%，评审时间 +91%。你加速的不是瓶颈。
我的调整：
- 加了一层"Agent 辅助评审"------让另一个 Agent 先做结构审查（lint 通过吗？架构合规吗？测试覆盖了吗？），人类只审行为正确性
- 显式跟踪评审等待时间------如果持续增长，说明需要加评审容量，而不是加更多编码 Agent
- 引入"Agent 工作队列"，避免多人在同一模块同时让 Agent 工作（集成冲突会指数级增长）
5. 每条 Linter 规则必须有对应的"设计意图"
信息层（AGENTS.md）是前馈，约束层（Linter）是反馈。它们必须配对：
AGENTS.md 写了"依赖方向单向"（Guide/前馈）
↕ 必须 配对
ESLint `no-restricted-imports`（Sensor/反馈）只有 Guide 没有 Sensor：Agent 看了规则但违反了也没人知道，规则白写。
只有 Sensor 没有 Guide：Agent 碰到报错但不知道为什么有这条规则，自我纠正效率低。
我现在加了一条硬规则：每条 Linter 规则必须能追溯到 AGENTS.md 或 docs/ 中的某一段设计意图。追溯不到的，要么补文档，要么删规则。
6. 工具选型要评估迁移成本
模型 post-training 阶段与特定 harness 共同训练，换工具后性能可能暴跌。Terminal Bench 数据：排名从 Top 5 掉到 Top 30。
所以我的选型策略是：
- 把工具特定的配置（如 Claude Code 的 CLAUDE.md）和工具无关的约束（如架构规则、Linter）分层管理
- 工具可以换，约束应该可移植
- Phase 1（AGENTS.md + docs/）和 Phase 2（Linter + CI）天然是工具无关的，风险集中在 Phase 3 的自动化脚本------这些脚本有明确的抽象层，方便将来换工具
Agent 工具选型
我用过或调研过的工具：
| 工具 | 适合场景 | 我的评价 |
|---|---|---|
| Claude Code | 深度自主任务（6h+ 连续工作） | 我的主力工具。长任务表现稳定，但迁移成本要注意 |
| Aider | 个人项目，终端党 | 轻量，适合快速迭代 |
| Cline | 小团队，Plan/Act 模式 | Plan 阶段可视化做得好 |
| OpenHands | 团队级部署，Docker 沙箱隔离 | 安全隔离做得好，适合多人协作 |
参考资料
- Harness Engineering 最佳实践：从概念到落地的完整操作手册 --- 落地三阶段、Linter 配置、CI 管线、踩坑经验
- 案例代码（ocean-dock 示例项目） --- Harness Engineering 初始化模板
- OpenAI 原文：Harness engineering: leveraging Codex in an agent-first world --- 原始方法论
- deusyu/harness-engineering --- 深度学习指南（19 篇文章 + 8 个跨文章洞见）
- harness-engineering.ai --- 知识图谱（883 实体）