Claude Code BMAD技能包：AI驱动开发流程标准化实践指南

1. 项目概述与核心价值

如果你正在使用 Claude Code 进行软件开发，并且对如何将 AI 驱动开发流程化、标准化感到困惑，那么terryso/claude-bmad-skills这个项目绝对值得你花时间深入了解。它不是一个简单的代码片段集合，而是一套为BMAD（Breakthrough Method of Agile AI Driven Development）方法论量身定制的技能包。简单来说，它把一套经过验证的、高效的 AI 辅助开发工作流，封装成了 Claude Code 可以直接调用的“插件”或“技能”，让你能像执行命令一样，自动化地完成从用户故事到代码交付的完整闭环。

我在实际项目中深度使用这套技能包已经有一段时间了，它的核心价值在于“将最佳实践固化”。很多团队在引入 AI 编程助手后，往往会陷入一种混乱：每个开发者使用 AI 的方式、步骤、验收标准都不一致，导致代码质量参差不齐，后期维护成本激增。BMAD Skills 通过预定义的、可配置的管道（Pipeline），强制性地将开发流程标准化。无论是处理一个简单的用户故事（Story），还是一个包含多个故事的史诗（Epic），它都能确保每个环节——需求分析、测试生成、编码、代码审查、测试覆盖追踪——都按照既定的高质量标准执行。这对于追求工程效能和代码质量的团队或个人开发者而言，是一个强有力的提效工具。

2. BMAD 方法论与技能包设计哲学

在深入使用这些技能之前，理解其背后的BMAD 方法论至关重要。这能帮助你明白为什么技能要这样设计，而不仅仅是机械地调用命令。BMAD 并非凭空创造，它是对敏捷开发（Agile）和测试驱动开发（TDD）在 AI 时代的一次深刻演进和整合。

2.1 BMAD 的核心循环：从故事到可交付代码

传统的 TDD 循环是“红-绿-重构”。而在 AI 驱动的 BMAD 中，这个循环被扩展和增强了，其核心思想是“将需求（用户故事）作为唯一输入，通过结构化的 AI 交互，输出经过验证的可交付代码”。一个完整的 BMAD 循环通常包含以下几个关键阶段：

1. 故事澄清与拆分：AI 帮助开发者精确理解用户故事（User Story）的验收标准（Acceptance Criteria），并将其拆分为具体、可测试的任务。这一步确保了开发目标与业务需求对齐，避免了后续的返工。
2. ATDD（验收测试驱动开发）测试生成：在写任何实现代码之前，先由 AI 根据验收标准生成高层级的、可执行的验收测试。这些测试定义了系统的“行为契约”，为后续开发提供了明确的成功标准。
3. AI 辅助开发与实现：在验收测试的指引下，开发者与 AI 协作，编写实现代码。AI 在此过程中扮演结对编程伙伴的角色，快速生成代码草案、解释复杂逻辑、甚至提出优化建议。
4. 自动化代码审查：代码编写完成后，由 AI 进行一轮自动化审查，检查代码风格、潜在缺陷、安全漏洞、性能问题以及是否符合架构规范。这相当于一个随时在线的资深 Reviewer。
5. 测试执行与覆盖度验证：运行所有测试（包括新生成的验收测试和已有的单元测试），确保新代码没有破坏现有功能，并达到预期的测试覆盖度。BMAD 强调“可验证的交付”。

claude-bmad-skills项目正是将上述理论循环，具体落地为可执行的 Claude Code 技能。每个技能都对应一个或多个 BMAD 阶段，并通过管道将它们串联起来，形成自动化工作流。

2.2 技能包的设计考量：隔离性、安全性与可配置性

浏览项目提供的三个核心技能，你会发现它们的设计在几个关键维度上做出了权衡：

• 执行模式：分为子代理（Subagent）和批处理（Batch）。子代理模式为管道中的每个步骤创建一个全新的、隔离的 Claude 会话上下文，确保步骤间不会产生信息干扰或依赖，让 AI 专注于当前任务。批处理模式则用于顺序处理多个独立单元（如一个 Epic 下的所有 Story）。
• 隔离级别：分为无隔离、工作树（Worktree）隔离。这是项目设计中非常精妙的一点。Git Worktree 允许你在同一个仓库中并行创建多个独立的工作目录，每个都有自己独立的分支和文件状态。-worktree后缀的技能会为每次运行创建一个隔离的 Worktree，所有修改都在其中进行，只有全部测试通过且审查无误后，才会合并回主分支。这极大地提升了开发过程的安全性，避免了实验性代码污染主工作区。
• 管道可配置性：技能不是铁板一块。它们通过引用references/workflow-steps.md文件来定义具体的管道步骤。这意味着你可以根据自己团队或项目的实际情况，自定义这个开发流水线。比如，你可以在代码审查后增加一个“生成 API 文档”的步骤，或者调整测试的粒度。

