1. 为什么单打独斗的 Claude Code 会话总在团队协作里翻车

先说一个我观察到的现象：很多团队引入 Claude Code 之后，头两周效率提升明显，第三周开始就有人抱怨“AI 生成的代码风格不统一”“同一个需求两个人问出来的实现方案完全不一样”。问题不在模型，而在于我们把 Claude Code 当成了一个“更聪明的补全工具”，而不是一个需要被编排的协作系统。

Claude Code 是 Anthropic 推出的命令行 AI 编程代理，它能读写文件、执行命令、跑测试，适合谁？适合已经在用 Git 做多人协作、有一定工程规范沉淀的后端或全栈团队。它能做什么？核心价值不是替你敲代码，而是把“需求理解→方案设计→编码→审查”这条链路里的重复认知劳动外包出去。但如果你只开一个会话从头聊到尾，上下文会随着轮次增加而衰减，早期定下的约束会被稀释，最后生成的代码就像三个人接力写出来的——每段单看都对，拼起来接口对不上。

我在一个商家运营后台项目里踩过这个坑。当时三个人共用一个 Claude Code 会话做任务分配模块，A 定了用 MyBatis-Plus 的 BaseMapper，聊到第十轮 B 让 AI 加个查询，AI 直接生成了 JPA 风格的 Repository，C 没注意就合并了，编译报错才发现。这不是模型笨，是会话里没有“角色边界”和“约束锚点”。

真正要解决的问题有三个：第一，上下文切换成本高，一个人从需求切到编码再切到审查，每次都要重建认知框架；第二，知识传递效率低，项目规范散在文档和个人脑子里，AI 每次都要重新学；第三，流程割裂，需求、设计、编码、审查串行传递，信息失真且反馈滞后。子代理加系统提示词的组合，本质上是把“一个人的多线程”变成“多个角色的流水线”，让每个 AI 角色只关心自己那一段，通过标准化中间产物对齐。

下面我会给出可直接复制的子代理配置片段、系统提示词模板，以及用真实项目验证协作效率的具体步骤。所有配置都基于 Claude Code 的.claude/目录约定，你可以直接放进仓库。

2. 前置准备：TaoToken 接入 Claude Code 的 Base URL 与 Key 配置

在讲子代理之前，得先把 Claude Code 接到一个稳定的模型服务上。Claude Code 默认走 Anthropic 官方接口，但团队协作场景下我们更希望有一个统一的入口来管理 Key、看调用量、做成本归因。TaoToken 提供的就是这样一个兼容 Anthropic 协议的接入层，官网是 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 端点是 https://taotoken.net/api 。

这里要强调一个概念：TaoToken 不是“中转”，它是一个标准的 API 网关，你拿到的 Key 和 Base URL 就是给 Claude Code 用的。Claude Code 支持通过环境变量覆盖默认端点，具体是ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY这两个。你可以在 shell 的 profile 里写，也可以在每个项目的.env里写，后者更适合团队——因为不同项目可以用不同的 Key 做成本隔离。

先拿 Key。打开 https://taotoken.net/api-keys ，登录后创建一个新 Key，权限选“模型调用”，复制出来。注意这个 Key 只显示一次，丢了就重建。然后配置环境变量，macOS/Linux 下编辑~/.zshrc或~/.bashrc：

export ANTHROPIC_BASE_URL="https://taotoken.net/api" export ANTHROPIC_API_KEY="sk-你的Key"

Windows 下用 PowerShell 的话：

$env:ANTHROPIC_BASE_URL="https://taotoken.net/api" $env:ANTHROPIC_API_KEY="sk-你的Key"

配完之后验证一下 Claude Code 能不能识别。在终端跑：

claude --version claude -p "用一句话说明你当前使用的模型"

如果第二条命令返回了模型名称而不是报 401，说明接入成功。这里有个细节：Claude Code 的模型 ID 需要显式指定，默认可能是claude-sonnet-4-5这类。你可以在项目根目录建一个.claude/settings.json，把模型 ID 固定下来，避免不同成员本地默认值不一致：

{ "model": "claude-sonnet-4-5", "env": { "ANTHROPIC_BASE_URL": "https://taotoken.net/api", "ANTHROPIC_API_KEY": "sk-你的Key" } }

注意：把 Key 写进 settings.json 只适合内部私有仓库，公开仓库请用环境变量注入。团队协作里我建议用.env.local加.gitignore的方式，settings.json 只放 model 和权限配置。

为什么前置这一步很重要？因为子代理系统会频繁调用模型，如果每个成员各自配一套 Key，成本无法归因，出了问题也不知道是谁的会话在刷量。统一走 TaoToken 之后，你可以在控制台看到每个 Key 的调用曲线，这对后面做“协作效率提升”的量化验证是基础。控制台地址是 https://taotoken.net/console ，接入文档在 https://taotoken.net/doc 。

