From 8b0754106d6281f0dd91956eb4741367d3d488c4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=A2=81=E5=B1=B1=E6=B2=B3?= <392425595@qq.com> Date: Tue, 24 Mar 2026 10:03:54 +0800 Subject: [PATCH] docs(zh-cn): refine Epic3 story 3.1 and 3.2 explanations (#2098) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * docs(zh-cn-explanation): refine epic3 stories 3.1-3.2 我统一 solutioning、project context 与 established projects 的中文术语和叙述边界，避免 explanation 页面混入 how-to 语气导致误判。 我补齐中文优先跳转并更新关键 workflow 命名，使多智能体协作与既有项目 FAQ 的说明更可执行。 feishu: https://feishu.cn/wiki/TODO Made-with: Cursor * docs(zh-cn-explanation): normalize admonition syntax 我将 3 篇中文 explanation 文档中的提示块语法统一为仓库约定的 `:::...:::` 形式。 此前使用 `::::...::::` 会导致与现有文档规范不一致；现在统一后可减少渲染歧义与后续维护成本。 Feishu: Made-with: Cursor --------- Co-authored-by: leon --- .../explanation/established-projects-faq.md | 72 ++++---- .../explanation/preventing-agent-conflicts.md | 155 +++++++--------- docs/zh-cn/explanation/project-context.md | 166 +++++------------- .../explanation/why-solutioning-matters.md | 84 ++++----- 4 files changed, 184 insertions(+), 293 deletions(-) diff --git a/docs/zh-cn/explanation/established-projects-faq.md b/docs/zh-cn/explanation/established-projects-faq.md index 6b37a98b6..a182d8723 100644 --- a/docs/zh-cn/explanation/established-projects-faq.md +++ b/docs/zh-cn/explanation/established-projects-faq.md @@ -1,60 +1,62 @@ --- title: "既有项目常见问题" -description: 关于在既有项目上使用 BMad 方法的常见问题 +description: 关于在既有项目上使用 BMad Method 的常见问题 sidebar: order: 8 --- -关于使用 BMad 方法（BMM）在既有项目上工作的常见问题的快速解答。 +关于在 established projects（既有项目）中使用 BMad Method 的高频问题，快速说明如下。 ## 问题 -- [我必须先运行 document-project 吗？](#我必须先运行-document-project-吗) -- [如果我忘记运行 document-project 怎么办？](#如果我忘记运行-document-project-怎么办) -- [我可以在既有项目上使用快速流程吗？](#我可以在既有项目上使用快速流程吗) -- [如果我的现有代码不遵循最佳实践怎么办？](#如果我的现有代码不遵循最佳实践怎么办) +- [我必须先运行文档梳理工作流吗？](#我必须先运行文档梳理工作流吗) +- [如果我忘了运行文档梳理怎么办？](#如果我忘了运行文档梳理怎么办) +- [既有项目可以直接用 Quick Flow 吗？](#既有项目可以直接用-quick-flow-吗) +- [如果现有代码不符合最佳实践怎么办？](#如果现有代码不符合最佳实践怎么办) +- [什么时候该从 Quick Flow 切到完整方法？](#什么时候该从-quick-flow-切到完整方法) -### 我必须先运行 document-project 吗？ +### 我必须先运行文档梳理工作流吗？ -强烈推荐，特别是如果： +不绝对必须，但通常强烈建议先运行 `bmad-document-project`，尤其当： +- 项目文档缺失或明显过时 +- 新成员或智能体难以快速理解现有系统 +- 你希望后续 `workflow` 基于真实现状而不是猜测执行 -- 没有现有文档 -- 文档已过时 -- AI 智能体需要关于现有代码的上下文 +如果你已有完整且最新的文档（包含 `docs/index.md`），并且能通过其他方式提供足够上下文，也可以跳过。 -如果你拥有全面且最新的文档，包括 `docs/index.md`，或者将使用其他工具或技术来帮助智能体发现现有系统，则可以跳过此步骤。 +### 如果我忘了运行文档梳理怎么办？ -### 如果我忘记运行 document-project 怎么办？ +可以随时补跑，不影响你继续推进当前任务。很多团队会在迭代中期或里程碑后再运行一次，用来把“代码现状”回写到文档里。 -不用担心——你可以随时执行。你甚至可以在项目期间或项目之后执行，以帮助保持文档最新。 +### 既有项目可以直接用 Quick Flow 吗？ -### 我可以在既有项目上使用快速流程吗？ +可以。Quick Flow（例如 `bmad-quick-dev`）在既有项目里通常很高效，尤其适合： +- 小功能增量 +- 缺陷修复 +- 风险可控的局部改动 -可以！快速流程在既有项目上效果很好。它将： +它会尝试识别现有技术栈、代码模式和约定，并据此生成更贴近现状的实现方案。 -- 自动检测你的现有技术栈 -- 分析现有代码模式 -- 检测约定并请求确认 -- 生成尊重现有代码的上下文丰富的技术规范 +### 如果现有代码不符合最佳实践怎么办？ -非常适合现有代码库中的错误修复和小功能。 +工作流会优先问你：“是否沿用当前约定？”你可以主动选择： +- **沿用**：优先保持一致性，降低短期改动风险 +- **升级**：建立新标准，并在 tech-spec 或架构中写明迁移理由与范围 -### 如果我的现有代码不遵循最佳实践怎么办？ +BMad Method 不会强制“立即现代化”，而是把决策权交给你。 -快速流程会检测你的约定并询问："我应该遵循这些现有约定吗？"你决定： +### 什么时候该从 Quick Flow 切到完整方法？ -- **是** → 与当前代码库保持一致 -- **否** → 建立新标准（在技术规范中记录原因） +当任务出现以下信号时，建议从 Quick Flow 升级到完整 BMad Method： +- 改动跨多个 `epic` 或多个子系统 +- 需要明确 `architecture` 决策，否则容易冲突 +- 涉及较大协作面、较高回归风险或复杂验收要求 -BMM 尊重你的选择——它不会强制现代化，但会提供现代化选项。 +如果你不确定，先让 `bmad-help` 判断当前阶段更稳妥的 workflow。 -**有未在此处回答的问题吗？** 请[提出问题](https://github.com/bmad-code-org/BMAD-METHOD/issues)或在 [Discord](https://discord.gg/gk8jAdXWmj) 中提问，以便我们添加它！ +**还有问题？** 欢迎在 [GitHub Issues](https://github.com/bmad-code-org/BMAD-METHOD/issues) 或 [Discord](https://discord.gg/gk8jAdXWmj) 提问。 ---- -## 术语说明 +## 继续阅读 -- **agent**：智能体。在人工智能与编程文档中，指具备自主决策或执行能力的单元。 -- **Quick Flow**：快速流程。BMad 方法中的一种工作流程，用于快速处理既有项目。 -- **spec**：规范。描述技术实现细节和标准的文档。 -- **stack**：技术栈。项目所使用的技术组合，包括框架、库、工具等。 -- **conventions**：约定。代码库中遵循的编码风格、命名规则等规范。 -- **modernization**：现代化。将旧代码或系统更新为更现代的技术和最佳实践的过程。 +- [既有项目（How-to）](../how-to/established-projects.md) +- [项目上下文（Explanation）](./project-context.md) +- [管理项目上下文（How-to）](../how-to/project-context.md) diff --git a/docs/zh-cn/explanation/preventing-agent-conflicts.md b/docs/zh-cn/explanation/preventing-agent-conflicts.md index c3f24faf6..b8cd4a083 100644 --- a/docs/zh-cn/explanation/preventing-agent-conflicts.md +++ b/docs/zh-cn/explanation/preventing-agent-conflicts.md @@ -5,133 +5,112 @@ sidebar: order: 4 --- -当多个 AI 智能体实现系统的不同部分时，它们可能会做出相互冲突的技术决策。架构文档通过建立共享标准来防止这种情况。 +当多个 AI 智能体并行实现系统时，冲突并不罕见。`architecture` 的作用，就是在 `solutioning` 阶段先统一关键决策，避免到 `epic/story` 实施时才暴露分歧。 -## 常见冲突类型 +## 冲突最常出现在哪些地方 ### API 风格冲突 -没有架构时： -- 智能体 A 使用 REST，路径为 `/users/{id}` +没有架构约束时： +- 智能体 A 使用 REST，路径是 `/users/{id}` - 智能体 B 使用 GraphQL mutations -- 结果：API 模式不一致，消费者困惑 +- 结果：接口模式不一致，调用方和集成层都变复杂 -有架构时： -- ADR 指定："所有客户端-服务器通信使用 GraphQL" -- 所有智能体遵循相同的模式 +有架构约束时： +- ADR 明确规定：“客户端与服务端统一使用 GraphQL” +- 所有智能体遵循同一套 API 规则 -### 数据库设计冲突 +### 数据库与命名冲突 -没有架构时： -- 智能体 A 使用 snake_case 列名 -- 智能体 B 使用 camelCase 列名 -- 结果：模式不一致，查询混乱 +没有架构约束时： +- 智能体 A 使用 `snake_case` 列名 +- 智能体 B 使用 `camelCase` 列名 +- 结果：schema 不一致，查询与迁移成本上升 -有架构时： -- 标准文档指定命名约定 -- 所有智能体遵循相同的模式 +有架构约束时： +- 标准文档统一命名约定和迁移策略 +- 所有智能体按同一模式实现 ### 状态管理冲突 -没有架构时： -- 智能体 A 使用 Redux 管理全局状态 +没有架构约束时： +- 智能体 A 使用 Redux - 智能体 B 使用 React Context -- 结果：多种状态管理方法，复杂度增加 +- 结果：状态层碎片化，维护复杂度增加 -有架构时： -- ADR 指定状态管理方法 -- 所有智能体一致实现 +有架构约束时： +- ADR 明确状态管理方案 +- 不同 `story` 的实现保持一致 -## 架构如何防止冲突 +## architecture 如何前置消解冲突 -### 1. 通过 ADR 明确决策 +### 1. 用 ADR 固化关键决策 -每个重要的技术选择都记录以下内容： -- 上下文（为什么这个决策很重要） -- 考虑的选项（有哪些替代方案） -- 决策（我们选择了什么） -- 理由（为什么选择它） -- 后果（接受的权衡） +每个关键技术选择都至少包含： +- 背景（为什么要做这个决策） +- 备选方案（有哪些选择） +- 最终决策（采用什么） +- 理由（为什么这样选） +- 后果（接受哪些权衡） -### 2. FR/NFR 特定指导 +### 2. 把 FR/NFR 映射到技术实现 -架构将每个功能需求映射到技术方法： -- FR-001：用户管理 → GraphQL mutations -- FR-002：移动应用 → 优化查询 +`architecture` 不是抽象原则清单，而是把需求落到可执行方案： +- FR-001（用户管理）→ GraphQL mutations +- FR-002（移动端性能）→ 查询裁剪与缓存策略 -### 3. 标准和约定 +### 3. 统一基础约定 -明确记录以下内容： +至少覆盖以下共识： - 目录结构 - 命名约定 -- 代码组织 -- 测试模式 +- 代码组织方式 +- 测试策略 -## 架构作为共享上下文 +## architecture 是所有 epic 的共享上下文 -将架构视为所有智能体在实现之前阅读的共享上下文： +把架构文档看作每个智能体在实施前都要阅读的“公共协议”： ```text -PRD："构建什么" +PRD: "做什么" ↓ -架构："如何构建" +architecture: "如何做" ↓ -智能体 A 阅读架构 → 实现 Epic 1 -智能体 B 阅读架构 → 实现 Epic 2 -智能体 C 阅读架构 → 实现 Epic 3 +智能体 A 读 architecture → 实现 Epic 1 +智能体 B 读 architecture → 实现 Epic 2 +智能体 C 读 architecture → 实现 Epic 3 ↓ -结果：一致的实现 +结果：实现一致、集成顺畅 ``` -## Key ADR Topics +## 优先写清的 ADR 主题 -防止冲突的常见决策： - -| 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 | +| API 风格 | GraphQL vs REST vs gRPC | +| 数据存储 | PostgreSQL vs MongoDB | +| 认证机制 | JWT vs Session | +| 状态管理 | Redux vs Context vs Zustand | +| 样式方案 | CSS Modules vs Tailwind vs Styled Components | +| 测试体系 | Jest + Playwright vs Vitest + Cypress | -## 避免的反模式 +## 常见误区 :::caution[常见错误] -- **隐式决策** — "我们边做边确定 API 风格"会导致不一致 -- **过度文档化** — 记录每个次要选择会导致分析瘫痪 -- **过时架构** — 文档写一次后从不更新，导致智能体遵循过时的模式 +- **隐式决策**：边写边定规则，最终通常会分叉 +- **过度文档化**：把每个小选择都写 ADR，造成分析瘫痪 +- **架构陈旧**：文档不更新，智能体继续按过时规则实现 ::: -:::tip[正确方法] -- 记录跨越 epic 边界的决策 -- 专注于容易产生冲突的领域 -- 随着学习更新架构 -- 对重大变更使用 `correct-course` +:::tip[更稳妥的做法] +- 先记录跨 `epic`、高冲突概率的决策 +- 把精力放在“会影响多个 story 的规则” +- 随着项目演进持续更新架构文档 +- 出现重大偏移时使用 `bmad-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）。描述产品功能、需求和目标的文档。 +- [为什么解决方案阶段很重要](./why-solutioning-matters.md) +- [项目上下文](./project-context.md) +- [工作流地图](../reference/workflow-map.md) diff --git a/docs/zh-cn/explanation/project-context.md b/docs/zh-cn/explanation/project-context.md index d43105ea6..7886e4c0c 100644 --- a/docs/zh-cn/explanation/project-context.md +++ b/docs/zh-cn/explanation/project-context.md @@ -1,55 +1,51 @@ --- title: "项目上下文" -description: project-context.md 如何使用项目的规则和偏好指导 AI 智能体 +description: project-context.md 如何使用项目规则和偏好指导 AI 智能体 sidebar: order: 7 --- -`project-context.md` 文件是您的项目面向 AI 智能体的实施指南。类似于其他开发系统中的"宪法"，它记录了确保所有工作流中代码生成一致的规则、模式和偏好。 +`project-context.md` 是面向 AI 智能体的项目级上下文文件。它的定位不是教程步骤，而是“实现约束说明”：把你的技术偏好、架构边界和工程约定沉淀成可复用规则，让不同工作流、不同智能体在多个 `story` 中做出一致决策。 -## 它的作用 +## project context 解决什么问题 -AI 智能体不断做出实施决策——遵循哪些模式、如何组织代码、使用哪些约定。如果没有明确指导，它们可能会： -- 遵循与您的代码库不匹配的通用最佳实践 -- 在不同的用户故事中做出不一致的决策 -- 错过项目特定的需求或约束 +没有统一上下文时，智能体往往会： +- 套用通用最佳实践，而不是你的项目约定 +- 在不同 `story` 中做出不一致实现 +- 漏掉代码里不易推断的隐性约束 -`project-context.md` 文件通过以简洁、针对 LLM 优化的格式记录智能体需要了解的内容来解决这个问题。 +有 `project-context.md` 时，这些高频偏差会明显减少，因为关键规则在进入实现前已经被显式声明。 -## 它的工作原理 +## 它如何被工作流使用 -每个实施工作流都会自动加载 `project-context.md`（如果存在）。架构师工作流也会加载它，以便在设计架构时尊重您的技术偏好。 +多数实现相关工作流会自动加载 `project-context.md`（若存在），并把它作为共享上下文参与决策。 -**由以下工作流加载：** -- `create-architecture` — 在解决方案设计期间尊重技术偏好 -- `create-story` — 使用项目模式指导用户故事创建 -- `dev-story` — 指导实施决策 -- `code-review` — 根据项目标准进行验证 -- `quick-dev` — 在实施技术规范时应用模式 -- `sprint-planning`、`retrospective`、`correct-course` — 提供项目范围的上下文 +**常见加载方包括：** +- `bmad-create-architecture`：在 solutioning 时纳入你的技术偏好 +- `bmad-create-story`：按项目约定拆分和描述 story +- `bmad-dev-story`：约束实现路径和代码风格 +- `bmad-code-review`：按项目标准做一致性校验 +- `bmad-quick-dev`：在快速实现中避免偏离既有模式 +- `bmad-sprint-planning`、`bmad-retrospective`、`bmad-correct-course`：读取项目级背景 -## 何时创建 +## 什么时候建立或更新 -`project-context.md` 文件在项目的任何阶段都很有用： - -| 场景 | 何时创建 | 目的 | +| 场景 | 建议时机 | 目标 | |----------|----------------|---------| -| **新项目，架构之前** | 手动，在 `create-architecture` 之前 | 记录您的技术偏好，以便架构师尊重它们 | -| **新项目，架构之后** | 通过 `generate-project-context` 或手动 | 捕获架构决策，供实施智能体使用 | -| **现有项目** | 通过 `generate-project-context` | 发现现有模式，以便智能体遵循既定约定 | -| **快速流程项目** | 在 `quick-dev` 之前或期间 | 确保快速实施尊重您的模式 | +| **新项目（架构前）** | 在 `bmad-create-architecture` 前手动创建 | 先声明技术偏好，避免架构偏航 | +| **新项目（架构后）** | 通过 `bmad-generate-project-context` 生成并补充 | 把架构决策转成可执行规则 | +| **既有项目** | 先生成，再人工校对 | 让智能体学习现有约定而非重造体系 | +| **Quick Flow 场景** | 在 `bmad-quick-dev` 前或过程中维护 | 弥补跳过完整规划带来的上下文缺口 | -:::tip[推荐] -对于新项目，如果您有强烈的技术偏好，请在架构之前手动创建。否则，在架构之后生成它以捕获这些决策。 +:::tip[推荐做法] +如果你有强技术偏好（例如数据库、状态管理、目录规范），尽量在架构前写入。否则可在架构后生成，再按项目现实补齐。 ::: -## 文件内容 +## 应该写哪些内容 -该文件有两个主要部分： +建议聚焦两类信息：**技术栈与版本**、**关键实现规则**。原则是记录“智能体不容易从代码片段直接推断”的内容。 -### 技术栈与版本 - -记录项目使用的框架、语言和工具及其具体版本： +### 1. 技术栈与版本 ```markdown ## Technology Stack & Versions @@ -60,9 +56,7 @@ AI 智能体不断做出实施决策——遵循哪些模式、如何组织代 - Styling: Tailwind CSS with custom design tokens ``` -### 关键实施规则 - -记录智能体可能忽略的模式和约定： +### 2. 关键实现规则 ```markdown ## Critical Implementation Rules @@ -73,104 +67,28 @@ AI 智能体不断做出实施决策——遵循哪些模式、如何组织代 **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/` ``` -专注于那些**不明显**的内容——智能体可能无法从阅读代码片段中推断出来的内容。不要记录普遍适用的标准实践。 +## 常见误解 -## 创建文件 +- **误解 1：它是操作手册。** + 不是。操作步骤请看 how-to；这里强调的是规则与边界。 +- **误解 2：写得越全越好。** + 不对。冗长且泛化的“最佳实践”会稀释有效约束。 +- **误解 3：写一次就结束。** + 这是动态文件。架构变化、约定变化后要同步更新。 -您有三个选择： +## 文件位置 -### 手动创建 +默认位置是 `_bmad-output/project-context.md`。工作流优先在该位置查找，也会扫描项目内的 `**/project-context.md`。 -在 `_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`，智能体会做出可能与您的项目不匹配的假设： - -| 没有上下文 | 有上下文 | -|----------------|--------------| -| 使用通用模式 | 遵循您的既定约定 | -| 用户故事之间风格不一致 | 实施一致 | -| 可能错过项目特定的约束 | 尊重所有技术需求 | -| 每个智能体独立决策 | 所有智能体遵循相同规则 | - -这对于以下情况尤其重要： -- **快速流程** — 跳过 PRD 和架构，因此上下文文件填补了空白 -- **团队项目** — 确保所有智能体遵循相同的标准 -- **现有项目** — 防止破坏既定模式 - -## 编辑和更新 - -`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 运行时。 +- [管理项目上下文（How-to）](../how-to/project-context.md) +- [既有项目常见问题](./established-projects-faq.md) +- [工作流地图](../reference/workflow-map.md) diff --git a/docs/zh-cn/explanation/why-solutioning-matters.md b/docs/zh-cn/explanation/why-solutioning-matters.md index 27e8f96ca..2a598f2dc 100644 --- a/docs/zh-cn/explanation/why-solutioning-matters.md +++ b/docs/zh-cn/explanation/why-solutioning-matters.md @@ -5,54 +5,53 @@ sidebar: order: 3 --- +Phase 3（solutioning）把“要做什么”（planning 产出）转成“如何实现”（`architecture` 设计 + 工作拆分）。它的核心价值是：在开发前先把跨 `epic` 的关键技术决策写清楚，让后续 `story` 实施保持一致。 -阶段 3（解决方案）将构建**什么**（来自规划）转化为**如何**构建（技术设计）。该阶段通过在实施开始前记录架构决策，防止多史诗项目中的智能体冲突。 - -## 没有解决方案阶段的问题 +## 不做 solutioning 会出现什么问题 ```text -智能体 1 使用 REST API 实现史诗 1 -智能体 2 使用 GraphQL 实现史诗 2 -结果：API 设计不一致，集成噩梦 +智能体 1 使用 REST API 实现 Epic 1 +智能体 2 使用 GraphQL 实现 Epic 2 +结果：API 设计不一致，集成成本暴涨 ``` -当多个智能体在没有共享架构指导的情况下实现系统的不同部分时，它们会做出可能冲突的独立技术决策。 +当多个智能体在没有共享 `architecture` 指南的前提下并行实现不同 `epic`，它们会各自做局部最优决策，最后在集成阶段发生冲突。 -## 有解决方案阶段的解决方案 +## 做了 solutioning 后会发生什么 ```text -架构工作流决定："所有 API 使用 GraphQL" -所有智能体遵循架构决策 -结果：实现一致，无冲突 +architecture 工作流先定规则："所有 API 使用 GraphQL" +所有智能体按同一套决策实现 story +结果：实现一致，集成顺滑 ``` -通过明确记录技术决策，所有智能体都能一致地实现，集成变得简单直接。 +solutioning 的本质不是“多写一份文档”，而是把高冲突风险决策前置，作为所有 `story` 的共享上下文。 -## 解决方案阶段 vs 规划阶段 +## solutioning 与 planning 的边界 -| 方面 | 规划（阶段 2） | 解决方案（阶段 3） | +| 方面 | Planning（阶段 2） | Solutioning（阶段 3） | | -------- | ----------------------- | --------------------------------- | -| 问题 | 做什么和为什么？ | 如何做？然后是什么工作单元？ | -| 输出 | FRs/NFRs（需求） | 架构 + 史诗/用户故事 | -| 智能体 | PM | 架构师 → PM | +| 核心问题 | 做什么，为什么做？ | 如何做，再如何拆分工作？ | +| 输出物 | FRs/NFRs（需求） | `architecture` + `epic/story` 拆分 | +| 主导角色 | PM | Architect → PM | | 受众 | 利益相关者 | 开发人员 | -| 文档 | PRD（FRs/NFRs） | 架构 + 史诗文件 | -| 层级 | 业务逻辑 | 技术设计 + 工作分解 | +| 文档 | PRD（FRs/NFRs） | 架构文档 + epics 文件 | +| 决策层级 | 业务目标与范围 | 技术策略与实现边界 | ## 核心原则 -**使技术决策明确且有文档记录**，以便所有智能体一致地实现。 +**让跨 `epic` 的关键技术决策显式、可追溯、可复用。** -这可以防止： +这能直接降低： - API 风格冲突（REST vs GraphQL） -- 数据库设计不一致 -- 状态管理分歧 -- 命名约定不匹配 -- 安全方法差异 +- 数据模型与命名约定不一致 +- 状态管理方案分裂 +- 安全策略分叉 +- 中后期返工成本 -## 何时需要解决方案阶段 +## 什么时候需要 solutioning -| 流程 | 需要解决方案阶段？ | +| 流程 | 需要 solutioning？ | |-------|----------------------| | Quick Flow | 否 - 完全跳过 | | BMad Method Simple | 可选 | @@ -60,31 +59,24 @@ sidebar: | Enterprise | 是 | :::tip[经验法则] -如果你有多个可能由不同智能体实现的史诗，你需要解决方案阶段。 +只要需求会拆成多个 `epic`，并且可能由不同智能体并行实现，就应该做 solutioning。 ::: -## 跳过的代价 +## 跳过 solutioning 的代价 -在复杂项目中跳过解决方案阶段会导致： +在复杂项目中跳过该阶段，常见后果是： -- **集成问题**在冲刺中期发现 -- **返工**由于实现冲突 -- **开发时间更长**整体 -- **技术债务**来自不一致模式 +- **集成问题**在冲刺中期暴露 +- **返工**由实现冲突引发 +- **整体研发周期拉长** +- **技术债务**因模式不一致持续累积 :::caution[成本倍增] -在解决方案阶段发现对齐问题比在实施期间发现要快 10 倍。 +在 solutioning 阶段发现对齐问题，通常比在实施中后期才发现更快、更便宜。 ::: ---- -## 术语说明 +## 继续阅读 -- **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**：技术债务。指为了短期目标而选择的不完美技术方案，未来需要付出额外成本来修复。 +- [防止智能体冲突](./preventing-agent-conflicts.md) +- [项目上下文](./project-context.md) +- [工作流地图](../reference/workflow-map.md)