这种设计体现了实用主义的工程思维：为常见场景提供开箱即用的最佳实践（默认管道），同时保留足够的灵活性（可配置管道）和安全性（工作树隔离）来应对复杂需求。

3. 环境准备与技能安装详解

开始使用前，你需要确保基础环境就绪。首先，你当然需要已经安装并配置好Claude Code插件或桌面应用。其次，确保你在一个 Git 仓库的根目录下进行操作，因为所有技能都深度依赖 Git 来管理代码版本和隔离环境。

项目提供了四种安装方式，各有其适用场景。

3.1 安装方式对比与选择建议

提示：对于个人项目或快速尝试，强烈推荐使用Option 1: Claude Code 插件市场。只需在 Claude Code 聊天框中输入安装命令，后续更新和管理都会非常方便。如果命令执行失败，请检查你的 Claude Code 版本是否支持插件市场功能。

3.2 安装后的验证与目录结构

安装成功后，你的本地 Claude Code 技能目录（通常是~/.claude/skills/或项目内的.agents/）下会新增一个bmad-skills的文件夹。了解其目录结构有助于后续的定制和问题排查。

.claude/skills/bmad-skills/ (或 .agents/bmad-skills/) ├── skills/ │ ├── bmad-story-pipeline/ │ │ ├── SKILL.md # 该技能的使用说明 │ │ └── references/ │ │ └── workflow-steps.md # **核心**：可配置的管道步骤定义文件 │ ├── bmad-story-pipeline-worktree/ │ │ ├── SKILL.md │ │ └── references/workflow-steps.md │ └── bmad-epic-pipeline-worktree/ │ └── SKILL.md └── ... (其他项目文件)

关键文件workflow-steps.md是你未来定制化工作流的入口。安装完成后，你可以尝试在 Claude Code 中输入/bmad-story-pipeline并回车，如果看到 Claude 开始回应并准备执行管道，说明安装成功。

4. 核心技能深度解析与实战应用

三个核心技能是这套工具包的灵魂。我们将逐一拆解，并结合实际案例说明如何使用。

4.1 bmad-story-pipeline：单故事标准交付流水线

这是最基础、最常用的技能。它为一个用户故事执行完整的、可配置的 BMAD 交付管道。

基本用法：

# 处理看板或列表中编号为 1-1 的故事 /bmad-story-pipeline 1-1 # 如果不带参数，Claude 会尝试自动识别当前上下文或让你选择要处理的故事 /bmad-story-pipeline

管道默认步骤解析：当你运行命令后，Claude 会作为一个“指挥员”，按照workflow-steps.md的定义，依次启动多个子代理（Subagent）来完成任务。默认管道包含以下5步：

1. Create user story：子代理 A 会分析你提供的故事 ID（如1-1），或与你交互澄清需求，最终输出一份清晰的、包含验收标准的用户故事描述。这一步的目的是对齐认知，确保 AI 和开发者对要构建什么有共同的理解。
2. Generate ATDD tests：子代理 B 接收上一步的故事描述，基于验收标准，生成具体的、可执行的验收测试代码（例如，使用 Jest、Cypress、Pytest 等框架）。这些测试最初会是失败状态（红），因为它们对应的功能尚未实现。这是 BMAD 的关键，测试先行，定义行为。
3. Development：子代理 C 面对失败的验收测试，开始编写实现代码。它会分析测试失败的原因，并逐步编写代码让测试通过（绿）。这个过程可能包含多次迭代，AI 会生成代码、运行测试、并根据错误反馈进行调整。
4. Code review：子代理 D 对子代理 C 生成的代码进行审查。检查项通常包括：代码风格、潜在 bug、性能问题、安全性、是否符合项目架构等。审查结果会以评论或建议修改的形式给出。这一步极大地提升了代码质量，相当于一次自动化的同行评审。
5. Trace test coverage：最后，Claude 会运行测试套件，并生成测试覆盖报告。确保新增的代码不仅有验收测试，单元测试的覆盖度也达到可接受的水平。这为“可交付”提供了数据支撑。

实战心得与技巧：