3. 可复制的子代理配置：settings.json 与系统提示词模板

这一节是全文的核心，给出可以直接落地的配置。Claude Code 的子代理机制通过.claude/agents/目录下的 Markdown 文件定义，每个文件是一个角色，包含 frontmatter 和系统提示词正文。同时.claude/settings.json负责全局的模型、权限和 MCP 配置。

先看目录结构，这是团队协作的“骨架”：

项目根/ ├── .claude/ │ ├── settings.json │ ├── agents/ │ │ ├── architect.md │ │ ├── implementer.md │ │ ├── reviewer.md │ │ └── frontend-gen.md │ └── CLAUDE.md ├── docs/ │ └── tech-solution.md └── src/

settings.json的完整片段如下，注意 permissions 里把危险命令挡掉，团队协作最怕某个成员的 AI 会话误删文件：

{ "model": "claude-sonnet-4-5", "permissions": { "allow": [ "Read", "Glob", "Grep", "Edit", "Write" ], "deny": [ "Bash(rm -rf:*)", "Bash(git push --force:*)", "Bash(curl:* | sh)" ] }, "env": { "ANTHROPIC_BASE_URL": "https://taotoken.net/api" } }

然后是四个子代理的定义。architect.md负责需求拆解和技术方案：

--- name: architect description: 需求分析与技术方案设计，输出 tech-solution.md tools: Read, Write, Glob, Grep --- 你是技术方案架构师。你的唯一职责是把需求拆解为模块，并写入 docs/tech-solution.md。 规则： 1. 每个模块必须包含：模块ID、功能描述、复杂度、依赖模块、责任人。 2. 技术选型必须引用项目现有组件，禁止引入未在 package.json 或 pom.xml 中声明的新依赖。 3. 输出前先读 docs/tech-solution.md 的现有内容，增量修改，不要覆盖其他模块。 4. 模块划分粒度：单个模块的实现代码不超过 300 行。 5. 完成后在文档末尾追加一行：`[architect] 方案更新于 <时间戳>`。

implementer.md负责按方案写代码：

--- name: implementer description: 根据 tech-solution.md 实现单个模块的代码与单测 tools: Read, Write, Edit, Glob, Grep, Bash --- 你是代码实现专家。你一次只实现一个模块，模块ID由调用方指定。 规则： 1. 开始前必须读 docs/tech-solution.md，确认该模块的接口定义和依赖。 2. 必须复用项目现有工具类，禁止重复实现。遇到不确定的复用点，先 Grep 搜索。 3. 所有 public 方法必须有单元测试，测试文件放在 src/test 对应路径。 4. 实现完成后，把 tech-solution.md 中该模块状态改为 `[已实现]`。 5. 禁止修改其他模块的文件，如需跨模块改动，在文档中标注 `[需architect确认]`。

reviewer.md负责审查：

--- name: reviewer description: 审查代码是否符合架构设计与规范 tools: Read, Glob, Grep --- 你是代码审查专家。你只审查，不修改代码。 审查清单： 1. 是否使用了 tech-solution.md 中指定的技术栈。 2. 命名是否符合项目规范（类名大驼峰、方法名小驼峰、常量全大写下划线）。 3. 是否有空指针风险、资源未关闭、事务边界错误。 4. 单元测试覆盖率是否覆盖核心分支。 5. 输出格式：每条问题给出文件路径、行号、问题描述、修改建议。 6. 审查通过后，把 tech-solution.md 中该模块状态改为 `[已审查]`。

frontend-gen.md针对低代码后台场景，生成页面配置：

--- name: frontend-gen description: 根据接口定义生成前端页面配置 tools: Read, Write, Glob --- 你是前端页面生成器。输入是后端接口的 DTO 定义，输出是页面 JSON 配置。 规则： 1. 列表页默认包含：搜索区、表格、分页、操作列。 2. 表单页字段类型映射：String→input，Integer→number，Date→datePicker，Enum→select。 3. 权限字段从接口的 @Permission 注解读取。 4. 输出文件放在 src/pages/{module}/config.json。

系统提示词模板放在.claude/CLAUDE.md，控制在 200 字以内，只放最关键的约束。我试过写 5000 字的“百科全书”，效果反而差，AI 会顾此失彼。现在的模板是：

# 项目约定 - 分层：Controller → Service → Mapper，Service 继承 BaseServiceImpl。 - 返回：统一 Result<T>，错误码用 ErrorCode 枚举。 - 数据库：MyBatis-Plus，实体继承 BaseEntity，表名 ocs_ 前缀。 - 权限：@Permission 注解，参数校验用 @Valid。 - 外部调用：飞书用 FeishuClient，禁止重复实现。 - 遇到分布式事务，参考 docs/分布式事务最佳实践.md 的 TCC 方案。

