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_URLhttps://taotoken.net/api export ANTHROPIC_API_KEYsk-你的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 或 FAILFAIL 时必须列出至少一条具体问题。注意审查官的工具里没有 Write。这是故意的——审查官只读不写避免它自己动手改方案改写交给专门的 rewriter 角色。职责单一输出才稳定。3.2 编写流程 SkillSkill 是流程编排说明书它告诉主 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(subagenttech-researcher, prompt调研现有促销引擎的扩展性输出到 docs/research/engine.md) 2. Task(subagenttech-researcher, prompt对比 json-rules-engine 与 zeebe 规则引擎输出到 docs/research/rules.md) 3. Task(subagenttech-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审查。如果 FAILrewriter按意见改再回到审查。整个循环最多 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 配置先用一个小需求跑一遍验证别直接上大需求。配置错误在大需求里会被放大排查成本高得多。小步验证快速迭代这套工作流才能真正为你所用。