• 故事编号的映射：你需要一个地方来管理你的用户故事。这可以是一个简单的 Markdown 文件、一个项目看板（如 GitHub Projects, Linear, Jira），或者就在聊天上下文里。运行技能前，确保 Claude 能访问到这些故事描述。例如，你可以先说：“这是我们本迭代的待办列表：1-1: 用户登录功能，1-2: 文章发布功能...”，然后再运行/bmad-story-pipeline 1-1。
• 与现有项目集成：技能会读取你当前 Git 仓库的代码，因此它能理解你的项目结构、已有的测试框架和代码规范。确保你在正确的项目目录下运行命令。
• 中断与恢复：管道执行时间可能较长。如果中途网络中断或你想暂停，Claude 通常会在当前步骤完成后保存上下文。你可以重新发送命令，有时它能从中断处继续，但更可靠的做法是记录下已完成步骤，手动执行后续部分。

4.2 bmad-story-pipeline-worktree：高安全性的隔离交付

这是bmad-story-pipeline的增强版，核心区别在于引入了Git Worktree进行物理隔离。

基本用法：

/bmad-story-pipeline-worktree 1-1

核心机制与优势：

1. 创建隔离沙盒：命令执行后，第一件事是在后台创建一个新的 Git Worktree，对应一个新的分支（如bmad/story-1-1）。所有后续的代码修改、文件创建都发生在这个完全独立的工作目录中，与你主分支（如main）的工作区互不干扰。
2. 执行标准管道：在隔离的 Worktree 中，完整运行与bmad-story-pipeline相同的 5 步流程。
3. 条件合并：这是最关键的安全阀。只有当管道中所有步骤成功完成，并且代码审查没有发现HIGH或MEDIUM级别的严重问题后，技能才会自动将这个隔离分支合并回你的主分支。如果任何一步失败，或者存在未解决的高优先级问题，合并操作会被阻止，隔离分支会被保留以供排查，主分支则保持纯净。

与基础版的对比：

踩坑记录与注意事项：

• Worktree 清理：如果管道运行失败，它会保留隔离的 Worktree 和分支。你需要定期手动清理这些残留的工作树，命令是git worktree prune。在运行新管道前，检查一下是否有旧的bmad/开头分支残留是个好习惯。
• 合并冲突：在隔离开发期间，如果主分支有其他提交，合并时可能产生冲突。技能通常能处理简单的冲突，但复杂的冲突可能需要你手动介入。建议在启动一个耗时较长的管道前，先确保你的主分支是最新的。
• 磁盘空间：每个 Worktree 都是仓库的一份完整拷贝（虽然 Git 有优化，但仍有开销）。如果你同时进行多个故事的隔离开发，请注意磁盘空间。

4.3 bmad-epic-pipeline-worktree：史诗级批量交付

当你需要处理一个包含多个用户故事的“史诗”时，逐个运行故事管道效率低下。bmad-epic-pipeline-worktree就是为了自动化这个批量过程而设计的。

基本用法：

# 处理史诗编号为 3 下的所有未完成故事 /bmad-epic-pipeline-worktree 3

执行逻辑剖析：

1. 故事收集与排序：技能首先会识别史诗 ID（如3），然后从你的项目管理工具或上下文中，找出所有属于该史诗且状态为“未完成”或“待办”的用户故事。接着，它按照故事编号进行升序排序。顺序执行很重要，因为它假设故事间可能存在依赖关系。
2. 顺序隔离执行：对于排序后的故事列表，技能为每一个故事依次调用/bmad-story-pipeline-worktree。注意，是“依次”而非“并行”。它为每个故事创建独立的 Worktree，运行完整的隔离管道。
3. 严格的门禁控制：只有当前一个故事的所有步骤成功完成，代码安全合并回主分支后，下一个故事的管道才会开始。这种设计确保了史诗的交付是增量且稳定的。
4. 失败处理：如果在处理某个故事时管道失败，整个史诗管道会立即停止。之前已经成功合并的故事会保留在主分支中，而失败的故事及其对应的隔离 Worktree 会保持原状，方便你排查问题。这避免了批量操作中“一颗老鼠屎坏了一锅粥”的情况。

适用场景与策略：

• 小型史诗或迭代：非常适合将一个迭代周期（Sprint）内的所有任务进行自动化交付。你只需要在迭代开始时定义好史诗和故事，然后运行一次命令，就能自动推进。
• 功能模块开发：例如，开发一个“支付模块”（史诗），里面包含“创建订单”、“调用支付网关”、“处理回调”等多个故事。使用此技能可以确保每个子功能都经过完整验证后再集成。
• 策略建议：虽然技能支持全自动，但我建议在首次对一个史诗使用前，先手动用bmad-story-pipeline-worktree跑通其中一个故事，确保你的项目环境、测试配置和故事描述格式都能被技能正确识别和处理，避免批量失败。

