docs(zh-cn): refine Epic3 story 3.1 and 3.2 explanations (#2098)
* 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: <https://www.feishu.cn/> Made-with: Cursor --------- Co-authored-by: leon <leon.liang@hairobotics.com>
This commit is contained in:
梁山河
GitHub
parent
90d9d880b6
commit
8b0754106d
|
|
@ -1,60 +1,62 @@
|
||||||
---
|
---
|
||||||
title: "既有项目常见问题"
|
title: "既有项目常见问题"
|
||||||
description: 关于在既有项目上使用 BMad 方法的常见问题
|
description: 关于在既有项目上使用 BMad Method 的常见问题
|
||||||
sidebar:
|
sidebar:
|
||||||
order: 8
|
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` 基于真实现状而不是猜测执行
|
||||||
|
|
||||||
- 没有现有文档
|
如果你已有完整且最新的文档（包含 `docs/index.md`），并且能通过其他方式提供足够上下文，也可以跳过。
|
||||||
- 文档已过时
|
|
||||||
- AI 智能体需要关于现有代码的上下文
|
|
||||||
|
|
||||||
如果你拥有全面且最新的文档，包括 `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**：智能体。在人工智能与编程文档中，指具备自主决策或执行能力的单元。
|
- [既有项目（How-to）](../how-to/established-projects.md)
|
||||||
- **Quick Flow**：快速流程。BMad 方法中的一种工作流程，用于快速处理既有项目。
|
- [项目上下文（Explanation）](./project-context.md)
|
||||||
- **spec**：规范。描述技术实现细节和标准的文档。
|
- [管理项目上下文（How-to）](../how-to/project-context.md)
|
||||||
- **stack**：技术栈。项目所使用的技术组合，包括框架、库、工具等。
|
|
||||||
- **conventions**：约定。代码库中遵循的编码风格、命名规则等规范。
|
|
||||||
- **modernization**：现代化。将旧代码或系统更新为更现代的技术和最佳实践的过程。
|
|
||||||
|
|
|
||||||
|
|
@ -5,133 +5,112 @@ sidebar:
|
||||||
order: 4
|
order: 4
|
||||||
---
|
---
|
||||||
|
|
||||||
当多个 AI 智能体实现系统的不同部分时，它们可能会做出相互冲突的技术决策。架构文档通过建立共享标准来防止这种情况。
|
当多个 AI 智能体并行实现系统时，冲突并不罕见。`architecture` 的作用，就是在 `solutioning` 阶段先统一关键决策，避免到 `epic/story` 实施时才暴露分歧。
|
||||||
|
|
||||||
## 常见冲突类型
|
## 冲突最常出现在哪些地方
|
||||||
|
|
||||||
### API 风格冲突
|
### API 风格冲突
|
||||||
|
|
||||||
没有架构时：
|
没有架构约束时：
|
||||||
- 智能体 A 使用 REST，路径为 `/users/{id}`
|
- 智能体 A 使用 REST，路径是 `/users/{id}`
|
||||||
- 智能体 B 使用 GraphQL mutations
|
- 智能体 B 使用 GraphQL mutations
|
||||||
- 结果：API 模式不一致，消费者困惑
|
- 结果：接口模式不一致，调用方和集成层都变复杂
|
||||||
|
|
||||||
有架构时：
|
有架构约束时：
|
||||||
- ADR 指定："所有客户端-服务器通信使用 GraphQL"
|
- ADR 明确规定：“客户端与服务端统一使用 GraphQL”
|
||||||
- 所有智能体遵循相同的模式
|
- 所有智能体遵循同一套 API 规则
|
||||||
|
|
||||||
### 数据库设计冲突
|
### 数据库与命名冲突
|
||||||
|
|
||||||
没有架构时：
|
没有架构约束时：
|
||||||
- 智能体 A 使用 snake_case 列名
|
- 智能体 A 使用 `snake_case` 列名
|
||||||
- 智能体 B 使用 camelCase 列名
|
- 智能体 B 使用 `camelCase` 列名
|
||||||
- 结果：模式不一致，查询混乱
|
- 结果：schema 不一致，查询与迁移成本上升
|
||||||
|
|
||||||
有架构时：
|
有架构约束时：
|
||||||
- 标准文档指定命名约定
|
- 标准文档统一命名约定和迁移策略
|
||||||
- 所有智能体遵循相同的模式
|
- 所有智能体按同一模式实现
|
||||||
|
|
||||||
### 状态管理冲突
|
### 状态管理冲突
|
||||||
|
|
||||||
没有架构时：
|
没有架构约束时：
|
||||||
- 智能体 A 使用 Redux 管理全局状态
|
- 智能体 A 使用 Redux
|
||||||
- 智能体 B 使用 React Context
|
- 智能体 B 使用 React Context
|
||||||
- 结果：多种状态管理方法，复杂度增加
|
- 结果：状态层碎片化，维护复杂度增加
|
||||||
|
|
||||||
有架构时：
|
有架构约束时：
|
||||||
- ADR 指定状态管理方法
|
- ADR 明确状态管理方案
|
||||||
- 所有智能体一致实现
|
- 不同 `story` 的实现保持一致
|
||||||
|
|
||||||
## 架构如何防止冲突
|
## architecture 如何前置消解冲突
|
||||||
|
|
||||||
### 1. 通过 ADR 明确决策
|
### 1. 用 ADR 固化关键决策
|
||||||
|
|
||||||
每个重要的技术选择都记录以下内容：
|
每个关键技术选择都至少包含：
|
||||||
- 上下文（为什么这个决策很重要）
|
- 背景（为什么要做这个决策）
|
||||||
- 考虑的选项（有哪些替代方案）
|
- 备选方案（有哪些选择）
|
||||||
- 决策（我们选择了什么）
|
- 最终决策（采用什么）
|
||||||
- 理由（为什么选择它）
|
- 理由（为什么这样选）
|
||||||
- 后果（接受的权衡）
|
- 后果（接受哪些权衡）
|
||||||
|
|
||||||
### 2. FR/NFR 特定指导
|
### 2. 把 FR/NFR 映射到技术实现
|
||||||
|
|
||||||
架构将每个功能需求映射到技术方法：
|
`architecture` 不是抽象原则清单，而是把需求落到可执行方案：
|
||||||
- FR-001：用户管理 → GraphQL mutations
|
- FR-001（用户管理）→ GraphQL mutations
|
||||||
- FR-002：移动应用 → 优化查询
|
- FR-002（移动端性能）→ 查询裁剪与缓存策略
|
||||||
|
|
||||||
### 3. 标准和约定
|
### 3. 统一基础约定
|
||||||
|
|
||||||
明确记录以下内容：
|
至少覆盖以下共识：
|
||||||
- 目录结构
|
- 目录结构
|
||||||
- 命名约定
|
- 命名约定
|
||||||
- 代码组织
|
- 代码组织方式
|
||||||
- 测试模式
|
- 测试策略
|
||||||
|
|
||||||
## 架构作为共享上下文
|
## architecture 是所有 epic 的共享上下文
|
||||||
|
|
||||||
将架构视为所有智能体在实现之前阅读的共享上下文：
|
把架构文档看作每个智能体在实施前都要阅读的“公共协议”：
|
||||||
|
|
||||||
```text
|
```text
|
||||||
PRD："构建什么"
|
PRD: "做什么"
|
||||||
↓
|
↓
|
||||||
架构："如何构建"
|
architecture: "如何做"
|
||||||
↓
|
↓
|
||||||
智能体 A 阅读架构 → 实现 Epic 1
|
智能体 A 读 architecture → 实现 Epic 1
|
||||||
智能体 B 阅读架构 → 实现 Epic 2
|
智能体 B 读 architecture → 实现 Epic 2
|
||||||
智能体 C 阅读架构 → 实现 Epic 3
|
智能体 C 读 architecture → 实现 Epic 3
|
||||||
↓
|
↓
|
||||||
结果：一致的实现
|
结果：实现一致、集成顺畅
|
||||||
```
|
```
|
||||||
|
|
||||||
## Key ADR Topics
|
## 优先写清的 ADR 主题
|
||||||
|
|
||||||
防止冲突的常见决策：
|
| 主题 | 示例决策 |
|
||||||
|
|
||||||
| Topic | Example Decision |
|
|
||||||
| ---------------- | -------------------------------------------- |
|
| ---------------- | -------------------------------------------- |
|
||||||
| API Style | GraphQL vs REST vs gRPC |
|
| API 风格 | GraphQL vs REST vs gRPC |
|
||||||
| Database | PostgreSQL vs MongoDB |
|
| 数据存储 | PostgreSQL vs MongoDB |
|
||||||
| Auth | JWT vs Sessions |
|
| 认证机制 | JWT vs Session |
|
||||||
| State Management | Redux vs Context vs Zustand |
|
| 状态管理 | Redux vs Context vs Zustand |
|
||||||
| Styling | CSS Modules vs Tailwind vs Styled Components |
|
| 样式方案 | CSS Modules vs Tailwind vs Styled Components |
|
||||||
| Testing | Jest + Playwright vs Vitest + Cypress |
|
| 测试体系 | Jest + Playwright vs Vitest + Cypress |
|
||||||
|
|
||||||
## 避免的反模式
|
## 常见误区
|
||||||
|
|
||||||
:::caution[常见错误]
|
:::caution[常见错误]
|
||||||
- **隐式决策** — "我们边做边确定 API 风格"会导致不一致
|
- **隐式决策**：边写边定规则，最终通常会分叉
|
||||||
- **过度文档化** — 记录每个次要选择会导致分析瘫痪
|
- **过度文档化**：把每个小选择都写 ADR，造成分析瘫痪
|
||||||
- **过时架构** — 文档写一次后从不更新，导致智能体遵循过时的模式
|
- **架构陈旧**：文档不更新，智能体继续按过时规则实现
|
||||||
:::
|
:::
|
||||||
|
|
||||||
:::tip[正确方法]
|
:::tip[更稳妥的做法]
|
||||||
- 记录跨越 epic 边界的决策
|
- 先记录跨 `epic`、高冲突概率的决策
|
||||||
- 专注于容易产生冲突的领域
|
- 把精力放在“会影响多个 story 的规则”
|
||||||
- 随着学习更新架构
|
- 随着项目演进持续更新架构文档
|
||||||
- 对重大变更使用 `correct-course`
|
- 出现重大偏移时使用 `bmad-correct-course`
|
||||||
:::
|
:::
|
||||||
|
|
||||||
---
|
## 继续阅读
|
||||||
## 术语说明
|
|
||||||
|
|
||||||
- **agent**：智能体。在人工智能与编程文档中，指具备自主决策或执行能力的单元。
|
- [为什么解决方案阶段很重要](./why-solutioning-matters.md)
|
||||||
- **ADR**：架构决策记录（Architecture Decision Record）。用于记录重要架构决策及其背景、选项和后果的文档。
|
- [项目上下文](./project-context.md)
|
||||||
- **FR**：功能需求（Functional Requirement）。系统必须具备的功能或行为。
|
- [工作流地图](../reference/workflow-map.md)
|
||||||
- **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）。描述产品功能、需求和目标的文档。
|
|
||||||
|
|
|
||||||
|
|
@ -1,55 +1,51 @@
|
||||||
---
|
---
|
||||||
title: "项目上下文"
|
title: "项目上下文"
|
||||||
description: project-context.md 如何使用项目的规则和偏好指导 AI 智能体
|
description: project-context.md 如何使用项目规则和偏好指导 AI 智能体
|
||||||
sidebar:
|
sidebar:
|
||||||
order: 7
|
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` — 在解决方案设计期间尊重技术偏好
|
- `bmad-create-architecture`：在 solutioning 时纳入你的技术偏好
|
||||||
- `create-story` — 使用项目模式指导用户故事创建
|
- `bmad-create-story`：按项目约定拆分和描述 story
|
||||||
- `dev-story` — 指导实施决策
|
- `bmad-dev-story`：约束实现路径和代码风格
|
||||||
- `code-review` — 根据项目标准进行验证
|
- `bmad-code-review`：按项目标准做一致性校验
|
||||||
- `quick-dev` — 在实施技术规范时应用模式
|
- `bmad-quick-dev`：在快速实现中避免偏离既有模式
|
||||||
- `sprint-planning`、`retrospective`、`correct-course` — 提供项目范围的上下文
|
- `bmad-sprint-planning`、`bmad-retrospective`、`bmad-correct-course`：读取项目级背景
|
||||||
|
|
||||||
## 何时创建
|
## 什么时候建立或更新
|
||||||
|
|
||||||
`project-context.md` 文件在项目的任何阶段都很有用：
|
| 场景 | 建议时机 | 目标 |
|
||||||
|
|
||||||
| 场景 | 何时创建 | 目的 |
|
|
||||||
|----------|----------------|---------|
|
|----------|----------------|---------|
|
||||||
| **新项目，架构之前** | 手动，在 `create-architecture` 之前 | 记录您的技术偏好，以便架构师尊重它们 |
|
| **新项目（架构前）** | 在 `bmad-create-architecture` 前手动创建 | 先声明技术偏好，避免架构偏航 |
|
||||||
| **新项目，架构之后** | 通过 `generate-project-context` 或手动 | 捕获架构决策，供实施智能体使用 |
|
| **新项目（架构后）** | 通过 `bmad-generate-project-context` 生成并补充 | 把架构决策转成可执行规则 |
|
||||||
| **现有项目** | 通过 `generate-project-context` | 发现现有模式，以便智能体遵循既定约定 |
|
| **既有项目** | 先生成，再人工校对 | 让智能体学习现有约定而非重造体系 |
|
||||||
| **快速流程项目** | 在 `quick-dev` 之前或期间 | 确保快速实施尊重您的模式 |
|
| **Quick Flow 场景** | 在 `bmad-quick-dev` 前或过程中维护 | 弥补跳过完整规划带来的上下文缺口 |
|
||||||
|
|
||||||
:::tip[推荐]
|
:::tip[推荐做法]
|
||||||
对于新项目，如果您有强烈的技术偏好，请在架构之前手动创建。否则，在架构之后生成它以捕获这些决策。
|
如果你有强技术偏好（例如数据库、状态管理、目录规范），尽量在架构前写入。否则可在架构后生成，再按项目现实补齐。
|
||||||
:::
|
:::
|
||||||
|
|
||||||
## 文件内容
|
## 应该写哪些内容
|
||||||
|
|
||||||
该文件有两个主要部分：
|
建议聚焦两类信息：**技术栈与版本**、**关键实现规则**。原则是记录“智能体不容易从代码片段直接推断”的内容。
|
||||||
|
|
||||||
### 技术栈与版本
|
### 1. 技术栈与版本
|
||||||
|
|
||||||
记录项目使用的框架、语言和工具及其具体版本：
|
|
||||||
|
|
||||||
```markdown
|
```markdown
|
||||||
## Technology Stack & Versions
|
## Technology Stack & Versions
|
||||||
|
|
@ -60,9 +56,7 @@ AI 智能体不断做出实施决策——遵循哪些模式、如何组织代
|
||||||
- Styling: Tailwind CSS with custom design tokens
|
- Styling: Tailwind CSS with custom design tokens
|
||||||
```
|
```
|
||||||
|
|
||||||
### 关键实施规则
|
### 2. 关键实现规则
|
||||||
|
|
||||||
记录智能体可能忽略的模式和约定：
|
|
||||||
|
|
||||||
```markdown
|
```markdown
|
||||||
## Critical Implementation Rules
|
## Critical Implementation Rules
|
||||||
|
|
@ -73,104 +67,28 @@ AI 智能体不断做出实施决策——遵循哪些模式、如何组织代
|
||||||
|
|
||||||
**Code Organization:**
|
**Code Organization:**
|
||||||
- Components in `/src/components/` with co-located `.test.tsx`
|
- 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
|
- API calls use the `apiClient` singleton — never fetch directly
|
||||||
|
|
||||||
**Testing Patterns:**
|
**Testing Patterns:**
|
||||||
- Unit tests focus on business logic, not implementation details
|
|
||||||
- Integration tests use MSW to mock API responses
|
- Integration tests use MSW to mock API responses
|
||||||
- E2E tests cover critical user journeys only
|
- 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
|
- [管理项目上下文（How-to）](../how-to/project-context.md)
|
||||||
# In your project root
|
- [既有项目常见问题](./established-projects-faq.md)
|
||||||
mkdir -p _bmad-output
|
- [工作流地图](../reference/workflow-map.md)
|
||||||
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 运行时。
|
|
||||||
|
|
|
||||||
|
|
@ -5,54 +5,53 @@ sidebar:
|
||||||
order: 3
|
order: 3
|
||||||
---
|
---
|
||||||
|
|
||||||
|
Phase 3（solutioning）把“要做什么”（planning 产出）转成“如何实现”（`architecture` 设计 + 工作拆分）。它的核心价值是：在开发前先把跨 `epic` 的关键技术决策写清楚，让后续 `story` 实施保持一致。
|
||||||
|
|
||||||
阶段 3（解决方案）将构建**什么**（来自规划）转化为**如何**构建（技术设计）。该阶段通过在实施开始前记录架构决策，防止多史诗项目中的智能体冲突。
|
## 不做 solutioning 会出现什么问题
|
||||||
|
|
||||||
## 没有解决方案阶段的问题
|
|
||||||
|
|
||||||
```text
|
```text
|
||||||
智能体 1 使用 REST API 实现史诗 1
|
智能体 1 使用 REST API 实现 Epic 1
|
||||||
智能体 2 使用 GraphQL 实现史诗 2
|
智能体 2 使用 GraphQL 实现 Epic 2
|
||||||
结果：API 设计不一致，集成噩梦
|
结果：API 设计不一致，集成成本暴涨
|
||||||
```
|
```
|
||||||
|
|
||||||
当多个智能体在没有共享架构指导的情况下实现系统的不同部分时，它们会做出可能冲突的独立技术决策。
|
当多个智能体在没有共享 `architecture` 指南的前提下并行实现不同 `epic`，它们会各自做局部最优决策，最后在集成阶段发生冲突。
|
||||||
|
|
||||||
## 有解决方案阶段的解决方案
|
## 做了 solutioning 后会发生什么
|
||||||
|
|
||||||
```text
|
```text
|
||||||
架构工作流决定："所有 API 使用 GraphQL"
|
architecture 工作流先定规则："所有 API 使用 GraphQL"
|
||||||
所有智能体遵循架构决策
|
所有智能体按同一套决策实现 story
|
||||||
结果：实现一致，无冲突
|
结果：实现一致，集成顺滑
|
||||||
```
|
```
|
||||||
|
|
||||||
通过明确记录技术决策，所有智能体都能一致地实现，集成变得简单直接。
|
solutioning 的本质不是“多写一份文档”，而是把高冲突风险决策前置，作为所有 `story` 的共享上下文。
|
||||||
|
|
||||||
## 解决方案阶段 vs 规划阶段
|
## solutioning 与 planning 的边界
|
||||||
|
|
||||||
| 方面 | 规划（阶段 2） | 解决方案（阶段 3） |
|
| 方面 | Planning（阶段 2） | Solutioning（阶段 3） |
|
||||||
| -------- | ----------------------- | --------------------------------- |
|
| -------- | ----------------------- | --------------------------------- |
|
||||||
| 问题 | 做什么和为什么？ | 如何做？然后是什么工作单元？ |
|
| 核心问题 | 做什么，为什么做？ | 如何做，再如何拆分工作？ |
|
||||||
| 输出 | FRs/NFRs（需求） | 架构 + 史诗/用户故事 |
|
| 输出物 | FRs/NFRs（需求） | `architecture` + `epic/story` 拆分 |
|
||||||
| 智能体 | PM | 架构师 → PM |
|
| 主导角色 | PM | Architect → PM |
|
||||||
| 受众 | 利益相关者 | 开发人员 |
|
| 受众 | 利益相关者 | 开发人员 |
|
||||||
| 文档 | PRD（FRs/NFRs） | 架构 + 史诗文件 |
|
| 文档 | PRD（FRs/NFRs） | 架构文档 + epics 文件 |
|
||||||
| 层级 | 业务逻辑 | 技术设计 + 工作分解 |
|
| 决策层级 | 业务目标与范围 | 技术策略与实现边界 |
|
||||||
|
|
||||||
## 核心原则
|
## 核心原则
|
||||||
|
|
||||||
**使技术决策明确且有文档记录**，以便所有智能体一致地实现。
|
**让跨 `epic` 的关键技术决策显式、可追溯、可复用。**
|
||||||
|
|
||||||
这可以防止：
|
这能直接降低：
|
||||||
- API 风格冲突（REST vs GraphQL）
|
- API 风格冲突（REST vs GraphQL）
|
||||||
- 数据库设计不一致
|
- 数据模型与命名约定不一致
|
||||||
- 状态管理分歧
|
- 状态管理方案分裂
|
||||||
- 命名约定不匹配
|
- 安全策略分叉
|
||||||
- 安全方法差异
|
- 中后期返工成本
|
||||||
|
|
||||||
## 何时需要解决方案阶段
|
## 什么时候需要 solutioning
|
||||||
|
|
||||||
| 流程 | 需要解决方案阶段？ |
|
| 流程 | 需要 solutioning？ |
|
||||||
|-------|----------------------|
|
|-------|----------------------|
|
||||||
| Quick Flow | 否 - 完全跳过 |
|
| Quick Flow | 否 - 完全跳过 |
|
||||||
| BMad Method Simple | 可选 |
|
| BMad Method Simple | 可选 |
|
||||||
|
|
@ -60,31 +59,24 @@ sidebar:
|
||||||
| Enterprise | 是 |
|
| Enterprise | 是 |
|
||||||
|
|
||||||
:::tip[经验法则]
|
:::tip[经验法则]
|
||||||
如果你有多个可能由不同智能体实现的史诗，你需要解决方案阶段。
|
只要需求会拆成多个 `epic`，并且可能由不同智能体并行实现，就应该做 solutioning。
|
||||||
:::
|
:::
|
||||||
|
|
||||||
## 跳过的代价
|
## 跳过 solutioning 的代价
|
||||||
|
|
||||||
在复杂项目中跳过解决方案阶段会导致：
|
在复杂项目中跳过该阶段，常见后果是：
|
||||||
|
|
||||||
- **集成问题**在冲刺中期发现
|
- **集成问题**在冲刺中期暴露
|
||||||
- **返工**由于实现冲突
|
- **返工**由实现冲突引发
|
||||||
- **开发时间更长**整体
|
- **整体研发周期拉长**
|
||||||
- **技术债务**来自不一致模式
|
- **技术债务**因模式不一致持续累积
|
||||||
|
|
||||||
:::caution[成本倍增]
|
:::caution[成本倍增]
|
||||||
在解决方案阶段发现对齐问题比在实施期间发现要快 10 倍。
|
在 solutioning 阶段发现对齐问题，通常比在实施中后期才发现更快、更便宜。
|
||||||
:::
|
:::
|
||||||
|
|
||||||
---
|
## 继续阅读
|
||||||
## 术语说明
|
|
||||||
|
|
||||||
- **agent**：智能体。在人工智能与编程文档中，指具备自主决策或执行能力的单元。
|
- [防止智能体冲突](./preventing-agent-conflicts.md)
|
||||||
- **epic**：史诗。在敏捷开发中，指一个大型的工作项，可分解为多个用户故事。
|
- [项目上下文](./project-context.md)
|
||||||
- **REST API**：表述性状态传递应用程序接口。一种基于 HTTP 协议的 Web API 设计风格。
|
- [工作流地图](../reference/workflow-map.md)
|
||||||
- **GraphQL**：一种用于 API 的查询语言和运行时环境。
|
|
||||||
- **FRs/NFRs**：功能需求/非功能需求。Functional Requirements/Non-Functional Requirements 的缩写。
|
|
||||||
- **PRD**：产品需求文档。Product Requirements Document 的缩写。
|
|
||||||
- **PM**：产品经理。Product Manager 的缩写。
|
|
||||||
- **sprint**：冲刺。敏捷开发中的固定时间周期，通常为 1-4 周。
|
|
||||||
- **technical debt**：技术债务。指为了短期目标而选择的不完美技术方案，未来需要付出额外成本来修复。
|
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue