背景

上礼拜一个做技术的朋友问我："你们搞的这个 Claude Code 多 agent，到底是个啥？我看网上又是 agent teams 又是 workflows 的，还有人说必须上 Claude Opus 才能跑，Kimi K3 行不行？"

我想了想，这事一句话说不清楚，干脆写篇文章统一回复。

先说结论：学会多 agent 的最好方式，是亲手做一个真项目。你看十篇教程，不如跟着我把一个真实项目搭一遍。这篇文章我拿一个已经跑通了的真实案例来讲——一套"四 agent + wiki 协作"的项目初始化体系，你跟着做一遍，agent teams、workflows、ultracode 这些概念自然就明白了。

1 三个概念，一句话说清

先把术语掰扯清楚，不然后面全是糊涂账。

1.1 Agent Teams：一群 AI 分工干活

一个人干项目，需求、设计、开发、测试、上线全包，累不说，还容易顾此失彼。Agent Teams 就是把这个"一个人"拆成"一队人"：

我实际项目里的配置：

• pm agent：管需求，写需求文档，评审设计是否符合需求
• developer agent：管设计和写码，写设计文档，过评审后写生产代码
• tester agent：管测试，写用例，跑测试，打回不合格代码
• releaser agent：管上线，走安全审核清单，写上线记录

这四个 agent 不是随口说说，是真的在 .claude/agents/ 下各建一个 .md 文件，写清楚职责边界。比如 tester 的边界就是"不改生产代码，测试失败只能写证据打回，不能顺手修"。

1.2 Workflows：给 AI 排好 SOP

光有分工还不够，还得有流程。Workflows 就是规定"谁先干、谁后干、怎么交接"的 SOP。

我项目里的核心流程是一条状态机：

讨论中 → 待评审 → 已批准 → 设计中 → 设计评审中 → 开发中 → 测试中 → 待上线 → 已上线

每个状态对应"下一步谁干什么"：

这个流程写在 wiki/workflow.md 里，是主会话和 4 个 agent 的共同契约。

1.3 Ultracode：多模型混编作战

很多人以为跑 agent teams 必须全上 Claude Opus，其实不用。Ultracode 的思路是"谁的活儿给谁"——主会话（编排器）用 Claude，子 agent 按任务类型选模型。

我实际项目里 UI 测试就指定了 Kimi K3：

tester agent 定义里写死：主会话派 UI 测试单时指定 model: claude-sonnet-kimik3，因为 Kimi K3 是多模态模型，能直读截图复核视觉细节；纯后端测试就不限定模型。

这就是 ultracode 的核心逻辑：主模型负责编排和判断，子模型按能力混编。

2 什么时候该用，什么时候别瞎折腾

不是所有人都需要上多 agent，我见过有人把"写一个 Hello World"都拆成三个 agent，纯属脱裤子放屁。

2.1 三种该用的场景

1）任务可拆解，且质量要求高

比如开发一个新功能，需求、设计、编码、测试、上线每个环节都有明确产出物，且产出物质量直接影响下游。我项目里一个 REQ 从讨论到上线，要走完 8 个状态，每个状态都有产出物：需求文档、设计文档、测试用例、结果报告、上线记录。

2）需要多角色评审，防单一视角盲区

设计文档为什么要 pm+tester 双评审？因为 pm 只看"是否符合需求意图"，tester 只看"可测性+边界覆盖"。一个人看容易漏，两个人交叉看才能兜住。

3）有标准流程，且需要留痕追溯

上线这事不能马虎。我项目里 releaser 必须走 deploy skill 的安全审核清单：密钥、日志泄密、注入、存储写路径、依赖、文档同步，六项逐项过，缺一项就打回。这个流程不标准化，早晚出事故。

2.2 三种不该用的误区

1）任务太简单

改个错别字、调个样式，直接干就完了，走全流程纯属浪费。所以我项目里有"简轨"机制：单模块小改、bug 修复、配置文档类改动，跳过设计文档和设计评审，直接进开发。简轨只豁免设计环节，测试和上线审核永不豁免。

2）上下文太短，信息密度低

一个 50 行脚本能解决的事，拆成 agent 反而增加沟通成本。agent 之间靠 wiki 文件交接，每个交接都有读写开销。

3）成本敏感且非关键路径

多 agent 意味着多轮 LLM 调用。我项目里一个全轨 REQ 走完，pm、dev、tester、releaser 加起来十几轮调用。如果是非核心功能，或者预算紧张，直接单 agent 干就完了。

