在 Claude Code 里养一个"高级工程师"团队：Sub-Agent 架构实战

• 1. 不是”更快的打字员”，而是”懂流程的架构师”
• 2. 团队代码库：三层架构
  • 2.1 Hooks：管理层基础设施
  • 2.2 员工手册：1% 规则
• 3. 头脑风暴与设计：写代码前的硬门禁
  • 3.1 视觉白板辅助
  • 3.2 技能发现流程
• 4. 执行引擎：Sub-Agent 驱动的开发
  • 4.1 Plan Review：计划审查关卡
  • 4.2 质量门禁：两道审查
• 5. TDD 铁律与系统化调试
  • 5.1 先写测试，再写代码
  • 5.2 四阶段调试法
• 6. 写技能 = 对流程文档做 TDD
• 7. 真实效果：测试一个完整项目
• 8. 如何进一步改进
• 9. 总结

1. 不是”更快的打字员”，而是”懂流程的架构师”

Junior 和 Senior 工程师之间真正的差距，不是语法熟练度，而是在压力下依然保持的预测能力、风险管理和工程纪律。

AI Agent 正好缺这个：它们会跳过审查、给自己找捷径、产出”自己觉得很好但没人审过”的代码。Anthropic 的实验已经证明，多个 Agent 协作时如果没有结构化流程，更多的 Agent 只会带来更多的混乱和浪费的算力。

FareedKhan 最近开源了一个项目，用 Claude Code 的 Sub-Agent 系统搭建了一套完整的”Staff Engineer 团队”，从设计到发布，每个环节都有专人（Agent）把关：

整个系统像一家真正的工程公司，职责清晰分工：

• 架构师（Architect）：逐个提问、探索方案、产出设计文档——不写一行代码，直到人类批准
• 技术主管（Tech Lead）：把设计拆成 2-5 分钟的任务，指定文件路径和完整代码
• 执行经理（Manager）：为每个任务启动独立 Sub-Agent，卡住的上报，坏的中止重派
• 质量门禁（Quality Gates）：两道独立审查
• TDD 铁律：先写测试再写代码，毫无例外

所有代码已开源：GitHub - FareedKhan-dev/claude-code-staff-engineer

2. 团队代码库：三层架构

作为一个需要协作的 Agent 团队，不能像单兵作战那样”让 Claude 自己摸索”。系统需要一个类似人类工程团队的结构化代码库：

senior_staff_engineer/
├── agents/        # 团队花名册——定义谁做什么
├── commands/      # 自定义 CLI 命令
├── hooks/         # 管理层——控制信息流和初始化
├── skills/        # 员工手册——流程和标准

agents/ 是团队目录，定义每个 Agent 的角色和职责。skills/ 是员工手册，包含每个成员必须遵守的流程。hooks/ 是管理层，确保每次会话开始时所有 Agent 都对齐。

2.1 Hooks：管理层基础设施

在真实公司里，每天开工前办公室已经开好门、咖啡机在运行、日历已同步——没人会注意到这些基础设施，直到它们出问题。

在 Claude Code 里，hooks 就是这个管理层。

配置很简单：每次会话启动时，运行初始化脚本。

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup|clear|compact",
        "hooks": [
          {
            "type": "command",
            "command": "\"${PROJECT_ROOT_DIR}/hooks/run-hook.cmd\" session-start",
            "async": false
          }
        ]
      }
    ]
  }
}

async: false 是关键——好比”早会没开完，谁都不准打开电脑”。因为对 AI Agent 来说，每次会话都是 D-Day，它没有昨天会话的记忆，每次都需要重新入职。

脚本在启动时将核心技能文件注入 Agent 上下文，相当于入职培训手册。它还兼容 Claude Code、Cursor 和 Copilot CLI 三种平台——跨平台思维正是 Staff Engineer 该有的基础设施设计。

2.2 员工手册：1% 规则

SKILL.md 是整个系统最重要的文件，开篇第一条规则是所有行为的基石：

如果你觉得有 1% 的可能性某个技能适用于当前任务，你必须调用它。这不是建议。不是可选项。你不能用任何理由绕过去。

这就是 1% 规则。没有它，Agent 会把技能当建议——任务”看起来简单”就跳过头脑风暴，”只是改个配置”就跳过 TDD，”就两行代码”就跳过审查。

每位 Senior 工程师都见过团队如何通过这些”小理由”逐渐放弃流程，结果总是同样的：质量下降、Bug 上线、谁都不知道发生了什么。

但 Sub-Agent 有一个逃生阀：如果它是被主 Agent 派来执行特定任务的，它不需要走完整的技能发现流程——相当于告诉合同工”你不需要参加全员大会，做你被雇来干的事就行”。

3. 头脑风暴与设计：写代码前的硬门禁

在 Amazon，写产品之前先写新闻稿。在 Basecamp，先写 pitch 文档。在 Google，设计文档要通过三个级别的审查才允许写一行代码。

共同点是什么？先想，再造。

在 Fareed 的系统中，头脑风暴技能开篇就是一道硬门禁（Hard Gate）：

在呈现设计方案并获得用户批准之前，不得调用任何实现技能、不得写任何代码、不得搭建任何项目。这适用于每一个项目，无论你觉得它多简单。

最危险的理由是”这个太简单了，不需要设计”。但经验表明——”简单”的配置修改影响了三个服务；”快速”的工具函数需要处理七个没人提到的边界条件；”简单”的 Todo 应用最后需要离线同步、冲突解决和多用户支持。

简单项目恰恰是未检验假设造成浪费最多的地方。

3.1 视觉白板辅助

在设计环节，系统还提供一个白板工具——当 Agent 觉得某些设计问题用视觉呈现比文字描述更清晰时，它会主动启动一个本地服务器，在浏览器中渲染设计方案的交互式线框图。

这不是被动的工具——Agent 自己判断哪些问题适合视觉呈现，然后主动启动。就像在会议上画白板的资深工程师。

3.2 技能发现流程

系统定义了一套完整的技能发现流程：收到任务 → 检查是否有技能适用 → 调用技能 → 声明正在使用的技能 → 遵循技能清单 → 响应。

最难的部分不是定义流程，而是拦截 Agent（和人）的自我合理化倾向。系统内置了一张红牌表：

4. 执行引擎：Sub-Agent 驱动的开发

设计通过后，执行经理登场。它的工作方式是这样的：

1. 为每个任务启动一个独立的 Sub-Agent，上下文完全隔离
2. 卡住的 Agent 自动上报
3. 执行质量差的 Agent 被终止并重新派发
4. 每个 Sub-Agent 有清晰的职责边界，不会相互干扰

4.1 Plan Review：计划审查关卡

在执行之前，所有任务计划要经过一个独立的 Sub-Agent 审查：

• Spec Review：检查计划是否完整覆盖了设计文档的要求
• Scope Creep 检查：确保计划没有超出设计范围
• 任务粒度验证：每个任务必须在 2-5 分钟内完成

这个审查者是一个独立的 Sub-Agent，被专门创建来”找茬”的。它的工作就是挑毛病——如果找不出问题，说明审查不够仔细。

4.2 质量门禁：两道审查

每个任务完成之后，要经过两道独立审查：

1. Spec Compliance Review（做对的事？）— 代码是否符合设计规范
2. Code Quality Review（做得好吗？）— 代码质量是否达标

验证门禁更进一步：任何完成声明都必须附带新的终端输出作为证据。只有纯文本的”我完成了”不算数。

5. TDD 铁律与系统化调试

5.1 先写测试，再写代码

Fareed 的系统把 TDD 定为不可撼动的铁律：

先写代码再写测试？删除代码。重来。没有例外：

• 不能”留着当参考”
• 不能在写测试时”顺便适配”
• 不能”看一眼”
• 删除就是删除

系统还为 TDD 定义了一系列反模式——那些 Agent 试图走捷径的方式：

• Test-Last Laziness：写完代码再补测试 = 测试覆盖的是写好的代码，不是需求
• Happy-Path Only：只测正常路径，异常路径全部忽略
• Assertion Minimalism：断言数量最少化，通过的测试没有价值
• Mock Everything：过度 Mock 让测试与具体实现耦合

每种反模式都有明确的定义和对应的修正策略。

5.2 四阶段调试法

