【Claude Code】BMad-Method 多智能体协作实战：PRD 与架构文档一键生成，TaoToken 统一 Key 接入

1. 从「一句话需求」到 PRD 与架构文档BMad-Method 多智能体协作到底解决什么问题如果你用 Claude Code 写过稍大一点的项目大概率遇到过这种场景一句话丢进去「帮我做个刷题 App」它噼里啪啦给你生成一堆文件跑起来发现登录逻辑和题库接口对不上改一处崩三处。这不是模型不行而是单轮对话式编码天生缺三样东西——全局需求约束、架构前置规划、角色分工闭环。BMad-MethodBreakthrough Method of Agile AI-Driven Development就是冲着这三个缺口来的它把一次开发拆成「分析师 → 产品经理 → 架构师 → 产品负责人 → Scrum Master → 开发 → 测试」多个智能体角色每个角色只干自己那一段产出结构化文档再交给下一个角色当上下文。这样 PRD、架构文档、迭代清单、测试用例都是链式生成的不会各说各话。这篇要解决的核心检索词就是Claude Code BMad-Method 多智能体协作生成 PRD 与架构文档。适合谁适合已经在用 Claude Code、但被「上下文遗忘 架构无规划 幻觉返工」折磨的独立开发者和三五人小团队。我会给你可复制的 agent 角色配置、BMad 工作流文件、以及用 TaoToken 统一 Key 接入 Claude Code 的完整步骤最后用一次真实需求迭代把「需求 → PRD → 架构 → 开发 → 评审 → 测试」整条链跑通给你看。先说清楚 BMad 和普通「多开几个对话窗口」的区别。普通做法是你自己复制粘贴上下文模型之间不共享记忆BMad 的做法是把每个角色的输出落成docs/下的 Markdown 文件下一个角色读文件而不是读你的口头描述。文件即上下文这是它能减少幻觉的根本原因。我实测下来一个中等复杂度的需求走完 BMad 全流程大概产出 8 份文档后面 dev 角色写代码时引用的是架构文档里的接口定义而不是自己瞎编。下面这张表先帮你建立角色认知后面配置和命令都围绕它展开角色职责典型产出文件analyst业务分析、竞品与场景梳理1-业务分析-xxx.mdpm把想法转成 PRD2-需求文档-xxx.mdarchitect整体技术方案、接口与数据设计3-技术方案-xxx.mdpo迭代需求清单与验收标准4-产品待办-xxx.mdsm迭代节奏、协作风险5-敏捷迭代-xxx.mddev编码实现与接口说明6-开发实现说明-xxx.mdqa测试用例与上线准入8-测试用例报告-xxx.md理解了这张表你就明白为什么 BMad 能把「一句话需求」变成可交付的工程文档——每个角色都有明确的输入文件和输出文件责任边界清晰不会互相甩锅。2. TaoToken 统一 Key 接入 Claude Code 的前置准备在跑 BMad 之前得先让 Claude Code 能稳定调用模型。这里我用 TaoToken 做统一接入原因是它一个 Key 就能覆盖 Claude 系列模型省得你在多个平台之间来回切 Key、改环境变量。官网入口是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册后在控制台生成 API Key 即可。接入 Claude Code 的关键是三件套Base URL API Key Model ID。很多人卡在第一步是因为 Claude Code 默认走官方端点你需要通过环境变量把它指向 TaoToken 的 API 地址。API 基础地址是 https://taotoken.net/api 注意这个地址不带任何查询参数直接填进配置里。先做环境变量配置。macOS / Linux 在~/.zshrc或~/.bashrc里加Windows 用系统环境变量或 PowerShell 的$env:# TaoToken 统一接入配置 export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEYsk-你的TaoToken密钥 export ANTHROPIC_MODELclaude-sonnet-4-20250514如果你用的是 Claude Code 的 settings 文件方式推荐团队协作时更好管理在项目根目录或用户目录建.claude/settings.json{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的TaoToken密钥, ANTHROPIC_MODEL: claude-sonnet-4-20250514 } }这里有个坑要提前说ANTHROPIC_BASE_URL结尾不要带/v1Claude Code 会自己拼路径你多写一段就会 404。我试过在末尾加/v1结果请求直接打到不存在的路由上报错信息还特别隐晦排查了十几分钟才反应过来。Key 的获取路径是控制台里的 API Keys 页面生成后只显示一次记得当场复制。如果你还想在网页端先验证模型是否可用可以用模型对话页面发一条测试消息确认 Key 有额度、模型能正常返回再去配 Claude Code这样能把「Key 问题」和「配置问题」分开排查。配置完成后用一条最简单的命令验证连通性claude -p 只回复两个字连通如果返回「连通」说明 Base URL、Key、Model ID 三件套都对。如果报 401八成是 Key 复制时带了空格或者用了已删除的 Key如果报连接超时检查 Base URL 是不是写成了带/v1的版本。这一步过了才轮到装 BMad。3. 可复制的 BMad-Method 工作流与 agent 角色配置BMad 的安装本身不复杂一条命令搞定但真正决定成败的是工作流文件和角色配置。先装npx bmad-method install如果你之前装过更新用git pull npm run install:bmad安装完成后项目里会多出bmad/或.bmad/目录不同版本路径略有差异以你本地为准里面包含 agents、tasks、templates、workflows 四类资源。核心组件对应关系是Agents 定义角色能力Tasks 定义执行步骤Templates 定义输出格式Workflows 定义执行序列。你要改的就是 agents 和 workflows。先看一个精简版的 agent 角色配置放在bmad/agents/下文件名比如analyst.agent.yamlagent: id: analyst name: 业务分析师 description: 负责业务需求梳理、场景分析与竞品调研 model: claude-sonnet-4-20250514 instructions: | 你是资深业务分析师。收到需求后先拆解业务目标、目标用户、 核心场景与边界条件输出结构化业务分析文档。 不要写代码不要设计数据库只聚焦「做什么、为谁做、为什么做」。 inputs: - 用户原始需求描述 outputs: - path: docs/1-业务分析-{{project}}.md template: business-analysis constraints: - 输出必须包含业务目标、用户画像、核心场景、非功能需求、风险点 - 每个场景需给出验收视角的成功标准再配一个 architect 角色这是生成架构文档的关键agent: id: architect name: 架构师 description: 基于 PRD 设计整体技术方案、接口与数据模型 model: claude-sonnet-4-20250514 instructions: | 你是系统架构师。读取 PRD 后输出技术选型、模块划分、 接口定义、数据模型与部署拓扑。接口需给出请求/响应字段。 所有技术决策要写明理由与备选方案。 inputs: - docs/2-需求文档-{{project}}.md outputs: - path: docs/3-技术方案-{{project}}.md template: tech-architecture constraints: - 必须包含模块依赖图文字描述即可 - 接口清单需标注鉴权方式与错误码 - 数据模型需给出字段类型与索引建议工作流文件把角色串起来放在bmad/workflows/full-cycle.yamlworkflow: id: full-cycle name: 需求到测试全流程 steps: - agent: analyst command: *analyst output: docs/1-业务分析-{{project}}.md - agent: pm command: *pm input: docs/1-业务分析-{{project}}.md output: docs/2-需求文档-{{project}}.md - agent: architect command: *architect input: docs/2-需求文档-{{project}}.md output: docs/3-技术方案-{{project}}.md - agent: po command: *po input: docs/3-技术方案-{{project}}.md output: docs/4-产品待办-{{project}}.md - agent: dev command: *dev input: docs/3-技术方案-{{project}}.md output: docs/6-开发实现说明-{{project}}.md - agent: qa command: *qa input: docs/2-需求文档-{{project}}.md output: docs/8-测试用例报告-{{project}}.md注意{{project}}是变量BMad 的模板系统支持变量替换和条件逻辑你可以在调用时传入项目名比如projectkotime所有输出文件就自动带上项目后缀不会互相覆盖。这套配置的好处是角色职责写死在 yaml 里模型每次执行都读同一份指令输出格式稳定不会这次给你表格下次给你散文。如果你用 Cline 或 CC Switch 这类工具管理多个模型端点记得把 TaoToken 的三件套也填进去Base URL 填https://taotoken.net/apiKey 填你的 TaoToken 密钥Model ID 填claude-sonnet-4-20250514。三件套缺一不可尤其是 Model ID填错会直接报模型不存在。4. 一次完整需求迭代从需求到 PRD、架构文档与测试用例现在拿一个真实需求跑一遍。需求是「用 Spring Boot 整合轻量级性能分析工具 KoTime要求能采集接口耗时、慢方法排行并提供可视化页面。」这是一个典型的中等复杂度需求够验证全流程。第一步启动 analyst。在 Claude Code 里输入*analyst 当前项目 Spring Boot 整合 KoTime 性能分析工具输出业务分析文档存放 docs/1-业务分析-kotime.mdanalyst 会输出业务目标接口性能可观测、用户画像后端开发与运维、核心场景慢接口定位、方法级耗时排行、非功能需求采集开销低于 5%、风险点埋点侵入性。这一步不写代码纯业务视角。第二步pm 基于业务分析生成 PRD*pm 根据 docs/1-业务分析-kotime.md 生成 PRD 需求文档输出 docs/2-需求文档-kotime.mdPRD 里会出现用户故事、功能规格、验收标准。比如「作为后端开发我希望看到近 1 小时慢接口 Top20以便快速定位性能瓶颈」验收标准写清楚响应时间、数据刷新频率。第三步architect 生成技术方案*architect 根据 docs/2-需求文档-kotime.md 生成整体技术方案输出 docs/3-技术方案-kotime.md这一步是重点。架构文档会给出依赖引入方式Maven 坐标、配置项采样率、存储方式、接口定义/kotime/api/slow-methods的请求响应字段、数据模型耗时记录表字段与索引、以及为什么选内存存储而不是直接落库的理由。我实测下来这份文档的接口定义详细到可以直接拿去写 Controllerdev 角色后面就是照着它实现的。第四步po 梳理迭代清单*po 根据 docs/3-技术方案-kotime.md 梳理迭代需求清单与验收标准输出 docs/4-产品待办-kotime.md第五步dev 编码实现*dev 依据 docs/3-技术方案-kotime.md 编码实现 KoTime 集成输出接口与代码说明文档存放 docs/6-开发实现说明-kotime.mddev 会生成pom.xml依赖片段、application.yml配置、以及核心的拦截器代码。比如采集接口耗时的拦截器Component public class KotimeInterceptor implements HandlerInterceptor { private final KotimeRecorder recorder; public KotimeInterceptor(KotimeRecorder recorder) { this.recorder recorder; } Override public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) { request.setAttribute(kt_start, System.nanoTime()); return true; } Override public void afterCompletion(HttpServletRequest request, HttpServletResponse response, Object handler, Exception ex) { long start (long) request.getAttribute(kt_start); long costMs (System.nanoTime() - start) / 1_000_000; recorder.record(request.getRequestURI(), costMs, ex ! null); } }第六步architect 做代码评审*architect 执行代码 Review核对代码规范与架构合规性输出 docs/7-代码评审记录-kotime.md评审会指出问题比如「拦截器未排除静态资源路径会导致无意义采集」「recorder 未做并发保护高并发下计数可能丢失」。然后你让 architect 修复*architect 帮我修复上面全部代码问题第七步qa 生成测试用例*qa 依据 docs/2-需求文档-kotime.md 与 docs/3-技术方案-kotime.md 编写全套测试用例输出 docs/8-测试用例报告-kotime.mdqa 会给出正常场景、边界场景耗时 0ms、超大耗时、异常场景接口抛异常时是否记录的用例以及上线准入标准。到这里从一句话需求到 PRD、架构、代码、评审、测试整条链闭环产出 8 份文档。整个过程你只做了「发命令」这一件事上下文传递全靠文件。5. 常见报错排查401、local proxy failed、reading choices 与 OAuth跑这套流程时报错基本集中在接入层和上下文层。我把踩过的坑按报错原文列出来你对照着查。401 Unauthorized / invalid api key这是最高频的。原因通常是三种——Key 复制时带了首尾空格、Key 已被删除或额度耗尽、环境变量没生效。排查顺序先在终端echo $ANTHROPIC_API_KEY看值对不对再去 TaoToken 控制台的 API Keys 页面确认 Key 状态。如果是 settings.json 方式检查 JSON 有没有语法错误导致整个文件没被加载。local proxy failed / connection refused这个报错说明 Claude Code 尝试连的地址不对。九成是ANTHROPIC_BASE_URL写错了比如写成了https://taotoken.net/api/v1或者结尾多了斜杠。正确值就是https://taotoken.net/api不带/v1不带尾斜杠。改完记得重开终端让环境变量生效。reading choices / unexpected response format这个报错通常出现在模型返回体不符合预期时常见于 Model ID 填错。比如你填了一个 TaoToken 不支持的模型名网关返回了错误结构Claude Code 解析时就报 reading choices。解决办法是把ANTHROPIC_MODEL改成确认可用的 ID比如claude-sonnet-4-20250514然后重新验证连通性。OAuth / authentication flow failed如果你之前登录过 Claude 官方账号本地可能残留 OAuth 凭证和 API Key 模式冲突。清理方式是删掉~/.claude/下的凭证缓存文件保留 settings.json或者用claude logout退出官方登录再走 API Key 模式。BMad 命令无响应 / 角色不生效这不是接入问题是工作流文件没被加载。检查bmad/agents/下的 yaml 缩进是否正确YAML 对缩进极其敏感多一个空格就解析失败。另外确认你调用时用的命令前缀和 agent id 一致比如 agent id 是analyst命令就得是*analyst。文档生成到一半中断多半是单次输出太长触发了 token 上限。解决办法是在 agent 配置里把大任务拆成多个 task或者让 pm 分章节生成 PRD。我试过让 pm 一次性生成完整 PRD结果在「非功能需求」章节被截断后来改成先出目录再逐章填充就稳了。排查时有个通用思路先分层再定位。接入层问题401、proxy failed、OAuth用claude -p 测试单独验证上下文层问题reading choices、文档中断看模型返回和 token 用量工作流层问题角色不生效看 yaml 解析。三层分开查比一股脑改配置高效得多。6. 把 BMad 工作流固化下来长期编码与 Agent 协作的接入建议跑通一次不难难的是让它变成你日常开发的一部分。我的建议是把 BMad 工作流和 TaoToken 接入都固化进项目模板新项目直接复制不用每次重配。具体做法在项目根目录建.claude/settings.json存 TaoToken 三件套建bmad/存角色和工作流 yaml建docs/存产出文档。新项目初始化时把这三个目录一起复制过去改一下{{project}}变量就能跑。这样团队里每个人拉下代码配好自己的 TaoToken Key就能用同一套工作流产出文档格式统一评审时不会因为「你写的 PRD 没验收标准」扯皮。对于长期编码和 Agent 协作场景如果你发现自己每天都在跑多角色流程、调用量比较大可以了解一下 Coding Plan 这类面向持续编码的接入方案它比按次调用更适合高频 Agent 工作流。日常验证模型是否可用用模型对话页面就够了需要管理多个 Key 或查看调用情况去控制台Key 的生成和轮换在 API Keys 页面。接入文档里有各语言和各工具的详细配置示例遇到不确定的参数先查文档再改配置比盲目试错快。最后给一个实用技巧BMad 的产出文档不要只当过程垃圾把它们纳入 Git 管理。每次需求迭代PRD 和架构文档的 diff 就是最好的变更记录。下次有人问「这个接口为什么这么设计」你直接翻docs/3-技术方案-xxx.md的提交历史比翻聊天记录靠谱得多。文档即上下文也即历史这是 BMad 这套方法最被低估的价值。