这套配置的关键在于“约束锚定”：每个子代理启动时都会读 CLAUDE.md，等于每次对话都重新强调一遍核心规范，解决了上下文衰减问题。三件套 Base URL、Key、Model ID 分别在 settings.json 的 env、env、model 字段里，缺一不可。

4. 验证请求：用真实项目跑通子代理协作链路

配置写完，得验证它真的能跑。我拿一个“拜访任务线上化”的真实需求做演示，这个需求包含 12 个模块，从任务创建到 ES 同步，复杂度跨度大，很适合验证子代理拆分能力。

第一步，启动 architect 子代理做方案设计。在 Claude Code 里输入：

@architect 分析需求：实现拜访任务线上化，包含任务创建、审批、日程同步、列表查询、详情、统计、结果提交、分配、触达、ES同步、导入、状态变更。输出到 docs/tech-solution.md

architect 会读现有文档，然后生成模块清单。实测下来，它输出的结构是这样的：

## 模块清单 | 模块ID | 功能 | 复杂度 | 依赖 | 责任人 | |--------|------|--------|------|--------| | M1 | 任务创建 | Medium | - | implementer | | M2 | 任务审批 | High | M1 | implementer | | M3 | 日程同步 | Medium | M2 | implementer | | M4 | 任务列表 | Medium | M1 | implementer | | M5 | 任务详情 | Low | M1 | implementer | | M6 | 任务统计 | Low | M4 | implementer | | M7 | 结果提交 | Medium | M1 | implementer | | M8 | 任务分配 | High | M1 | implementer | | M9 | 任务触达 | Medium | M1,M7 | implementer | | M10 | ES同步 | Medium | M1,M4 | implementer | | M11 | 任务导入 | High | M1 | implementer | | M12 | 状态变更 | Low | - | implementer |

第二步，让 implementer 逐个实现。注意一次只给一个模块 ID：

@implementer 实现 M1，参考 docs/tech-solution.md

implementer 会先读文档，确认 M1 的接口定义，然后生成 Service、Mapper、DTO 和单测。完成后它会把 M1 状态改成[已实现]。这里有个验证点：你去看 tech-solution.md，M1 那行的状态确实变了，说明子代理的写回机制生效了。

第三步，让 reviewer 审查：

@reviewer 审查 M1 的实现

reviewer 输出问题清单，比如“TaskCreateService.java 第 45 行缺少空指针校验”“单测未覆盖审批驳回分支”。implementer 根据清单修改，reviewer 复审通过后把状态改成[已审查]。

第四步，验证接口能通。跑一下单测：

mvn test -Dtest=TaskCreateServiceTest

预期输出Tests run: 8, Failures: 0, Errors: 0。再启动服务，用 curl 打一下创建接口：

curl -X POST http://localhost:8080/api/v1/task/create \ -H "Content-Type: application/json" \ -d '{"taskName":"测试拜访","merchantId":"M001","assigneeId":"U001"}'

返回{"code":0,"data":{"taskId":"T20250101"}}就说明链路通了。

这套流程跑下来，12 个模块的协作时间是 3 天，而之前单人单会话模式做同样需求花了 5 天，且返工两次。效率提升主要来自两点：一是 reviewer 在编码阶段就拦住了问题，避免了后期联调才发现接口不一致；二是 tech-solution.md 作为单一事实来源，任何人接手都能看懂当前进度。

如果你只想验证模型连通性，不想跑完整项目，可以用模型对话页面快速测一下：https://taotoken.net/models ，输入一段 prompt 看返回是否正常。但真正的协作验证必须在项目里跑，因为子代理的价值体现在文件读写和状态同步上。

5. 常见报错排查：401、local proxy failed 与 reading choices

这一节列几个团队协作里高频出现的报错，以及对应的排查路径。这些错误我在不同项目里都遇到过，按出现频率排序。

401 Unauthorized。最常见的原因是 Key 没生效或 Base URL 写错。先检查环境变量：

echo $ANTHROPIC_BASE_URL echo $ANTHROPIC_API_KEY

如果 Base URL 末尾多了斜杠，比如https://taotoken.net/api/，某些版本的 Claude Code 会拼出//v1/messages导致 401。改成不带斜杠的https://taotoken.net/api。另一个原因是 Key 被禁用或额度耗尽，去 https://taotoken.net/api-keys 看状态。还有一种隐蔽情况：settings.json 里的 env 覆盖了 shell 的环境变量，但 Key 写错了，这时候echo看到的是对的，实际用的是错的。排查方法是临时把 settings.json 的 env 删掉，只靠 shell 变量跑一次。

local proxy failed。这个报错通常出现在公司网络环境里，Claude Code 尝试走系统代理但代理不可达。注意，这里说的不是让你去配什么特殊网络工具，而是检查你的 shell 里有没有残留的HTTP_PROXY或HTTPS_PROXY变量：