3 实战项目：四 agent + wiki 协作体系

下面讲真东西。这是我一个真实项目里跑通的体系，你跟着做一遍就明白多 agent 怎么玩了。

3.1 项目背景与需求拆解

这个项目要解决什么问题？一句话：让 Claude Code 在任何新项目里，按手册一步步搭出"主会话编排 + 四 agent + wiki 驱动"的协作体系。

需求拆解成 8 步：

1）建目录骨架：wiki/、logs/、.claude/agents/、.claude/skills/
2）写 4 个 agent 定义：pm、developer、tester、releaser
3）写协作 SOP：wiki/workflow.md
4）写文档骨架 + 模板：readme、四份模板、看板、经验汇总
5）写 skills + 脚本 + settings 改造
6）写项目级 CLAUDE.md
7）按项目扩展（全新项目 vs 已有项目两条路径）
8）验收：跑脚本 + 模拟一个 REQ 走通全流程

前 6 步是机械搭建，第 7 步才需要动脑子——读新项目实际代码，把现状逆写进 wiki。

3.2 怎么设计 agent 分工

四个 agent 的定义文件，每份都有 frontmatter 和职责边界。以 developer 为例，关键设计：

---
name: developer
description: 开发 agent。根据已批准需求先写设计文档并接受评审，评审通过后写生产代码。不跳过设计评审直接写代码——除非派单注明「简轨」。
tools: Read, Write, Edit, Glob, Grep, Bash
---

注意两个设计点：

• description 里写明例外："除非派单注明简轨"。这是给主会话看的，告诉它什么时候可以跳设计。
• tools 明确限制：developer 有 Bash 能跑测试，但没有 WebFetch，防止它跑偏去查外部资料。

职责按严格顺序写死：

1. 设计（全轨）：读需求 → 写设计文档 → 看板翻「设计评审中」→ 停下来等评审
2. 修订：评审打回 → 按意见修订 → 等复审
3. 开发：评审通过 → 写生产代码 → 自测 → 看板翻「测试中」
4. 经验沉淀：上线后回填设计文档 §8 + experience.md

边界条款是防越权的第一道闸：

- 评审通过前不写生产代码（唯一例外是简轨）
- 不改 wiki/pm/ 的需求内容、不写 wiki/tests/、不写 wiki/release/
- 发现需求本身有问题 → 打回给主会话，不擅自扩大或缩小范围

3.3 workflow 怎么排

workflow 的核心是状态机，但有两个关键设计值得单独说。

第一，简轨与全轨的分叉。

不是所有需求都值得走全流程。主会话在「已批准」时先判轨道：

这个设计解决了"流程太重"的痛点。我项目里 60% 的 REQ 走简轨，省掉了设计文档和两轮评审，但测试和上线审核一个不少。

第二，讨论区与经验沉淀。

需求讨论期的草稿放 wiki/discuss/，结论一出即流向正式文档或删除，执行完不留痕。这是防止"草稿堆积"的机制。

经验沉淀分两级：

• 每个 REQ 上线后，developer 回填设计文档第 8 节「经验与教训」
• 可复用的一行经验追加到 wiki/dev/experience.md，供改代码前快速检索

这个设计让团队知识不随项目结束而流失。

说到经验沉淀，我想起 2018 年做摄像机项目时，团队里有个老工程师离职，带走了红外遥控协议的所有踩坑记录，新接手的兄弟又重新踩了一遍，光 38kHz 载波频率就调了三天。从那以后我就明白：经验不沉淀，等于团队在白干。这套 wiki + experience.md 的机制，就是给 AI 团队也装上"经验不落地"的保险。

3.4 跑出来的效果与踩过的坑

这套体系在我项目里跑了 20+ 个 REQ，效果：

• 需求平均交付周期从 3 天降到 1.5 天（简轨的功劳）
• 上线事故率降为 0（releaser 安全审核清单的功劳）
• 文档与代码漂移率大幅降低（my-check skill + freshness 脚本的功劳）

踩过的坑也不少：

1）agent 越权改文件

边界条款靠指令约束，无法强制封锁。有一次 developer 顺手改了 tester 的用例文件，被 code review 抓到。后来加了条款：发现越权行为应纠正并回报用户，严重时在 agent 定义里补针对性条款。

2）UI 测试截图存证难

脚本测试能验证接口契约，但页面渲染对不对，脚本说了不算。后来给 tester 加了 browser-test skill，用 headless Chrome 实测并截图。Chrome 二进制固定在 tests/third_party/chrome/，版本与 chromedriver 配套。

