这篇 Gist 就像一本“怎么带一群AI小伙伴一起干活”的菜鸟入门手册。它教你如何用 Claude Code 的 TeammateTool + 任务系统 来组织一群智能体协同工作，把复杂任务分成小块整齐完成。
当你面对一个庞大、复杂、甚至有点吓人的任务时，别慌，你根本不需要自己硬扛。Claude Code 的这套系统，就是让你当上一支由 AI 小伙伴组成的“智能特工队”总指挥官。
你只需要一声令下，一群各有所长的 AI 队员就会自动集结、分工协作、互相通信、完成任务，最后整整齐齐地向你汇报战果。
整个系统围绕四个核心角色展开：你（队长）、队友（AI 智能体）、任务（待办事项）和收件箱（消息通道）。你负责发号施令，队友负责执行，任务是大家共同的目标，收件箱则是彼此沟通的微信私聊窗口。
所有这些都被组织在一个叫“团队”的文件夹里，结构清晰得像军训列队，每个成员都有自己的编号、身份和职责，连聊天记录都存成 JSON 文件，方便随时回溯。
1️⃣ 基本角色（Primitives）——谁是谁？
这里列出了一些常见的“角色和概念”解释如下：
* 智能体（Agent）：就是一个会思考的问题解答 AI，小伙伴级别的助手。
* 团队（Team）：一群智能体组成的小组，有一个队长。
* 队友（Teammate）：那群被招来的智能体队员。
* 队长（Leader）：你！带队的人。
* 任务（Task）：小目标，比如“找文件”“写报告”这种。
* 收件箱（Inbox）：队友之间传信息的地方。
* 任务列表（TaskList）：排队的小目标集合。
这个部分相当于告诉你：“我们要组织一队机器人一起干活，它们各自有名字、分工、能互相发消息。”
文件结构：
~/.claude/teams/{队伍名称}/ |
创建团队就像开个微信群，但这个群能自动干活
一切的起点，是你决定要干一件大事。这时候，你不需要手动一个个拉人，而是直接调用 TeammateTool 的 spawnTeam 操作，比如写一句 Teammate({ operation: "spawnTeam", team_name: "my-project" })。
这一行代码，就相当于你在微信里点“新建群聊”，然后起名叫“我的项目攻坚组”。
系统立刻会在你的用户目录下创建两个专属文件夹：~/.claude/teams/my-project/ 和 ~/.claude/tasks/my-project/。
前者存放团队的“户口本” config.json，里面登记了所有成员的姓名、ID、颜色标签和加入时间；
后者则是任务的“作战室”，每个任务都以独立的 JSON 文件形式存在，编号从 1 开始。
你作为发起人，自动成为 team-lead，拥有最高权限，可以批准新人加入、分配任务、发送全局通知，甚至下令解散整个团队。
2️⃣ 工作流程大概长啥样（Lifecycle）
智能体协作分大步走：
1. 创建团队：你先说“我们叫这个队去搞事情”。
2. 定义任务：把整个任务拆成好几块。
3. 召唤队友：让小伙伴们加入你的团队。
4. 分配任务：每个人接一块去做。
5. 协调与沟通：队友互相发消息、汇报进度。
6. 完成任务 & 停工：所有小目标完成，你下令大家收工。
7. 打扫现场：删掉临时文件、清理配置。
流程图 LR |
6️⃣ spawnTeam 和 TeammateTool 操作总览
智能体团队靠下面这些命令来管理：
* spawnTeam：建立团队，就像开个群。
* discoverTeams：查查有哪些团队可加入。
* requestJoin：请求加入某个团队。
* approveJoin / rejectJoin：队长同意或拒绝队友加入。
* write：私信某个队友。
* broadcast：向所有队友发送消息（就像群聊）。
* requestShutdown：叫队友结束工作。
* approveShutdown / rejectShutdown：队友自己同意结束还是继续工作。
* cleanup：收尾，把临时资源删掉。
4️⃣ 任务系统（Task System）
任务这块比上面讲得更详细：
* 任务有 编号、状态、负责人、依赖关系。
* 任务可以被阻塞（比如任务 #3 被 #1 和 #2 卡着）。
* 当阻塞的那些任务完成了，后面的才会解除锁定。
就是把大任务像搭乐高一样，一块块按顺序完成。
任务不是待办清单，而是带依赖关系的乐高积木
在这个系统里，任务远不止是简单的“To-Do”。每一个任务都是一个结构化的 JSON 对象，包含 ID、主题、详细描述、当前状态、负责人、以及最关键的——依赖列表 blockedBy。
这意味着你可以把一个大项目拆解成一系列逻辑严密的小步骤，并明确指定它们的先后顺序。
例如，你可以先创建任务 #1 “研究 OAuth2 最佳实践”，再创建任务 #2 “设计认证系统架构”，然后通过 TaskUpdate({ taskId: "2", addBlockedBy: ["1"] }) 告诉系统：任务 #2 必须等任务 #1 完成后才能开始。
这种依赖机制让整个工作流像搭乐高一样精准。当任务 #1 被标记为 completed，系统会自动检查所有被它阻塞的任务，并将符合条件的任务状态更新为 pending，使其可以被其他队友认领。
任务本质上是放在本地文件夹里的 JSON 文件，每个任务都有：
✔️ ID
✔️ 描述
✔️ 状态
✔️ 谁在做
✔️ 拦着它完成的哪些任务
就像你写下 To-Do List，一项一项推进。
召唤队友有两种方式：临时工和正式队员，用错就亏大了
Claude Code 提供了两种截然不同的召唤 AI 助手的方式，选择哪一种，直接决定了你的工作效率。
第一种是使用 Task 工具直接调用 subagent，比如 Task({ subagent_type: "Explore", prompt: "Find all auth files" })。
这种方式召唤出来的 AI 就像一个高效的临时工，它会立刻执行你给的指令，完成后直接把结果返回给你，然后就消失了。
它不加入任何团队，没有收件箱，也不能参与后续的协作。
这种方式最适合做那些快速、独立、一次性的查询或分析工作。
第二种方式才是真正的团队协作：你必须先创建一个团队，然后在调用 Task 时同时指定 team_name 和 name 参数，比如 Task({ team_name: "my-project", name: "security-reviewer", ... })。
这样召唤出来的 AI 会成为一个正式的 teammate，它会被写入团队的 config.json，拥有自己的收件箱，并且可以主动从共享的任务列表中认领工作。它会一直存在，直到你显式地请求它 shutdown。
这两种方式的核心区别在于生命周期和协作能力，搞混了就会导致信息孤岛或者资源浪费。
消息系统是团队的神经系统，私聊比群发更高效
在一个由多个 AI 组成的团队里，如何确保信息准确、高效地传递？答案就是 inbox 消息系统。
每个成员，包括你这个队长，都有一个专属的 JSON 文件作为收件箱。
当一个队友需要向你汇报进度、请求指示或发送结果时，它不会把内容输出到主聊天窗口（那是你看不到的），而是必须调用 Teammate({ operation: "write", target_agent_id: "team-lead", value: "..." })，将消息精准投递到你的收件箱里。
同样，你也可以用 write 操作私信任何一个特定的队友。
这种点对点的通信方式，保证了信息的私密性和准确性。虽然系统也提供了 broadcast 操作可以群发消息，但文档里明确警告这很“昂贵”，因为它会给每个队友都发一条独立的消息。
所以，除非是遇到服务器着火这种级别的紧急事件，否则永远优先使用 write 进行精准沟通。
小结，智能体之间的通信很像打微信：
队长 -> 队友：write（私聊，告诉你做什么）
队长 -> 全体：broadcast（群发消息，但花资源）
队友 -> 队长：汇报进度
⚠️ 不是每条输出都是对大家可见，有些只是“队友内部自己看”。
AI 队友不是千篇一律的，而是身怀绝技的特种兵
这个系统最强大的地方，在于它提供了一整套预设的、各具特色的智能体类型，让你可以根据任务需求精准匹配。
Bash 智能体就是一个命令行老手，专门负责执行 git status、npm install 这类系统命令。
Explore 智能体是你的侦察兵，速度快、成本低，擅长在代码库里地毯式搜索文件或模式。
Plan 智能体则是个战略家，能为你规划出实现某个功能的详细步骤。
而 general-purpose 智能体则是全能型选手，拥有所有工具的使用权，适合处理需要多步操作的复杂任务。
更酷的是，通过插件，你还能召唤出各种领域的专家，比如 security-sentinel（安全哨兵）专门揪出代码里的安全漏洞，performance-oracle（性能先知）负责找出性能瓶颈，kieran-rails-reviewer（Rails 代码审查员）则能用 Rails 社区的最佳实践来审视你的代码。
小结：不同的智能体有不同风格：
Bash智能体：像一个终端小助手，会敲命令。
Explore智能体：擅长快速扫描，把信息找出来。
Plan智能体：负责提出解决方案，像出主意的小伙伴。
Research智能体：擅长查资料和文档。
还有很多“插件型智能体”，就像给小伙伴装了额外的技能包，比如专门做安全检查、性能评估、代码风格检查那种。
从研究到上线，一套完整的自动化流水线就这么跑起来了
你要为一个新功能从零开始构建一套完整的开发流程。
首先，你创建一个名为“feature-oauth”的团队。
接着，你一口气创建五个任务：#1 研究、#2 规划、#3 实现、#4 测试、#5 最终审查，并设置好它们的依赖关系，形成一条严格的流水线。
然后，你召唤五位专家加入团队：
一位 best-practices-researcher 负责任务 #1，
一位 Plan 智能体负责任务 #2，
一位 general-purpose 智能体负责任务 #3，
另一位 general-purpose 智能体负责任务 #4，
最后一位 security-sentinel 负责任务 #5。
一切就绪后，你什么都不用做。研究员会自动认领并完成任务 #1，完成后，规划师发现任务 #2 已解锁，立刻接手并产出方案。方案一完成，实现者就开始编码，编码一结束，测试员就跑测试，最后安全专家进行全面审查。整个过程全自动、无中断，你只需要在最后去收件箱里收取一份完整的、经过层层把关的交付报告。
当所有任务都顺利完成，胜利的喜悦过后，千万别忘了最重要的一步：清理现场。
一个不负责任的队长可能会直接关掉终端，留下一堆残骸。但一个专业的指挥官会严格执行 shutdown 流程。
首先，你需要对每一个还在运行的队友调用 requestShutdown，礼貌地通知它们工作已经结束。每个队友在收到请求后，必须调用 approveShutdown 来确认，这既是礼节，也是系统用来确认队友已安全退出的信号。
只有在所有队友都确认退出后，你才能调用 cleanup 操作。
cleanup 会彻底删除 ~/.claude/teams/ 和 ~/.claude/tasks/ 下对应团队的所有文件，让你的系统恢复到 pristine 状态。
如果跳过 shutdown 直接 cleanup，系统会报错“Cannot cleanup with active members”，因为这可能导致数据丢失或进程僵尸。
你召唤的 AI 队友们到底是在后台默默干活，还是在你眼前实时表演？
这取决于你运行 Claude Code 的环境。
如果你在普通的终端里运行，系统会默认使用 in-process 模式，所有队友都在同一个 Node.js 进程里作为异步任务运行。你看不到它们的思考过程，只能通过收件箱接收最终结果。
这种方式最快、最轻量，适合自动化脚本。
但如果你在 tmux 会话里运行，或者使用 macOS 的 iTerm2 并安装了 it2 工具，系统就会自动切换到 tmux 或 iterm2 模式。
这时，每个队友都会获得一个独立的终端窗格，你可以亲眼看到它们一行行地输出思考、执行命令、调试错误。
这种可视化模式对于调试和理解 AI 的行为至关重要，让你从一个单纯的发令者，变成一个可以实时观察、干预和学习的导演。
你可以根据自己的需求，通过环境变量 CLAUDE_CODE_SPAWN_BACKEND 强制指定运行模式，完全掌控这场人机协作大戏的呈现方式。
并行、流水线与自组织蜂群
掌握了基础操作后，你就可以玩转三种高级协作模式，把 AI 团队的效率榨干。
第一种是“并行专家模式”：面对一个复杂的代码审查任务，你可以同时召唤安全、性能、架构三位专家，让他们各自从不同角度并行分析同一份代码，最后将三份报告汇总，得到一个360度无死角的评估。
第二种是“流水线模式”，如前所述，将任务分解为严格的前后依赖，让不同专长的 AI 依次接力，确保每一步都建立在前一步的坚实基础上。
第三种，也是最酷的，是“自组织蜂群模式”：你创建一大堆彼此独立的小任务（比如审查一百个文件），然后召唤三到五个通用型 AI 队友，给它们一个统一的指令：“去任务池里找活干，干完一个再拿下一个”。
这些 AI 会自发地竞争、认领、完成任务，实现完美的负载均衡。你只需要坐等所有任务完成的通知。
这三种模式，分别对应了协同、串行和分布式计算的思想，让你可以根据任务特性，灵活选择最高效的作战阵型。
小结：这个 Gist 在讲什么
这个文档是给有 多智能体编排需求的人准备的操作指南，帮助你懂得：
✅ 怎么把一个大任务拆成好多子任务
✅ 怎么组织一队 AI 小伙伴一起干
✅ 怎么让他们彼此沟通、互相汇报
✅ 怎么结束任务并清理资源
它把整个流程 从零带你入门，像教你当一个 AI 小队长一样写顺序剧本一样分步骤实现。