env | grep -i proxy

如果有，且指向一个已经关掉的本地端口，就会报 local proxy failed。解决方法是 unset 掉：

unset HTTP_PROXY HTTPS_PROXY http_proxy https_proxy

然后重启终端。团队协作里这个错误经常出现在新成员机器上，因为他们的 shell 配置是从旧项目拷过来的。

reading choices 相关报错。完整报错类似error reading choices: unexpected end of JSON input，这通常是模型返回的流式响应被截断。原因可能是网络抖动，也可能是单次请求的 max_tokens 设得太小。检查 settings.json 里有没有手动设max_tokens，如果有且小于 4096，调大。另一个原因是子代理的 prompt 太长，超过了模型上下文窗口，这时候需要精简 CLAUDE.md 或拆分任务。实测下来，把单个子代理的输入控制在 8000 token 以内最稳。

OAuth 相关报错。如果你之前用 Claude Code 登录过官方账号，本地会缓存 OAuth token，切换成 API Key 模式时可能冲突。报错类似OAuth token invalid。解决方法是清掉缓存目录：

rm -rf ~/.claude/credentials.json

然后重新用 API Key 启动。注意不要删整个.claude目录，那里面还有你的 agents 配置。

子代理不写回文档。这个不算报错，但很常见。现象是 implementer 跑完了，tech-solution.md 状态没变。原因是子代理的 tools 里没加 Write 权限。检查 agents/implementer.md 的 frontmatter，tools字段必须包含Write和Edit。另外，如果文档被其他进程占用（比如你正开着编辑器且没保存），写入会失败，关掉编辑器再跑。

CC Switch 切换后配置丢失。有些团队用 CC Switch 管理多套配置，切换后 settings.json 被覆盖。这时候三件套要重新确认：Base URL 是不是https://taotoken.net/api，Key 是不是当前环境的，Model ID 是不是claude-sonnet-4-5。建议把这三项写进项目的 README，新成员照着填。

排障的通用思路是：先确认环境变量，再确认 settings.json，最后看子代理的 tools 权限。90% 的问题出在前两步。如果还搞不定，去接入文档 https://taotoken.net/doc 搜报错关键词，或者直接在模型对话页 https://taotoken.net/models 发一条最小请求，看是不是模型侧的问题。

6. 把子代理协作沉淀为团队资产：从 Coding Plan 到长期迭代

跑通一次不难，难的是让这套东西在团队里持续运转。我的经验是把它当成一个“内部产品”来维护，而不是一次性配置。

第一件事是建立 tech-solution.md 的评审机制。子代理生成的方案不能直接信，必须有人工评审环节。我们的做法是每天站会花 10 分钟过一遍文档里新增的模块，确认接口定义和依赖关系合理。这一步不能省，因为如果方案阶段就错了，后面 implementer 和 reviewer 会把错误放大。我见过一个案例，architect 把“任务分配”的依赖写成了 M2 而不是 M1，结果 implementer 按错误依赖实现，reviewer 也没发现，联调时才发现审批流根本没触发。

第二件事是维护“AI 错误案例库”。每次 reviewer 发现 AI 的典型错误，就记一条到 docs/ai-error-cases.md，比如“AI 忘记处理分布式锁超时”“日期格式转换用了系统默认时区”。每两周回顾一次，把高频错误提炼成 CLAUDE.md 里的新约束。这样系统提示词是活的，会随着项目演进而进化，而不是一开始写死。

第三件事是量化协作效率。我们在 TaoToken 控制台看每个 Key 的调用量，结合 Git 提交记录，算两个指标：单模块平均实现时长、reviewer 拦截问题数。前者反映协作速度，后者反映质量。实测下来，引入子代理后单模块时长从 4 小时降到 2.5 小时，reviewer 平均每个模块拦下 3 个问题，其中 1 个是接口不一致类的严重问题。

如果你团队要长期做 AI 辅助编码，建议上 Coding Plan，它把模型调用、成本归因、团队配额做在了一起，比每人各自管 Key 省心。入口在 https://taotoken.net/coding-plan 。对于只是偶尔验证模型的场景，用模型对话页就够了，不必上完整方案。

最后说一个我踩过的坑：不要试图让子代理直接连生产数据库。MCP 可以扩展 AI 的外部能力，但生产库的读写权限必须走人工审批。我们的做法是 MCP 只连测试环境和文档系统，生产变更一律走 CI/CD。子代理再智能，也不能绕过工程纪律。

这套方法的核心不是让 AI 替你做决定，而是让 AI 把重复的认知劳动接过去，人专注于方案评审和质量把控。角色边界清晰了，上下文就不会丢；中间产物标准化了，协作就不会乱。你可以先从 architect 和 reviewer 两个角色开始试，跑顺了再加 implementer，循序渐进比一次性铺开更稳。