3）多模型混编的上下文一致性

Kimi K3 和 Claude 混编时，发现 Kimi 对某些 prompt 结构的理解有偏差。解决办法：主会话派单时，给 Kimi 的 prompt 更结构化，关键信息用列表而非段落。

4 模型选择：Kimi K3、GLM 5.3 能不能用？

这是最多人问的问题。我特意去查了最新官方文档（2026-09-06 时点），给你列个明白账。

4.1 当前可用模型状态

数据来源
Kimi 平台文档：platform.kimi.ai/docs（2026-09-06 时点）
Z.ai 文档：docs.z.ai/guides/llm/（2026-09-06 时点）
GLM 5.3 在 Z.ai Code Bench 达 34.5%，超过 Claude Opus 4.8，低于 Claude Fable 5

4.2 怎么混编：主 agent 用 Claude，子 agent 按能力选

我的配置原则：

1）主会话（编排器）用 Claude Opus

编排器要判断状态机流转、拆解任务、裁决评审分歧，这些都需要强推理能力。Claude 在这方面最稳。

2）子 agent 按任务类型选

• developer：编码任务可用 GLM 5.3 或 Kimi K2.7 Code，实测 GLM 5.3 在 Terminal-Bench 3.0 达 28.3，比 GLM 5.2 的 4.6 提升 6 倍
• tester：UI 测试指定 Kimi K3（多模态，能看截图）；纯后端测试不限定
• pm/releaser：文档和审核任务，Claude Sonnet 即可

3）混编注意事项

• 不同模型对 prompt 结构的理解有差异，派单 prompt 要结构化
• 上下文窗口要匹配任务长度，1M 窗口的模型适合长文档分析
• 价格差异大，高频调用的子 agent 可用性价比更高的模型

4.3 一个实际配置示例

我项目里 .claude/settings.json 的权限白名单按技术栈配，Python 项目加 Bash(python3:*)、Bash(pytest:*)，Node 项目加 Bash(npm:*)。这是减少权限询问打断的关键。

PostToolUse 钩子注册 remind-doc-sync.sh，代码文件被编辑后自动提醒同步 wiki。这是防文档漂移的兜底机制。

==多 agent 不挑模型，挑的是分工==

5 保姆级上手步骤

废话不多说，跟着做。

5.1 准备工作

1）安装 Claude Code（略）
2）准备一个 git 仓库（新项目 git init，已有项目直接进）
3）在项目根目录启动 Claude Code

5.2 初始化四 agent 体系

把整个初始化手册交给 Claude Code，说"按这份手册初始化项目协作体系"。手册里包含每一步要创建的文件的完整内容，全部去业务化。

这份手册我沉淀成了模板，放在项目 wiki 的 design 目录下，已去业务化。你拿去就能用，占位符用 <尖括号> 标注，替换成你项目的真实信息即可。手册核心内容我在第 3 节已经拆解过了，跟着做就行。

如果你只要最小可用版本，手动建这几个文件：

mkdir -p wiki/{discuss,pm,dev,tests,release,templates} \
         .claude/agents .claude/skills

然后逐个创建：

• .claude/agents/pm.md
• .claude/agents/developer.md
• .claude/agents/tester.md
• .claude/agents/releaser.md
• wiki/workflow.md
• wiki/pm/to-do.md

每个文件的内容按我第 3 节讲的思路写，关键是职责边界和状态机。

5.3 跑通第一个 REQ

模拟一个需求走全流程：

1）在 wiki/discuss/ 建草稿，跟主会话讨论
2）派 pm 升格为正式需求文档
3）主会话判轨道（简单需求走简轨）
4）派 developer 开发
5）派 tester 测试
6）派 releaser 上线
7）developer 回填经验

跑通后删掉模拟文件，看板清零。

5.4 常见问题排查

最后

回到开头那句话：学会多 agent 的最好方式，是亲手做一个真项目。

这篇文章给你的不是理论，是一套我跑通了的完整方案。你拿去初始化一个新项目，或者改造一个已有项目，跟着状态机走一遍，agent teams、workflows、ultracode 这些概念就全活了。

别光看，动手做。做完一个 REQ，你就明白我在说什么了。

如果你在做过程中卡住了，或者跑出了更好的经验，欢迎回来交流。这套体系不是终点，是起点——你完全可以根据项目特点加 agent、改状态机、换模型组合。工具是死的，用法是活的。