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>

Author: lrliang

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)

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)