5. 高级定制：打造属于你自己的 BMAD 流水线

项目最大的亮点之一就是可配置的管道。默认的workflow-steps.md文件只是一个起点，你可以完全根据团队流程定制它。

5.1 解读 workflow-steps.md 结构

让我们看看一个简化版的workflow-steps.md可能长什么样：

# BMAD Pipeline Steps Configuration ## Step 1: Story Elaboration **Agent Role**: Product Analyst **Objective**: Clarify the user story and define clear acceptance criteria. **Instructions**: | - Read the story ID: {{story_id}} - Find the story description from the project context. - If details are vague, ask the user for clarification. - Output a finalized story description with a bulleted list of acceptance criteria. **Output To**: `story_specification` ## Step 2: ATDD Test Generation **Agent Role**: Test Engineer **Objective**: Create executable acceptance tests based on the criteria. **Input From**: `story_specification` **Instructions**: | - Analyze the acceptance criteria from the previous step. - Based on the project's tech stack (e.g., Jest for React, Pytest for Python), generate failing acceptance test code. - Place the test file in the appropriate directory following project convention. **Output To**: `generated_tests`

（为简洁起见，只展示前两步）

这个配置文件定义了一个步骤列表。每个步骤包含：

• 步骤名称与角色：定义了这一步做什么，以及执行 AI 子代理扮演的角色（这会影响其思考方式）。
• 目标：该步骤要达成的具体成果。
• 输入/输出：步骤间通过命名的上下文变量（如story_specification）传递信息。
• 指令：给 AI 子代理的具体、可操作的命令。这是定制的核心，你可以在这里写入任何符合你团队规范的详细要求。

5.2 定制化管道示例

假设你的团队流程在代码审查后，还需要自动生成 API 文档（假设是 Swagger/OpenAPI），并且要在合并前执行一次安全扫描。你可以这样修改workflow-steps.md，在默认步骤中插入两步：

1. 在 “Code review” 步骤后，添加 “Generate API Documentation” 步骤：

   ## Step 5: Generate API Documentation **Agent Role**: Technical Writer **Objective**: Automatically generate or update OpenAPI/Swagger documentation for any new or modified API endpoints. **Input From**: `developed_code` (假设上一步开发输出的上下文变量) **Instructions**: | - Scan the changed code files, focusing on controller/router files and API endpoint definitions. - If using decorators (e.g., SpringFox, Swagger UI for Spring), ensure they are correctly applied. - If using a separate OpenAPI spec file (openapi.yaml), update the relevant paths, schemas, and parameters. - Output a summary of documentation updates made. **Output To**: `api_docs_update`

2. 在 “Trace test coverage” 步骤前，添加 “Security Scan” 步骤：

   ## Step 6: Security Scan **Agent Role**: Security Specialist **Objective**: Perform a static application security testing (SAST) on the changed code. **Input From**: `developed_code` **Instructions**: | - Analyze the modified code for common security vulnerabilities (e.g., SQL injection, XSS, insecure deserialization, hardcoded secrets). - Use the context of the project's programming language and frameworks to identify relevant risks. - Provide a report listing any potential security issues found, categorized by severity (HIGH, MEDIUM, LOW). - For HIGH severity issues, suggest concrete code fixes. **Output To**: `security_scan_report`

   然后，你需要修改原 “Trace test coverage” 步骤的Input From，使其也能考虑安全扫描报告。

通过这样的定制，你的 BMAD 管道就升级为包含了安全左移和文档自动化的增强型工作流。这充分体现了将团队流程固化到工具中所带来的巨大价值。

6. 常见问题排查与实战经验实录

即使工具设计得再完善，在实际使用中总会遇到各种情况。以下是我在长期使用中总结的一些典型问题及解决方法。

6.1 技能执行失败或命令未找到

• 问题：输入/bmad-story-pipeline后，Claude 没有反应，或提示“未知命令”。
• 排查步骤：
  1. 确认安装：首先检查技能是否安装成功。可以到 Claude Code 的技能管理界面查看，或者在技能安装目录下确认文件是否存在。
  2. 检查路径：如果你使用“克隆并复制”方式安装，确保复制到了正确的 Claude Code 技能目录。这个目录路径可能因安装方式（VS Code 插件、桌面版）而异，需要查阅对应文档。
  3. 重启 Claude Code：有时安装新技能后需要重启 Claude Code 应用或插件以重新加载技能列表。
  4. 权限问题：确保技能文件具有可执行权限（主要在 Linux/macOS 系统下需要注意）。

