From 76fb7e067b5e9bea9c62e3083d2fd50a7d287bff Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=A2=81=E5=B1=B1=E6=B2=B3?= <392425595@qq.com> Date: Mon, 23 Mar 2026 00:27:41 +0800 Subject: [PATCH] docs(zh-cn): refine established project guides (#2096) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * docs(zh-cn): refine established project guides clarify the boundary between new-project and established-project usage so zh-cn readers can choose the right workflow path. align project context terminology and command references with current conventions while keeping guidance concise and executable. Feishu: https://www.feishu.cn/ Made-with: Cursor * docs(zh-cn): fix project-context syntax and wording 我将 project-context 文档中的提示块语法统一回项目规范的 `:::...:::` 形式，避免与文档风格约定不一致。 我同时把“在不同用户故事（story）间决策不一致”调整为“之间决策不一致”，提升中文表达的自然度与可读性。 Feishu: Made-with: Cursor --------- Co-authored-by: leon Co-authored-by: Alex Verkhovsky --- docs/zh-cn/how-to/established-projects.md | 80 ++++++--------- docs/zh-cn/how-to/project-context.md | 120 +++++++++------------- 2 files changed, 82 insertions(+), 118 deletions(-) diff --git a/docs/zh-cn/how-to/established-projects.md b/docs/zh-cn/how-to/established-projects.md index 515711862..9be085fce 100644 --- a/docs/zh-cn/how-to/established-projects.md +++ b/docs/zh-cn/how-to/established-projects.md @@ -5,9 +5,9 @@ sidebar: order: 6 --- -在现有项目和遗留代码库上工作时，有效使用 BMad Method。 +当你在现有项目或遗留代码库上工作时，本指南帮助你更稳妥地使用 BMad Method。 -本指南涵盖了使用 BMad Method 接入现有项目的核心工作流程。 +如果你是从零开始的新项目，建议先看[快速入门](../tutorials/getting-started.md)；本文主要面向既有项目接入场景。 :::note[前置条件] - 已安装 BMad Method（`npx bmad-method install`） @@ -23,16 +23,16 @@ sidebar: - `_bmad-output/planning-artifacts/` - `_bmad-output/implementation-artifacts/` -## 步骤 2：创建项目上下文 +## 步骤 2：创建项目上下文（project context） :::tip[推荐用于既有项目] -生成 `project-context.md` 以捕获你现有代码库的模式和约定。这确保 AI 智能体在实施变更时遵循你既定的实践。 +生成 `project-context.md`，梳理现有代码库的模式与约定，确保 AI 智能体在实施变更时遵循你既有的工程实践。 ::: -运行生成项目上下文工作流程： +运行生成项目上下文工作流： ```bash -/bmad-bmm-generate-project-context +bmad-generate-project-context ``` 这将扫描你的代码库以识别： @@ -40,9 +40,10 @@ sidebar: - 代码组织模式 - 命名约定 - 测试方法 -- 框架特定模式 +- 框架相关模式 -你可以查看和完善生成的文件，或者如果你更喜欢，可以在 `_bmad-output/project-context.md` 手动创建它。 +你可以先审阅并完善生成内容；如果更希望手动维护，也可以直接在 +`_bmad-output/project-context.md` 创建并编辑。 [了解更多关于项目上下文](../explanation/project-context.md) @@ -55,80 +56,63 @@ sidebar: - 架构 - 任何其他相关的项目信息 -对于复杂项目，考虑使用 `document-project` 工作流程。它提供运行时变体，将扫描你的整个项目并记录其实际当前状态。 +对于复杂项目，可考虑使用 `bmad-document-project` 工作流。它会扫描整个项目并记录当前真实状态。 -## 步骤 3：获取帮助 +## 步骤 4：获取帮助 -### BMad-Help：你的起点 +### BMad-Help：默认起点 -**随时运行 `bmad-help`，当你不确定下一步该做什么时。** 这个智能指南： +**当你不确定下一步做什么时，随时运行 `bmad-help`。** 这个智能指南会： -- 检查你的项目以查看已经完成了什么 -- 根据你安装的模块显示选项 +- 检查项目当前状态，识别哪些工作已经完成 +- 根据你安装的模块给出可行选项 - 理解自然语言查询 ``` bmad-help 我有一个现有的 Rails 应用，我应该从哪里开始？ -bmad-help quick-flow 和完整方法有什么区别？ -bmad-help 显示我有哪些可用的工作流程 +bmad-help Quick Flow 和完整方法有什么区别？ +bmad-help 显示我当前有哪些可用工作流 ``` -BMad-Help 还会在**每个工作流程结束时自动运行**，提供关于下一步该做什么的清晰指导。 +BMad-Help 还会在**每个工作流结束时自动运行**，明确告诉你下一步该做什么。 ### 选择你的方法 根据变更范围，你有两个主要选项： -| 范围 | 推荐方法 | -| ------------------------------ | ----------------------------------------------------------------------------------------------------------------- | -| **小型更新或添加** | 运行 `bmad-quick-dev` 在单个工作流中澄清意图、规划、实现和审查。完整的四阶段 BMad Method 可能有些过度。 | -| **重大变更或添加** | 从 BMad Method 开始，根据需要应用或多或少的严谨性。 | +| 范围 | 推荐方法 | +| --- | --- | +| **小型更新或新增** | 运行 `bmad-quick-dev`，在单个工作流中完成意图澄清、规划、实现与审查。完整四阶段 BMad Method 往往过重。 | +| **重大变更或新增** | 从完整 BMad Method 开始，再按项目风险和协作需求调整流程严谨度。 | ### 在创建 PRD 期间 在创建简报或直接进入 PRD 时，确保智能体： - 查找并分析你现有的项目文档 -- 阅读关于你当前系统的适当上下文 +- 读取与你当前系统匹配的项目上下文（project context） -你可以明确地指导智能体，但目标是确保新功能与你的现有系统良好集成。 +你可以显式补充指令，但核心目标是让新功能与现有 architecture 和代码约束自然融合。 ### UX 考量 -UX 工作是可选的。决定不取决于你的项目是否有 UX，而取决于： +UX 工作是可选项。是否需要进入 UX 流程，不取决于“项目里有没有 UX”，而取决于： -- 你是否将处理 UX 变更 -- 是否需要重要的新 UX 设计或模式 +- 你是否真的在做 UX 层面的变更 +- 是否需要新增重要的 UX 设计或交互模式 -如果你的变更只是对你满意的现有屏幕进行简单更新，则不需要完整的 UX 流程。 +如果本次只是对现有页面做小幅调整，通常不需要完整 UX 流程。 -### 架构考量 +### 架构考量（architecture） 在进行架构工作时，确保架构师： -- 使用适当的已记录文件 -- 扫描现有代码库 +- 使用正确且最新的文档输入 +- 扫描并理解现有代码库 -在此处要密切注意，以防止重新发明轮子或做出与你现有架构不一致的决定。 +这一点非常关键：可避免“重复造轮子”，也能减少与现有架构冲突的设计决策。 ## 更多信息 - **[快速修复](./quick-fixes.md)** - 错误修复和临时变更 - **[既有项目 FAQ](../explanation/established-projects-faq.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/zh-cn/how-to/project-context.md b/docs/zh-cn/how-to/project-context.md index 7693d2cb6..2025a6032 100644 --- a/docs/zh-cn/how-to/project-context.md +++ b/docs/zh-cn/how-to/project-context.md @@ -5,27 +5,30 @@ sidebar: order: 8 --- -使用 `project-context.md` 文件确保 AI 智能体在所有工作流程中遵循项目的技术偏好和实现规则。 +使用 `project-context.md`，确保 AI 智能体在各类工作流中遵循项目的技术偏好与实现规则。 +为了保证这份上下文始终可见，你也可以在工具上下文或 always-rules 文件（如 `AGENTS.md`） +中加入这句： +`Important project context and conventions are located in [path to project context]/project-context.md` :::note[前置条件] - 已安装 BMad Method -- 了解项目的技术栈和约定 +- 了解项目的技术栈与团队约定 ::: ## 何时使用 -- 在开始架构设计之前有明确的技术偏好 -- 已完成架构设计并希望为实施捕获决策 -- 正在处理具有既定模式的现有代码库 -- 注意到智能体在不同用户故事中做出不一致的决策 +- 在开始架构（architecture）前，你已有明确的技术偏好 +- 已完成架构设计，希望把关键决策沉淀到实施阶段 +- 正在处理具有既定模式的既有代码库 +- 发现智能体在不同用户故事（story）之间决策不一致 -## 步骤 1：选择方法 +## 步骤 1：选择路径 -**手动创建** — 当您确切知道要记录哪些规则时最佳 +**手动创建** — 适合你已经明确知道要沉淀哪些规则 -**架构后生成** — 最适合捕获解决方案制定过程中所做的决策 +**架构后生成** — 适合把 solutioning 阶段形成的架构决策沉淀下来 -**为现有项目生成** — 最适合在现有代码库中发现模式 +**为既有项目生成** — 适合从现有代码库中自动发现团队约定与模式 ## 步骤 2：创建文件 @@ -38,17 +41,17 @@ mkdir -p _bmad-output touch _bmad-output/project-context.md ``` -添加技术栈和实现规则： +然后补充技术栈与实现规则： ```markdown --- -project_name: 'MyProject' -user_name: 'YourName' +project_name: '我的项目' +user_name: '你的名字' date: '2026-02-15' sections_completed: ['technology_stack', 'critical_rules'] --- -# AI 智能体的项目上下文 +# AI 智能体项目上下文 ## 技术栈与版本 @@ -60,93 +63,70 @@ sections_completed: ['technology_stack', 'critical_rules'] ## 关键实现规则 **TypeScript：** -- 启用严格模式，不使用 `any` 类型 -- 公共 API 使用 `interface`，联合类型使用 `type` +- 开启严格模式，禁止使用 `any` 类型 +- 对外 API 使用 `interface`，联合类型使用 `type` **代码组织：** -- 组件位于 `/src/components/` 并附带同位置测试 -- API 调用使用 `apiClient` 单例 — 绝不直接使用 fetch +- 组件放在 `/src/components/`，并与测试文件同目录（co-located） +- API 调用统一使用 `apiClient` 单例，不要直接使用 `fetch` **测试：** -- 单元测试专注于业务逻辑 -- 集成测试使用 MSW 进行 API 模拟 +- 单元测试聚焦业务逻辑 +- 集成测试使用 MSW 模拟 API ``` ### 选项 B：架构后生成 -在新的聊天中运行工作流程： +在新的会话中运行： ```bash -/bmad-bmm-generate-project-context +bmad-generate-project-context ``` -工作流程扫描架构文档和项目文件，生成捕获所做决策的上下文文件。 +该工作流会扫描架构文档和项目文件，生成能够反映已做决策的上下文文件。 -### 选项 C：为现有项目生成 +### 选项 C：为既有项目生成 -对于现有项目，运行： +对于既有项目，运行： ```bash -/bmad-bmm-generate-project-context +bmad-generate-project-context ``` -工作流程分析代码库以识别约定，然后生成上下文文件供您审查和完善。 +该工作流会分析代码库中的约定，然后生成可供你审阅和完善的上下文文件。 ## 步骤 3：验证内容 -审查生成的文件并确保它捕获了： +审查生成文件，并确认它覆盖了： - 正确的技术版本 -- 实际约定（而非通用最佳实践） -- 防止常见错误的规则 -- 框架特定的模式 +- 你的真实约定（不是通用最佳实践） +- 能预防常见错误的规则 +- 框架相关模式 -手动编辑以添加任何缺失内容或删除不准确之处。 +如果有缺漏或误判，直接手动补充和修正。 -## 您将获得 +## 你将获得 -一个 `project-context.md` 文件，它： +一个 `project-context.md` 文件，它可以： -- 确保所有智能体遵循相同的约定 -- 防止在不同用户故事中做出不一致的决策 -- 为实施捕获架构决策 -- 作为项目模式和规则的参考 +- 确保所有智能体遵循相同约定 +- 避免在不同用户故事（story）中出现不一致决策 +- 为实施阶段保留架构决策 +- 作为项目模式与规则的长期参考 ## 提示 -:::tip[关注非显而易见的内容] -记录智能体可能遗漏的模式，例如"在每个公共类、函数和变量上使用 JSDoc 风格注释"，而不是像"使用有意义的变量名"这样的通用实践，因为 LLM 目前已经知道这些。 -::: - -:::tip[保持精简] -此文件由每个实施工作流程加载。长文件会浪费上下文。不要包含仅适用于狭窄范围或特定用户故事或功能的内容。 -::: - -:::tip[根据需要更新] -当模式发生变化时手动编辑，或在重大架构更改后重新生成。 -::: - -:::tip[适用于所有项目类型] -对于快速流程和完整的 BMad Method 项目同样有用。 +:::tip[最佳实践] +- **聚焦“不明显但重要”的规则**：优先记录智能体容易漏掉的项目约束，而不是 + “变量要有意义”这类通用建议。 +- **保持精简**：此文件会被多数实现工作流加载，过长会浪费上下文窗口。避免写入 + 只适用于单一 story 的细节。 +- **按需更新**：当团队约定变化时手动更新，或在架构发生较大变化后重新生成。 +- **适用于 Quick Flow 与完整 BMad Method**：两种模式都可共享同一份项目上下文。 ::: ## 后续步骤 -- [**项目上下文说明**](../explanation/project-context.md) — 了解其工作原理 -- [**工作流程图**](../reference/workflow-map.md) — 查看哪些工作流程加载项目上下文 - ---- -## 术语说明 - -- **agent**：智能体。在人工智能与编程文档中，指具备自主决策或执行能力的单元。 -- **workflow**：工作流程。指完成特定任务的一系列步骤或过程。 -- **codebase**：代码库。指项目的所有源代码和资源的集合。 -- **implementation**：实施。指将设计或架构转化为实际代码的过程。 -- **architecture**：架构。指系统的整体结构和设计。 -- **stack**：技术栈。指项目使用的技术组合，如编程语言、框架、工具等。 -- **convention**：约定。指团队或项目中遵循的编码规范和最佳实践。 -- **singleton**：单例。一种设计模式，确保类只有一个实例。 -- **co-located**：同位置。指相关文件（如测试文件）与主文件放在同一目录中。 -- **mocking**：模拟。在测试中用模拟对象替代真实对象的行为。 -- **context**：上下文。指程序运行时的环境信息或背景信息。 -- **LLM**：大语言模型。Large Language Model 的缩写，指大型语言模型。 +- [**项目上下文说明**](../explanation/project-context.md) - 了解其工作原理 +- [**工作流程图**](../reference/workflow-map.md) - 查看哪些工作流会加载项目上下文