1. 为什么串行对话撑不起真实项目：从一次优惠券需求说起
Claude Code 用久了会遇到一个明显的瓶颈：单轮对话只能线性推进。你问一句它答一句，调研、写方案、审查、改写全挤在同一个上下文里，聊到后面它开始遗忘前面的约束，你不得不反复贴需求文档。我试过用一个会话硬扛「优惠券叠加」这种中等复杂度的需求，结果调研阶段还没结束，上下文已经塞满了网页摘要和代码片段，方案质量断崖式下跌。
这个问题的本质是上下文污染。一个 Agent 同时扮演需求分析师、技术调研员、方案架构师、审查官四个角色，每个角色的关注点互相干扰。调研员需要广撒网看大量资料，审查官需要严格对照规则挑毛病，两者的「思维模式」完全不同，塞进同一个上下文只会互相稀释注意力。
Claude Code 给出的解法是把这些角色拆成独立的Subagent，每个 Subagent 拥有自己的上下文窗口和工具权限，主 Agent 只负责调度和汇总。再配合Skill把「需求→调研→编写→审查→改写」这套流程固化成可复用的说明书，你就从「每次重新解释一遍要干什么」变成「一句话触发整条流水线」。
这篇教程面向已经用过 Claude Code、但还在用单会话串行干活的开发者。我会拆解 Subagent 的分工设计、Skill 的流程编排写法，重点讲清楚并行任务怎么落地——这是把串行对话改造成可维护工作流的关键一步。全程给出可复制的配置片段，最后用一个真实需求跑通验证。
核心检索词先明确：Claude Code 工作流、Subagent 并行、Skill 复用，这三样组合起来能做什么？简单说，就是让 AI 像一个虚拟开发团队那样，多个角色同时开工，主控汇总结果，你只负责下需求和验收。
2. TaoToken 前置：给 Claude Code 配好可用的模型入口
在搭工作流之前，得先保证 Claude Code 能稳定调用模型。Subagent 并行会成倍放大请求量，如果模型入口不稳定，并行任务里只要有一个请求超时，整条流水线就卡住了。所以这一步不是可选项。
TaoToken 提供的是兼容 Anthropic 接口的模型调用入口，Claude Code 可以直接对接。你需要准备三样东西：Base URL、API Key、Model ID。这三件套在后面的 Subagent 配置里会反复出现，先记牢。
Base URL 用https://taotoken.net/api，注意这个地址不带任何查询参数。API Key 在控制台的 API Keys 页面生成，建议给工作流单独建一个 Key，方便按项目统计用量。Model ID 根据你的 Subagent 角色来选，调研类任务用响应快的模型，审查类任务用推理更严谨的模型。
配置方式有两种。第一种是环境变量，适合全局生效：
export ANTHROPIC_BASE_URL="https://taotoken.net/api" export ANTHROPIC_API_KEY="sk-你的key"第二种是写进 Claude Code 的配置文件，适合按项目隔离。在项目根目录的.claude/settings.json里写：
{ "env": { "ANTHROPIC_BASE_URL": "https://taotoken.net/api", "ANTHROPIC_API_KEY": "sk-你的key", "ANTHROPIC_MODEL": "claude-sonnet-4-20250514" } }这里有个容易踩的坑：Base URL 结尾不要多加/v1。Claude Code 内部会自己拼接路径，你多写一层会变成/v1/v1/messages，直接 404。我见过不少人卡在这里，以为是 Key 失效，其实是地址写重了。
配好之后先做一次最小验证，别急着上工作流。运行：
claude -p "回复 ok"如果返回ok，说明模型入口通了。如果报 401，检查 Key 是否复制完整、有没有多余空格。如果报连接超时，检查 Base URL 是否写成了带 UTM 参数的完整链接——那个是给浏览器用的，API 调用只要域名加/api。
对于要跑并行工作流的场景，建议在控制台里把这个 Key 的额度看清楚，并行任务消耗比串行高，心里有个数。需要生成 Key 的话去 API Keys 页面，接入细节可以对照接入文档。
3. 可复制配置：Subagent 分工 + Skill 流程 + 并行 Task
这一节是整篇的核心，给出能直接抄进项目的配置。目录结构先理清楚：
项目根/ ├── .claude/ │ ├── agents/ # Subagent 定义 │ │ ├── requirement-analyst.md │ │ ├── tech-researcher.md │ │ ├── solution-architect.md │ │ └── reviewer.md │ ├── skills/ # 流程说明书 │ │ └── solution-workflow.md │ ├── rules/ # 全局约束 │ │ └── planning-constraints.md │ └── settings.json # 模型入口配置3.1 定义四个专用 Subagent
每个 Subagent 是一个 Markdown 文件，头部用 YAML frontmatter 声明元信息，正文是角色设定。关键是tools字段——只给这个角色真正需要的工具，权限越窄越安全。
需求分析师，负责把模糊需求变成结构化文档：
--- name: requirement-analyst description: 需求沟通与澄清，输出结构化需求规格说明书 tools: Read, Grep, Write model: claude-sonnet-4-20250514 --- 你是需求分析师。与用户沟通后输出《需求规格说明书》，必须包含： 1. 功能列表（每条可验收） 2. 约束条件（性能、兼容性、依赖） 3. 验收标准（可量化） 输出路径：docs/requirements.md技术调研员，负责对比选型、输出调研报告：
--- name: tech-researcher description: 技术选型对比，输出带对比表的调研报告 tools: Read, WebFetch, Write model: claude-sonnet-4-20250514 --- 你是技术调研专家。针对指定调研方向，输出包含对比表、优劣势分析、 适用场景建议的报告。每个结论必须标注信息来源。 输出路径：docs/research/{topic}.md方案架构师，负责综合需求和调研结果写方案：
--- name: solution-architect description: 综合需求与调研报告，输出技术方案设计文档 tools: Read, Write, Grep model: claude-sonnet-4-20250514 --- 你是方案架构师。输入需求文档和全部调研报告，输出设计文档，包含： 背景、技术选型对比、详细设计、风险评估、测试策略。 输出路径：docs/design-proposal.md审查官，负责挑毛病，不通过必须给具体修改建议：
--- name: reviewer description: 严格审查方案，输出通过/不通过及逐条修改意见 tools: Read, Grep model: claude-sonnet-4-20250514 --- 你是资深审查官。依据 .claude/rules/ 下的规则逐条核对方案。 输出格式：「章节-问题-建议修改」，不得空泛。 结论只能是 PASS 或 FAIL，FAIL 时必须列出至少一条具体问题。注意审查官的工具里没有 Write。这是故意的——审查官只读不写，避免它自己动手改方案，改写交给专门的 rewriter 角色。职责单一，输出才稳定。
3.2 编写流程 Skill
Skill 是流程编排说明书，它告诉主 Agent 什么时候调用哪个 Subagent。放在.claude/skills/solution-workflow.md：
--- name: solution-workflow description: 技术方案闭环流程：需求→并行调研→编写→审查→改写 --- # 技术方案工作流 当用户说「按 solution-workflow 处理」时，执行以下步骤： ## 步骤 1：需求澄清 调用 subagent `requirement-analyst`，传入用户原始需求。 等待输出 docs/requirements.md 后再进入下一步。 ## 步骤 2：并行调研 从需求文档中提取调研方向，为每个方向启动一个 `tech-researcher`。 使用 Task 工具并行调用，不要串行等待。 每个调研任务指定独立的输出路径，避免写文件冲突。 ## 步骤 3：方案编写 调用 `solution-architect`，输入需求文档 + 全部调研报告。 ## 步骤 4：审查改写循环 - 调用 `reviewer` 审查 docs/design-proposal.md - 若 FAIL，调用 `rewriter` 按意见修改，回到步骤 4 - 最多循环 5 次，仍 FAIL 则终止并报告用户3.3 并行 Task 的写法
这是把串行改造成并行的关键。在 Skill 的步骤 2 里，不要写「依次调研 A、B、C」，而是明确要求同时启动：
## 步骤 2：并行调研 同时启动以下调研任务（使用 Task 工具并发调用）： 1. Task(subagent="tech-researcher", prompt="调研现有促销引擎的扩展性，输出到 docs/research/engine.md") 2. Task(subagent="tech-researcher", prompt="对比 json-rules-engine 与 zeebe 规则引擎，输出到 docs/research/rules.md") 3. Task(subagent="tech-researcher", prompt="调研高并发下优惠券计算的性能瓶颈，输出到 docs/research/perf.md") 等待全部返回后，汇总生成 docs/research/summary.md。每个 Task 的输出路径必须不同，否则多个 Subagent 同时写同一个文件会互相覆盖。这是并行场景下最常见的翻车点。
3.4 全局规则约束
在.claude/rules/planning-constraints.md里写死底线，所有 Agent 都受约束：
--- type: always --- # 技术方案编写约束 1. 方案必须包含：背景、技术选型对比、详细设计、风险评估、测试策略。 2. 引入第三方库必须提供对比表和已知漏洞检查。 3. 审查意见格式：「章节-问题-建议修改」，不得空泛。 4. 所有调研结论必须标注来源，禁止编造数据。type: always表示这条规则在所有对话中生效。如果你只想让它在某个 Subagent 里生效，把规则内容写进那个 Subagent 的正文即可。
4. 验证请求：跑通一次并行任务流水线
配置写完，得实际跑一次确认整条链路通了。用一个具体需求来验证：给电商后台加「优惠券叠加」功能。
在项目根目录启动 Claude Code，输入：
按照 solution-workflow 处理以下需求： 为电商后台添加优惠券叠加功能，支持满减券和折扣券按规则叠加计算。 现有代码位于 /src/promotion。预期执行流程是这样的：主 Agent 先调用requirement-analyst，产出docs/requirements.md。然后进入并行调研阶段，同时启动三个tech-researcher，分别调研促销引擎扩展性、规则引擎选型、高并发性能。三个任务并行跑，总耗时约等于最慢的那个，而不是三个相加。
验证并行是否真的生效，看日志。运行：
claude logs --tail如果看到三个 Task 几乎同时开始、时间戳接近，说明并行成功。如果是一个接一个串行出现，检查 Skill 里是否写明了「并行调用」——有些情况下主 Agent 会保守地串行执行，需要显式强调。
调研完成后，solution-architect综合所有报告写方案，reviewer审查。如果 FAIL，rewriter按意见改，再回到审查。整个循环最多 5 次。
验证成功的标志有三个：docs/requirements.md存在且包含可验收的功能列表；docs/research/下有多个独立报告文件；docs/design-proposal.md存在且审查结论为 PASS。
想单独验证模型入口是否正常，可以用模型对话页面发一条测试消息，确认返回正常再跑工作流，能省去排查入口问题的时间。
跑通之后你会发现，同样的需求，串行模式要来回对话十几次，工作流模式一句话触发，中间过程全自动。省下的不只是时间，更是上下文管理的精力。
5. 常见报错排查：401、local proxy failed、reading choices
并行工作流跑起来后，报错会比单会话更集中地暴露出来。下面几个是我实际遇到过的，对照着排查。
401 Unauthorized。最常见的原因是 API Key 没配对。检查.claude/settings.json里的ANTHROPIC_API_KEY是否和 TaoToken 控制台生成的一致，注意有没有多余空格或换行。另一个原因是 Base URL 写错，比如写成了带 UTM 参数的完整链接。API 调用只要https://taotoken.net/api，不要带?utm_source=...那串。三件套里 Base URL、Key、Model ID 任何一个错都会导致 401 或 404。
local proxy failed。这个报错通常出现在你本地配了代理，但代理没启动或端口不对。Claude Code 会读取环境变量里的代理设置。检查HTTP_PROXY、HTTPS_PROXY是否指向了一个不存在的端口。如果不需要代理，直接 unset 掉这两个变量。并行任务对连接稳定性要求高，代理链路不稳会频繁触发这个错。
reading choices 相关报错。这类错误说明请求发出去了，但返回的数据结构不符合预期。常见于 Model ID 写错——比如写了一个 TaoToken 不支持的模型名，返回体里没有choices字段。对照控制台里可用的 Model ID 列表核对一遍。另一个可能是 Base URL 多写了/v1，导致请求打到了错误的路由。
OAuth 相关报错。如果你之前用官方账号登录过 Claude Code，本地可能残留了 OAuth 凭证，和 API Key 模式冲突。清理掉旧的凭证缓存，确保走的是 API Key 认证。检查~/.claude/下有没有残留的 token 文件。
并行任务写文件冲突。这个不报错，但结果会错乱——多个 Subagent 同时写同一个文件，后写的覆盖先写的。排查方法是检查每个 Task 的prompt里输出路径是否唯一。统一放到docs/research/下但文件名不同，就不会冲突。
并发数超限。并行任务开太多会触发速率限制。用这个命令限制并发：
claude config set maxConcurrentTasks 5普通工作流建议不超过 7 个并发。任务确实多的话，分批跑，或者拆成两级——先并行粗筛，再对候选结果深度调研。
排查顺序建议从入口开始：先用claude -p "回复 ok"确认模型入口通，再跑工作流。入口不通的情况下排查工作流配置是浪费时间。需要重新生成 Key 的话去 API Keys，配置细节对照接入文档。
6. 把工作流用起来：从单次验证到长期复用
配置跑通一次之后，接下来是让它变成日常工具。几个实用建议。
Subagent 的工具集要克制。调研员给WebFetch和Write就够了，别给它Bash——它不需要执行命令，给了反而增加误操作风险。审查官只给Read和Grep，让它专注挑毛病。工具越窄，角色行为越稳定。
模型选择上，调研类 Subagent 用响应快的模型，因为要并行跑多个，速度和成本都敏感。审查类可以用推理更强的模型，它只跑一两次，值得多花一点。在 Subagent 的 frontmatter 里用model字段分别指定。
并行任务的数量要控制。普通方案建议 5 到 7 个并发，再多容易触发速率限制，而且主 Agent 汇总结果的上下文也会膨胀。如果调研方向超过 7 个，先做一轮粗筛，每个方向只返回 3 到 5 个关键指标，再对筛出来的候选做深度调研。
Skill 是可以复用的。solution-workflow这套流程不只适用于优惠券需求，任何「需求→调研→方案→审查」的场景都能套。你只需要换需求描述，流程本身不用改。这就是把串行对话改造成工作流的价值——流程固化下来，每次只换输入。
长期跑编码和 Agent 任务的话，可以关注 Coding Plan，按用量规划比单次调用更划算。工作流跑顺之后，你会发现真正的瓶颈不再是「AI 能不能做」，而是「你怎么设计分工」。Subagent 拆得越合理，Skill 写得越清晰，整条流水线的产出就越稳定。
最后留一个实操技巧：每次改完 Subagent 或 Skill 配置，先用一个小需求跑一遍验证，别直接上大需求。配置错误在大需求里会被放大，排查成本高得多。小步验证，快速迭代，这套工作流才能真正为你所用。