6.2 管道步骤卡住或 AI 输出不符合预期

• 问题：管道在某个步骤（如“生成测试”）长时间无响应，或 AI 生成的代码/测试与项目技术栈不符。
• 排查与解决：
  1. 检查上下文：BMAD 技能严重依赖聊天上下文。确保在运行管道前，你已经通过对话或文件上传，让 Claude 了解了你的项目结构、技术栈（如package.json,pom.xml）、代码规范等。最好将项目的主要配置文件（如package.json,jest.config.js）在对话中上传一次。
  2. 审查workflow-steps.md指令：AI 是严格按指令行事的。如果指令模糊，输出就可能偏离预期。将指令写得尽可能具体。例如，不要只说“生成测试”，而要说“在src/test/java/目录下，使用 JUnit 5 和 Mockito，为UserService类的login方法生成单元测试”。
  3. 分步调试：如果整个管道失败，可以尝试手动模拟管道步骤。即，自己扮演“指挥员”，依次给 Claude 发送类似每一步指令的提示，观察它在哪一步出现问题，从而定位是技能配置问题还是项目环境问题。
  4. 网络与超时：复杂的代码生成或测试运行可能耗时较长，确保网络稳定。某些在线 API 调用可能会有超时限制。

6.3 Git 相关错误（特别是 Worktree 模式）

• 问题：-worktree技能报错，如 “fatal: ‘xxx’ is already a working tree” 或合并时冲突。
• 排查与解决：
  1. 清理残留 Worktree：这是最常见的问题。运行git worktree list查看所有工作树，然后使用git worktree remove <path>或git worktree prune清理那些已经不再需要的、尤其是之前失败管道留下的工作树。
  2. 主分支状态：在启动一个需要运行较长时间的管道前，先执行git fetch && git pull确保主分支是最新的，可以减少合并冲突的概率。
  3. 手动处理冲突：如果技能提示合并冲突，它通常会停止并保留现场。你需要手动进入那个隔离的 Worktree 目录，使用git status查看冲突文件，解决冲突后，手动执行git add .和git commit，最后再尝试手动合并到主分支。
  4. Git 版本：确保你使用的 Git 版本支持 Worktree 功能的所有特性（一般 Git 2.5+ 即可）。

6.4 如何与现有项目管理工具集成

• 问题：我的故事在 Jira/Linear/Asana 上，如何让技能自动读取？
• 现状与建议：目前claude-bmad-skills项目本身不直接与第三方项目管理工具集成。它依赖于你在 Claude 的聊天上下文中提供故事信息。
• 变通方案：
  • 手动复制：最直接的方式，将故事标题和描述从管理工具复制到聊天框。
  • 使用浏览器插件：有些 Claude 的浏览器插件支持读取当前页面内容。你可以打开 Jira 故事页面，然后让 Claude 插件“读取此页面”，再运行技能。
  • 自定义技能扩展：对于高级用户，可以修改技能源码，在第一步“故事澄清”中，增加调用项目管理工具 API 的逻辑（这需要一定的开发能力）。这也是项目开源的意义所在，社区可以共同完善这类集成。

6.5 性能优化与最佳实践

1. 管道步骤精简：不是所有项目都需要完整的 5 步。对于非常小的修改，你可以定制一个简化的workflow-steps.md，只包含“开发”和“运行测试”两步，以提升速度。
2. 利用缓存：Claude Code 本身有上下文缓存。确保你的项目关键文件（配置文件、核心模块代码）在对话早期就被引入上下文，这样在管道执行时，AI 就不需要反复“回忆”或“读取”它们，能提高生成准确性和速度。
3. 分而治之：对于特别复杂的用户故事，不要指望一次管道就能完美解决。可以手动将大故事拆分成多个逻辑上独立的小任务，然后为每个小任务运行管道。最后再手动进行集成。BMAD 是工具，而不是束缚思维的牢笼。
4. 定期回顾与更新：随着项目技术栈演进和团队规范变化，定期回顾和更新你的workflow-steps.md文件。让管道定义始终反映你们当前的最佳实践。

这套技能的本质，是将开发者从重复性的、机械的流程操作中解放出来，让我们能更专注于创造性的问题解决和架构设计。它初期可能需要一些学习和调优成本，但一旦流程跑顺，其对开发节奏和代码质量的提升是显而易见的。