Bug 修复不是随意开始的。系统有一套四阶段取证流程：

1. 理解 Bug — 生成精确的复现步骤
2. 定位根因 — 用日志、断点、二分法找到根本原因
3. 修复 — 只改最少量的代码
4. 验证 — 确认修复有效且没有回归

根因追踪要求五层深度——不是问”哪行代码错了”，而是追问”为什么那行代码会存在”、”为什么测试没发现”、”为什么 review 没发现”、”是什么流程漏洞允许它上线”。

6. 写技能 = 对流程文档做 TDD

这个系统最反直觉的设计是：写 SKILL.md 的过程本身就是 TDD。

写测试用例（Agent 压力测试）→ 看它们失败（基线行为）
→ 写技能文档 → 看测试通过（Agent 遵守流程）→ 重构（修补漏洞）

核心原则：如果你没有见过 Agent 在没有技能时的失败行为，你就不知道技能该教什么。

大多数团队把流程文档写出来、发布到 Confluence，就假设它有效。但 Fareed 的系统把文档当代码——你不会把函数不经测试就上线，为什么流程文档要例外？

不同的技能需要不同的测试类型：

• 纪律性技能（必须遵守的规则）→ 压力测试 + 组合压力测试
• 技术性技能（如何操作）→ 应用场景测试
• 参考性技能（API 文档）→ 检索测试

7. 真实效果：测试一个完整项目

Fareed 用一个真实项目验证了系统效果：从 YouTube 转录集合构建一个交互式技能关联可视化图谱。

系统做的第一件事完全不像在”做项目”——它探索。调用头脑风暴技能 → 派 Sub-Agent 扫描项目结构 → 阅读所有文档 → 不形成任何意见，只是安静地了解。

然后它创建一个完整的头脑风暴清单，一步一步执行。它甚至主动提供了一个视觉白板——在问第一个问题之前，先启动了本地服务端，让设计问题可以在浏览器中可视化的呈现和讨论。

提问方式是一个接一个的苏格拉底式追问，而不是一次性抛出一堆问题。每一次追问都基于前一次的答案——这才能发掘批量提问永远发现不了的细节：比如”视觉探索应该是主要访问模式”这个需求，会改变整个架构。

一旦收集完需求，它不是在代码编辑器里写，而是在白板浏览器中渲染三种不同方案的交互式线框图，标注优劣，等人类选择。

从开始到第一行生产代码产生前，房间里的环节都是纯思考。没有实现。没有搭建项目结构。没有一个 Agent 说”让我先搭个架子”。

8. 如何进一步改进

作者在文末留下了一个路线图，指向了下一个阶段的方向：

• 跨会话记忆：每次会话都是 D-Day，一个持久的记忆层让 Agent 可以积累机构知识
• 模型路由：根据任务复杂度自动选择不同成本的模型
• Agent 间通信：让并行工作的 Sub-Agent 能互相发现”我找到了一个共享工具”
• 技能回归测试：CI 流程每晚运行压力场景，发现 Agent 开始绕过流程时自动报警
• 人工反馈闭环：当人类驳回一个决定时，反馈信号加固被违反的规则

这些方向让这个系统从一个”AI 开发辅助”向”AI 工程组织”演进——不再只是一个更聪明的代码助手，而是一个拥有流程、纪律、学习能力的数字工程团队。

9. 总结

FareedKhan 的这个项目展示了一个重要趋势：未来 AI Agent 开发的瓶颈不是模型能力，而是工程纪律。

当多个 Agent 协作时，”更多的 Agent = 更多的混乱”这条规律和人类世界如出一辙。唯一能打破它的是——比人类更严格的流程定义、更彻底的规则执行、更不留情面的质量审查。

这个系统的设计哲学值得每个做 Agent 开发的团队学习：先定义流程，再写代码；先设置门禁，再开放权限；先测试技能，再部署执行。

它的价值不在于自动化了多少工作，而在于把软件开发中最难复制的东西——工程文化的流程纪律——变成了可编程、可复用的资产。

版权所有，本作品采用知识共享署名-非商业性使用 3.0 未本地化版本许可协议进行许可。转载请注明出处：https://www.wangjun.dev//2026/05/build-senior-staff-engineer-in-claude-code/