diff --git a/README_CN.md b/README_CN.md new file mode 100644 index 000000000..85b42cb2f --- /dev/null +++ b/README_CN.md @@ -0,0 +1,121 @@ +![BMad Method](banner-bmad-method.png) + +[![Version](https://img.shields.io/npm/v/bmad-method?color=blue&label=version)](https://www.npmjs.com/package/bmad-method) +[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE) +[![Node.js Version](https://img.shields.io/badge/node-%3E%3D20.0.0-brightgreen)](https://nodejs.org) +[![Discord](https://img.shields.io/badge/Discord-Join%20Community-7289da?logo=discord&logoColor=white)](https://discord.gg/gk8jAdXWmj) + +**突破性敏捷 AI 驱动开发方法** — 简称 “BMAD 方法论” ，BMAD方法论是由多个模块生态构成的AI驱动敏捷开发模块系统，这是最佳且最全面的敏捷 AI 驱动开发框架，具备真正的规模自适应人工智能，可适应快速开发，适应企业规模化开发。 + +**100% 免费且开源。** 无付费。无内容门槛。无封闭 Discord。我们赋能每个人，我们将为全球现在在人工智能领域发展的普通人提供公平的学习机会。 + +## 为什么选择 BMad 方法？ + +传统 AI 工具替你思考，产生平庸的结果。BMad 智能体和辅助工作流充当专家协作者，引导你通过结构化流程，与 AI 的合作发挥最佳思维，产出最有效优秀的结果。 + +- **AI 智能帮助** — 随时使用 `/bmad-help` 获取下一步指导 +- **规模-领域自适应** — 根据项目复杂度自动调整规划深度 +- **结构化工作流** — 基于分析、规划、架构和实施的敏捷最佳实践 +- **专业智能体** — 12+ 领域专家（PM、架构师、开发者、UX、Scrum Master 等） +- **派对模式** — 将多个智能体角色带入一个会话进行协作和讨论 +- **完整生命周期** — 从想法开始（头脑风暴）到部署发布 + +[在 **docs.bmad-method.org** 了解更多](http://docs.bmad-method.org) + +--- + +## 🚀 BMad 的下一步是什么？ + +**V6 已到来，我们才刚刚开始！** BMad 方法正在快速发展，包括跨平台智能体团队和子智能体集成、技能架构、BMad Builder v1、开发循环自动化等优化，以及更多正在开发中的功能。 + +**[📍 查看完整路线图 →](http://docs.bmad-method.org/roadmap/)** + +--- + +## 快速开始 + +**先决条件**：[Node.js](https://nodejs.org) v20+ + +```bash +npx bmad-method install +``` + +> 如果你获得的是过时的测试版，请使用：`npx bmad-method@6.0.1 install` + +按照安装程序提示操作，然后在项目文件夹中打开你的 AI IDE（Claude Code、Cursor 等）。 + +**非交互式安装**（用于 CI/CD）： + +```bash +npx bmad-method install --directory /path/to/project --modules bmm --tools claude-code --yes +``` + +[查看所有安装选项](http://docs.bmad-method.org/how-to/non-interactive-installation/) + +> **不确定该做什么？** 运行 `/bmad-help` — 它会准确告诉你下一步做什么以及什么是可选的。你也可以问诸如 `/bmad-help 我刚刚完成了架构设计，接下来该做什么？` 之类的问题。 + +## 模块 + +BMad 方法通过官方模块扩展到专业领域。可在安装期间或之后的任何时间使用。 + +| Module | Purpose | +| ----------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- | +| **[BMad Method (BMM)](https://github.com/bmad-code-org/BMAD-METHOD)** | 包含 34+ 工作流的核心框架 | +| **[BMad Builder (BMB)](https://github.com/bmad-code-org/bmad-builder)** | 创建自定义 BMad 智能体和工作流 | +| **[Test Architect (TEA)](https://github.com/bmad-code-org/tea)** | 基于风险的测试策略和自动化 | +| **[Game Dev Studio (BMGD)](https://github.com/bmad-code-org/bmad-module-game-dev-studio)** | 游戏开发工作流（Unity、Unreal、Godot） | +| **[Creative Intelligence Suite (CIS)](https://github.com/bmad-code-org/bmad-module-creative-intelligence-suite)** | 创新、头脑风暴、设计思维 | + +## 文档 + +[BMad 方法文档站点](http://docs.bmad-method.org) — 教程、指南、概念和参考 + +**快速链接：** +- [入门教程](http://docs.bmad-method.org/tutorials/getting-started/) +- [从先前版本升级](http://docs.bmad-method.org/how-to/upgrade-to-v6/) +- [测试架构师文档](https://bmad-code-org.github.io/bmad-method-test-architecture-enterprise/) + + +## 社区 + +- [Discord](https://discord.gg/gk8jAdXWmj) — 获取帮助、分享想法、协作 +- [在 YouTube 上订阅](https://www.youtube.com/@BMadCode) — 教程、大师课和播客（2025 年 2 月推出） +- [GitHub Issues](https://github.com/bmad-code-org/BMAD-METHOD/issues) — 错误报告和功能请求 +- [讨论](https://github.com/bmad-code-org/BMAD-METHOD/discussions) — 社区对话 + +## 支持 BMad + +BMad 对每个人都是免费的 — 并且永远如此。如果你想支持开发： + +- ⭐ 请点击此页面右上角附近的项目星标图标 +- ☕ [请我喝咖啡](https://buymeacoffee.com/bmad) — 为开发提供动力 +- 🏢 企业赞助 — 在 Discord 上私信 +- 🎤 演讲与媒体 — 可参加会议、播客、采访（在 Discord 上联系 BM） + +## 贡献 + +我们欢迎贡献！请参阅 [CONTRIBUTING.md](CONTRIBUTING.md) 了解指南。 + +## 许可证 + +MIT 许可证 — 详见 [LICENSE](LICENSE)。 + +--- + +**BMad** 和 **BMAD-METHOD** 是 BMad Code, LLC 的商标。详见 [TRADEMARK.md](TRADEMARK.md)。 + +[![Contributors](https://contrib.rocks/image?repo=bmad-code-org/BMAD-METHOD)](https://github.com/bmad-code-org/BMAD-METHOD/graphs/contributors) + +请参阅 [CONTRIBUTORS.md](CONTRIBUTORS.md) 了解贡献者信息。 + +--- +## 术语说明 + +- **agent**：智能体。在人工智能与编程文档中，指具备自主决策或执行能力的单元。 +- **workflow**：工作流。指一系列有序的任务或步骤，用于完成特定目标。 +- **CI/CD**：持续集成/持续部署。一种自动化软件开发实践，用于频繁集成代码更改并自动部署。 +- **IDE**：集成开发环境。提供代码编辑、调试、构建等功能的软件开发工具。 +- **PM**：产品经理。负责产品规划、需求管理和团队协调的角色。 +- **UX**：用户体验。指用户在使用产品或服务过程中的整体感受和交互体验。 +- **Scrum Master**：Scrum 主管。敏捷开发 Scrum 框架中的角色，负责促进团队遵循 Scrum 流程。 +- **PRD**：产品需求文档。详细描述产品功能、需求和规格的文档。 diff --git a/docs_cn/404_cn.md b/docs_cn/404_cn.md new file mode 100644 index 000000000..a417d2e00 --- /dev/null +++ b/docs_cn/404_cn.md @@ -0,0 +1,9 @@ +--- +title: 页面未找到 +template: splash +--- + + +您查找的页面不存在或已被移动。 + +[返回首页](./index_cn.md) diff --git a/docs_cn/_STYLE_GUIDE.md b/docs_cn/_STYLE_GUIDE.md new file mode 100644 index 000000000..c6e9eff58 --- /dev/null +++ b/docs_cn/_STYLE_GUIDE.md @@ -0,0 +1,370 @@ +--- +title: "Documentation Style Guide" +description: Project-specific documentation conventions based on Google style and Diataxis structure +--- + +This project adheres to the [Google Developer Documentation Style Guide](https://developers.google.com/style) and uses [Diataxis](https://diataxis.fr/) to structure content. Only project-specific conventions follow. + +## Project-Specific Rules + +| Rule | Specification | +| -------------------------------- | ---------------------------------------- | +| No horizontal rules (`---`) | Fragments reading flow | +| No `####` headers | Use bold text or admonitions instead | +| No "Related" or "Next:" sections | Sidebar handles navigation | +| No deeply nested lists | Break into sections instead | +| No code blocks for non-code | Use admonitions for dialogue examples | +| No bold paragraphs for callouts | Use admonitions instead | +| 1-2 admonitions per section max | Tutorials allow 3-4 per major section | +| Table cells / list items | 1-2 sentences max | +| Header budget | 8-12 `##` per doc; 2-3 `###` per section | + +## Admonitions (Starlight Syntax) + +```md +:::tip[Title] +Shortcuts, best practices +::: + +:::note[Title] +Context, definitions, examples, prerequisites +::: + +:::caution[Title] +Caveats, potential issues +::: + +:::danger[Title] +Critical warnings only — data loss, security issues +::: +``` + +### Standard Uses + +| Admonition | Use For | +| ------------------------ | ----------------------------- | +| `:::note[Prerequisites]` | Dependencies before starting | +| `:::tip[Quick Path]` | TL;DR summary at document top | +| `:::caution[Important]` | Critical caveats | +| `:::note[Example]` | Command/response examples | + +## Standard Table Formats + +**Phases:** + +```md +| Phase | Name | What Happens | +| ----- | -------- | -------------------------------------------- | +| 1 | Analysis | Brainstorm, research *(optional)* | +| 2 | Planning | Requirements — PRD or tech-spec *(required)* | +``` + +**Commands:** + +```md +| Command | Agent | Purpose | +| ------------ | ------- | ------------------------------------ | +| `brainstorm` | Analyst | Brainstorm a new project | +| `prd` | PM | Create Product Requirements Document | +``` + +## Folder Structure Blocks + +Show in "What You've Accomplished" sections: + +````md +``` +your-project/ +├── _bmad/ # BMad configuration +├── _bmad-output/ +│ ├── planning-artifacts/ +│ │ └── PRD.md # Your requirements document +│ ├── implementation-artifacts/ +│ └── project-context.md # Implementation rules (optional) +└── ... +``` +```` + +## Tutorial Structure + +```text +1. Title + Hook (1-2 sentences describing outcome) +2. Version/Module Notice (info or warning admonition) (optional) +3. What You'll Learn (bullet list of outcomes) +4. Prerequisites (info admonition) +5. Quick Path (tip admonition - TL;DR summary) +6. Understanding [Topic] (context before steps - tables for phases/agents) +7. Installation (optional) +8. Step 1: [First Major Task] +9. Step 2: [Second Major Task] +10. Step 3: [Third Major Task] +11. What You've Accomplished (summary + folder structure) +12. Quick Reference (commands table) +13. Common Questions (FAQ format) +14. Getting Help (community links) +15. Key Takeaways (tip admonition) +``` + +### Tutorial Checklist + +- [ ] Hook describes outcome in 1-2 sentences +- [ ] "What You'll Learn" section present +- [ ] Prerequisites in admonition +- [ ] Quick Path TL;DR admonition at top +- [ ] Tables for phases, commands, agents +- [ ] "What You've Accomplished" section present +- [ ] Quick Reference table present +- [ ] Common Questions section present +- [ ] Getting Help section present +- [ ] Key Takeaways admonition at end + +## How-To Structure + +```text +1. Title + Hook (one sentence: "Use the `X` workflow to...") +2. When to Use This (bullet list of scenarios) +3. When to Skip This (optional) +4. Prerequisites (note admonition) +5. Steps (numbered ### subsections) +6. What You Get (output/artifacts produced) +7. Example (optional) +8. Tips (optional) +9. Next Steps (optional) +``` + +### How-To Checklist + +- [ ] Hook starts with "Use the `X` workflow to..." +- [ ] "When to Use This" has 3-5 bullet points +- [ ] Prerequisites listed +- [ ] Steps are numbered `###` subsections with action verbs +- [ ] "What You Get" describes output artifacts + +## Explanation Structure + +### Types + +| Type | Example | +| ----------------- | ----------------------------- | +| **Index/Landing** | `core-concepts/index.md` | +| **Concept** | `what-are-agents.md` | +| **Feature** | `quick-flow.md` | +| **Philosophy** | `why-solutioning-matters.md` | +| **FAQ** | `established-projects-faq.md` | + +### General Template + +```text +1. Title + Hook (1-2 sentences) +2. Overview/Definition (what it is, why it matters) +3. Key Concepts (### subsections) +4. Comparison Table (optional) +5. When to Use / When Not to Use (optional) +6. Diagram (optional - mermaid, 1 per doc max) +7. Next Steps (optional) +``` + +### Index/Landing Pages + +```text +1. Title + Hook (one sentence) +2. Content Table (links with descriptions) +3. Getting Started (numbered list) +4. Choose Your Path (optional - decision tree) +``` + +### Concept Explainers + +```text +1. Title + Hook (what it is) +2. Types/Categories (### subsections) (optional) +3. Key Differences Table +4. Components/Parts +5. Which Should You Use? +6. Creating/Customizing (pointer to how-to guides) +``` + +### Feature Explainers + +```text +1. Title + Hook (what it does) +2. Quick Facts (optional - "Perfect for:", "Time to:") +3. When to Use / When Not to Use +4. How It Works (mermaid diagram optional) +5. Key Benefits +6. Comparison Table (optional) +7. When to Graduate/Upgrade (optional) +``` + +### Philosophy/Rationale Documents + +```text +1. Title + Hook (the principle) +2. The Problem +3. The Solution +4. Key Principles (### subsections) +5. Benefits +6. When This Applies +``` + +### Explanation Checklist + +- [ ] Hook states what document explains +- [ ] Content in scannable `##` sections +- [ ] Comparison tables for 3+ options +- [ ] Diagrams have clear labels +- [ ] Links to how-to guides for procedural questions +- [ ] 2-3 admonitions max per document + +## Reference Structure + +### Types + +| Type | Example | +| ----------------- | --------------------- | +| **Index/Landing** | `workflows/index.md` | +| **Catalog** | `agents/index.md` | +| **Deep-Dive** | `document-project.md` | +| **Configuration** | `core-tasks.md` | +| **Glossary** | `glossary/index.md` | +| **Comprehensive** | `bmgd-workflows.md` | + +### Reference Index Pages + +```text +1. Title + Hook (one sentence) +2. Content Sections (## for each category) + - Bullet list with links and descriptions +``` + +### Catalog Reference + +```text +1. Title + Hook +2. Items (## for each item) + - Brief description (one sentence) + - **Commands:** or **Key Info:** as flat list +3. Universal/Shared (## section) (optional) +``` + +### Item Deep-Dive Reference + +```text +1. Title + Hook (one sentence purpose) +2. Quick Facts (optional note admonition) + - Module, Command, Input, Output as list +3. Purpose/Overview (## section) +4. How to Invoke (code block) +5. Key Sections (## for each aspect) + - Use ### for sub-options +6. Notes/Caveats (tip or caution admonition) +``` + +### Configuration Reference + +```text +1. Title + Hook +2. Table of Contents (jump links if 4+ items) +3. Items (## for each config/task) + - **Bold summary** — one sentence + - **Use it when:** bullet list + - **How it works:** numbered steps (3-5 max) + - **Output:** expected result (optional) +``` + +### Comprehensive Reference Guide + +```text +1. Title + Hook +2. Overview (## section) + - Diagram or table showing organization +3. Major Sections (## for each phase/category) + - Items (### for each item) + - Standardized fields: Command, Agent, Input, Output, Description +4. Next Steps (optional) +``` + +### Reference Checklist + +- [ ] Hook states what document references +- [ ] Structure matches reference type +- [ ] Items use consistent structure throughout +- [ ] Tables for structured/comparative data +- [ ] Links to explanation docs for conceptual depth +- [ ] 1-2 admonitions max + +## Glossary Structure + +Starlight generates right-side "On this page" navigation from headers: + +- Categories as `##` headers — appear in right nav +- Terms in tables — compact rows, not individual headers +- No inline TOC — right sidebar handles navigation + +### Table Format + +```md +## Category Name + +| Term | Definition | +| ------------ | ---------------------------------------------------------------------------------------- | +| **Agent** | Specialized AI persona with specific expertise that guides users through workflows. | +| **Workflow** | Multi-step guided process that orchestrates AI agent activities to produce deliverables. | +``` + +### Definition Rules + +| Do | Don't | +| ----------------------------- | ------------------------------------------- | +| Start with what it IS or DOES | Start with "This is..." or "A [term] is..." | +| Keep to 1-2 sentences | Write multi-paragraph explanations | +| Bold term name in cell | Use plain text for terms | + +### Context Markers + +Add italic context at definition start for limited-scope terms: + +- `*Quick Flow only.*` +- `*BMad Method/Enterprise.*` +- `*Phase N.*` +- `*BMGD.*` +- `*Established projects.*` + +### Glossary Checklist + +- [ ] Terms in tables, not individual headers +- [ ] Terms alphabetized within categories +- [ ] Definitions 1-2 sentences +- [ ] Context markers italicized +- [ ] Term names bolded in cells +- [ ] No "A [term] is..." definitions + +## FAQ Sections + +```md +## Questions + +- [Do I always need architecture?](#do-i-always-need-architecture) +- [Can I change my plan later?](#can-i-change-my-plan-later) + +### Do I always need architecture? + +Only for BMad Method and Enterprise tracks. Quick Flow skips to implementation. + +### Can I change my plan later? + +Yes. The SM agent has a `correct-course` workflow for handling scope changes. + +**Have a question not answered here?** [Open an issue](...) or ask in [Discord](...). +``` + +## Validation Commands + +Before submitting documentation changes: + +```bash +npm run docs:fix-links # Preview link format fixes +npm run docs:fix-links -- --write # Apply fixes +npm run docs:validate-links # Check links exist +npm run docs:build # Verify no build errors +``` diff --git a/docs_cn/explanation/advanced-elicitation_cn.md b/docs_cn/explanation/advanced-elicitation_cn.md new file mode 100644 index 000000000..7ecbdf0e5 --- /dev/null +++ b/docs_cn/explanation/advanced-elicitation_cn.md @@ -0,0 +1,62 @@ +--- +title: "高级启发" +description: 使用结构化推理方法推动 LLM 重新思考其工作 +sidebar: + order: 6 +--- + +让 LLM 重新审视它刚刚生成的内容。你选择一种推理方法，它将该方法应用于自己的输出，然后你决定是否保留改进。 + +## 什么是高级启发？ + +结构化的第二轮处理。与其要求 AI "再试一次" 或 "做得更好"，不如选择一种特定的推理方法，让 AI 通过该视角重新审视自己的输出。 + +这种区别很重要。模糊的请求会产生模糊的修订。命名的方法会强制采用特定的攻击角度，揭示出通用重试会遗漏的见解。 + +## 何时使用 + +- 在工作流生成内容后，你想要替代方案 +- 当输出看起来还可以，但你怀疑还有更深层次的内容 +- 对假设进行压力测试或发现弱点 +- 对于重新思考有帮助的高风险内容 + +工作流在决策点提供高级启发——在 LLM 生成某些内容后，系统会询问你是否要运行它。 + +## 工作原理 + +1. LLM 为你的内容建议 5 种相关方法 +2. 你选择一种（或重新洗牌以获取不同选项） +3. 应用方法，显示改进 +4. 接受或丢弃，重复或继续 + +## 内置方法 + +有数十种推理方法可用。几个示例： + +- **事前复盘** - 假设项目已经失败，反向推导找出原因 +- **第一性原理思维** - 剥离假设，从基本事实重建 +- **逆向思维** - 询问如何保证失败，然后避免这些事情 +- **红队对蓝队** - 攻击你自己的工作，然后为它辩护 +- **苏格拉底式提问** - 用"为什么？"和"你怎么知道？"挑战每个主张 +- **约束移除** - 放下所有约束，看看有什么变化，然后有选择地加回 +- **利益相关者映射** - 从每个利益相关者的角度重新评估 +- **类比推理** - 在其他领域找到平行案例并应用其教训 + +还有更多。AI 会为你的内容选择最相关的选项——你选择运行哪一个。 + +:::tip[从这里开始] +对于任何规范或计划，事前复盘都是一个很好的首选。它始终能找到标准审查会遗漏的空白。 +::: + +--- +## 术语说明 + +- **LLM**：大语言模型。一种基于深度学习的自然语言处理模型，能够理解和生成人类语言。 +- **elicitation**：启发。在人工智能与提示工程中，指通过特定方法引导模型生成更高质量或更符合预期的输出。 +- **pre-mortem analysis**：事前复盘。一种风险管理技术，假设项目已经失败，然后反向推导可能的原因，以提前识别和预防潜在问题。 +- **first principles thinking**：第一性原理思维。一种将复杂问题分解为最基本事实或假设，然后从这些基本要素重新构建解决方案的思维方式。 +- **inversion**：逆向思维。通过思考如何导致失败来避免失败，从而找到成功路径的思维方式。 +- **red team vs blue team**：红队对蓝队。一种模拟对抗的方法，红队负责攻击和发现问题，蓝队负责防御和解决问题。 +- **socratic questioning**：苏格拉底式提问。一种通过连续提问来揭示假设、澄清概念和深入思考的对话方法。 +- **stakeholder mapping**：利益相关者映射。识别并分析项目中所有利益相关者及其利益、影响和关系的系统性方法。 +- **analogical reasoning**：类比推理。通过将当前问题与已知相似领域的问题进行比较，从而借鉴解决方案或见解的推理方式。 diff --git a/docs_cn/explanation/adversarial-review_cn.md b/docs_cn/explanation/adversarial-review_cn.md new file mode 100644 index 000000000..c969c1e53 --- /dev/null +++ b/docs_cn/explanation/adversarial-review_cn.md @@ -0,0 +1,71 @@ +--- +title: "对抗性评审" +description: 防止懒惰"看起来不错"评审的强制推理技术 +sidebar: + order: 5 +--- + +通过要求发现问题来强制进行更深入的分析。 + +## 什么是对抗性评审？ + +一种评审技术，评审者*必须*发现问题。不允许"看起来不错"。评审者采取怀疑态度——假设问题存在并找到它们。 + +这不是为了消极。而是为了强制进行真正的分析，而不是对提交的内容进行草率浏览并盖章批准。 + +**核心规则：**你必须发现问题。零发现会触发停止——重新分析或解释原因。 + +## 为什么有效 + +普通评审容易受到确认偏差的影响。你浏览工作，没有发现突出的问题，就批准了它。"发现问题"的指令打破了这种模式： + +- **强制彻底性**——在你足够努力地查看以发现问题之前，不能批准 +- **捕捉遗漏**——"这里缺少什么？"成为一个自然的问题 +- **提高信号质量**——发现是具体且可操作的，而不是模糊的担忧 +- **信息不对称**——在新的上下文中运行评审（无法访问原始推理），以便你评估的是工件，而不是意图 + +## 在哪里使用 + +对抗性评审出现在 BMad 工作流程的各个地方——代码评审、实施就绪检查、规范验证等。有时它是必需步骤，有时是可选的（如高级启发或派对模式）。该模式适应任何需要审查的工件。 + +## 需要人工过滤 + +因为 AI 被*指示*要发现问题，它就会发现问题——即使问题不存在。预期会有误报：伪装成问题的吹毛求疵、对意图的误解，或完全幻觉化的担忧。 + +**你决定什么是真实的。**审查每个发现，忽略噪音，修复重要的内容。 + +## 示例 + +而不是： + +> "身份验证实现看起来合理。已批准。" + +对抗性评审产生： + +> 1. **高** - `login.ts:47` - 失败尝试没有速率限制 +> 2. **高** - 会话令牌存储在 localStorage 中（易受 XSS 攻击） +> 3. **中** - 密码验证仅在客户端进行 +> 4. **中** - 失败登录尝试没有审计日志 +> 5. **低** - 魔法数字 `3600` 应该是 `SESSION_TIMEOUT_SECONDS` + +第一个评审可能会遗漏安全漏洞。第二个发现了四个。 + +## 迭代和收益递减 + +在处理发现后，考虑再次运行。第二轮通常会捕获更多。第三轮也不总是无用的。但每一轮都需要时间，最终你会遇到收益递减——只是吹毛求疵和虚假发现。 + +:::tip[更好的评审] +假设问题存在。寻找缺失的内容，而不仅仅是错误的内容。 +::: + +--- +## 术语说明 + +- **adversarial review**：对抗性评审。一种强制评审者必须发现问题的评审技术，旨在防止草率批准。 +- **confirmation bias**：确认偏差。倾向于寻找、解释和记忆符合自己已有信念的信息的心理倾向。 +- **information asymmetry**：信息不对称。交易或评审中一方拥有比另一方更多或更好信息的情况。 +- **false positives**：误报。错误地将不存在的问题识别为存在的问题。 +- **diminishing returns**：收益递减。在投入持续增加的情况下，产出增长逐渐减少的现象。 +- **XSS**：跨站脚本攻击（Cross-Site Scripting）。一种安全漏洞，攻击者可在网页中注入恶意脚本。 +- **localStorage**：本地存储。浏览器提供的 Web Storage API，用于在客户端存储键值对数据。 +- **magic number**：魔法数字。代码中直接出现的未命名数值常量，缺乏语义含义。 diff --git a/docs_cn/explanation/brainstorming_cn.md b/docs_cn/explanation/brainstorming_cn.md new file mode 100644 index 000000000..a7479e88f --- /dev/null +++ b/docs_cn/explanation/brainstorming_cn.md @@ -0,0 +1,43 @@ +--- +title: "头脑风暴" +description: 使用 60+ 种经过验证的构思技术进行互动创意会议 +sidebar: + order: 2 +--- + +通过引导式探索释放你的创造力。 + +## 什么是头脑风暴？ + +运行 `brainstorming`，你就拥有了一位创意引导者，帮助你从自身挖掘想法——而不是替你生成想法。AI 充当教练和向导，使用经过验证的技术，创造让你最佳思维涌现的条件。 + +**适用于：** + +- 突破创意瓶颈 +- 生成产品或功能想法 +- 从新角度探索问题 +- 将原始概念发展为行动计划 + +## 工作原理 + +1. **设置** - 定义主题、目标、约束 +2. **选择方法** - 自己选择技术、获取 AI 推荐、随机选择或遵循渐进式流程 +3. **引导** - 通过探索性问题和协作式教练引导完成技术 +4. **组织** - 将想法按主题分组并确定优先级 +5. **行动** - 为顶级想法制定下一步和成功指标 + +所有内容都会被记录在会议文档中，你可以稍后参考或与利益相关者分享。 + +:::note[你的想法] +每个想法都来自你。工作流程创造洞察的条件——你是源头。 +::: + +--- +## 术语说明 + +- **brainstorming**：头脑风暴。一种集体或个人的创意生成方法，通过自由联想和发散思维产生大量想法。 +- **ideation**：构思。产生想法、概念或解决方案的过程。 +- **facilitator**：引导者。在会议或工作坊中引导讨论、促进参与并帮助达成目标的人。 +- **creative blocks**：创意瓶颈。在创意过程中遇到的思维停滞或灵感枯竭状态。 +- **probing questions**：探索性问题。旨在深入挖掘信息、激发思考或揭示潜在见解的问题。 +- **stakeholders**：利益相关者。对项目或决策有利益关系或受其影响的个人或群体。 diff --git a/docs_cn/explanation/established-projects-faq_cn.md b/docs_cn/explanation/established-projects-faq_cn.md new file mode 100644 index 000000000..8756faa20 --- /dev/null +++ b/docs_cn/explanation/established-projects-faq_cn.md @@ -0,0 +1,60 @@ +--- +title: "既有项目常见问题" +description: 关于在既有项目上使用 BMad 方法的常见问题 +sidebar: + order: 8 +--- +关于使用 BMad 方法（BMM）在既有项目上工作的常见问题的快速解答。 + +## 问题 + +- [我必须先运行 document-project 吗？](#do-i-have-to-run-document-project-first) +- [如果我忘记运行 document-project 怎么办？](#what-if-i-forget-to-run-document-project) +- [我可以在既有项目上使用快速流程吗？](#can-i-use-quick-flow-for-established-projects) +- [如果我的现有代码不遵循最佳实践怎么办？](#what-if-my-existing-code-doesnt-follow-best-practices) + +### 我必须先运行 document-project 吗？ + +强烈推荐，特别是如果： + +- 没有现有文档 +- 文档已过时 +- AI 智能体需要关于现有代码的上下文 + +如果你拥有全面且最新的文档，包括 `docs/index.md`，或者将使用其他工具或技术来帮助智能体发现现有系统，则可以跳过此步骤。 + +### 如果我忘记运行 document-project 怎么办？ + +不用担心——你可以随时执行。你甚至可以在项目期间或项目之后执行，以帮助保持文档最新。 + +### 我可以在既有项目上使用快速流程吗？ + +可以！快速流程在既有项目上效果很好。它将： + +- 自动检测你的现有技术栈 +- 分析现有代码模式 +- 检测约定并请求确认 +- 生成尊重现有代码的上下文丰富的技术规范 + +非常适合现有代码库中的错误修复和小功能。 + +### 如果我的现有代码不遵循最佳实践怎么办？ + +快速流程会检测你的约定并询问："我应该遵循这些现有约定吗？"你决定： + +- **是** → 与当前代码库保持一致 +- **否** → 建立新标准（在技术规范中记录原因） + +BMM 尊重你的选择——它不会强制现代化，但会提供现代化选项。 + +**有未在此处回答的问题吗？** 请[提出问题](https://github.com/bmad-code-org/BMAD-METHOD/issues)或在 [Discord](https://discord.gg/gk8jAdXWmj) 中提问，以便我们添加它！ + +--- +## 术语说明 + +- **agent**：智能体。在人工智能与编程文档中，指具备自主决策或执行能力的单元。 +- **Quick Flow**：快速流程。BMad 方法中的一种工作流程，用于快速处理既有项目。 +- **tech-spec**：技术规范。描述技术实现细节和标准的文档。 +- **stack**：技术栈。项目所使用的技术组合，包括框架、库、工具等。 +- **conventions**：约定。代码库中遵循的编码风格、命名规则等规范。 +- **modernization**：现代化。将旧代码或系统更新为更现代的技术和最佳实践的过程。 diff --git a/docs_cn/explanation/party-mode_cn.md b/docs_cn/explanation/party-mode_cn.md new file mode 100644 index 000000000..85061f393 --- /dev/null +++ b/docs_cn/explanation/party-mode_cn.md @@ -0,0 +1,79 @@ +--- +title: "派对模式" +description: 多智能体协作——将所有 AI 智能体汇聚到一次对话中 +sidebar: + order: 7 +--- + +将所有 AI 智能体汇聚到一次对话中。 + +## 什么是 Party Mode？ + +运行 `party-mode`，你的整个 AI 团队就齐聚一堂——PM、架构师、开发者、UX 设计师，任何你需要的人。BMad Master 负责编排，根据每条消息选择相关的智能体。智能体以角色身份回应，彼此同意、反对，并在彼此的想法基础上继续构建。 + +对话可以持续到你想要的时间。提出追问、对答案提出质疑、引导讨论方向——这是与智能体之间真正的来回交流，直到你完成目标。 + +**适用于：** + +- 需要权衡的重大决策 +- 头脑风暴会议 +- 出现问题时的复盘 +- 冲刺回顾与规划 + +## 示例 + +### 指出糟糕的架构 + +**You:** "好了团队，我们上个冲刺是一场灾难。认证服务宕机了三次。谁搞砸了这件事？" + +**Architect:** "设计本身是合理的——分布式认证，有适当的回退机制。如果实现偏离了规范……" + +**Dev:** "我完全按照架构文档执行的。规范没有考虑到并发会话失效的竞态条件。" + +**PM:** "你们两个都忽略了更大的问题——我们没有在 PRD 中验证会话管理需求。这是我的错，没有发现这一点。" + +**TEA:** "我也应该在集成测试中发现这一点。测试场景没有覆盖并发失效。" + +### 创意头脑风暴 + +**You:** "我们如何让入职体验变得神奇，而不是无聊？" + +**UX Designer:** "从渐进式披露开始——在用户需要时揭示功能，而不是在教程中一次性展示所有内容。" + +**Storyteller:** "如果入职是一个故事会怎样？每一步都揭示一个角色的旅程——用户就是英雄。" + +**Game Designer:** "在此基础上——如果第一个'任务'实际上是解决一个真实的用户问题会怎样？他们通过做有价值的事情来学习。" + +### 技术决策 + +**You:** "MVP 用单体还是微服务？" + +**Architect:** "从单体开始。微服务会增加你在 1000 用户时不需要的复杂性。" + +**PM:** "同意。上市时间比理论上的可扩展性更重要。" + +**Dev:** "单体，但要有清晰的模块边界。如果需要，我们以后可以提取服务。" + +:::tip[Better Decisions] +通过多元视角做出更好的决策。欢迎来到 party mode。 +::: + +--- +## 术语说明 + +- **agent**：智能体。在人工智能与编程文档中，指具备自主决策或执行能力的单元。 +- **PM**：产品经理（Product Manager）。 +- **Architect**：架构师。 +- **Dev**：开发者（Developer）。 +- **UX Designer**：用户体验设计师。 +- **TEA**：测试工程师（Test Engineer/Automation）。 +- **PRD**：产品需求文档（Product Requirements Document）。 +- **MVP**：最小可行产品（Minimum Viable Product）。 +- **monolith**：单体架构。一种将应用程序构建为单一、统一单元的架构风格。 +- **microservices**：微服务。一种将应用程序构建为一组小型、独立服务的架构风格。 +- **progressive disclosure**：渐进式披露。一种交互设计模式，仅在用户需要时显示信息或功能。 +- **post-mortem**：复盘。对事件或项目进行事后分析，以了解发生了什么以及如何改进。 +- **sprint**：冲刺。敏捷开发中的固定时间周期，通常为 1-4 周。 +- **race condition**：竞态条件。当多个进程或线程同时访问和操作共享数据时，系统行为取决于执行顺序的一种情况。 +- **fallback**：回退机制。当主要方法失败时使用的备用方案。 +- **time to market**：上市时间。产品从概念到推向市场所需的时间。 diff --git a/docs_cn/explanation/preventing-agent-conflicts_cn.md b/docs_cn/explanation/preventing-agent-conflicts_cn.md new file mode 100644 index 000000000..c3f24faf6 --- /dev/null +++ b/docs_cn/explanation/preventing-agent-conflicts_cn.md @@ -0,0 +1,137 @@ +--- +title: "防止智能体冲突" +description: 架构如何在多个智能体实现系统时防止冲突 +sidebar: + order: 4 +--- + +当多个 AI 智能体实现系统的不同部分时，它们可能会做出相互冲突的技术决策。架构文档通过建立共享标准来防止这种情况。 + +## 常见冲突类型 + +### API 风格冲突 + +没有架构时： +- 智能体 A 使用 REST，路径为 `/users/{id}` +- 智能体 B 使用 GraphQL mutations +- 结果：API 模式不一致，消费者困惑 + +有架构时： +- ADR 指定："所有客户端-服务器通信使用 GraphQL" +- 所有智能体遵循相同的模式 + +### 数据库设计冲突 + +没有架构时： +- 智能体 A 使用 snake_case 列名 +- 智能体 B 使用 camelCase 列名 +- 结果：模式不一致，查询混乱 + +有架构时： +- 标准文档指定命名约定 +- 所有智能体遵循相同的模式 + +### 状态管理冲突 + +没有架构时： +- 智能体 A 使用 Redux 管理全局状态 +- 智能体 B 使用 React Context +- 结果：多种状态管理方法，复杂度增加 + +有架构时： +- ADR 指定状态管理方法 +- 所有智能体一致实现 + +## 架构如何防止冲突 + +### 1. 通过 ADR 明确决策 + +每个重要的技术选择都记录以下内容： +- 上下文（为什么这个决策很重要） +- 考虑的选项（有哪些替代方案） +- 决策（我们选择了什么） +- 理由（为什么选择它） +- 后果（接受的权衡） + +### 2. FR/NFR 特定指导 + +架构将每个功能需求映射到技术方法： +- FR-001：用户管理 → GraphQL mutations +- FR-002：移动应用 → 优化查询 + +### 3. 标准和约定 + +明确记录以下内容： +- 目录结构 +- 命名约定 +- 代码组织 +- 测试模式 + +## 架构作为共享上下文 + +将架构视为所有智能体在实现之前阅读的共享上下文： + +```text +PRD："构建什么" + ↓ +架构："如何构建" + ↓ +智能体 A 阅读架构 → 实现 Epic 1 +智能体 B 阅读架构 → 实现 Epic 2 +智能体 C 阅读架构 → 实现 Epic 3 + ↓ +结果：一致的实现 +``` + +## Key ADR Topics + +防止冲突的常见决策： + +| Topic | Example Decision | +| ---------------- | -------------------------------------------- | +| API Style | GraphQL vs REST vs gRPC | +| Database | PostgreSQL vs MongoDB | +| Auth | JWT vs Sessions | +| State Management | Redux vs Context vs Zustand | +| Styling | CSS Modules vs Tailwind vs Styled Components | +| Testing | Jest + Playwright vs Vitest + Cypress | + +## 避免的反模式 + +:::caution[常见错误] +- **隐式决策** — "我们边做边确定 API 风格"会导致不一致 +- **过度文档化** — 记录每个次要选择会导致分析瘫痪 +- **过时架构** — 文档写一次后从不更新，导致智能体遵循过时的模式 +::: + +:::tip[正确方法] +- 记录跨越 epic 边界的决策 +- 专注于容易产生冲突的领域 +- 随着学习更新架构 +- 对重大变更使用 `correct-course` +::: + +--- +## 术语说明 + +- **agent**：智能体。在人工智能与编程文档中，指具备自主决策或执行能力的单元。 +- **ADR**：架构决策记录（Architecture Decision Record）。用于记录重要架构决策及其背景、选项和后果的文档。 +- **FR**：功能需求（Functional Requirement）。系统必须具备的功能或行为。 +- **NFR**：非功能需求（Non-Functional Requirement）。系统性能、安全性、可扩展性等质量属性。 +- **Epic**：史诗。大型功能或用户故事的集合，通常需要多个迭代完成。 +- **snake_case**：蛇形命名法。单词之间用下划线连接，所有字母小写的命名风格。 +- **camelCase**：驼峰命名法。除第一个单词外，每个单词首字母大写的命名风格。 +- **GraphQL mutations**：GraphQL 变更操作。用于修改服务器数据的 GraphQL 操作类型。 +- **Redux**：JavaScript 状态管理库。用于管理应用全局状态的可预测状态容器。 +- **React Context**：React 上下文 API。用于在组件树中传递数据而无需逐层传递 props。 +- **Zustand**：轻量级状态管理库。用于 React 应用的简单状态管理解决方案。 +- **CSS Modules**：CSS 模块。将 CSS 作用域限制在组件内的技术。 +- **Tailwind**：Tailwind CSS。实用优先的 CSS 框架。 +- **Styled Components**：样式化组件。使用 JavaScript 编写样式的 React 库。 +- **Jest**：JavaScript 测试框架。用于编写和运行测试的工具。 +- **Playwright**：端到端测试框架。用于自动化浏览器测试的工具。 +- **Vitest**：Vite 原生测试框架。快速且轻量的单元测试工具。 +- **Cypress**：端到端测试框架。用于 Web 应用测试的工具。 +- **gRPC**：远程过程调用框架。Google 开发的高性能 RPC 框架。 +- **JWT**：JSON Web Token。用于身份验证的开放标准令牌。 +- **PRD**：产品需求文档（Product Requirements Document）。描述产品功能、需求和目标的文档。 diff --git a/docs_cn/explanation/project-context_cn.md b/docs_cn/explanation/project-context_cn.md new file mode 100644 index 000000000..c33b3adfc --- /dev/null +++ b/docs_cn/explanation/project-context_cn.md @@ -0,0 +1,176 @@ +--- +title: "项目上下文" +description: project-context.md 如何使用项目的规则和偏好指导 AI 智能体 +sidebar: + order: 7 +--- + +[`project-context.md`](project-context.md) 文件是您的项目面向 AI 智能体的实施指南。类似于其他开发系统中的"宪法"，它记录了确保所有工作流中代码生成一致的规则、模式和偏好。 + +## 它的作用 + +AI 智能体不断做出实施决策——遵循哪些模式、如何组织代码、使用哪些约定。如果没有明确指导，它们可能会： +- 遵循与您的代码库不匹配的通用最佳实践 +- 在不同的用户故事中做出不一致的决策 +- 错过项目特定的需求或约束 + +[`project-context.md`](project-context.md) 文件通过以简洁、针对 LLM 优化的格式记录智能体需要了解的内容来解决这个问题。 + +## 它的工作原理 + +每个实施工作流都会自动加载 [`project-context.md`](project-context.md)（如果存在）。架构师工作流也会加载它，以便在设计架构时尊重您的技术偏好。 + +**由以下工作流加载：** +- `create-architecture` — 在解决方案设计期间尊重技术偏好 +- `create-story` — 使用项目模式指导用户故事创建 +- `dev-story` — 指导实施决策 +- `code-review` — 根据项目标准进行验证 +- `quick-dev` — 在实施技术规范时应用模式 +- `sprint-planning`、`retrospective`、`correct-course` — 提供项目范围的上下文 + +## 何时创建 + +[`project-context.md`](project-context.md) 文件在项目的任何阶段都很有用： + +| 场景 | 何时创建 | 目的 | +|----------|----------------|---------| +| **新项目，架构之前** | 手动，在 `create-architecture` 之前 | 记录您的技术偏好，以便架构师尊重它们 | +| **新项目，架构之后** | 通过 `generate-project-context` 或手动 | 捕获架构决策，供实施智能体使用 | +| **现有项目** | 通过 `generate-project-context` | 发现现有模式，以便智能体遵循既定约定 | +| **快速流程项目** | 在 `quick-dev` 之前或期间 | 确保快速实施尊重您的模式 | + +:::tip[推荐] +对于新项目，如果您有强烈的技术偏好，请在架构之前手动创建。否则，在架构之后生成它以捕获这些决策。 +::: + +## 文件内容 + +该文件有两个主要部分： + +### 技术栈与版本 + +记录项目使用的框架、语言和工具及其具体版本： + +```markdown +## Technology Stack & Versions + +- Node.js 20.x, TypeScript 5.3, React 18.2 +- State: Zustand (not Redux) +- Testing: Vitest, Playwright, MSW +- Styling: Tailwind CSS with custom design tokens +``` + +### 关键实施规则 + +记录智能体可能忽略的模式和约定： + +```markdown +## Critical Implementation Rules + +**TypeScript Configuration:** +- Strict mode enabled — no `any` types without explicit approval +- Use `interface` for public APIs, `type` for unions/intersections + +**Code Organization:** +- Components in `/src/components/` with co-located `.test.tsx` +- Utilities in `/src/lib/` for reusable pure functions +- API calls use the `apiClient` singleton — never fetch directly + +**Testing Patterns:** +- Unit tests focus on business logic, not implementation details +- Integration tests use MSW to mock API responses +- E2E tests cover critical user journeys only + +**Framework-Specific:** +- All async operations use the `handleError` wrapper for consistent error handling +- Feature flags accessed via `featureFlag()` from `@/lib/flags` +- New routes follow the file-based routing pattern in `/src/app/` +``` + +专注于那些**不明显**的内容——智能体可能无法从阅读代码片段中推断出来的内容。不要记录普遍适用的标准实践。 + +## 创建文件 + +您有三个选择： + +### 手动创建 + +在 `_bmad-output/project-context.md` 创建文件并添加您的规则： + +```bash +# In your project root +mkdir -p _bmad-output +touch _bmad-output/project-context.md +``` + +使用您的技术栈和实施规则编辑它。架构师和实施工作流将自动查找并加载它。 + +### 架构后生成 + +在完成架构后运行 `generate-project-context` 工作流： + +```bash +/bmad-bmm-generate-project-context +``` + +这将扫描您的架构文档和项目文件，生成一个捕获所做决策的上下文文件。 + +### 为现有项目生成 + +对于现有项目，运行 `generate-project-context` 以发现现有模式： + +```bash +/bmad-bmm-generate-project-context +``` + +该工作流分析您的代码库以识别约定，然后生成一个您可以审查和优化的上下文文件。 + +## 为什么重要 + +没有 [`project-context.md`](project-context.md)，智能体会做出可能与您的项目不匹配的假设： + +| 没有上下文 | 有上下文 | +|----------------|--------------| +| 使用通用模式 | 遵循您的既定约定 | +| 用户故事之间风格不一致 | 实施一致 | +| 可能错过项目特定的约束 | 尊重所有技术需求 | +| 每个智能体独立决策 | 所有智能体遵循相同规则 | + +这对于以下情况尤其重要： +- **快速流程** — 跳过 PRD 和架构，因此上下文文件填补了空白 +- **团队项目** — 确保所有智能体遵循相同的标准 +- **现有项目** — 防止破坏既定模式 + +## 编辑和更新 + +[`project-context.md`](project-context.md) 文件是一个动态文档。在以下情况下更新它： + +- 架构决策发生变化 +- 建立了新的约定 +- 模式在实施过程中演变 +- 您从智能体行为中发现差距 + +您可以随时手动编辑它，或者在重大更改后重新运行 `generate-project-context` 来更新它。 + +:::note[文件位置] +默认位置是 `_bmad-output/project-context.md`。工作流在那里搜索它，并且还会检查项目中任何位置的 `**/project-context.md`。 +::: + +--- +## 术语说明 + +- **agent**：智能体。在人工智能与编程文档中，指具备自主决策或执行能力的单元。 +- **workflow**：工作流。指一系列自动化或半自动化的任务流程。 +- **PRD**：产品需求文档（Product Requirements Document）。描述产品功能、需求和目标的文档。 +- **LLM**：大语言模型（Large Language Model）。指基于深度学习的自然语言处理模型。 +- **singleton**：单例。一种设计模式，确保一个类只有一个实例。 +- **E2E**：端到端（End-to-End）。指从用户角度出发的完整测试流程。 +- **MSW**：Mock Service Worker。用于模拟 API 响应的库。 +- **Vitest**：基于 Vite 的单元测试框架。 +- **Playwright**：端到端测试框架。 +- **Zustand**：轻量级状态管理库。 +- **Redux**：JavaScript 应用状态管理库。 +- **Tailwind CSS**：实用优先的 CSS 框架。 +- **TypeScript**：JavaScript 的超集，添加了静态类型。 +- **React**：用于构建用户界面的 JavaScript 库。 +- **Node.js**：基于 Chrome V8 引擎的 JavaScript 运行时。 diff --git a/docs_cn/explanation/quick-flow_cn.md b/docs_cn/explanation/quick-flow_cn.md new file mode 100644 index 000000000..4f1936c18 --- /dev/null +++ b/docs_cn/explanation/quick-flow_cn.md @@ -0,0 +1,93 @@ +--- +title: "Quick Flow" +description: 小型变更的快速通道 - 跳过完整方法论 +sidebar: + order: 1 +--- + +跳过繁琐流程。Quick Flow 通过两条命令将你从想法带到可运行的代码 - 无需产品简报、无需 PRD、无需架构文档。 + +## 何时使用 + +- Bug 修复和补丁 +- 重构现有代码 +- 小型、易于理解的功能 +- 原型设计和探索性开发 +- 单智能体工作，一名开发者可以掌控完整范围 + +## 何时不使用 + +- 需要利益相关者对齐的新产品或平台 +- 跨越多个组件或团队的主要功能 +- 需要架构决策的工作（数据库架构、API 契约、服务边界） +- 需求不明确或有争议的任何工作 + +:::caution[Scope Creep] +如果你启动 Quick Flow 后发现范围超出预期，`quick-dev` 会检测到并提供升级选项。你可以在任何时间切换到完整的 PRD 工作流程，而不会丢失你的工作。 +::: + +## 工作原理 + +Quick Flow 有两条命令，每条都由结构化的工作流程支持。你可以一起运行它们，也可以独立运行。 + +### quick-spec：规划 + +运行 `quick-spec`，Barry（Quick Flow 智能体）会引导你完成对话式发现过程： + +1. **理解** - 你描述想要构建的内容。Barry 扫描代码库以提出有针对性的问题，然后捕获问题陈述、解决方案方法和范围边界。 +2. **调查** - Barry 读取相关文件，映射代码模式，识别需要修改的文件，并记录技术上下文。 +3. **生成** - 生成完整的技术规范，包含有序的实现任务（具体文件路径和操作）、Given/When/Then 格式的验收标准、测试策略和依赖项。 +4. **审查** - 展示完整规范供你确认。你可以在最终定稿前进行编辑、提问、运行对抗性审查或使用高级启发式方法进行优化。 + +输出是一个 `tech-spec-{slug}.md` 文件，保存到项目的实现工件文件夹中。它包含新智能体实现功能所需的一切 - 无需对话历史。 + +### quick-dev：构建 + +运行 `quick-dev`，Barry 实现工作。它以两种模式运行： + +- **技术规范模式** - 指向规范文件（`quick-dev tech-spec-auth.md`），它按顺序执行每个任务，编写测试，并验证验收标准。 +- **直接模式** - 直接给出指令（`quick-dev "refactor the auth middleware"`），它收集上下文，构建心智计划，并执行。 + +实现后，`quick-dev` 针对所有任务和验收标准运行自检审计，然后触发差异的对抗性代码审查。发现的问题会呈现给你，以便在收尾前解决。 + +:::tip[Fresh Context] +为获得最佳效果，在完成 `quick-spec` 后，在新对话中运行 `quick-dev`。这为实现智能体提供了专注于构建的干净上下文。 +::: + +## Quick Flow 跳过的内容 + +完整的 BMad 方法在编写任何代码之前会生成产品简报、PRD、架构文档和 Epic/Story 分解。Quick Flow 用单个技术规范替代所有这些。这之所以有效，是因为 Quick Flow 针对以下变更： + +- 产品方向已确立 +- 架构决策已做出 +- 单个开发者可以推理完整范围 +- 需求可以在一次对话中涵盖 + +## 升级到完整 BMad 方法 + +Quick Flow 包含内置的范围检测护栏。当你使用直接请求运行 `quick-dev` 时，它会评估多组件提及、系统级语言和方法不确定性等信号。如果检测到工作超出快速流程范围： + +- **轻度升级** - 建议先运行 `quick-spec` 创建计划 +- **重度升级** - 建议切换到完整的 BMad 方法 PRD 流程 + +你也可以随时手动升级。你的技术规范工作会继续推进 - 它将成为更广泛规划过程的输入，而不是被丢弃。 + +--- +## 术语说明 + +- **Quick Flow**：快速流程。BMad 方法中用于小型变更的简化工作流程，跳过完整的产品规划和架构文档阶段。 +- **PRD**：Product Requirements Document，产品需求文档。详细描述产品功能、需求和验收标准的文档。 +- **Product Brief**：产品简报。概述产品愿景、目标和范围的高层文档。 +- **Architecture doc**：架构文档。描述系统架构、组件设计和技术决策的文档。 +- **Epic/Story**：史诗/故事。敏捷开发中的工作单元，Epic 是大型功能集合，Story 是具体用户故事。 +- **agent**：智能体。在人工智能与编程文档中，指具备自主决策或执行能力的单元。 +- **Scope Creep**：范围蔓延。项目范围在开发过程中逐渐扩大，超出原始计划的现象。 +- **tech-spec**：技术规范。详细描述技术实现方案、任务分解和验收标准的文档。 +- **slug**：短标识符。用于生成 URL 或文件名的简短、唯一的字符串标识。 +- **Given/When/Then**：一种行为驱动开发（BDD）的测试场景描述格式，用于定义验收标准。 +- **adversarial review**：对抗性审查。一种代码审查方法，模拟攻击者视角以发现潜在问题和漏洞。 +- **elicitation**：启发式方法。通过提问和对话引导来获取信息、澄清需求的技术。 +- **stakeholder**：利益相关者。对项目有利益或影响的个人或组织。 +- **API contracts**：API 契约。定义 API 接口规范、请求/响应格式和行为约定的文档。 +- **service boundaries**：服务边界。定义服务职责范围和边界的架构概念。 +- **spikes**：探索性开发。用于探索技术可行性或解决方案的短期研究活动。 diff --git a/docs_cn/explanation/why-solutioning-matters_cn.md b/docs_cn/explanation/why-solutioning-matters_cn.md new file mode 100644 index 000000000..27e8f96ca --- /dev/null +++ b/docs_cn/explanation/why-solutioning-matters_cn.md @@ -0,0 +1,90 @@ +--- +title: "为什么解决方案阶段很重要" +description: 理解为什么解决方案阶段对于多史诗项目至关重要 +sidebar: + order: 3 +--- + + +阶段 3（解决方案）将构建**什么**（来自规划）转化为**如何**构建（技术设计）。该阶段通过在实施开始前记录架构决策，防止多史诗项目中的智能体冲突。 + +## 没有解决方案阶段的问题 + +```text +智能体 1 使用 REST API 实现史诗 1 +智能体 2 使用 GraphQL 实现史诗 2 +结果：API 设计不一致，集成噩梦 +``` + +当多个智能体在没有共享架构指导的情况下实现系统的不同部分时，它们会做出可能冲突的独立技术决策。 + +## 有解决方案阶段的解决方案 + +```text +架构工作流决定："所有 API 使用 GraphQL" +所有智能体遵循架构决策 +结果：实现一致，无冲突 +``` + +通过明确记录技术决策，所有智能体都能一致地实现，集成变得简单直接。 + +## 解决方案阶段 vs 规划阶段 + +| 方面 | 规划（阶段 2） | 解决方案（阶段 3） | +| -------- | ----------------------- | --------------------------------- | +| 问题 | 做什么和为什么？ | 如何做？然后是什么工作单元？ | +| 输出 | FRs/NFRs（需求） | 架构 + 史诗/用户故事 | +| 智能体 | PM | 架构师 → PM | +| 受众 | 利益相关者 | 开发人员 | +| 文档 | PRD（FRs/NFRs） | 架构 + 史诗文件 | +| 层级 | 业务逻辑 | 技术设计 + 工作分解 | + +## 核心原则 + +**使技术决策明确且有文档记录**，以便所有智能体一致地实现。 + +这可以防止： +- API 风格冲突（REST vs GraphQL） +- 数据库设计不一致 +- 状态管理分歧 +- 命名约定不匹配 +- 安全方法差异 + +## 何时需要解决方案阶段 + +| 流程 | 需要解决方案阶段？ | +|-------|----------------------| +| Quick Flow | 否 - 完全跳过 | +| BMad Method Simple | 可选 | +| BMad Method Complex | 是 | +| Enterprise | 是 | + +:::tip[经验法则] +如果你有多个可能由不同智能体实现的史诗，你需要解决方案阶段。 +::: + +## 跳过的代价 + +在复杂项目中跳过解决方案阶段会导致： + +- **集成问题**在冲刺中期发现 +- **返工**由于实现冲突 +- **开发时间更长**整体 +- **技术债务**来自不一致模式 + +:::caution[成本倍增] +在解决方案阶段发现对齐问题比在实施期间发现要快 10 倍。 +::: + +--- +## 术语说明 + +- **agent**：智能体。在人工智能与编程文档中，指具备自主决策或执行能力的单元。 +- **epic**：史诗。在敏捷开发中，指一个大型的工作项，可分解为多个用户故事。 +- **REST API**：表述性状态传递应用程序接口。一种基于 HTTP 协议的 Web API 设计风格。 +- **GraphQL**：一种用于 API 的查询语言和运行时环境。 +- **FRs/NFRs**：功能需求/非功能需求。Functional Requirements/Non-Functional Requirements 的缩写。 +- **PRD**：产品需求文档。Product Requirements Document 的缩写。 +- **PM**：产品经理。Product Manager 的缩写。 +- **sprint**：冲刺。敏捷开发中的固定时间周期，通常为 1-4 周。 +- **technical debt**：技术债务。指为了短期目标而选择的不完美技术方案，未来需要付出额外成本来修复。 diff --git a/docs_cn/how-to/customize-bmad_cn.md b/docs_cn/how-to/customize-bmad_cn.md new file mode 100644 index 000000000..b131579f9 --- /dev/null +++ b/docs_cn/how-to/customize-bmad_cn.md @@ -0,0 +1,182 @@ +--- +title: "如何自定义 BMad" +description: 自定义智能体、工作流和模块，同时保持更新兼容性 +sidebar: + order: 7 +--- + +使用 `.customize.yaml` 文件来调整智能体行为、角色和菜单，同时在更新过程中保留您的更改。 + +## 何时使用此功能 + +- 您想要更改智能体的名称、个性或沟通风格 +- 您需要智能体记住项目特定的上下文 +- 您想要添加自定义菜单项来触发您自己的工作流或提示 +- 您希望智能体在每次启动时执行特定操作 + +:::note[前置条件] +- 在项目中安装了 BMad（参见[如何安装 BMad](./install-bmad_cn.md)） +- 用于编辑 YAML 文件的文本编辑器 +::: + +:::caution[保护您的自定义配置] +始终使用此处描述的 `.customize.yaml` 文件，而不是直接编辑智能体文件。安装程序在更新期间会覆盖智能体文件，但会保留您的 `.customize.yaml` 更改。 +::: + +## 步骤 + +### 1. 定位自定义文件 + +安装后，在以下位置为每个智能体找到一个 `.customize.yaml` 文件： + +```text +_bmad/_config/agents/ +├── core-bmad-master.customize.yaml +├── bmm-dev.customize.yaml +├── bmm-pm.customize.yaml +└── ...（每个已安装的智能体一个文件） +``` + +### 2. 编辑自定义文件 + +打开您想要修改的智能体的 `.customize.yaml` 文件。每个部分都是可选的——只自定义您需要的内容。 + +| 部分 | 行为 | 用途 | +| ------------------ | -------- | ---------------------------------------------- | +| `agent.metadata` | 替换 | 覆盖智能体的显示名称 | +| `persona` | 替换 | 设置角色、身份、风格和原则 | +| `memories` | 追加 | 添加智能体始终会记住的持久上下文 | +| `menu` | 追加 | 为工作流或提示添加自定义菜单项 | +| `critical_actions` | 追加 | 定义智能体的启动指令 | +| `prompts` | 追加 | 创建可重复使用的提示供菜单操作使用 | + +标记为 **替换** 的部分会完全覆盖智能体的默认设置。标记为 **追加** 的部分会添加到现有配置中。 + +**智能体名称** + +更改智能体的自我介绍方式： + +```yaml +agent: + metadata: + name: 'Spongebob' # 默认值："Amelia" +``` + +**角色** + +替换智能体的个性、角色和沟通风格： + +```yaml +persona: + role: 'Senior Full-Stack Engineer' + identity: 'Lives in a pineapple (under the sea)' + communication_style: 'Spongebob annoying' + principles: + - 'Never Nester, Spongebob Devs hate nesting more than 2 levels deep' + - 'Favor composition over inheritance' +``` + +`persona` 部分会替换整个默认角色，因此如果您设置它，请包含所有四个字段。 + +**记忆** + +添加智能体将始终记住的持久上下文： + +```yaml +memories: + - 'Works at Krusty Krab' + - 'Favorite Celebrity: David Hasslehoff' + - 'Learned in Epic 1 that it is not cool to just pretend that tests have passed' +``` + +**菜单项** + +向智能体的显示菜单添加自定义条目。每个条目需要一个 `trigger`、一个目标（`workflow` 路径或 `action` 引用）和一个 `description`： + +```yaml +menu: + - trigger: my-workflow + workflow: 'my-custom/workflows/my-workflow.yaml' + description: My custom workflow + - trigger: deploy + action: '#deploy-prompt' + description: Deploy to production +``` + +**关键操作** + +定义智能体启动时运行的指令： + +```yaml +critical_actions: + - 'Check the CI Pipelines with the XYZ Skill and alert user on wake if anything is urgently needing attention' +``` + +**自定义提示** + +创建可重复使用的提示，菜单项可以通过 `action="#id"` 引用： + +```yaml +prompts: + - id: deploy-prompt + content: | + Deploy the current branch to production: + 1. Run all tests + 2. Build the project + 3. Execute deployment script +``` + +### 3. 应用您的更改 + +编辑后，重新编译智能体以应用更改： + +```bash +npx bmad-method install +``` + +安装程序会检测现有安装并提供以下选项： + +| Option | What It Does | +| ---------------------------- | ------------------------------------------------------------------- | +| **Quick Update** | 将所有模块更新到最新版本并重新编译所有智能体 | +| **Recompile Agents** | 仅应用自定义配置，不更新模块文件 | +| **Modify BMad Installation** | 用于添加或删除模块的完整安装流程 | + +对于仅自定义配置的更改，**Recompile Agents** 是最快的选项。 + +## 故障排除 + +**更改未生效？** + +- 运行 `npx bmad-method install` 并选择 **Recompile Agents** 以应用更改 +- 检查您的 YAML 语法是否有效（缩进很重要） +- 验证您编辑的是该智能体正确的 `.customize.yaml` 文件 + +**智能体无法加载？** + +- 使用在线 YAML 验证器检查 YAML 语法错误 +- 确保在取消注释后没有留下空字段 +- 尝试恢复到原始模板并重新构建 + +**需要重置智能体？** + +- 清空或删除智能体的 `.customize.yaml` 文件 +- 运行 `npx bmad-method install` 并选择 **Recompile Agents** 以恢复默认设置 + +## 工作流自定义 + +对现有 BMad Method 工作流和技能的自定义即将推出。 + +## 模块自定义 + +关于构建扩展模块和自定义现有模块的指南即将推出。 + +--- +## 术语说明 + +- **agent**：智能体。在人工智能与编程文档中，指具备自主决策或执行能力的单元。 +- **workflow**：工作流。指一系列有序的任务或步骤，用于完成特定目标。 +- **persona**：角色。指智能体的身份、个性、沟通风格和行为原则的集合。 +- **memory**：记忆。指智能体持久存储的上下文信息，用于在对话中保持连贯性。 +- **critical action**：关键操作。指智能体启动时必须执行的指令或任务。 +- **prompt**：提示。指发送给智能体的输入文本，用于引导其生成特定响应或执行特定操作。 diff --git a/docs_cn/how-to/established-projects_cn.md b/docs_cn/how-to/established-projects_cn.md new file mode 100644 index 000000000..86e472891 --- /dev/null +++ b/docs_cn/how-to/established-projects_cn.md @@ -0,0 +1,134 @@ +--- +title: "既有项目" +description: 如何在现有代码库中使用 BMad Method +sidebar: + order: 6 +--- + +在现有项目和遗留代码库上工作时，有效使用 BMad Method。 + +本指南涵盖了使用 BMad Method 接入现有项目的核心工作流程。 + +:::note[前置条件] +- 已安装 BMad Method（`npx bmad-method install`） +- 一个你想要处理的现有代码库 +- 访问 AI 驱动的 IDE（Claude Code 或 Cursor） +::: + +## 步骤 1：清理已完成的规划产物 + +如果你通过 BMad 流程完成了所有 PRD 史诗和用户故事，请清理这些文件。归档它们、删除它们，或者在需要时依赖版本历史。不要将这些文件保留在： + +- `docs/` +- `_bmad-output/planning-artifacts/` +- `_bmad-output/implementation-artifacts/` + +## 步骤 2：创建项目上下文 + +:::tip[推荐用于既有项目] +生成 `project-context.md` 以捕获你现有代码库的模式和约定。这确保 AI 智能体在实施变更时遵循你既定的实践。 +::: + +运行生成项目上下文工作流程： + +```bash +/bmad-bmm-generate-project-context +``` + +这将扫描你的代码库以识别： +- 技术栈和版本 +- 代码组织模式 +- 命名约定 +- 测试方法 +- 框架特定模式 + +你可以查看和完善生成的文件，或者如果你更喜欢，可以在 `_bmad-output/project-context.md` 手动创建它。 + +[了解更多关于项目上下文](../explanation/project-context_cn.md) + +## 步骤 3：维护高质量项目文档 + +你的 `docs/` 文件夹应包含简洁、组织良好的文档，准确代表你的项目： + +- 意图和业务理由 +- 业务规则 +- 架构 +- 任何其他相关的项目信息 + +对于复杂项目，考虑使用 `document-project` 工作流程。它提供运行时变体，将扫描你的整个项目并记录其实际当前状态。 + +## 步骤 3：获取帮助 + +### BMad-Help：你的起点 + +**随时运行 `/bmad-help`，当你不确定下一步该做什么时。** 这个智能指南： + +- 检查你的项目以查看已经完成了什么 +- 根据你安装的模块显示选项 +- 理解自然语言查询 + +``` +/bmad-help 我有一个现有的 Rails 应用，我应该从哪里开始？ +/bmad-help quick-flow 和完整方法有什么区别？ +/bmad-help 显示我有哪些可用的工作流程 +``` + +BMad-Help 还会在**每个工作流程结束时自动运行**，提供关于下一步该做什么的清晰指导。 + +### 选择你的方法 + +根据变更范围，你有两个主要选项： + +| 范围 | 推荐方法 | +| ------------------------------ | ----------------------------------------------------------------------------------------------------------------- | +| **小型更新或添加** | 使用 `quick-flow-solo-dev` 创建技术规范并实施变更。完整的四阶段 BMad Method 可能有些过度。 | +| **重大变更或添加** | 从 BMad Method 开始，根据需要应用或多或少的严谨性。 | + +### 在创建 PRD 期间 + +在创建简报或直接进入 PRD 时，确保智能体： + +- 查找并分析你现有的项目文档 +- 阅读关于你当前系统的适当上下文 + +你可以明确地指导智能体，但目标是确保新功能与你的现有系统良好集成。 + +### UX 考量 + +UX 工作是可选的。决定不取决于你的项目是否有 UX，而取决于： + +- 你是否将处理 UX 变更 +- 是否需要重要的新 UX 设计或模式 + +如果你的变更只是对你满意的现有屏幕进行简单更新，则不需要完整的 UX 流程。 + +### 架构考量 + +在进行架构工作时，确保架构师： + +- 使用适当的已记录文件 +- 扫描现有代码库 + +在此处要密切注意，以防止重新发明轮子或做出与你现有架构不一致的决定。 + +## 更多信息 + +- **[快速修复](./quick-fixes_cn.md)** - 错误修复和临时变更 +- **[既有项目 FAQ](../explanation/established-projects-faq_cn.md)** - 关于在既有项目上工作的常见问题 + +--- +## 术语说明 + +- **BMad Method**：BMad 方法。一种结构化的软件开发方法论，用于指导从分析到实施的完整流程。 +- **PRD**：产品需求文档（Product Requirements Document）。描述产品功能、需求和目标的文档。 +- **epic**：史诗。大型功能或用户故事的集合，通常需要较长时间完成。 +- **story**：用户故事。描述用户需求的简短陈述，通常遵循"作为...我想要...以便于..."的格式。 +- **agent**：智能体。在人工智能与编程文档中，指具备自主决策或执行能力的单元。 +- **IDE**：集成开发环境（Integrated Development Environment）。提供代码编辑、调试、构建等功能的软件工具。 +- **UX**：用户体验（User Experience）。用户在使用产品或服务过程中的整体感受和交互体验。 +- **tech-spec**：技术规范（Technical Specification）。描述技术实现细节、架构设计和开发标准的文档。 +- **quick-flow**：快速流程。BMad Method 中的一种简化工作流程，适用于小型变更或快速迭代。 +- **legacy codebase**：遗留代码库。指历史遗留的、可能缺乏文档或使用过时技术的代码集合。 +- **project context**：项目上下文。描述项目技术栈、约定、模式等背景信息的文档。 +- **artifact**：产物。在开发过程中生成的文档、代码或其他输出物。 +- **runtime variant**：运行时变体。在程序运行时可选择或切换的不同实现方式或配置。 diff --git a/docs_cn/how-to/get-answers-about-bmad_cn.md b/docs_cn/how-to/get-answers-about-bmad_cn.md new file mode 100644 index 000000000..d40dbbcab --- /dev/null +++ b/docs_cn/how-to/get-answers-about-bmad_cn.md @@ -0,0 +1,144 @@ +--- +title: "如何获取关于 BMad 的答案" +description: 使用 LLM 快速回答您自己的 BMad 问题 +sidebar: + order: 4 +--- + +## 从这里开始：BMad-Help + +**获取关于 BMad 答案的最快方式是 `/bmad-help`。** 这个智能指南可以回答超过 80% 的问题，并且直接在您的 IDE 中可用，方便您工作时使用。 + +BMad-Help 不仅仅是一个查询工具——它： +- **检查您的项目**以查看已完成的内容 +- **理解自然语言**——用简单的英语提问 +- **根据您安装的模块变化**——显示相关选项 +- **在工作流后自动运行**——告诉您接下来该做什么 +- **推荐第一个必需任务**——无需猜测从哪里开始 + +### 如何使用 BMad-Help + +只需使用斜杠命令运行它： + +``` +/bmad-help +``` + +或者结合自然语言查询： + +``` +/bmad-help 我有一个 SaaS 想法并且知道所有功能。我应该从哪里开始？ +/bmad-help 我在 UX 设计方面有哪些选择？ +/bmad-help 我在 PRD 工作流上卡住了 +/bmad-help 向我展示到目前为止已完成的内容 +``` + +BMad-Help 会回应： +- 针对您情况的建议 +- 第一个必需任务是什么 +- 流程的其余部分是什么样的 + +--- + +## 何时使用本指南 + +在以下情况下使用本节： +- 您想了解 BMad 的架构或内部机制 +- 您需要 BMad-Help 提供范围之外的答案 +- 您在安装前研究 BMad +- 您想直接探索源代码 + +## 步骤 + +### 1. 选择您的来源 + +| 来源 | 最适合用于 | 示例 | +| -------------------- | ----------------------------------------- | ---------------------------- | +| **`_bmad` 文件夹** | BMad 如何工作——智能体、工作流、提示词 | "PM 智能体做什么？" | +| **完整的 GitHub 仓库** | 历史、安装程序、架构 | "v6 中有什么变化？" | +| **`llms-full.txt`** | 来自文档的快速概述 | "解释 BMad 的四个阶段" | + +`_bmad` 文件夹在您安装 BMad 时创建。如果您还没有它，请改为克隆仓库。 + +### 2. 将您的 AI 指向来源 + +**如果您的 AI 可以读取文件（Claude Code、Cursor 等）：** + +- **已安装 BMad：** 指向 `_bmad` 文件夹并直接提问 +- **想要更深入的上下文：** 克隆[完整仓库](https://github.com/bmad-code-org/BMAD-METHOD) + +**如果您使用 ChatGPT 或 Claude.ai：** + +将 `llms-full.txt` 获取到您的会话中： + +```text +https://bmad-code-org.github.io/BMAD-METHOD/llms-full.txt +``` + + +### 3. 提出您的问题 + +:::note[示例] +**问：** "告诉我用 BMad 构建某物的最快方式" + +**答：** 使用快速流程：运行 `quick-spec` 编写技术规范，然后运行 `quick-dev` 实现它——跳过完整的规划阶段。 +::: + +## 您将获得什么 + +关于 BMad 的直接答案——智能体如何工作、工作流做什么、为什么事物以这种方式构建——无需等待其他人回应。 + +## 提示 + +- **验证令人惊讶的答案**——LLM 偶尔会出错。检查源文件或在 Discord 上询问。 +- **具体化**——"PRD 工作流的第 3 步做什么？"比"PRD 如何工作？"更好 + +## 仍然卡住了？ + +尝试了 LLM 方法但仍需要帮助？您现在有一个更好的问题可以问。 + +| 频道 | 用于 | +| ------------------------- | ------------------------------------------- | +| `#bmad-method-help` | 快速问题（实时聊天） | +| `help-requests` 论坛 | 详细问题（可搜索、持久） | +| `#suggestions-feedback` | 想法和功能请求 | +| `#report-bugs-and-issues` | 错误报告 | + +**Discord：** [discord.gg/gk8jAdXWmj](https://discord.gg/gk8jAdXWmj) + +**GitHub Issues：** [github.com/bmad-code-org/BMAD-METHOD/issues](https://github.com/bmad-code-org/BMAD-METHOD/issues)（用于明确的错误） + +*你！* + *卡住* + *在队列中——* + *等待* + *等待谁？* + +*来源* + *就在那里，* + *显而易见！* + +*指向* + *你的机器。* + *释放它。* + +*它读取。* + *它说话。* + *尽管问——* + +*为什么要等* + *明天* + *当你拥有* + *今天？* + +*—Claude* + +--- +## 术语说明 + +- **agent**：智能体。在人工智能与编程文档中，指具备自主决策或执行能力的单元。 +- **LLM**：大语言模型。基于深度学习的自然语言处理模型，能够理解和生成人类语言。 +- **SaaS**：软件即服务。一种通过互联网提供软件应用的交付模式。 +- **UX**：用户体验。用户在使用产品或服务过程中建立的主观感受和评价。 +- **PRD**：产品需求文档。详细描述产品功能、特性和需求的正式文档。 +- **IDE**：集成开发环境。提供代码编辑、调试、构建等功能的软件开发工具。 diff --git a/docs_cn/how-to/install-bmad_cn.md b/docs_cn/how-to/install-bmad_cn.md new file mode 100644 index 000000000..1b2c8f101 --- /dev/null +++ b/docs_cn/how-to/install-bmad_cn.md @@ -0,0 +1,105 @@ +--- +title: "如何安装 BMad" +description: 在项目中安装 BMad 的分步指南 +sidebar: + order: 1 +--- + +使用 `npx bmad-method install` 命令在项目中设置 BMad，并选择你需要的模块和 AI 工具。 + +如果你想使用非交互式安装程序并在命令行中提供所有安装选项，请参阅[本指南](./non-interactive-installation_cn.md)。 + +## 何时使用 + +- 使用 BMad 启动新项目 +- 将 BMad 添加到现有代码库 +- 更新现有的 BMad 安装 + +:::note[前置条件] +- **Node.js** 20+（安装程序必需） +- **Git**（推荐） +- **AI 工具**（Claude Code、Cursor 或类似工具） +::: + +## 步骤 + +### 1. 运行安装程序 + +```bash +npx bmad-method install +``` + +:::tip[最新版本] +要从主分支安装最新版本（可能不稳定）： +```bash +npx github:bmad-code-org/BMAD-METHOD install +``` +::: + +### 2. 选择安装位置 + +安装程序会询问在哪里安装 BMad 文件： + +- 当前目录（如果你自己创建了目录并从该目录运行，推荐用于新项目） +- 自定义路径 + +### 3. 选择你的 AI 工具 + +选择你使用的 AI 工具： + +- Claude Code +- Cursor +- 其他 + +每个工具都有自己的命令集成方式。安装程序会创建微小的提示文件来激活工作流和智能体——它只是将它们放在工具期望找到的位置。 + +### 4. 选择模块 + +安装程序会显示可用的模块。选择你需要的模块——大多数用户只需要 **BMad Method**（软件开发模块）。 + +### 5. 按照提示操作 + +安装程序会引导你完成剩余步骤——自定义内容、设置等。 + +## 你将获得 + +```text +your-project/ +├── _bmad/ +│ ├── bmm/ # 你选择的模块 +│ │ └── config.yaml # 模块设置（如果你需要更改它们） +│ ├── core/ # 必需的核心模块 +│ └── ... +├── _bmad-output/ # 生成的工件 +├── .claude/ # Claude Code 命令（如果使用 Claude Code） +└── .kiro/ # Kiro 引导文件（如果使用 Kiro） +``` + +## 验证安装 + +运行 `/bmad-help` 来验证一切正常并查看下一步操作。 + +**BMad-Help 是你的智能向导**，它会： +- 确认你的安装正常工作 +- 根据你安装的模块显示可用内容 +- 推荐你的第一步 + +你也可以向它提问： +``` +/bmad-help 我刚安装完成，应该先做什么？ +/bmad-help 对于 SaaS 项目我有哪些选项？ +``` + +## 故障排除 + +**安装程序抛出错误**——将输出复制粘贴到你的 AI 助手中，让它来解决问题。 + +**安装程序工作正常但后续出现问题**——你的 AI 需要 BMad 上下文才能提供帮助。请参阅[如何获取关于 BMad 的答案](./get-answers-about-bmad_cn.md)了解如何将你的 AI 指向正确的来源。 + +--- +## 术语说明 + +- **agent**：智能体。在人工智能与编程文档中，指具备自主决策或执行能力的单元。 +- **workflow**：工作流。指一系列有序的任务或步骤，用于完成特定目标。 +- **module**：模块。指软件系统中可独立开发、测试和维护的功能单元。 +- **artifact**：工件。指在软件开发过程中生成的任何输出，如文档、代码、配置文件等。 diff --git a/docs_cn/how-to/non-interactive-installation_cn.md b/docs_cn/how-to/non-interactive-installation_cn.md new file mode 100644 index 000000000..04ca05f41 --- /dev/null +++ b/docs_cn/how-to/non-interactive-installation_cn.md @@ -0,0 +1,181 @@ +--- +title: 非交互式安装 +description: 使用命令行标志安装 BMad，适用于 CI/CD 流水线和自动化部署 +sidebar: + order: 2 +--- + +使用命令行标志以非交互方式安装 BMad。这适用于： + +## 使用场景 + +- 自动化部署和 CI/CD 流水线 +- 脚本化安装 +- 跨多个项目的批量安装 +- 使用已知配置的快速安装 + +:::note[前置条件] +需要 [Node.js](https://nodejs.org) v20+ 和 `npx`（随 npm 附带）。 +::: + +## 可用标志 + +### 安装选项 + +| 标志 | 描述 | 示例 | +|------|-------------|---------| +| `--directory ` | 安装目录 | `--directory ~/projects/myapp` | +| `--modules ` | 逗号分隔的模块 ID | `--modules bmm,bmb` | +| `--tools ` | 逗号分隔的工具/IDE ID（使用 `none` 跳过） | `--tools claude-code,cursor` 或 `--tools none` | +| `--custom-content ` | 逗号分隔的自定义模块路径 | `--custom-content ~/my-module,~/another-module` | +| `--action ` | 对现有安装的操作：`install`（默认）、`update`、`quick-update` 或 `compile-agents` | `--action quick-update` | + +### 核心配置 + +| 标志 | 描述 | 默认值 | +|------|-------------|---------| +| `--user-name ` | 智能体使用的名称 | 系统用户名 | +| `--communication-language ` | 智能体通信语言 | 英语 | +| `--document-output-language ` | 文档输出语言 | 英语 | +| `--output-folder ` | 输出文件夹路径 | _bmad-output | + +### 其他选项 + +| 标志 | 描述 | +|------|-------------| +| `-y, --yes` | 接受所有默认值并跳过提示 | +| `-d, --debug` | 启用清单生成的调试输出 | + +## 模块 ID + +`--modules` 标志可用的模块 ID： + +- `bmm` — BMad Method Master +- `bmb` — BMad Builder + +查看 [BMad 注册表](https://github.com/bmad-code-org) 获取可用的外部模块。 + +## 工具/IDE ID + +`--tools` 标志可用的工具 ID： + +**推荐：** `claude-code`、`cursor` + +运行一次 `npx bmad-method install` 交互式安装以查看完整的当前支持工具列表，或查看 [平台代码配置](https://github.com/bmad-code-org/BMAD-METHOD/blob/main/tools/cli/installers/lib/ide/platform-codes.yaml)。 + +## 安装模式 + +| 模式 | 描述 | 示例 | +|------|-------------|---------| +| 完全非交互式 | 提供所有标志以跳过所有提示 | `npx bmad-method install --directory . --modules bmm --tools claude-code --yes` | +| 半交互式 | 提供部分标志；BMad 提示其余部分 | `npx bmad-method install --directory . --modules bmm` | +| 仅使用默认值 | 使用 `-y` 接受所有默认值 | `npx bmad-method install --yes` | +| 不包含工具 | 跳过工具/IDE 配置 | `npx bmad-method install --modules bmm --tools none` | + +## 示例 + +### CI/CD 流水线安装 + +```bash +#!/bin/bash +# install-bmad.sh + +npx bmad-method install \ + --directory "${GITHUB_WORKSPACE}" \ + --modules bmm \ + --tools claude-code \ + --user-name "CI Bot" \ + --communication-language English \ + --document-output-language English \ + --output-folder _bmad-output \ + --yes +``` + +### 更新现有安装 + +```bash +npx bmad-method install \ + --directory ~/projects/myapp \ + --action update \ + --modules bmm,bmb,custom-module +``` + +### 快速更新（保留设置） + +```bash +npx bmad-method install \ + --directory ~/projects/myapp \ + --action quick-update +``` + +### 使用自定义内容安装 + +```bash +npx bmad-method install \ + --directory ~/projects/myapp \ + --modules bmm \ + --custom-content ~/my-custom-module,~/another-module \ + --tools claude-code +``` + +## 安装结果 + +- 项目中完全配置的 `_bmad/` 目录 +- 为所选模块和工具编译的智能体和工作流 +- 用于生成产物的 `_bmad-output/` 文件夹 + +## 验证和错误处理 + +BMad 会验证所有提供的标志： + +- **目录** — 必须是具有写入权限的有效路径 +- **模块** — 对无效的模块 ID 发出警告（但不会失败） +- **工具** — 对无效的工具 ID 发出警告（但不会失败） +- **自定义内容** — 每个路径必须包含有效的 `module.yaml` 文件 +- **操作** — 必须是以下之一：`install`、`update`、`quick-update`、`compile-agents` + +无效值将： +1. 显示错误并退出（对于目录等关键选项） +2. 显示警告并跳过（对于自定义内容等可选项目） +3. 回退到交互式提示（对于缺失的必需值） + +:::tip[最佳实践] +- 为 `--directory` 使用绝对路径以避免歧义 +- 在 CI/CD 流水线中使用前先在本地测试标志 +- 结合 `-y` 实现真正的无人值守安装 +- 如果在安装过程中遇到问题，使用 `--debug` +::: + +## 故障排除 + +### 安装失败，提示"Invalid directory" + +- 目录路径必须存在（或其父目录必须存在） +- 您需要写入权限 +- 路径必须是绝对路径或相对于当前目录的正确相对路径 + +### 未找到模块 + +- 验证模块 ID 是否正确 +- 外部模块必须在注册表中可用 + +### 自定义内容路径无效 + +确保每个自定义内容路径： +- 指向一个目录 +- 在根目录中包含 `module.yaml` 文件 +- 在 `module.yaml` 中有 `code` 字段 + +:::note[仍然卡住了？] +使用 `--debug` 运行以获取详细输出，尝试交互模式以隔离问题，或在 报告。 +::: + +--- +## 术语说明 + +- **CI/CD**：持续集成/持续部署。一种自动化软件开发流程的实践，用于频繁集成代码更改并自动部署到生产环境。 +- **agent**：智能体。在人工智能与编程文档中，指具备自主决策或执行能力的单元。 +- **module**：模块。软件系统中可独立开发、测试和维护的功能单元。 +- **IDE**：集成开发环境。提供代码编辑、调试、构建等功能的软件开发工具。 +- **npx**：Node Package eXecute。npm 包执行器，用于直接执行 npm 包而无需全局安装。 +- **workflow**：工作流。一系列有序的任务或步骤，用于完成特定的业务流程或开发流程。 diff --git a/docs_cn/how-to/project-context_cn.md b/docs_cn/how-to/project-context_cn.md new file mode 100644 index 000000000..d1cf8dfce --- /dev/null +++ b/docs_cn/how-to/project-context_cn.md @@ -0,0 +1,152 @@ +--- +title: "管理项目上下文" +description: 创建并维护 project-context.md 以指导 AI 智能体 +sidebar: + order: 7 +--- + +使用 `project-context.md` 文件确保 AI 智能体在所有工作流程中遵循项目的技术偏好和实现规则。 + +:::note[前置条件] +- 已安装 BMad Method +- 了解项目的技术栈和约定 +::: + +## 何时使用 + +- 在开始架构设计之前有明确的技术偏好 +- 已完成架构设计并希望为实施捕获决策 +- 正在处理具有既定模式的现有代码库 +- 注意到智能体在不同用户故事中做出不一致的决策 + +## 步骤 1：选择方法 + +**手动创建** — 当您确切知道要记录哪些规则时最佳 + +**架构后生成** — 最适合捕获解决方案制定过程中所做的决策 + +**为现有项目生成** — 最适合在现有代码库中发现模式 + +## 步骤 2：创建文件 + +### 选项 A：手动创建 + +在 `_bmad-output/project-context.md` 创建文件： + +```bash +mkdir -p _bmad-output +touch _bmad-output/project-context.md +``` + +添加技术栈和实现规则： + +```markdown +--- +project_name: 'MyProject' +user_name: 'YourName' +date: '2026-02-15' +sections_completed: ['technology_stack', 'critical_rules'] +--- + +# AI 智能体的项目上下文 + +## 技术栈与版本 + +- Node.js 20.x, TypeScript 5.3, React 18.2 +- 状态管理：Zustand +- 测试：Vitest, Playwright +- 样式：Tailwind CSS + +## 关键实现规则 + +**TypeScript：** +- 启用严格模式，不使用 `any` 类型 +- 公共 API 使用 `interface`，联合类型使用 `type` + +**代码组织：** +- 组件位于 `/src/components/` 并附带同位置测试 +- API 调用使用 `apiClient` 单例 — 绝不直接使用 fetch + +**测试：** +- 单元测试专注于业务逻辑 +- 集成测试使用 MSW 进行 API 模拟 +``` + +### 选项 B：架构后生成 + +在新的聊天中运行工作流程： + +```bash +/bmad-bmm-generate-project-context +``` + +工作流程扫描架构文档和项目文件，生成捕获所做决策的上下文文件。 + +### 选项 C：为现有项目生成 + +对于现有项目，运行： + +```bash +/bmad-bmm-generate-project-context +``` + +工作流程分析代码库以识别约定，然后生成上下文文件供您审查和完善。 + +## 步骤 3：验证内容 + +审查生成的文件并确保它捕获了： + +- 正确的技术版本 +- 实际约定（而非通用最佳实践） +- 防止常见错误的规则 +- 框架特定的模式 + +手动编辑以添加任何缺失内容或删除不准确之处。 + +## 您将获得 + +一个 `project-context.md` 文件，它： + +- 确保所有智能体遵循相同的约定 +- 防止在不同用户故事中做出不一致的决策 +- 为实施捕获架构决策 +- 作为项目模式和规则的参考 + +## 提示 + +:::tip[关注非显而易见的内容] +记录智能体可能遗漏的模式，例如"在每个公共类、函数和变量上使用 JSDoc 风格注释"，而不是像"使用有意义的变量名"这样的通用实践，因为 LLM 目前已经知道这些。 +::: + +:::tip[保持精简] +此文件由每个实施工作流程加载。长文件会浪费上下文。不要包含仅适用于狭窄范围或特定用户故事或功能的内容。 +::: + +:::tip[根据需要更新] +当模式发生变化时手动编辑，或在重大架构更改后重新生成。 +::: + +:::tip[适用于所有项目类型] +对于快速流程和完整的 BMad Method 项目同样有用。 +::: + +## 后续步骤 + +- [**项目上下文说明**](../explanation/project-context_cn.md) — 了解其工作原理 +- [**工作流程图**](../reference/workflow-map_cn.md) — 查看哪些工作流程加载项目上下文 + +--- +## 术语说明 + +- **agent**：智能体。在人工智能与编程文档中，指具备自主决策或执行能力的单元。 +- **workflow**：工作流程。指完成特定任务的一系列步骤或过程。 +- **codebase**：代码库。指项目的所有源代码和资源的集合。 +- **implementation**：实施。指将设计或架构转化为实际代码的过程。 +- **architecture**：架构。指系统的整体结构和设计。 +- **stack**：技术栈。指项目使用的技术组合，如编程语言、框架、工具等。 +- **convention**：约定。指团队或项目中遵循的编码规范和最佳实践。 +- **singleton**：单例。一种设计模式，确保类只有一个实例。 +- **co-located**：同位置。指相关文件（如测试文件）与主文件放在同一目录中。 +- **mocking**：模拟。在测试中用模拟对象替代真实对象的行为。 +- **context**：上下文。指程序运行时的环境信息或背景信息。 +- **LLM**：大语言模型。Large Language Model 的缩写，指大型语言模型。 diff --git a/docs_cn/how-to/quick-fixes_cn.md b/docs_cn/how-to/quick-fixes_cn.md new file mode 100644 index 000000000..89bc9d69d --- /dev/null +++ b/docs_cn/how-to/quick-fixes_cn.md @@ -0,0 +1,140 @@ +--- +title: "快速修复" +description: 如何进行快速修复和临时更改 +sidebar: + order: 5 +--- + +直接使用 **DEV 智能体**进行 bug 修复、重构或小型针对性更改，这些操作不需要完整的 BMad Method 或 Quick Flow。 + +## 何时使用此方法 + +- 原因明确且已知的 bug 修复 +- 包含在少数文件中的小型重构（重命名、提取、重组） +- 次要功能调整或配置更改 +- 探索性工作，以了解不熟悉的代码库 + +:::note[前置条件] +- 已安装 BMad Method（`npx bmad-method install`） +- AI 驱动的 IDE（Claude Code、Cursor 或类似工具） +::: + +## 选择你的方法 + +| 情况 | 智能体 | 原因 | +| --- | --- | --- | +| 修复特定 bug 或进行小型、范围明确的更改 | **DEV agent** | 直接进入实现，无需规划开销 | +| 更改涉及多个文件，或希望先有书面计划 | **Quick Flow Solo Dev** | 在实现前创建 quick-spec，使智能体与你的标准保持一致 | + +如果不确定，请从 DEV 智能体开始。如果更改范围扩大，你始终可以升级到 Quick Flow。 + +## 步骤 + +### 1. 加载 DEV 智能体 + +在 AI IDE 中启动一个**新的聊天**，并使用斜杠命令加载 DEV 智能体： + +```text +/bmad-agent-bmm-dev +``` + +这会将智能体的角色和能力加载到会话中。如果你决定需要 Quick Flow，请在新的聊天中加载 **Quick Flow Solo Dev** 智能体： + +```text +/bmad-agent-bmm-quick-flow-solo-dev +``` + +加载 Solo Dev 智能体后，描述你的更改并要求它创建一个 **quick-spec**。智能体会起草一个轻量级规范，捕获你想要更改的内容和方式。批准 quick-spec 后，告诉智能体开始 **Quick Flow 开发周期**——它将实现更改、运行测试并执行自我审查，所有这些都由你刚刚批准的规范指导。 + +:::tip[新聊天] +加载智能体时始终启动新的聊天会话。重用之前工作流的会话可能导致上下文冲突。 +::: + +### 2. 描述更改 + +用通俗语言告诉智能体你需要什么。具体说明问题，如果你知道相关代码的位置，也请说明。 + +:::note[示例提示词] +**Bug 修复** -- "修复允许空密码的登录验证 bug。验证逻辑位于 `src/auth/validate.ts`。" + +**重构** -- "重构 UserService 以使用 async/await 而不是回调。" + +**配置更改** -- "更新 CI 流水线以在运行之间缓存 node_modules。" + +**依赖更新** -- "将 express 依赖升级到最新的 v5 版本并修复任何破坏性更改。" +::: + +你不需要提供每个细节。智能体会读取相关的源文件，并在需要时提出澄清问题。 + +### 3. 让智能体工作 + +智能体将： + +- 读取并分析相关的源文件 +- 提出解决方案并解释其推理 +- 在受影响的文件中实现更改 +- 如果存在测试套件，则运行项目的测试套件 + +如果你的项目有测试，智能体会在进行更改后自动运行它们，并迭代直到测试通过。对于没有测试套件的项目，请手动验证更改（运行应用、访问端点、检查输出）。 + +### 4. 审查和验证 + +在提交之前，审查更改内容： + +- 通读 diff 以确认更改符合你的意图 +- 自己运行应用程序或测试以再次检查 +- 如果看起来有问题，告诉智能体需要修复什么——它可以在同一会话中迭代 + +满意后，使用描述修复的清晰消息提交更改。 + +:::caution[如果出现问题] +如果提交的更改导致意外问题，请使用 `git revert HEAD` 干净地撤销最后一次提交。然后启动与 DEV 智能体的新聊天以尝试不同的方法。 +::: + +## 学习你的代码库 + +DEV 智能体也适用于探索不熟悉的代码。在新的聊天中加载它并提出问题： + +:::note[示例提示词] +"解释此代码库中的身份验证系统是如何工作的。" + +"向我展示 API 层中的错误处理发生在哪里。" + +"`ProcessOrder` 函数的作用是什么，什么调用了它？" +::: + +使用智能体了解你的项目，理解组件如何连接，并在进行更改之前探索不熟悉的区域。 + +## 你将获得 + +- 已应用修复或重构的修改后的源文件 +- 通过的测试（如果你的项目有测试套件） +- 描述更改的干净提交 + +不会生成规划产物——这就是这种方法的意义所在。 + +## 何时升级到正式规划 + +在以下情况下考虑使用 [Quick Flow](../explanation/quick-flow_cn.md) 或完整的 BMad Method： + +- 更改影响多个系统或需要在许多文件中进行协调更新 +- 你不确定范围，需要规范来理清思路 +- 修复在工作过程中变得越来越复杂 +- 你需要为团队记录文档或架构决策 + +--- +## 术语说明 + +- **agent**：智能体。在人工智能与编程文档中，指具备自主决策或执行能力的单元。 +- **quick-spec**：快速规范。一种轻量级的规范文档，用于快速捕获和描述更改的内容和方式。 +- **Quick Flow**：快速流程。BMad Method 中的一种工作流程，用于快速实现小型更改。 +- **refactoring**：重构。在不改变代码外部行为的情况下改进其内部结构的过程。 +- **breaking changes**：破坏性更改。可能导致现有代码或功能不再正常工作的更改。 +- **test suite**：测试套件。一组用于验证软件功能的测试用例集合。 +- **CI pipeline**：CI 流水线。持续集成流水线，用于自动化构建、测试和部署代码。 +- **async/await**：异步编程语法。JavaScript/TypeScript 中用于处理异步操作的语法糖。 +- **callbacks**：回调函数。作为参数传递给其他函数并在适当时候被调用的函数。 +- **endpoint**：端点。API 中可访问的特定 URL 路径。 +- **diff**：差异。文件或代码更改前后的对比。 +- **commit**：提交。将更改保存到版本控制系统的操作。 +- **git revert HEAD**：Git 命令，用于撤销最后一次提交。 diff --git a/docs_cn/how-to/shard-large-documents_cn.md b/docs_cn/how-to/shard-large-documents_cn.md new file mode 100644 index 000000000..3f3385623 --- /dev/null +++ b/docs_cn/how-to/shard-large-documents_cn.md @@ -0,0 +1,86 @@ +--- +title: "文档分片指南" +description: 将大型 Markdown 文件拆分为更小的组织化文件，以更好地管理上下文 +sidebar: + order: 8 +--- + +如果需要将大型 Markdown 文件拆分为更小、组织良好的文件以更好地管理上下文，请使用 `shard-doc` 工具。 + +:::caution[已弃用] +不再推荐使用此方法，随着工作流程的更新以及大多数主要 LLM 和工具支持子进程，这很快将变得不再必要。 +::: + +## 何时使用 + +仅当你发现所选工具/模型组合无法在需要时加载和读取所有文档作为输入时，才使用此方法。 + +## 什么是文档分片？ + +文档分片根据二级标题（`## Heading`）将大型 Markdown 文件拆分为更小、组织良好的文件。 + +### 架构 + +```text +分片前： +_bmad-output/planning-artifacts/ +└── PRD.md（大型 50k token 文件） + +分片后： +_bmad-output/planning-artifacts/ +└── prd/ + ├── index.md # 带有描述的目录 + ├── overview.md # 第 1 节 + ├── user-requirements.md # 第 2 节 + ├── technical-requirements.md # 第 3 节 + └── ... # 其他章节 +``` + +## 步骤 + +### 1. 运行 Shard-Doc 工具 + +```bash +/bmad-shard-doc +``` + +### 2. 遵循交互式流程 + +```text +智能体：您想要分片哪个文档？ +用户：docs/PRD.md + +智能体：默认目标位置：docs/prd/ + 接受默认值？[y/n] +用户：y + +智能体：正在分片 PRD.md... + ✓ 已创建 12 个章节文件 + ✓ 已生成 index.md + ✓ 完成！ +``` + +## 工作流程发现机制 + +BMad 工作流程使用**双重发现系统**： + +1. **首先尝试完整文档** - 查找 `document-name.md` +2. **检查分片版本** - 查找 `document-name/index.md` +3. **优先级规则** - 如果两者都存在，完整文档优先 - 如果希望使用分片版本，请删除完整文档 + +## 工作流程支持 + +所有 BMM 工作流程都支持这两种格式： + +- 完整文档 +- 分片文档 +- 自动检测 +- 对用户透明 + +--- +## 术语说明 + +- **sharding**：分片。将大型文档或数据集拆分为更小、更易管理的部分的过程。 +- **token**：令牌。在自然语言处理和大型语言模型中，文本的基本单位，通常对应单词或字符的一部分。 +- **subprocesses**：子进程。由主进程创建的独立执行单元，可以并行运行以执行特定任务。 +- **agent**：智能体。在人工智能与编程文档中，指具备自主决策或执行能力的单元。 diff --git a/docs_cn/how-to/upgrade-to-v6_cn.md b/docs_cn/how-to/upgrade-to-v6_cn.md new file mode 100644 index 000000000..616a928f2 --- /dev/null +++ b/docs_cn/how-to/upgrade-to-v6_cn.md @@ -0,0 +1,120 @@ +--- +title: "如何升级到 v6" +description: 从 BMad v4 迁移到 v6 +sidebar: + order: 3 +--- + +使用 BMad 安装程序从 v4 升级到 v6，其中包括自动检测旧版安装和迁移辅助。 + +## 何时使用本指南 + +- 您已安装 BMad v4（`.bmad-method` 文件夹） +- 您希望迁移到新的 v6 架构 +- 您有需要保留的现有规划产物 + +:::note[前置条件] +- Node.js 20+ +- 现有的 BMad v4 安装 +::: + +## 步骤 + +### 1. 运行安装程序 + +按照[安装程序说明](./install-bmad_cn.md)操作。 + +### 2. 处理旧版安装 + +当检测到 v4 时，您可以： + +- 允许安装程序备份并删除 `.bmad-method` +- 退出并手动处理清理 + +如果您将 bmad method 文件夹命名为其他名称 - 您需要手动删除该文件夹。 + +### 3. 清理 IDE 命令 + +手动删除旧版 v4 IDE 命令 - 例如如果您使用 claude，查找任何以 bmad 开头的嵌套文件夹并删除它们： + +- `.claude/commands/BMad/agents` +- `.claude/commands/BMad/tasks` + +### 4. 迁移规划产物 + +**如果您有规划文档（Brief/PRD/UX/Architecture）：** + +将它们移动到 `_bmad-output/planning-artifacts/` 并使用描述性名称： + +- 在文件名中包含 `PRD` 用于 PRD 文档 +- 相应地包含 `brief`、`architecture` 或 `ux-design` +- 分片文档可以放在命名的子文件夹中 + +**如果您正在进行规划：** 考虑使用 v6 工作流重新开始。将现有文档作为输入——新的渐进式发现工作流配合网络搜索和 IDE 计划模式会产生更好的结果。 + +### 5. 迁移进行中的开发 + +如果您已创建或实现了故事： + +1. 完成 v6 安装 +2. 将 `epics.md` 或 `epics/epic*.md` 放入 `_bmad-output/planning-artifacts/` +3. 运行 Scrum Master 的 `sprint-planning` 工作流 +4. 告诉 SM 哪些史诗/故事已经完成 + +## 您将获得 + +**v6 统一结构：** + +```text +your-project/ +├── _bmad/ # 单一安装文件夹 +│ ├── _config/ # 您的自定义配置 +│ │ └── agents/ # 智能体自定义文件 +│ ├── core/ # 通用核心框架 +│ ├── bmm/ # BMad Method 模块 +│ ├── bmb/ # BMad Builder +│ └── cis/ # Creative Intelligence Suite +└── _bmad-output/ # 输出文件夹（v4 中为 doc 文件夹） +``` + +## 模块迁移 + +| v4 模块 | v6 状态 | +| ----------------------------- | ----------------------------------------- | +| `.bmad-2d-phaser-game-dev` | 已集成到 BMGD 模块 | +| `.bmad-2d-unity-game-dev` | 已集成到 BMGD 模块 | +| `.bmad-godot-game-dev` | 已集成到 BMGD 模块 | +| `.bmad-infrastructure-devops` | 已弃用 — 新的 DevOps 智能体即将推出 | +| `.bmad-creative-writing` | 未适配 — 新的 v6 模块即将推出 | + +## 主要变更 + +| 概念 | v4 | v6 | +| ------------ | --------------------------------------- | ------------------------------------ | +| **核心** | `_bmad-core` 实际上是 BMad Method | `_bmad/core/` 是通用框架 | +| **方法** | `_bmad-method` | `_bmad/bmm/` | +| **配置** | 直接修改文件 | 每个模块使用 `config.yaml` | +| **文档** | 需要设置分片或非分片 | 完全灵活，自动扫描 | + +--- +## 术语说明 + +- **agent**：智能体。在人工智能与编程文档中，指具备自主决策或执行能力的单元。 +- **epic**：史诗。在敏捷开发中，指大型的工作项，可分解为多个用户故事。 +- **story**：故事。在敏捷开发中，指用户故事，描述用户需求的功能单元。 +- **Scrum Master**：Scrum 主管。敏捷开发 Scrum 框架中的角色，负责促进团队流程和移除障碍。 +- **sprint-planning**：冲刺规划。Scrum 框架中的会议，用于确定下一个冲刺期间要完成的工作。 +- **sharded**：分片。将大型文档拆分为多个较小的文件以便于管理和处理。 +- **PRD**：产品需求文档（Product Requirements Document）。描述产品功能、需求和特性的文档。 +- **Brief**：简报。概述项目目标、范围和关键信息的文档。 +- **UX**：用户体验（User Experience）。用户在使用产品或服务过程中的整体感受和交互体验。 +- **Architecture**：架构。系统的结构设计，包括组件、模块及其相互关系。 +- **BMGD**：BMad Game Development。BMad 游戏开发模块。 +- **DevOps**：开发运维（Development Operations）。结合开发和运维的实践，旨在缩短系统开发生命周期。 +- **BMad Method**：BMad 方法。BMad 框架的核心方法论模块。 +- **BMad Builder**：BMad 构建器。BMad 框架的构建工具。 +- **Creative Intelligence Suite**：创意智能套件。BMad 框架中的创意工具集合。 +- **IDE**：集成开发环境（Integrated Development Environment）。提供代码编辑、调试等功能的软件开发工具。 +- **progressive discovery**：渐进式发现。逐步深入探索和理解需求的过程。 +- **web search**：网络搜索。通过互联网检索信息的能力。 +- **plan mode**：计划模式。IDE 中的一种工作模式，用于规划和设计任务。 diff --git a/docs_cn/index_cn.md b/docs_cn/index_cn.md new file mode 100644 index 000000000..b6d0f5e33 --- /dev/null +++ b/docs_cn/index_cn.md @@ -0,0 +1,69 @@ +--- +title: 欢迎使用 BMad 方法 +description: 具备专业智能体、引导式工作流和智能规划的 AI 驱动开发框架 +--- + +BMad 方法（**B**reakthrough **M**ethod of **A**gile AI **D**riven Development，敏捷 AI 驱动开发的突破性方法）是 BMad 方法生态系统中的一个 AI 驱动开发框架模块，帮助您完成从构思和规划到智能体实现的整个软件开发过程。它提供专业的 AI 智能体、引导式工作流和智能规划，能够根据您项目的复杂度进行调整，无论是修复错误还是构建企业平台。 + +如果您熟悉使用 Claude、Cursor 或 GitHub Copilot 等 AI 编码助手，就可以开始使用了。 + +:::note[🚀 V6 已发布，我们才刚刚起步！] +技能架构、BMad Builder v1、开发循环自动化以及更多功能正在开发中。**[查看路线图 →](/roadmap/)** +::: + +## 新手入门？从教程开始 + +理解 BMad 的最快方式是亲自尝试。 + +- **[BMad 入门指南](./tutorials/getting-started_cn.md)** — 安装并了解 BMad 的工作原理 +- **[工作流地图](./reference/workflow-map_cn.md)** — BMM 阶段、工作流和上下文管理的可视化概览 + +:::tip[只想直接上手？] +安装 BMad 并运行 `/bmad-help` — 它会根据您的项目和已安装的模块引导您完成所有操作。 +::: + +## 如何使用本文档 + +本文档根据您的目标分为四个部分： + +| 部分 | 用途 | +| ----------------- | ---------------------------------------------------------------------------------------------------------- | +| **教程** | 以学习为导向。通过分步指南引导您构建内容。如果您是新手，请从这里开始。 | +| **操作指南** | 以任务为导向。解决特定问题的实用指南。"如何自定义智能体？"等内容位于此处。 | +| **说明** | 以理解为导向。深入探讨概念和架构。当您想知道*为什么*时阅读。 | +| **参考** | 以信息为导向。智能体、工作流和配置的技术规范。 | + +## 扩展和自定义 + +想要使用自己的智能体、工作流或模块来扩展 BMad 吗？**[BMad Builder](https://bmad-builder-docs.bmad-method.org/)** 提供了创建自定义扩展的框架和工具，无论是为 BMad 添加新功能还是从头开始构建全新的模块。 + +## 您需要什么 + +BMad 可与任何支持自定义系统提示词或项目上下文的 AI 编码助手配合使用。热门选项包括： + +- **[Claude Code](https://code.claude.com)** — Anthropic 的 CLI 工具（推荐） +- **[Cursor](https://cursor.sh)** — AI 优先的代码编辑器 +- **[Codex CLI](https://github.com/openai/codex)** — OpenAI 的终端编码智能体 + +您应该熟悉版本控制、项目结构和敏捷工作流等基本软件开发概念。无需具备 BMad 风格智能体系统的先验经验——这正是本文档的作用。 + +## 加入社区 + +获取帮助、分享您的构建内容，或为 BMad 做出贡献： + +- **[Discord](https://discord.gg/gk8jAdXWmj)** — 与其他 BMad 用户聊天、提问、分享想法 +- **[GitHub](https://github.com/bmad-code-org/BMAD-METHOD)** — 源代码、问题和贡献 +- **[YouTube](https://www.youtube.com/@BMadCode)** — 视频教程和演练 + +## 下一步 + +准备开始了吗？**[BMad 入门指南](./tutorials/getting-started_cn.md)** 并构建您的第一个项目。 + +--- +## 术语说明 + +- **agent**：智能体。在人工智能与编程文档中，指具备自主决策或执行能力的单元。 +- **AI-driven**：AI 驱动。指由人工智能技术主导或驱动的系统或方法。 +- **workflow**：工作流。指一系列有序的任务或步骤，用于完成特定目标。 +- **prompt**：提示词。指输入给 AI 模型的指令或问题，用于引导其生成特定输出。 +- **context**：上下文。指在特定场景下理解信息所需的背景信息或环境。 diff --git a/docs_cn/reference/agents_cn.md b/docs_cn/reference/agents_cn.md new file mode 100644 index 000000000..ed87652d9 --- /dev/null +++ b/docs_cn/reference/agents_cn.md @@ -0,0 +1,41 @@ +--- +title: 智能体 +description: 默认 BMM 智能体及其菜单触发器和主要工作流 +sidebar: + order: 2 +--- + +## 默认智能体 + +本页列出了随 BMad Method 安装的默认 BMM（Agile 套件）智能体，以及它们的菜单触发器和主要工作流。 + +## 注意事项 + +- 触发器是显示在每个智能体菜单中的简短菜单代码（例如 `CP`）和模糊匹配。 +- 斜杠命令是单独生成的。斜杠命令列表及其定义位置请参阅[命令](./commands.md)。 +- QA（Quinn）是 BMM 中的轻量级测试自动化智能体。完整的测试架构师（TEA）位于其独立模块中。 + +| 智能体 | 触发 | 主要工作流 | +| --------------------------- | --------------------------------- | --------------------------------------------------------------------------------------------------- | +| Analyst (Mary) | `BP`, `RS`, `CB`, `DP` | 头脑风暴项目、研究、创建简报、文档化项目 | +| Product Manager (John) | `CP`, `VP`, `EP`, `CE`, `IR`, `CC` | 创建/验证/编辑 PRD、创建史诗和用户故事、实施就绪、纠正方向 | +| Architect (Winston) | `CA`, `IR` | 创建架构、实施就绪 | +| Scrum Master (Bob) | `SP`, `CS`, `ER`, `CC` | 冲刺规划、创建用户故事、史诗回顾、纠正方向 | +| Developer (Amelia) | `DS`, `CR` | 开发用户故事、代码评审 | +| QA Engineer (Quinn) | `QA` | 自动化（为现有功能生成测试） | +| Quick Flow Solo Dev (Barry) | `QS`, `QD`, `CR` | 快速规格、快速开发、代码评审 | +| UX Designer (Sally) | `CU` | 创建 UX 设计 | +| Technical Writer (Paige) | `DP`, `WD`, `US`, `MG`, `VD`, `EC` | 文档化项目、撰写文档、更新标准、Mermaid 生成、验证文档、解释概念 | + +--- +## 术语说明 + +- **agent**：智能体。在人工智能与编程文档中，指具备自主决策或执行能力的单元。 +- **BMM**：BMad Method 中的默认智能体套件，涵盖敏捷开发流程中的各类角色。 +- **PRD**：产品需求文档（Product Requirements Document）。 +- **Epic**：史诗。大型功能或需求集合，可拆分为多个用户故事。 +- **Story**：用户故事。描述用户需求的简短陈述。 +- **Sprint**：冲刺。敏捷开发中的固定时间周期迭代。 +- **QA**：质量保证（Quality Assurance）。 +- **TEA**：测试架构师（Test Architect）。 +- **Mermaid**：一种用于生成图表和流程图的文本语法。 diff --git a/docs_cn/reference/commands_cn.md b/docs_cn/reference/commands_cn.md new file mode 100644 index 000000000..8f35371cd --- /dev/null +++ b/docs_cn/reference/commands_cn.md @@ -0,0 +1,166 @@ +--- +title: 命令 +description: BMad 斜杠命令参考——它们是什么、如何工作以及在哪里找到它们。 +sidebar: + order: 3 +--- + +斜杠命令是预构建的提示词，用于在 IDE 中加载智能体、运行工作流或执行任务。BMad 安装程序在安装时根据已安装的模块生成这些命令。如果您后续添加、删除或更改模块，请重新运行安装程序以保持命令同步（参见[故障排除](#troubleshooting)）。 + +## 命令与智能体菜单触发器 + +BMad 提供两种开始工作的方式，它们服务于不同的目的。 + +| 机制 | 调用方式 | 发生什么 | +| --- | --- | --- | +| **斜杠命令** | 在 IDE 中输入 `/bmad-...` | 直接加载智能体、运行工作流或执行任务 | +| **智能体菜单触发器** | 先加载智能体，然后输入简短代码（例如 `DS`） | 智能体解释代码并启动匹配的工作流，同时保持角色设定 | + +智能体菜单触发器需要活动的智能体会话。当您知道要使用哪个工作流时，使用斜杠命令。当您已经与智能体一起工作并希望在不离开对话的情况下切换任务时，使用触发器。 + +## 命令如何生成 + +当您运行 `npx bmad-method install` 时，安装程序会读取每个选定模块的清单，并为每个智能体、工作流、任务和工具编写一个命令文件。每个文件都是一个简短的 Markdown 提示词，指示 AI 加载相应的源文件并遵循其指令。 + +安装程序为每种命令类型使用模板： + +| 命令类型 | 生成的文件的作用 | +| --- | --- | +| **智能体启动器** | 加载智能体角色文件，激活其菜单，并保持角色设定 | +| **工作流命令** | 加载工作流引擎（`workflow.xml`）并传递工作流配置 | +| **任务命令** | 加载独立任务文件并遵循其指令 | +| **工具命令** | 加载独立工具文件并遵循其指令 | + +:::note[重新运行安装程序] +如果您添加或删除模块，请再次运行安装程序。它会重新生成所有命令文件以匹配您当前的模块选择。 +::: + +## 命令文件的位置 + +安装程序将命令文件写入项目内 IDE 特定的目录中。确切路径取决于您在安装期间选择的 IDE。 + +| IDE / CLI | 命令目录 | +| --- | --- | +| Claude Code | `.claude/commands/` | +| Cursor | `.cursor/commands/` | +| Windsurf | `.windsurf/workflows/` | +| 其他 IDE | 请参阅安装程序输出中的目标路径 | + +所有 IDE 都在其命令目录中接收一组扁平的命令文件。例如，Claude Code 安装看起来像： + +```text +.claude/commands/ +├── bmad-agent-bmm-dev.md +├── bmad-agent-bmm-pm.md +├── bmad-bmm-create-prd.md +├── bmad-editorial-review-prose.md +├── bmad-help.md +└── ... +``` + +文件名决定了 IDE 中的斜杠命令名称。例如，文件 `bmad-agent-bmm-dev.md` 注册命令 `/bmad-agent-bmm-dev`。 + +## 如何发现您的命令 + +在 IDE 中输入 `/bmad` 并使用自动完成功能浏览可用命令。 + +运行 `/bmad-help` 获取关于下一步的上下文感知指导。 + +:::tip[快速发现] +项目中生成的命令文件夹是权威列表。在文件资源管理器中打开它们以查看每个命令及其描述。 +::: + +## 命令类别 + +### 智能体命令 + +智能体命令加载具有定义角色、沟通风格和工作流菜单的专业化 AI 角色。加载后，智能体保持角色设定并响应菜单触发器。 + +| 示例命令 | 智能体 | 角色 | +| --- | --- | --- | +| `/bmad-agent-bmm-dev` | Amelia（开发者） | 严格按照规范实现故事 | +| `/bmad-agent-bmm-pm` | John（产品经理） | 创建和验证 PRD | +| `/bmad-agent-bmm-architect` | Winston（架构师） | 设计系统架构 | +| `/bmad-agent-bmm-sm` | Bob（Scrum Master） | 管理冲刺和故事 | + +参见[智能体](./agents_cn.md)获取默认智能体及其触发器的完整列表。 + +### 工作流命令 + +工作流命令运行结构化的多步骤过程，而无需先加载智能体角色。它们加载工作流引擎并传递特定的工作流配置。 + +| 示例命令 | 目的 | +| --- | --- | +| `/bmad-bmm-create-prd` | 创建产品需求文档 | +| `/bmad-bmm-create-architecture` | 设计系统架构 | +| `/bmad-bmm-dev-story` | 实现故事 | +| `/bmad-bmm-code-review` | 运行代码审查 | +| `/bmad-bmm-quick-spec` | 定义临时更改（快速流程） | + +参见[工作流地图](./workflow-map_cn.md)获取按阶段组织的完整工作流参考。 + +### 任务和工具命令 + +任务和工具是独立的操作，不需要智能体或工作流上下文。 + +#### BMad-Help：您的智能向导 + +**`/bmad-help`** 是您发现下一步操作的主要界面。它不仅仅是一个查找工具——它是一个智能助手，可以： + +- **检查您的项目**以查看已经完成的工作 +- **理解自然语言查询**——用简单的英语提问 +- **根据已安装的模块而变化**——根据您拥有的内容显示选项 +- **在工作流后自动调用**——每个工作流都以清晰的下一步结束 +- **推荐第一个必需任务**——无需猜测从哪里开始 + +**示例：** + +``` +/bmad-help +/bmad-help 我有一个 SaaS 想法并且知道所有功能。我应该从哪里开始？ +/bmad-help 我在 UX 设计方面有哪些选择？ +/bmad-help 我在 PRD 工作流上卡住了 +``` + +#### 其他任务和工具 + +| 示例命令 | 目的 | +| --- | --- | +| `/bmad-shard-doc` | 将大型 Markdown 文件拆分为较小的部分 | +| `/bmad-index-docs` | 索引项目文档 | +| `/bmad-editorial-review-prose` | 审查文档散文质量 | + +## 命名约定 + +命令名称遵循可预测的模式。 + +| 模式 | 含义 | 示例 | +| --- | --- | --- | +| `bmad-agent--` | 智能体启动器 | `bmad-agent-bmm-dev` | +| `bmad--` | 工作流命令 | `bmad-bmm-create-prd` | +| `bmad-` | 核心任务或工具 | `bmad-help` | + +模块代码：`bmm`（敏捷套件）、`bmb`（构建器）、`tea`（测试架构师）、`cis`（创意智能）、`gds`（游戏开发工作室）。参见[模块](./modules_cn.md)获取描述。 + +## 故障排除 + +**安装后命令未出现。** 重启您的 IDE 或重新加载窗口。某些 IDE 会缓存命令列表，需要刷新才能获取新文件。 + +**预期的命令缺失。** 安装程序仅为您选择的模块生成命令。再次运行 `npx bmad-method install` 并验证您的模块选择。检查命令文件是否存在于预期目录中。 + +**已删除模块的命令仍然出现。** 安装程序不会自动删除旧的命令文件。从 IDE 的命令目录中删除过时的文件，或删除整个命令目录并重新运行安装程序以获取一组干净的命令。 + +--- +## 术语说明 + +- **slash command**：斜杠命令。以 `/` 开头的命令，用于在 IDE 中快速执行特定操作。 +- **agent**：智能体。在人工智能与编程文档中，指具备自主决策或执行能力的单元。 +- **workflow**：工作流。一系列结构化的步骤，用于完成特定任务或流程。 +- **IDE**：集成开发环境。用于软件开发的综合应用程序，提供代码编辑、调试、构建等功能。 +- **persona**：角色设定。为智能体定义的特定角色、性格和行为方式。 +- **trigger**：触发器。用于启动特定操作或流程的机制。 +- **manifest**：清单。描述模块或组件的元数据文件。 +- **installer**：安装程序。用于安装和配置软件的工具。 +- **PRD**：产品需求文档。描述产品功能、需求和规范的文档。 +- **SaaS**：软件即服务。通过互联网提供软件服务的模式。 +- **UX**：用户体验。用户在使用产品或服务过程中的整体感受和交互体验。 diff --git a/docs_cn/reference/modules_cn.md b/docs_cn/reference/modules_cn.md new file mode 100644 index 000000000..04162d657 --- /dev/null +++ b/docs_cn/reference/modules_cn.md @@ -0,0 +1,94 @@ +--- +title: 官方模块 +description: 用于构建自定义智能体、创意智能、游戏开发和测试的附加模块 +sidebar: + order: 4 +--- + +BMad 通过您在安装期间选择的官方模块进行扩展。这些附加模块为内置核心和 BMM（敏捷套件）之外的特定领域提供专门的智能体、工作流和任务。 + +:::tip[安装模块] +运行 `npx bmad-method install` 并选择您需要的模块。安装程序会自动处理下载、配置和 IDE 集成。 +::: + +## BMad Builder + +在引导式协助下创建自定义智能体、工作流和特定领域的模块。BMad Builder 是用于扩展框架本身的元模块。 + +- **代码：** `bmb` +- **npm：** [`bmad-builder`](https://www.npmjs.com/package/bmad-builder) +- **GitHub：** [bmad-code-org/bmad-builder](https://github.com/bmad-code-org/bmad-builder) + +**提供：** + +- 智能体构建器 —— 创建具有自定义专业知识和工具访问权限的专用 AI 智能体 +- 工作流构建器 —— 设计包含步骤和决策点的结构化流程 +- 模块构建器 —— 将智能体和工作流打包为可共享、可发布的模块 +- 交互式设置，支持 YAML 配置和 npm 发布 + +## 创意智能套件 + +用于早期开发阶段的结构化创意、构思和创新的 AI 驱动工具。该套件提供多个智能体，利用经过验证的框架促进头脑风暴、设计思维和问题解决。 + +- **代码：** `cis` +- **npm：** [`bmad-creative-intelligence-suite`](https://www.npmjs.com/package/bmad-creative-intelligence-suite) +- **GitHub：** [bmad-code-org/bmad-module-creative-intelligence-suite](https://github.com/bmad-code-org/bmad-module-creative-intelligence-suite) + +**提供：** + +- 创新策略师、设计思维教练和头脑风暴教练智能体 +- 问题解决者和创意问题解决者，用于系统性和横向思维 +- 故事讲述者和演示大师，用于叙事和推介 +- 构思框架，包括 SCAMPER、逆向头脑风暴和问题重构 + +## 游戏开发工作室 + +适用于 Unity、Unreal、Godot 和自定义引擎的结构化游戏开发工作流。通过 Quick Flow 支持快速原型制作，并通过史诗驱动的冲刺支持全面规模的生产。 + +- **代码：** `gds` +- **npm：** [`bmad-game-dev-studio`](https://www.npmjs.com/package/bmad-game-dev-studio) +- **GitHub：** [bmad-code-org/bmad-module-game-dev-studio](https://github.com/bmad-code-org/bmad-module-game-dev-studio) + +**提供：** + +- 游戏设计文档（GDD）生成工作流 +- 用于快速原型制作的 Quick Dev 模式 +- 针对角色、对话和世界构建的叙事设计支持 +- 覆盖 21+ 种游戏类型，并提供特定引擎的架构指导 + +## 测试架构师（TEA） + +通过专家智能体和九个结构化工作流提供企业级测试策略、自动化指导和发布门控决策。TEA 远超内置 QA 智能体，提供基于风险的优先级排序和需求可追溯性。 + +- **代码：** `tea` +- **npm：** [`bmad-method-test-architecture-enterprise`](https://www.npmjs.com/package/bmad-method-test-architecture-enterprise) +- **GitHub：** [bmad-code-org/bmad-method-test-architecture-enterprise](https://github.com/bmad-code-org/bmad-method-test-architecture-enterprise) + +**提供：** + +- Murat 智能体（主测试架构师和质量顾问） +- 用于测试设计、ATDD、自动化、测试审查和可追溯性的工作流 +- NFR 评估、CI 设置和框架脚手架 +- P0-P3 优先级排序，可选 Playwright Utils 和 MCP 集成 + +## 社区模块 + +社区模块和模块市场即将推出。请查看 [BMad GitHub 组织](https://github.com/bmad-code-org) 获取最新更新。 + +--- +## 术语说明 + +- **agent**：智能体。在人工智能与编程文档中，指具备自主决策或执行能力的单元。 +- **workflow**：工作流。指一系列有序的任务或步骤，用于完成特定的业务流程或开发流程。 +- **module**：模块。指可独立开发、测试和部署的软件单元，用于扩展系统功能。 +- **meta-module**：元模块。指用于创建或扩展其他模块的模块，是模块的模块。 +- **ATDD**：验收测试驱动开发（Acceptance Test-Driven Development）。一种敏捷开发实践，在编写代码之前先编写验收测试。 +- **NFR**：非功能性需求（Non-Functional Requirement）。指系统在性能、安全性、可维护性等方面的质量属性要求。 +- **CI**：持续集成（Continuous Integration）。一种软件开发实践，频繁地将代码集成到主干分支，并进行自动化测试。 +- **MCP**：模型上下文协议（Model Context Protocol）。一种用于在 AI 模型与外部工具或服务之间进行通信的协议。 +- **SCAMPER**：一种创意思维技巧，包含替代、组合、调整、修改、其他用途、消除和重组七个维度。 +- **GDD**：游戏设计文档（Game Design Document）。用于描述游戏设计理念、玩法、机制等内容的详细文档。 +- **P0-P3**：优先级分级。P0 为最高优先级（关键），P3 为最低优先级（可选）。 +- **sprint**：冲刺。敏捷开发中的固定时间周期，通常为 1-4 周，用于完成预定的工作。 +- **epic**：史诗。敏捷开发中的大型工作项，可分解为多个用户故事或任务。 +- **Quick Flow**：快速流程。一种用于快速原型开发的工作流模式。 diff --git a/docs_cn/reference/testing_cn.md b/docs_cn/reference/testing_cn.md new file mode 100644 index 000000000..013e277e6 --- /dev/null +++ b/docs_cn/reference/testing_cn.md @@ -0,0 +1,122 @@ +--- +title: 测试选项 +description: 比较内置 QA 智能体（Quinn）与测试架构师（TEA）模块的测试自动化。 +sidebar: + order: 5 +--- + +BMad 提供两条测试路径：用于快速生成测试的内置 QA 智能体，以及用于企业级测试策略的可安装测试架构师模块。 + +## 应该使用哪一个？ + +| 因素 | Quinn（内置 QA） | TEA 模块 | +| --- | --- | --- | +| **最适合** | 中小型项目、快速覆盖 | 大型项目、受监管或复杂领域 | +| **设置** | 无需安装——包含在 BMM 中 | 通过 `npx bmad-method install` 单独安装 | +| **方法** | 快速生成测试，稍后迭代 | 先规划，再生成并保持可追溯性 | +| **测试类型** | API 和 E2E 测试 | API、E2E、ATDD、NFR 等 | +| **策略** | 快乐路径 + 关键边界情况 | 基于风险的优先级排序（P0-P3） | +| **工作流数量** | 1（Automate） | 9（设计、ATDD、自动化、审查、可追溯性等） | + +:::tip[从 Quinn 开始] +大多数项目应从 Quinn 开始。如果后续需要测试策略、质量门控或需求可追溯性，可并行安装 TEA。 +::: + +## 内置 QA 智能体（Quinn） + +Quinn 是 BMM（敏捷套件）模块中的内置 QA 智能体。它使用项目现有的测试框架快速生成可运行的测试——无需配置或额外安装。 + +**触发方式：** `QA` 或 `bmad-bmm-qa-automate` + +### Quinn 的功能 + +Quinn 运行单个工作流（Automate），包含五个步骤： + +1. **检测测试框架**——扫描 `package.json` 和现有测试文件以识别框架（Jest、Vitest、Playwright、Cypress 或任何标准运行器）。如果不存在，则分析项目技术栈并推荐一个。 +2. **识别功能**——询问要测试的内容或自动发现代码库中的功能。 +3. **生成 API 测试**——覆盖状态码、响应结构、快乐路径和 1-2 个错误情况。 +4. **生成 E2E 测试**——使用语义定位器和可见结果断言覆盖用户工作流。 +5. **运行并验证**——执行生成的测试并立即修复失败。 + +Quinn 会生成测试摘要，保存到项目的实现产物文件夹中。 + +### 测试模式 + +生成的测试遵循"简单且可维护"的理念： + +- **仅使用标准框架 API**——不使用外部工具或自定义抽象 +- UI 测试使用**语义定位器**（角色、标签、文本而非 CSS 选择器） +- **独立测试**，无顺序依赖 +- **无硬编码等待或休眠** +- **清晰的描述**，可作为功能文档阅读 + +:::note[范围] +Quinn 仅生成测试。如需代码审查和故事验证，请改用代码审查工作流（`CR`）。 +::: + +### 何时使用 Quinn + +- 为新功能或现有功能快速实现测试覆盖 +- 无需高级设置的初学者友好型测试自动化 +- 任何开发者都能阅读和维护的标准测试模式 +- 不需要全面测试策略的中小型项目 + +## 测试架构师（TEA）模块 + +TEA 是一个独立模块，提供专家智能体（Murat）和九个结构化工作流，用于企业级测试。它超越了测试生成，涵盖测试策略、基于风险的规划、质量门控和需求可追溯性。 + +- **文档：** [TEA 模块文档](https://bmad-code-org.github.io/bmad-method-test-architecture-enterprise/) +- **安装：** `npx bmad-method install` 并选择 TEA 模块 +- **npm：** [`bmad-method-test-architecture-enterprise`](https://www.npmjs.com/package/bmad-method-test-architecture-enterprise) + +### TEA 提供的功能 + +| Workflow | Purpose | +| --- | --- | +| Test Design | 创建与需求关联的全面测试策略 | +| ATDD | 基于干系人标准的验收测试驱动开发 | +| Automate | 使用高级模式和工具生成测试 | +| Test Review | 根据策略验证测试质量和覆盖范围 | +| Traceability | 将测试映射回需求，用于审计和合规 | +| NFR Assessment | 评估非功能性需求（性能、安全性） | +| CI Setup | 在持续集成管道中配置测试执行 | +| Framework Scaffolding | 设置测试基础设施和项目结构 | +| Release Gate | 基于数据做出发布/不发布决策 | + +TEA 还支持 P0-P3 基于风险的优先级排序，以及与 Playwright Utils 和 MCP 工具的可选集成。 + +### 何时使用 TEA + +- 需要需求可追溯性或合规文档的项目 +- 需要在多个功能间进行基于风险的测试优先级排序的团队 +- 发布前具有正式质量门控的企业环境 +- 在编写测试前必须规划测试策略的复杂领域 +- 已超出 Quinn 单一工作流方法的项目 + +## 测试如何融入工作流 + +Quinn 的 Automate 工作流出现在 BMad 方法工作流图的第 4 阶段（实现）。典型序列： + +1. 使用开发工作流（`DS`）实现一个故事 +2. 使用 Quinn（`QA`）或 TEA 的 Automate 工作流生成测试 +3. 使用代码审查（`CR`）验证实现 + +Quinn 直接从源代码工作，无需加载规划文档（PRD、架构）。TEA 工作流可以与上游规划产物集成以实现可追溯性。 + +有关测试在整体流程中的位置，请参阅[工作流图](./workflow-map_cn.md)。 + +--- +## 术语说明 + +- **QA (Quality Assurance)**：质量保证。确保产品或服务满足质量要求的过程。 +- **E2E (End-to-End)**：端到端。测试整个系统从开始到结束的完整流程。 +- **ATDD (Acceptance Test-Driven Development)**：验收测试驱动开发。在编码前先编写验收测试的开发方法。 +- **NFR (Non-Functional Requirement)**：非功能性需求。描述系统如何运行而非做什么的需求，如性能、安全性等。 +- **P0-P3**：优先级级别。P0 为最高优先级，P3 为最低优先级，用于基于风险的测试排序。 +- **Happy path**：快乐路径。测试系统在理想条件下的正常工作流程。 +- **Semantic locators**：语义定位器。使用有意义的元素属性（如角色、标签、文本）而非 CSS 选择器来定位 UI 元素。 +- **Quality gates**：质量门控。在开发流程中设置的检查点，用于确保质量标准。 +- **Requirements traceability**：需求可追溯性。能够追踪需求从设计到测试再到实现的完整链路。 +- **agent**：智能体。在人工智能与编程文档中，指具备自主决策或执行能力的单元。 +- **CI (Continuous Integration)**：持续集成。频繁地将代码集成到主干，并自动运行测试的实践。 +- **MCP (Model Context Protocol)**：模型上下文协议。用于在 AI 模型与外部工具之间通信的协议。 diff --git a/docs_cn/reference/workflow-map_cn.md b/docs_cn/reference/workflow-map_cn.md new file mode 100644 index 000000000..f90799a70 --- /dev/null +++ b/docs_cn/reference/workflow-map_cn.md @@ -0,0 +1,104 @@ +--- +title: "工作流程图" +description: BMad Method 工作流程阶段与输出的可视化参考 +sidebar: + order: 1 +--- + +BMad Method（BMM）是 BMad 生态系统中的一个模块，旨在遵循上下文工程与规划的最佳实践。AI 智能体在清晰、结构化的上下文中表现最佳。BMM 系统在 4 个不同阶段中逐步构建该上下文——每个阶段以及每个阶段内的多个可选工作流程都会生成文档，这些文档为下一阶段提供信息，因此智能体始终知道要构建什么以及为什么。 + +其基本原理和概念来自敏捷方法论，这些方法论在整个行业中被广泛用作思维框架，并取得了巨大成功。 + +如果您在任何时候不确定该做什么，`/bmad-help` 命令将帮助您保持正轨或了解下一步该做什么。您也可以随时参考此文档以获取参考信息——但如果您已经安装了 BMad Method，`/bmad-help` 是完全交互式的，速度要快得多。此外，如果您正在使用扩展了 BMad Method 或添加了其他互补非扩展模块的不同模块——`/bmad-help` 会不断演进以了解所有可用内容，从而为您提供最佳即时建议。 + +最后的重要说明：以下每个工作流程都可以通过斜杠命令直接使用您选择的工具运行，或者先加载智能体，然后使用智能体菜单中的条目来运行。 + + + +

+ 在新标签页中打开图表 ↗ +

+ +## 阶段 1：分析（可选） + +在投入规划之前探索问题空间并验证想法。 + +| 工作流程 | 目的 | 产出 | +| ------------------------------- | -------------------------------------------------------------------------- | ------------------------- | +| `bmad-brainstorming` | 在头脑风暴教练的引导协助下进行项目想法头脑风暴 | `brainstorming-report.md` | +| `bmad-bmm-research` | 验证市场、技术或领域假设 | 研究发现 | +| `bmad-bmm-create-product-brief` | 捕捉战略愿景 | `product-brief.md` | + +## 阶段 2：规划 + +定义要构建什么以及为谁构建。 + +| 工作流程 | 目的 | 产出 | +| --------------------------- | ---------------------------------------- | ------------ | +| `bmad-bmm-create-prd` | 定义需求（FRs/NFRs） | `PRD.md` | +| `bmad-bmm-create-ux-design` | 设计用户体验（当 UX 重要时） | `ux-spec.md` | + +## 阶段 3：解决方案设计 + +决定如何构建它并将工作分解为故事。 + +| 工作流程 | 目的 | 产出 | +| ----------------------------------------- | ------------------------------------------ | --------------------------- | +| `bmad-bmm-create-architecture` | 明确技术决策 | 包含 ADR 的 `architecture.md` | +| `bmad-bmm-create-epics-and-stories` | 将需求分解为可实施的工作 | 包含故事的 Epic 文件 | +| `bmad-bmm-check-implementation-readiness` | 实施前的关卡检查 | PASS/CONCERNS/FAIL 决策 | + +## 阶段 4：实施 + +逐个故事地构建它。即将推出完整的阶段 4 自动化！ + +| 工作流程 | 目的 | 产出 | +| -------------------------- | ------------------------------------------------------------------------ | -------------------------------- | +| `bmad-bmm-sprint-planning` | 初始化跟踪（每个项目一次，以排序开发周期） | `sprint-status.yaml` | +| `bmad-bmm-create-story` | 准备下一个故事以供实施 | `story-[slug].md` | +| `bmad-bmm-dev-story` | 实施该故事 | 工作代码 + 测试 | +| `bmad-bmm-code-review` | 验证实施质量 | 批准或请求更改 | +| `bmad-bmm-correct-course` | 处理冲刺中的重大变更 | 更新的计划或重新路由 | +| `bmad-bmm-automate` | 为现有功能生成测试 - 在完整的 epic 完成后使用 | 端到端 UI 专注测试套件 | +| `bmad-bmm-retrospective` | 在 epic 完成后回顾 | 经验教训 | + +## 快速流程（并行轨道） + +对于小型、易于理解的工作，跳过阶段 1-3。 + +| 工作流程 | 目的 | 产出 | +| --------------------- | ------------------------------------------ | --------------------------------------------- | +| `bmad-bmm-quick-spec` | 定义临时变更 | `tech-spec.md`（小型变更的故事文件） | +| `bmad-bmm-quick-dev` | 根据规范或直接指令实施 | 工作代码 + 测试 | + +## 上下文管理 + +每个文档都成为下一阶段的上下文。PRD 告诉架构师哪些约束很重要。架构告诉开发智能体要遵循哪些模式。故事文件为实施提供专注、完整的上下文。没有这种结构，智能体会做出不一致的决策。 + +### 项目上下文 + +:::tip[推荐] +创建 `project-context.md` 以确保 AI 智能体遵循您项目的规则和偏好。该文件就像您项目的宪法——它指导所有工作流程中的实施决策。这个可选文件可以在架构创建结束时生成，或者在现有项目中也可以生成它，以捕捉与当前约定保持一致的重要内容。 +::: + +**如何创建它：** + +- **手动** — 使用您的技术栈和实施规则创建 `_bmad-output/project-context.md` +- **生成它** — 运行 `/bmad-bmm-generate-project-context` 以从您的架构或代码库自动生成 + +[**了解更多关于 project-context.md**](../explanation/project-context_cn.md) + +--- +## 术语说明 + +- **agent**：智能体。在人工智能与编程文档中，指具备自主决策或执行能力的单元。 +- **BMad Method (BMM)**：BMad 方法。BMad 生态系统中的一个模块，用于上下文工程与规划。 +- **FRs/NFRs**：功能需求/非功能需求。Functional Requirements/Non-Functional Requirements 的缩写。 +- **PRD**：产品需求文档。Product Requirements Document 的缩写。 +- **UX**：用户体验。User Experience 的缩写。 +- **ADR**：架构决策记录。Architecture Decision Record 的缩写。 +- **Epic**：史诗。大型功能或用户故事的集合，通常需要多个冲刺才能完成。 +- **Story**：用户故事。描述用户需求的简短陈述。 +- **Sprint**：冲刺。敏捷开发中的固定时间周期，用于完成预定的工作。 +- **Slug**：短标识符。URL 友好的标识符，通常用于文件命名。 +- **Context**：上下文。为 AI 智能体提供的环境信息和背景资料。 diff --git a/docs_cn/roadmap_cn.mdx b/docs_cn/roadmap_cn.mdx new file mode 100644 index 000000000..2bc89b7e2 --- /dev/null +++ b/docs_cn/roadmap_cn.mdx @@ -0,0 +1,152 @@ +--- +title: 路线图 +description: BMad 的下一步计划——功能、改进与社区贡献 +--- + +# BMad 方法：公开路线图 + +BMad 方法、BMad 方法模块（BMM）和 BMad 构建器（BMB）正在持续演进。以下是我们正在开展的工作以及即将推出的内容。 + +
+ +

进行中

+ +
+
+ 🧩 +

通用技能架构

+

一个技能，任意平台。一次编写，随处运行。

+
+
+ 🏗️ +

BMad 构建器 v1

+

打造生产级 AI 智能体与工作流，内置评估、团队协作与优雅降级。

+
+
+ 🧠 +

项目上下文系统

+

AI 真正理解你的项目。框架感知的上下文，随代码库共同演进。

+
+
+ 📦 +

集中式技能

+

一次安装，随处使用。跨项目共享技能，告别文件杂乱。

+
+
+ 🔄 +

自适应技能

+

技能懂你的工具。为 Claude、Codex、Kimi、OpenCode 等提供优化变体，以及更多。

+
+
+ 📝 +

BMad 团队专业博客

+

来自团队的指南、文章与见解。即将上线。

+
+
+ +

入门阶段

+ +
+
+ 🏪 +

技能市场

+

发现、安装与更新社区构建的技能。一条 curl 命令即可获得超能力。

+
+
+ 🎨 +

工作流定制

+

打造属于你的工作流。集成 Jira、Linear、自定义输出——你的工作流，你的规则。

+
+
+ 🚀 +

阶段 1-3 优化

+

通过子智能体上下文收集实现闪电般快速的规划。YOLO 模式遇上引导式卓越。

+
+
+ 🌐 +

企业级就绪

+

SSO、审计日志、团队工作空间。那些让企业点头同意的无聊但必要的东西。

+
+
+ 💎 +

社区模块爆发

+

娱乐、安全、治疗、角色扮演以及更多内容。扩展 BMad 方法平台。

+
+
+ ⚡ +

开发循环自动化

+

可选的开发自动驾驶。让 AI 处理流程，同时保持质量高企。

+
+
+ +

社区与团队

+ +
+
+ 🎙️ +

BMad 方法播客

+

关于 AI 原生开发的对话。2026 年 3 月 1 日上线！

+
+
+ 🎓 +

BMad 方法大师课

+

从用户到专家。深入每个阶段、每个工作流、每个秘密。

+
+
+ 🏗️ +

BMad 构建器大师课

+

构建你自己的智能体。当你准备好创造而不仅仅是使用时的高级技巧。

+
+
+ ⚡ +

BMad 原型优先

+

一次会话从想法到可用原型。像创作艺术品一样打造你的梦想应用。

+
+
+ 🌴 +

BMad BALM！

+

AI 原生的生活管理。任务、习惯、目标——你的 AI 副驾驶，无处不在。

+
+
+ 🖥️ +

官方 UI

+

整个 BMad 生态系统的精美界面。CLI 的强大，GUI 的精致。

+
+
+ 🔒 +

BMad 一体机

+

自托管、气隙隔离、企业级。你的 AI 助手、你的基础设施、你的控制。

+
+
+ +
+

想要贡献？

+

+ 这只是计划内容的一部分。BMad 开源团队欢迎贡献者！{" "}
+ 在 GitHub 上加入我们，共同塑造 AI 驱动开发的未来。 +

+

+ 喜欢我们正在构建的东西？我们感谢一次性与月度{" "}支持。 +

+

+ 如需企业赞助、合作咨询、演讲邀请、培训或媒体咨询：{" "} + contact@bmadcode.com +

+
+
+ +--- +## 术语说明 + +- **agent**：智能体。在人工智能与编程文档中，指具备自主决策或执行能力的单元。 +- **SSO**：单点登录。一种用户认证机制，允许用户使用一组凭据访问多个应用程序。 +- **air-gapped**：气隙隔离。指系统与外部网络完全物理隔离的安全措施。 +- **YOLO**：You Only Live Once 的缩写，此处指快速、大胆的执行模式。 +- **evals**：评估。对 AI 模型或智能体性能的测试与评价。 +- **graceful degradation**：优雅降级。系统在部分功能失效时仍能保持基本功能的特性。 +- **sub-agent**：子智能体。在主智能体协调下执行特定任务的辅助智能体。 +- **context**：上下文。AI 理解任务所需的相关信息与环境背景。 +- **workflow**：工作流。一系列有序的任务或操作流程。 +- **skills**：技能。AI 智能体可执行的具体能力或功能模块。 +- **CLI**：命令行界面。通过文本命令与计算机交互的方式。 +- **GUI**：图形用户界面。通过图形元素与计算机交互的方式。 diff --git a/docs_cn/tutorials/getting-started_cn.md b/docs_cn/tutorials/getting-started_cn.md new file mode 100644 index 000000000..f220f13f9 --- /dev/null +++ b/docs_cn/tutorials/getting-started_cn.md @@ -0,0 +1,300 @@ +--- +title: "快速入门" +description: 安装 BMad 并构建你的第一个项目 +--- + +使用 AI 驱动的工作流更快地构建软件，通过专门的智能体引导你完成规划、架构设计和实现。 + +## 你将学到 + +- 为新项目安装并初始化 BMad Method +- 使用 **BMad-Help** —— 你的智能向导，它知道下一步该做什么 +- 根据项目规模选择合适的规划路径 +- 从需求到可用代码，逐步推进各个阶段 +- 有效使用智能体和工作流 + +:::note[前置条件] +- **Node.js 20+** — 安装程序必需 +- **Git** — 推荐用于版本控制 +- **AI 驱动的 IDE** — Claude Code、Cursor 或类似工具 +- **一个项目想法** — 即使是简单的想法也可以用于学习 +::: + +:::tip[最简单的路径] +**安装** → `npx bmad-method install` +**询问** → `/bmad-help 我应该先做什么？` +**构建** → 让 BMad-Help 逐个工作流地引导你 +::: + +## 认识 BMad-Help：你的智能向导 + +**BMad-Help 是开始使用 BMad 的最快方式。** 你不需要记住工作流或阶段 —— 只需询问，BMad-Help 就会： + +- **检查你的项目**，看看已经完成了什么 +- **根据你安装的模块显示你的选项** +- **推荐下一步** —— 包括第一个必需任务 +- **回答问题**，比如"我有一个 SaaS 想法，应该从哪里开始？" + +### 如何使用 BMad-Help + +只需在 AI IDE 中使用斜杠命令运行它： + +``` +/bmad-help +``` + +或者结合问题以获得上下文感知的指导： + +``` +/bmad-help 我有一个 SaaS 产品的想法，我已经知道我想要的所有功能。我应该从哪里开始？ +``` + +BMad-Help 将回应： +- 针对你的情况推荐什么 +- 第一个必需任务是什么 +- 其余流程是什么样的 + +### 它也驱动工作流 + +BMad-Help 不仅回答问题 —— **它会在每个工作流结束时自动运行**，告诉你确切地下一步该做什么。无需猜测，无需搜索文档 —— 只需对下一个必需工作流的清晰指导。 + +:::tip[从这里开始] +安装 BMad 后，立即运行 `/bmad-help`。它将检测你安装了哪些模块，并引导你找到项目的正确起点。 +::: + +## 了解 BMad + +BMad 通过带有专门 AI 智能体的引导工作流帮助你构建软件。该过程遵循四个阶段： + +| 阶段 | 名称 | 发生什么 | +| ---- | -------------- | -------------------------------------------------- | +| 1 | 分析 | 头脑风暴、研究、产品简报 *（可选）* | +| 2 | 规划 | 创建需求（PRD 或技术规范） | +| 3 | 解决方案设计 | 设计架构 *（仅限 BMad Method/Enterprise only）* | +| 4 | 实现 | 逐个史诗、逐个故事地构建 | + +**[打开工作流地图](../reference/workflow-map_cn.md)** 以探索阶段、工作流和上下文管理。 + +根据项目的复杂性，BMad 提供三种规划路径： + +| 路径 | 最适合 | 创建的文档 | +| --------------- | ---------------------------------------------------- | --------------------------------------- | +| **Quick Flow** | 错误修复、简单功能、范围清晰（1-15 个故事） | 仅技术规范 | +| **BMad Method** | 产品、平台、复杂功能（10-50+ 个故事） | PRD + 架构 + UX | +| **Enterprise** | 合规、多租户系统（30+ 个故事） | PRD + 架构 + 安全 + DevOps | + +:::note +故事数量是指导，而非定义。根据规划需求选择你的路径，而不是故事数学。 +::: + +## 安装 + +在项目目录中打开终端并运行： + +```bash +npx bmad-method install +``` + +当提示选择模块时，选择 **BMad Method**。 + +安装程序会创建两个文件夹： +- `_bmad/` — 智能体、工作流、任务和配置 +- `_bmad-output/` — 目前为空，但这是你的工件将被保存的地方 + +:::tip[你的下一步] +在项目文件夹中打开你的 AI IDE 并运行： + +``` +/bmad-help +``` + +BMad-Help 将检测你已完成的内容，并准确推荐下一步该做什么。你也可以问它诸如"我的选项是什么？"或"我有一个 SaaS 想法，我应该从哪里开始？"之类的问题。 +::: + +:::note[如何加载智能体和运行工作流] +每个工作流都有一个你在 IDE 中运行的**斜杠命令**（例如 `/bmad-bmm-create-prd`）。运行工作流命令会自动加载相应的智能体 —— 你不需要单独加载智能体。你也可以直接加载智能体进行一般对话（例如，加载 PM 智能体使用 `/bmad-agent-bmm-pm`）。 +::: + +:::caution[新对话] +始终为每个工作流开始一个新的对话。这可以防止上下文限制导致问题。 +::: + +## 步骤 1：创建你的计划 + +完成阶段 1-3。**为每个工作流使用新对话。** + +:::tip[项目上下文（可选）] +在开始之前，考虑创建 `project-context.md` 来记录你的技术偏好和实现规则。这确保所有 AI 智能体在整个项目中遵循你的约定。 + +在 `_bmad-output/project-context.md` 手动创建它，或在架构之后使用 `/bmad-bmm-generate-project-context` 生成它。[了解更多](../explanation/project-context_cn.md)。 +::: + +### 阶段 1：分析（可选） + +此阶段中的所有工作流都是可选的： +- **头脑风暴**（`/bmad-brainstorming`） — 引导式构思 +- **研究**（`/bmad-bmm-research`） — 市场和技术研究 +- **创建产品简报**（`/bmad-bmm-create-product-brief`） — 推荐的基础文档 + +### 阶段 2：规划（必需） + +**对于 BMad Method 和 Enterprise 路径：** +1. 在新对话中加载 **PM 智能体**（`/bmad-agent-bmm-pm`） +2. 运行 `prd` 工作流（`/bmad-bmm-create-prd`） +3. 输出：`PRD.md` + +**对于 Quick Flow 路径：** +- 使用 `quick-spec` 工作流（`/bmad-bmm-quick-spec`）代替 PRD，然后跳转到实现 + +:::note[UX 设计（可选）] +如果你的项目有用户界面，在创建 PRD 后加载 **UX-Designer 智能体**（`/bmad-agent-bmm-ux-designer`）并运行 UX 设计工作流（`/bmad-bmm-create-ux-design`）。 +::: + +### 阶段 3：解决方案设计（BMad Method/Enterprise） + +**创建架构** +1. 在新对话中加载 **Architect 智能体**（`/bmad-agent-bmm-architect`） +2. 运行 `create-architecture`（`/bmad-bmm-create-architecture`） +3. 输出：包含技术决策的架构文档 + +**创建史诗和故事** + +:::tip[V6 改进] +史诗和故事现在在架构*之后*创建。这会产生更高质量的故事，因为架构决策（数据库、API 模式、技术栈）直接影响工作应该如何分解。 +::: + +1. 在新对话中加载 **PM 智能体**（`/bmad-agent-bmm-pm`） +2. 运行 `create-epics-and-stories`（`/bmad-bmm-create-epics-and-stories`） +3. 工作流使用 PRD 和架构来创建技术信息丰富的故事 + +**实现就绪检查** *（强烈推荐）* +1. 在新对话中加载 **Architect 智能体**（`/bmad-agent-bmm-architect`） +2. 运行 `check-implementation-readiness`（`/bmad-bmm-check-implementation-readiness`） +3. 验证所有规划文档之间的一致性 + +## 步骤 2：构建你的项目 + +规划完成后，进入实现阶段。**每个工作流应该在新对话中运行。** + +### 初始化冲刺规划 + +加载 **SM 智能体**（`/bmad-agent-bmm-sm`）并运行 `sprint-planning`（`/bmad-bmm-sprint-planning`）。这将创建 `sprint-status.yaml` 来跟踪所有史诗和故事。 + +### 构建周期 + +对于每个故事，使用新对话重复此周期： + +| 步骤 | 智能体 | 工作流 | 命令 | 目的 | +| ---- | ------ | ------------ | ----------------------- | ------------------------------- | +| 1 | SM | `create-story` | `/bmad-bmm-create-story` | 从史诗创建故事文件 | +| 2 | DEV | `dev-story` | `/bmad-bmm-dev-story` | 实现故事 | +| 3 | DEV | `code-review` | `/bmad-bmm-code-review` | 质量验证 *（推荐）* | + +完成史诗中的所有故事后，加载 **SM 智能体**（`/bmad-agent-bmm-sm`）并运行 `retrospective`（`/bmad-bmm-retrospective`）。 + +## 你已完成的工作 + +你已经学习了使用 BMad 构建的基础： + +- 安装了 BMad 并为你的 IDE 进行了配置 +- 使用你选择的规划路径初始化了项目 +- 创建了规划文档（PRD、架构、史诗和故事） +- 了解了实现的构建周期 + +你的项目现在拥有： + +```text +your-project/ +├── _bmad/ # BMad 配置 +├── _bmad-output/ +│ ├── planning-artifacts/ +│ │ ├── PRD.md # 你的需求文档 +│ │ ├── architecture.md # 技术决策 +│ │ └── epics/ # 史诗和故事文件 +│ ├── implementation-artifacts/ +│ │ └── sprint-status.yaml # 冲刺跟踪 +│ └── project-context.md # 实现规则（可选） +└── ... +``` + +## 快速参考 + +| 工作流 | 命令 | 智能体 | 目的 | +| ----------------------------------- | --------------------------------------- | -------- | -------------------------------------------- | +| **`help`** ⭐ | `/bmad-help` | 任意 | **你的智能向导 —— 随时询问任何问题！** | +| `prd` | `/bmad-bmm-create-prd` | PM | 创建产品需求文档 | +| `create-architecture` | `/bmad-bmm-create-architecture` | Architect | 创建架构文档 | +| `generate-project-context` | `/bmad-bmm-generate-project-context` | Analyst | 创建项目上下文文件 | +| `create-epics-and-stories` | `/bmad-bmm-create-epics-and-stories` | PM | 将 PRD 分解为史诗 | +| `check-implementation-readiness` | `/bmad-bmm-check-implementation-readiness` | Architect | 验证规划一致性 | +| `sprint-planning` | `/bmad-bmm-sprint-planning` | SM | 初始化冲刺跟踪 | +| `create-story` | `/bmad-bmm-create-story` | SM | 创建故事文件 | +| `dev-story` | `/bmad-bmm-dev-story` | DEV | 实现故事 | +| `code-review` | `/bmad-bmm-code-review` | DEV | 审查已实现的代码 | + +## 常见问题 + +**我总是需要架构吗？** +仅对于 BMad Method 和 Enterprise 路径。Quick Flow 从技术规范跳转到实现。 + +**我可以稍后更改我的计划吗？** +可以。SM 智能体有一个 `correct-course` 工作流（`/bmad-bmm-correct-course`）用于处理范围变更。 + +**如果我想先进行头脑风暴怎么办？** +在开始 PRD 之前，加载 Analyst 智能体（`/bmad-agent-bmm-analyst`）并运行 `brainstorming`（`/bmad-brainstorming`）。 + +**我需要遵循严格的顺序吗？** +不一定。一旦你了解了流程，你可以使用上面的快速参考直接运行工作流。 + +## 获取帮助 + +:::tip[第一站：BMad-Help] +**随时运行 `/bmad-help`** —— 这是摆脱困境的最快方式。问它任何问题： +- "安装后我应该做什么？" +- "我在工作流 X 上卡住了" +- "我在 Y 方面有什么选项？" +- "向我展示到目前为止已完成的工作" + +BMad-Help 检查你的项目，检测你已完成的内容，并确切地告诉你下一步该做什么。 +::: + +- **在工作流期间** — 智能体通过问题和解释引导你 +- **社区** — [Discord](https://discord.gg/gk8jAdXWmj) (#bmad-method-help, #report-bugs-and-issues) + +## 关键要点 + +:::tip[记住这些] +- **从 `/bmad-help` 开始** — 你的智能向导，了解你的项目和选项 +- **始终使用新对话** — 为每个工作流开始新对话 +- **路径很重要** — Quick Flow 使用 quick-spec；Method/Enterprise 需要 PRD 和架构 +- **BMad-Help 自动运行** — 每个工作流结束时都会提供下一步的指导 +::: + +准备好开始了吗？安装 BMad，运行 `/bmad-help`，让你的智能向导为你引路。 + +--- +## 术语说明 + +- **agent**：智能体。在人工智能与编程文档中，指具备自主决策或执行能力的单元。 +- **epic**：史诗。软件开发中用于组织和管理大型功能或用户需求的高级工作项。 +- **story**：故事。敏捷开发中的用户故事，描述用户需求的小型工作项。 +- **PRD**：产品需求文档（Product Requirements Document）。详细描述产品功能、需求和目标的文档。 +- **workflow**：工作流。一系列有序的任务或步骤，用于完成特定目标。 +- **sprint**：冲刺。敏捷开发中的固定时间周期，用于完成预定的工作。 +- **IDE**：集成开发环境（Integrated Development Environment）。提供代码编辑、调试等功能的软件工具。 +- **artifact**：工件。软件开发过程中产生的文档、代码或其他可交付成果。 +- **retrospective**：回顾。敏捷开发中的会议，用于反思和改进团队工作流程。 +- **tech-spec**：技术规范（Technical Specification）。描述系统技术实现细节的文档。 +- **UX**：用户体验（User Experience）。用户在使用产品过程中的整体感受和交互体验。 +- **PM**：产品经理（Product Manager）。负责产品规划、需求管理和团队协调的角色。 +- **SM**：Scrum Master。敏捷开发中的角色，负责促进 Scrum 流程和团队协作。 +- **DEV**：开发者（Developer）。负责编写代码和实现功能的角色。 +- **Architect**：架构师。负责系统架构设计和技术决策的角色。 +- **Analyst**：分析师。负责需求分析、市场研究等工作的角色。 +- **npx**：Node Package eXecute。Node.js 包执行器，用于运行 npm 包而无需安装。 +- **Node.js**：基于 Chrome V8 引擎的 JavaScript 运行时环境。 +- **Git**：分布式版本控制系统。 +- **SaaS**：软件即服务（Software as a Service）。通过互联网提供软件服务的模式。 +- **DevOps**：开发运维（Development and Operations）。强调开发和运维协作的实践和方法。 +- **multi-tenant**：多租户。一种软件架构，允许单个实例为多个客户（租户）提供服务。 +- **compliance**：合规性。遵守法律、法规和行业标准的要求。