bmad-method 6.0.4 → 6.0.5-next.1

package/docs/zh-cn/explanation/brainstorming.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**：利益相关者。对项目或决策有利益关系或受其影响的个人或群体。

package/docs/zh-cn/explanation/established-projects-faq.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**：现代化。将旧代码或系统更新为更现代的技术和最佳实践的过程。

package/docs/zh-cn/explanation/party-mode.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**：上市时间。产品从概念到推向市场所需的时间。

package/docs/zh-cn/explanation/preventing-agent-conflicts.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）。描述产品功能、需求和目标的文档。

package/docs/zh-cn/explanation/project-context.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 运行时。

package/docs/zh-cn/explanation/quick-flow.md

@@ -0,0 +1,93 @@
+---
+title: "快速流程"
+description: 小型变更的快速通道 - 跳过完整方法论
+sidebar:
+  order: 1
+---
+
+跳过繁琐流程。快速流程通过两条命令将你从想法带到可运行的代码 - 无需产品简报、无需 PRD、无需架构文档。
+
+## 何时使用
+
+- Bug 修复和补丁
+- 重构现有代码
+- 小型、易于理解的功能
+- 原型设计和探索性开发
+- 单智能体工作，一名开发者可以掌控完整范围
+
+## 何时不使用
+
+- 需要利益相关者对齐的新产品或平台
+- 跨越多个组件或团队的主要功能
+- 需要架构决策的工作（数据库架构、API 契约、服务边界）
+- 需求不明确或有争议的任何工作
+
+:::caution[Scope Creep]
+如果你启动快速流程后发现范围超出预期，`quick-dev` 会检测到并提供升级选项。你可以在任何时间切换到完整的 PRD 工作流程，而不会丢失你的工作。
+:::
+
+## 工作原理
+
+快速流程有两条命令，每条都由结构化的工作流程支持。你可以一起运行它们，也可以独立运行。
+
+### 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`。这为实现智能体提供了专注于构建的干净上下文。
+:::
+
+## 快速流程跳过的内容
+
+完整的 BMad 方法在编写任何代码之前会生成产品简报、PRD、架构文档和 Epic/Story 分解。Quick Flow 用单个技术规范替代所有这些。这之所以有效，是因为 Quick Flow 针对以下变更：
+
+- 产品方向已确立
+- 架构决策已做出
+- 单个开发者可以推理完整范围
+- 需求可以在一次对话中涵盖
+
+## 升级到完整 BMad 方法
+
+快速流程包含内置的范围检测护栏。当你使用直接请求运行 `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**：探索性开发。用于探索技术可行性或解决方案的短期研究活动。

package/docs/zh-cn/explanation/why-solutioning-matters.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**：技术债务。指为了短期目标而选择的不完美技术方案，未来需要付出额外成本来修复。