Claude Code 项目级多会话协作实践手册

实践手册。能力与参数对照 Claude Code 官方文档（code.claude.com，2026-10-18 核对）：跨会话消息需 v2.1.224+（macOS / Linux / WSL 2）或 v2.1.234+（原生 Windows），Agent Teams 为实验特性。文中的会话发现部分来自本机 ListAgents 实测；送达语义、审批规则与限制来自官方文档，未做跨会话收发演练（避免打扰本机既有会话），读者可按第三、四章自测。

从一个具体需求开始：系统要上一个复杂功能，横跨数据模型、接口和后端逻辑，改动面大，评审、修改、测试都得排上。手边最顺手的做法是开四个 Claude Code 窗口，各管一摊，需要传话时人肉复制粘贴。

真跑起来，麻烦会慢慢露头：三个窗口各自攒着上下文，评审意见与修改记录对不上；「这版可以吗」要在四个窗口之间来回问；窗口一多，谁是最终裁决、哪次改动经过谁的手，只能靠记忆。

这份手册先回答「为什么要多开几个会话」，再把口头约定换成可配置的机制：先选形态（跨窗口消息、编队或流水线），再立规矩（谁能给谁发消息、什么消息会被扣下），最后把裁决做成有 rubric 和门禁的流程。

一、为什么需要多个 Agent，以及四条路线

1.1 上下文与视角：多会话的第一性理由

同一段对话里，评审者读得到修改者的全部解释，修改者也读得到评审者每一次自我更正。信息看似更全，判断反而更容易趋同：修改者刚说完「这里没问题」，评审再指出同一处的风险，就要先绕过这段解释，锚定效应在同一个上下文里格外强。

拆成独立会话，每个角色带自己的上下文入场：评审者拿规格、验收标准和 diff；修改者拿裁决单和上次的返工意见；测试者拿行为描述和失败用例。谁也不必读别人的过程噪声，判断是独立做出的，再通过消息与任务列表交叉核对。多 Agent 的价值主要在这里：不同视角、不同上下文各判一遍，问题召回率通常高于一个人从头看到尾。

代价同样明确：上下文不共享，信息就必须显式传递。角色之间传什么、按什么格式回报、裁决依据什么，都要提前定，否则多开会话只是把混乱并行化。后文的模板、审批矩阵和 rubric，解决的正是这个「显式传递」问题。这与上下文工程的原则一致：上下文不是越多越好，装着什么决定判断的质量。

1.2 四条路线一张表

回到开头那个需求：四个角色、一个裁决者。落到选型上就是三个问题：要保留多个窗口？走跨会话消息。能接受合并成一个窗口？走 Agent Teams。同一个流程要反复跑？走 Dynamic Workflow。要做成工具给别人用，再看 SDK。

MCP 在这张表之外。MCP 是模型与工具之间的协议，没有 agent 间通信能力，官方也没有 A2A 支持；claude mcp serve 只把 Claude Code 的工具暴露给外部客户端，不暴露会话与消息。硬要用 MCP 搭消息总线，只有「共享 HTTP MCP server 当拉取式信箱」（每个会话自己轮询，无推送）或 Channels（研究预览，受 allowlist 限制、无投递确认）两条自建路，都拿不到原生的会话发现、命名与审批语义。原生跨会话消息已经覆盖这个需求，不必绕道。

二、会话即地址：基础机制

2.1 命名与发现

每个交互式会话都有一个名字，这就是它的地址。

   
   
   
   claude --name reviewer     # 启动时命名
# 或在会话内
/rename reviewer

人类查看可达会话用 /list-agents（别名 /peers），第一行是本会话自己的名字（v2.1.239+）。Claude 侧对应的是内置工具 ListAgents 与 SendMessage：你用自然语言下指令（「问一下 reviewer 那个迁移做完了没」），Claude 自己找人、发信；也可以在输入框里打 @ 加首字母从候选里选（v2.1.232+），名字含空格或特殊字符时加引号：@"release notes"。

几条硬规则：只有绑定了收件 socket 的会话能被寻址，bare 模式启动的会话没有 socket，不会出现在列表里；同名会话由系统附加短标识区分；/status 里的 Peer address 能看到本会话的收件地址。

2.2 送达语义

2.3 本机实测记录

在 macOS 上运行 ListAgents，返回形如（会话名做了脱敏）：

   
   
   
   本会话：公众号
Peer sessions（4）：
  reviewer-demo   · interactive · idle  · started 2h ago
  modifier-demo   · interactive · busy  · started 15h ago
  tester-demo     · interactive · idle  · started 2d ago
  judge-demo      · interactive · idle  · started 1h ago

能列出、能寻址，跨会话协作的前提就成立了。注意 busy 的会话不是不能发，消息会在它两次工具调用之间被处理。

三、路线一：跨会话消息，四窗口剧本

3.1 拉起四个窗口

   
   
   
   # 终端 1（只读，做评审）
claude --name reviewer
# 终端 2（可写，做修改）
claude --name modifier
# 终端 3（跑测试）
claude --name tester
# 终端 4（汇总与裁决）
claude --name judge

modifier 与 tester 会写文件、跑命令，建议给它们单独的工作目录或 git worktree，避免和你的主工作区互相覆盖。reviewer 与 judge 只读，不需要。

3.2 入站策略与权限模式

跨会话消息能不能进来，由接收方的 crossSessionInbound（accept / hold / refuse）决定，也可以在 /config 的「Messages from your other sessions」里改。未显式设置时，按双方权限模式推导：

被扣留的消息会弹审批框，显示发送方与预览，默认 5 分钟过期（dialogExpiry 可调，支持 "never"）。-p 会话没有审批框，默认扣留的消息到期即丢；无人值守的 worker 要在 --settings 里设 crossSessionInbound: "accept"，否则消息进不来。跨机发送想加一道人工确认，设 isolatePeerMachines: true（同机消息不受影响）。

3.3 协作剧本与消息模板

跨会话消息是纯文本，没有结构化协议，所以模板要自己定。下发给 worker 的任务卡建议包含三件事：

   
   
   
   @reviewer 任务：评审「租户权限」功能的实现分支，对照 docs/specs/rbac.md 的验收标准，diff 用 git diff main...HEAD。
输出格式（只输出这个 JSON，不修改任何文件）：
{"verdict":"pass|fail","findings":[{"line":42,"severity":"high","issue":"...","evidence":"file:line"}],"unknowns":["..."]}
时限：10 分钟内给结论；拿不准的写进 unknowns，不要猜。

worker 回报时，judge 收到的消息带 from 字段，回信直接按发送方地址回发即可。judge 想等 worker 干完再行动，用 notify_when_idle 订阅一次空闲通知，不要轮询。

裁决有三种输出：通过；打回并附整改单（具体到文件行与验收标准）；升级人工。把这三档写死，评审就不会停在「感觉不太行」。

3.4 安全边界

跨会话消息在设计上有明确边界：它不能替你批准权限请求，不能修改配置或 CLAUDE.md，消息里的斜杠命令不会被执行，接收方自己的权限规则仍然管着消息要求的工作。反过来，消息按一次普通 prompt 计费；SendMessage / ListAgents 的 deny 规则会连 subagent 与 teammate 的消息一起禁掉，团队环境里慎用这两种封禁。

3.5 故障排查

四、路线二：Agent Teams，单窗口编队（实验）