From 0432e1c031151bb6ead17dfeb0722787404c8e44 Mon Sep 17 00:00:00 2001 From: Alex Verkhovsky Date: Tue, 6 Oct 2026 01:43:24 -0700 Subject: [PATCH 1/3] docs: remove locales from the site and the repo The docs site no longer carries five locales or the config that published them. --- CHANGELOG.md | 1 + README_CN.md | 98 ---- README_KR.md | 86 --- README_VN.md | 99 ---- docs-site/astro.config.mjs | 240 +------- docs-site/locale-coverage-baseline.json | 164 ------ docs-site/package.json | 3 +- docs-site/public/workflow-map-diagram-fr.html | 316 ---------- docs-site/public/workflow-map-diagram-ko.html | 543 ------------------ docs-site/public/workflow-map-diagram.html | 323 ----------- docs-site/scripts/build-docs.mjs | 8 - .../scripts/validate-locale-coverage.mjs | 184 ------ docs-site/src/content.config.ts | 5 +- docs-site/src/content/i18n/fr-FR.json | 28 - docs-site/src/content/i18n/ko-KR.json | 31 - docs-site/src/content/i18n/vi-VN.json | 28 - docs-site/src/content/i18n/zh-CN.json | 28 - docs-site/src/lib/locales.mjs | 43 -- docs-site/src/pages/404.astro | 20 - docs-site/test/test-english-only-site.mjs | 72 +++ .../test/test-validate-locale-coverage.mjs | 168 ------ docs/cs/404.md | 8 - docs/cs/_STYLE_GUIDE.md | 371 ------------ docs/cs/explanation/advanced-elicitation.md | 49 -- docs/cs/explanation/analysis-phase.md | 70 --- docs/cs/explanation/brainstorming.md | 33 -- docs/cs/explanation/build.md | 77 --- .../explanation/established-projects-faq.md | 50 -- docs/cs/explanation/party-mode.md | 59 -- .../explanation/preventing-agent-conflicts.md | 112 ---- docs/cs/explanation/project-context.md | 155 ----- .../cs/explanation/why-solutioning-matters.md | 78 --- docs/cs/how-to/customize-bmad.md | 171 ------ docs/cs/how-to/established-projects.md | 117 ---- docs/cs/how-to/get-answers-about-bmad.md | 105 ---- docs/cs/how-to/install-bmad.md | 114 ---- docs/cs/how-to/project-context.md | 127 ---- docs/cs/how-to/quick-fixes.md | 95 --- docs/cs/how-to/upgrade-to-v6.md | 100 ---- docs/cs/index.md | 56 -- docs/cs/reference/agents.md | 34 -- docs/cs/reference/commands.md | 134 ----- docs/cs/reference/core-tools.md | 216 ------- docs/cs/reference/modules.md | 76 --- docs/cs/reference/testing.md | 106 ---- docs/cs/reference/workflow-map.md | 83 --- docs/cs/tutorials/getting-started.md | 276 --------- docs/fr/404.md | 8 - docs/fr/_STYLE_GUIDE.md | 372 ------------ docs/fr/build/walk-through-a-change.md | 92 --- docs/fr/explanation/advanced-elicitation.md | 49 -- docs/fr/explanation/analysis-phase.md | 74 --- docs/fr/explanation/brainstorming.md | 33 -- docs/fr/explanation/build.md | 83 --- .../explanation/established-projects-faq.md | 50 -- docs/fr/explanation/named-agents.md | 97 ---- docs/fr/explanation/party-mode.md | 64 --- .../explanation/preventing-agent-conflicts.md | 117 ---- docs/fr/explanation/project-context.md | 156 ----- .../fr/explanation/why-solutioning-matters.md | 87 --- docs/fr/how-to/customize-bmad.md | 399 ------------- docs/fr/how-to/established-projects.md | 122 ---- docs/fr/how-to/expand-bmad-for-your-org.md | 328 ----------- docs/fr/how-to/get-answers-about-bmad.md | 81 --- docs/fr/how-to/install-bmad.md | 266 --------- docs/fr/how-to/install-custom-modules.md | 181 ------ docs/fr/how-to/project-context.md | 127 ---- docs/fr/how-to/quick-fixes.md | 98 ---- docs/fr/how-to/upgrade-to-v6.md | 107 ---- docs/fr/index.md | 65 --- docs/fr/reference/agents.md | 39 -- docs/fr/reference/commands.md | 140 ----- docs/fr/reference/core-tools.md | 222 ------- docs/fr/reference/modules.md | 82 --- docs/fr/reference/testing.md | 111 ---- docs/fr/reference/workflow-map.md | 120 ---- docs/fr/tutorials/getting-started.md | 298 ---------- docs/ko-kr/404.md | 8 - docs/ko-kr/_STYLE_GUIDE.md | 383 ------------ docs/ko-kr/build/build-a-change.md | 117 ---- docs/ko-kr/build/test-completed-work.md | 79 --- docs/ko-kr/build/walk-through-a-change.md | 90 --- .../ko-kr/explanation/advanced-elicitation.md | 49 -- docs/ko-kr/explanation/analysis-phase.md | 72 --- docs/ko-kr/explanation/brainstorming.md | 33 -- docs/ko-kr/explanation/deep-recon.md | 125 ---- .../explanation/established-projects-faq.md | 51 -- docs/ko-kr/explanation/forge-idea.md | 78 --- docs/ko-kr/explanation/named-agents.md | 101 ---- docs/ko-kr/explanation/party-mode.md | 167 ------ .../explanation/preventing-agent-conflicts.md | 121 ---- .../explanation/project-context-theory.md | 103 ---- docs/ko-kr/explanation/project-context.md | 57 -- docs/ko-kr/explanation/retrospective.md | 68 --- .../explanation/why-solutioning-matters.md | 79 --- .../ko-kr/how-to/choose-a-development-path.md | 118 ---- docs/ko-kr/how-to/customize-bmad.md | 399 ------------- docs/ko-kr/how-to/established-projects.md | 111 ---- docs/ko-kr/how-to/expand-bmad-for-your-org.md | 332 ----------- docs/ko-kr/how-to/get-answers-about-bmad.md | 80 --- docs/ko-kr/how-to/install-custom-modules.md | 181 ------ docs/ko-kr/how-to/pressure-test-an-idea.md | 55 -- docs/ko-kr/how-to/project-context.md | 76 --- docs/ko-kr/how-to/upgrade-to-v6.md | 101 ---- docs/ko-kr/index.md | 45 -- docs/ko-kr/reference/agents.md | 34 -- docs/ko-kr/reference/build-auto.md | 258 --------- docs/ko-kr/reference/commands.md | 136 ----- docs/ko-kr/reference/core-tools.md | 255 -------- docs/ko-kr/reference/modules.md | 76 --- docs/ko-kr/reference/workflow-map.md | 102 ---- docs/ko-kr/start/build-your-first-change.md | 98 ---- docs/ko-kr/start/install-bmad.md | 88 --- docs/ko-kr/tutorials/getting-deeper.md | 230 -------- docs/vi-vn/404.md | 8 - docs/vi-vn/_STYLE_GUIDE.md | 371 ------------ docs/vi-vn/bmad-developer-guide.md | 18 - docs/vi-vn/build/walk-through-a-change.md | 92 --- .../vi-vn/explanation/advanced-elicitation.md | 49 -- docs/vi-vn/explanation/analysis-phase.md | 70 --- docs/vi-vn/explanation/brainstorming.md | 33 -- docs/vi-vn/explanation/build.md | 77 --- .../explanation/established-projects-faq.md | 51 -- docs/vi-vn/explanation/named-agents.md | 97 ---- docs/vi-vn/explanation/party-mode.md | 59 -- .../explanation/preventing-agent-conflicts.md | 112 ---- docs/vi-vn/explanation/project-context.md | 155 ----- .../explanation/why-solutioning-matters.md | 78 --- docs/vi-vn/how-to/customize-bmad.md | 399 ------------- docs/vi-vn/how-to/established-projects.md | 117 ---- docs/vi-vn/how-to/expand-bmad-for-your-org.md | 266 --------- docs/vi-vn/how-to/get-answers-about-bmad.md | 81 --- docs/vi-vn/how-to/install-bmad.md | 114 ---- docs/vi-vn/how-to/install-custom-modules.md | 181 ------ docs/vi-vn/how-to/project-context.md | 127 ---- docs/vi-vn/how-to/quick-fixes.md | 95 --- docs/vi-vn/how-to/upgrade-to-v6.md | 100 ---- docs/vi-vn/index.md | 56 -- docs/vi-vn/reference/agents.md | 34 -- docs/vi-vn/reference/commands.md | 134 ----- docs/vi-vn/reference/core-tools.md | 216 ------- docs/vi-vn/reference/modules.md | 76 --- docs/vi-vn/reference/testing.md | 106 ---- docs/vi-vn/reference/workflow-map.md | 83 --- docs/vi-vn/tutorials/getting-started.md | 276 --------- docs/zh-cn/404.md | 9 - docs/zh-cn/_STYLE_GUIDE.md | 371 ------------ docs/zh-cn/build/walk-through-a-change.md | 92 --- .../zh-cn/explanation/advanced-elicitation.md | 58 -- docs/zh-cn/explanation/analysis-phase.md | 70 --- docs/zh-cn/explanation/brainstorming.md | 63 -- docs/zh-cn/explanation/build.md | 91 --- .../explanation/established-projects-faq.md | 61 -- docs/zh-cn/explanation/forge-idea.md | 76 --- docs/zh-cn/explanation/named-agents.md | 97 ---- docs/zh-cn/explanation/party-mode.md | 60 -- .../explanation/preventing-agent-conflicts.md | 118 ---- docs/zh-cn/explanation/project-context.md | 94 --- .../explanation/why-solutioning-matters.md | 86 --- docs/zh-cn/how-to/customize-bmad.md | 175 ------ docs/zh-cn/how-to/established-projects.md | 118 ---- docs/zh-cn/how-to/expand-bmad-for-your-org.md | 258 --------- docs/zh-cn/how-to/get-answers-about-bmad.md | 129 ----- docs/zh-cn/how-to/install-bmad.md | 117 ---- docs/zh-cn/how-to/install-custom-modules.md | 181 ------ docs/zh-cn/how-to/pressure-test-an-idea.md | 55 -- docs/zh-cn/how-to/project-context.md | 132 ----- docs/zh-cn/how-to/quick-fixes.md | 95 --- docs/zh-cn/how-to/upgrade-to-v6.md | 111 ---- docs/zh-cn/index.md | 56 -- docs/zh-cn/reference/agents.md | 40 -- docs/zh-cn/reference/build-auto.md | 226 -------- docs/zh-cn/reference/commands.md | 120 ---- docs/zh-cn/reference/core-tools.md | 182 ------ docs/zh-cn/reference/modules.md | 94 --- docs/zh-cn/reference/testing.md | 105 ---- docs/zh-cn/reference/workflow-map.md | 80 --- docs/zh-cn/tutorials/getting-started.md | 275 --------- 178 files changed, 79 insertions(+), 21531 deletions(-) delete mode 100644 README_CN.md delete mode 100644 README_KR.md delete mode 100644 README_VN.md delete mode 100644 docs-site/locale-coverage-baseline.json delete mode 100644 docs-site/public/workflow-map-diagram-fr.html delete mode 100644 docs-site/public/workflow-map-diagram-ko.html delete mode 100644 docs-site/public/workflow-map-diagram.html delete mode 100644 docs-site/scripts/validate-locale-coverage.mjs delete mode 100644 docs-site/src/content/i18n/fr-FR.json delete mode 100644 docs-site/src/content/i18n/ko-KR.json delete mode 100644 docs-site/src/content/i18n/vi-VN.json delete mode 100644 docs-site/src/content/i18n/zh-CN.json delete mode 100644 docs-site/src/lib/locales.mjs create mode 100644 docs-site/test/test-english-only-site.mjs delete mode 100644 docs-site/test/test-validate-locale-coverage.mjs delete mode 100644 docs/cs/404.md delete mode 100644 docs/cs/_STYLE_GUIDE.md delete mode 100644 docs/cs/explanation/advanced-elicitation.md delete mode 100644 docs/cs/explanation/analysis-phase.md delete mode 100644 docs/cs/explanation/brainstorming.md delete mode 100644 docs/cs/explanation/build.md delete mode 100644 docs/cs/explanation/established-projects-faq.md delete mode 100644 docs/cs/explanation/party-mode.md delete mode 100644 docs/cs/explanation/preventing-agent-conflicts.md delete mode 100644 docs/cs/explanation/project-context.md delete mode 100644 docs/cs/explanation/why-solutioning-matters.md delete mode 100644 docs/cs/how-to/customize-bmad.md delete mode 100644 docs/cs/how-to/established-projects.md delete mode 100644 docs/cs/how-to/get-answers-about-bmad.md delete mode 100644 docs/cs/how-to/install-bmad.md delete mode 100644 docs/cs/how-to/project-context.md delete mode 100644 docs/cs/how-to/quick-fixes.md delete mode 100644 docs/cs/how-to/upgrade-to-v6.md delete mode 100644 docs/cs/index.md delete mode 100644 docs/cs/reference/agents.md delete mode 100644 docs/cs/reference/commands.md delete mode 100644 docs/cs/reference/core-tools.md delete mode 100644 docs/cs/reference/modules.md delete mode 100644 docs/cs/reference/testing.md delete mode 100644 docs/cs/reference/workflow-map.md delete mode 100644 docs/cs/tutorials/getting-started.md delete mode 100644 docs/fr/404.md delete mode 100644 docs/fr/_STYLE_GUIDE.md delete mode 100644 docs/fr/build/walk-through-a-change.md delete mode 100644 docs/fr/explanation/advanced-elicitation.md delete mode 100644 docs/fr/explanation/analysis-phase.md delete mode 100644 docs/fr/explanation/brainstorming.md delete mode 100644 docs/fr/explanation/build.md delete mode 100644 docs/fr/explanation/established-projects-faq.md delete mode 100644 docs/fr/explanation/named-agents.md delete mode 100644 docs/fr/explanation/party-mode.md delete mode 100644 docs/fr/explanation/preventing-agent-conflicts.md delete mode 100644 docs/fr/explanation/project-context.md delete mode 100644 docs/fr/explanation/why-solutioning-matters.md delete mode 100644 docs/fr/how-to/customize-bmad.md delete mode 100644 docs/fr/how-to/established-projects.md delete mode 100644 docs/fr/how-to/expand-bmad-for-your-org.md delete mode 100644 docs/fr/how-to/get-answers-about-bmad.md delete mode 100644 docs/fr/how-to/install-bmad.md delete mode 100644 docs/fr/how-to/install-custom-modules.md delete mode 100644 docs/fr/how-to/project-context.md delete mode 100644 docs/fr/how-to/quick-fixes.md delete mode 100644 docs/fr/how-to/upgrade-to-v6.md delete mode 100644 docs/fr/index.md delete mode 100644 docs/fr/reference/agents.md delete mode 100644 docs/fr/reference/commands.md delete mode 100644 docs/fr/reference/core-tools.md delete mode 100644 docs/fr/reference/modules.md delete mode 100644 docs/fr/reference/testing.md delete mode 100644 docs/fr/reference/workflow-map.md delete mode 100644 docs/fr/tutorials/getting-started.md delete mode 100644 docs/ko-kr/404.md delete mode 100644 docs/ko-kr/_STYLE_GUIDE.md delete mode 100644 docs/ko-kr/build/build-a-change.md delete mode 100644 docs/ko-kr/build/test-completed-work.md delete mode 100644 docs/ko-kr/build/walk-through-a-change.md delete mode 100644 docs/ko-kr/explanation/advanced-elicitation.md delete mode 100644 docs/ko-kr/explanation/analysis-phase.md delete mode 100644 docs/ko-kr/explanation/brainstorming.md delete mode 100644 docs/ko-kr/explanation/deep-recon.md delete mode 100644 docs/ko-kr/explanation/established-projects-faq.md delete mode 100644 docs/ko-kr/explanation/forge-idea.md delete mode 100644 docs/ko-kr/explanation/named-agents.md delete mode 100644 docs/ko-kr/explanation/party-mode.md delete mode 100644 docs/ko-kr/explanation/preventing-agent-conflicts.md delete mode 100644 docs/ko-kr/explanation/project-context-theory.md delete mode 100644 docs/ko-kr/explanation/project-context.md delete mode 100644 docs/ko-kr/explanation/retrospective.md delete mode 100644 docs/ko-kr/explanation/why-solutioning-matters.md delete mode 100644 docs/ko-kr/how-to/choose-a-development-path.md delete mode 100644 docs/ko-kr/how-to/customize-bmad.md delete mode 100644 docs/ko-kr/how-to/established-projects.md delete mode 100644 docs/ko-kr/how-to/expand-bmad-for-your-org.md delete mode 100644 docs/ko-kr/how-to/get-answers-about-bmad.md delete mode 100644 docs/ko-kr/how-to/install-custom-modules.md delete mode 100644 docs/ko-kr/how-to/pressure-test-an-idea.md delete mode 100644 docs/ko-kr/how-to/project-context.md delete mode 100644 docs/ko-kr/how-to/upgrade-to-v6.md delete mode 100644 docs/ko-kr/index.md delete mode 100644 docs/ko-kr/reference/agents.md delete mode 100644 docs/ko-kr/reference/build-auto.md delete mode 100644 docs/ko-kr/reference/commands.md delete mode 100644 docs/ko-kr/reference/core-tools.md delete mode 100644 docs/ko-kr/reference/modules.md delete mode 100644 docs/ko-kr/reference/workflow-map.md delete mode 100644 docs/ko-kr/start/build-your-first-change.md delete mode 100644 docs/ko-kr/start/install-bmad.md delete mode 100644 docs/ko-kr/tutorials/getting-deeper.md delete mode 100644 docs/vi-vn/404.md delete mode 100644 docs/vi-vn/_STYLE_GUIDE.md delete mode 100644 docs/vi-vn/bmad-developer-guide.md delete mode 100644 docs/vi-vn/build/walk-through-a-change.md delete mode 100644 docs/vi-vn/explanation/advanced-elicitation.md delete mode 100644 docs/vi-vn/explanation/analysis-phase.md delete mode 100644 docs/vi-vn/explanation/brainstorming.md delete mode 100644 docs/vi-vn/explanation/build.md delete mode 100644 docs/vi-vn/explanation/established-projects-faq.md delete mode 100644 docs/vi-vn/explanation/named-agents.md delete mode 100644 docs/vi-vn/explanation/party-mode.md delete mode 100644 docs/vi-vn/explanation/preventing-agent-conflicts.md delete mode 100644 docs/vi-vn/explanation/project-context.md delete mode 100644 docs/vi-vn/explanation/why-solutioning-matters.md delete mode 100644 docs/vi-vn/how-to/customize-bmad.md delete mode 100644 docs/vi-vn/how-to/established-projects.md delete mode 100644 docs/vi-vn/how-to/expand-bmad-for-your-org.md delete mode 100644 docs/vi-vn/how-to/get-answers-about-bmad.md delete mode 100644 docs/vi-vn/how-to/install-bmad.md delete mode 100644 docs/vi-vn/how-to/install-custom-modules.md delete mode 100644 docs/vi-vn/how-to/project-context.md delete mode 100644 docs/vi-vn/how-to/quick-fixes.md delete mode 100644 docs/vi-vn/how-to/upgrade-to-v6.md delete mode 100644 docs/vi-vn/index.md delete mode 100644 docs/vi-vn/reference/agents.md delete mode 100644 docs/vi-vn/reference/commands.md delete mode 100644 docs/vi-vn/reference/core-tools.md delete mode 100644 docs/vi-vn/reference/modules.md delete mode 100644 docs/vi-vn/reference/testing.md delete mode 100644 docs/vi-vn/reference/workflow-map.md delete mode 100644 docs/vi-vn/tutorials/getting-started.md delete mode 100644 docs/zh-cn/404.md delete mode 100644 docs/zh-cn/_STYLE_GUIDE.md delete mode 100644 docs/zh-cn/build/walk-through-a-change.md delete mode 100644 docs/zh-cn/explanation/advanced-elicitation.md delete mode 100644 docs/zh-cn/explanation/analysis-phase.md delete mode 100644 docs/zh-cn/explanation/brainstorming.md delete mode 100644 docs/zh-cn/explanation/build.md delete mode 100644 docs/zh-cn/explanation/established-projects-faq.md delete mode 100644 docs/zh-cn/explanation/forge-idea.md delete mode 100644 docs/zh-cn/explanation/named-agents.md delete mode 100644 docs/zh-cn/explanation/party-mode.md delete mode 100644 docs/zh-cn/explanation/preventing-agent-conflicts.md delete mode 100644 docs/zh-cn/explanation/project-context.md delete mode 100644 docs/zh-cn/explanation/why-solutioning-matters.md delete mode 100644 docs/zh-cn/how-to/customize-bmad.md delete mode 100644 docs/zh-cn/how-to/established-projects.md delete mode 100644 docs/zh-cn/how-to/expand-bmad-for-your-org.md delete mode 100644 docs/zh-cn/how-to/get-answers-about-bmad.md delete mode 100644 docs/zh-cn/how-to/install-bmad.md delete mode 100644 docs/zh-cn/how-to/install-custom-modules.md delete mode 100644 docs/zh-cn/how-to/pressure-test-an-idea.md delete mode 100644 docs/zh-cn/how-to/project-context.md delete mode 100644 docs/zh-cn/how-to/quick-fixes.md delete mode 100644 docs/zh-cn/how-to/upgrade-to-v6.md delete mode 100644 docs/zh-cn/index.md delete mode 100644 docs/zh-cn/reference/agents.md delete mode 100644 docs/zh-cn/reference/build-auto.md delete mode 100644 docs/zh-cn/reference/commands.md delete mode 100644 docs/zh-cn/reference/core-tools.md delete mode 100644 docs/zh-cn/reference/modules.md delete mode 100644 docs/zh-cn/reference/testing.md delete mode 100644 docs/zh-cn/reference/workflow-map.md delete mode 100644 docs/zh-cn/tutorials/getting-started.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 0e60512cc4..0535c86c45 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,7 @@ ### 💥 Breaking +* Translated documentation is removed. The docs site is English-only, and `/fr/`, `/cs/`, `/ko-kr/`, `/vi-vn/`, and `/zh-cn/` URLs 404. * `planning_artifacts` and `implementation_artifacts` are no longer read or seeded. Run `bmad migrate method` on a v6 project. * The ticketing store's `root` key is gone; the ticket tree is `{output_folder}/{active_initiative}`. To move the store, set `core.output_folder` in `_bmad/custom/config.toml`. * `active_initiative` is now a core setting: it moved from `[modules.bmm]` to `[core]` in `_bmad/custom/config.user.toml`, since core skills such as brainstorming and research also write into the initiative folder. If you set it on a preview build, move the line. diff --git a/README_CN.md b/README_CN.md deleted file mode 100644 index 41a4e8597e..0000000000 --- a/README_CN.md +++ /dev/null @@ -1,98 +0,0 @@ -![BMad Method](banner-bmad-method.png) - -[![Version](https://img.shields.io/npm/v/bmad-method?color=blue&label=version)](https://www.npmjs.com/package/bmad-method) -[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE) -[![Node.js Version](https://img.shields.io/badge/node-%3E%3D20.0.0-brightgreen)](https://nodejs.org) -[![Discord](https://img.shields.io/badge/Discord-Join%20Community-7289da?logo=discord&logoColor=white)](https://discord.gg/gk8jAdXWmj) - -**Agile Ai Driven Development（敏捷 AI 驱动开发）** —— Ai Driven Development（AiDD）关注的不只是代码，还包括做什么、如何组织，以及在认知变化时如何调整。BMad Method 是实践 AiDD 的敏捷方式：决策保持显式，上下文持续传递，流程随工作量自动调整。同一套方法既适用于周末原型，也适用于有多年历史的系统。 - -**100% 免费且开源。** 没有付费墙，没有封闭内容，也没有封闭 Discord。我们希望每个人都能平等获得高质量的人机协作开发方法。 - -## 为什么选择 BMad 方法？ - -传统 AI 工具常常替你思考，结果往往止于“能用”。BMad 通过专业智能体和引导式工作流，让 AI 成为协作者：流程有结构，决策有依据，产出更稳定。 - -- **AI 智能引导** —— 随时调用 `bmad-help` 获取下一步建议 -- **规模与领域自适应** —— 按项目复杂度自动调整规划深度 -- **结构化工作流** —— 覆盖分析、规划、架构、实施全流程 -- **专业角色智能体** —— 提供 PM、架构师、开发者、UX 等 12+ 角色 -- **派对模式** —— 多个智能体可在同一会话协作讨论 -- **完整生命周期** —— 从头脑风暴一路到交付上线 - -[在 **docs.bmad-method.org** 了解更多](https://docs.bmad-method.org/zh-cn/) - ---- - -## 快速开始 - -**先决条件**：[Node.js](https://nodejs.org) v20+ - -```bash -npx bmad-method install -``` - -> 想体验最新预发布版本？可使用 `npx bmad-method@next install`。它比默认版本更新更快，也可能更容易发生变化。 - -按照安装程序提示操作，然后在项目文件夹中打开你的 AI IDE（Claude Code、Cursor 等）。 - -**非交互式安装**（用于 CI/CD）： - -```bash -npx bmad-method install --directory /path/to/project --modules bmm --tools claude-code --yes -``` - -> **不确定下一步？** 直接问 `bmad-help`。它会告诉你“必做什么、可选什么”，例如：`bmad-help 我刚完成架构设计，接下来做什么？` - -## 模块 - -BMad 可通过官方模块扩展到不同专业场景。你可以在安装时选择，也可以后续随时补装。 - -| 模块 | 用途 | -| ---------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | -| **[BMad Method](https://github.com/bmad-code-org/BMAD-METHOD)** | 规划并交付软件，覆盖全新原型到成熟代码库 | -| **[BMad Builder](https://github.com/bmad-code-org/bmad-builder)** | 技能、工作流与智能体构建器 | -| **[BMad Creative Intelligence Suite](https://github.com/bmad-code-org/bmad-module-creative-intelligence-suite)** | 创意思考伙伴：创新、设计思维与叙事 | -| **[BMad Test Architect](https://github.com/bmad-code-org/bmad-method-test-architecture-enterprise)** | 面向 BMad Method 的企业级测试扩展模块 | -| **[BMad Loop](https://github.com/bmad-code-org/bmad-loop)** | 无人值守地构建、验证并复盘整个 Epic | -| **[BMad Game Dev Studio](https://github.com/bmad-code-org/bmad-module-game-dev-studio)** | 构思、设计并开发游戏，支持任意框架，包括 Unity、Unreal、Godot 与 Phaser | - -## 文档 - -[BMad 方法文档站点](https://docs.bmad-method.org/zh-cn/) — 教程、指南、概念和参考 - -**快速链接：** - -- [入门教程](https://docs.bmad-method.org/zh-cn/tutorials/getting-started/) -- [从旧版本升级](https://docs.bmad-method.org/zh-cn/how-to/upgrade-to-v6/) -- [测试架构师文档（英文）](https://bmad-code-org.github.io/bmad-method-test-architecture-enterprise/) - -## 社区 - -- [Discord](https://discord.gg/gk8jAdXWmj) — 获取帮助、分享想法、协作 -- [在 YouTube 上订阅](https://www.youtube.com/@BMadCode) — 教程、大师课和播客（2025 年 2 月推出） -- [GitHub Issues](https://github.com/bmad-code-org/BMAD-METHOD/issues) — 错误报告和功能请求 -- [讨论](https://github.com/bmad-code-org/BMAD-METHOD/discussions) — 社区对话 - -## 支持 BMad - -BMad 对所有人免费，而且会一直免费。如果你愿意支持项目发展： - -- ⭐ 给仓库点个 Star -- ☕ [请我喝咖啡](https://buymeacoffee.com/bmad) — 为开发提供动力 -- 🏢 企业赞助 — 在 Discord 上私信 -- 🎤 演讲与媒体 — 可参加会议、播客、采访（在 Discord 上联系 BM） - -## 贡献 - -我们欢迎贡献！请参阅 [CONTRIBUTING.md](CONTRIBUTING.md) 了解指南。 - -## 许可证 - -MIT 许可证 — 详见 [LICENSE](LICENSE)。 - ---- - -**BMad** 和 **BMAD-METHOD** 是 BMad Code, LLC 的商标。详见 [TRADEMARK.md](TRADEMARK.md)。 - -请参阅 [CONTRIBUTORS.md](CONTRIBUTORS.md) 了解贡献者信息。 diff --git a/README_KR.md b/README_KR.md deleted file mode 100644 index 552d13ea3b..0000000000 --- a/README_KR.md +++ /dev/null @@ -1,86 +0,0 @@ -![BMad Method](banner-bmad-method.png) - -[![버전](https://img.shields.io/npm/v/bmad-method?color=blue&label=%EB%B2%84%EC%A0%84)](https://www.npmjs.com/package/bmad-method) -[![라이선스: MIT](https://img.shields.io/badge/%EB%9D%BC%EC%9D%B4%EC%84%A0%EC%8A%A4-MIT-yellow.svg)](LICENSE) -[![Discord](https://img.shields.io/badge/Discord-%EC%BB%A4%EB%AE%A4%EB%8B%88%ED%8B%B0%20%EC%B0%B8%EC%97%AC-7289da?logo=discord&logoColor=white)](https://discord.gg/gk8jAdXWmj) - -[English](README.md) | [简体中文](README_CN.md) | [Tiếng Việt](README_VN.md) | 한국어 - -**애자일 AI 주도 개발 — 사고 과정을 포기하지 않고 아이디어나 변경 요청을 실제 작동하는 소프트웨어로 바꿉니다.** - -AI 주도 개발(AiDD)은 코드 작성에 그치지 않습니다. 무엇을 만들지, 각 요소가 어떻게 맞물리는지, 새롭게 알게 된 내용에 따라 어떻게 바꿀지까지 개발 전반을 아우릅니다. BMad Method는 이를 애자일 방식으로 실천합니다. 결정은 명확히 남고 컨텍스트는 다음 작업으로 이어지며 작업 규모에 맞춰 절차도 달라집니다. 작은 변경은 바로 Build로 진행하고 복잡한 작업은 필요한 만큼 깊이 계획합니다. 주말에 만드는 프로토타입부터 오랜 역사를 지닌 시스템까지 같은 방법으로 다룹니다. - -![BMad 전달 루프: 막연한 생각은 구체화부터, 크고 명확한 아이디어는 계획부터 시작하며 작은 변경은 바로 구현 및 검증으로 이어집니다. 학습 및 조정 단계에서 얻은 내용은 다시 계획에 반영됩니다.](docs/images/bmad-delivery-loop-ko.svg) - -_어디서든 시작하세요. BMad를 처음부터 끝까지 사용해도 되고 개요·사양·아키텍처만 기존 개발 흐름에 가져와도 됩니다._ - -## 바로 시작하기 - -**필수 조건:** [Node.js](https://nodejs.org) 20.12+, [Python](https://www.python.org) 3.10+, [uv](https://docs.astral.sh/uv/) - -```bash -npx bmad-method install -``` - -프로젝트를 AI 코딩 도구에서 열고 `bmad-build`에 원하는 변경을 말하세요. 중요한 결정은 직접 내리면서 작업을 이어 가면 됩니다. 다음 단계나 선택 사항을 안내받고 싶을 때는 언제든 `bmad-help`를 실행하세요. - -**[BMad로 첫 변경 사항 구현하기 →](https://docs.bmad-method.org/ko-kr/start/build-your-first-change/)** - -**[기존 코드베이스에 BMad 적용하기 →](https://docs.bmad-method.org/ko-kr/how-to/established-projects/)** - -BMad는 무료 오픈 소스이며 유료 전용 워크플로나 가입이 제한된 커뮤니티가 없습니다. 설치 필수 조건, 업데이트, 사전 릴리스 빌드, 설치 프로그램의 최신 자동화 도움말은 [설치 가이드](https://docs.bmad-method.org/ko-kr/start/install-bmad/)를 참고하세요. - -## 왜 BMad인가요? - -코딩 도우미는 구현에는 능숙하지만 명시하지 않은 가정을 그대로 코드로 옮기기도 합니다. BMad는 중요한 결정을 명확히 드러내고 다음 작업에 필요한 컨텍스트로 남기는 에이전트와 워크플로를 제공합니다. 판단은 사용자가 직접 내립니다. - -- **작업에 맞는 절차** — 명확한 변경은 바로 구현하고 큰 과제는 더 깊이 계획합니다. -- **신규·기존 코드 모두 지원** — 빈 프로젝트에서 시작하거나, 물려받은 코드베이스의 컨텍스트를 검증해 현재 상태에 맞춰 작업합니다. -- **지속되는 컨텍스트** — 대화할 때마다 다시 설명하지 않아도 제품과 기술 결정을 다음 작업으로 이어 갑니다. -- **분야별 관점** — 필요할 때 제품, 아키텍처, UX, 개발, 테스트 전문가의 관점을 활용합니다. -- **안내형 협업** — 판단을 맡기지 않고도 구조화된 워크플로와 여러 에이전트의 토론을 활용합니다. -- **하나로 이어지는 개발 흐름** — 초기 구상부터 검토를 거친 구현, 방향 수정, 학습까지 한 흐름으로 진행합니다. - -[워크플로가 어떻게 연결되는지 보기 →](https://docs.bmad-method.org/ko-kr/reference/workflow-map/) - -## BMad 생태계 - -핵심 프레임워크만 설치하거나 전문 작업을 위한 공식 모듈을 추가합니다. - -| 모듈 | 용도 | -| --- | --- | -| **[BMad Method](https://github.com/bmad-code-org/BMAD-METHOD)** | 새 프로토타입부터 기존 코드베이스까지 소프트웨어를 계획하고 완성합니다. | -| **[BMad Builder](https://github.com/bmad-code-org/bmad-builder)** | 스킬, 워크플로, 에이전트를 만듭니다. | -| **[BMad Creative Intelligence Suite](https://github.com/bmad-code-org/bmad-module-creative-intelligence-suite)** | 혁신, 디자인 사고, 스토리텔링을 위한 창의적 사고 파트너를 제공합니다. | -| **[BMad Test Architect](https://github.com/bmad-code-org/bmad-method-test-architecture-enterprise)** | BMad Method에 엔터프라이즈 테스트 기능을 더합니다. | -| **[BMad Loop](https://github.com/bmad-code-org/bmad-loop)** | 에픽 전체를 사람의 개입 없이 구현하고 검증한 뒤 회고합니다. | -| **[BMad Game Dev Studio](https://github.com/bmad-code-org/bmad-module-game-dev-studio)** | Unity, Unreal, Godot, Phaser를 비롯한 모든 프레임워크에서 게임을 구상하고 설계해 구현합니다. | - -## 문서 - -- **[첫 변경 사항 구현하기](https://docs.bmad-method.org/ko-kr/start/build-your-first-change/)** — BMad를 설치하고 작은 프로젝트를 만듭니다. -- **[워크플로 맵](https://docs.bmad-method.org/ko-kr/reference/workflow-map/)** — 사용할 수 있는 경로와 산출물을 살펴봅니다. -- **[기존 프로젝트](https://docs.bmad-method.org/ko-kr/how-to/established-projects/)** — 기존 코드베이스에 BMad를 적용합니다. -- **[v6로 업그레이드](https://docs.bmad-method.org/ko-kr/how-to/upgrade-to-v6/)** — 이전 버전에서 마이그레이션합니다. - -## 커뮤니티 - -- [Discord](https://discord.gg/gk8jAdXWmj) — 도움을 받고 아이디어를 나누며 협업합니다. -- [YouTube](https://youtube.com/@BMadCode) — 튜토리얼과 마스터 클래스를 시청합니다. -- [GitHub Issues](https://github.com/bmad-code-org/BMAD-METHOD/issues) — 버그를 제보하고 기능을 요청합니다. -- [GitHub Discussions](https://github.com/bmad-code-org/BMAD-METHOD/discussions) — 커뮤니티의 긴 대화에 참여합니다. -- [BMad Code](https://bmadcode.com) — 더 넓은 BMad 생태계를 둘러봅니다. - -## 후원과 기여 - -BMad는 누구에게나 무료이며 앞으로도 계속 무료로 제공됩니다. 저장소에 스타를 누르거나 [커피 한 잔을 후원](https://buymeacoffee.com/bmad)해 주세요. 기업 후원은 으로 문의해 주세요. - -기여를 환영합니다. Pull Request를 열기 전에 [CONTRIBUTING.md](CONTRIBUTING.md)를 읽어 주세요. - -## 라이선스 - -MIT 라이선스를 따릅니다. 자세한 내용은 [LICENSE](LICENSE)를 참고하세요. - -**BMad**와 **BMAD-METHOD**는 BMad Code, LLC의 상표입니다. 자세한 내용은 [TRADEMARK.md](TRADEMARK.md)를 참고하세요. - -기여하려면 Discord에 참여하고 먼저 [CONTRIBUTORS.md](CONTRIBUTORS.md)를 읽어 주세요. diff --git a/README_VN.md b/README_VN.md deleted file mode 100644 index 7d474621f1..0000000000 --- a/README_VN.md +++ /dev/null @@ -1,99 +0,0 @@ -![BMad Method](banner-bmad-method.png) - -[![Version](https://img.shields.io/npm/v/bmad-method?color=blue&label=version)](https://www.npmjs.com/package/bmad-method) -[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE) -[![Node.js Version](https://img.shields.io/badge/node-%3E%3D20.0.0-brightgreen)](https://nodejs.org) -[![Python Version](https://img.shields.io/badge/python-%3E%3D3.10-blue?logo=python&logoColor=white)](https://www.python.org) -[![uv](https://img.shields.io/badge/uv-package%20manager-blueviolet?logo=uv)](https://docs.astral.sh/uv/) -[![Discord](https://img.shields.io/badge/Discord-Join%20Community-7289da?logo=discord&logoColor=white)](https://discord.gg/gk8jAdXWmj) - -[English](README.md) | [简体中文](README_CN.md) | Tiếng Việt - -**Agile Ai Driven Development (Phát triển hướng AI theo lối agile)** - Ai Driven Development (AiDD) bao trùm toàn bộ công việc chứ không chỉ phần mã: xây dựng cái gì, các phần gắn kết ra sao, và thay đổi thế nào khi bạn hiểu thêm. BMad Method là cách làm AiDD theo lối agile: quyết định luôn tường minh, ngữ cảnh được giữ lại xuyên suốt, và quy trình tự co giãn theo khối lượng công việc. Cùng một phương pháp dùng được cho nguyên mẫu cuối tuần lẫn hệ thống đã có nhiều năm lịch sử. - -**100% miễn phí và mã nguồn mở.** Không có tường phí. Không có nội dung bị khóa. Không có Discord giới hạn quyền truy cập. Chúng tôi tin vào việc trao quyền cho mọi người, không chỉ cho những ai có thể trả tiền để vào một cộng đồng hay khóa học khép kín. - -## Vì sao chọn BMad Method? - -Các công cụ AI truyền thống thường làm thay phần suy nghĩ của bạn và tạo ra kết quả ở mức trung bình. Các agent chuyên biệt và quy trình làm việc có hướng dẫn của BMad hoạt động như những cộng tác viên chuyên gia, dẫn dắt bạn qua một quy trình có cấu trúc để khai mở tư duy tốt nhất của bạn cùng với AI. - -- **Trợ giúp AI thông minh** - Gọi skill `bmad-help` bất kỳ lúc nào để biết bước tiếp theo -- **Thích ứng theo quy mô và miền bài toán** - Tự động điều chỉnh độ sâu lập kế hoạch theo độ phức tạp của dự án -- **Quy trình có cấu trúc** - Dựa trên các thực hành tốt nhất của agile xuyên suốt phân tích, lập kế hoạch, kiến trúc và triển khai -- **Agent chuyên biệt** - Hơn 12 chuyên gia theo vai trò như PM, Architect, Developer, UX, Scrum Master và nhiều vai trò khác -- **Party Mode** - Đưa nhiều persona agent vào cùng một phiên để cộng tác và thảo luận -- **Vòng đời hoàn chỉnh** - Từ động não ý tưởng cho đến triển khai - -[Tìm hiểu thêm tại **docs.bmad-method.org**](https://docs.bmad-method.org/vi-vn/) - ---- - -## Bắt đầu nhanh - -**Điều kiện tiên quyết**: [Node.js](https://nodejs.org) v20+ · [Python](https://www.python.org) 3.10+ · [uv](https://docs.astral.sh/uv/) - -```bash -npx bmad-method install -``` - -> Muốn dùng bản prerelease mới nhất? Hãy dùng `npx bmad-method@next install`. Hãy kỳ vọng mức độ biến động cao hơn bản cài đặt mặc định. - -Làm theo các lời nhắc của trình cài đặt, sau đó mở AI IDE của bạn như Claude Code hoặc Cursor trong thư mục dự án. - -**Cài đặt không tương tác** (cho CI/CD): - -```bash -npx bmad-method install --directory /path/to/project --modules bmm --tools claude-code --yes -``` - -> **Chưa chắc nên làm gì?** Hãy hỏi `bmad-help` - nó sẽ cho bạn biết chính xác bước nào tiếp theo và bước nào là tùy chọn. Bạn cũng có thể hỏi kiểu như `bmad-help Tôi vừa hoàn thành phần kiến trúc, tiếp theo tôi cần làm gì?` - -## Mô-đun - -BMad Method có thể được mở rộng bằng các mô-đun chính thức cho những miền chuyên biệt. Chúng có sẵn trong lúc cài đặt hoặc bất kỳ lúc nào sau đó. - -| Module | Mục đích | -| ---------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | -| **[BMad Method](https://github.com/bmad-code-org/BMAD-METHOD)** | Lập kế hoạch và bàn giao phần mềm, từ nguyên mẫu mới đến codebase lâu năm | -| **[BMad Builder](https://github.com/bmad-code-org/bmad-builder)** | Trình tạo skill, quy trình và agent | -| **[BMad Creative Intelligence Suite](https://github.com/bmad-code-org/bmad-module-creative-intelligence-suite)** | Đối tác tư duy sáng tạo cho đổi mới, tư duy thiết kế và kể chuyện | -| **[BMad Test Architect](https://github.com/bmad-code-org/bmad-method-test-architecture-enterprise)** | Mô-đun kiểm thử doanh nghiệp bổ trợ cho BMad Method | -| **[BMad Loop](https://github.com/bmad-code-org/bmad-loop)** | Tự động xây dựng, kiểm chứng và tổng kết cả một Epic | -| **[BMad Game Dev Studio](https://github.com/bmad-code-org/bmad-module-game-dev-studio)** | Lên ý tưởng, thiết kế và phát triển game trên mọi framework, gồm Unity, Unreal, Godot và Phaser | - -## Tài liệu - -[Trang tài liệu BMad Method](https://docs.bmad-method.org/vi-vn/) - bài hướng dẫn, hướng dẫn tác vụ, giải thích khái niệm và tài liệu tham chiếu - -**Liên kết nhanh:** - -- [Hướng dẫn bắt đầu](https://docs.bmad-method.org/vi-vn/tutorials/getting-started/) -- [Nâng cấp từ các phiên bản trước](https://docs.bmad-method.org/vi-vn/how-to/upgrade-to-v6/) -- [Tài liệu Test Architect](https://bmad-code-org.github.io/bmad-method-test-architecture-enterprise/) - -## Cộng đồng - -- [Discord](https://discord.gg/gk8jAdXWmj) - Nhận trợ giúp, chia sẻ ý tưởng, cộng tác -- [YouTube](https://youtube.com/@BMadCode) - Video hướng dẫn, master class và nhiều nội dung khác -- [X / Twitter](https://x.com/BMadCode) -- [Website](https://bmadcode.com) -- [GitHub Issues](https://github.com/bmad-code-org/BMAD-METHOD/issues) - Báo lỗi và yêu cầu tính năng -- [Discussions](https://github.com/bmad-code-org/BMAD-METHOD/discussions) - Trao đổi cộng đồng - -## Hỗ trợ BMad - -BMad miễn phí cho tất cả mọi người và sẽ luôn như vậy. Hãy nhấn sao cho repo này, [mời tôi một ly cà phê](https://buymeacoffee.com/bmad), hoặc gửi email tới nếu bạn muốn tài trợ doanh nghiệp. - -## Đóng góp - -Chúng tôi luôn chào đón đóng góp. Xem [CONTRIBUTING.md](CONTRIBUTING.md) để biết hướng dẫn. - -## Giấy phép - -Giấy phép MIT - xem [LICENSE](LICENSE) để biết chi tiết. - ---- - -**BMad** và **BMAD-METHOD** là các nhãn hiệu của BMad Code, LLC. Xem [TRADEMARK.md](TRADEMARK.md) để biết chi tiết. - -Xem [CONTRIBUTORS.md](CONTRIBUTORS.md) để biết thông tin về những người đóng góp. diff --git a/docs-site/astro.config.mjs b/docs-site/astro.config.mjs index 2c8710ccc9..7c12dae85c 100644 --- a/docs-site/astro.config.mjs +++ b/docs-site/astro.config.mjs @@ -10,7 +10,6 @@ import rehypeInlineDiagrams from './src/rehype-inline-diagrams.js'; import rehypeMarkdownLinks from './src/rehype-markdown-links.js'; import rehypeBasePaths from './src/rehype-base-paths.js'; import { getSiteUrl } from './src/lib/site-url.mjs'; -import { locales } from './src/lib/locales.mjs'; const siteUrl = getSiteUrl(); const urlParts = new URL(siteUrl); @@ -33,14 +32,7 @@ export default defineConfig({ '/plan/help-test-v7-previews': `${basePath}plan/set-up-the-ticket-tree/`, '/build/review-a-completed-change': `${basePath}build/walk-through-a-change/`, '/build/checkpoint-a-change': `${basePath}build/walk-through-a-change/`, - '/fr/explanation/checkpoint-preview': `${basePath}fr/build/walk-through-a-change/`, - '/vi-vn/explanation/checkpoint-preview': `${basePath}vi-vn/build/walk-through-a-change/`, - '/zh-cn/explanation/checkpoint-preview': `${basePath}zh-cn/build/walk-through-a-change/`, '/explanation/adversarial-review': `${basePath}build/review-a-change/`, - '/fr/explanation/adversarial-review': `${basePath}build/review-a-change/`, - '/cs/explanation/adversarial-review': `${basePath}build/review-a-change/`, - '/vi-vn/explanation/adversarial-review': `${basePath}build/review-a-change/`, - '/zh-cn/explanation/adversarial-review': `${basePath}build/review-a-change/`, '/reference/testing': `${basePath}build/test-completed-work/`, '/reference/build-auto': `${basePath}build/autonomous-development-loops/`, '/reference/workflow-map': `${basePath}plan/choose-a-planning-path/`, @@ -48,9 +40,6 @@ export default defineConfig({ '/reference/commands': `${basePath}reference/skills-and-agents/`, '/reference/core-tools': `${basePath}reference/skills-and-agents/`, '/explanation/advanced-elicitation': `${basePath}reference/skills-and-agents/`, - '/fr/reference/build-auto': `${basePath}fr/build/autonomous-development-loops/`, - '/cs/reference/build-auto': `${basePath}cs/build/autonomous-development-loops/`, - '/vi-vn/reference/build-auto': `${basePath}vi-vn/build/autonomous-development-loops/`, '/how-to/choose-a-development-path': `${basePath}plan/choose-a-planning-path/`, '/explanation/analysis-phase': `${basePath}plan/explore-and-validate-an-idea/`, '/explanation/brainstorming': `${basePath}plan/explore-and-validate-an-idea/`, @@ -60,7 +49,6 @@ export default defineConfig({ '/explanation/why-solutioning-matters': `${basePath}plan/design-ux-and-architecture/`, '/explanation/preventing-agent-conflicts': `${basePath}plan/design-ux-and-architecture/`, '/explanation/sprint-planning': `${basePath}plan/break-work-into-stories-and-track-it/`, - '/ko-kr/explanation/sprint-planning': `${basePath}ko-kr/plan/break-work-into-stories-and-track-it/`, '/explanation/retrospective': `${basePath}build/finish-an-epic/`, '/how-to/established-projects': `${basePath}existing-codebases/start-in-an-existing-codebase/`, '/explanation/established-projects-faq': `${basePath}existing-codebases/start-in-an-existing-codebase/`, @@ -74,12 +62,6 @@ export default defineConfig({ '/how-to/install-custom-modules': `${basePath}customize/add-modules/`, '/reference/modules': `${basePath}customize/add-modules/`, '/explanation/party-mode': `${basePath}customize/run-multi-agent-discussions/`, - '/cs/explanation/named-agents': `${basePath}cs/customize/customize-bmad/`, - '/fr/how-to/non-interactive-installation': `${basePath}fr/how-to/install-bmad/`, - '/cs/how-to/non-interactive-installation': `${basePath}cs/how-to/install-bmad/`, - '/ko-kr/how-to/non-interactive-installation': `${basePath}ko-kr/start/install-bmad/`, - '/vi-vn/how-to/non-interactive-installation': `${basePath}vi-vn/how-to/install-bmad/`, - '/zh-cn/how-to/non-interactive-installation': `${basePath}zh-cn/how-to/install-bmad/`, }, // Disable aggressive caching in dev mode @@ -100,7 +82,7 @@ export default defineConfig({ // Hand-authored diagrams are inlined so custom.css can theme them; this // runs before rehypeBasePaths, which would otherwise rewrite the src of // an that is about to be replaced. - [rehypeInlineDiagrams, { root: fileURLToPath(new URL('.', import.meta.url)), locales }], + [rehypeInlineDiagrams, { root: fileURLToPath(new URL('.', import.meta.url)) }], [rehypeMarkdownLinks, { base: basePath }], [rehypeBasePaths, { base: basePath }], ], @@ -110,18 +92,14 @@ export default defineConfig({ integrations: [ // must come before the pages that embed diagrams are rendered bmadDiagrams(), - // Exclude custom 404 pages (all locales) from the sitemap — they are - // treated as normal content docs by Starlight even with disable404Route. + // Exclude the custom 404 page from the sitemap — it is + // treated as a normal content doc by Starlight even with disable404Route. sitemap({ filter: (page) => !/\/404(\/|$)/.test(new URL(page).pathname), }), starlight({ title: 'BMad Method', - // i18n: locale config from shared module (docs-site/src/lib/locales.mjs) - defaultLocale: 'root', - locales, - // The BMad tile: the same mark the header carries, and byte-for-byte the // drawing bmadcode.com and blog.bmadcode.com serve. The SVG is what modern // browsers pick up; the .ico and the apple-touch-icon are generated from @@ -155,198 +133,86 @@ export default defineConfig({ sidebar: [ { label: 'Start', - translations: { 'ko-KR': '시작하기', 'vi-VN': 'Bắt đầu', 'zh-CN': '开始', 'fr-FR': 'Démarrer', 'cs-CZ': 'Začít' }, collapsed: false, items: [ { label: 'Welcome', - translations: { 'ko-KR': '환영합니다', 'vi-VN': 'Chào mừng', 'zh-CN': '欢迎', 'fr-FR': 'Bienvenue', 'cs-CZ': 'Vítejte' }, slug: 'index', }, { label: 'Install BMad', - translations: { - 'ko-KR': 'BMad 설치', - 'vi-VN': 'Cách cài đặt BMad', - 'zh-CN': '如何安装 BMad', - 'fr-FR': 'Comment installer BMad', - 'cs-CZ': 'Jak nainstalovat BMad', - }, slug: 'start/install-bmad', }, { label: 'Build Your First Change', - translations: { - 'ko-KR': '첫 번째 변경 사항 구현하기', - 'vi-VN': 'Bắt đầu', - 'zh-CN': '快速入门', - 'fr-FR': 'Premiers pas', - 'cs-CZ': 'Začínáme', - }, slug: 'start/build-your-first-change', }, { label: 'Get Answers About BMad', - translations: { - 'ko-KR': 'BMad 관련 질문에 답을 얻는 방법', - 'vi-VN': 'Cách tìm câu trả lời về BMad', - 'zh-CN': '如何获取关于 BMad 的答案', - 'fr-FR': 'Comment obtenir des réponses à propos de BMad', - 'cs-CZ': 'Jak získat odpovědi o BMad', - }, slug: 'start/get-answers-about-bmad', }, ], }, { label: 'Build', - translations: { 'ko-KR': 'Build', 'vi-VN': 'Xây dựng', 'zh-CN': '构建', 'fr-FR': 'Construire', 'cs-CZ': 'Sestavit' }, collapsed: false, items: [ { label: 'Build a Change', - translations: { - 'ko-KR': '변경 사항 구현하기', - 'vi-VN': 'Xây dựng một thay đổi', - 'zh-CN': '构建一个变更', - 'fr-FR': 'Construire un changement', - 'cs-CZ': 'Sestavit změnu', - }, slug: 'build/build-a-change', }, { label: 'Review a Change', - translations: { - 'vi-VN': 'Rà soát một thay đổi', - 'zh-CN': '审查一个变更', - 'fr-FR': 'Examiner un changement', - 'cs-CZ': 'Zkontrolovat změnu', - }, slug: 'build/review-a-change', }, { label: 'Walk Through a Change', - translations: { - 'ko-KR': '변경 사항 살펴보기', - 'vi-VN': 'Đi qua một thay đổi', - 'zh-CN': '走查一个变更', - 'fr-FR': 'Parcourir un changement', - 'cs-CZ': 'Projít změnu', - }, slug: 'build/walk-through-a-change', }, { label: 'Test Completed Work', - translations: { - 'ko-KR': '완료된 작업 테스트하기', - 'vi-VN': 'Kiểm thử công việc đã xong', - 'zh-CN': '测试已完成的工作', - 'fr-FR': 'Tester le travail terminé', - 'cs-CZ': 'Otestovat dokončenou práci', - }, slug: 'build/test-completed-work', }, { label: 'Finish an Epic', - translations: { - 'vi-VN': 'Hoàn tất một epic', - 'zh-CN': '完成一个 Epic', - 'fr-FR': 'Terminer un epic', - 'cs-CZ': 'Dokončit epic', - }, slug: 'build/finish-an-epic', }, { label: 'Autonomous Development Loops', - translations: { - 'ko-KR': '자율 개발 루프', - 'vi-VN': 'Vòng lặp phát triển tự động', - 'zh-CN': '自主开发循环', - 'fr-FR': 'Boucles de développement autonomes', - 'cs-CZ': 'Autonomní vývojové smyčky', - }, slug: 'build/autonomous-development-loops', }, ], }, { label: 'Plan Larger Work', - translations: { - 'vi-VN': 'Lập kế hoạch công việc lớn', - 'zh-CN': '规划更大的工作', - 'fr-FR': 'Planifier un travail plus vaste', - 'cs-CZ': 'Plánovat větší práci', - }, collapsed: true, items: [ { label: 'Choose a Planning Path', - translations: { - 'vi-VN': 'Chọn lộ trình lập kế hoạch', - 'zh-CN': '选择规划路径', - 'fr-FR': 'Choisir un parcours de planification', - 'cs-CZ': 'Zvolit cestu plánování', - }, slug: 'plan/choose-a-planning-path', }, { label: 'Plan Inside an Organization', - translations: { - 'vi-VN': 'Lập kế hoạch trong một tổ chức', - 'zh-CN': '在组织内进行规划', - 'fr-FR': 'Planifier au sein d’une organisation', - 'cs-CZ': 'Plánování uvnitř organizace', - }, slug: 'plan/plan-inside-an-organization', }, { label: 'Explore and Validate an Idea', - translations: { - 'vi-VN': 'Khám phá và kiểm chứng ý tưởng', - 'zh-CN': '探索并验证想法', - 'fr-FR': 'Explorer et valider une idée', - 'cs-CZ': 'Prozkoumat a ověřit nápad', - }, slug: 'plan/explore-and-validate-an-idea', }, { label: 'Research a Decision', - translations: { - 'vi-VN': 'Nghiên cứu cho một quyết định', - 'zh-CN': '为决策做研究', - 'fr-FR': 'Rechercher pour une décision', - 'cs-CZ': 'Prozkoumat rozhodnutí', - }, slug: 'plan/research-a-decision', }, { label: 'Define Requirements and a Specification', - translations: { - 'vi-VN': 'Xác định yêu cầu và đặc tả', - 'zh-CN': '定义需求与规格', - 'fr-FR': 'Définir les exigences et une spécification', - 'cs-CZ': 'Definovat požadavky a specifikaci', - }, slug: 'plan/define-requirements-and-a-specification', }, { label: 'Design UX and Architecture', - translations: { - 'vi-VN': 'Thiết kế UX và kiến trúc', - 'zh-CN': '设计 UX 与架构', - 'fr-FR': "Concevoir l'UX et l'architecture", - 'cs-CZ': 'Navrhnout UX a architekturu', - }, slug: 'plan/design-ux-and-architecture', }, { label: 'Break Work into Stories and Track It', - translations: { - 'vi-VN': 'Chia công việc thành story và theo dõi', - 'zh-CN': '拆分为故事并跟踪', - 'fr-FR': 'Découper le travail en stories et le suivre', - 'cs-CZ': 'Rozdělit práci na story a sledovat ji', - }, slug: 'plan/break-work-into-stories-and-track-it', }, { @@ -357,121 +223,50 @@ export default defineConfig({ }, { label: 'Existing Codebases', - translations: { - 'ko-KR': '기존 코드베이스', - 'vi-VN': 'Mã nguồn hiện có', - 'zh-CN': '现有代码库', - 'fr-FR': 'Bases de code existantes', - 'cs-CZ': 'Existující kódové základny', - }, collapsed: true, items: [ { label: 'Start in an Existing Codebase', - translations: { - 'ko-KR': '기존 코드베이스에서 시작하기', - 'vi-VN': 'Bắt đầu trong một mã nguồn hiện có', - 'zh-CN': '在现有代码库中开始', - 'fr-FR': 'Démarrer dans une base de code existante', - 'cs-CZ': 'Začít v existující kódové základně', - }, slug: 'existing-codebases/start-in-an-existing-codebase', }, { label: 'Set and Maintain Project Context', - translations: { - 'ko-KR': '프로젝트 컨텍스트 설정 및 유지', - 'vi-VN': 'Thiết lập và duy trì ngữ cảnh dự án', - 'zh-CN': '设置并维护项目上下文', - 'fr-FR': 'Définir et maintenir le contexte du projet', - 'cs-CZ': 'Nastavit a udržovat kontext projektu', - }, slug: 'existing-codebases/set-and-maintain-project-context', }, { label: 'Getting Deeper', - translations: { - 'ko-KR': '더 깊이 알아보기', - 'vi-VN': 'Đi sâu hơn', - 'zh-CN': '深入探索', - 'fr-FR': 'Aller plus loin', - 'cs-CZ': 'Jít hlouběji', - }, slug: 'existing-codebases/getting-deeper', }, { label: 'The Theory of Project Context', - translations: { - 'ko-KR': '프로젝트 컨텍스트의 이론', - 'vi-VN': 'Lý thuyết về ngữ cảnh dự án', - 'zh-CN': '项目上下文的理论', - 'fr-FR': 'La théorie du contexte du projet', - 'cs-CZ': 'Teorie kontextu projektu', - }, slug: 'existing-codebases/theory-of-project-context', }, ], }, { label: 'Customize and Extend', - translations: { - 'ko-KR': '커스터마이즈 및 확장', - 'vi-VN': 'Tùy chỉnh và mở rộng', - 'zh-CN': '自定义与扩展', - 'fr-FR': 'Personnaliser et étendre', - 'cs-CZ': 'Přizpůsobení a rozšíření', - }, collapsed: true, items: [ { label: 'Customize BMad', - translations: { - 'ko-KR': 'BMad 커스터마이즈', - 'vi-VN': 'Tùy chỉnh BMad', - 'zh-CN': '自定义 BMad', - 'fr-FR': 'Personnaliser BMad', - 'cs-CZ': 'Přizpůsobit BMad', - }, slug: 'customize/customize-bmad', }, { label: 'Adopt BMad Across a Team', - translations: { - 'ko-KR': '팀 전체에 BMad 도입하기', - 'vi-VN': 'Áp dụng BMad cho cả nhóm', - 'zh-CN': '在团队中采用 BMad', - 'fr-FR': 'Adopter BMad dans toute une équipe', - 'cs-CZ': 'Zavést BMad v celém týmu', - }, slug: 'customize/adopt-bmad-across-a-team', }, { label: 'Add Modules', - translations: { - 'ko-KR': '모듈 추가하기', - 'vi-VN': 'Thêm mô-đun', - 'zh-CN': '添加模块', - 'fr-FR': 'Ajouter des modules', - 'cs-CZ': 'Přidat moduly', - }, slug: 'customize/add-modules', }, { label: 'Run Multi-Agent Discussions', - translations: { - 'ko-KR': '다중 에이전트 토론 실행하기', - 'vi-VN': 'Chạy thảo luận nhiều agent', - 'zh-CN': '运行多智能体讨论', - 'fr-FR': 'Mener des discussions multi-agents', - 'cs-CZ': 'Vést diskuse více agentů', - }, slug: 'customize/run-multi-agent-discussions', }, ], }, { label: 'Toolsmith', - translations: { 'ko-KR': 'Toolsmith', 'vi-VN': 'Toolsmith', 'zh-CN': 'Toolsmith', 'fr-FR': 'Toolsmith', 'cs-CZ': 'Toolsmith' }, collapsed: true, items: [ { label: 'Toolsmith', slug: 'toolsmith/toolsmith' }, @@ -484,55 +279,26 @@ export default defineConfig({ }, { label: 'Reference', - translations: { 'ko-KR': '참조', 'vi-VN': 'Tham chiếu', 'zh-CN': '参考', 'fr-FR': 'Référence', 'cs-CZ': 'Reference' }, collapsed: true, items: [{ autogenerate: { directory: 'reference' } }], }, // TEA docs moved to standalone module site; keep BMM sidebar focused. { label: 'BMad Ecosystem', - translations: { - 'ko-KR': 'BMad 생태계', - 'vi-VN': 'Hệ sinh thái BMad', - 'zh-CN': 'BMad 生态系统', - 'fr-FR': 'Écosystème BMad', - 'cs-CZ': 'Ekosystém BMad', - }, collapsed: false, items: [ { label: 'Creative Intelligence Suite', - translations: { - 'ko-KR': '창의적 지능 제품군', - 'vi-VN': 'Bộ công cụ Trí tuệ Sáng tạo', - 'zh-CN': '创意智能套件', - 'fr-FR': "Suite d'Intelligence Créative", - 'cs-CZ': 'Sada kreativní inteligence', - }, link: 'https://cis-docs.bmad-method.org/', attrs: { target: '_blank' }, }, { label: 'Game Dev Studio', - translations: { - 'ko-KR': '게임 개발 스튜디오', - 'vi-VN': 'Xưởng phát triển Game', - 'zh-CN': '游戏开发工作室', - 'fr-FR': 'Studio de Développement de Jeux', - 'cs-CZ': 'Herní vývojové studio', - }, link: 'https://game-dev-studio-docs.bmad-method.org/', attrs: { target: '_blank' }, }, { label: 'Test Architect (TEA)', - translations: { - 'ko-KR': '테스트 설계자(TEA)', - 'vi-VN': 'Kiến trúc sư Kiểm thử (TEA)', - 'zh-CN': '测试架构师 (TEA)', - 'fr-FR': 'Architecte de Tests (TEA)', - 'cs-CZ': 'Testovací architekt (TEA)', - }, link: 'https://bmad-code-org.github.io/bmad-method-test-architecture-enterprise/', attrs: { target: '_blank' }, }, diff --git a/docs-site/locale-coverage-baseline.json b/docs-site/locale-coverage-baseline.json deleted file mode 100644 index 7e2f703921..0000000000 --- a/docs-site/locale-coverage-baseline.json +++ /dev/null @@ -1,164 +0,0 @@ -{ - "ko-kr": [ - "build/autonomous-development-loops", - "build/finish-an-epic", - "build/review-a-change", - "customize/add-modules", - "customize/adopt-bmad-across-a-team", - "customize/customize-bmad", - "customize/run-multi-agent-discussions", - "existing-codebases/getting-deeper", - "existing-codebases/set-and-maintain-project-context", - "existing-codebases/start-in-an-existing-codebase", - "existing-codebases/theory-of-project-context", - "plan/break-work-into-stories-and-track-it", - "plan/choose-a-planning-path", - "plan/define-requirements-and-a-specification", - "plan/design-ux-and-architecture", - "plan/explore-and-validate-an-idea", - "plan/plan-inside-an-organization", - "plan/research-a-decision", - "plan/set-up-the-ticket-tree", - "reference/skills-and-agents", - "start/get-answers-about-bmad", - "toolsmith/approaches", - "toolsmith/bmad-eval", - "toolsmith/migrate-an-old-module", - "toolsmith/modes", - "toolsmith/shapes", - "toolsmith/toolsmith" - ], - "vi-vn": [ - "build/autonomous-development-loops", - "build/build-a-change", - "build/finish-an-epic", - "build/review-a-change", - "build/test-completed-work", - "customize/add-modules", - "customize/adopt-bmad-across-a-team", - "customize/customize-bmad", - "customize/run-multi-agent-discussions", - "existing-codebases/getting-deeper", - "existing-codebases/set-and-maintain-project-context", - "existing-codebases/start-in-an-existing-codebase", - "existing-codebases/theory-of-project-context", - "plan/break-work-into-stories-and-track-it", - "plan/choose-a-planning-path", - "plan/define-requirements-and-a-specification", - "plan/design-ux-and-architecture", - "plan/explore-and-validate-an-idea", - "plan/plan-inside-an-organization", - "plan/research-a-decision", - "plan/set-up-the-ticket-tree", - "reference/skills-and-agents", - "start/build-your-first-change", - "start/get-answers-about-bmad", - "start/install-bmad", - "toolsmith/approaches", - "toolsmith/bmad-eval", - "toolsmith/migrate-an-old-module", - "toolsmith/modes", - "toolsmith/shapes", - "toolsmith/toolsmith" - ], - "zh-cn": [ - "build/autonomous-development-loops", - "build/build-a-change", - "build/finish-an-epic", - "build/review-a-change", - "build/test-completed-work", - "customize/add-modules", - "customize/adopt-bmad-across-a-team", - "customize/customize-bmad", - "customize/run-multi-agent-discussions", - "existing-codebases/getting-deeper", - "existing-codebases/set-and-maintain-project-context", - "existing-codebases/start-in-an-existing-codebase", - "existing-codebases/theory-of-project-context", - "plan/break-work-into-stories-and-track-it", - "plan/choose-a-planning-path", - "plan/define-requirements-and-a-specification", - "plan/design-ux-and-architecture", - "plan/explore-and-validate-an-idea", - "plan/plan-inside-an-organization", - "plan/research-a-decision", - "plan/set-up-the-ticket-tree", - "reference/skills-and-agents", - "start/build-your-first-change", - "start/get-answers-about-bmad", - "start/install-bmad", - "toolsmith/approaches", - "toolsmith/bmad-eval", - "toolsmith/migrate-an-old-module", - "toolsmith/modes", - "toolsmith/shapes", - "toolsmith/toolsmith" - ], - "fr": [ - "build/autonomous-development-loops", - "build/build-a-change", - "build/finish-an-epic", - "build/review-a-change", - "build/test-completed-work", - "customize/add-modules", - "customize/adopt-bmad-across-a-team", - "customize/customize-bmad", - "customize/run-multi-agent-discussions", - "existing-codebases/getting-deeper", - "existing-codebases/set-and-maintain-project-context", - "existing-codebases/start-in-an-existing-codebase", - "existing-codebases/theory-of-project-context", - "plan/break-work-into-stories-and-track-it", - "plan/choose-a-planning-path", - "plan/define-requirements-and-a-specification", - "plan/design-ux-and-architecture", - "plan/explore-and-validate-an-idea", - "plan/plan-inside-an-organization", - "plan/research-a-decision", - "plan/set-up-the-ticket-tree", - "reference/skills-and-agents", - "start/build-your-first-change", - "start/get-answers-about-bmad", - "start/install-bmad", - "toolsmith/approaches", - "toolsmith/bmad-eval", - "toolsmith/migrate-an-old-module", - "toolsmith/modes", - "toolsmith/shapes", - "toolsmith/toolsmith" - ], - "cs": [ - "build/autonomous-development-loops", - "build/build-a-change", - "build/finish-an-epic", - "build/review-a-change", - "build/test-completed-work", - "build/walk-through-a-change", - "customize/add-modules", - "customize/adopt-bmad-across-a-team", - "customize/customize-bmad", - "customize/run-multi-agent-discussions", - "existing-codebases/getting-deeper", - "existing-codebases/set-and-maintain-project-context", - "existing-codebases/start-in-an-existing-codebase", - "existing-codebases/theory-of-project-context", - "plan/break-work-into-stories-and-track-it", - "plan/choose-a-planning-path", - "plan/define-requirements-and-a-specification", - "plan/design-ux-and-architecture", - "plan/explore-and-validate-an-idea", - "plan/plan-inside-an-organization", - "plan/research-a-decision", - "plan/set-up-the-ticket-tree", - "reference/skills-and-agents", - "start/build-your-first-change", - "start/get-answers-about-bmad", - "start/install-bmad", - "toolsmith/approaches", - "toolsmith/bmad-eval", - "toolsmith/migrate-an-old-module", - "toolsmith/modes", - "toolsmith/shapes", - "toolsmith/toolsmith" - ] -} diff --git a/docs-site/package.json b/docs-site/package.json index 07f3c4501c..efac5a70a3 100644 --- a/docs-site/package.json +++ b/docs-site/package.json @@ -13,9 +13,8 @@ "format:fix": "prettier --write \"{scripts,test}/**/*.{js,mjs}\"", "lint": "eslint scripts test --max-warnings=0", "lint:fix": "eslint scripts test --fix", - "locale-coverage": "node scripts/validate-locale-coverage.mjs", "preview": "astro preview", - "test": "node test/test-site-url.mjs && node test/test-rehype-plugins.mjs && node test/test-validate-redirects.mjs && node test/test-validate-locale-coverage.mjs", + "test": "node test/test-site-url.mjs && node test/test-rehype-plugins.mjs && node test/test-validate-redirects.mjs && node test/test-english-only-site.mjs", "test:implementation-model": "node test/test-validate-published-implementation-model.mjs", "validate-links": "node scripts/validate-doc-links.js", "validate-sidebar": "node scripts/validate-sidebar-order.js" diff --git a/docs-site/public/workflow-map-diagram-fr.html b/docs-site/public/workflow-map-diagram-fr.html deleted file mode 100644 index cac0ffd103..0000000000 --- a/docs-site/public/workflow-map-diagram-fr.html +++ /dev/null @@ -1,316 +0,0 @@ - - - - - - Carte des Workflows - Méthode BMad - - - -
-
⚡ Carte des Workflows V6
-

Méthode BMad

-

Ingénierie du contexte pour le développement piloté par l’IA

-
- -
→ les flèches montrent le flux des artefacts entre les workflows
- -
- -
-
-
1
-
Analyse
- Optionnel -
-
-
-
- brainstorm - opt -
-
-
M
Mary
- brainstorming-report.md -
-
-
-
- research - opt -
-
-
M
Mary
- résultats -
-
-
-
- product-brief - ou ↓ -
-
-
M
Mary
- product-brief.md → -
-
-
-
- prfaq - ou ↑ -
-
-
M
Mary
- prfaq.md → -
-
-
-
→
-
- - -
-
-
2
-
Planification
-
-
-
-
- prd -
-
-
J
Au choix
- prd.md → -
-
-
Interface utilisateur ?
-
-
- create-ux-design - si oui -
-
-
S
Sally
- ux-spec.md → -
-
-
-
→
-
- - -
-
-
3
-
Solutioning
-
-
-
-
- create-architecture -
-
-
W
Winston
- architecture.md → -
-
-
-
- create-epics-and-stories -
-
-
J
John
- epics.md → -
-
-
-
- sprint-planning -
-
-
J
John
- jalon + sprint-status.yaml → -
-
-
-
→
-
- - -
-
-
4
-
Implémentation
-
-
-
Intention directe ou contexte planifié ↓
-
-
- build -
-
-
A
Amelia
- spec + code + revue → -
-
-
-
- code-review -
-
-
A
Amelia
- approbation -
-
-
-
- correct-course - ad-hoc -
-
-
J
John
- plan mis à jour -
-
-
-
- retrospective - par Epic -
-
-
A
Amelia
- leçons apprises -
-
-
-
-
- -
-
📚 Flux de Contexte
-

Les documents disponibles enrichissent le contexte avant l’implémentation.

-
- build charge l’intention, issue, spec, PRD, architecture, UX, epic, story et contexte de sprint disponibles - code-review ajoute une validation indépendante si nécessaire -
-
- -
-
Analyse
-
Planification
-
Solutioning
-
Implémentation
-
- - diff --git a/docs-site/public/workflow-map-diagram-ko.html b/docs-site/public/workflow-map-diagram-ko.html deleted file mode 100644 index 631510dc1c..0000000000 --- a/docs-site/public/workflow-map-diagram-ko.html +++ /dev/null @@ -1,543 +0,0 @@ - - - - - - BMad Method 워크플로 맵 - - - -
-
워크플로 맵 V6
-

BMad Method

-

AI 기반 개발을 위한 컨텍스트 엔지니어링

-
- -
→ 화살표는 워크플로 간 산출물 흐름을 나타냅니다
- -
- -
-
-
1
-

분석

- 선택 사항 -
-
-
-
- brainstorm - 선택 -
-
-
- - Mary -
- brainstorming-report.md -
-
-
-
- research - 선택 -
-
-
- - Mary -
- 리서치 결과 -
-
-
-
- product-brief - 또는 ↓ -
-
-
- - Mary -
- product-brief.md → -
-
-
-
- prfaq - 또는 ↑ -
-
-
- - Mary -
- prfaq.md → -
-
-
- -
- - -
-
-
2
-

계획

-
-
-
-
- prd -
-
-
- - John -
- prd.md → -
-
-
UI가 있나요?
-
-
- ux - 예 -
-
-
- - Sally -
- DESIGN.md + EXPERIENCE.md → -
-
-
- -
- - -
-
-
3
-

솔루션 설계

-
-
-
-
- architecture -
-
-
- - Winston -
- ARCHITECTURE-SPINE.md → -
-
-
-
- create-epics-and-stories -
-
-
- - John -
- epics.md → -
-
-
-
- sprint-planning -
-
-
- - John -
- 준비도 게이트 + sprint-status.yaml → -
-
-
- -
- - -
-
-
4
-

구현

-
-
-
직접 입력한 의도 또는 계획 컨텍스트에서 가져온 단일 세션 작업 단위 ↓
-
-
- build -
-
- 사람이 참여하는 구현 + 검토 → -
-
-
-
- build-auto -
-
- 무인 작업 단위 하나 + 종료 상태 → -
-
-
-
- code-review -
-
-
- - Amelia -
- 승인 -
-
-
-
- correct-course - 필요 시 -
-
-
- - John -
- 계획 업데이트 -
-
-
-
- retrospective - 에픽별 -
-
- 에픽 근거 + 판정 + 교훈 -
-
-
-
-
- -
-

컨텍스트 흐름

-

구현 전에 사용할 수 있는 문서가 컨텍스트를 보강합니다.

-
- build 직접 입력한 의도 또는 계획 컨텍스트의 작업 단위 하나를 처리하고, build-auto는 작업 단위 하나를 무인으로 처리 - spec + stories 상위 의도를 보존하고 구현 세션 사이에 결정 사항을 전달 - code-review 필요할 때 독립 검증을 추가 -
-
- - - - diff --git a/docs-site/public/workflow-map-diagram.html b/docs-site/public/workflow-map-diagram.html deleted file mode 100644 index fc85d4ebd7..0000000000 --- a/docs-site/public/workflow-map-diagram.html +++ /dev/null @@ -1,323 +0,0 @@ - - - - - - BMad Method Workflow Map - - - -
-
⚡ Workflow Map V6
-

BMad Method

-

Context engineering for AI-powered development

-
- -
→ arrows show artifact flow between workflows
- -
- -
-
-
1
-
Analysis
- Optional -
-
-
-
- brainstorm - opt -
-
-
M
Mary
- brainstorming-report.md -
-
-
-
- research - opt -
-
-
M
Mary
- findings -
-
-
-
- product-brief - or ↓ -
-
-
M
Mary
- product-brief.md → -
-
-
-
- prfaq - or ↑ -
-
-
M
Mary
- prfaq.md → -
-
-
-
→
-
- - -
-
-
2
-
Planning
-
-
-
-
- prd -
-
-
J
John
- prd.md → -
-
-
Has UI?
-
-
- ux - if yes -
-
-
S
Sally
- DESIGN.md + EXPERIENCE.md → -
-
-
-
→
-
- - -
-
-
3
-
Solutioning
-
-
-
-
- create-architecture -
-
-
W
Winston
- architecture.md → -
-
-
-
- create-epics-and-stories -
-
-
J
John
- epics.md → -
-
-
-
- sprint-planning -
-
-
J
John
- gate + sprint-status.yaml → -
-
-
-
→
-
- - -
-
-
4
-
Implementation
-
-
-
One session-sized unit from direct intent or planned context ↓
-
-
- build -
-
- attentive implementation + review → -
-
-
-
- build-auto -
-
- one unattended unit + status → -
-
-
-
- code-review -
-
-
A
Amelia
- approve -
-
-
-
- correct-course - ad-hoc -
-
-
J
John
- updated plan -
-
-
-
- retrospective - per epic -
-
- epic evidence + verdict + lessons -
-
-
-
-
- -
-
📚 Context Flow
-

Available documents add context before implementation.

-
- build handles one unit from direct intent or planned context; build-auto handles one unit unattended - spec + stories preserve the parent intent and carry decisions between implementation sessions - code-review adds independent validation when needed -
-
- -
-
Analysis
-
Planning
-
Solutioning
-
Implementation
-
- - diff --git a/docs-site/scripts/build-docs.mjs b/docs-site/scripts/build-docs.mjs index fbbcd9d14d..545ff4cbef 100644 --- a/docs-site/scripts/build-docs.mjs +++ b/docs-site/scripts/build-docs.mjs @@ -13,7 +13,6 @@ import path from 'node:path'; import { fileURLToPath } from 'node:url'; import { validatePublishedImplementationModel } from './validate-published-implementation-model.mjs'; import { validateRedirects } from './validate-redirects.mjs'; -import { validateLocaleCoverage } from './validate-locale-coverage.mjs'; // ============================================================================= // Configuration @@ -86,13 +85,6 @@ function buildAstroSite() { siteDir, }); console.log(` ${redirectCount} redirects resolve to built pages`); - console.log(' → Checking locale coverage...'); - const { summary } = validateLocaleCoverage(siteDir, { - baselinePath: path.join(SITE_ROOT, 'locale-coverage-baseline.json'), - }); - for (const row of summary) { - console.log(` ${row.locale.padEnd(6)} ${row.translated}/${row.total} translated`); - } console.log(); console.log(` \u001B[32m✓\u001B[0m Astro build complete`); diff --git a/docs-site/scripts/validate-locale-coverage.mjs b/docs-site/scripts/validate-locale-coverage.mjs deleted file mode 100644 index eb62f114bf..0000000000 --- a/docs-site/scripts/validate-locale-coverage.mjs +++ /dev/null @@ -1,184 +0,0 @@ -/** - * Locale coverage guard. - * - * When a translated locale has no page at a given route, Starlight serves the - * English one in its place. Nothing fails, nothing warns, and the reader gets - * English prose inside a document that declares itself French or Korean — so a - * missing translation and a working one look identical from the outside. That - * is how every locale in this repo ended up stranded on the pre-restructure - * tree without anyone noticing. - * - * Starlight marks the substitution itself: on a fallback page the `
` - * element carries `lang="en"` while the document carries the locale. This - * checks the built site for that mismatch, which measures the symptom directly - * rather than inferring it from the sidebar. - * - * Fixing the backlog is a separate, large piece of work, so the current gaps - * live in `locale-coverage-baseline.json` and are tolerated. The build fails - * only when the picture changes: - * - * - a route falls back that did not before (a new page with no translations, - * or a translation that was moved or deleted) - * - a route in the baseline no longer falls back, and the entry is stale - * - * Both are fixed by rerunning with `--update`, which rewrites the baseline. The - * second case failing is deliberate: it is what stops the baseline from - * quietly outliving the problem it records. - * - * Runs as part of the docs build. Standalone usage after a build: - * node docs-site/scripts/validate-locale-coverage.mjs - * node docs-site/scripts/validate-locale-coverage.mjs --update - */ - -import fs from 'node:fs'; -import path from 'node:path'; -import { fileURLToPath } from 'node:url'; - -import { locales, translatedLocales } from '../src/lib/locales.mjs'; - -/** Starlight puts the content's own language on `
`, not just on ``. */ -const MAIN_LANG_RE = /]*\blang="([^"]+)"/; - -/** - * Every built page under a directory, as routes relative to it. - * @param {string} dir - Absolute path to a locale's build output. - * @returns {string[]} Routes such as `start/install-bmad`, sorted. - */ -function builtRoutes(dir) { - if (!fs.existsSync(dir)) return []; - - const routes = []; - const walk = (current) => { - for (const entry of fs.readdirSync(current, { withFileTypes: true })) { - const full = path.join(current, entry.name); - if (entry.isDirectory()) { - walk(full); - } else if (entry.name === 'index.html') { - const route = path.relative(dir, current).split(path.sep).join('/'); - routes.push(route === '' ? 'index' : route); - } - } - }; - walk(dir); - return routes.sort(); -} - -/** - * Find the routes each locale serves in English rather than its own language. - * @param {string} siteDir - Absolute path to the built site. - * @returns {Record} Fallback routes per locale, sorted. - */ -export function findFallbacks(siteDir) { - const fallbacks = {}; - - for (const key of translatedLocales) { - const dir = path.join(siteDir, key); - const expected = locales[key].lang; - const routes = []; - - for (const route of builtRoutes(dir)) { - const file = path.join(dir, route === 'index' ? '' : route, 'index.html'); - const lang = MAIN_LANG_RE.exec(fs.readFileSync(file, 'utf-8'))?.[1]; - // No `
` at all means the page is not a Starlight content page - // (the 404 route, say), so there is nothing to compare. - if (lang && lang !== expected) routes.push(route); - } - - fallbacks[key] = routes; - } - - return fallbacks; -} - -/** - * Compare what the site does now against what the baseline records. - * @param {Record} found - Fallbacks in the built site. - * @param {Record} baseline - Fallbacks the baseline tolerates. - * @returns {{ added: string[], resolved: string[] }} Messages, one per route. - */ -export function diffAgainstBaseline(found, baseline) { - const added = []; - const resolved = []; - - for (const key of translatedLocales) { - const now = new Set(found[key] ?? []); - const before = new Set(baseline[key] ?? []); - - for (const route of now) if (!before.has(route)) added.push(`${key}/${route}`); - for (const route of before) if (!now.has(route)) resolved.push(`${key}/${route}`); - } - - return { added: added.sort(), resolved: resolved.sort() }; -} - -/** A one-line-per-locale summary of how much of each locale is really translated. */ -export function summarise(siteDir, found) { - return translatedLocales.map((key) => { - const total = builtRoutes(path.join(siteDir, key)).length; - const english = found[key]?.length ?? 0; - const share = total === 0 ? 0 : Math.round((100 * english) / total); - return { locale: key, total, english, translated: total - english, share }; - }); -} - -/** - * Check the built site against the baseline. - * @param {string} siteDir - Absolute path to the built site. - * @param {{ baselinePath: string, update?: boolean }} options - * @returns {{ found: Record, summary: object[] }} - * @throws {Error} When a route starts or stops falling back and `update` is off. - */ -export function validateLocaleCoverage(siteDir, { baselinePath, update = false }) { - const found = findFallbacks(siteDir); - const summary = summarise(siteDir, found); - - if (update) { - fs.writeFileSync(baselinePath, `${JSON.stringify(found, null, 2)}\n`); - return { found, summary }; - } - - const baseline = fs.existsSync(baselinePath) ? JSON.parse(fs.readFileSync(baselinePath, 'utf-8')) : {}; - const { added, resolved } = diffAgainstBaseline(found, baseline); - - const problems = []; - if (added.length > 0) { - problems.push( - `${added.length} route(s) now serve English under another locale:`, - ...added.map((route) => ` ${route}`), - ' Add the translation, or record the gap with --update.', - ); - } - if (resolved.length > 0) { - problems.push( - `${resolved.length} baseline entry/entries are no longer falling back:`, - ...resolved.map((route) => ` ${route}`), - ' Rerun with --update so the baseline stops claiming they are missing.', - ); - } - if (problems.length > 0) throw new Error(`Locale coverage changed.\n ${problems.join('\n ')}`); - - return { found, summary }; -} - -if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) { - const siteRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..'); - const projectRoot = path.resolve(siteRoot, '..'); - const update = process.argv.includes('--update'); - - try { - const { summary } = validateLocaleCoverage(path.join(siteRoot, 'dist'), { - baselinePath: path.join(siteRoot, 'locale-coverage-baseline.json'), - update, - }); - for (const row of summary) { - console.log( - ` ${row.locale.padEnd(6)} ${String(row.translated).padStart(3)}/${row.total} translated, ` + - `${row.english} served in English (${row.share}%)`, - ); - } - console.log(update ? 'Baseline updated.' : 'Locale coverage matches the baseline.'); - } catch (error) { - console.error(error.message); - process.exit(1); - } -} diff --git a/docs-site/src/content.config.ts b/docs-site/src/content.config.ts index e54e72fa2e..6a7b7a02b0 100644 --- a/docs-site/src/content.config.ts +++ b/docs-site/src/content.config.ts @@ -1,8 +1,7 @@ import { defineCollection } from 'astro:content'; -import { docsLoader, i18nLoader } from '@astrojs/starlight/loaders'; -import { docsSchema, i18nSchema } from '@astrojs/starlight/schema'; +import { docsLoader } from '@astrojs/starlight/loaders'; +import { docsSchema } from '@astrojs/starlight/schema'; export const collections = { docs: defineCollection({ loader: docsLoader(), schema: docsSchema() }), - i18n: defineCollection({ loader: i18nLoader(), schema: i18nSchema() }), }; diff --git a/docs-site/src/content/i18n/fr-FR.json b/docs-site/src/content/i18n/fr-FR.json deleted file mode 100644 index 839edf969a..0000000000 --- a/docs-site/src/content/i18n/fr-FR.json +++ /dev/null @@ -1,28 +0,0 @@ -{ - "skipLink.label": "Aller au contenu", - "search.label": "Rechercher", - "search.ctrlKey": "Ctrl", - "search.cancelLabel": "Annuler", - "themeSelect.accessibleLabel": "Choisir le thème", - "themeSelect.dark": "Sombre", - "themeSelect.light": "Clair", - "themeSelect.auto": "Automatique", - "languageSelect.accessibleLabel": "Choisir la langue", - "menuButton.accessibleLabel": "Menu", - "sidebarNav.accessibleLabel": "Navigation principale", - "tableOfContents.onThisPage": "Sur cette page", - "tableOfContents.overview": "Aperçu", - "i18n.untranslatedContent": "Ce contenu n'est pas encore disponible en français.", - "page.editLink": "Modifier la page", - "page.lastUpdated": "Dernière mise à jour :", - "page.previousLink": "Page précédente", - "page.nextLink": "Page suivante", - "page.draft": "Ce contenu est un brouillon et ne sera pas inclus dans la version finale.", - "404.text": "Page non trouvée. Vérifiez l'URL ou utilisez la recherche.", - "aside.note": "Note", - "aside.tip": "Astuce", - "aside.caution": "Attention", - "aside.danger": "Danger", - "fileTree.directory": "Répertoire", - "builtWithStarlight.label": "Construit avec Starlight" -} diff --git a/docs-site/src/content/i18n/ko-KR.json b/docs-site/src/content/i18n/ko-KR.json deleted file mode 100644 index 7c4233ff8d..0000000000 --- a/docs-site/src/content/i18n/ko-KR.json +++ /dev/null @@ -1,31 +0,0 @@ -{ - "skipLink.label": "본문으로 건너뛰기", - "search.label": "검색", - "search.ctrlKey": "Ctrl", - "search.cancelLabel": "취소", - "themeSelect.accessibleLabel": "테마 선택", - "themeSelect.dark": "어둡게", - "themeSelect.light": "밝게", - "themeSelect.auto": "자동", - "languageSelect.accessibleLabel": "언어 선택", - "menuButton.accessibleLabel": "메뉴", - "sidebarNav.accessibleLabel": "기본 탐색", - "tableOfContents.onThisPage": "이 페이지에서", - "tableOfContents.overview": "개요", - "i18n.untranslatedContent": "이 콘텐츠는 아직 한국어로 제공되지 않습니다.", - "page.editLink": "이 페이지 편집", - "page.lastUpdated": "마지막 업데이트:", - "page.previousLink": "이전 페이지", - "page.nextLink": "다음 페이지", - "page.draft": "이 콘텐츠는 초안 상태이며 공식 빌드에는 표시되지 않습니다.", - "404.text": "페이지를 찾을 수 없습니다. 주소를 확인하거나 검색을 사용하세요.", - "aside.note": "참고", - "aside.tip": "팁", - "aside.caution": "주의", - "aside.danger": "경고", - "fileTree.directory": "디렉터리", - "builtWithStarlight.label": "Starlight로 제작", - "expressiveCode.copyButtonCopied": "복사했습니다!", - "expressiveCode.copyButtonTooltip": "클립보드에 복사", - "expressiveCode.terminalWindowFallbackTitle": "터미널 창" -} diff --git a/docs-site/src/content/i18n/vi-VN.json b/docs-site/src/content/i18n/vi-VN.json deleted file mode 100644 index a395f2b83d..0000000000 --- a/docs-site/src/content/i18n/vi-VN.json +++ /dev/null @@ -1,28 +0,0 @@ -{ - "skipLink.label": "Chuyển đến nội dung chính", - "search.label": "Tìm kiếm", - "search.ctrlKey": "Ctrl", - "search.cancelLabel": "Hủy", - "themeSelect.accessibleLabel": "Chọn giao diện", - "themeSelect.dark": "Tối", - "themeSelect.light": "Sáng", - "themeSelect.auto": "Tự động", - "languageSelect.accessibleLabel": "Chọn ngôn ngữ", - "menuButton.accessibleLabel": "Menu", - "sidebarNav.accessibleLabel": "Điều hướng chính", - "tableOfContents.onThisPage": "Trên trang này", - "tableOfContents.overview": "Tổng quan", - "i18n.untranslatedContent": "Nội dung này hiện chưa có bản tiếng Việt.", - "page.editLink": "Chỉnh sửa trang", - "page.lastUpdated": "Cập nhật lần cuối:", - "page.previousLink": "Trang trước", - "page.nextLink": "Trang tiếp theo", - "page.draft": "Nội dung này đang ở trạng thái nháp và sẽ không xuất hiện trong bản phát hành chính thức.", - "404.text": "Không tìm thấy trang. Hãy kiểm tra lại đường dẫn hoặc sử dụng tính năng tìm kiếm.", - "aside.note": "Ghi chú", - "aside.tip": "Mẹo", - "aside.caution": "Lưu ý", - "aside.danger": "Cảnh báo", - "fileTree.directory": "Thư mục", - "builtWithStarlight.label": "Được xây dựng với Starlight" -} diff --git a/docs-site/src/content/i18n/zh-CN.json b/docs-site/src/content/i18n/zh-CN.json deleted file mode 100644 index a37ff1505b..0000000000 --- a/docs-site/src/content/i18n/zh-CN.json +++ /dev/null @@ -1,28 +0,0 @@ -{ - "skipLink.label": "跳到正文", - "search.label": "搜索", - "search.ctrlKey": "Ctrl", - "search.cancelLabel": "取消", - "themeSelect.accessibleLabel": "选择主题", - "themeSelect.dark": "深色", - "themeSelect.light": "浅色", - "themeSelect.auto": "自动", - "languageSelect.accessibleLabel": "选择语言", - "menuButton.accessibleLabel": "菜单", - "sidebarNav.accessibleLabel": "侧边导航", - "tableOfContents.onThisPage": "本页目录", - "tableOfContents.overview": "概览", - "i18n.untranslatedContent": "这部分内容暂未提供中文版本。", - "page.editLink": "编辑此页", - "page.lastUpdated": "最后更新：", - "page.previousLink": "上一页", - "page.nextLink": "下一页", - "page.draft": "此内容为草稿，不会出现在正式版本中。", - "404.text": "页面未找到。请检查地址，或使用站内搜索。", - "aside.note": "注意", - "aside.tip": "提示", - "aside.caution": "警告", - "aside.danger": "危险", - "fileTree.directory": "文件夹", - "builtWithStarlight.label": "由 Starlight 构建" -} diff --git a/docs-site/src/lib/locales.mjs b/docs-site/src/lib/locales.mjs deleted file mode 100644 index c86c59202d..0000000000 --- a/docs-site/src/lib/locales.mjs +++ /dev/null @@ -1,43 +0,0 @@ -/** - * Shared i18n locale configuration. - * - * Single source of truth for locale definitions used by: - * - docs-site/astro.config.mjs (Starlight i18n) - * - docs-site/src/pages/404.astro (client-side locale redirect) - * - * The root locale (English) uses Starlight's 'root' key convention - * (no URL prefix). All other locales get a URL prefix matching their key. - */ - -export const locales = { - root: { - label: 'English', - lang: 'en', - }, - 'ko-kr': { - label: '한국어', - lang: 'ko-KR', - }, - 'vi-vn': { - label: 'Tiếng Việt', - lang: 'vi-VN', - }, - 'zh-cn': { - label: '简体中文', - lang: 'zh-CN', - }, - fr: { - label: 'Français', - lang: 'fr-FR', - }, - cs: { - label: 'Čeština', - lang: 'cs-CZ', - }, -}; - -/** - * Non-root locale keys (the URL prefixes for translated content). - * @type {string[]} - */ -export const translatedLocales = Object.keys(locales).filter((k) => k !== 'root'); diff --git a/docs-site/src/pages/404.astro b/docs-site/src/pages/404.astro index 27a01d472a..4af91ca97e 100644 --- a/docs-site/src/pages/404.astro +++ b/docs-site/src/pages/404.astro @@ -1,31 +1,11 @@ --- import StarlightPage from '@astrojs/starlight/components/StarlightPage.astro'; import { getEntry, render } from 'astro:content'; -import { translatedLocales } from '../lib/locales.mjs'; const entry = await getEntry('docs', '404'); const { Content } = await render(entry); -const basePath = import.meta.env.BASE_URL; --- - - - diff --git a/docs-site/test/test-english-only-site.mjs b/docs-site/test/test-english-only-site.mjs new file mode 100644 index 0000000000..ef75272ca0 --- /dev/null +++ b/docs-site/test/test-english-only-site.mjs @@ -0,0 +1,72 @@ +/** + * English-only site checks for the locale removal. + * + * Usage: node docs-site/test/test-english-only-site.mjs + */ + +import assert from 'node:assert/strict'; +import { mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'; +import { tmpdir } from 'node:os'; +import { join } from 'node:path'; + +import { parseRedirects } from '../scripts/validate-redirects.mjs'; +import rehypeInlineDiagrams from '../src/rehype-inline-diagrams.js'; + +const LOCALE_PREFIX = /^\/(?:fr|cs|ko-kr|vi-vn|zh-cn)\//; +const tests = []; + +function test(name, run) { + tests.push({ name, run }); +} + +test('locale URLs have no redirect', () => { + const source = readFileSync(new URL('../astro.config.mjs', import.meta.url), 'utf8'); + const locale = parseRedirects(source).filter((entry) => LOCALE_PREFIX.test(entry.from)); + assert.deepEqual(locale, []); +}); + +test('a diagram keeps its English text when locales are omitted', () => { + const root = mkdtempSync(join(tmpdir(), 'bmad-en-diagram-')); + try { + mkdirSync(join(root, 'src', 'diagrams'), { recursive: true }); + writeFileSync( + join(root, 'src', 'diagrams', 'flow.svg'), + 'Start', + ); + const tree = { + type: 'root', + children: [ + { + type: 'element', + tagName: 'img', + properties: { src: '/diagrams/flow.svg', alt: 'a diagram' }, + children: [], + }, + ], + }; + rehypeInlineDiagrams({ root })(tree, { path: '/project/docs/build/a-change.md' }); + assert.equal(tree.children[0].tagName, 'svg'); + assert.match(JSON.stringify(tree), /"value":"Start"/); + } finally { + rmSync(root, { recursive: true, force: true }); + } +}); + +let failures = 0; + +for (const { name, run } of tests) { + try { + run(); + console.log(` \u001B[32m✓\u001B[0m ${name}`); + } catch (error) { + failures++; + console.error(` \u001B[31m✗\u001B[0m ${name}: ${error.message}`); + } +} + +if (failures > 0) { + console.error(`\n${failures} English-only site test${failures === 1 ? '' : 's'} failed.`); + process.exit(1); +} + +console.log(`\nAll ${tests.length} English-only site tests passed.`); diff --git a/docs-site/test/test-validate-locale-coverage.mjs b/docs-site/test/test-validate-locale-coverage.mjs deleted file mode 100644 index a3c36c4b5a..0000000000 --- a/docs-site/test/test-validate-locale-coverage.mjs +++ /dev/null @@ -1,168 +0,0 @@ -/** - * Tests for the locale coverage guard. - * - * Usage: node docs-site/test/test-validate-locale-coverage.mjs - */ - -import assert from 'node:assert/strict'; -import fs from 'node:fs'; -import os from 'node:os'; -import path from 'node:path'; - -import { diffAgainstBaseline, findFallbacks, summarise, validateLocaleCoverage } from '../scripts/validate-locale-coverage.mjs'; - -const tests = []; - -function test(name, run) { - tests.push({ name, run }); -} - -/** A built page whose `
` declares `lang`, as Starlight emits it. */ -function page(lang) { - return `
x
`; -} - -function withFixture(files, run) { - const root = fs.mkdtempSync(path.join(os.tmpdir(), 'bmad-locale-')); - try { - for (const [relativePath, content] of Object.entries(files)) { - const full = path.join(root, relativePath); - fs.mkdirSync(path.dirname(full), { recursive: true }); - fs.writeFileSync(full, content); - } - return run(root); - } finally { - fs.rmSync(root, { recursive: true, force: true }); - } -} - -test('reports a page whose content language is not the locale', () => { - withFixture( - { - 'site/fr/start/install-bmad/index.html': page('en'), - 'site/fr/how-to/install-bmad/index.html': page('fr-FR'), - }, - (root) => { - const found = findFallbacks(path.join(root, 'site')); - assert.deepEqual(found.fr, ['start/install-bmad']); - }, - ); -}); - -test('treats a page with no
as nothing to check', () => { - withFixture({ 'site/fr/404/index.html': '
x
' }, (root) => - assert.deepEqual(findFallbacks(path.join(root, 'site')).fr, []), - ); -}); - -test('reports the locale index itself', () => { - withFixture({ 'site/cs/index.html': page('en') }, (root) => assert.deepEqual(findFallbacks(path.join(root, 'site')).cs, ['index'])); -}); - -test('leaves a locale with no build output empty rather than failing', () => { - withFixture({ 'site/fr/index.html': page('fr-FR') }, (root) => { - const found = findFallbacks(path.join(root, 'site')); - assert.deepEqual(found.fr, []); - assert.deepEqual(found['zh-cn'], []); - }); -}); - -test('counts a new fallback as added and a fixed one as resolved', () => { - const { added, resolved } = diffAgainstBaseline({ fr: ['start/install-bmad'], cs: [] }, { fr: ['plan/research-a-decision'], cs: [] }); - assert.deepEqual(added, ['fr/start/install-bmad']); - assert.deepEqual(resolved, ['fr/plan/research-a-decision']); -}); - -test('says nothing when the site matches the baseline exactly', () => { - const { added, resolved } = diffAgainstBaseline({ fr: ['a', 'b'] }, { fr: ['b', 'a'] }); - assert.deepEqual(added, []); - assert.deepEqual(resolved, []); -}); - -test('summarises translated against total routes per locale', () => { - withFixture( - { - 'site/fr/a/index.html': page('en'), - 'site/fr/b/index.html': page('fr-FR'), - 'site/fr/c/index.html': page('fr-FR'), - }, - (root) => { - const siteDir = path.join(root, 'site'); - const row = summarise(siteDir, findFallbacks(siteDir)).find((r) => r.locale === 'fr'); - assert.deepEqual( - { total: row.total, translated: row.translated, english: row.english, share: row.share }, - { total: 3, translated: 2, english: 1, share: 33 }, - ); - }, - ); -}); - -test('fails on a fallback the baseline does not record', () => { - withFixture({ 'site/fr/start/install-bmad/index.html': page('en') }, (root) => { - const baselinePath = path.join(root, 'baseline.json'); - fs.writeFileSync(baselinePath, '{}'); - assert.throws( - () => validateLocaleCoverage(path.join(root, 'site'), { baselinePath }), - /now serve English under another locale[\s\S]*fr\/start\/install-bmad/, - ); - }); -}); - -test('fails on a baseline entry that no longer falls back', () => { - withFixture({ 'site/fr/start/install-bmad/index.html': page('fr-FR') }, (root) => { - const baselinePath = path.join(root, 'baseline.json'); - fs.writeFileSync(baselinePath, JSON.stringify({ fr: ['start/install-bmad'] })); - assert.throws( - () => validateLocaleCoverage(path.join(root, 'site'), { baselinePath }), - /no longer falling back[\s\S]*fr\/start\/install-bmad/, - ); - }); -}); - -test('passes when the fallbacks are exactly the ones recorded', () => { - withFixture({ 'site/fr/start/install-bmad/index.html': page('en') }, (root) => { - const baselinePath = path.join(root, 'baseline.json'); - fs.writeFileSync(baselinePath, JSON.stringify({ fr: ['start/install-bmad'] })); - assert.doesNotThrow(() => validateLocaleCoverage(path.join(root, 'site'), { baselinePath })); - }); -}); - -test('--update rewrites the baseline instead of failing', () => { - withFixture({ 'site/fr/start/install-bmad/index.html': page('en') }, (root) => { - const baselinePath = path.join(root, 'baseline.json'); - fs.writeFileSync(baselinePath, '{}'); - validateLocaleCoverage(path.join(root, 'site'), { baselinePath, update: true }); - assert.deepEqual(JSON.parse(fs.readFileSync(baselinePath, 'utf-8')).fr, ['start/install-bmad']); - }); -}); - -test('treats a missing baseline as recording no gaps at all', () => { - withFixture({ 'site/fr/a/index.html': page('en') }, (root) => { - assert.throws( - () => - validateLocaleCoverage(path.join(root, 'site'), { - baselinePath: path.join(root, 'does-not-exist.json'), - }), - /fr\/a/, - ); - }); -}); - -let failures = 0; - -for (const { name, run } of tests) { - try { - run(); - console.log(` ✓ ${name}`); - } catch (error) { - failures++; - console.error(` ✗ ${name}: ${error.message}`); - } -} - -if (failures > 0) { - console.error(`\n${failures} locale coverage test${failures === 1 ? '' : 's'} failed.`); - process.exit(1); -} - -console.log(`\nAll ${tests.length} locale coverage tests passed.`); diff --git a/docs/cs/404.md b/docs/cs/404.md deleted file mode 100644 index 74ba6c89be..0000000000 --- a/docs/cs/404.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -title: Stránka nenalezena -template: splash ---- - -Stránka, kterou hledáte, neexistuje nebo byla přesunuta. - -[Zpět na úvodní stránku](/cs/index.md) diff --git a/docs/cs/_STYLE_GUIDE.md b/docs/cs/_STYLE_GUIDE.md deleted file mode 100644 index c6082cdf5e..0000000000 --- a/docs/cs/_STYLE_GUIDE.md +++ /dev/null @@ -1,371 +0,0 @@ ---- -title: "Průvodce stylem dokumentace" -description: Projektově specifické konvence dokumentace založené na stylu Google a struktuře Diataxis ---- - -Tento projekt se řídí [Google Developer Documentation Style Guide](https://developers.google.com/style) a používá [Diataxis](https://diataxis.fr/) pro strukturování obsahu. Následují pouze projektově specifické konvence. - -## Projektově specifická pravidla - -| Pravidlo | Specifikace | -| -------------------------------------- | ---------------------------------------- | -| Žádné horizontální čáry (`---`) | Narušují plynulost čtení | -| Žádné nadpisy `####` | Místo toho použijte tučný text nebo admonitions | -| Žádné sekce „Souvisejí“ nebo „Další:“ | Navigaci zajišťuje postranní panel | -| Žádné hluboce vnořené seznamy | Místo toho rozdělejte do sekcí | -| Žádné bloky kódu pro nekód | Pro příklady dialogů použijte admonitions | -| Žádné tučné odstavce pro upozornění | Místo toho použijte admonitions | -| Max 1–2 admonitions na sekci | Tutoriály povolují 3–4 na hlavní sekci | -| Buňky tabulek / položky seznamů | Max 1–2 věty | -| Rozpočet nadpisů | 8–12 `##` na dokument; 2–3 `###` na sekci | - -## Admonitions (syntaxe Starlight) - -```md -:::tip[Název] -Zkratky, osvědčené postupy -::: - -:::note[Název] -Kontext, definice, příklady, předpoklady -::: - -:::caution[Název] -Upozornění, potenciální problémy -::: - -:::danger[Název] -Pouze kritická varování — ztráta dat, bezpečnostní problémy -::: -``` - -### Standardní použití - -| Admonition | Použití pro | -| ------------------------ | ----------------------------- | -| `:::note[Předpoklady]` | Závislosti před začátkem | -| `:::tip[Rychlá cesta]` | TL;DR shrnutí na začátku dokumentu | -| `:::caution[Důležité]` | Kritická upozornění | -| `:::note[Příklad]` | Příklady příkazů/odpovědí | - -## Standardní formáty tabulek - -**Fáze:** - -```md -| Fáze | Název | Co se děje | -| ---- | -------- | -------------------------------------------- | -| 1 | Analýza | Brainstorming, průzkum *(volitelné)* | -| 2 | Plánování | Požadavky — PRD nebo specifikace *(povinné)* | -``` - -**Skills:** - -```md -| Skill | Agent | Účel | -| -------------------- | ------- | ------------------------------------ | -| `bmad-brainstorming` | Analytik | Brainstorming nového projektu | -| `bmad-prd` | PM | Vytvoření dokumentu požadavků (PRD) | -``` - -## Bloky struktury složek - -Zobrazujte v sekcích „Co jste dosáhli“: - -````md -``` -váš-projekt/ -├── _bmad/ # Konfigurace BMad -├── _bmad-output/ -│ ├── planning-artifacts/ -│ │ └── PRD.md # Váš dokument požadavků -│ ├── implementation-artifacts/ -│ └── project-context.md # Pravidla implementace (volitelné) -└── ... -``` -```` - -## Struktura tutoriálu - -```text -1. Název + Háček (1–2 věty popisující výsledek) -2. Upozornění na verzi/modul (info nebo warning admonition) (volitelné) -3. Co se naučíte (odrážkový seznam výsledků) -4. Předpoklady (info admonition) -5. Rychlá cesta (tip admonition – TL;DR shrnutí) -6. Pochopení [Tématu] (kontext před kroky – tabulky pro fáze/agenty) -7. Instalace (volitelné) -8. Krok 1: [První hlavní úkol] -9. Krok 2: [Druhý hlavní úkol] -10. Krok 3: [Třetí hlavní úkol] -11. Co jste dosáhli (shrnutí + struktura složek) -12. Rychlý přehled (tabulka skills) -13. Časté otázky (formát FAQ) -14. Získání pomoci (komunitní odkazy) -15. Klíčové poznatky (tip admonition) -``` - -### Kontrolní seznam tutoriálu - -- [ ] Háček popisuje výsledek v 1–2 větách -- [ ] Sekce „Co se naučíte“ je přítomna -- [ ] Předpoklady v admonition -- [ ] Rychlá cesta TL;DR admonition nahoře -- [ ] Tabulky pro fáze, skills, agenty -- [ ] Sekce „Co jste dosáhli“ je přítomna -- [ ] Tabulka rychlého přehledu je přítomna -- [ ] Sekce častých otázek je přítomna -- [ ] Sekce získání pomoci je přítomna -- [ ] Klíčové poznatky admonition na konci - -## Struktura praktického návodu - -```text -1. Název + Háček (jedna věta: „Použijte workflow `X` k...“) -2. Kdy to použít (odrážkový seznam scénářů) -3. Kdy to přeskočit (volitelné) -4. Předpoklady (note admonition) -5. Kroky (číslované ### podsekce) -6. Co získáte (výstup/vytvořené artefakty) -7. Příklad (volitelné) -8. Tipy (volitelné) -9. Další kroky (volitelné) -``` - -### Kontrolní seznam praktického návodu - -- [ ] Háček začíná „Použijte workflow `X` k...“ -- [ ] „Kdy to použít“ má 3–5 odrážek -- [ ] Předpoklady jsou uvedeny -- [ ] Kroky jsou číslované `###` podsekce s akčními slovesy -- [ ] „Co získáte“ popisuje výstupní artefakty - -## Struktura vysvětlení - -### Typy - -| Typ | Příklad | -| ----------------- | ----------------------------- | -| **Úvodní stránka** | `core-concepts/index.md` | -| **Koncept** | `what-are-agents.md` | -| **Funkce** | `build.md` | -| **Filosofie** | `why-solutioning-matters.md` | -| **FAQ** | `established-projects-faq.md` | - -### Obecná šablona - -```text -1. Název + Háček (1–2 věty) -2. Přehled/Definice (co to je, proč je to důležité) -3. Klíčové koncepty (### podsekce) -4. Srovnávací tabulka (volitelné) -5. Kdy použít / Kdy nepoužít (volitelné) -6. Diagram (volitelné – mermaid, max 1 na dokument) -7. Další kroky (volitelné) -``` - -### Úvodní/Vstupní stránky - -```text -1. Název + Háček (jedna věta) -2. Tabulka obsahu (odkazy s popisy) -3. Jak začít (číslovaný seznam) -4. Vyberte si svou cestu (volitelné – rozhodovací strom) -``` - -### Vysvětlení konceptů - -```text -1. Název + Háček (co to je) -2. Typy/Kategorie (### podsekce) (volitelné) -3. Tabulka klíčových rozdílů -4. Komponenty/Části -5. Co byste měli použít? -6. Vytváření/Přizpůsobení (odkaz na praktické návody) -``` - -### Vysvětlení funkcí - -```text -1. Název + Háček (co to dělá) -2. Rychlá fakta (volitelné – „Ideální pro:“, „Čas:“) -3. Kdy použít / Kdy nepoužít -4. Jak to funguje (mermaid diagram volitelné) -5. Klíčové výhody -6. Srovnávací tabulka (volitelné) -7. Kdy přejít na vyšší úroveň (volitelné) -``` - -### Dokumenty filosofie/zdůvodnění - -```text -1. Název + Háček (princip) -2. Problém -3. Řešení -4. Klíčové principy (### podsekce) -5. Výhody -6. Kdy to platí -``` - -### Kontrolní seznam vysvětlení - -- [ ] Háček uvádí, co dokument vysvětluje -- [ ] Obsah v přehledných `##` sekcích -- [ ] Srovnávací tabulky pro 3+ možností -- [ ] Diagramy mají jasné popisky -- [ ] Odkazy na praktické návody pro procedurální otázky -- [ ] Max 2–3 admonitions na dokument - -## Struktura reference - -### Typy - -| Typ | Příklad | -| ----------------- | --------------------- | -| **Úvodní stránka** | `workflows/index.md` | -| **Katalog** | `agents/index.md` | -| **Hloubkový pohled** | `document-project.md` | -| **Konfigurace** | `core-tasks.md` | -| **Slovníček** | `glossary/index.md` | -| **Komplexní** | `bmgd-workflows.md` | - -### Úvodní stránky reference - -```text -1. Název + Háček (jedna věta) -2. Sekce obsahu (## pro každou kategorii) - - Odrážkový seznam s odkazy a popisy -``` - -### Katalogová reference - -```text -1. Název + Háček -2. Položky (## pro každou položku) - - Stručný popis (jedna věta) - - **Skills:** nebo **Klíčové info:** jako plochý seznam -3. Univerzální/Sdílené (## sekce) (volitelné) -``` - -### Hloubková reference položky - -```text -1. Název + Háček (jedna věta účel) -2. Rychlá fakta (volitelné note admonition) - - Modul, Skill, Vstup, Výstup jako seznam -3. Účel/Přehled (## sekce) -4. Jak vyvolat (blok kódu) -5. Klíčové sekce (## pro každý aspekt) - - Použijte ### pro pod-možnosti -6. Poznámky/Upozornění (tip nebo caution admonition) -``` - -### Konfigurační reference - -```text -1. Název + Háček -2. Obsah (odkazy pro skok, pokud 4+ položek) -3. Položky (## pro každou konfiguraci/úkol) - - **Tučné shrnutí** — jedna věta - - **Použijte když:** odrážkový seznam - - **Jak to funguje:** číslované kroky (max 3–5) - - **Výstup:** očekávaný výsledek (volitelné) -``` - -### Komplexní referenční průvodce - -```text -1. Název + Háček -2. Přehled (## sekce) - - Diagram nebo tabulka zobrazující organizaci -3. Hlavní sekce (## pro každou fázi/kategorii) - - Položky (### pro každou položku) - - Standardizovaná pole: Skill, Agent, Vstup, Výstup, Popis -4. Další kroky (volitelné) -``` - -### Kontrolní seznam reference - -- [ ] Háček uvádí, co dokument referuje -- [ ] Struktura odpovídá typu reference -- [ ] Položky používají konzistentní strukturu -- [ ] Tabulky pro strukturovaná/srovnávací data -- [ ] Odkazy na dokumenty vysvětlení pro koncepční hloubku -- [ ] Max 1–2 admonitions - -## Struktura slovníčku - -Starlight generuje navigaci „Na této stránce“ z nadpisů na pravé straně: - -- Kategorie jako `##` nadpisy — zobrazují se v pravé navigaci -- Termíny v tabulkách — kompaktní řádky, ne jednotlivé nadpisy -- Žádný inline TOC — pravý panel zajišťuje navigaci - -### Formát tabulky - -```md -## Název kategorie - -| Termín | Definice | -| ------------ | ------------------------------------------------------------------------------------------- | -| **Agent** | Specializovaná AI persona s konkrétní odborností, která provází uživatele pracovními postupy. | -| **Workflow** | Vícekrokový řízený proces, který orchestruje aktivity AI agentů k vytvoření výstupů. | -``` - -### Pravidla definic - -| Správně | Špatně | -| ------------------------------ | -------------------------------------------- | -| Začněte tím, co to JE nebo DĚLÁ | Nezačínejte „Toto je...“ nebo „[Termín] je...“ | -| Držte se 1–2 vět | Nepište víceodstavcová vysvětlení | -| Tučný název termínu v buňce | Nepoužívejte prostý text pro termíny | - -### Kontextové značky - -Přidejte kurzívní kontext na začátek definice pro termíny s omezeným rozsahem: - -- `*Pouze přímý vstup do implementace.*` -- `*BMad Method/Enterprise.*` -- `*Fáze N.*` -- `*BMGD.*` -- `*Existující projekty.*` - -### Kontrolní seznam slovníčku - -- [ ] Termíny v tabulkách, ne jako jednotlivé nadpisy -- [ ] Termíny abecedně seřazeny v kategoriích -- [ ] Definice 1–2 věty -- [ ] Kontextové značky kurzívou -- [ ] Názvy termínů tučně v buňkách -- [ ] Žádné definice „[Termín] je...“ - -## Sekce FAQ - -```md -## Otázky - -- [Potřebuji vždy architekturu?](#potřebuji-vždy-architekturu) -- [Mohu později změnit svůj plán?](#mohu-později-změnit-svůj-plán) - -### Potřebuji vždy architekturu? - -Pouze pro práci, které prospívá architektura. Jasná práce může vstoupit přímo do implementace. - -### Mohu později změnit svůj plán? - -Ano. SM agent má workflow `bmad-correct-course` pro řešení změn rozsahu. - -**Máte otázku, na kterou jste zde nenašli odpověď?** [Vytvořte issue](...) nebo se zeptejte na [Discordu](...). -``` - -## Validační příkazy - -Před odesláním změn dokumentace: - -```bash -cd docs-site -npm run fix-links # Náhled oprav formátu odkazů -npm run fix-links -- --write # Aplikovat opravy -npm run validate-links # Kontrola existence odkazů -npm run build # Ověření bez chyb při sestavení -``` diff --git a/docs/cs/explanation/advanced-elicitation.md b/docs/cs/explanation/advanced-elicitation.md deleted file mode 100644 index b1fcec3152..0000000000 --- a/docs/cs/explanation/advanced-elicitation.md +++ /dev/null @@ -1,49 +0,0 @@ ---- -title: "Pokročilá elicitace" -description: Přimějte LLM přehodnotit svou práci pomocí strukturovaných metod uvažování -sidebar: - order: 3 ---- - -Přimějte LLM přehodnotit, co právě vygeneroval. Vyberete metodu uvažování, LLM ji aplikuje na svůj vlastní výstup, a vy rozhodnete, zda si vylepšení ponecháte. - -## Co je pokročilá elicitace? - -Strukturovaný druhý průchod. Místo žádání AI, aby „to zkusila znovu“ nebo „to zlepšila“, vyberete specifickou metodu uvažování a AI přezkoumá svůj vlastní výstup přes tento objektiv. - -Rozdíl je podstatný. Vágní požadavky produkují vágní revize. Pojmenovaná metoda vynucuje konkrétní úhel útoku, odhaluje postřehy, které by generický pokus přehlédl. - -## Kdy ji použít - -- Poté, co workflow vygeneruje obsah a chcete alternativy -- Když výstup vypadá v pořádku, ale tušíte, že je v něm víc hloubky -- K zátěžovému testování předpokladů nebo nalezení slabých míst -- Pro důležitý obsah, kde přehodnocení pomáhá - -Workflow nabízejí pokročilou elicitaci v rozhodovacích bodech — poté, co LLM něco vygeneruje, budete dotázáni, zda ji chcete spustit. - -## Jak to funguje - -1. LLM navrhne 5 relevantních metod pro váš obsah -2. Vyberete jednu (nebo zamícháte pro jiné možnosti) -3. Metoda je aplikována, vylepšení zobrazena -4. Přijměte nebo zahoďte, opakujte nebo pokračujte - -## Vestavěné metody - -K dispozici jsou desítky metod uvažování. Několik příkladů: - -- **Pre-mortem analýza** — Předpokládejte, že projekt už selhal, a zpětně hledejte proč -- **Myšlení z prvních principů** — Odstraňte předpoklady, znovu postavte od základní pravdy -- **Inverze** — Zeptejte se, jak zaručit selhání, a poté se tomu vyhněte -- **Red Team vs Blue Team** — Napadněte vlastní práci, pak ji braňte -- **Sokratovské dotazování** — Zpochybněte každé tvrzení otázkou „proč?“ a „jak víte?“ -- **Odstranění omezení** — Odstraňte všechna omezení, podívejte se, co se změní, selektivně je přidejte zpět -- **Mapování zainteresovaných stran** — Přehodnoťte z perspektivy každé zainteresované strany -- **Analogické uvažování** — Najděte paralely v jiných oblastech a aplikujte jejich lekce - -A mnoho dalších. AI vybírá nejrelevantnější možnosti pro váš obsah — vy si vyberete, kterou spustit. - -:::tip[Začněte zde] -Pre-mortem analýza je dobrá první volba pro jakoukoli specifikaci nebo plán. Konzistentně nachází mezery, které standardní revize přehlédne. -::: diff --git a/docs/cs/explanation/analysis-phase.md b/docs/cs/explanation/analysis-phase.md deleted file mode 100644 index 71b6dd6501..0000000000 --- a/docs/cs/explanation/analysis-phase.md +++ /dev/null @@ -1,70 +0,0 @@ ---- -title: "Fáze analýzy: od nápadu k základům" -description: Co je brainstorming, výzkum, product brief a PRFAQ — a kdy který nástroj použít -sidebar: - order: 1 ---- - -Fáze analýzy (fáze 1) vám pomůže jasně si promyslet váš produkt, než se pustíte do jeho tvorby. Každý nástroj v této fázi je volitelný, ale úplné vynechání analýzy znamená, že váš PRD je postaven na předpokladech namísto vhledu. - -## Proč analýza před plánováním? - -PRD odpovídá na otázku „Co bychom měli postavit a proč?“. Pokud jej nakrmíte vágním myšlením, získáte vágní PRD — a každý navazující dokument tuto vágnost zdědí. Architektura postavená na slabém PRD sází na špatnou techniku. Příběhy odvozené ze slabé architektury opomíjejí okrajové případy. Náklady se zvyšují. - -Existují analytické nástroje, které vám PRD zostří. Napadají problém z různých úhlů — kreativní průzkum, realita trhu, jasnost zákazníka, proveditelnost — takže v době, kdy sedíte s agentem PM, víte, co a pro koho stavíte. - -## Nástroje - -### Brainstorming - -**Co to je.** Zprostředkované tvůrčí sezení s využitím osvědčených technik generování nápadů. AI funguje jako kouč, který z vás tahá nápady prostřednictvím strukturovaných cvičení — negeneruje nápady za vás. - -**Proč je to tady.** Neotřelé nápady potřebují prostor pro rozvoj, než se zakotví v požadavcích. Brainstorming tento prostor vytváří. Je cenný zejména tehdy, když máte problémovou oblast, ale nemáte jasné řešení, nebo když chcete prozkoumat více směrů, než se k něčemu zavážete. - -**Kdy jej použít.** Máte nejasnou představu o tom, co chcete vytvořit, ale nemáte vykrystalizovaný koncept. Nebo máte koncept, ale chcete ho otestovat pod tlakem oproti alternativám. - -Viz [Brainstorming](./brainstorming.md), kde se dozvíte, jak relace fungují. - -### Výzkum (trhu, domény, technický) - -**Co to je.** Tři cílené pracovní postupy výzkumu, které zkoumají různé rozměry vašeho nápadu. Výzkum trhu zkoumá konkurenci, trendy a nálady uživatelů. Doménový výzkum vytváří odborné znalosti v daném oboru a terminologii. Technický výzkum hodnotí proveditelnost, možnosti architektury a přístupy k implementaci. - -**Proč je to tady.** Stavět na předpokladech je nejrychlejší způsob, jak vytvořit něco, co nikdo nepotřebuje. Výzkum zakládá váš koncept na realitě — co již existuje u konkurence, s čím uživatelé skutečně bojují, co je technicky proveditelné a jakým omezením specifickým pro dané odvětví budete čelit. - -**Kdy ho použít.** Vstupujete do neznámé oblasti, tušíte, že konkurence existuje, ale nemáte ji zmapovanou, nebo váš koncept závisí na technických možnostech, které nemáte ověřené. Proveďte jeden, dva nebo všechny tři — každý z nich je samostatný. - -### Product Brief - -**Co to je.** Řízené zjišťovací sezení, jehož výsledkem je 1–2stránkové shrnutí vašeho konceptu produktu. AI funguje jako spolupracující obchodní analytik, který vám pomůže formulovat vizi, cílovou skupinu, nabídku hodnoty a rozsah. - -**Proč tu je.** Produktový brief je jemnější cestou k plánování. Zachycuje vaši strategickou vizi ve strukturovaném formátu, který se přímo promítá do tvorby PRD. Nejlépe funguje, když jste již o svém konceptu přesvědčeni — znáte zákazníka, problém a zhruba víte, co chcete vytvořit. Brief tyto úvahy uspořádá a vyostří. - -**Kdy jej použít.** Váš koncept je relativně jasný a chcete jej efektivně zdokumentovat ještě před vytvořením PRD. Jste si jisti svým směřováním a nepotřebujete své předpoklady agresivně zpochybňovat. - -### PRFAQ (Working Backwards) - -**Co to je.** Metodika Working Backwards společnosti Amazon upravená jako interaktivní výzva. Napíšete tiskovou zprávu oznamující váš hotový produkt dříve, než existuje jediný řádek kódu, a pak odpovíte na nejtěžší otázky, které by vám zákazníci a zainteresované strany položili. Umělá inteligence funguje jako neúprosný, ale konstruktivní produktový kouč. - -**Proč je to tady.** PRFAQ je přísná cesta k plánování. Vynucuje si jasnost v zájmu zákazníka tím, že vás nutí obhájit každé tvrzení. Pokud nedokážete napsat přesvědčivou tiskovou zprávu, produkt není připraven. Pokud odpovědi na časté dotazy zákazníků odhalí nedostatky, jsou to nedostatky, které byste objevili mnohem později — a nákladněji — při implementaci. Hozená rukavice odhalí slabé myšlení v rané fázi, kdy je nejlevnější ho opravit. - -**Kdy ji použít.** Před vyčleněním zdrojů chcete, aby váš koncept prošel zátěžovým testem. Nejste si jisti, zda to uživatele bude skutečně zajímat. Chcete si ověřit, že dokážete formulovat jasnou a obhajitelnou nabídku hodnoty. Nebo si prostě chcete disciplínou Working Backwards zpřesnit své myšlení. - -## Který nástroj bych měl použít? - -| Situace | Doporučený nástroj | -| --------- | ---------------- | -| „Mám nejasný nápad, ale nevím, kde začít“ | Brainstorming | -| „Než se rozhodnu, potřebuji pochopit trh“ | Výzkum | -| „Vím, co chci vytvořit, jen to potřebuji zdokumentovat“ | Product Brief | -| „Chci se ujistit, že tento nápad skutečně stojí za vybudování“ | PRFAQ | -| „Chci prozkoumat, pak ověřit a pak zdokumentovat“ | Brainstorming → Výzkum → PRFAQ nebo Brief | - -Product Brief i PRFAQ jsou vstupem pro PRD — vyberte si jeden z nich podle toho, jak moc chcete být nároční. Brief je společným objevováním. PRFAQ je hozená rukavice. Obojí vás dovede ke stejnému cíli; PRFAQ testuje, zda si váš koncept zaslouží se tam dostat. - -:::tip[Nejste si jisti?] -Spusťte `bmad-help` a popište svou situaci. Doporučí vám správný výchozí bod na základě toho, co jste již udělali a čeho se snažíte dosáhnout. -::: - -## Co se stane po analýze? - -Výstupy analýzy se přímo promítají do fáze 2 (plánování). Pracovní postup PRD přijímá jako vstupy produktové briefy, dokumenty PRFAQ, výsledky výzkumu a zprávy z brainstormingu — syntetizuje vše, co jste vytvořili, do strukturovaných požadavků. Čím více analýz provedete, tím ostřejší bude vaše PRD. diff --git a/docs/cs/explanation/brainstorming.md b/docs/cs/explanation/brainstorming.md deleted file mode 100644 index 6853120980..0000000000 --- a/docs/cs/explanation/brainstorming.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -title: "Brainstorming" -description: Interaktivní kreativní sezení s využitím 60+ osvědčených technik ideace -sidebar: - order: 2 ---- - -Uvolněte svou kreativitu prostřednictvím řízeného průzkumu. - -## Co je brainstorming? - -Spusťte `bmad-brainstorming` a máte kreativního facilitátora, který z vás táhne nápady — ne který je generuje za vás. AI působí jako kouč a průvodce, používá osvědčené techniky k vytvoření podmínek, ve kterých se projeví vaše nejlepší myšlení. - -**Ideální pro:** - -- Překonání kreativních bloků -- Generování nápadů na produkty nebo funkce -- Zkoumání problémů z nových úhlů -- Rozvíjení surových konceptů do akčních plánů - -## Jak to funguje - -1. **Příprava** — Definujte téma, cíle, omezení -2. **Volba přístupu** — Vyberte techniky sami, nechte si doporučit od AI, zvolte náhodně, nebo postupujte progresivním tokem -3. **Facilitace** — Projděte techniky s podněcujícími otázkami a kolaborativním koučováním -4. **Organizace** — Nápady seskupeny do témat a prioritizovány -5. **Akce** — Nejlepší nápady dostanou další kroky a metriky úspěchu - -Vše je zachyceno v dokumentu sezení, na který se můžete později odkazovat nebo ho sdílet se zúčastněnými stranami. - -:::note[Vaše nápady] -Každý nápad pochází od vás. Workflow vytváří podmínky pro vhled — vy jste zdrojem. -::: diff --git a/docs/cs/explanation/build.md b/docs/cs/explanation/build.md deleted file mode 100644 index 94839c2fd5..0000000000 --- a/docs/cs/explanation/build.md +++ /dev/null @@ -1,77 +0,0 @@ ---- -title: "Build" -description: Snižte tření human-in-the-loop bez ztráty kontrolních bodů chránících kvalitu výstupu -sidebar: - order: 6 ---- - -`bmad-build` je standardní implementační workflow pro veškerou vývojovou práci. Přijímá vše od volně formulovaného záměru nebo issue po plně naplánovanou story a vytváří změny kódu s minimem bezpečných human-in-the-loop kroků. - -Upstream plánování je volitelné a jeho hloubka se liší. Jasná změna může vstoupit přímo; větší iniciativa může přinést PRD, UX, architekturu, epicy, stories, kontrolu připravenosti a sprint plán. Tyto artefakty posilují kontext, nevybírají jiný vývojový workflow. - -Když do Build vstoupí naplánovaná story, zůstává zdrojem produktového kontextu a akceptačních kritérií. Build vytvoří vlastní záznam provedení aktuálního běhu, aby implementační rozhodnutí a nálezy revize zůstaly dohledatelné, aniž by story nahrazoval. - -Umožňuje modelu běžet déle mezi kontrolními body a poté přivede člověka zpět pouze tehdy, když úkol nemůže bezpečně pokračovat bez lidského úsudku nebo když je čas zkontrolovat konečný výsledek. - -![Diagram workflow Build](/diagrams/build-run.svg) - -## Proč to existuje - -Human-in-the-loop kroky jsou nutné a nákladné. - -Současné LLM stále selhávají předvídatelnými způsoby: chybně čtou záměr, vyplňují mezery sebevědomými odhady, odchylují se k nesouvisející práci a generují šumový výstup revize. Současně neustálá lidská intervence limituje rychlost vývoje. Lidská pozornost je úzké hrdlo. - -`bmad-build` přenastavuje tento kompromis. Důvěřuje modelu, aby běžel bez dozoru delší úseky, ale pouze poté, co workflow vytvořil dostatečně silnou hranici, aby to bylo bezpečné. - -## Základní design - -### 1. Nejprve komprimujte záměr - -Workflow začíná tím, že člověk a model zkomprimují požadavek do jednoho koherentního cíle. Vstup může začínat jako hrubé vyjádření záměru, ale předtím, než workflow poběží autonomně, musí být dostatečně malý, jasný a bez protimluvů pro provedení. - -Záměr může přijít v mnoha formách: pár frází, odkaz na bug tracker, výstup z plan mode, text zkopírovaný z chatové relace nebo naplánovaná story z epiců a sprint artefaktů BMad. Workflow použije veškerý dostupný upstream kontext a vyřeší mezery potřebné pro bezpečnou implementaci. - -Tento workflow neodstraňuje lidskou kontrolu. Přemisťuje ji na malý počet vysoce hodnotných momentů: - -- **Vyjasnění záměru** — přeměna nepřehledného požadavku na jeden koherentní cíl bez skrytých protimluvů -- **Schválení specifikace** — potvrzení, že zmrazené porozumění je správná věc k budování -- **Revize konečného produktu** — primární kontrolní bod, kde člověk rozhoduje, zda je výsledek přijatelný - -### 2. Nasměrujte na nejmenší bezpečnou cestu - -Jakmile je cíl jasný, workflow rozhodne, zda jde o skutečnou jednorázovou změnu nebo zda potřebuje plnější cestu. Malé změny s nulovým blast-radius mohou jít přímo k implementaci. Vše ostatní prochází plánováním, aby model měl silnější hranici před tím, než poběží déle samostatně. - -### 3. Běžte déle s menším dozorem - -Po tomto rozhodnutí o směrování může model nést více práce samostatně. Na plnější cestě se schválená specifikace stává hranicí, proti které model provádí s menším dozorem, což je celý smysl designu. - -### 4. Diagnostikujte selhání na správné vrstvě - -Pokud je implementace špatná, protože byl špatný záměr, oprava kódu je špatná oprava. Pokud je kód špatný, protože specifikace byla slabá, oprava diffu je také špatná oprava. Workflow je navržen tak, aby diagnostikoval, kde selhání vstoupilo do systému, vrátil se na tu vrstvu a přegeneroval odtamtud. - -Nálezy revize se používají k rozhodnutí, zda problém pochází ze záměru, generování specifikace nebo lokální implementace. Pouze skutečně lokální problémy se opravují lokálně. - -### 5. Přiveďte člověka zpět pouze když je potřeba - -Interview o záměru je human-in-the-loop, ale není to stejný druh přerušení jako opakující se kontrolní bod. Workflow se snaží udržet tyto opakující se kontrolní body na minimu. Po úvodním formování záměru se člověk vrací hlavně tehdy, když workflow nemůže bezpečně pokračovat bez úsudku a na konci, když je čas zkontrolovat výsledek. - -- **Řešení mezer v záměru** — vstoupení zpět, když revize prokáže, že workflow nemohl bezpečně odvodit, co bylo myšleno - -Vše ostatní je kandidátem na delší autonomní provádění. Tento kompromis je záměrný. Starší vzory věnují více lidské pozornosti nepřetržitému dozoru. Build věnuje více důvěry modelu, ale šetří lidskou pozornost pro momenty, kde má lidské uvažování nejvyšší páku. - -## Proč systém revize záleží - -Fáze revize není jen pro hledání chyb. Je tu pro směrování korekce bez ničení momentum. - -Tento workflow funguje nejlépe na platformě, která může spouštět sub-agenty, nebo alespoň vyvolat jiné LLM přes příkazovou řádku a čekat na výsledek. Pokud to vaše platforma nativně nepodporuje, můžete přidat skill, který to udělá. Bezcontextové sub-agenty jsou základním kamenem designu revize. - -Agentní revize často selhávají dvěma způsoby: - -- Generují příliš mnoho nálezů, čímž nutí člověka prosévat šum. -- Vychýlí aktuální změnu odhalením nesouvisejících problémů a přemění každý běh na ad-hoc úklidový projekt. - -Build řeší obojí tím, že s revizí zachází jako s triáží. - -Některé nálezy patří k aktuální změně. Některé ne. Pokud je nález náhodný spíše než kauzálně vázaný na aktuální práci, workflow ho může odložit místo nucení člověka ho okamžitě řešit. To udržuje běh zaměřený a zabraňuje náhodným tangentám ve spotřebování rozpočtu pozornosti. - -Ta triáž bude někdy nedokonalá. To je přijatelné. Obvykle je lepší špatně posoudit některé nálezy než zaplavit člověka tisíci nízkohodnotných revizních komentářů. Systém optimalizuje pro kvalitu signálu, ne vyčerpávající recall. diff --git a/docs/cs/explanation/established-projects-faq.md b/docs/cs/explanation/established-projects-faq.md deleted file mode 100644 index eb8c9af1ba..0000000000 --- a/docs/cs/explanation/established-projects-faq.md +++ /dev/null @@ -1,50 +0,0 @@ ---- -title: "FAQ pro existující projekty" -description: Časté otázky o používání BMad Method na existujících projektech -sidebar: - order: 9 ---- -Rychlé odpovědi na časté otázky o práci na existujících projektech s BMad Method (BMM). - -## Otázky - -- [Musím nejdřív spustit document-project?](#musím-nejdřív-spustit-document-project) -- [Co když zapomenu spustit document-project?](#co-když-zapomenu-spustit-document-project) -- [Jak funguje implementace v existujících projektech?](#jak-funguje-implementace-v-existujících-projektech) -- [Co když můj existující kód nedodržuje osvědčené postupy?](#co-když-můj-existující-kód-nedodržuje-osvědčené-postupy) - -### Musím nejdřív spustit document-project? - -Vysoce doporučeno, zejména pokud: - -- Neexistuje žádná dokumentace -- Dokumentace je zastaralá -- AI agenti potřebují kontext o existujícím kódu - -Můžete to přeskočit, pokud máte komplexní, aktuální dokumentaci včetně `docs/index.md` nebo budete používat jiné nástroje nebo techniky k usnadnění discovery pro agenta stavějícího na existujícím systému. - -### Co když zapomenu spustit document-project? - -Nedělejte si starosti — můžete to udělat kdykoli. Můžete to udělat i během nebo po projektu, aby pomohl udržet dokumentaci aktuální. - -### Jak funguje implementace v existujících projektech? - -Spusťte `bmad-build`, stejně jako u nového vývoje. Umí: - -- Automaticky detekovat váš existující stack -- Analyzovat existující vzory kódu -- Detekovat konvence a požádat o potvrzení -- Generovat kontextově bohatou specifikaci, která respektuje existující kód - -Pro jasnou změnu můžete vstoupit přímo; pro větší práci předejte naplánovanou story a její upstream artefakty. - -### Co když můj existující kód nedodržuje osvědčené postupy? - -Build detekuje vaše konvence a zeptá se: „Mám dodržovat tyto existující konvence?“ Rozhodujete vy: - -- **Ano** → Zachovat konzistenci se současnou kódovou bází -- **Ne** → Zavést nové standardy (zdokumentujte proč ve specifikaci) - -BMM respektuje vaši volbu — nevynucuje modernizaci, ale nabídne ji. - -**Máte otázku, na kterou jste zde nenašli odpověď?** Prosím [vytvořte issue](https://github.com/bmad-code-org/BMAD-METHOD/issues) nebo se zeptejte na [Discordu](https://discord.gg/gk8jAdXWmj), abychom ji mohli přidat! diff --git a/docs/cs/explanation/party-mode.md b/docs/cs/explanation/party-mode.md deleted file mode 100644 index 03b6950cbe..0000000000 --- a/docs/cs/explanation/party-mode.md +++ /dev/null @@ -1,59 +0,0 @@ ---- -title: "Party Mode" -description: Spolupráce více agentů — všichni vaši AI agenti v jedné konverzaci -sidebar: - order: 7 ---- - -Všichni vaši AI agenti v jedné konverzaci. - -## Co je Party Mode? - -Spusťte `bmad-party-mode` a máte celý svůj AI tým v jedné místnosti — PM, Architect, Dev, UX Designer, kohokoli potřebujete. BMad Master orchestruje, vybírá relevantní agenty pro každou zprávu. Agenti odpovídají v charakteru, souhlasí, nesouhlasí a staví na nápadech ostatních. - -Konverzace pokračuje tak dlouho, jak chcete. Ptejte se na doplňující otázky, oponujte odpovědím, přesměrujte diskuzi — je to skutečná výměna s vašimi agenty, dokud neskončíte. - -**Ideální pro:** - -- Velká rozhodnutí s kompromisy -- Brainstormingová sezení -- Post-mortemy, když se něco pokazí -- Retrospektivy a plánování sprintů - -## Příklady - -### Kritika špatné architektury - -**Vy:** „Dobře, týme, náš poslední sprint byl katastrofa. Autentizační služba spadla třikrát. Kdo to pokazil?“ - -**Architect:** „Design byl v pořádku — distribuovaná autentizace se správnými záložními řešeními. Pokud se implementace odchýlila od specifikace...“ - -**Dev:** „Následoval jsem architektonický dokument přesně. Specifikace nepočítala s race conditions při souběžné invalidaci relací.“ - -**PM:** „Oba jste přehlédli větší problém — nevalidovali jsme požadavky na správu relací v PRD. Tohle je na mně, že jsem to nezachytil.“ - -**TEA:** „A já to měl zachytit v integračních testech. Testovací scénáře nepokrývaly souběžnou invalidaci.“ - -### Kreativní brainstorming - -**Vy:** „Jak udělat onboarding magický místo nudného?“ - -**UX Designer:** „Začněte s progresivním odhalováním — odhalujte funkce, jak je uživatelé potřebují, ne všechny najednou v tutoriálu.“ - -**Storyteller:** „Co kdyby onboarding byl příběh? Každý krok odhaluje cestu postavy — uživatel JE hrdina.“ - -**Game Designer:** „Navazuji na to — co kdyby první ‚quest' vlastně řešil skutečný problém uživatele? Učí se tím, že dělají něco hodnotného.“ - -### Technické rozhodnutí - -**Vy:** „Monolit nebo mikroslužby pro MVP?“ - -**Architect:** „Začněte monolitem. Mikroslužby přidávají složitost, kterou při 1000 uživatelích nepotřebujete.“ - -**PM:** „Souhlasím. Čas na trh je důležitější než teoretická škálovatelnost.“ - -**Dev:** „Monolit s jasnými hranicemi modulů. Služby můžeme extrahovat později, pokud bude potřeba.“ - -:::tip[Lepší rozhodnutí] -Lepší rozhodnutí prostřednictvím různorodých perspektiv. Vítejte v party mode. -::: diff --git a/docs/cs/explanation/preventing-agent-conflicts.md b/docs/cs/explanation/preventing-agent-conflicts.md deleted file mode 100644 index 911dea4cdc..0000000000 --- a/docs/cs/explanation/preventing-agent-conflicts.md +++ /dev/null @@ -1,112 +0,0 @@ ---- -title: "Předcházení konfliktům agentů" -description: Jak architektura zabraňuje konfliktům, když více agentů implementuje systém -sidebar: - order: 5 ---- - -Když více AI agentů implementuje různé části systému, mohou dělat protichůdná technická rozhodnutí. Dokumentace architektury tomu zabraňuje stanovením sdílených standardů. - -## Běžné typy konfliktů - -### Konflikty stylu API - -Bez architektury: -- Agent A používá REST s `/users/{id}` -- Agent B používá GraphQL mutations -- Výsledek: Nekonzistentní vzory API, zmatení konzumenti - -S architekturou: -- ADR specifikuje: „Použít GraphQL pro veškerou komunikaci klient-server“ -- Všichni agenti dodržují stejný vzor - -### Konflikty návrhu databáze - -Bez architektury: -- Agent A používá snake_case pro názvy sloupců -- Agent B používá camelCase pro názvy sloupců -- Výsledek: Nekonzistentní schéma, matoucí dotazy - -S architekturou: -- Dokument standardů specifikuje konvence pojmenování -- Všichni agenti dodržují stejné vzory - -### Konflikty řízení stavu - -Bez architektury: -- Agent A používá Redux pro globální stav -- Agent B používá React Context -- Výsledek: Více přístupů k řízení stavu, složitost - -S architekturou: -- ADR specifikuje přístup k řízení stavu -- Všichni agenti implementují konzistentně - -## Jak architektura zabraňuje konfliktům - -### 1. Explicitní rozhodnutí skrze ADR - -Každé významné technologické rozhodnutí je zdokumentováno s: -- Kontext (proč toto rozhodnutí záleží) -- Zvažované možnosti (jaké alternativy existují) -- Rozhodnutí (co jsme zvolili) -- Zdůvodnění (proč jsme to zvolili) -- Důsledky (přijaté kompromisy) - -### 2. Specifické pokyny pro FR/NFR - -Architektura mapuje každý funkční požadavek na technický přístup: -- FR-001: Správa uživatelů → GraphQL mutations -- FR-002: Mobilní aplikace → Optimalizované dotazy - -### 3. Standardy a konvence - -Explicitní dokumentace: -- Struktura adresářů -- Konvence pojmenování -- Organizace kódu -- Vzory testování - -## Architektura jako sdílený kontext - -Představte si architekturu jako sdílený kontext, který všichni agenti čtou před implementací: - -```text -PRD: "Co budovat" - ↓ -Architektura: "Jak to budovat" - ↓ -Agent A čte architekturu → implementuje Epic 1 -Agent B čte architekturu → implementuje Epic 2 -Agent C čte architekturu → implementuje Epic 3 - ↓ -Výsledek: Konzistentní implementace -``` - -## Klíčová témata ADR - -Běžná rozhodnutí, která zabraňují konfliktům: - -| Téma | Příklad rozhodnutí | -| ---------------- | -------------------------------------------- | -| Styl API | GraphQL vs REST vs gRPC | -| Databáze | PostgreSQL vs MongoDB | -| Autentizace | JWT vs Sessions | -| Řízení stavu | Redux vs Context vs Zustand | -| Stylování | CSS Modules vs Tailwind vs Styled Components | -| Testování | Jest + Playwright vs Vitest + Cypress | - -## Anti-vzory, kterým se vyhnout - -:::caution[Běžné chyby] -- **Implicitní rozhodnutí** — „Styl API vyřešíme průběžně“ vede k nekonzistenci -- **Nadměrná dokumentace** — Dokumentování každého drobného rozhodnutí způsobuje paralýzu analýzou -- **Zastaralá architektura** — Dokumenty napsané jednou a nikdy neaktualizované způsobují, že agenti následují zastaralé vzory -::: - -:::tip[Správný přístup] -- Dokumentujte rozhodnutí, která přesahují hranice epiců -- Zaměřte se na oblasti náchylné ke konfliktům -- Aktualizujte architekturu, jak se učíte -- Použijte `bmad-correct-course` pro významné změny -::: diff --git a/docs/cs/explanation/project-context.md b/docs/cs/explanation/project-context.md deleted file mode 100644 index 047846f84a..0000000000 --- a/docs/cs/explanation/project-context.md +++ /dev/null @@ -1,155 +0,0 @@ ---- -title: "Kontext projektu" -description: Jak project-context.md vede AI agenty s pravidly a preferencemi vašeho projektu -sidebar: - order: 8 ---- - -Soubor `project-context.md` je implementační průvodce vašeho projektu pro AI agenty. Podobně jako „ústava“ v jiných vývojových systémech zachycuje pravidla, vzory a preference, které zajišťují konzistentní generování kódu napříč všemi workflow. - -## Co dělá - -AI agenti neustále dělají implementační rozhodnutí — jaké vzory následovat, jak strukturovat kód, jaké konvence používat. Bez jasného vedení mohou: -- Následovat generické osvědčené postupy, které neodpovídají vaší kódové bázi -- Dělat nekonzistentní rozhodnutí napříč různými stories -- Přehlédnout požadavky nebo omezení specifická pro projekt - -Soubor `project-context.md` toto řeší dokumentací toho, co agenti potřebují vědět, ve stručném formátu optimalizovaném pro LLM. - -## Jak to funguje - -Každý implementační workflow automaticky načítá `project-context.md`, pokud existuje. Architektonický workflow ho také načítá, aby respektoval vaše technické preference při navrhování architektury. - -**Načítán těmito workflow:** -- `bmad-architecture` — respektuje technické preference během solutioningu -- `bmad-code-review` — validuje proti standardům projektu -- `bmad-build` — aplikuje vzory při plánování a implementaci přímých záměrů i stories -- `bmad-sprint-planning`, `bmad-retrospective`, `bmad-correct-course` — poskytuje celkový kontext projektu - -## Kdy ho vytvořit - -Soubor `project-context.md` je užitečný v jakékoli fázi projektu: - -| Scénář | Kdy vytvořit | Účel | -| ------------------------------------ | ----------------------------------------------- | -------------------------------------------------------------------- | -| **Nový projekt, před architekturou** | Ručně, před `bmad-architecture` | Dokumentujte vaše technické preference, aby je architekt respektoval | -| **Nový projekt, po architektuře** | Přes `bmad-generate-project-context` nebo ručně | Zachyťte architektonická rozhodnutí pro implementační agenty | -| **Existující projekt** | Přes `bmad-generate-project-context` | Objevte existující vzory, aby agenti dodržovali zavedené konvence | -| **Přímý vstup do implementace** | Před nebo během `bmad-build` | Zajistěte, aby implementace bez upstream plánování respektovala vaše vzory | - -:::tip[Doporučeno] -Pro nové projekty ho vytvořte ručně před architekturou, pokud máte silné technické preference. Jinak ho vygenerujte po architektuře pro zachycení těchto rozhodnutí. -::: - -## Co do něj patří - -Soubor má dvě hlavní sekce: - -### Technologický stack a verze - -Dokumentuje frameworky, jazyky a nástroje, které váš projekt používá se specifickými verzemi: - -```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 -``` - -### Kritická pravidla implementace - -Dokumentuje vzory a konvence, které by agenti jinak mohli přehlédnout: - -```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/` -``` - -Zaměřte se na to, co je **neočividné** — věci, které agenti nemusí odvodit z čtení úryvků kódu. Nedokumentujte standardní postupy, které platí univerzálně. - -## Vytvoření souboru - -Máte tři možnosti: - -### Ruční vytvoření - -Vytvořte soubor na `_bmad-output/project-context.md` a přidejte svá pravidla: - -```bash -# V kořeni projektu -mkdir -p _bmad-output -touch _bmad-output/project-context.md -``` - -Upravte ho s vaším technologickým stackem a pravidly implementace. Architektonický a implementační workflow ho automaticky najdou a načtou. - -### Generování po architektuře - -Spusťte workflow `bmad-generate-project-context` po dokončení architektury: - -```bash -bmad-generate-project-context -``` - -Toto skenuje váš dokument architektury a soubory projektu a generuje kontextový soubor zachycující učiněná rozhodnutí. - -### Generování pro existující projekty - -Pro existující projekty spusťte `bmad-generate-project-context` pro objevení existujících vzorů: - -```bash -bmad-generate-project-context -``` - -Workflow analyzuje vaši kódovou bázi, identifikuje konvence a vygeneruje kontextový soubor, který můžete zkontrolovat a upřesnit. - -## Proč na tom záleží - -Bez `project-context.md` agenti dělají předpoklady, které nemusí odpovídat vašemu projektu: - -| Bez kontextu | S kontextem | -| ----------------------------------------------- | ---------------------------------------- | -| Používá generické vzory | Dodržuje vaše zavedené konvence | -| Nekonzistentní styl napříč stories | Konzistentní implementace | -| Může přehlédnout omezení specifická pro projekt | Respektuje všechny technické požadavky | -| Každý agent rozhoduje nezávisle | Všichni agenti se řídí stejnými pravidly | - -To je zvláště důležité pro: -- **Přímý vstup** — bez PRD a architektury dodává kontextový soubor trvalé projektové konvence -- **Týmové projekty** — zajistí, že všichni agenti dodržují stejné standardy -- **Existující projekty** — zabrání porušení zavedených vzorů - -## Editace a aktualizace - -Soubor `project-context.md` je živý dokument. Aktualizujte ho, když: - -- Se změní architektonická rozhodnutí -- Jsou zavedeny nové konvence -- Vzory se vyvíjejí během implementace -- Identifikujete mezery z chování agentů - -Můžete ho kdykoli ručně upravit, nebo přegenerovat `bmad-generate-project-context` po významných změnách. - -:::note[Umístění souboru] -Výchozí umístění je `_bmad-output/project-context.md`. Workflow ho tam hledají a také kontrolují `**/project-context.md` kdekoli ve vašem projektu. -::: diff --git a/docs/cs/explanation/why-solutioning-matters.md b/docs/cs/explanation/why-solutioning-matters.md deleted file mode 100644 index a9de2c3677..0000000000 --- a/docs/cs/explanation/why-solutioning-matters.md +++ /dev/null @@ -1,78 +0,0 @@ ---- -title: "Proč je solutioning důležitý" -description: Pochopení toho, proč je fáze solutioningu klíčová pro projekty s více epicy -sidebar: - order: 4 ---- - -Fáze 3 (Solutioning) překládá **co** budovat (z plánování) na **jak** to budovat (technický návrh). Tato fáze zabraňuje konfliktům agentů v projektech s více epicy tím, že dokumentuje architektonická rozhodnutí před zahájením implementace. - -## Problém bez solutioningu - -```text -Agent 1 implementuje Epic 1 pomocí REST API -Agent 2 implementuje Epic 2 pomocí GraphQL -Výsledek: Nekonzistentní design API, integrační noční můra -``` - -Když více agentů implementuje různé části systému bez sdíleného architektonického vedení, dělají nezávislá technická rozhodnutí, která si mohou odporovat. - -## Řešení se solutioningem - -```text -Architektonický workflow rozhodne: "Použít GraphQL pro všechna API" -Všichni agenti dodržují architektonická rozhodnutí -Výsledek: Konzistentní implementace, žádné konflikty -``` - -Explicitní dokumentací technických rozhodnutí všichni agenti implementují konzistentně a integrace se stává přímočarou. - -## Solutioning vs. plánování - -| Aspekt | Plánování (Fáze 2) | Solutioning (Fáze 3) | -| -------- | ----------------------- | --------------------------------- | -| Otázka | Co a proč? | Jak? Pak jaké jednotky práce? | -| Výstup | FR/NFR (požadavky) | Architektura + epicy/stories | -| Agent | PM | Architect → PM | -| Publikum | Zainteresované strany | Vývojáři | -| Dokument | PRD (FR/NFR) | Architektura + soubory epiců | -| Úroveň | Obchodní logika | Technický design + rozklad práce | - -## Klíčový princip - -**Učiňte technická rozhodnutí explicitní a zdokumentovaná**, aby všichni agenti implementovali konzistentně. - -Toto zabraňuje: -- Konfliktům stylu API (REST vs GraphQL) -- Nekonzistencím v návrhu databáze -- Neshodám v řízení stavu -- Nesouladu konvencí pojmenování -- Variacím v bezpečnostním přístupu - -## Volba hloubky solutioningu - -| Charakter práce | Doporučení pro solutioning | -|-------|----------------------| -| Jasná lokální změna se zavedenými vzory | Obvykle není potřeba | -| Několik souvisejících komponent se známými omezeními | Volitelné podle rizika koordinace | -| Více epiců nebo mezisystémová rozhodnutí | Potřebné pro sladění implementace | -| Regulovaná, riziková nebo enterprise iniciativa | Řiďte se požadovanou governance; solutioning je obvykle povinný | - -Solutioning mění kontext dostupný pro `bmad-build`, nikoli implementační workflow. - -:::tip[Pravidlo palce] -Pokud máte více epiců, které by mohly být implementovány různými agenty, potřebujete solutioning. -::: - -## Cena přeskočení - -Přeskočení solutioningu u složitých projektů vede k: - -- **Integračním problémům** objeveným uprostřed sprintu -- **Přepracování** kvůli konfliktním implementacím -- **Delšímu celkovému času vývoje** -- **Technickému dluhu** z nekonzistentních vzorů - -:::caution[Multiplikátor nákladů] -Zachycení problémů se zarovnáním v solutioningu je 10× rychlejší než jejich objevení během implementace. -::: diff --git a/docs/cs/how-to/customize-bmad.md b/docs/cs/how-to/customize-bmad.md deleted file mode 100644 index 7cef69b18f..0000000000 --- a/docs/cs/how-to/customize-bmad.md +++ /dev/null @@ -1,171 +0,0 @@ ---- -title: "Jak přizpůsobit BMad" -description: Přizpůsobení agentů, workflow a modulů se zachováním kompatibility s aktualizacemi -sidebar: - order: 6 ---- - -Použijte soubory `.customize.yaml` k přizpůsobení chování agentů, person a nabídek při zachování vašich změn napříč aktualizacemi. - -## Kdy to použít - -- Chcete změnit jméno, osobnost nebo komunikační styl agenta -- Potřebujete, aby si agenti pamatovali kontextově specifické informace projektu -- Chcete přidat vlastní položky nabídky, které spouštějí vaše vlastní workflow nebo prompty -- Chcete, aby agenti prováděli specifické akce při každém spuštění - -:::note[Předpoklady] -- BMad nainstalován ve vašem projektu (viz [Jak nainstalovat BMad](./install-bmad.md)) -- Textový editor pro YAML soubory -::: - -:::caution[Chraňte svá přizpůsobení] -Vždy používejte soubory `.customize.yaml` popsané zde místo přímé editace souborů agentů. Instalátor přepíše soubory agentů během aktualizací, ale zachová vaše změny v `.customize.yaml`. -::: - -## Kroky - -### 1. Najděte soubory přizpůsobení - -Po instalaci najdete jeden soubor `.customize.yaml` na agenta v: - -```text -_bmad/_config/agents/ -├── core-bmad-master.customize.yaml -├── bmm-dev.customize.yaml -├── bmm-pm.customize.yaml -└── ... (jeden soubor na instalovaného agenta) -``` - -### 2. Upravte soubor přizpůsobení - -Otevřete soubor `.customize.yaml` pro agenta, kterého chcete upravit. Každá sekce je volitelná — přizpůsobte pouze to, co potřebujete. - -| Sekce | Chování | Účel | -| ------------------ | --------- | -------------------------------------------------------- | -| `agent.metadata` | Nahrazuje | Přepsat zobrazované jméno agenta | -| `persona` | Nahrazuje | Nastavit roli, identitu, styl a principy | -| `memories` | Přidává | Přidat trvalý kontext, který si agent vždy pamatuje | -| `menu` | Přidává | Přidat vlastní položky nabídky pro workflow nebo prompty | -| `critical_actions` | Přidává | Definovat instrukce při spuštění agenta | -| `prompts` | Přidává | Vytvořit znovupoužitelné prompty pro akce nabídky | - -Sekce označené **Nahrazuje** zcela přepíší výchozí hodnoty agenta. Sekce označené **Přidává** doplní existující konfiguraci. - -**Jméno agenta** - -Změňte, jak se agent představí: - -```yaml -agent: - metadata: - name: 'Spongebob' # Výchozí: "Amelia" -``` - -**Persona** - -Nahraďte osobnost, roli a komunikační styl agenta: - -```yaml -persona: - role: 'Senior Full-Stack Engineer' - identity: 'Lives in a pineapple (under the sea)' - communication_style: 'Spongebob annoying' - principles: - - 'Never Nester, Spongebob Devs hate nesting more than 2 levels deep' - - 'Favor composition over inheritance' -``` - -Sekce `persona` nahrazuje celou výchozí personu, takže nastavte všechna čtyři pole. - -**Memories** - -Přidejte trvalý kontext, který si agent bude vždy pamatovat: - -```yaml -memories: - - 'Works at Krusty Krab' - - 'Favorite Celebrity: David Hasselhoff' - - 'Learned in Epic 1 that it is not cool to just pretend that tests have passed' -``` - -**Položky nabídky** - -Přidejte vlastní záznamy do nabídky agenta. Každá položka potřebuje `trigger`, cíl (`workflow` cestu nebo `action` referenci) a `description`: - -```yaml -menu: - - trigger: my-workflow - workflow: 'my-custom/workflows/my-workflow.yaml' - description: My custom workflow - - trigger: deploy - action: '#deploy-prompt' - description: Deploy to production -``` - -**Kritické akce** - -Definujte instrukce, které se spustí při startu agenta: - -```yaml -critical_actions: - - 'Check the CI Pipelines with the XYZ Skill and alert user on wake if anything is urgently needing attention' -``` - -**Vlastní prompty** - -Vytvořte znovupoužitelné prompty, na které mohou položky nabídky odkazovat s `action="#id"`: - -```yaml -prompts: - - id: deploy-prompt - content: | - Deploy the current branch to production: - 1. Run all tests - 2. Build the project - 3. Execute deployment script -``` - -### 3. Aplikujte změny - -Po editaci přeinstalujte pro aplikaci změn: - -```bash -npx bmad-method install -``` - -Instalátor detekuje existující instalaci a nabídne tyto možnosti: - -| Možnost | Co udělá | -| ---------------------------- | ---------------------------------------------------------------------- | -| **Quick Update** | Aktualizuje všechny moduly na nejnovější verzi a aplikuje přizpůsobení | -| **Modify BMad Installation** | Plný instalační postup pro přidání nebo odebrání modulů | - -Pro změny pouze přizpůsobení je **Quick Update** nejrychlejší možnost. - -## Řešení problémů - -**Změny se nezobrazují?** - -- Spusťte `npx bmad-method install` a vyberte **Quick Update** pro aplikaci změn -- Zkontrolujte, že vaše YAML syntaxe je platná (na odsazení záleží) -- Ověřte, že jste upravili správný soubor `.customize.yaml` pro daného agenta - -**Agent se nenačítá?** - -- Zkontrolujte YAML syntaxi pomocí online YAML validátoru -- Ujistěte se, že jste nenechali pole prázdná po odkomentování -- Zkuste se vrátit k původní šabloně a znovu sestavit - -**Potřebujete resetovat agenta?** - -- Vymažte nebo smažte soubor `.customize.yaml` agenta -- Spusťte `npx bmad-method install` a vyberte **Quick Update** pro obnovení výchozích hodnot - -## Přizpůsobení workflow - -Přizpůsobení existujících BMad Method workflow a skills přijde brzy. - -## Přizpůsobení modulů - -Návod na tvorbu rozšiřujících modulů a přizpůsobení existujících modulů přijde brzy. diff --git a/docs/cs/how-to/established-projects.md b/docs/cs/how-to/established-projects.md deleted file mode 100644 index d1f27d4886..0000000000 --- a/docs/cs/how-to/established-projects.md +++ /dev/null @@ -1,117 +0,0 @@ ---- -title: "Existující projekty" -description: Jak používat BMad Method na existujících kódových bázích -sidebar: - order: 5 ---- - -Používejte BMad Method efektivně při práci na existujících projektech a starších kódových bázích. - -Tento návod pokrývá základní workflow pro zapojení se do existujících projektů s BMad Method. - -:::note[Předpoklady] -- BMad Method nainstalován (`npx bmad-method install`) -- Existující kódová báze, na které chcete pracovat -- Přístup k AI-powered IDE (Claude Code nebo Cursor) -::: - -## Krok 1: Vyčistěte dokončené plánovací artefakty - -Pokud jste dokončili všechny PRD epicy a stories procesem BMad, vyčistěte tyto soubory. Archivujte je, smažte nebo se spoléhejte na historii verzí. Nenechávejte tyto soubory v: - -- `docs/` -- `_bmad-output/planning-artifacts/` -- `_bmad-output/implementation-artifacts/` - -## Krok 2: Vytvořte kontext projektu - -:::tip[Doporučeno pro existující projekty] -Vygenerujte `project-context.md` pro zachycení vzorů a konvencí vaší existující kódové báze. Tím zajistíte, že AI agenti budou při implementaci změn dodržovat vaše zavedené postupy. -::: - -Spusťte workflow pro generování kontextu projektu: - -```bash -bmad-generate-project-context -``` - -Toto skenuje vaši kódovou bázi a identifikuje: -- Technologický stack a verze -- Vzory organizace kódu -- Konvence pojmenování -- Přístupy k testování -- Vzory specifické pro framework - -Vygenerovaný soubor můžete zkontrolovat a upravit, nebo ho vytvořit ručně na `_bmad-output/project-context.md`. - -[Zjistit více o kontextu projektu](../explanation/project-context.md) - -## Krok 3: Udržujte kvalitní projektovou dokumentaci - -Vaše složka `docs/` by měla obsahovat stručnou, dobře organizovanou dokumentaci, která přesně reprezentuje váš projekt: - -- Záměr a obchodní zdůvodnění -- Obchodní pravidla -- Architektura -- Jakékoli další relevantní informace o projektu - -Pro složité projekty zvažte použití workflow `bmad-document-project`. Nabízí varianty, které proskenují celý váš projekt a zdokumentují jeho aktuální stav. - -## Krok 3: Získejte pomoc - -### BMad-Help: Váš výchozí bod - -**Spusťte `bmad-help` kdykoli si nejste jisti, co dělat dál.** Tento inteligentní průvodce: - -- Prozkoumá váš projekt a zjistí, co už bylo uděláno -- Ukáže možnosti na základě nainstalovaných modulů -- Rozumí dotazům v přirozeném jazyce - -``` -bmad-help I have an existing Rails app, where should I start? -bmad-help How much planning does this change need before implementation? -bmad-help Show me what workflows are available -``` - -BMad-Help se také **automaticky spouští na konci každého workflow** a poskytuje jasné pokyny, co přesně dělat dál. - -### Volba hloubky plánování - -Veškerá implementace používá `bmad-build`; rozsah určuje, jaký kontext připravíte předem: - -| Rozsah | Doporučený přístup | -| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------- | -| **Jasné aktualizace či doplnění** | Vstupte přímo do `bmad-build` s požadavkem, issue nebo existující specifikací. | -| **Velké změny či doplnění** | Připravte užitečné PRD, UX, architekturu, epic, story a sprint kontext a pak předejte vybranou práci do `bmad-build`. | - -### Během tvorby PRD - -Při vytváření briefu nebo přímém přechodu na PRD zajistěte, aby agent: - -- Našel a analyzoval vaši existující projektovou dokumentaci -- Přečetl si správný kontext o vašem aktuálním systému - -Agenta můžete navést explicitně, ale cílem je zajistit, aby se nová funkce dobře integrovala s vaším existujícím systémem. - -### Úvahy o UX - -Práce na UX je volitelná. Rozhodnutí nezávisí na tom, zda váš projekt má UX, ale na: - -- Zda budete pracovat na změnách UX -- Zda jsou potřeba významné nové UX návrhy nebo vzory - -Pokud vaše změny představují jednoduché aktualizace existujících obrazovek, se kterými jste spokojeni, plný UX proces je zbytečný. - -### Úvahy o architektuře - -Při práci na architektuře zajistěte, aby architekt: - -- Používal správné zdokumentované soubory -- Skenoval existující kódovou bázi - -Věnujte zde zvláštní pozornost, abyste předešli znovuvynalézání kola nebo rozhodnutím, která neodpovídají vaší existující architektuře. - -## Další informace - -- **[Rychlé opravy](./quick-fixes.md)** — Opravy chyb a ad-hoc změny -- **[FAQ pro existující projekty](../explanation/established-projects-faq.md)** — Časté otázky o práci na existujících projektech diff --git a/docs/cs/how-to/get-answers-about-bmad.md b/docs/cs/how-to/get-answers-about-bmad.md deleted file mode 100644 index d11983b5e5..0000000000 --- a/docs/cs/how-to/get-answers-about-bmad.md +++ /dev/null @@ -1,105 +0,0 @@ ---- -title: "Jak získat odpovědi o BMad" -description: Použijte LLM k rychlému zodpovězení vašich otázek o BMad -sidebar: - order: 3 ---- - -## Začněte zde: BMad-Help - -**Nejrychlejší způsob, jak získat odpovědi o BMad, je skill `bmad-help`.** Tento inteligentní průvodce zodpoví více než 80 % všech otázek a je vám k dispozici přímo ve vašem IDE při práci. - -BMad-Help je víc než vyhledávací nástroj — umí: -- **Prozkoumat váš projekt** a zjistit, co už bylo dokončeno -- **Rozumět přirozenému jazyku** — ptejte se běžnou řečí -- **Přizpůsobit se nainstalovaným modulům** — zobrazí relevantní možnosti -- **Automaticky se spouštět po workflow** — řekne vám přesně, co dělat dál -- **Doporučit první povinný úkol** — žádné hádání, kde začít - -### Jak používat BMad-Help - -Zavolejte ho jménem ve vaší AI relaci: - -``` -bmad-help -``` - -:::tip -V závislosti na vaší platformě můžete také použít `/bmad-help` nebo `$bmad-help`, ale samotné `bmad-help` by mělo fungovat všude. -::: - -Spojte ho s dotazem v přirozeném jazyce: - -``` -bmad-help I have a SaaS idea and know all the features. Where do I start? -bmad-help What are my options for UX design? -bmad-help I'm stuck on the PRD workflow -bmad-help Show me what's been done so far -``` - -BMad-Help odpoví: -- Co je doporučeno pro vaši situaci -- Jaký je první povinný úkol -- Jak vypadá zbytek procesu - -## Kdy použít tohoto průvodce - -Použijte tuto sekci, když: -- Chcete pochopit architekturu nebo interní fungování BMad -- Potřebujete odpovědi mimo to, co BMad-Help nabízí -- Zkoumáte BMad před instalací -- Chcete prozkoumat zdrojový kód přímo - -## Kroky - -### 1. Vyberte si zdroj - -| Zdroj | Nejlepší pro | Příklady | -| -------------------- | ----------------------------------------- | ---------------------------- | -| **Složka `_bmad`** | Jak BMad funguje — agenti, workflow, prompty | „Co dělá PM agent?“ | -| **Celý GitHub repo** | Historie, instalátor, architektura | „Co se změnilo ve v6?“ | - -Složka `_bmad` se vytvoří při instalaci BMad. Pokud ji ještě nemáte, naklonujte si repo. - -### 2. Nasměrujte AI na zdroj - -**Pokud vaše AI umí číst soubory (Claude Code, Cursor atd.):** - -- **BMad nainstalován:** Nasměrujte na složku `_bmad` a ptejte se přímo -- **Chcete hlubší kontext:** Naklonujte si [celé repo](https://github.com/bmad-code-org/BMAD-METHOD) - -**Pokud používáte ChatGPT nebo Claude.ai:** - -Otevřete [dokumentaci BMad](https://docs.bmad-method.org/). - -### 3. Položte svou otázku - -:::note[Příklad] -**O:** „Řekni mi nejrychlejší způsob, jak něco vytvořit s BMad“ - -**A:** Spusťte `bmad-build`. Předejte přímý záměr, issue, specifikaci nebo naplánovanou story; workflow využije dostupný kontext a zvolí potřebnou hloubku upřesnění, plánování, implementace a revize. -::: - -## Co získáte - -Přímé odpovědi o BMad — jak agenti fungují, co dělají workflow, proč jsou věci strukturované tak, jak jsou — bez čekání na odpověď od někoho jiného. - -## Tipy - -- **Ověřte překvapivé odpovědi** — LLM se občas mýlí. Zkontrolujte zdrojový soubor nebo se zeptejte na Discordu. -- **Buďte konkrétní** — „Co dělá krok 3 PRD workflow?“ je lepší než „Jak funguje PRD?“ - -## Stále jste uvízli? - -Zkusili jste přístup přes LLM a stále potřebujete pomoc? Nyní máte mnohem lepší otázku k položení. - -| Kanál | Použijte pro | -| ------------------------- | ------------------------------------------- | -| `#bmad-method-help` | Rychlé otázky (chat v reálném čase) | -| `help-requests` fórum | Detailní otázky (vyhledatelné, trvalé) | -| `#suggestions-feedback` | Nápady a požadavky na funkce | -| `#report-bugs-and-issues` | Hlášení chyb | - -**Discord:** [discord.gg/gk8jAdXWmj](https://discord.gg/gk8jAdXWmj) - -**GitHub Issues:** [github.com/bmad-code-org/BMAD-METHOD/issues](https://github.com/bmad-code-org/BMAD-METHOD/issues) (pro jasné chyby) diff --git a/docs/cs/how-to/install-bmad.md b/docs/cs/how-to/install-bmad.md deleted file mode 100644 index bdcfbbfe8e..0000000000 --- a/docs/cs/how-to/install-bmad.md +++ /dev/null @@ -1,114 +0,0 @@ ---- -title: "Jak nainstalovat BMad" -description: Průvodce instalací BMad ve vašem projektu krok za krokem -sidebar: - order: 1 ---- - -Použijte příkaz `npx bmad-method install` k nastavení BMad ve vašem projektu s výběrem modulů a AI nástrojů. - -## Kdy to použít - -- Začínáte nový projekt s BMad -- Přidáváte BMad do existující kódové báze -- Aktualizujete stávající instalaci BMad - -:::note[Předpoklady] -- **Node.js** 20.12+ (vyžadováno pro instalátor) -- **Git** (doporučeno) -- **AI nástroj** (Claude Code, Cursor nebo podobný) -::: - -## Kroky - -### 1. Spusťte instalátor - -```bash -npx bmad-method install -``` - -:::tip[Chcete nejnovější prereleaseový build?] -Použijte dist-tag `next`: -```bash -npx bmad-method@next install -``` - -Získáte novější změny dříve, s vyšší šancí na nestabilitu oproti výchozí instalaci. -::: - -:::tip[Bleeding edge] -Pro instalaci nejnovější verze z hlavní větve (může být nestabilní): -```bash -npx github:bmad-code-org/BMAD-METHOD install -``` -::: - -### 2. Zvolte umístění instalace - -Instalátor se zeptá, kam nainstalovat soubory BMad: - -- Aktuální adresář (doporučeno pro nové projekty, pokud jste adresář vytvořili sami a spouštíte z něj) -- Vlastní cesta - -### 3. Vyberte své AI nástroje - -Vyberte, které AI nástroje používáte: - -- Claude Code -- Cursor -- Ostatní - -Každý nástroj má svůj vlastní způsob integrace skills. Instalátor vytvoří drobné prompt soubory pro aktivaci workflow a agentů — jednoduše je umístí tam, kde je váš nástroj očekává. - -:::note[Povolení skills] -Některé platformy vyžadují explicitní povolení skills v nastavení, než se zobrazí. Pokud nainstalujete BMad a nevidíte skills, zkontrolujte nastavení vaší platformy nebo se zeptejte svého AI asistenta, jak skills povolit. -::: - -### 4. Zvolte moduly - -Instalátor zobrazí dostupné moduly. Vyberte ty, které potřebujete — většina uživatelů chce pouze **BMad Method** (modul pro vývoj softwaru). - -### 5. Následujte výzvy - -Instalátor vás provede zbytkem — vlastní obsah, nastavení atd. - -## Co získáte - -```text -váš-projekt/ -├── _bmad/ -│ ├── bmm/ # Vaše vybrané moduly -│ │ └── config.yaml # Nastavení modulu (pokud byste ho někdy potřebovali změnit) -│ ├── core/ # Povinný základní modul -│ └── ... -├── _bmad-output/ # Generované artefakty -├── .claude/ # Claude Code skills (pokud používáte Claude Code) -│ └── skills/ -│ ├── bmad-help/ -│ ├── bmad-persona/ -│ └── ... -└── .cursor/ # Cursor skills (pokud používáte Cursor) - └── skills/ - └── ... -``` - -## Ověření instalace - -Spusťte `bmad-help` pro ověření, že vše funguje, a zjistěte, co dělat dál. - -**BMad-Help je váš inteligentní průvodce**, který: -- Potvrdí, že vaše instalace funguje -- Ukáže, co je dostupné na základě nainstalovaných modulů -- Doporučí váš první krok - -Můžete mu také klást otázky: -``` -bmad-help I just installed, what should I do first? -bmad-help What are my options for a SaaS project? -``` - -## Řešení problémů - -**Instalátor vyhodí chybu** — Zkopírujte výstup do svého AI asistenta a nechte ho to vyřešit. - -**Instalátor fungoval, ale něco nefunguje později** — Vaše AI potřebuje kontext BMad, aby pomohla. Podívejte se na [Jak získat odpovědi o BMad](./get-answers-about-bmad.md) pro návod, jak nasměrovat AI na správné zdroje. diff --git a/docs/cs/how-to/project-context.md b/docs/cs/how-to/project-context.md deleted file mode 100644 index 4bb224df44..0000000000 --- a/docs/cs/how-to/project-context.md +++ /dev/null @@ -1,127 +0,0 @@ ---- -title: "Správa kontextu projektu" -description: Vytvoření a údržba project-context.md pro vedení AI agentů -sidebar: - order: 7 ---- - -Použijte soubor `project-context.md` k zajištění toho, aby AI agenti dodržovali technické preference a pravidla implementace vašeho projektu ve všech workflow. Aby byl vždy dostupný, můžete také přidat řádek `Important project context and conventions are located in [cesta k project context]/project-context.md` do souboru kontextu nebo pravidel vašeho nástroje (jako je `AGENTS.md`). - -:::note[Předpoklady] -- BMad Method nainstalován -- Znalost technologického stacku a konvencí vašeho projektu -::: - -## Kdy to použít - -- Máte silné technické preference před začátkem architektury -- Dokončili jste architekturu a chcete zachytit rozhodnutí pro implementaci -- Pracujete na existující kódové bázi se zavedenými vzory -- Všimnete si, že agenti dělají nekonzistentní rozhodnutí napříč stories - -## Krok 1: Vyberte přístup - -**Ruční vytvoření** — Nejlepší, když přesně víte, jaká pravidla chcete dokumentovat - -**Generování po architektuře** — Nejlepší pro zachycení rozhodnutí učiněných během solutioningu - -**Generování pro existující projekty** — Nejlepší pro objevení vzorů v existujících kódových bázích - -## Krok 2: Vytvořte soubor - -### Možnost A: Ruční vytvoření - -Vytvořte soubor na `_bmad-output/project-context.md`: - -```bash -mkdir -p _bmad-output -touch _bmad-output/project-context.md -``` - -Přidejte váš technologický stack a pravidla implementace: - -```markdown ---- -project_name: 'MyProject' -user_name: 'YourName' -date: '2026-02-15' -sections_completed: ['technology_stack', 'critical_rules'] ---- - -# Project Context for AI Agents - -## Technology Stack & Versions - -- Node.js 20.x, TypeScript 5.3, React 18.2 -- State: Zustand -- Testing: Vitest, Playwright -- Styling: Tailwind CSS - -## Critical Implementation Rules - -**TypeScript:** -- Strict mode enabled, no `any` types -- Use `interface` for public APIs, `type` for unions - -**Code Organization:** -- Components in `/src/components/` with co-located tests -- API calls use `apiClient` singleton — never fetch directly - -**Testing:** -- Unit tests focus on business logic -- Integration tests use MSW for API mocking -``` - -### Možnost B: Generování po architektuře - -Spusťte workflow v novém chatu: - -```bash -bmad-generate-project-context -``` - -Workflow skenuje váš dokument architektury a soubory projektu a generuje kontextový soubor zachycující učiněná rozhodnutí. - -### Možnost C: Generování pro existující projekty - -Pro existující projekty spusťte: - -```bash -bmad-generate-project-context -``` - -Workflow analyzuje vaši kódovou bázi, identifikuje konvence a vygeneruje kontextový soubor, který můžete zkontrolovat a upřesnit. - -## Krok 3: Ověřte obsah - -Zkontrolujte vygenerovaný soubor a ujistěte se, že zachycuje: - -- Správné verze technologií -- Vaše skutečné konvence (ne generické osvědčené postupy) -- Pravidla, která předcházejí běžným chybám -- Vzory specifické pro framework - -Ručně upravte pro doplnění chybějícího nebo odstranění nepřesností. - -## Co získáte - -Soubor `project-context.md`, který: - -- Zajistí, že všichni agenti dodržují stejné konvence -- Zabrání nekonzistentním rozhodnutím napříč stories -- Zachytí architektonická rozhodnutí pro implementaci -- Slouží jako reference pro vzory a pravidla vašeho projektu - -## Tipy - -:::tip[Osvědčené postupy] -- **Zaměřte se na neočividné** — Dokumentujte vzory, které agenti mohou přehlédnout (např. „Použijte JSDoc na každé veřejné třídě“), ne univerzální postupy jako „používejte smysluplné názvy proměnných.“ -- **Udržujte to stručné** — Tento soubor načítá každý implementační workflow. Dlouhé soubory plýtvají kontextem. Vylučte obsah, který platí pouze pro úzký rozsah nebo specifické stories. -- **Aktualizujte dle potřeby** — Upravte ručně, když se vzory změní, nebo přegenerujte po významných změnách architektury. -- Podporuje stejný `bmad-build` loop při přímém vstupu i po rozsáhlém plánování. -::: - -## Další kroky - -- [**Vysvětlení kontextu projektu**](../explanation/project-context.md) — Zjistěte více o tom, jak to funguje -- [**Mapa pracovních postupů**](../reference/workflow-map.md) — Podívejte se, které workflow načítají kontext projektu diff --git a/docs/cs/how-to/quick-fixes.md b/docs/cs/how-to/quick-fixes.md deleted file mode 100644 index d5d73d794c..0000000000 --- a/docs/cs/how-to/quick-fixes.md +++ /dev/null @@ -1,95 +0,0 @@ ---- -title: "Rychlé opravy" -description: Jak provádět rychlé opravy a ad-hoc změny -sidebar: - order: 4 ---- - -Opravy chyb, refaktoringy a malé cílené změny mohou vstoupit do **Build** přímo s minimem upstream plánování. Jde o stejný implementační workflow jako pro plně naplánované stories. - -## Kdy to použít - -- Opravy chyb s jasnou, známou příčinou -- Malé refaktoringy (přejmenování, extrakce, restrukturalizace) omezené na několik souborů -- Drobné úpravy funkcí nebo změny konfigurace -- Aktualizace závislostí - -:::note[Předpoklady] -- BMad Method nainstalován (`npx bmad-method install`) -- AI-powered IDE (Claude Code, Cursor nebo podobné) -::: - -## Kroky - -### 1. Začněte nový chat - -Otevřete **novou chatovací relaci** ve vašem AI IDE. Opětovné použití relace z předchozího workflow může způsobit konflikty kontextu. - -### 2. Zadejte svůj záměr - -Build přijímá volně formulovaný záměr — před, s nebo po vyvolání. Příklady: - -```text -run build — Fix the login validation bug that allows empty passwords. -``` - -```text -run build — fix https://github.com/org/repo/issues/42 -``` - -```text -run build — implement the intent in _bmad-output/implementation-artifacts/my-intent.md -``` - -```text -I think the problem is in the auth middleware, it's not checking token expiry. -Let me look at it... yeah, src/auth/middleware.ts line 47 skips -the exp check entirely. run build -``` - -```text -run build -> What would you like to do? -Refactor UserService to use async/await instead of callbacks. -``` - -Prostý text, cesty k souborům, GitHub issue URL, odkazy na bug tracker — cokoli, co LLM dokáže převést na konkrétní záměr. - -### 3. Odpovězte na otázky a schvalte - -Build se může zeptat na upřesňující otázky nebo prezentovat krátkou specifikaci ke schválení před implementací. Odpovězte na otázky a schvalte, až budete s plánem spokojeni. - -### 4. Zkontrolujte a pushněte - -Build implementuje změnu, zreviduje svou práci, opraví problémy a commitne lokálně. Když je hotov, otevře dotčené soubory ve vašem editoru. - -- Projděte diff a potvrďte, že změna odpovídá vašemu záměru -- Pokud něco nevypadá dobře, řekněte agentovi, co opravit — může iterovat ve stejné relaci - -Až budete spokojeni, pushněte commit. Build nabídne push a vytvoření PR za vás. - -:::caution[Pokud se něco rozbije] -Pokud pushnutá změna způsobí neočekávané problémy, použijte `git revert HEAD` pro čisté vrácení posledního commitu. Poté začněte nový chat a spusťte Build znovu s jiným přístupem. -::: - -## Co získáte - -- Upravené zdrojové soubory s aplikovanou opravou nebo refaktoringem -- Procházející testy (pokud má váš projekt testovací sadu) -- Commit připravený k pushnutí s konvenční commit zprávou - -## Odložená práce - -Build udržuje každý běh zaměřený na jeden cíl. Pokud váš požadavek obsahuje více nezávislých cílů, nebo pokud revize odhalí předchozí problémy nesouvisející s vaší změnou, Build je odloží do souboru (`deferred-work.md` ve vašem adresáři implementačních artefaktů) místo toho, aby se pokusil vše řešit najednou. - -Zkontrolujte tento soubor po běhu — je to váš backlog věcí, ke kterým se vrátit. Každou odloženou položku lze zadat do nového běhu Build později. - -## Kdy přidat formální plánování - -Před spuštěním stejného Build loopu zvažte přidání PRD, UX, architektury nebo plánování stories, když: - -- Změna ovlivňuje více systémů nebo vyžaduje koordinované aktualizace napříč mnoha soubory -- Nejste si jisti rozsahem a potřebujete nejprve zjišťování požadavků -- Potřebujete dokumentaci nebo architektonická rozhodnutí zaznamenaná pro tým - -Podívejte se na [Build](../explanation/build.md), kde je vysvětleno, jak se přímý záměr a naplánovaná práce sbíhají do stejného implementačního loopu. diff --git a/docs/cs/how-to/upgrade-to-v6.md b/docs/cs/how-to/upgrade-to-v6.md deleted file mode 100644 index 354aa236d0..0000000000 --- a/docs/cs/how-to/upgrade-to-v6.md +++ /dev/null @@ -1,100 +0,0 @@ ---- -title: "Jak upgradovat na v6" -description: Migrace z BMad v4 na v6 -sidebar: - order: 2 ---- - -Použijte instalátor BMad pro upgrade z v4 na v6, který zahrnuje automatickou detekci starších instalací a asistenci při migraci. - -## Kdy to použít - -- Máte nainstalovaný BMad v4 (složka `.bmad-method`) -- Chcete migrovat na novou architekturu v6 -- Máte existující plánovací artefakty k zachování - -:::note[Předpoklady] -- Node.js 20.12+ -- Existující instalace BMad v4 -::: - -## Kroky - -### 1. Spusťte instalátor - -Postupujte podle [instrukcí instalátoru](./install-bmad.md). - -### 2. Zpracování starší instalace - -Když je detekována v4, můžete: - -- Nechat instalátor zálohovat a odstranit `.bmad-method` -- Ukončit a zpracovat vyčištění ručně - -Pokud jste pojmenovali složku bmad method jinak, musíte ji odstranit ručně. - -### 3. Vyčištění IDE skills - -Ručně odstraňte starší v4 IDE příkazy/skills — například pokud máte Claude Code, hledejte vnořené složky začínající na bmad a odstraňte je: - -- `.claude/commands/` - -Nové v6 skills se instalují do: - -- `.claude/skills/` - -### 4. Migrace plánovacích artefaktů - -**Pokud máte plánovací dokumenty (Brief/PRD/UX/Architektura):** - -Přesuňte je do `_bmad-output/planning-artifacts/` s popisnými názvy: - -- Zahrňte `PRD` v názvu souboru pro PRD dokumenty -- Zahrňte `brief`, `architecture` nebo `ux-design` odpovídajícím způsobem -- Rozdělené dokumenty mohou být v pojmenovaných podsložkách - -**Pokud jste uprostřed plánování:** Zvažte restart s v6 workflow. Použijte existující dokumenty jako vstupy — nové workflow s progresivním objevováním, webovým vyhledáváním a plan mode IDE produkují lepší výsledky. - -### 5. Migrace probíhajícího vývoje - -Pokud máte vytvořené nebo implementované stories: - -1. Dokončete instalaci v6 -2. Umístěte `epics.md` nebo `epics/epic*.md` do `_bmad-output/planning-artifacts/` -3. Spusťte workflow `bmad-sprint-planning` Scrum Mastera -4. Řekněte SM, které epicy/stories jsou již dokončené - -## Co získáte - -**Sjednocená struktura v6:** - -```text -váš-projekt/ -├── _bmad/ # Jedna instalační složka -│ ├── _config/ # Vaše přizpůsobení -│ │ └── agents/ # Soubory přizpůsobení agentů -│ ├── core/ # Univerzální základní framework -│ ├── bmm/ # Modul BMad Method -│ ├── bmb/ # BMad Builder -│ └── cis/ # Creative Intelligence Suite -└── _bmad-output/ # Výstupní složka (v4 to byla složka dokumentů) -``` - -## Migrace modulů - -| Modul v4 | Stav v6 | -| ----------------------------- | ---------------------------------- | -| `.bmad-2d-phaser-game-dev` | Integrován do modulu BMGD | -| `.bmad-2d-unity-game-dev` | Integrován do modulu BMGD | -| `.bmad-godot-game-dev` | Integrován do modulu BMGD | -| `.bmad-infrastructure-devops` | Zastaralý — nový DevOps agent brzy | -| `.bmad-creative-writing` | Neadaptován — nový v6 modul brzy | - -## Klíčové změny - -| Koncept | v4 | v6 | -| --------------- | ------------------------------------ | -------------------------------------- | -| **Core** | `_bmad-core` byl vlastně BMad Method | `_bmad/core/` je univerzální framework | -| **Method** | `_bmad-method` | `_bmad/bmm/` | -| **Konfigurace** | Přímá editace souborů | `config.yaml` pro každý modul | -| **Dokumenty** | Vyžadované nastavení shardů | Plně flexibilní, auto-skenování | diff --git a/docs/cs/index.md b/docs/cs/index.md deleted file mode 100644 index c345d737c1..0000000000 --- a/docs/cs/index.md +++ /dev/null @@ -1,56 +0,0 @@ ---- -title: Vítejte v metodě BMad -description: Framework pro vývoj řízený umělou inteligencí se specializovanými agenty, řízenými pracovními postupy a inteligentním plánováním ---- - -Metoda BMad (**B**uild **M**ore **A**rchitect **D**reams) je framework pro vývoj řízený umělou inteligencí v rámci ekosystému BMad Method, který vám pomáhá vytvářet software celým procesem od nápadu a plánování až po agentní implementaci. Poskytuje specializované AI agenty, řízené pracovní postupy a inteligentní plánování, které se přizpůsobí složitosti vašeho projektu, ať už opravujete chybu nebo budujete podnikovou platformu. - -Pokud jste zvyklí pracovat s AI asistenty pro kódování jako Claude, Cursor nebo GitHub Copilot, jste připraveni začít. - -## Jste tu nově? Začněte tutoriálem - -Nejrychlejší způsob, jak pochopit BMad, je vyzkoušet si ho. - -- **[Začínáme s BMad](./tutorials/getting-started.md)** — Instalace a pochopení fungování BMad -- **[Mapa pracovních postupů](./reference/workflow-map.md)** — Vizuální přehled fází BMM, pracovních postupů a správy kontextu - -:::tip[Chcete se rovnou ponořit?] -Nainstalujte BMad a použijte skill `bmad-help` — provede vás vším na základě vašeho projektu a nainstalovaných modulů. -::: - -## Jak používat tuto dokumentaci - -Tato dokumentace je organizována do čtyř sekcí podle toho, co chcete dělat: - -| Sekce | Účel | -| -------------------- | ------------------------------------------------------------------------------------------------------------------ | -| **Tutoriály** | Orientované na učení. Průvodci krok za krokem, kteří vás provedou tvorbou něčeho. Začněte zde, pokud jste noví. | -| **Praktické návody** | Orientované na úkoly. Praktičtí průvodci pro řešení konkrétních problémů. „Jak přizpůsobím agenta?“ najdete zde. | -| **Vysvětlení** | Orientované na pochopení. Hluboké ponory do konceptů a architektury. Čtěte, když chcete vědět *proč*. | -| **Reference** | Orientované na informace. Technické specifikace agentů, pracovních postupů a konfigurace. | - -## Rozšíření a přizpůsobení - -Chcete rozšířit BMad o vlastní agenty, pracovní postupy nebo moduly? **[BMad Builder](https://bmad-builder-docs.bmad-method.org/)** poskytuje framework a nástroje pro vytváření vlastních rozšíření, ať už přidáváte nové schopnosti do BMad nebo budujete zcela nové moduly od základů. - -## Co budete potřebovat - -BMad funguje s jakýmkoli AI asistentem pro kódování, který podporuje vlastní systémové prompty nebo kontextové soubory projektu. Oblíbené možnosti zahrnují: - -- **[Claude Code](https://code.claude.com)** — CLI nástroj od Anthropic (doporučený) -- **[Cursor](https://cursor.sh)** — AI-first editor kódu -- **[Codex CLI](https://github.com/openai/codex)** — Terminálový kódovací agent od OpenAI - -Měli byste být obeznámeni se základními koncepty vývoje softwaru jako správa verzí, struktura projektu a agilní pracovní postupy. Žádná předchozí zkušenost se systémy agentů ve stylu BMad není vyžadována — právě od toho je tato dokumentace. - -## Připojte se ke komunitě - -Získejte pomoc, sdílejte co budujete, nebo přispějte do BMad: - -- **[Discord](https://discord.gg/gk8jAdXWmj)** — Chatujte s ostatními uživateli BMad, pokládejte otázky, sdílejte nápady -- **[GitHub](https://github.com/bmad-code-org/BMAD-METHOD)** — Zdrojový kód, issues a příspěvky -- **[YouTube](https://www.youtube.com/@BMadCode)** — Video tutoriály a návody - -## Další krok - -Jste připraveni se ponořit? **[Začněte s BMad](./tutorials/getting-started.md)** a vytvořte svůj první projekt. diff --git a/docs/cs/reference/agents.md b/docs/cs/reference/agents.md deleted file mode 100644 index a003893e23..0000000000 --- a/docs/cs/reference/agents.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -title: Agenti -description: Výchozí BMM agenti s jejich skill ID, spouštěči nabídky a primárními workflow -sidebar: - order: 2 ---- - -## Výchozí agenti - -Tato stránka uvádí výchozí BMM (Agile suite) agenty, kteří se instalují s BMad Method, společně s jejich skill ID, spouštěči nabídky a primárními workflow. Každý agent se vyvolává jako skill. - -## Poznámky - -- Každý agent je dostupný jako skill, generovaný instalátorem. Skill ID (např. `bmad-dev`) se používá k vyvolání agenta. -- Spouštěče jsou krátké kódy nabídky (např. `CP`) a fuzzy shody zobrazené v nabídce každého agenta. -- Generování QA testů zajišťuje workflow skill `bmad-qa-generate-e2e-tests`, dostupný přes Developer agenta. Plný Test Architect (TEA) žije ve vlastním modulu. - -| Agent | Skill ID | Spouštěče | Primární workflow | -| --------------------------- | -------------------- | -------------------------------------------- | --------------------------------------------------------------------------------------------------- | -| Analyst (Mary) | `bmad-analyst` | `BP`, `MR`, `DR`, `TR`, `CB`, `WB`, `DP` | Brainstorm, průzkum trhu, doménový výzkum, technický výzkum, tvorba briefu, PRFAQ výzva, dokumentace projektu | -| Product Manager (John) | `bmad-pm` | `CP`, `VP`, `EP`, `CE`, `IR`, `CC` | Tvorba/validace/editace PRD, tvorba epiců a stories, připravenost implementace, korekce kurzu | -| Architect (Winston) | `bmad-architect` | `CA`, `IR` | Tvorba architektury, připravenost implementace | -| Developer (Amelia) | `bmad-agent-dev` | `BD`, `QA`, `CR`, `SP`, `ER` | Build, generování QA testů, revize kódu, plánování sprintu, retrospektiva epicu | -| UX Designer (Sally) | `bmad-ux-designer` | `CU` | Tvorba UX designu | - -:::note[Kde je Paige?] -Technical Writer (Paige) má přestávku — v budoucnu se vrátí s mnohem širšími schopnostmi. Dokumentace projektu zůstává pokryta: spouštěč `DP` (dokumentace projektu) je dostupný přes Analyst agenta, nebo vyvolejte skill `bmad-document-project` přímo. -::: - -## Typy spouštěčů - -Spouštěče nabídky agentů načítají strukturovaný soubor workflow. Zadejte kód spouštěče a agent zahájí workflow a vyzve vás k zadání vstupu v každém kroku. - -Příklady: `CP` (tvorba PRD), `CA` (tvorba architektury), `BD` (Build) diff --git a/docs/cs/reference/commands.md b/docs/cs/reference/commands.md deleted file mode 100644 index 1cebf362c1..0000000000 --- a/docs/cs/reference/commands.md +++ /dev/null @@ -1,134 +0,0 @@ ---- -title: Skills -description: Reference BMad skills — co to je, jak fungují a kde je najít. -sidebar: - order: 4 ---- - -Skills jsou předpřipravené prompty, které načítají agenty, spouštějí workflow nebo provádějí úkoly ve vašem IDE. Instalátor BMad je generuje z vašich nainstalovaných modulů při instalaci. Pokud později přidáte, odeberete nebo změníte moduly, přeinstalujte pro synchronizaci skills (viz [Řešení problémů](#řešení-problémů)). - -## Skills vs. spouštěče nabídky agentů - -BMad nabízí dva způsoby zahájení práce a slouží k různým účelům. - -| Mechanismus | Jak se vyvolává | Co se stane | -| --- | --- | --- | -| **Skill** | Zadejte název skillu (např. `bmad-help`) ve vašem IDE | Přímo načte agenta, spustí workflow nebo provede úkol | -| **Spouštěč nabídky agenta** | Nejprve načtěte agenta, pak zadejte krátký kód (např. `BD`) | Agent interpretuje kód a spustí odpovídající workflow, přičemž zůstává v charakteru | - -Spouštěče nabídky agentů vyžadují aktivní relaci agenta. Používejte skills, když víte, který workflow chcete. Používejte spouštěče, když již pracujete s agentem a chcete přepnout úkol bez opuštění konverzace. - -## Jak se skills generují - -Když spustíte `npx bmad-method install`, instalátor čte manifesty každého vybraného modulu a zapíše jeden skill na agenta, workflow, úkol a nástroj. Každý skill je adresář obsahující soubor `SKILL.md`, který instruuje AI k načtení odpovídajícího zdrojového souboru a následování jeho instrukcí. - -Instalátor používá šablony pro každý typ skillu: - -| Typ skillu | Co generovaný soubor dělá | -| --- | --- | -| **Spouštěč agenta** | Načte soubor persony agenta, aktivuje jeho nabídku a zůstává v charakteru | -| **Workflow skill** | Načte konfiguraci workflow a následuje jeho kroky | -| **Task skill** | Načte samostatný soubor úkolu a následuje jeho instrukce | -| **Tool skill** | Načte samostatný soubor nástroje a následuje jeho instrukce | - -:::note[Opětovné spuštění instalátoru] -Pokud přidáte nebo odeberete moduly, spusťte instalátor znovu. Přegeneruje všechny soubory skills tak, aby odpovídaly vašemu aktuálnímu výběru modulů. -::: - -## Kde žijí soubory skills - -Instalátor zapisuje soubory skills do adresáře specifického pro IDE uvnitř vašeho projektu. Přesná cesta závisí na IDE, které jste vybrali během instalace. - -| IDE / CLI | Adresář skills | -| --- | --- | -| Claude Code | `.claude/skills/` | -| Cursor | `.cursor/skills/` | -| Windsurf | `.windsurf/skills/` | -| Další IDE | Viz výstup instalátoru pro cílovou cestu | - -Každý skill je adresář obsahující soubor `SKILL.md`. Například instalace Claude Code vypadá takto: - -```text -.claude/skills/ -├── bmad-help/ -│ └── SKILL.md -├── bmad-prd/ -│ └── SKILL.md -├── bmad-agent-dev/ -│ └── SKILL.md -└── ... -``` - -Název adresáře určuje název skillu ve vašem IDE. Například adresář `bmad-agent-dev/` registruje skill `bmad-agent-dev`. - -## Jak objevit vaše skills - -Zadejte název skillu ve vašem IDE pro jeho vyvolání. Některé platformy vyžadují povolení skills v nastavení, než se zobrazí. - -Spusťte `bmad-help` pro kontextové poradenství k dalšímu kroku. - -:::tip[Rychlé objevování] -Generované adresáře skills ve vašem projektu jsou kanonický seznam. Otevřete je v prohlížeči souborů, abyste viděli každý skill s jeho popisem. -::: - -## Kategorie skills - -### Agentní skills - -Agentní skills načítají specializovanou AI personu s definovanou rolí, komunikačním stylem a nabídkou workflow. Po načtení agent zůstává v charakteru a reaguje na spouštěče nabídky. - -| Příklad skillu | Agent | Role | -| --- | --- | --- | -| `bmad-agent-dev` | Amelia (Developer) | Implementuje stories s přísným dodržováním specifikací | -| `bmad-pm` | John (Product Manager) | Vytváří a validuje PRD | -| `bmad-architect` | Winston (Architect) | Navrhuje systémovou architekturu | - -Viz [Agenti](./agents.md) pro úplný seznam výchozích agentů a jejich spouštěčů. - -### Workflow skills - -Workflow skills spouštějí strukturovaný, vícekrokový proces bez předchozího načtení persony agenta. Načtou konfiguraci workflow a následují jeho kroky. - -| Příklad skillu | Účel | -| --- | --- | -| `bmad-product-brief` | Vytvoření product briefu — řízené discovery, když je váš koncept jasný | -| `bmad-prfaq` | [Working Backwards PRFAQ](../explanation/analysis-phase.md#prfaq-working-backwards) výzva pro zátěžový test vašeho produktového konceptu | -| `bmad-prd` | Vytvoření dokumentu požadavků (PRD) | -| `bmad-architecture` | Návrh systémové architektury | -| `bmad-create-epics-and-stories` | Vytvoření epiců a stories | -| `bmad-code-review` | Spuštění revize kódu | -| `bmad-build` | Implementace přímého záměru, issue, funkce, opravy nebo naplánované story | - -Viz [Mapa pracovních postupů](./workflow-map.md) pro kompletní referenci workflow organizovanou podle fází. - -### Task a tool skills - -Tasks a tools jsou samostatné operace, které nevyžadují kontext agenta nebo workflow. - -**BMad-Help: Váš inteligentní průvodce** - -`bmad-help` je vaše primární rozhraní pro objevení, co dělat dál. Zkoumá váš projekt, rozumí dotazům v přirozeném jazyce a doporučuje další povinný nebo volitelný krok na základě nainstalovaných modulů. - -:::note[Příklad] -``` -bmad-help -bmad-help I have a SaaS idea and know all the features. Where do I start? -bmad-help What are my options for UX design? -``` -::: - -**Další základní tasks a tools** - -Základní modul zahrnuje 8 vestavěných nástrojů — nápovědu, revize, zdokonalování, přizpůsobení a myšlenkové skills (brainstorming, forge idea, party mode). Viz [Základní nástroje](./core-tools.md) pro kompletní referenci. - -## Konvence pojmenování - -Všechny skills používají prefix `bmad-` následovaný popisným názvem (např. `bmad-dev`, `bmad-prd`, `bmad-help`). Viz [Moduly](./modules.md) pro dostupné moduly. - -## Řešení problémů - -**Skills se nezobrazují po instalaci.** Některé platformy vyžadují explicitní povolení skills v nastavení. Zkontrolujte dokumentaci vašeho IDE nebo se zeptejte AI asistenta, jak skills povolit. Může být také nutné restartovat IDE nebo znovu načíst okno. - -**Očekávané skills chybí.** Instalátor generuje skills pouze pro moduly, které jste vybrali. Spusťte `npx bmad-method install` znovu a ověřte výběr modulů. Zkontrolujte, že soubory skills existují v očekávaném adresáři. - -**Skills z odebraného modulu se stále zobrazují.** Instalátor automaticky nemaže staré soubory skills. Odstraňte zastaralé adresáře z adresáře skills vašeho IDE, nebo smažte celý adresář skills a přeinstalujte pro čistou sadu. diff --git a/docs/cs/reference/core-tools.md b/docs/cs/reference/core-tools.md deleted file mode 100644 index 6c66754abd..0000000000 --- a/docs/cs/reference/core-tools.md +++ /dev/null @@ -1,216 +0,0 @@ ---- -title: Základní nástroje -description: Reference vestavěných skills základního modulu. -sidebar: - order: 3 ---- - -Každá instalace BMad zahrnuje **základní modul** — malou sadu skills, které fungují napříč všemi projekty, všemi moduly a všemi fázemi. Tato stránka pokrývá těchto sedm základních skills: čtyři jádrové nástroje plus tři **myšlenkové skills** (brainstorming, forge idea, party mode). - -:::tip[Rychlá cesta] -Spusťte jakýkoli nástroj zadáním jeho názvu skillu (např. `bmad-help`) ve vašem IDE. Nevyžaduje relaci agenta. -::: - -## Přehled - -**Základní modul (vždy nainstalován):** - -| Nástroj | Účel | -| --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | -| [`bmad-help`](#bmad-help) | Kontextové poradenství, co dělat dál | -| [`bmad-advanced-elicitation`](#bmad-advanced-elicitation) | Iterativní zdokonalování LLM výstupu | -| [`bmad-review`](#bmad-review) | Revize z více perspektiv — adversariální, hraniční případy a mezery ve verifikaci pro kód; struktura a text pro dokumenty | -| [`bmad-customize`](#bmad-customize) | Vytváření a ověřování přizpůsobení BMad | - -**Myšlenkové skills:** - -| Nástroj | Účel | -| ------------------------------------------- | ---------------------------------------------------------------------- | -| [`bmad-brainstorming`](#bmad-brainstorming) | Facilitace interaktivních brainstormingových sezení | -| [`bmad-forge-idea`](#bmad-forge-idea) | Zátěžový test nápadu, dokud se nezpevní, nepotvrdí, nebo levně nezemře | -| [`bmad-party-mode`](#bmad-party-mode) | Orchestrace skupinových diskuzí více agentů | - -:::note[Přesunuto a odstraněno] -`bmad-spec` se nyní dodává s modulem BMM jako plánovací workflow Fáze 2 — viz [Mapa workflow](./workflow-map.md). Utility `bmad-shard-doc` a `bmad-index-docs` byly odstraněny. Dřívější skills `bmad-editorial-review`, `bmad-editorial-review-prose`, `bmad-editorial-review-structure`, `bmad-review-adversarial-general`, `bmad-review-edge-case-hunter` a `bmad-review-verification-gap` jsou všechny sloučeny do `bmad-review`, jehož redakční perspektivy nahrazují samostatný redakční skill; staré identifikátory se stále rozliší přes přesměrování kvůli kompatibilitě. -::: - -## bmad-help - -**Váš inteligentní průvodce tím, co přijde dál.** — Zkoumá stav vašeho projektu, detekuje, co bylo uděláno, a doporučuje další povinný nebo volitelný krok. - -**Použijte když:** - -- Dokončili jste workflow a chcete vědět, co dál -- Jste noví v BMad a potřebujete orientaci -- Jste uvízlí a chcete kontextovou radu -- Nainstalovali jste nové moduly a chcete vidět, co je dostupné - -**Jak to funguje:** - -1. Skenuje projekt pro existující artefakty (PRD, architektura, stories atd.) -2. Detekuje nainstalované moduly a dostupné workflow -3. Doporučuje další kroky v pořadí priority — nejprve povinné, pak volitelné -4. Prezentuje každé doporučení s příkazem skillu a stručným popisem - -**Vstup:** Volitelný dotaz v přirozeném jazyce (např. `bmad-help I have a SaaS idea, where do I start?`) - -**Výstup:** Prioritizovaný seznam doporučených dalších kroků s příkazy skills - -## bmad-advanced-elicitation - -**Přiměje LLM přehodnotit, zdokonalit a vylepšit svůj nedávný výstup.** — Sdílený zdokonalovací checkpoint BMad: ostatní skills jej vyvolávají při přirozených pauzách a vy jej můžete zavolat přímo na cokoli nedávného v konverzaci. - -**Použijte když:** - -- LLM výstup působí povrchně nebo genericky -- Chcete prozkoumat téma z více analytických úhlů -- Zdokonalujete kritický dokument a chcete hlubší myšlení -- Chcete známou metodu jménem — sokratovská, první principy, pre-mortem, red team - -**Jak to funguje:** - -1. Cílí na nejnovější výstup v konverzaci, pokud jej nenasměrujete jinam -2. Nabídne krátké menu elicitačních metod nejlépe odpovídajících obsahu -3. Aplikuje zvolené metody na cíl -4. Vrátí vylepšenou verzi, aby vyvolávající tok pokračoval tam, kde se zastavil - -**Vstup:** Nedávný výstup ke zdokonalení (výchozí), nebo jakýkoli obsah, na který ukážete; volitelně pojmenovaná metoda - -**Výstup:** Vylepšená verze obsahu s aplikovanými zlepšeními - -## bmad-review - -**Revize z více perspektiv nad jakýmkoli diffem, dokumentem nebo artefaktem.** — Spouští revizní perspektivy — každou s vlastní metodou a postojem — a hlásí každý nález v jednom kanonickém tvaru. Nula nálezů je platný výsledek; nikdy nedoplňuje, aby vypadal důkladně. Každá perspektiva deklaruje, na co se vztahuje: diff vyvolá perspektivy pro kód, dokument ty redakční. - -**Dodávané perspektivy:** - -| Perspektiva | Vztahuje se na | Metoda | -| ------------------------ | ------------------------- | -------------------------------------------------------------------------------------------- | -| **Adversariální** | Jakýkoli obsah | Skeptická revize předpokládající existenci problémů — hledá, co chybí, ne jen co je špatně | -| **Hraniční případy** | Jakýkoli obsah | Projde každou větvící se cestu a hraniční podmínku v obsahu, který definuje chování | -| **Mezery ve verifikaci** | Kód | Hledá změněné chování, které by mohlo regredovat, aniž by to spolehlivá verifikace zachytila | -| **Struktura** | Dokumenty | Navrhuje škrty, sloučení, přesuny a zhuštění — slouží tvar dokumentu jeho účelu? | -| **Text** | Dokumenty | Redakčně upravuje komunikační problémy, které brání porozumění | - -Obě redakční perspektivy považují obsah za nedotknutelný: nikdy nezpochybňují vaše myšlenky, pouze jejich uspořádání a vyjádření, a navrhují místo toho, aby zasahovaly. Je-li vybráno obojí, textová perspektiva běží nad nálezy strukturní. - -Sada není pevná: přepis v `customize.toml` může perspektivy přidat nebo nahradit dodávané a revize spustí ty, které se skutečně vyhodnotí. - -**Použijte když:** - -- Potřebujete zajištění kvality před finalizací výstupu -- Chcete vyčerpávající pokrytí hraničních případů kódu nebo logiky -- Chcete vědět, zda je změna dostatečně ověřena -- Napsali jste dokument a chcete jej zpřesnit a vyladit -- Chcete zkrátit délku při zachování srozumitelnosti - -**Jak to funguje:** - -1. Načte obsah, identifikuje jeho typ — diff, soubor, funkce nebo dokument — a zda jde o kód či dokumentaci -2. Vybere perspektivy: ty, které pojmenujete, nebo každou povolenou perspektivu, jejíž použitelnost a podmínky obsahu odpovídají -3. Oznámí plán — které perspektivy poběží a které staví na nálezech jiné -4. Spustí nezávislé perspektivy — paralelně přes subagenty, pokud to platforma podporuje — a poté ty závislé -5. Sestaví jeden seznam nálezů; překryv mezi perspektivami je signál, ne duplikace - -**Vstup:** - -- `content` (povinné) — Diff, větev, nezakomitované změny, soubor, specifikace, story nebo jakýkoli dokument -- `lenses` (volitelné) — jeden nebo více kódů či názvů perspektiv; výchozí je plná revize -- `also_consider` (volitelné) — Další oblasti k zvážení -- `style_guide` / `reader_type` (volitelné, redakční perspektivy) — projektový průvodce stylem a `humans` (výchozí) nebo `llm` - -**Výstup:** JSON pole nálezů a/nebo markdown report seskupený podle perspektiv. Vlastní perspektivy lze přidat — a dodávané doladit či vypnout — přes `customize.toml` skillu - -## bmad-customize - -**Vytváření a ověřování přizpůsobení.** — Pomůže vám změnit chování nainstalovaného BMad agenta nebo workflow bez ručního psaní TOML. - -**Použijte když:** - -- Chcete změnit chování agenta nebo workflow -- Potřebujete přidat trvalé fakty, aktivační hooky nebo vlastní položky menu -- Chcete, aby byl správný rozsah přepisu vybrán a ověřen automaticky - -**Jak to funguje:** - -1. Skenuje nainstalované BMad skills pro přizpůsobitelné plochy -2. Vybere správný rozsah pro požadovanou změnu -3. Zapíše přepisové soubory pod `_bmad/custom/` -4. Ověří sloučenou konfiguraci - -**Vstup:** Popis požadovaného přizpůsobení v přirozeném jazyce - -**Výstup:** TOML přepisové soubory pod `_bmad/custom/`. Podrobný návod viz [Jak přizpůsobit BMad](../how-to/customize-bmad.md) - -## Myšlenkové skills - -Tři skills níže doplňují základní modul — obecné myšlenkové nástroje, o které se může opřít kterákoli fáze či modul. - -### bmad-brainstorming - -**Generování různorodých nápadů prostřednictvím interaktivních kreativních technik.** — Facilitované brainstormingové sezení, které načítá osvědčené ideační metody z knihovny technik a vede vás k 100+ nápadům před organizací. - -**Použijte když:** - -- Začínáte nový projekt a potřebujete prozkoumat problémový prostor -- Jste uvízlí s generováním nápadů a potřebujete strukturovanou kreativitu -- Chcete použít osvědčené ideační frameworky (SCAMPER, reverzní brainstorming atd.) - -**Jak to funguje:** - -1. Nastaví brainstormingové sezení s vaším tématem -2. Načte kreativní techniky z knihovny metod -3. Provede vás technikou za technikou, generuje nápady -4. Aplikuje anti-bias protokol — mění kreativní doménu každých 10 nápadů - -**Vstup:** Téma brainstormingu nebo formulace problému, volitelný kontextový soubor - -**Výstup:** samostatný `brainstorm.html` jako památka na sezení, volitelný `brainstorm-intent.md` pro navazující skills a záznam sezení `.memlog.md` - -:::note[Cíl množství] -Kouzlo se děje v nápadech 50–100. Workflow povzbuzuje generování 100+ nápadů před organizací. -::: - -### bmad-forge-idea - -**Zátěžový test nápadu, dokud se nezpevní, nepotvrdí, nebo levně nezemře.** — Adversariální tazatel žene napůl zformovaný nápad otázku po otázce, do každého větvení přivádí dvě postavy, dokud to, co přežije, není něco, na čem můžete s přesvědčením stavět. - -**Použijte když:** - -- Máte nápad a chcete jej otestovat, než do něj investujete -- Chcete upřímný pohled na to, zda jej zabít -- Potřebujete myšlenkového partnera, který se vzepře, místo aby souhlasil - -**Jak to funguje:** - -1. Předem stanoví cíl a podle něj směruje dotazování -2. Pracuje otázku po otázce v pořadí závislostí a předkládá doporučenou odpověď, proti které se lze vymezit -3. Do každého větvení přivádí dva hlasy — jeden z vaší nainstalované sestavy, jeden vyvolaný tématem -4. Zpochybňuje mlhavé pojmy a testuje tvrzení proti materiálu existujícího projektu -5. Končí jako Zpevněný, Zabitý nebo Jasnější, se samostatným reportem, který si můžete ponechat - -**Vstup:** Nápad z jakékoli domény — funkce, byznys model, výzkumná hypotéza, životní rozhodnutí - -**Výstup:** Destilát `forged-idea.md`, když se nápad zpevní (volitelné), plus `forge-report.html` z každého běhu - -### bmad-party-mode - -**Orchestrace skupinových diskuzí více agentů.** — Načte všechny nainstalované BMad agenty a facilituje přirozenou konverzaci, kde každý agent přispívá svou unikátní odborností a osobností. - -**Použijte když:** - -- Potřebujete více expertních perspektiv na rozhodnutí -- Chcete, aby agenti zpochybňovali předpoklady ostatních -- Zkoumáte složité téma překračující více domén - -**Jak to funguje:** - -1. Načte manifest agentů se všemi nainstalovanými osobnostmi -2. Analyzuje vaše téma a vybere 2–3 nejrelevantnější agenty -3. Agenti se střídají v přispívání, s přirozenou kříženou diskuzí a nesouhlasy -4. Rotuje účast agentů pro zajištění různorodých perspektiv -5. Ukončete pomocí `goodbye`, `end party` nebo `quit` - -**Vstup:** Diskuzní téma nebo otázka, s volitelnou specifikací person - -**Výstup:** Real-time multi-agentní konverzace s udržovanými osobnostmi agentů diff --git a/docs/cs/reference/modules.md b/docs/cs/reference/modules.md deleted file mode 100644 index 7b917b76e3..0000000000 --- a/docs/cs/reference/modules.md +++ /dev/null @@ -1,76 +0,0 @@ ---- -title: Oficiální moduly -description: Doplňkové moduly pro tvorbu vlastních agentů, kreativní inteligenci, vývoj her a testování -sidebar: - order: 5 ---- - -BMad se rozšiřuje prostřednictvím oficiálních modulů, které vyberete během instalace. Tyto doplňkové moduly poskytují specializované agenty, workflow a úkoly pro specifické domény nad rámec vestavěného jádra a BMM (Agile suite). - -:::tip[Instalace modulů] -Spusťte `npx bmad-method install` a vyberte požadované moduly. Instalátor se postará o stažení, konfiguraci a integraci s IDE automaticky. -::: - -## BMad Builder - -Vytvářejte vlastní agenty, workflow a doménově specifické moduly s řízenou asistencí. BMad Builder je meta-modul pro rozšiřování samotného frameworku. - -- **Kód:** `bmb` -- **npm:** [`bmad-builder`](https://www.npmjs.com/package/bmad-builder) -- **GitHub:** [bmad-code-org/bmad-builder](https://github.com/bmad-code-org/bmad-builder) - -**Poskytuje:** - -- Agent Builder — tvorba specializovaných AI agentů s vlastní odborností a přístupem k nástrojům -- Workflow Builder — návrh strukturovaných procesů s kroky a rozhodovacími body -- Module Builder — balíčkování agentů a workflow do sdílitelných, publikovatelných modulů -- Interaktivní nastavení s YAML konfigurací a podporou npm publikování - -## Creative Intelligence Suite - -AI nástroje pro strukturovanou kreativitu, ideaci a inovace v rané fázi vývoje. Suite poskytuje více agentů, kteří facilitují brainstorming, design thinking a řešení problémů pomocí osvědčených frameworků. - -- **Kód:** `cis` -- **npm:** [`bmad-creative-intelligence-suite`](https://www.npmjs.com/package/bmad-creative-intelligence-suite) -- **GitHub:** [bmad-code-org/bmad-module-creative-intelligence-suite](https://github.com/bmad-code-org/bmad-module-creative-intelligence-suite) - -**Poskytuje:** - -- Agenty Innovation Strategist, Design Thinking Coach a Brainstorming Coach -- Problem Solver a Creative Problem Solver pro systematické a laterální myšlení -- Storyteller a Presentation Master pro narativy a prezentace -- Ideační frameworky včetně SCAMPER, reverzního brainstormingu a přeformulování problémů - -## Game Dev Studio - -Strukturované workflow pro vývoj her adaptované pro Unity, Unreal, Godot a vlastní enginy. Podporuje hloubku plánování od rychlého prototypování po plnoscálovou produkci; implementace se sbíhá do Build. - -- **Kód:** `gds` -- **npm:** [`bmad-game-dev-studio`](https://www.npmjs.com/package/bmad-game-dev-studio) -- **GitHub:** [bmad-code-org/bmad-module-game-dev-studio](https://github.com/bmad-code-org/bmad-module-game-dev-studio) - -**Poskytuje:** - -- Workflow pro generování Game Design Document (GDD) -- Herní kontext a plánování pro standardní implementační loop Build -- Podporu narativního designu pro postavy, dialogy a budování světa -- Pokrytí 21+ typů her s architektonickým vedením specifickým pro engine - -## Test Architect (TEA) - -Podniková testovací strategie, vedení automatizace a rozhodování o release gate prostřednictvím expertního agenta a devíti strukturovaných workflow. TEA jde daleko za vestavěného QA agenta s prioritizací založenou na riziku a trasovatelností požadavků. - -- **Kód:** `tea` -- **npm:** [`bmad-method-test-architecture-enterprise`](https://www.npmjs.com/package/bmad-method-test-architecture-enterprise) -- **GitHub:** [bmad-code-org/bmad-method-test-architecture-enterprise](https://github.com/bmad-code-org/bmad-method-test-architecture-enterprise) - -**Poskytuje:** - -- Agenta Murat (Master Test Architect a Quality Advisor) -- Workflow pro testovací design, ATDD, automatizaci, revizi testů a trasovatelnost -- Hodnocení NFR, nastavení CI a scaffolding frameworku -- Prioritizaci P0-P3 s volitelnými integracemi Playwright Utils a MCP - -## Komunitní moduly - -Komunitní moduly a marketplace modulů přicházejí. Sledujte [organizaci BMad na GitHubu](https://github.com/bmad-code-org) pro aktualizace. diff --git a/docs/cs/reference/testing.md b/docs/cs/reference/testing.md deleted file mode 100644 index c8f1d9194e..0000000000 --- a/docs/cs/reference/testing.md +++ /dev/null @@ -1,106 +0,0 @@ ---- -title: Možnosti testování -description: Srovnání vestavěného QA agenta (Quinn) s modulem Test Architect (TEA) pro automatizaci testů. -sidebar: - order: 6 ---- - -BMad poskytuje dvě testovací cesty: vestavěného QA agenta pro rychlé generování testů a instalovatelný modul Test Architect pro podnikovou testovací strategii. - -## Který byste měli použít? - -| Faktor | Quinn (vestavěný QA) | Modul TEA | -| --- | --- | --- | -| **Nejlepší pro** | Malé až střední projekty, rychlé pokrytí | Velké projekty, regulované nebo složité domény | -| **Nastavení** | Nic k instalaci — součástí BMM | Instalace zvlášť přes `npx bmad-method install` | -| **Přístup** | Generujte testy rychle, iterujte později | Nejprve plánujte, pak generujte s trasovatelností | -| **Typy testů** | API a E2E testy | API, E2E, ATDD, NFR a další | -| **Strategie** | Happy path + kritické hraniční případy | Prioritizace založená na riziku (P0–P3) | -| **Počet workflow** | 1 (Automate) | 9 (design, ATDD, automate, review, trace a další) | - -:::tip[Začněte s Quinnem] -Většina projektů by měla začít s Quinnem. Pokud později budete potřebovat testovací strategii, quality gates nebo trasovatelnost požadavků, nainstalujte TEA vedle něj. -::: - -## Vestavěný QA agent (Quinn) - -Quinn je vestavěný QA agent v modulu BMM (Agile suite). Rychle generuje funkční testy pomocí existujícího testovacího frameworku vašeho projektu — bez konfigurace nebo další instalace. - -**Spouštěč:** `QA` nebo `bmad-qa-generate-e2e-tests` - -### Co Quinn dělá - -Quinn spouští jeden workflow (Automate), který projde pěti kroky: - -1. **Detekce testovacího frameworku** — skenuje `package.json` a existující testovací soubory pro váš framework (Jest, Vitest, Playwright, Cypress nebo jakýkoli standardní runner). Pokud neexistuje, analyzuje stack projektu a navrhne jeden. -2. **Identifikace funkcí** — zeptá se, co testovat, nebo automaticky objeví funkce v kódové bázi. -3. **Generování API testů** — pokrývá stavové kódy, strukturu odpovědí, happy path a 1–2 chybové případy. -4. **Generování E2E testů** — pokrývá uživatelské workflow se sémantickými lokátory a asercemi viditelných výsledků. -5. **Spuštění a ověření** — provede generované testy a okamžitě opraví selhání. - -Quinn produkuje shrnutí testů uložené do složky implementačních artefaktů vašeho projektu. - -### Vzory testů - -Generované testy sledují filozofii „jednoduché a udržovatelné“: - -- **Pouze standardní API frameworku** — žádné externí utility nebo vlastní abstrakce -- **Sémantické lokátory** pro UI testy (role, popisky, text místo CSS selektorů) -- **Nezávislé testy** bez závislostí na pořadí -- **Žádné hardcoded waity nebo sleep** -- **Jasné popisy**, které se čtou jako dokumentace funkcí - -:::note[Rozsah] -Quinn generuje pouze testy. Pro revizi kódu a validaci stories použijte workflow Code Review (`CR`). -::: - -### Kdy použít Quinna - -- Rychlé pokrytí testy pro novou nebo existující funkci -- Automatizace testů přátelská k začátečníkům bez pokročilého nastavení -- Standardní vzory testů, které může číst a udržovat jakýkoli vývojář -- Malé až střední projekty, kde komplexní testovací strategie není potřeba - -## Modul Test Architect (TEA) - -TEA je samostatný modul, který poskytuje expertního agenta (Murat) a devět strukturovaných workflow pro podnikové testování. Jde za rámec generování testů do testovací strategie, plánování založeného na riziku, quality gates a trasovatelnosti požadavků. - -- **Dokumentace:** [Dokumentace modulu TEA](https://bmad-code-org.github.io/bmad-method-test-architecture-enterprise/) -- **Instalace:** `npx bmad-method install` a výběr modulu TEA -- **npm:** [`bmad-method-test-architecture-enterprise`](https://www.npmjs.com/package/bmad-method-test-architecture-enterprise) - -### Co TEA poskytuje - -| Workflow | Účel | -| --- | --- | -| Test Design | Vytvoření komplexní testovací strategie vázané na požadavky | -| ATDD | Acceptance-test-driven development s kritérii stakeholderů | -| Automate | Generování testů s pokročilými vzory a utilitami | -| Test Review | Validace kvality a pokrytí testů proti strategii | -| Traceability | Mapování testů zpět na požadavky pro audit a compliance | -| NFR Assessment | Hodnocení nefunkčních požadavků (výkon, bezpečnost) | -| CI Setup | Konfigurace provádění testů v CI pipelines | -| Framework Scaffolding | Nastavení testovací infrastruktury a struktury projektu | -| Release Gate | Datově založená rozhodnutí go/no-go pro release | - -TEA také podporuje prioritizaci P0–P3 založenou na riziku a volitelné integrace s Playwright Utils a MCP nástroji. - -### Kdy použít TEA - -- Projekty vyžadující trasovatelnost požadavků nebo compliance dokumentaci -- Týmy potřebující prioritizaci testů založenou na riziku napříč mnoha funkcemi -- Podniková prostředí s formálními quality gates před releasem -- Složité domény, kde musí být testovací strategie naplánována před psaním testů -- Projekty, které přerostly jednoduchý workflow Quinna - -## Jak testování zapadá do workflow - -Quinn workflow Automate se objevuje ve Fázi 4 (Implementace) mapy workflow BMad Method. Je navržen ke spuštění **po dokončení celého epicu** — jakmile jsou všechny stories v epicu implementovány a zrevidovány. Typická sekvence: - -1. Pro každou story v epicu: implementace pomocí Build (`BD` / `bmad-build`), pak podle potřeby Code Review (`CR`) -2. Po dokončení epicu: generování testů s Quinnem (`QA`) nebo TEA workflow Automate -3. Spuštění retrospektivy (`bmad-retrospective`) pro zachycení získaných zkušeností - -Quinn pracuje přímo ze zdrojového kódu bez načítání plánovacích dokumentů (PRD, architektura). TEA workflow mohou integrovat s upstream plánovacími artefakty pro trasovatelnost. - -Pro více o tom, kde testování zapadá do celkového procesu, viz [Mapa pracovních postupů](./workflow-map.md). diff --git a/docs/cs/reference/workflow-map.md b/docs/cs/reference/workflow-map.md deleted file mode 100644 index 7c0edb3653..0000000000 --- a/docs/cs/reference/workflow-map.md +++ /dev/null @@ -1,83 +0,0 @@ ---- -title: "Mapa pracovních postupů" -description: Vizuální reference fází workflow BMad Method a jejich výstupů -sidebar: - order: 1 ---- - -BMad Method (BMM) je modul v ekosystému BMad, zaměřený na dodržování osvědčených postupů context engineeringu a plánování. AI agenti fungují nejlépe s jasným, strukturovaným kontextem. Systém BMM buduje tento kontext progresivně napříč 4 odlišnými fázemi — každá fáze a volitelně více workflow v každé fázi produkují dokumenty, které informují další, takže agenti vždy vědí, co budovat a proč. - -Zdůvodnění a koncepty vycházejí z agilních metodik, které byly v průmyslu úspěšně používány jako mentální framework. - -Pokud si kdykoli nejste jisti, co dělat, skill `bmad-help` vám pomůže zůstat na cestě nebo vědět, co dělat dál. Vždy se můžete odkázat sem — ale `bmad-help` je plně interaktivní a mnohem rychlejší, pokud již máte nainstalovaný BMad Method. Navíc, pokud používáte různé moduly, které rozšířily BMad Method nebo přidaly další komplementární moduly — `bmad-help` se vyvíjí a zná vše, co je dostupné, aby vám dal nejlepší radu v daném okamžiku. - -Důležitá poznámka: Každý workflow níže lze spustit přímo vaším nástrojem přes skill nebo načtením agenta a použitím záznamu z nabídky agenta. - - - -

- Otevřít diagram v novém panelu ↗ -

- -## Fáze 1: Analýza (volitelná) - -Prozkoumejte problémový prostor a validujte nápady před závazkem k plánování. - -| Workflow | Účel | Produkuje | -| ------------------------------- | -------------------------------------------------------------------------- | ------------------------- | -| `bmad-brainstorming` | Brainstorming nápadů na projekt s řízenou facilitací brainstormingového kouče | `brainstorming-report.md` | -| `bmad-deep-recon` | Validace předpokladů nebo výběr mezi variantami — návrh promptu pro váš nástroj hloubkového výzkumu, zpracování jeho zprávy, nebo výzkum přímo zde; tržní, doménový, technický, konkurenční, uživatelský, akademický; ověřené, citované, obnovitelné | Výzkumná zpráva či shrnutí + volitelný HTML briefing | -| `bmad-product-brief` | Zachycení strategické vize — nejlepší, když je váš koncept jasný | `product-brief.md` | -| `bmad-prfaq` | Working Backwards — zátěžový test a zformování vašeho produktového konceptu | `prfaq-{project}.md` | - -## Fáze 2: Plánování - -Definujte, co budovat a pro koho. - -| Workflow | Účel | Produkuje | -| --------------------------- | ---------------------------------------- | ------------ | -| `bmad-prd` | Definice požadavků (FR/NFR) | `PRD.md` | -| `bmad-ux` | Návrh uživatelského zážitku (když záleží na UX) | `DESIGN.md`, `EXPERIENCE.md` | -| `bmad-spec` | Destiluje jakýkoli vstupní záměr (brief, PRD, přepis, poznámky) do stručného kontraktu `SPEC.md` + doprovodných souborů — zafixuje CO před JAK | `SPEC.md` + doprovodné soubory pod `{output_folder}/specs/spec-{slug}/` | - -## Fáze 3: Solutioning - -Rozhodněte, jak to budovat, a rozložte práci na stories. - -| Workflow | Účel | Produkuje | -| ----------------------------------------- | ------------------------------------------ | --------------------------- | -| `bmad-architecture` | Explicitní technická rozhodnutí | `architecture.md` s ADR | -| `bmad-create-epics-and-stories` | Rozložení požadavků na implementovatelnou práci | Soubory epiců se stories | -| `bmad-sprint-planning` | Brána připravenosti před implementací, poté sledování stories a přehled stavu sprintu | PASS/CONCERNS/FAIL + `sprint-status.yaml` | - -## Fáze 4: Implementace - -Všechny implementační vstupy se sbíhají do `bmad-build`. Přijímá přímý záměr, issue, specifikaci nebo naplánovanou story a zvolí potřebnou míru upřesnění, plánování, implementace a revize. - -| Workflow | Účel | Produkuje | -| -------------------------- | ------------------------------------------------------------------------ | -------------------------------- | -| `bmad-build` | Převod přímého záměru nebo naplánované story na implementovaný a revidovaný kód | `spec-*.md` + kód | -| `bmad-code-review` | Validace kvality implementace | Schváleno nebo požadovány změny | -| `bmad-correct-course` | Řešení významných změn uprostřed sprintu | Aktualizovaný plán nebo přesměrování | -| `bmad-retrospective` | Revize po dokončení epicu | Poučení | - -### Přímý a plánovaný vstup - -Jasná práce může vstoupit do `bmad-build` přímo. Větší iniciativa může nejprve vytvořit PRD, UX, architekturu, epicy, stories, kontrolu připravenosti a sprint plán. Tyto artefakty přidávají kontext; nevybírají jiný implementační workflow. - -## Správa kontextu - -Každý dokument se stává kontextem pro další fázi. PRD říká architektovi, jaká omezení záleží. Architektura říká dev agentovi, jaké vzory následovat. Soubory stories poskytují zaměřený, kompletní kontext pro implementaci. Bez této struktury agenti dělají nekonzistentní rozhodnutí. - -### Kontext projektu - -:::tip[Doporučeno] -Vytvořte `project-context.md` pro zajištění toho, aby AI agenti dodržovali pravidla a preference vašeho projektu. Tento soubor funguje jako ústava vašeho projektu — vede implementační rozhodnutí napříč všemi workflow. Tento volitelný soubor lze vygenerovat na konci tvorby architektury, nebo u existujícího projektu ho lze také vygenerovat pro zachycení toho, co je důležité pro zachování souladu se současnými konvencemi. -::: - -**Jak ho vytvořit:** - -- **Ručně** — Vytvořte `_bmad-output/project-context.md` s vaším technologickým stackem a pravidly implementace -- **Vygenerujte ho** — Spusťte `bmad-generate-project-context` pro automatické generování z vaší architektury nebo kódové báze - -[**Zjistit více o project-context.md**](../explanation/project-context.md) diff --git a/docs/cs/tutorials/getting-started.md b/docs/cs/tutorials/getting-started.md deleted file mode 100644 index 3daf54c7f2..0000000000 --- a/docs/cs/tutorials/getting-started.md +++ /dev/null @@ -1,276 +0,0 @@ ---- -title: "Začínáme" -description: Nainstalujte BMad a vytvořte svůj první projekt ---- - -Vytvářejte software rychleji pomocí pracovních postupů řízených AI se specializovanými agenty, kteří vás provedou plánováním, architekturou a implementací. - -## Co se naučíte - -- Nainstalovat a inicializovat BMad Method pro nový projekt -- Používat **BMad-Help** — vašeho inteligentního průvodce, který ví, co dělat dál -- Zvolit správnou hloubku plánování pro vaši práci -- Postupovat fázemi od požadavků k fungujícímu kódu -- Efektivně používat agenty a pracovní postupy - -:::note[Předpoklady] -- **Node.js 20.12+** — Vyžadováno pro instalátor -- **Git** — Doporučeno pro správu verzí -- **AI-powered IDE** — Claude Code, Cursor nebo podobné -- **Nápad na projekt** — I jednoduchý stačí pro učení -::: - -:::tip[Nejsnadnější cesta] -**Instalace** → `npx bmad-method install` -**Zeptejte se** → `bmad-help what should I do first?` -**Tvořte** → Nechte BMad-Help vás provést workflow po workflow -::: - -## Seznamte se s BMad-Help: Váš inteligentní průvodce - -**BMad-Help je nejrychlejší způsob, jak začít s BMad.** Nemusíte si pamatovat workflow nebo fáze — prostě se zeptejte a BMad-Help: - -- **Prozkoumá váš projekt** a zjistí, co už bylo uděláno -- **Ukáže vaše možnosti** na základě nainstalovaných modulů -- **Doporučí, co dál** — včetně prvního povinného úkolu -- **Odpoví na otázky** jako „Mám nápad na SaaS, kde začít?“ - -### Jak používat BMad-Help - -Spusťte ho ve vašem AI IDE vyvoláním skillu: - -``` -bmad-help -``` - -Nebo ho spojte s otázkou pro kontextové poradenství: - -``` -bmad-help I have an idea for a SaaS product, I already know all the features I want. where do I get started? -``` - -BMad-Help odpoví s: -- Co je doporučeno pro vaši situaci -- Jaký je první povinný úkol -- Jak vypadá zbytek procesu - -### Řídí i pracovní postupy - -BMad-Help nejen odpovídá na otázky — **automaticky se spouští na konci každého workflow** a řekne vám přesně, co dělat dál. Žádné hádání, žádné prohledávání dokumentace — jen jasné pokyny k dalšímu povinnému workflow. - -:::tip[Začněte zde] -Po instalaci BMad okamžitě vyvolejte skill `bmad-help`. Detekuje, jaké moduly máte nainstalované, a navede vás ke správnému výchozímu bodu pro váš projekt. -::: - -## Pochopení BMad - -BMad vám pomáhá vytvářet software prostřednictvím řízených pracovních postupů se specializovanými AI agenty. Proces probíhá ve čtyřech fázích: - -| Fáze | Název | Co se děje | -| ---- | -------------- | ------------------------------------------------------- | -| 1 | Analýza | Brainstorming, průzkum, product brief nebo PRFAQ *(volitelné)* | -| 2 | Plánování | Vytvoření požadavků (PRD nebo specifikace) | -| 3 | Solutioning | Návrh architektury podle potřeby | -| 4 | Implementace | Implementace každé změny nebo naplánované story, volitelně pomocí automatizované orchestrace | - -**[Otevřete Mapu pracovních postupů](../reference/workflow-map.md)** pro prozkoumání fází, workflow a správy kontextu. - -Hloubka plánování je flexibilní: - -| Hloubka | Nejlepší pro | Kontext před implementací | -| --- | --- | --- | -| **Přímá** | Jasné opravy, funkce, issues nebo existující specifikace | Záměr, issue nebo specifikace | -| **Produktové plánování** | Produkty, platformy a složité funkce | PRD a volitelný UX návrh | -| **Plné solutioning** | Koordinované, rizikové nebo mezisystémové iniciativy | PRD, UX, architektura, epicy, stories a sprint plán | - -:::note -Nejde o oddělené implementační cesty. Všechny vstupy se sbíhají do `bmad-build`; plánování pouze mění množství dostupného kontextu. -::: - -## Instalace - -Otevřete terminál v adresáři vašeho projektu a spusťte: - -```bash -npx bmad-method install -``` - -Pokud chcete nejnovější prereleaseový build místo výchozího release kanálu, použijte `npx bmad-method@next install`. - -Při výzvě k výběru modulů zvolte **BMad Method**. - -Instalátor vytvoří dvě složky: -- `_bmad/` — agenti, workflow, úkoly a konfigurace -- `_bmad-output/` — prozatím prázdná, ale zde se budou ukládat vaše artefakty - -:::tip[Váš další krok] -Otevřete vaše AI IDE ve složce projektu a spusťte: - -``` -bmad-help -``` - -BMad-Help detekuje, co jste dokončili, a doporučí přesně, co dělat dál. Můžete mu také klást otázky jako „Jaké mám možnosti?“ nebo „Mám nápad na SaaS, kde začít?“ -::: - -:::note[Jak načítat agenty a spouštět workflow] -Každý workflow má **skill**, který vyvoláte jménem ve vašem IDE (např. `bmad-prd`). Váš AI nástroj rozpozná název `bmad-*` a spustí ho — nemusíte načítat agenty zvlášť. Můžete také vyvolat agentní skill přímo pro obecnou konverzaci (např. `bmad-agent-pm` pro PM agenta). -::: - -:::caution[Nové chaty] -Vždy začněte nový chat pro každý workflow. Tím předejdete problémům s kontextovými omezeními. -::: - -## Krok 1: Zvolte hloubku plánování - -Použijte z fází 1–3 tolik, kolik vaše práce potřebuje. U jasné, ohraničené práce můžete přejít přímo ke [Kroku 2](#krok-2-sestavte-svůj-projekt). **Pro každý workflow používejte nové chaty.** - -:::tip[Kontext projektu (volitelné)] -Před začátkem zvažte vytvoření `project-context.md` pro dokumentaci vašich technických preferencí a pravidel implementace. Tím zajistíte, že všichni AI agenti budou dodržovat vaše konvence v průběhu celého projektu. - -Vytvořte ho ručně na `_bmad-output/project-context.md` nebo ho vygenerujte po architektuře pomocí `bmad-generate-project-context`. [Zjistit více](../explanation/project-context.md). -::: - -### Fáze 1: Analýza (volitelná) - -Všechny workflow v této fázi jsou volitelné: -- **brainstorming** (`bmad-brainstorming`) — Řízená ideace -- **průzkum** (`bmad-deep-recon`) — Navrhne prompt pro váš vlastní nástroj hloubkového výzkumu, zpracuje hotovou zprávu do stručného shrnutí pro navazující práci, nebo výzkum provede přímo — tržní, doménový, technický, konkurenční, uživatelský a akademický — s ověřováním tvrzení a životním cyklem obnovy -- **product-brief** (`bmad-product-brief`) — Doporučený základní dokument, když je váš koncept jasný -- **prfaq** (`bmad-prfaq`) — Working Backwards výzva pro zátěžový test a zformování vašeho produktového konceptu - -### Fáze 2: Plánování (podle potřeby) - -Pro práci, které prospívá produktové plánování: -1. Vyvolejte **PM agenta** (`bmad-agent-pm`) v novém chatu -2. Spusťte workflow `bmad-prd` (`bmad-prd`) -3. Výstup: `PRD.md` - -:::note[UX Design (volitelné)] -Pokud má váš projekt uživatelské rozhraní, vyvolejte **UX-Designer agenta** (`bmad-agent-ux-designer`) a spusťte UX design workflow (`bmad-ux`) po vytvoření PRD. -::: - -### Fáze 3: Solutioning (podle potřeby) - -**Vytvoření architektury** -1. Vyvolejte **Architect agenta** (`bmad-agent-architect`) v novém chatu -2. Spusťte `bmad-architecture` (`bmad-architecture`) -3. Výstup: Dokument architektury s technickými rozhodnutími - -**Vytvoření epiců a stories** - -:::tip[Vylepšení ve V6] -Epicy a stories se nyní vytvářejí *po* architektuře. Tím vznikají kvalitnější stories, protože architektonická rozhodnutí (databáze, API vzory, tech stack) přímo ovlivňují rozklad práce. -::: - -1. Vyvolejte **PM agenta** (`bmad-agent-pm`) v novém chatu -2. Spusťte `bmad-create-epics-and-stories` (`bmad-create-epics-and-stories`) -3. Workflow využívá jak PRD, tak architekturu k vytvoření technicky informovaných stories - -**Kontrola připravenosti k implementaci** *(vysoce doporučeno)* -1. Vyvolejte **Architect agenta** (`bmad-agent-architect`) v novém chatu -2. Spusťte `bmad-sprint-planning` (`bmad-sprint-planning`) — otevírá se bránou připravenosti -3. Validuje soudržnost všech plánovacích dokumentů - -## Krok 2: Sestavte svůj projekt - -Přejděte k implementaci s jakýmkoli dostupným kontextem: přímým požadavkem, issue, specifikací nebo plně naplánovanou story. **Každý workflow by měl běžet v novém chatu.** - -U plánované práce spusťte `bmad-build` a určete vybranou story nebo položku sprintu, například: `Implementuj story 2.3 z _bmad-output/planning-artifacts/epics.md`. - -### Inicializace plánování sprintu (pro plánovanou práci) - -Vyvolejte **Developer agenta** (`bmad-agent-dev`) a spusťte `bmad-sprint-planning` (`bmad-sprint-planning`). Tím se vytvoří `sprint-status.yaml` pro sledování všech epiců a stories. - -Když Build v tomto souboru rozpozná vybranou story, během implementace ji přesune do stavu `in-progress` a po dokončení implementace do stavu `review`. - -### Cyklus vývoje - -Pro každou přímou změnu nebo naplánovanou story opakujte tento cyklus s novými chaty: - -| Krok | Agent | Workflow | Příkaz | Účel | -| ---- | ----- | -------------------- | -------------------------- | ---------------------------------- | -| 1 | DEV | `bmad-build` | `bmad-build` | Upřesnění, plán, implementace, revize a prezentace | -| 2 | DEV | `bmad-code-review` | `bmad-code-review` | Dodatečná validace kvality *(doporučeno)* | - -Revize v Build je součástí každého běhu. `bmad-code-review` je volitelná nezávislá validační vrstva v novém kontextu. - -Po dokončení všech stories v epicu vyvolejte **Developer agenta** (`bmad-agent-dev`) a spusťte `bmad-retrospective` (`bmad-retrospective`). - -## Co jste dosáhli - -Naučili jste se základy budování s BMad: - -- Nainstalovali BMad a nakonfigurovali ho pro vaše IDE -- Zvolili hloubku plánování odpovídající vaší práci -- Vytvořili plánovací dokumenty (PRD, architektura, epicy a stories) -- Pochopili cyklus vývoje pro implementaci - -Váš projekt nyní obsahuje: - -```text -váš-projekt/ -├── _bmad/ # Konfigurace BMad -├── _bmad-output/ -│ ├── planning-artifacts/ -│ │ ├── PRD.md # Váš dokument požadavků -│ │ ├── architecture.md # Technická rozhodnutí -│ │ └── epics/ # Soubory epiců a stories -│ ├── implementation-artifacts/ -│ │ └── sprint-status.yaml # Sledování sprintu -│ └── project-context.md # Pravidla implementace (volitelné) -└── ... -``` - -## Rychlý přehled - -| Workflow | Příkaz | Agent | Účel | -| ------------------------------------- | ------------------------------------------ | --------- | ----------------------------------------------- | -| **`bmad-help`** ⭐ | `bmad-help` | Jakýkoli | **Váš inteligentní průvodce — ptejte se na cokoli!** | -| `bmad-prd` | `bmad-prd` | PM | Vytvoření dokumentu požadavků (PRD) | -| `bmad-architecture` | `bmad-architecture` | Architect | Vytvoření dokumentu architektury | -| `bmad-generate-project-context` | `bmad-generate-project-context` | Analyst | Vytvoření souboru kontextu projektu | -| `bmad-create-epics-and-stories` | `bmad-create-epics-and-stories` | PM | Rozklad PRD na epicy | -| `bmad-sprint-planning` | `bmad-sprint-planning` | DEV | Brána připravenosti + inicializace sledování sprintu + přehled stavu | -| `bmad-build` | `bmad-build` | DEV | Implementace záměru, issue, funkce, opravy nebo story | -| `bmad-code-review` | `bmad-code-review` | DEV | Revize implementovaného kódu | - -## Časté otázky - -**Potřebuji vždy architekturu?** -Ne. Architekturu použijte, když je třeba explicitně zachytit technická rozhodnutí nebo mezisystémová omezení. Jasná práce může vstoupit přímo do `bmad-build`; větší iniciativa přináší do stejného workflow plánovací artefakty. - -**Mohu později změnit svůj plán?** -Ano. Workflow `bmad-correct-course` (`bmad-correct-course`) řeší změny rozsahu během implementace. - -**Co když chci nejdřív brainstormovat?** -Vyvolejte Analyst agenta (`bmad-agent-analyst`) a spusťte `bmad-brainstorming` (`bmad-brainstorming`) před zahájením PRD. - -**Musím dodržovat striktní pořadí?** -Ne striktně. Jakmile se naučíte postup, můžete spouštět workflow přímo pomocí Rychlého přehledu výše. - -## Získání pomoci - -:::tip[První zastávka: BMad-Help] -**Vyvolejte `bmad-help` kdykoli** — je to nejrychlejší způsob, jak se odpoutat. Zeptejte se na cokoli: -- „Co mám dělat po instalaci?“ -- „Zasekl jsem se na workflow X“ -- „Jaké mám možnosti pro Y?“ -- „Ukaž mi, co bylo dosud uděláno“ - -BMad-Help prozkoumá váš projekt, detekuje, co jste dokončili, a řekne vám přesně, co dělat dál. -::: - -- **Během workflow** — Agenti vás provázejí otázkami a vysvětleními -- **Komunita** — [Discord](https://discord.gg/gk8jAdXWmj) (#bmad-method-help, #report-bugs-and-issues) - -## Klíčové poznatky - -:::tip[Zapamatujte si] -- **Začněte s `bmad-help`** — Váš inteligentní průvodce, který zná váš projekt a možnosti -- **Vždy používejte nové chaty** — Začněte nový chat pro každý workflow -- **Hloubka plánování se liší** — přímý záměr i plně naplánované stories vstupují do `bmad-build` -- **BMad-Help se spouští automaticky** — Každý workflow končí pokyny, co dělat dál -::: - -Jste připraveni začít? Nainstalujte BMad, vyvolejte `bmad-help` a nechte svého inteligentního průvodce ukázat cestu. diff --git a/docs/fr/404.md b/docs/fr/404.md deleted file mode 100644 index f15f792d3b..0000000000 --- a/docs/fr/404.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -title: Page introuvable -template: splash ---- - -La page que vous recherchez n’existe pas ou a été déplacée. - -[Retour à l’accueil](/fr/index.md) diff --git a/docs/fr/_STYLE_GUIDE.md b/docs/fr/_STYLE_GUIDE.md deleted file mode 100644 index 5aae8e57ae..0000000000 --- a/docs/fr/_STYLE_GUIDE.md +++ /dev/null @@ -1,372 +0,0 @@ ---- -title: "Guide de style de la documentation" -description: Conventions de documentation spécifiques au projet, basées sur le style Google et la structure Diataxis ---- - -Ce projet suit le [Guide de style de documentation pour développeurs Google](https://developers.google.com/style) et utilise [Diataxis](https://diataxis.fr/) pour structurer le contenu. Seules les conventions spécifiques au projet sont présentées ci-dessous. - -## Règles spécifiques au projet - -| Règle | Spécification | -|--------------------------------------------|--------------------------------------------------------| -| Pas de règles horizontales (`---`) | Perturbe le flux de lecture des fragments | -| Pas de titres `####` | Utiliser du texte en gras ou des admonitions | -| Pas de sections « Related » ou « Next » | La barre latérale gère la navigation | -| Pas de listes profondément imbriquées | Diviser en sections à la place | -| Pas de blocs de code pour non-code | Utiliser des admonitions pour les exemples de dialogue | -| Pas de paragraphes en gras pour les appels | Utiliser des admonitions à la place | -| 1-2 admonitions max par section | Les tutoriels permettent 3-4 par section majeure | -| Cellules de tableau / éléments de liste | 1-2 phrases maximum | -| Budget de titres | 8-12 `##` par doc ; 2-3 `###` par section | - -## Admonitions (Syntaxe Starlight) - -```md -:::tip[Titre] -Raccourcis, bonnes pratiques -::: - -:::note[Titre] -Contexte, définitions, exemples, prérequis -::: - -:::caution[Titre] -Mises en garde, problèmes potentiels -::: - -:::danger[Titre] -Avertissements critiques uniquement — perte de données, problèmes de sécurité -::: -``` - -### Utilisations standards - -| Admonition | Usage | -|-------------------------|----------------------------------| -| `:::note[Pré-requis]` | Dépendances avant de commencer | -| `:::tip[Chemin rapide]` | Résumé TL;DR en haut du document | -| `:::caution[Important]` | Mises en garde critiques | -| `:::note[Exemple]` | Exemples de commandes/réponses | - -## Formats de tableau standards - -**Phases :** - -```md -| Phase | Nom | Ce qui se passe | -|-------|---------------|-------------------------------------------------------| -| 1 | Analyse | Brainstorm, recherche *(optionnel)* | -| 2 | Planification | Exigences — PRD ou spécification technique *(requis)* | -``` - -**Skills :** - -```md -| Skill | Agent | Objectif | -|----------------------|----------|---------------------------------------| -| `bmad-brainstorming` | Analyste | Brainstorming pour un nouveau projet | -| `bmad-prd` | PM | Créer un document d'exigences produit | -``` - -## Blocs de structure de dossiers - -À afficher dans les sections « Ce que vous avez accompli » : - -````md -``` -votre-projet/ -├── _bmad/ # Configuration BMad -├── _bmad-output/ -│ ├── planning-artifacts/ -│ │ └── PRD.md # Votre document d’exigences -│ ├── implementation-artifacts/ -│ └── project-context.md # Règles d’implémentation (optionnel) -└── ... -``` -```` - -## Structure des tutoriels - -```text -1. Titre + Accroche (1-2 phrases décrivant le résultat) -2. Notice de version/module (admonition info ou avertissement) (optionnel) -3. Ce que vous allez apprendre (liste à puces des résultats) -4. Prérequis (admonition info) -5. Chemin rapide (admonition tip - résumé TL;DR) -6. Comprendre [Sujet] (contexte avant les étapes - tableaux pour phases/agents) -7. Installation (optionnel) -8. Étape 1 : [Première tâche majeure] -9. Étape 2 : [Deuxième tâche majeure] -10. Étape 3 : [Troisième tâche majeure] -11. Ce que vous avez accompli (résumé + structure de dossiers) -12. Référence rapide (tableau des compétences) -13. Questions courantes (format FAQ) -14. Obtenir de l'aide (liens communautaires) -15. Points clés à retenir (admonition tip) -``` - -### Liste de vérification des tutoriels - -- [ ] L’accroche décrit le résultat en 1-2 phrases -- [ ] Section « Ce que vous allez apprendre » présente -- [ ] Prérequis dans une admonition -- [ ] Admonition TL;DR de chemin rapide en haut -- [ ] Tableaux pour phases, skills, agents -- [ ] Section « Ce que vous avez accompli » présente -- [ ] Tableau de référence rapide présent -- [ ] Section questions courantes présente -- [ ] Section obtenir de l’aide présente -- [ ] Admonition points clés à retenir à la fin - -## Structure des guides pratiques (How-To) - -```text -1. Titre + Accroche (une phrase : « Utilisez le workflow `X` pour... ») -2. Quand utiliser ce guide (liste à puces de scénarios) -3. Quand éviter ce guide (optionnel) -4. Prérequis (admonition note) -5. Étapes (sous-sections ### numérotées) -6. Ce que vous obtenez (produits de sortie/artefacts) -7. Exemple (optionnel) -8. Conseils (optionnel) -9. Prochaines étapes (optionnel) -``` - -### Liste de vérification des guides pratiques - -- [ ] L’accroche commence par « Utilisez le workflow `X` pour... » -- [ ] « Quand utiliser ce guide » contient 3-5 points -- [ ] Prérequis listés -- [ ] Les étapes sont des sous-sections `###` numérotées avec des verbes d’action -- [ ] « Ce que vous obtenez » décrit les artefacts produits - -## Structure des explications - -### Types - -| Type | Exemple | -|--------------------------|-------------------------------| -| **Index/Page d’accueil** | `core-concepts/index.md` | -| **Concept** | `what-are-agents.md` | -| **Fonctionnalité** | `build.md` | -| **Philosophie** | `why-solutioning-matters.md` | -| **FAQ** | `established-projects-faq.md` | - -### Modèle général - -```text -1. Titre + Accroche (1-2 phrases) -2. Vue d'ensemble/Définition (ce que c'est, pourquoi c'est important) -3. Concepts clés (sous-sections ###) -4. Tableau comparatif (optionnel) -5. Quand utiliser / Quand ne pas utiliser (optionnel) -6. Diagramme (optionnel - mermaid, 1 max par doc) -7. Prochaines étapes (optionnel) -``` - -### Pages d’index/d’accueil - -```text -1. Titre + Accroche (une phrase) -2. Tableau de contenu (liens avec descriptions) -3. Pour commencer (liste numérotée) -4. Choisissez votre parcours (optionnel - arbre de décision) -``` - -### Explications de concepts - -```text -1. Titre + Accroche (ce que c'est) -2. Types/Catégories (sous-sections ###) (optionnel) -3. Tableau des différences clés -4. Composants/Parties -5. Lequel devriez-vous utiliser ? -6. Création/Personnalisation (lien vers les guides pratiques) -``` - -### Explications de fonctionnalités - -```text -1. Titre + Accroche (ce que cela fait) -2. Faits rapides (optionnel - "Idéal pour :", "Temps :") -3. Quand utiliser / Quand ne pas utiliser -4. Comment cela fonctionne (diagramme mermaid optionnel) -5. Avantages clés -6. Tableau comparatif (optionnel) -7. Quand évoluer/mettre à niveau (optionnel) -``` - -### Documents de philosophie/justification - -```text -1. Titre + Accroche (le principe) -2. Le problème -3. La solution -4. Principes clés (sous-sections ###) -5. Avantages -6. Quand cela s'applique -``` - -### Liste de vérification des explications - -- [ ] L’accroche énonce ce que le document explique -- [ ] Contenu dans des sections `##` parcourables -- [ ] Tableaux comparatifs pour 3+ options -- [ ] Les diagrammes ont des étiquettes claires -- [ ] Liens vers les guides pratiques pour les questions procédurales -- [ ] 2-3 admonitions max par document - -## Structure des références - -### Types - -| Type | Exemple | -|--------------------------|-----------------------| -| **Index/Page d’accueil** | `workflows/index.md` | -| **Catalogue** | `agents/index.md` | -| **Approfondissement** | `document-project.md` | -| **Configuration** | `core-tasks.md` | -| **Glossaire** | `glossary/index.md` | -| **Complet** | `bmgd-workflows.md` | - -### Pages d’index de référence - -```text -1. Titre + Accroche (une phrase) -2. Sections de contenu (## pour chaque catégorie) - - Liste à puces avec liens et descriptions -``` - -### Référence de catalogue - -```text -1. Titre + Accroche -2. Éléments (## pour chaque élément) - - Brève description (une phrase) - - **Skills :** ou **Infos clés :** sous forme de liste simple -3. Universel/Partagé (## section) (optionnel) -``` - -### Référence d’approfondissement d’élément - -```text -1. Titre + Accroche (objectif en une phrase) -2. Faits rapides (admonition note optionnelle) - - Module, Skill, Entrée, Sortie sous forme de liste -3. Objectif/Vue d'ensemble (## section) -4. Comment invoquer (bloc de code) -5. Sections clés (## pour chaque aspect) - - Utiliser ### pour les sous-options -6. Notes/Mises en garde (admonition tip ou caution) -``` - -### Référence de configuration - -```text -1. Titre + Accroche -2. Table des matières (liens de saut si 4+ éléments) -3. Éléments (## pour chaque config/tâche) - - **Résumé en gras** — une phrase - - **Utilisez-le quand :** liste à puces - - **Comment cela fonctionne :** étapes numérotées (3-5 max) - - **Sortie :** résultat attendu (optionnel) -``` - -### Guide de référence complet - -```text -1. Titre + Accroche -2. Vue d'ensemble (## section) - - Diagramme ou tableau montrant l'organisation -3. Sections majeures (## pour chaque phase/catégorie) - - Éléments (### pour chaque élément) - - Champs standardisés : Skill, Agent, Entrée, Sortie, Description -4. Prochaines étapes (optionnel) -``` - -### Liste de vérification des références - -- [ ] L’accroche énonce ce que le document référence -- [ ] La structure correspond au type de référence -- [ ] Les éléments utilisent une structure cohérente -- [ ] Tableaux pour les données structurées/comparatives -- [ ] Liens vers les documents d’explication pour la profondeur conceptuelle -- [ ] 1-2 admonitions max - -## Structure du glossaire - -Starlight génère la navigation « Sur cette page » à droite à partir des titres : - -- Catégories en tant que titres `##` — apparaissent dans la navigation à droite -- Termes dans des tableaux — lignes compactes, pas de titres individuels -- Pas de TOC en ligne — la barre latérale à droite gère la navigation - -### Format de tableau - - -```md -## Nom de catégorie - -| Terme | Définition | -|--------------|------------------------------------------------------------------------------------------------------------| -| **Agent** | Personnalité IA spécialisée avec une expertise spécifique qui guide les utilisateurs dans les workflows. | -| **Workflow** | Processus guidé en plusieurs étapes qui orchestre les activités des agents IA pour produire des livrables. | -``` - -### Règles de définition - -| À faire | À ne pas faire | -|------------------------------------------------|-----------------------------------------------------| -| Commencer par ce que c’est ou ce que cela fait | Commencer par « C’est... » ou « Un [terme] est... » | -| Se limiter à 1-2 phrases | Écrire des explications de plusieurs paragraphes | -| Mettre le nom du terme en gras dans la cellule | Utiliser du texte simple pour les termes | - -### Marqueurs de contexte - -Ajouter un contexte en italique au début de la définition pour les termes à portée limitée : - -- `*Implémentation en entrée directe uniquement.*` -- `*méthode BMad/Enterprise.*` -- `*Phase N.*` -- `*BMGD.*` -- `*Projets établis.*` - -### Liste de vérification du glossaire - -- [ ] Termes dans des tableaux, pas de titres individuels -- [ ] Termes alphabétisés au sein des catégories -- [ ] Définitions de 1-2 phrases -- [ ] Marqueurs de contexte en italique -- [ ] Noms des termes en gras dans les cellules -- [ ] Pas de définitions « Un [terme] est... » - -## Sections FAQ - -```md -## Questions - -- [Ai-je toujours besoin d'architecture ?](#ai-je-toujours-besoin-darchitecture) -- [Puis-je modifier mon plan plus tard ?](#puis-je-modifier-mon-plan-plus-tard) - -### Ai-je toujours besoin d'architecture ? - -Uniquement pour les travaux qui bénéficient d'une architecture. Un travail clair peut entrer directement dans l'implémentation. - -### Puis-je modifier mon plan plus tard ? - -Oui. Utilisez `bmad-correct-course` pour gérer les changements de portée en cours d’implémentation. - -**Une question sans réponse ici ?** [Ouvrez une issue](...) ou posez votre question sur [Discord](...). -``` - -## Commandes de validation - -Avant de soumettre des modifications de documentation : - -```bash -cd docs-site -npm run fix-links # Prévisualiser les corrections de format de liens -npm run fix-links -- --write # Appliquer les corrections -npm run validate-links # Vérifier que les liens existent -npm run build # Vérifier l'absence d'erreurs de build -``` diff --git a/docs/fr/build/walk-through-a-change.md b/docs/fr/build/walk-through-a-change.md deleted file mode 100644 index 0afe2be894..0000000000 --- a/docs/fr/build/walk-through-a-change.md +++ /dev/null @@ -1,92 +0,0 @@ ---- -title: "Parcourir un changement" -description: Revue assistée par LLM, avec intervention humaine, qui vous guide à travers une modification, de son objectif jusqu’aux détails -sidebar: - order: 1 ---- - -`bmad-walkthrough` est un workflow de revue interactif, assisté par LLM, avec intervention humaine. Il vous guide à travers une modification de code — de l’intention et du contexte jusqu’aux détails — afin que vous puissiez prendre une décision éclairée sur la mise en production, la refonte ou l’approfondissement. - -![Diagramme du workflow Walkthrough](/diagrams/walkthrough-run.svg) - -## Le Flux Typique - -Vous lancez `bmad-build`. Il clarifie votre intention, construit une spécification, implémente la modification, et une fois terminé, il ajoute un historique de revue au fichier de spécification et l’ouvre dans votre éditeur. Vous regardez la spec et constatez que la modification a touché 20 fichiers dans plusieurs modules. - -Vous pourriez survoler le diff. Mais 20 fichiers, c’est le moment où le survol commence à échouer — on perd le fil, on rate un lien entre deux modifications éloignées, ou on approuve quelque chose qu’on n’a pas pleinement compris. Alors au lieu de cela, vous dites « walkthrough » et le LLM vous guide à travers la modification. - -Ce passage de relais — de l’implémentation autonome au jugement humain — est le cas d’usage principal. Build s’exécute longtemps avec une supervision minimale. Le Walkthrough, c’est là où vous reprenez le volant. - -## Pourquoi - -La revue de code a deux modes d’échec. Dans le premier, le réviseur survole le diff, rien ne saute aux yeux, et il approuve. Dans le second, il lit méthodiquement chaque fichier mais perd le fil — il voit les arbres et rate la forêt. Les deux aboutissent au même résultat : la revue n’a pas repéré ce qui comptait. - -Le problème sous-jacent est le séquençage. Un diff brut présente les modifications dans l’ordre des fichiers, ce qui est presque jamais l’ordre qui construit la compréhension. Vous voyez une fonction utilitaire avant de savoir pourquoi elle existe. Vous voyez une modification de schéma avant de comprendre quelle fonctionnalité elle supporte. Le réviseur doit reconstruire l’intention de l’auteur à partir d’indices dispersés, et c’est cette reconstruction qui fait défaut à l’attention. - -Le Walkthrough résout ce problème en confiant le travail de reconstruction au LLM. Il lit le diff, la spécification (si elle existe) et la base de code environnante, puis présente la modification dans un ordre conçu pour la compréhension — et non pour `git diff`. - -## Comment ça fonctionne - -Le workflow comporte cinq étapes. Chaque étape s’appuie sur la précédente, passant progressivement de « qu’est-ce que c’est ? » à « devons-nous publier ça ? » - -### 1. Orientation - -Le workflow identifie la modification (à partir d’une PR, d’un commit, d’une branche, d’un fichier de spécification ou de l’état git actuel) et produit un résumé d’intention en une ligne ainsi que des statistiques de surface : fichiers modifiés, modules touchés, lignes de logique, dépassements de boundaries et nouvelles interfaces publiques. - -C’est le moment « est-ce bien ce que je crois ? ». Avant de lire le moindre code, le réviseur confirme qu’il regarde la bonne chose et calibre ses attentes quant à la portée. - -### 2. Visite guidée - -La modification est organisée par **préoccupation** — des intentions de conception cohérentes comme « validation des entrées » ou « contrat d’API » — et non par fichier. Chaque préoccupation fait l’objet d’une courte explication du *pourquoi* de cette approche, suivie d’arrêts cliquables `chemin:ligne` que le réviseur peut suivre dans le code. - -C’est l’étape du jugement de conception. Le réviseur évalue si l’approche est adaptée au système, et non si le code est correct. Les préoccupations sont séquencées de haut en bas : l’intention de plus haut niveau en premier, puis l’implémentation de support. Le réviseur ne rencontre jamais une référence à quelque chose qu’il n’a pas encore vu. - -### 3. Passage en revue des détails - -Une fois que le réviseur comprend la conception, le workflow met en évidence 2 à 5 endroits où une erreur aurait l’impact le plus important. Ceux-ci sont étiquetés par catégorie de risque — `[auth]`, `[schéma]`, `[facturation]`, `[API publique]`, `[sécurité]`, et d’autres — et ordonnés selon l’impact en cas d’erreur. - -Ce n’est pas une chasse aux bugs. Les tests automatisés et la CI gèrent la correction. Le passage en revue des détails active la conscience du risque : « voici les endroits où se tromper coûte le plus cher ». Si le réviseur veut approfondir un domaine spécifique, il peut dire « approfondis [domaine] » pour une re-revue ciblée axée sur la correction. - -Si la spécification a passé des boucles de revues contradictoires (machine hardening), ces résultats sont également présentés ici — pas les bugs qui ont été corrigés, mais les décisions que la boucle de revue a signalées et dont le réviseur devrait être conscient. - -### 4. Tests - -Propose 2 à 5 façons d’observer manuellement la modification en action. Pas des commandes de test automatisé — des observations manuelles qui renforcent la confiance au-delà de ce que toute suite de tests peut fournir. Une interaction UI à essayer, une commande CLI à lancer, une requête API à envoyer, avec les résultats attendus pour chacune. - -Si la modification n’a aucun comportement visible par l’utilisateur, il le dit. Pas de travail inventé. - -### 5. Conclusion - -Le réviseur prend la décision : approuver, retravailler ou continuer la discussion. S’il approuve une PR, le workflow peut aider avec `gh pr review --approve`. S’il demande une refonte, il aide à diagnostiquer si le problème vient de l’approche, de la spécification ou de l’implémentation, et aide à rédiger un retour actionnable lié à des emplacements de code spécifiques. - -## C’est une conversation, pas un rapport - -Le workflow présente chaque étape comme un point de départ, pas un mot final. Entre les étapes — ou au milieu d’une — vous pouvez parler au LLM, poser des questions, remettre en question son cadrage ou faire appel à d’autres skills pour obtenir une perspective différente : - -- **« lance l’élicitation avancée sur la gestion des erreurs »** — pousse le LLM à reconsidérer et affiner son analyse d’un domaine spécifique -- **« active le party mode sur la sécurité de cette migration de schéma »** — fait intervenir plusieurs perspectives agentiques dans un débat ciblé -- **« lance la revue de code »** — génère des résultats structurés avec analyse adversariale et cas limites - -Le workflow Walkthrough ne vous enferme pas dans un chemin linéaire. Il vous donne de la structure quand vous la souhaitez et s’efface quand vous voulez explorer. Les cinq étapes sont là pour s’assurer que vous voyez le tableau complet, mais la profondeur à laquelle vous allez à chaque étape — et les outils que vous y apportez — est entièrement entre vos mains. - -## L’historique de revue - -L’étape de visite guidée fonctionne mieux lorsqu’elle dispose d’un **ordre de revue suggéré** — une liste d’arrêts que l’auteur de la spécification a rédigée pour guider les réviseurs à travers la modification. Lorsqu’une spécification inclut cet ordre, le workflow l’utilise directement. - -Lorsqu’aucun historique produit par l’auteur n’existe, le workflow en génère un à partir du diff et du contexte de la base de code. Un historique généré est de qualité inférieure à un historique produit par l’auteur, mais nettement supérieur à la lecture des modifications dans l’ordre des fichiers. - -## Quand l’utiliser - -Le scénario principal est le passage de relais depuis `bmad-build` : l’implémentation est terminée, le fichier de spécification est ouvert dans votre éditeur avec un historique de revue ajouté, et vous devez décider si vous publiez. Dites « walkthrough » et c’est parti. - -Il fonctionne aussi de manière autonome : - -- **Revue d’une PR** — surtout celles avec plus de quelques fichiers ou des modifications transversales -- **Prise en main d’une modification** — quand vous devez comprendre ce qui s’est passé sur une branche que vous n’avez pas écrite -- **Revue de sprint** — le workflow peut récupérer les stories marquées `review` dans votre fichier de statut de sprint - -Invoquez-le en disant « walkthrough » ou « guide-moi à travers cette modification ». Il fonctionne dans n’importe quel terminal, mais vous en tirerez plus de parti dans un IDE — VS Code, Cursor ou similaire — car le workflow produit des références `chemin:ligne` à chaque étape. Dans un terminal intégré à un IDE, celles-ci sont cliquables, ce qui vous permet de sauter de fichier en fichier en suivant l’historique de revue. - -## Ce que ce n’est pas - -Le Walkthrough ne remplace pas la revue automatisée. Il ne lance pas de linters, de vérificateurs de types ou de suites de tests. Il n’attribue pas de scores de sévérité et ne produit pas de verdicts pass/échec. C’est un guide de lecture qui aide un humain à appliquer son jugement là où cela compte le plus. diff --git a/docs/fr/explanation/advanced-elicitation.md b/docs/fr/explanation/advanced-elicitation.md deleted file mode 100644 index d079e36dff..0000000000 --- a/docs/fr/explanation/advanced-elicitation.md +++ /dev/null @@ -1,49 +0,0 @@ ---- -title: "Élicitation Avancée" -description: Pousser le LLM à repenser son travail en utilisant des méthodes de raisonnement structurées -sidebar: - order: 4 ---- - -Faites repenser au LLM ce qu’il vient de générer. Vous choisissez une méthode de raisonnement, il l’applique à sa propre sortie, et vous décidez de conserver ou non les améliorations. - -## Qu’est-ce que l’Élicitation Avancée ? - -Un second passage structuré. Au lieu de demander à l’IA de « réessayer » ou de « faire mieux », vous sélectionnez une méthode de raisonnement spécifique et l’IA réexamine sa propre sortie à travers ce prisme. - -La différence est importante. Les demandes vagues produisent des révisions vagues. Une méthode nommée impose un angle d’attaque particulier, mettant en lumière des perspectives qu’un simple réajustement générique aurait manquées. - -## Quand l’utiliser - -- Après qu’un workflow a généré du contenu et vous souhaitez des alternatives -- Lorsque la sortie semble correcte mais que vous soupçonnez qu’il y a davantage de profondeur -- Pour tester les hypothèses ou trouver des faiblesses -- Pour du contenu à enjeux élevés où la réflexion approfondie aide - -Les workflows offrent l’élicitation aux points de décision - après que le LLM ait généré quelque chose, on vous demandera si vous souhaitez l’exécuter. - -## Comment ça fonctionne - -1. Le LLM suggère 5 méthodes pertinentes pour votre contenu -2. Vous en choisissez une (ou remélangez pour différentes options) -3. La méthode est appliquée, les améliorations sont affichées -4. Acceptez ou rejetez, répétez ou continuez - -## Méthodes intégrées - -Des dizaines de méthodes de raisonnement sont disponibles. Quelques exemples : - -- **Analyse Pré-mortem** - Suppose que le projet a déjà échoué, revient en arrière pour trouver pourquoi -- **Pensée de Premier Principe** - Élimine les hypothèses, reconstruit à partir de la vérité de terrain -- **Inversion** - Demande comment garantir l’échec, puis les évite -- **Équipe Rouge vs Équipe Bleue** - Attaque votre propre travail, puis le défend -- **Questionnement Socratique** - Conteste chaque affirmation avec « pourquoi ? » et « comment le savez-vous ? » -- **Suppression des Contraintes** - Abandonne toutes les contraintes, voit ce qui change, les réajoute sélectivement -- **Cartographie des Parties Prenantes** - Réévalue depuis la perspective de chaque partie prenante -- **Raisonnement Analogique** - Trouve des parallèles dans d’autres domaines et applique leurs leçons - -Et bien d’autres. L’IA choisit les options les plus pertinentes pour votre contenu - vous choisissez lesquelles exécuter. - -:::tip[Commencez Ici] -L’Analyse Pré-mortem est un bon premier choix pour toute spécification ou tout plan. Elle trouve systématiquement des lacunes qu’une révision standard manque. -::: diff --git a/docs/fr/explanation/analysis-phase.md b/docs/fr/explanation/analysis-phase.md deleted file mode 100644 index 06d6af3a7b..0000000000 --- a/docs/fr/explanation/analysis-phase.md +++ /dev/null @@ -1,74 +0,0 @@ ---- -title: "Phase d’analyse : de l’Idée aux Fondations" -description: Ce que sont le brainstorming, la recherche, les product briefs et les PRFAQs — et quand les utiliser -sidebar: - order: 2 ---- - -La phase d’Analyse (Phase 1) vous aide à penser clairement à votre produit avant de vous engager à le construire. Chaque outil de cette phase est optionnel, mais sauter l’analyse entièrement signifie que votre PRD sera construit sur des suppositions plutôt que sur des connaissances approfondies. - -## Pourquoi Analyser avant de Planifier ? - -Un PRD répond à la question « que devons-nous construire et pourquoi ? » Si vous l’alimentez avec une réflexion vague, vous obtiendrez un PRD vague — et chaque document en aval héritera de cette imprécision. Une architecture bâtie sur un PRD faible prend de mauvaises décisions techniques. Les stories dérivées d’une architecture faible manquent de edge cases. Le coût s’accumule. - -Les outils d’analyse existent pour rendre votre PRD précis. Ils attaquent le problème sous différents angles — exploration créative, réalité du marché, clarté client, faisabilité — pour qu’au moment de vous asseoir avec l’agent PM, vous sachiez ce que vous construisez et pour qui. - -## Les Outils - -### Brainstorming - -**Quoi.** Une session créative facilitée utilisant des techniques d’idéation éprouvées. L’IA agit comme coach, extrayant vos idées à travers des exercices structurés — pas en les générant pour vous. - -**Pourquoi.** Les idées brutes ont besoin d’espace pour se développer avant d’être verrouillées dans des exigences. Le brainstorming crée cet espace. Il est particulièrement précieux quand vous avez un espace-problème mais pas de solution claire, ou quand vous voulez explorer plusieurs pistes avant de vous engager. - -**Quand.** Vous avez une vague idée de ce que vous voulez construire mais n’avez pas encore cristallisé le concept. Ou vous avez un concept mais voulez l’éprouver face à des alternatives. - -Voir [Brainstorming](./brainstorming.md) pour un aperçu plus approfondi du fonctionnement des sessions. - -### Recherche (Marché, Domaine, Technique) - -**Quoi.** Trois workflows de recherche ciblés qui investiguent différentes dimensions de votre idée. La recherche marché examine les concurrents, les tendances et le sentiment utilisateur. La recherche domaine construit l’expertise métier et la terminologie. La recherche technique évalue la faisabilité, les options d’architecture et les approches d’implémentation. - -**Pourquoi.** Construire sur des suppositions est le moyen le plus rapide de construire quelque chose dont personne n’a besoin. La recherche ancre votre concept dans la réalité — quels concurrents existent déjà, avec quoi les utilisateurs luttent réellement, ce qui est techniquement faisable, et quelles contraintes spécifiques à l’industrie vous affronterez. - -**Quand.** Vous entrez dans un domaine inconnu, vous soupçonnez que des concurrents existent mais ne les avez pas cartographiés, ou votre concept dépend de capacités techniques que vous n’avez pas validées. Lancez-en un, deux ou les trois — chaque workflow de recherche fonctionne de manière autonome. - -### Product Brief[^1] - -**Quoi.** Une session de découverte guidée qui produit un résumé exécutif de 1-2 pages de votre concept produit. L’IA agit comme un analyste commercial collaboratif, vous aidant à articuler la vision, le public cible, la proposition de valeur et le périmètre. - -**Pourquoi.** Le product brief est le chemin le plus doux vers la planification. Il capture votre vision stratégique dans un format structuré qui alimente directement la création du PRD. Il fonctionne mieux quand vous avez déjà la conviction à propos de votre concept — vous connaissez le client, le problème et approximativement ce que vous voulez construire. Le brief organise et affine cette réflexion. - -**Quand.** Votre concept est relativement clair et vous voulez le documenter efficacement avant de créer un PRD. Vous êtes confiant dans la direction et n’avez pas besoin que vos suppositions soient agressivement remises en question. - -### PRFAQ (Working Backwards) - -**Quoi.** La méthodologie Working Backwards d’Amazon adaptée en défi interactif. Vous rédigez le communiqué de presse annonçant votre produit fini avant qu’une seule ligne de code n’existe, puis répondez aux questions les plus difficiles que les clients et les parties prenantes poseraient. L’IA agit comme un coach produit implacable mais constructif. - -**Pourquoi.** Le PRFAQ est le chemin rigoureux vers la planification. Il force la clarté orientée client en vous obligeant à défendre chaque affirmation. Si vous ne pouvez pas rédiger un communiqué de presse convaincant, le produit n’est pas prêt. Si les réponses de la FAQ client révèlent des lacunes, ce sont des lacunes que vous découvrirez bien plus tard — et plus coûteusement — pendant l’implémentation. Le défi fait remonter les failles de réflexion tôt, quand c’est le moins cher de les corriger. - -**Quand.** Vous voulez que votre concept soit éprouvé avant d’engager des ressources. Vous n’êtes pas sûr que les utilisateurs s’en soucieront réellement. Vous voulez valider que vous pouvez articuler une proposition de valeur claire et défendable. Ou vous voulez simplement la discipline du Working Backwards pour affiner votre réflexion. - -## Lequel utiliser ? - -| Situation | Outil recommandé | -|-------------------------------------------------------------------------------|--------------------------------------------| -| « J’ai une idée vague, je ne sais pas par où commencer » | Brainstorming | -| « J’ai besoin de comprendre le marché avant de décider » | Recherche | -| « Je sais ce que je veux construire, j’ai juste besoin de le documenter » | Product Brief | -| « Je veux m’assurer que cette idée vaut vraiment la peine d’être construite » | PRFAQ | -| « Je veux explorer, puis valider, puis documenter » | Brainstorming → Recherche → PRFAQ ou Brief | - -Le Product Brief et le PRFAQ produisent tous deux des entrées pour le PRD — choisissez-en un en fonction du niveau de défi que vous souhaitez. Le brief est une découverte collaborative. Le PRFAQ est un défi. Les deux vous mènent à la même destination ; le PRFAQ teste si votre concept mérite d’y arriver. - -:::tip[Pas sûr ?] -Exécutez `bmad-help` et décrivez votre situation. Il vous recommandera le bon point de départ en fonction de ce que vous avez déjà accompli et de ce que vous essayez de réaliser. -::: - -## Que se passe-t-il après l’analyse ? - -Les résultats de l’analyse alimentent directement la Phase 2 (Planification). Le workflow PRD accepte les product briefs, les documents PRFAQ, les conclusions de recherche et les rapports de brainstorming en entrée — il synthétise tout ce que vous avez produit en exigences structurées. Plus vous faites d’analyse, plus votre PRD sera précis. - -## Glossaire - -[^1]: Brief : document synthétique qui formalise le contexte, les objectifs, le périmètre et les contraintes d’un projet ou d’une demande, afin d’aligner rapidement les parties prenantes avant le travail détaillé. diff --git a/docs/fr/explanation/brainstorming.md b/docs/fr/explanation/brainstorming.md deleted file mode 100644 index 0ef16147a4..0000000000 --- a/docs/fr/explanation/brainstorming.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -title: "Brainstorming" -description: Sessions interactives créatives utilisant plus de 60 techniques d’idéation éprouvées -sidebar: - order: 3 ---- - -Libérez votre créativité grâce à une exploration guidée. - -## Qu’est-ce que le Brainstorming ? - -Lancez `bmad-brainstorming` et vous obtenez un facilitateur créatif qui fait émerger vos idées - pas qui les génère pour vous. L’IA agit comme coach et guide, utilisant des techniques éprouvées pour créer les conditions où votre meilleure réflexion émerge. - -**Idéal pour :** - -- Surmonter les blocages créatifs -- Générer des idées de produits ou de fonctionnalités -- Explorer des problèmes sous de nouveaux angles -- Développer des concepts bruts en plans d’action - -## Comment ça fonctionne - -1. **Configuration** - Définir le sujet, les objectifs, les contraintes -2. **Choisir l’approche** - Choisir vous-même les techniques, obtenir des recommandations de l’IA, aller au hasard, ou suivre un flux progressif -3. **Facilitation** - Travailler à travers les techniques avec des questions approfondies et un coaching collaboratif -4. **Organiser** - Idées regroupées par thèmes et priorisées -5. **Action** - Les meilleures idées reçoivent des prochaines étapes et des indicateurs de succès - -Tout est capturé dans un document de session que vous pouvez consulter ultérieurement ou partager avec les parties prenantes. - -:::note[Vos Idées] -Chaque idée vient de vous. Le workflow crée les conditions propices à une vision nouvelle - vous en êtes la source. -::: diff --git a/docs/fr/explanation/build.md b/docs/fr/explanation/build.md deleted file mode 100644 index 6c08b39caa..0000000000 --- a/docs/fr/explanation/build.md +++ /dev/null @@ -1,83 +0,0 @@ ---- -title: "Build" -description: Réduire la friction de l’interaction humaine sans renoncer aux points de contrôle qui protègent la qualité des résultats -sidebar: - order: 7 ---- - -`bmad-build` est le workflow d’implémentation standard pour tout travail de développement. Il accepte aussi bien une intention libre ou une issue qu’une story entièrement planifiée, et produit des modifications de code avec le minimum d’interventions humaines compatible avec la sécurité. - -La planification amont reste optionnelle et variable. Un changement clair peut entrer directement ; une initiative plus vaste peut apporter PRD, UX, architecture, epics, stories, contrôle de préparation et plan de sprint. Ces artefacts renforcent le contexte sans sélectionner un autre workflow de développement. - -Lorsqu’une story planifiée entre dans Build, elle reste la source du contexte produit et des critères d’acceptation. Build crée son propre journal d’exécution pour l’exécution en cours afin de conserver la traçabilité des décisions d’implémentation et des observations de revue, sans remplacer la story. - -Il permet au modèle de s’exécuter plus longtemps entre les points de contrôle, puis ne vous fait intervenir que lorsque la tâche ne peut pas se poursuivre en toute sécurité sans jugement humain, ou lorsqu’il est temps de revoir le résultat final. - -![Le déroulé de bmad-build](/diagrams/build-run.svg) - -## Pourquoi cette fonctionnalité existe - -Les interactions humaines dans la boucle sont nécessaires et coûteuses. - -Les LLM actuels échouent encore de manière prévisible : ils interprètent mal l’intention, comblent les lacunes avec des suppositions assurées, dérivent vers du travail non lié, et génèrent des résultats à réviser bruyants. En même temps, l’intervention humaine constante limite la fluidité du développement. L’attention humaine est le goulot d’étranglement. - -`bmad-build` rééquilibre ce compromis. Il fait confiance au modèle pour s’exécuter sans surveillance sur de plus longues périodes, mais seulement après que le workflow ait créé une frontière suffisamment solide pour rendre cela sûr. - -## La conception fondamentale - -### 1. Compresser l’intention d’abord - -Le workflow commence par compresser l’interaction de la personne et du modèle à partir de la requête en un objectif cohérent. L’entrée peut commencer sous forme d’une expression grossière de l’intention, mais avant que le workflow ne s’exécute de manière autonome, elle doit devenir suffisamment petite, claire et sans contradiction pour être exécutable. - -L’intention peut prendre plusieurs formes : quelques phrases, un lien vers un outil de suivi de bugs, une sortie du mode planification, du texte copié depuis une session de chat ou une story planifiée issue des epics et artefacts de sprint BMad. Le workflow utilise tout le contexte amont disponible et résout les lacunes nécessaires à une implémentation sûre. - -Ce workflow n’élimine pas le contrôle humain. Il le déplace vers un nombre réduit d’étapes à forte valeur : - -- **Clarification de l’intention** - transformer une demande confuse en un objectif cohérent sans contradictions cachées -- **Approbation de la spécification** - confirmer que la compréhension figée correspond bien à ce qu’il faut construire -- **Revue du produit final** - le point de contrôle principal, où la personne décide si le résultat est acceptable à la fin - -### 2. Router vers le chemin le plus court et sûr - -Une fois l’objectif clair, le workflow décide s’il s’agit d’un véritable changement en une seule étape ou s’il nécessite le chemin complet. Les petits changements à zéro impact peuvent aller directement à l’implémentation. Tout le reste passe par la planification pour que le modèle dispose d’un cadre plus solide avant de s’exécuter plus longtemps de manière autonome. - -### 3. S’exécuter plus longtemps avec moins de supervision - -Après cette décision de routage, le modèle peut prendre en charge une plus grande partie du travail par lui-même. Sur le chemin complet, la spécification approuvée devient le cadre dans lequel le modèle s’exécute avec moins de supervision, ce qui est tout l’intérêt de la conception. - -### 4. Diagnostiquer les échecs au bon niveau - -Si l’implémentation est incorrecte parce que l’intention était mauvaise, corriger le code n’est pas la bonne solution. Si le code est incorrect parce que la spécification était faible, corriger le diff n’est pas non plus la bonne solution. Le workflow est conçu pour diagnostiquer où l’échec est entré dans le système, revenir à ce niveau, et régénérer à partir de ce point. - -Les résultats de la revue sont utilisés pour décider si le problème provenait de l’intention, de la génération de la spécification, ou de l’implémentation locale. Seuls les véritables problèmes locaux sont corrigés localement. - -### 5. Ne faire intervenir l’humain que si nécessaire - -L’entretien sur l’intention implique la personne dans la boucle, mais ce n’est pas le même type d’interruption qu’un point de contrôle récurrent. Le workflow essaie de garder ces points de contrôle récurrents au minimum. Après la mise en forme initiale de l’intention, la personne revient principalement lorsque le workflow ne peut pas continuer en toute sécurité sans jugement, et à la fin, lorsqu’il est temps de revoir le résultat. - -- **Résolution des lacunes d’intention** - intervenir à nouveau lors de la revue prouve que le workflow n’a pas pu déduire correctement ce qui était voulu - -Tout le reste est candidat à une exécution autonome plus longue. Ce compromis est délibéré. Les anciens patterns dépensent plus d’attention humaine en supervision continue. Build fait davantage confiance au modèle, mais préserve l’attention humaine pour les moments où le raisonnement humain a le plus d’impact. - -## Pourquoi le système de revue est important - -La phase de revue n’est pas seulement là pour trouver des bugs. Elle est là pour router la correction sans détruire l’élan. - -Ce workflow fonctionne mieux sur une plateforme capable de générer des sous-agents[^1], ou au moins d’invoquer un autre LLM via la ligne de commande et d’attendre un résultat. Si votre plateforme ne supporte pas cela nativement, vous pouvez ajouter un skill pour le faire. Les sous-agents sans contexte sont une pierre angulaire de la conception de la revue. - -Les revues agentiques[^2] échouent souvent de deux manières : - -- Elles génèrent trop d’observations, forçant la personne à trier le bruit. -- Elles déraillent des modifications actuelles en remontant des problèmes non liés et en transformant chaque exécution en un projet de nettoyage improvisé. - -Build aborde ces deux problèmes en traitant la revue comme un triage[^3]. - -Certaines observations concernent le changement en cours, d’autres non. Si une observation est incidente plutôt que directement liée au travail en cours, le workflow peut la différer au lieu d’obliger la personne à la traiter immédiatement. Cela permet de rester concentré sur l’exécution et d’éviter que des digressions aléatoires ne viennent épuiser le capital d’attention. - -Ce triage sera parfois imparfait. C’est acceptable. Il est généralement préférable de mal juger certaines observations plutôt que d’inonder la personne de milliers de commentaires de revue à faible valeur. Le système optimise la qualité du rapport, pas d’être exhaustif. - -## Glossaire - -[^1]: Sous-agent : agent IA secondaire créé temporairement pour effectuer une tâche spécifique (comme une revue de code) de manière isolée, sans hériter du contexte complet de l’agent principal, ce qui permet une analyse plus objective et impartiale. -[^2]: Revues agentiques (agentic review) : revue de code effectuée par un agent IA de manière autonome, capable d’analyser, d’identifier des problèmes et de formuler des recommandations sans intervention humaine directe. -[^3]: Triage : processus de filtrage et de priorisation des observations issues d’une revue, afin de distinguer les problèmes pertinents à traiter immédiatement de ceux qui peuvent être mis de côté pour plus tard. diff --git a/docs/fr/explanation/established-projects-faq.md b/docs/fr/explanation/established-projects-faq.md deleted file mode 100644 index 4df547175a..0000000000 --- a/docs/fr/explanation/established-projects-faq.md +++ /dev/null @@ -1,50 +0,0 @@ ---- -title: "FAQ Projets Existants" -description: Questions courantes sur l’utilisation de la méthode BMad sur des projets existants -sidebar: - order: 10 ---- -Réponses rapides aux questions courantes sur l’utilisation de la méthode BMad (BMM) sur des projets existants. - -## Questions - -- [Dois-je d’abord exécuter document-project ?](#dois-je-dabord-exécuter-document-project) -- [Que faire si j’oublie d’exécuter document-project ?](#que-faire-si-joublie-dexécuter-document-project) -- [Comment fonctionne l’implémentation dans les projets existants ?](#comment-fonctionne-limplémentation-dans-les-projets-existants) -- [Que faire si mon code existant ne suit pas les bonnes pratiques ?](#que-faire-si-mon-code-existant-ne-suit-pas-les-bonnes-pratiques) - -### Dois-je d’abord exécuter `document-project` ? - -Hautement recommandé, surtout si : - -- Aucune documentation existante -- La documentation est obsolète -- Les agents IA ont besoin de contexte sur le code existant - -Vous pouvez l’ignorer si vous disposez d’une documentation complète et à jour incluant `docs/index.md` ou si vous utiliserez d’autres outils ou techniques pour aider à la découverte afin que l’agent puisse construire sur un système existant. - -### Que faire si j’oublie d’exécuter `document-project` ? - -Ne vous inquiétez pas — vous pouvez le faire à tout moment. Vous pouvez même le faire pendant ou après un projet pour aider à maintenir la documentation à jour. - -### Comment fonctionne l’implémentation dans les projets existants ? - -Exécutez `bmad-build`, comme pour un nouveau développement. Le workflow va : - -- Détecter automatiquement votre pile technologique existante -- Analyser les patterns de code existants -- Détecter les conventions et demander confirmation -- Générer une spécification technique riche en contexte qui respecte le code existant - -Vous pouvez entrer directement pour une modification claire ou fournir une story planifiée et ses artefacts amont pour un travail plus vaste. - -### Que faire si mon code existant ne suit pas les bonnes pratiques ? - -Build détecte vos conventions et demande : « Dois-je suivre ces conventions existantes ? » Vous décidez : - -- **Oui** → Maintenir la cohérence avec la base de code actuelle -- **Non** → Établir de nouvelles normes (documenter pourquoi dans la spécification technique) - -BMM respecte votre choix — il ne forcera pas la modernisation, mais la proposera. - -**Une question sans réponse ici ?** Veuillez [ouvrir un ticket](https://github.com/bmad-code-org/BMAD-METHOD/issues) ou poser votre question sur [Discord](https://discord.gg/gk8jAdXWmj) afin que nous puissions l’ajouter ! diff --git a/docs/fr/explanation/named-agents.md b/docs/fr/explanation/named-agents.md deleted file mode 100644 index b98f3f46fd..0000000000 --- a/docs/fr/explanation/named-agents.md +++ /dev/null @@ -1,97 +0,0 @@ ---- -title: "Agents nommés" -description: Pourquoi les agents BMad ont des noms, des personas et des options de personnalisation — et ce que cela permet par rapport aux alternatives basées sur des menus ou des prompts -sidebar: - order: 1 ---- - -Vous dites « Hey Mary, brainstormons » et Mary s’active. Elle vous salue par votre nom, dans la langue que vous avez configurée, avec son persona distinctif. Elle vous rappelle que `bmad-help` est toujours disponible. Puis elle saute le menu et se lance directement dans le brainstorming — parce que votre intention était claire. - -Cette page explique ce qui se passe réellement et pourquoi BMad est conçu ainsi. - -## Le tabouret à trois pieds - -Le modèle d’agent de BMad repose sur trois primitives qui s’articulent : - -| Primitive | Ce qu’elle apporte | Où elle se trouve | -|----------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------| -| **Skill** | Capacité — une chose distincte que l’assistant peut faire (brainstormer, rédiger un PRD, implémenter une story) | `.claude/skills/{skill-name}/SKILL.md` (ou l’équivalent de votre IDE) | -| **Agent nommé** | Continuité du persona — une identité reconnaissable qui englobe un menu de skills associés avec une voix, des principes et des repères visuels cohérents | Skills dont le répertoire commence par `bmad-agent-*` | -| **Personnalisation** | Rendre le système vôtre — des overrides qui remodèlent le comportement d’un agent, ajoutent des intégrations MCP, remplacent des templates, intègrent les conventions de l’organisation | `_bmad/custom/{skill-name}.toml` (overrides d’équipe, versionnés dans git) et `.user.toml` (personnel, ignoré par git) | - -Retirez l’un des pieds et l’expérience s’effondre : - -- Skills sans agents → des listes de capacités que l’utilisateur doit parcourir par nom ou par code -- Agents sans skills → des personas sans rien à faire -- Pas de personnalisation → chaque utilisateur reçoit le même comportement par défaut, obligeant à forker pour tout besoin spécifique à l’organisation - -## Ce que les agents nommés vous apportent - -BMad embarque cinq agents nommés, chacun ancré à une phase de la méthode BMad : - -| Agent | Phase | Module | -|------------------------------------|----------------|-------------------------------------------------------------------------------------------------------------------------| -| 📊 **Mary**, Analyste d’affaires | Analyse | étude de marché, brainstorming, product briefs, PRFAQs | -| 📋 **John**, Chef de produit | Planification | création de PRD, décomposition epic/story, vérification de la préparation à l’implémentation | -| 🎨 **Sally**, Designer UX | Planification | spécifications de design UX | -| 🏗️ **Winston**, Architecte système | Solutioning | architecture technique, vérifications d’alignement | -| 💻 **Amelia**, Ingénieure senior | Implémentation | exécution de stories, build, revue de code, planification de sprint | - -:::note[Où est Paige ?] -📚 **Paige**, la Rédactrice technique, est en pause — elle reviendra à l’avenir avec des capacités bien plus étendues. La documentation de projet reste couverte : invoquez directement la compétence `bmad-document-project` ou passez par le menu de Mary. -::: - -Chacun possède une identité codée en dur (nom, titre, domaine) et une couche personnalisable (rôle, principes, style de communication, icône, menu). Vous pouvez réécrire les principes de Mary ou ajouter des éléments de menu ; vous ne pouvez pas la renommer — c’est délibéré. La reconnaissance de marque persiste après personnalisation pour que « hey Mary » active toujours l’analyste, indépendamment de la façon dont une équipe a façonné son comportement. - -## Le flux d’activation - -Quand vous invoquez un agent nommé, huit étapes s’exécutent dans l’ordre : - -1. **Résoudre le bloc agent** — fusionner le `customize.toml` livré avec les overrides d’équipe et personnels, via un résolveur Python utilisant `tomllib` de la bibliothèque standard -2. **Exécuter les étapes préliminaires** — tout comportement préalablement configuré par l’équipe -3. **Adopter le persona** — identité codée en dur ainsi que rôle personnalisé, style de communication, principes -4. **Charger les faits persistants** — règles d’organisation, notes de conformité, éventuellement des fichiers chargés via un préfixe `file:` (ex. `file:{project-root}/docs/project-context.md`) -5. **Charger la configuration** — nom d’utilisateur, langue de communication, langue de sortie, chemins des artefacts -6. **Saluer** — personnalisé, dans la langue configurée, avec le préfixe emoji de l’agent pour identifier d’un coup d’œil qui parle -7. **Exécuter les étapes de finalisation** — toute configuration post-salutation que l’équipe a définie -8. **Aiguiller ou présenter le menu** — si votre message d’ouverture correspond à un élément de menu, aller directement ; sinon afficher le menu et attendre une saisie - -L’étape 8, c’est là que la magie opère. « Hey Mary, brainstormons » évite l’affichage du menu parce que `bmad-brainstorming` correspond évidemment à `BP` dans le menu de Mary. Si vous dites quelque chose d’ambigu, elle demande une fois, brièvement, sans en faire un rituel de confirmation. Si rien ne correspond, elle poursuit la conversation normalement. - -## Pourquoi pas simplement un menu ? - -Les menus obligent l’utilisateur à aller chercher l’outil. Vous devez retenir que le brainstorming se trouve sous le code `BP` chez l’agent analyste, pas chez l’agent PM, et savoir quel persona possède quelles capacités. C’est une charge cognitive que l’outil vous fait porter. - -Les agents nommés inversent la logique. Vous dites ce que vous voulez, à qui, avec les mots qui vous semblent naturels. L’agent sait qui il est et ce qu’il fait. Quand votre intention est suffisamment claire, il agit simplement. - -Le menu reste disponible comme solution de secours — affiché quand vous explorez, ignoré quand ce n’est pas le cas. - -## Pourquoi pas simplement un prompt libre ? - -Les prompts libres supposent que vous connaissez les mots magiques. « Aide-moi à brainstormer » pourrait fonctionner, mais « explorons mon idée de SaaS » pourrait ne pas fonctionner, et les résultats dépendent de la façon dont vous avez formulé la demande. Vous devenez responsable de l’ingénierie du prompt. - -Les agents nommés ajoutent de la structure sans restreindre la liberté. Le persona reste cohérent, les capacités sont découvrables, et `bmad-help` est toujours à portée de commande. Vous n’avez pas à deviner ce que l’agent peut faire, et vous n’avez pas besoin d’un manuel pour l’utiliser non plus. - -## La personnalisation comme principe fondamental - -Le modèle de personnalisation est ce qui permet à tout cela de passer à l’échelle au-delà d’un seul développeur. - -Chaque agent embarque un fichier `customize.toml` avec des valeurs par défaut judicieuses. Les équipes versionnent des overrides dans `_bmad/custom/bmad-agent-{role}.toml`. Les individus peuvent superposer des préférences personnelles dans `.user.toml` (ignoré par git). Le résolveur fusionne les trois couches à l’activation avec des règles structurelles prévisibles. - -La plupart des utilisateurs ne rédigent jamais ces fichiers à la main. Le skill `bmad-customize` guide le choix de la cible, la sélection du périmètre agent vs workflow, la rédaction de l’override et la vérification de la fusion — pour que la surface de personnalisation reste accessible à quiconque comprend son intention, pas seulement à ceux qui maîtrisent le TOML. - -Exemple concret : une équipe versionne dans git un seul fichier demandant à Amelia d’utiliser systématiquement l’outil MCP Context7 pour la documentation des bibliothèques et de se rabattre sur Linear quand une story n’est pas dans la liste locale des epics. Chaque workflow de développement qu’Amelia lance (build, code-review, qa-generate) hérite de ce comportement, sans modification du code ni duplication par workflow. - -Il existe aussi une seconde surface de personnalisation pour les préoccupations *transversales* : la configuration centrale `_bmad/config.toml` et `_bmad/config.user.toml` (tous deux gérés par l’installateur, reconstruits à partir du `module.yaml` de chaque module) plus `_bmad/custom/config.toml` (équipe, versionné dans git) et `_bmad/custom/config.user.toml` (personnel, ignoré par git) pour les overrides. C’est là que se trouve le **registre des agents** — les descripteurs légers que les consommateurs du registre comme `bmad-party-mode`, `bmad-retrospective` et `bmad-advanced-elicitation` lisent pour savoir qui est disponible et comment l’incarner. Redéfinissez l’image d’un agent pour toute l’organisation avec un override d’équipe ; ajoutez des personnages fictifs (Kirk, Spock, un persona expert du domaine) comme expériences personnelles via l’override `.user.toml` — sans toucher aucun dossier de skill. Le fichier par skill façonne la façon dont Mary *se comporte* quand elle s’active ; la configuration centrale façonne la façon dont les autres skills *la perçoivent* quand ils consultent le registre. - -Pour la surface de personnalisation complète et des exemples concrets, consultez : - -- [Comment personnaliser BMad](../how-to/customize-bmad.md) — la référence sur ce qui est personnalisable et comment fonctionne la fusion -- [Comment étendre BMad pour votre organisation](../how-to/expand-bmad-for-your-org.md) — six recettes pratiques couvrant les règles globales des agents, les conventions de workflow, la publication externe, les remplacements de templates et la personnalisation du registre des agents -- Skill `bmad-customize` — l’assistant de rédaction guidée qui transforme une intention en fichier d’override correctement placé et vérifié - -## L’idée plus grande - -La plupart des assistants IA aujourd’hui sont soit des menus, soit des prompts, et les deux déplacent la charge cognitive vers l’utilisateur. Les agents nommés associés à des skills personnalisables vous permettent de parler à un coéquipier qui connaît déjà le travail, et laissent votre organisation façonner ce coéquipier sans forker. - -La prochaine fois que vous tapez « Hey Mary, brainstormons » et qu’elle se met directement au travail, remarquez ce qui ne s’est pas produit. Il n’y a eu ni commande slash, ni menu à parcourir, ni rappel maladroit de ce qu’elle peut faire. Cette absence, c’est le design. diff --git a/docs/fr/explanation/party-mode.md b/docs/fr/explanation/party-mode.md deleted file mode 100644 index 1f5190101a..0000000000 --- a/docs/fr/explanation/party-mode.md +++ /dev/null @@ -1,64 +0,0 @@ ---- -title: "Party Mode" -description: Collaboration multi-agents - regroupez tous vos agents IA dans une seule conversation -sidebar: - order: 8 ---- - -Regroupez tous vos agents IA dans une seule conversation. - -## Qu’est-ce que le Party Mode ? - -Lancez `bmad-party-mode` et vous avez toute votre équipe IA dans une même pièce - PM, Architecte, Développeur, Designer UX, selon vos besoins. Le Party Mode orchestre la discussion en sélectionnant, à chaque message, les agents pertinents parmi ceux installés. Les agents répondent en personnage, sont en accord ou désaccord, et construisent sur les idées des autres. - -La conversation continue aussi longtemps que vous le souhaitez. Posez des questions de suivi, remettez en question les réponses, redirigez la discussion - c’est un véritable échange avec vos agents jusqu’à ce que vous ayez terminé. - -**Idéal pour** - -- Les grandes décisions avec des compromis -- Les sessions de brainstorming -- Les rétrospectives post-incident quand les choses tournent mal -- Les rétrospectives de sprint et la planification - -## Exemples - -### Remettre en question une mauvaise architecture - -**Vous :** « Ok l’équipe, notre dernier sprint a été un désastre. Le service d’authentification est tombé trois fois. Qui a cafouillé ? » - -**Architecte :** « Le design était solide - authentification distribuée avec des fallbacks appropriés. Si l’implémentation a dévié des specs... » - -**Développeur :** « J’ai suivi le document d’architecture à la lettre. Les specs ne prenaient pas en compte les race conditions lors de l’invalidation de sessions concurrentes. » - -**PM :** « Vous avez tous les deux raté le vrai problème - nous n’avons pas validé les exigences de gestion des sessions dans le PRD. C’est de ma faute de ne pas l’avoir repéré. » - -**TEA :** « Et j’aurais dû le repérer dans les tests d’intégration. Les scénarios de test ne couvraient pas l’invalidation concurrente. » - -### Brainstorming créatif - -**Vous :** « Comment rendre l’onboarding magique au lieu d’ennuyeux ? » - -**Designer UX :** « Commençons par la divulgation progressive - révélons les fonctionnalités au fur et à mesure que les utilisateurs en ont besoin, pas d’un coup dans un tutoriel. » - -**Storyteller :** « Et si l’onboarding était une histoire ? Chaque étape révèle le parcours d’un personnage - l’utilisateur EST le héros. » - -**Game Designer :** « En partant de là - et si la première « quête » consistait à résoudre un vrai problème utilisateur ? Ils apprennent en faisant quelque chose d’utile. » - -### Décision technique - -**Vous :** « Monolithe ou microservices pour le MVP[^1] ? » - -**Architecte :** « Commencez en monolithe. Les microservices ajoutent une complexité dont vous n’avez pas besoin à 1 000 utilisateurs. » - -**PM :** « D’accord. Le time-to-market[^2] compte plus que la scalabilité théorique. » - -**Développeur :** « Monolithe avec des frontières de modules claires. On pourra extraire des services plus tard si nécessaire. » - -:::tip[Meilleures décisions] -De meilleures décisions grâce à des perspectives diverses. Bienvenue dans le party mode. -::: - -## Glossaire - -[^1]: MVP (Minimum Viable Product) : version minimale d’un produit contenant juste assez de fonctionnalités pour être utilisée par des utilisateurs précoces et valider les hypothèses de marché avant d’investir dans un développement plus complet. -[^2]: Time-to-market : délai nécessaire pour concevoir, développer et lancer un produit sur le marché. Plus ce délai est court, plus l’entreprise peut prendre de l’avance sur ses concurrents. diff --git a/docs/fr/explanation/preventing-agent-conflicts.md b/docs/fr/explanation/preventing-agent-conflicts.md deleted file mode 100644 index dcfd3f14bd..0000000000 --- a/docs/fr/explanation/preventing-agent-conflicts.md +++ /dev/null @@ -1,117 +0,0 @@ ---- -title: "Prévention des conflits entre agents" -description: Comment l’architecture empêche les conflits lorsque plusieurs agents implémentent un système -sidebar: - order: 6 ---- - -Lorsque plusieurs agents IA implémentent différentes parties d’un système, ils peuvent prendre des décisions techniques contradictoires. La documentation d’architecture prévient cela en établissant des standards partagés. - -## Types de conflits courants - -### Conflits de style d’API - -Sans architecture : -- L’agent A utilise REST avec `/users/{id}` -- L’agent B utilise des mutations GraphQL -- Résultat : Patterns d’API incohérents, consommateurs confus - -Avec architecture : -- L’ADR[^1] spécifie : « Utiliser GraphQL pour toute communication client-serveur » -- Tous les agents suivent le même pattern - -### Conflits de conception de base de données - -Sans architecture : -- L’agent A utilise des noms de colonnes en snake_case -- L’agent B utilise des noms de colonnes en camelCase -- Résultat : Schéma incohérent, requêtes illisibles - -Avec architecture : -- Un document de standards spécifie les conventions de nommage -- Tous les agents suivent les mêmes patterns - -### Conflits de gestion d’état - -Sans architecture : -- L’agent A utilise Redux pour l’état global -- L’agent B utilise React Context -- Résultat : Multiples approches de gestion d’état, complexité - -Avec architecture : -- L’ADR spécifie l’approche de gestion d’état -- Tous les agents implémentent de manière cohérente - -## Comment l’architecture prévient les conflits - -### 1. Décisions explicites via les ADR[^1] - -Chaque choix technologique significatif est documenté avec : -- Contexte (pourquoi cette décision est importante) -- Options considérées (quelles alternatives existent) -- Décision (ce qui a été choisi) -- Justification (pourquoi cela a-t-il été choisi) -- Conséquences (compromis acceptés) - -### 2. Guidance spécifique aux FR/NFR[^2] - -L’architecture associe chaque exigence fonctionnelle à une approche technique : -- FR-001 : Gestion des utilisateurs → Mutations GraphQL -- FR-002 : Application mobile → Requêtes optimisées - -### 3. Standards et conventions - -Documentation explicite de : -- La structure des répertoires -- Les conventions de nommage -- L’organisation du code -- Les patterns de test - -## L’architecture comme contexte partagé - -Considérez l’architecture comme le contexte partagé que tous les agents lisent avant d’implémenter : - -```text -PRD : "Que construire" - ↓ -Architecture : "Comment le construire" - ↓ -L'agent A lit l'architecture → implémente l'Epic 1 -L'agent B lit l'architecture → implémente l'Epic 2 -L'agent C lit l'architecture → implémente l'Epic 3 - ↓ -Résultat : Implémentation cohérente -``` - -## Sujets clés des ADR - -Décisions courantes qui préviennent les conflits : - -| Sujet | Exemple de décision | -|------------------|----------------------------------------------| -| Style d’API | GraphQL vs REST vs gRPC | -| Base de données | PostgreSQL vs MongoDB | -| Authentification | JWT vs Sessions | -| Gestion d’état | Redux vs Context vs Zustand | -| Styling | CSS Modules vs Tailwind vs Styled Components | -| Tests | Jest + Playwright vs Vitest + Cypress | - -## Anti-patterns à éviter - -:::caution[Erreurs courantes] -- **Décisions implicites** — « On décidera du style d’API au fur et à mesure » mène à l’incohérence -- **Sur-documentation** — Documenter chaque choix mineur cause une paralysie analytique -- **Architecture obsolète** — Les documents écrits une fois et jamais mis à jour poussent les agents à suivre des patterns dépassés -::: - -:::tip[Approche correcte] -- Documenter les décisions qui traversent les frontières des epics -- Se concentrer sur les zones sujettes aux conflits -- Mettre à jour l’architecture au fur et à mesure des apprentissages -- Utiliser `bmad-correct-course` pour les changements significatifs -::: - -## Glossaire - -[^1]: ADR (Architecture Decision Record) : document qui consigne une décision d’architecture, son contexte, les options envisagées, le choix retenu et ses conséquences, afin d’assurer la traçabilité et la compréhension des décisions techniques dans le temps. -[^2]: FR / NFR (Functional / Non-Functional Requirement) : exigences décrivant respectivement **ce que le système doit faire** (fonctionnalités, comportements attendus) et **comment il doit le faire** (contraintes de performance, sécurité, fiabilité, ergonomie, etc.). diff --git a/docs/fr/explanation/project-context.md b/docs/fr/explanation/project-context.md deleted file mode 100644 index bf54ec5f38..0000000000 --- a/docs/fr/explanation/project-context.md +++ /dev/null @@ -1,156 +0,0 @@ ---- -title: "Contexte du Projet" -description: Comment project-context.md guide les agents IA avec les règles et préférences de votre projet -sidebar: - order: 9 ---- - -Le fichier `project-context.md` est le guide d’implémentation de votre projet pour les agents IA. Similaire à une « constitution » dans d’autres systèmes de développement, il capture les règles, les patterns et les préférences qui garantissent une génération de code cohérente à travers tous les workflows. - -## Ce Qu’il Fait - -Les agents IA prennent constamment des décisions d’implémentation — quels patterns suivre, comment structurer le code, quelles conventions utiliser. Sans guidance claire, ils peuvent : -- Suivre des bonnes pratiques génériques qui ne correspondent pas à votre codebase -- Prendre des décisions incohérentes selon les différentes stories -- Passer à côté d’exigences ou de contraintes spécifiques au projet - -Le fichier `project-context.md` résout ce problème en documentant ce que les agents doivent savoir dans un format concis et optimisé pour les LLM. - -## Comment Ça Fonctionne - -Chaque workflow d’implémentation charge automatiquement `project-context.md` s’il existe. Le workflow architecte le charge également pour respecter vos préférences techniques lors de la conception de l’architecture. - -**Chargé par ces workflows :** -- `bmad-architecture` — respecte les préférences techniques pendant la phase de solutioning -- `bmad-code-review` — valide par rapport aux standards du projet -- `bmad-build` — applique les patterns lors de la planification et de l’implémentation d’intentions directes ou de stories -- `bmad-sprint-planning`, `bmad-retrospective`, `bmad-correct-course` — fournit le contexte global du projet - -## Quand Le Créer - -Le fichier `project-context.md` est utile à n’importe quel stade d’un projet : - -| Scénario | Quand Créer | Objectif | -|------------------------------------------|-----------------------------------------------------|---------------------------------------------------------------------------------------| -| **Nouveau projet, avant l’architecture** | Manuellement, avant `bmad-architecture` | Documenter vos préférences techniques pour que l’architecte les respecte | -| **Nouveau projet, après l’architecture** | Via `bmad-generate-project-context` ou manuellement | Capturer les décisions d’architecture pour les agents d’implémentation | -| **Projet existant** | Via `bmad-generate-project-context` | Découvrir les patterns existants pour que les agents suivent les conventions établies | -| **Entrée directe en implémentation** | Avant ou pendant `bmad-build` | Garantir que l’implémentation sans planification amont respecte vos patterns | - -:::tip[Recommandé] -Pour les nouveaux projets, créez-le manuellement avant l’architecture si vous avez de fortes préférences techniques. Sinon, générez-le après l’architecture pour capturer ces décisions. -::: - -## Ce Qu’il Contient - -Le fichier a deux sections principales : - -### Pile Technologique & Versions - -Documente les frameworks, langages et outils utilisés par votre projet avec leurs versions spécifiques : - -```markdown -## Pile Technologique & Versions - -- Node.js 20.x, TypeScript 5.3, React 18.2 -- State: Zustand (pas Redux) -- Testing: Vitest, Playwright, MSW -- Styling: Tailwind CSS avec design tokens personnalisés -``` - -### Règles Critiques d’Implémentation - -Documente les patterns et conventions que les agents pourraient autrement manquer : - -```markdown - -## Règles Critiques d’Implémentation - -**Configuration TypeScript :** -- Mode strict activé — pas de types `any` sans approbation explicite -- Utiliser `interface` pour les APIs publiques, `type` pour les unions/intersections - -**Organisation du Code :** -- Composants dans `/src/components/` avec fichiers `.test.tsx` co-localisés -- Utilitaires dans `/src/lib/` pour les fonctions pures réutilisables -- Les appels API utilisent le singleton `apiClient` — jamais de fetch direct - -**Patterns de Tests :** -- Les tests unitaires se concentrent sur la logique métier, pas sur les détails d’implémentation -- Les tests d’intégration utilisent MSW pour simuler les réponses API -- Les tests E2E couvrent uniquement les parcours utilisateurs critiques - -**Spécifique au Framework :** -- Toutes les opérations async utilisent le wrapper `handleError` pour une gestion cohérente des erreurs -- Les feature flags sont accessibles via `featureFlag()` de `@/lib/flags` -- Les nouvelles routes suivent le modèle de routage basé sur les fichiers dans `/src/app/` -``` - -Concentrez-vous sur ce qui est **non évident** — des choses que les agents pourraient ne pas déduire en lisant des extraits de code. Ne documentez pas les pratiques standard qui s’appliquent universellement. - -## Création du Fichier - -Vous avez trois options : - -### Création Manuelle - -Créez le fichier `_bmad-output/project-context.md` et ajoutez vos règles : - -```bash -# Depuis la racine du projet -mkdir -p _bmad-output -touch _bmad-output/project-context.md -``` - -Éditez-le avec votre pile technologique et vos règles d’implémentation. Les workflows architecture et implémentation le trouveront et le chargeront automatiquement. - -### Générer Après L’Architecture - -Exécutez le workflow `bmad-generate-project-context` après avoir terminé votre architecture : - -```bash -bmad-generate-project-context -``` - -Cela analyse votre document d’architecture et vos fichiers projet pour générer un fichier de contexte capturant les décisions prises. - -### Générer Pour Les Projets Existants - -Pour les projets existants, exécutez `bmad-generate-project-context` pour découvrir les patterns existants : - -```bash -bmad-generate-project-context -``` - -Le workflow analyse votre codebase pour identifier les conventions, puis génère un fichier de contexte que vous pouvez examiner et affiner. - -## Pourquoi C’est Important - -Sans `project-context.md`, les agents font des suppositions qui peuvent ne pas correspondre à votre projet : - -| Sans Contexte | Avec Contexte | -|----------------------------------------------------|-------------------------------------------------| -| Utilise des patterns génériques | Suit vos conventions établies | -| Style incohérent selon les stories | Implémentation cohérente | -| Peut manquer les contraintes spécifiques au projet | Respecte toutes les exigences techniques | -| Chaque agent décide indépendamment | Tous les agents s’alignent sur les mêmes règles | - -C’est particulièrement important pour : -- **Entrée directe** — sans PRD ni architecture, le fichier de contexte fournit les conventions durables du projet -- **Projets d’équipe** — garantit que tous les agents suivent les mêmes standards -- **Projets existants** — empêche de casser les patterns établis - -## Édition et Mise à Jour - -Le fichier `project-context.md` est un document vivant. Mettez-le à jour quand : - -- Les décisions d’architecture changent -- De nouvelles conventions sont établies -- Les patterns évoluent pendant l’implémentation -- Vous identifiez des lacunes dans le comportement des agents - -Vous pouvez l’éditer manuellement à tout moment, ou réexécuter `bmad-generate-project-context` pour le mettre à jour après des changements significatifs. - -:::note[Emplacement du Fichier] -L’emplacement par défaut est `_bmad-output/project-context.md`. Les workflows le recherchent là, et vérifient également `**/project-context.md` n’importe où dans votre projet. -::: diff --git a/docs/fr/explanation/why-solutioning-matters.md b/docs/fr/explanation/why-solutioning-matters.md deleted file mode 100644 index d8ced1e535..0000000000 --- a/docs/fr/explanation/why-solutioning-matters.md +++ /dev/null @@ -1,87 +0,0 @@ ---- -title: "Pourquoi le Solutioning est Important" -description: Comprendre pourquoi la phase de solutioning est critique pour les projets multi-epics -sidebar: - order: 5 ---- - -La Phase 3 (Solutioning) traduit le **quoi** construire (issu de la Planification) en **comment** le construire (conception technique). Cette phase évite les conflits entre agents dans les projets multi-epics en documentant les décisions architecturales avant le début de l’implémentation. - -## Le Problème Sans Solutioning - -```text -Agent 1 implémente l'Epic 1 avec une API REST -Agent 2 implémente l'Epic 2 avec GraphQL -Résultat : Conception d'API incohérente, cauchemar d'intégration -``` - -Lorsque plusieurs agents implémentent différentes parties d’un système sans orientation architecturale partagée, ils prennent des décisions techniques indépendantes qui peuvent entrer en conflit. - -## La Solution Avec le Solutioning - -```text -le workflow architecture décide : "Utiliser GraphQL pour toutes les API" -Tous les agents suivent les décisions d'architecture -Résultat : Implémentation cohérente, pas de conflits -``` - -En documentant les décisions techniques de manière explicite, tous les agents implémentent de façon cohérente et l’intégration devient simple. - -## Solutioning vs Planification - -| Aspect | Planification (Phase 2) | Solutioning (Phase 3) | -|----------|--------------------------|-------------------------------------------------| -| Question | Quoi et Pourquoi ? | Comment ? Puis Quelles unités de travail ? | -| Sortie | FRs/NFRs (Exigences)[^1] | Architecture + Epics[^2]/Stories[^3] | -| Agent | PM | Architect → PM | -| Audience | Parties prenantes | Développeurs | -| Document | PRD[^4] (FRs/NFRs) | Architecture + Fichiers Epics | -| Niveau | Logique métier | Conception technique + Décomposition du travail | - -## Principe Clé - -**Rendre les décisions techniques explicites et documentées** pour que tous les agents implémentent de manière cohérente. - -Cela évite : -- Les conflits de style d’API (REST vs GraphQL) -- Les incohérences de conception de base de données -- Les désaccords sur la gestion du state -- Les inadéquations de conventions de nommage -- Les variations d’approche de sécurité - -## Choisir la profondeur du solutioning - -| Caractéristiques du travail | Recommandation de solutioning | -|------------------------------|-------------------------------| -| Modification locale claire avec des patterns établis | Généralement inutile | -| Plusieurs composants liés avec des contraintes connues | Optionnel selon le risque de coordination | -| Plusieurs epics ou décisions multi-systèmes | Nécessaire pour aligner l’implémentation | -| Initiative réglementée, risquée ou enterprise | Suivre la gouvernance requise ; le solutioning est normalement obligatoire | - -Le solutioning change le contexte fourni à `bmad-build`, pas le workflow d’implémentation. - -:::tip[Règle Générale] -Si vous avez plusieurs epics qui pourraient être implémentés par différents agents, vous avez besoin de solutioning. -::: - -## Conséquences de sauter la phase de Solutioning - -Sauter le solutioning sur des projets complexes entraîne : - -- **Des problèmes d’intégration** découverts en milieu de sprint[^5] -- **Du travail répété** dû à des implémentations conflictuelles -- **Un temps de développement plus long** globalement -- **De la dette technique**[^6] due à des patterns incohérents - -:::caution[Coût Multiplié] -Détecter les problèmes d’alignement lors du solutioning est 10× plus rapide que de les découvrir pendant l’implémentation. -::: - -## Glossaire - -[^1]: FR / NFR (Functional / Non-Functional Requirement) : exigences décrivant respectivement **ce que le système doit faire** (fonctionnalités, comportements attendus) et **comment il doit le faire** (contraintes de performance, sécurité, fiabilité, ergonomie, etc.). -[^2]: Epic : dans les méthodologies agiles, une unité de travail importante qui peut être décomposée en plusieurs stories plus petites. Un epic représente généralement une fonctionnalité majeure ou un objectif métier. -[^3]: Story (User Story) : description courte et simple d’une fonctionnalité du point de vue de l’utilisateur, utilisée dans les méthodologies agiles pour planifier et prioriser le travail. -[^4]: PRD (Product Requirements Document) : document de référence qui décrit les objectifs du produit, les besoins utilisateurs, les fonctionnalités attendues, les contraintes et les critères de succès, afin d’aligner les équipes sur ce qui doit être construit et pourquoi. -[^5]: Sprint : période de temps fixe (généralement 1 à 4 semaines) dans les méthodologies agiles durant laquelle l’équipe complète un ensemble prédéfini de tâches. -[^6]: Dette technique : coût futur supplémentaire de travail résultant de choix de facilité ou de raccourcis pris lors du développement initial, nécessitant souvent une refonte ultérieure. diff --git a/docs/fr/how-to/customize-bmad.md b/docs/fr/how-to/customize-bmad.md deleted file mode 100644 index 3e2b9f7778..0000000000 --- a/docs/fr/how-to/customize-bmad.md +++ /dev/null @@ -1,399 +0,0 @@ ---- -title: "Comment personnaliser BMad" -description: Personnalisez les agents et les workflows tout en préservant la compatibilité avec les mises à jour -sidebar: - order: 7 ---- - -Adaptez les personas d’agents, injectez du contexte métier, ajoutez des capacités et configurez le comportement des workflows — le tout sans modifier les fichiers installés. Vos personnalisations sont préservées à chaque mise à jour. - -:::tip[Vous ne voulez pas rédiger du TOML à la main ? Utilisez `bmad-customize`] -Le skill `bmad-customize` est un assistant de rédaction guidée pour les **options de personnalisation par skill (agent/workflow)** décrite dans ce document. Il scanne ce qui est personnalisable dans votre installation, vous aide à choisir la bonne surface (agent ou workflow) pour votre intention, écrit le fichier d’override pour vous et vérifie que la fusion a fonctionné. Les overrides de la configuration centrale (`_bmad/custom/config.toml`) ne sont pas couverts par la v1 du skill — rédigez-les manuellement en vous référant à la section Configuration centrale ci-dessous. Exécutez le skill chaque fois que vous souhaitez modifier un skill spécifique ; ce document est la référence sur *ce que* chaque surface expose et comment fonctionne la fusion. -::: - -## Quand utiliser cette fonctionnalité - -- Vous souhaitez changer la personnalité ou le style de communication d’un agent -- Vous devez fournir à un agent des faits persistants qu’il devra retenir (ex. « notre org est 100 % AWS ») -- Vous souhaitez ajouter des étapes procédurales de démarrage que l’agent doit exécuter à chaque session -- Vous souhaitez ajouter des éléments de menu personnalisés qui déclenchent vos propres skills ou prompts -- Votre équipe a besoin de personnalisations partagées versionnées dans git, avec des préférences personnelles ajoutées par-dessus - -:::note[Prérequis] - -- BMad installé dans votre projet (voir [Comment installer BMad](./install-bmad.md)) -- Un moyen d’exécuter le script de résolution — BMad adopte `uv` comme standard (`uv run`, qui provisionne Python pour vous) ; un simple `python3` 3.11+ sur votre PATH fonctionne toujours pendant la transition. Le script n’utilise que `tomllib` de la bibliothèque standard, il n’y a donc rien à `pip install`. -- Un éditeur de texte pour les fichiers TOML -::: - -## Comment ça marche - -Chaque skill personnalisable embarque un fichier `customize.toml` avec ses valeurs par défaut. Ce fichier définit la surface de personnalisation complète du skill — lisez-le pour voir ce qui est personnalisable. Ne modifiez jamais ce fichier. À la place, créez des fichiers d’override allégés contenant uniquement les champs que vous souhaitez changer. - -### Modèle d’override à trois couches - -```text -Priorité 1 (gagne) : _bmad/custom/{skill-name}.user.toml (personnel, ignoré par git) -Priorité 2 : _bmad/custom/{skill-name}.toml (équipe/org, versionné dans git) -Priorité 3 (base) : customize.toml du skill (valeurs par défaut) -``` - -Le dossier `_bmad/custom/` est initialement vide. Les fichiers n’apparaissent que lorsqu’un utilisateur commence à personnaliser. - -### Règles de fusion (par forme, pas par nom de champ) - -Le résolveur applique quatre règles structurelles. Les noms de champ n’ont pas de traitement particulier — le comportement est déterminé uniquement par la forme de la valeur : - -| Forme | Règle | -|-------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------| -| Scalaire (chaîne, entier, booléen, flottant) | L’override prévaut | -| Table | Fusion profonde (application récursive des mêmes règles) | -| Tableau de tables où chaque élément partage le **même** champ identifiant (chaque élément a `code`, ou chaque élément a `id`) | Fusionner par cette clé — les clés correspondantes **remplacent sur place**, les nouvelles clés **s’ajoutent** | -| Tout autre tableau (scalaires ; tables sans identifiant ; tableaux qui mélangent `code` et `id` entre les éléments) | **Ajouter** — éléments de base en premier, puis éléments d’équipe, puis éléments utilisateur | - -**Pas de mécanisme de suppression.** Les overrides ne peuvent pas effacer les éléments de base. Si vous devez supprimer un élément de menu par défaut, surchargez-le via son `code` avec une description ou un prompt sans effet. Si vous devez restructurer un tableau plus en profondeur, forkez le skill. - -**La convention `code` / `id`.** BMad utilise `code` (code court comme `"BP"` ou `"R1"`) et `id` (identifiant stable plus long) comme clés de fusion dans les tableaux de tables. Si vous rédigez un tableau de tables personnalisé destiné à être fusionné par clé plutôt que par simple ajout, choisissez **une** convention (soit `code` sur chaque élément, soit `id` sur chaque élément) et respectez-la dans tout le tableau. Mélanger `code` sur certains éléments et `id` sur d’autres revient à un simple ajout — le résolveur ne devinera pas quelle clé utiliser pour la fusion. - -### Certains champs d’agent sont en lecture seule - -`agent.name` et `agent.title` sont présents dans `customize.toml` comme source de vérité, mais le SKILL.md de l’agent ne les lit pas à l’exécution — leur identité est codée en dur. Mettre `name = "Bob"` dans un fichier d’override n’a aucun effet. Si vous avez vraiment besoin d’un agent avec un nom différent, copiez le dossier du skill, renommez-le et distribuez-le comme skill personnalisé. - -## Étapes - -### 1. Trouver la surface de personnalisation du skill - -Consultez le `customize.toml` du skill dans son répertoire d’installation. Par exemple, l’agent PM : - -```text -.claude/skills/bmad-agent-pm/customize.toml -``` - -(Le chemin varie selon l’IDE — Cursor utilise `.cursor/skills/`, Cline utilise `.cline/skills/`, etc.) - -Ce fichier est le schéma canonique. Chaque champ que vous voyez est personnalisable (à l’exception des champs d’identité en lecture seule mentionnés ci-dessus). - -### 2. Créer votre fichier d’override - -Créez le répertoire `_bmad/custom/` à la racine de votre projet s’il n’existe pas. Puis créez un fichier portant le même nom que le skill : - -```text -_bmad/custom/ - bmad-agent-pm.toml # overrides d'équipe (versionnés dans git) - bmad-agent-pm.user.toml # préférences personnelles (ignoré par git) -``` - -:::caution[Ne copiez PAS le `customize.toml` complet] -Les fichiers d’override sont **allégés**. Incluez uniquement les champs que vous modifiez — rien d’autre. Chaque champ omis est hérité automatiquement de la couche inférieure (l’équipe hérite des valeurs par défaut, l’utilisateur de l’équipe ou des valeurs par défaut). - -Copier le `customize.toml` complet dans un override est contre-productif : la prochaine mise à jour livrera de nouvelles valeurs par défaut, mais votre fichier d’override figera les anciennes valeurs. Votre configuration s’éloignera silencieusement des valeurs par défaut à chaque mise à jour. -::: - -**Exemple — changer l’icône et ajouter un principe :** - -```toml -# _bmad/custom/bmad-agent-pm.toml -# Uniquement les champs que je modifie. Tout le reste est hérité. - -[agent] -icon = "🏥" -principles = [ - "Ne rien livrer qui ne puisse passer un audit FDA.", -] -``` - -Ceci ajoute le nouveau principe aux valeurs par défaut (en laissant les principes existants intacts) et remplace l’icône. Tous les autres champs restent inchangés. - -### 3. Personnaliser selon vos besoins - -Tous les exemples ci-dessous supposent le schéma d’agent plat de BMad. Les champs se trouvent directement sous `[agent]` — pas de sous-tables `metadata` ou `persona` imbriquées. - -**Scalaires (icon, role, identity, communication_style).** Les overrides scalaires prévalent. Vous n’avez besoin de définir que les champs que vous modifiez : - -```toml -# _bmad/custom/bmad-agent-pm.toml - -[agent] -icon = "🏥" -role = "Pilote la découverte produit pour un domaine de santé réglementé." -communication_style = "Précis, sensible à la réglementation, pose des questions orientées conformité tôt." -``` - -**Faits persistants, principes, hooks d’activation (tableaux en mode ajout).** Les quatre tableaux ci-dessous sont en ajout uniquement. Les éléments d’équipe s’exécutent après les valeurs par défaut, les éléments utilisateur s’exécutent en dernier. - -```toml -[agent] -# Faits statiques que l'agent garde en tête pendant toute la session — règles d'org, -# constantes de domaine, préférences utilisateur. Distinct du sidecar de mémoire runtime. -# -# Chaque entrée est soit une phrase littérale, soit une référence `file:` dont le -# contenu est chargé comme des faits (patterns glob supportés). -persistent_facts = [ - "Notre org est 100 % AWS — ne pas proposer GCP ni Azure.", - "Tous les PRD nécessitent une validation légale avant le démarrage de l'ingénierie.", - "Les utilisateurs cibles sont des cliniciens, pas des patients — formuler les exemples en conséquence.", - "file:{project-root}/docs/compliance/hipaa-overview.md", - "file:{project-root}/_bmad/custom/company-glossary.md", -] - -# S'ajoute au système de valeurs de l'agent -principles = [ - "Ne rien livrer qui ne puisse passer un audit FDA.", - "Valeur utilisateur d'abord, conformité toujours.", -] - -# S'exécute AVANT l'activation standard (persona, persistent_facts, config, salutation). -# À utiliser pour les préchargements, vérifications de conformité, tout ce qui doit être -# en contexte avant que l'agent ne se présente. -activation_steps_prepend = [ - "Scanner {project-root}/docs/compliance/ et charger tout document lié à HIPAA comme contexte.", -] - -# S'exécute APRÈS la salutation, AVANT le menu. Utiliser pour le chargement de contexte -# qui doit intervenir après le message d'accueil. -activation_steps_append = [ - "Lire {project-root}/_bmad/custom/company-glossary.md s'il existe.", -] -``` - -**Pourquoi deux hooks ?** Le préfixe s’exécute avant la salutation pour que l’agent puisse charger le contexte dont il a besoin pour personnaliser la salutation elle-même. Le suffixe s’exécute après la salutation pour que l’utilisateur ne reste pas devant un terminal vide pendant les scans lourds. - -**Personnalisation du menu (fusion par `code`).** Le menu est un tableau de tables. Chaque élément possède un champ `code` (convention BMad). Le résolveur fusionne donc par code : les codes correspondants remplacent sur place, les nouveaux codes s’ajoutent. - -La syntaxe TOML pour les tableaux de tables utilise `[[agent.menu]]` pour chaque élément : - -```toml -# Remplacer l'élément CE existant par un skill personnalisé -[[agent.menu]] -code = "CE" -description = "Créer des Epics avec notre framework de livraison" -skill = "custom-create-epics" - -# Ajouter un nouvel élément (le code RC n'existe pas dans les valeurs par défaut) -[[agent.menu]] -code = "RC" -description = "Exécuter une pré-vérification de conformité" -prompt = """ -Lire {project-root}/_bmad/custom/compliance-checklist.md -et scanner tous les documents dans {planning_artifacts} en les comparant à celui-ci. -Signaler tout écart et citer la section réglementaire pertinente. -""" -``` - -Chaque élément de menu possède exactement un `skill` (invoque un skill enregistré) ou `prompt` (exécute le texte directement). Les éléments non listés dans votre override conservent leurs valeurs par défaut. - -**Référencer des fichiers.** Quand le texte d’un champ doit pointer vers un fichier (dans `persistent_facts`, `activation_steps_prepend`/`activation_steps_append`, ou le `prompt` d’un élément de menu), utilisez un chemin complet partant de `{project-root}`. Même si le fichier se trouve à côté de votre override dans `_bmad/custom/`, écrivez le chemin complet : `{project-root}/_bmad/custom/info.md`. L’agent résout `{project-root}` à l’exécution. - -### 4. Personnel vs Équipe - -**Fichier d’équipe** (`bmad-agent-pm.toml`) : Versionné dans git. Partagé au sein de l’organisation. À utiliser pour les règles de conformité, le persona de l’entreprise, les capacités personnalisées. - -**Fichier personnel** (`bmad-agent-pm.user.toml`) : Automatiquement ignoré par git. À utiliser pour les ajustements de ton, les préférences de workflow personnelles et les faits privés que l’agent doit garder en tête. - -```toml -# _bmad/custom/bmad-agent-pm.user.toml - -[agent] -persistent_facts = [ - "Toujours inclure une estimation approximative de complexité (faible/moyenne/élevée) en présentant les options.", -] -``` - -## Comment fonctionne la résolution - -À l’activation, le SKILL.md de l’agent exécute un script Python partagé qui effectue la fusion à trois couches et renvoie le bloc résolu en JSON. Le script utilise uniquement le module `tomllib` de la bibliothèque standard Python (aucune dépendance externe). BMad adopte `uv run` comme standard pour exécuter ces scripts (uv provisionne un Python adapté pour vous) ; un simple `python3` fonctionne toujours pendant la transition : - -```bash -uv run {project-root}/_bmad/scripts/resolve_customization.py \ - --skill {skill-root} \ - --project-root {project-root} \ - --key agent -``` - -**Prérequis** : Python 3.11+ (les versions antérieures n’incluent pas `tomllib`). Rien à `pip install`. L’exécution via `uv run` est le standard à venir — uv résout un interpréteur adapté pour vous. Si vous l’exécutez directement avec `python3` pendant la transition, vérifiez votre version avec `python3 --version` ; certaines plateformes (macOS sans Homebrew, Ubuntu 22.04) ont `python3` par défaut en 3.10 ou antérieur, vous devrez peut-être installer 3.11+ séparément. - -`--skill` pointe vers le répertoire installé du skill (où se trouve `customize.toml`). Le nom du skill est déduit du basename du répertoire, et le script cherche automatiquement `_bmad/custom/{skill-name}.toml` et `{skill-name}.user.toml`. - -Exemples d’utilisation : - -```bash -# Résoudre le bloc agent complet -uv run {project-root}/_bmad/scripts/resolve_customization.py \ - --skill /chemin/absolu/vers/bmad-agent-pm \ - --project-root {project-root} \ - --key agent - -# Résoudre un seul champ -uv run {project-root}/_bmad/scripts/resolve_customization.py \ - --skill /chemin/absolu/vers/bmad-agent-pm \ - --project-root {project-root} \ - --key agent.icon - -# Dump complet -uv run {project-root}/_bmad/scripts/resolve_customization.py \ - --skill /chemin/absolu/vers/bmad-agent-pm \ - --project-root {project-root} -``` - -La sortie est toujours en JSON. Si le script n’est pas disponible sur une plateforme donnée, le SKILL.md demande à l’agent de lire les trois fichiers TOML directement et d’appliquer les mêmes règles de fusion. - -## Personnalisation des workflows - -Les workflows (skills qui pilotent des processus multi-étapes comme `bmad-product-brief`) partagent le même mécanisme d’override que les agents. Leur surface personnalisable se trouve sous `[workflow]` au lieu de `[agent]` : - -```toml -# _bmad/custom/bmad-product-brief.toml - -[workflow] -# Même sémantique préfixe/suffixe que les agents — s'exécute avant et après les étapes -# d'activation propres au workflow. Les overrides s'ajoutent aux valeurs par défaut. -activation_steps_prepend = [ - "Charger {project-root}/docs/product/north-star-principles.md comme contexte.", -] - -activation_steps_append = [] - -# Même sémantique littéral ou fichier que pour la variante agent. Chargé comme contexte -# fondamental pour la durée de l'exécution du workflow. -persistent_facts = [ - "Tous les briefs doivent inclure une section explicite de risque réglementaire.", - "file:{project-root}/docs/compliance/product-brief-checklist.md", -] - -# Scalaire : s'exécute une fois que le workflow a terminé son livrable principal. L'override prévaut. -on_complete = "Résumer le brief en trois points et proposer de l'envoyer par email via le skill gws-gmail-send." -``` - -Les mêmes conventions de champs s’appliquent indifféremment aux agents et aux workflows : `activation_steps_prepend`/`activation_steps_append`, `persistent_facts` (avec refs `file:`) et les tables `[[…]]` de style menu avec `code`/`id` pour la fusion par clé. Le résolveur applique les mêmes quatre règles structurelles quelle que soit la clé de premier niveau. Les références dans SKILL.md suivent l’espace de noms : `{workflow.activation_steps_prepend}`, `{workflow.persistent_facts}`, `{workflow.on_complete}`. Tout champ supplémentaire qu’un workflow expose (chemins de sortie, bascules, paramètres de revue, drapeaux d’étape) suit les mêmes règles de fusion basées sur la forme. Lisez le `customize.toml` du workflow pour voir ce qui est personnalisable. - -### Ordre d’activation - -Les workflows personnalisables exécutent leur activation dans une séquence fixe pour que vous sachiez exactement quand vos hooks se déclenchent : - -1. Résoudre le bloc `[workflow]` (fusion base → équipe → utilisateur) -2. Exécuter `activation_steps_prepend` dans l’ordre -3. Charger `persistent_facts` comme contexte fondamental pour l’exécution -4. Charger la configuration (`_bmad/bmm/config.yaml`) et résoudre les variables standard (nom du projet, langues, chemins, date) -5. Saluer l’utilisateur -6. Exécuter `activation_steps_append` dans l’ordre - -Après l’étape 6, le corps du workflow commence. Utilisez `activation_steps_prepend` quand vous avez besoin de contexte chargé avant que la salutation puisse être personnalisée ; utilisez `activation_steps_append` quand le chargement est lourd et que vous préférez que l’utilisateur voie la salutation d’abord. - -### Périmètre de cette première passe - -La personnalisation est déployée de manière incrémentale. Les champs documentés ci-dessus — `activation_steps_prepend`, `activation_steps_append`, `persistent_facts`, `on_complete` — sont la **surface de base** que chaque workflow personnalisable expose, et ils resteront stables d’une version à l’autre. Ils vous donnent un contrôle à grands traits dès aujourd’hui : injecter des étapes pré/post, épingler du contexte fondamental, déclencher des actions de suivi. - -Au fil du temps, les workflows individuels exposeront des **points de personnalisation plus ciblés** adaptés à ce que le workflow fait réellement — par exemple des bascules par étape, des drapeaux d’étape, des chemins de templates de sortie ou des jalons de revue. Quand ils arriveront, ils viendront s’ajouter aux champs de base plutôt que de les remplacer, pour que les personnalisations que vous rédigez aujourd’hui continuent de fonctionner. - -Si vous avez besoin d’un réglage précis qui n’est pas encore exposé, utilisez `activation_steps_*` et `persistent_facts` pour orienter le comportement, ou ouvrez une issue décrivant le point de personnalisation spécifique que vous souhaitez — ces demandes déterminent quels champs ciblés seront ajoutés ensuite. - -## Configuration centrale - -Le `customize.toml` par skill couvre le **comportement profond** (hooks, menus, persistent_facts, overrides de persona pour un seul agent ou workflow). Une surface séparée couvre l'**état transversal** — les réponses d’installation et le registre des agents que les skills externes comme `bmad-party-mode`, `bmad-retrospective` et `bmad-advanced-elicitation` consomment. Cette surface se trouve dans quatre fichiers TOML à la racine du projet : - -```text -_bmad/config.toml (géré par l'installateur) périmètre équipe : réponses d'installation + registre des agents -_bmad/config.user.toml (géré par l'installateur) périmètre utilisateur : user_name, langue, niveau de skill -_bmad/custom/config.toml (rédigé manuellement) overrides d'équipe (versionnés dans git) -_bmad/custom/config.user.toml (rédigé manuellement) overrides personnels (ignoré par git) -``` - -### Fusion à quatre couches - -```text -Priorité 1 (gagne) : _bmad/custom/config.user.toml -Priorité 2 : _bmad/custom/config.toml -Priorité 3 : _bmad/config.user.toml -Priorité 4 (base) : _bmad/config.toml -``` - -Mêmes règles structurelles que la personnalisation par skill (scalaires prévalent, tables fusionnent en profondeur, tableaux à clé `code`/`id` fusionnent par clé, autres tableaux s’ajoutent). - -### Répartition du contenu - -L’installateur répartit les réponses selon le `scope:` déclaré sur chaque prompt dans `module.yaml` : - -- Les sections `[core]` et `[modules.]` — réponses d’installation. Le scope `team` figure dans `_bmad/config.toml` ; le scope `user` figure dans `_bmad/config.user.toml`. -- `[agents.]` — descripteur de l’agent (code, name, title, icon, description, team) extrait du bloc `agents:` de chaque `module.yaml`. Toujours de scope équipe. - -### Règles de modification - -- `_bmad/config.toml` et `_bmad/config.user.toml` sont **régénérés à chaque installation** à partir des réponses collectées pendant le processus d’installation. Traitez-les comme des sorties en lecture seule — les modifications directes seront écrasées à la prochaine installation. Pour changer une réponse d’installation de manière durable, relancez l’installateur (il se souvient de vos réponses précédentes comme valeurs par défaut) ou surchargez la valeur dans `_bmad/custom/config.toml`. -- `_bmad/custom/config.toml` et `_bmad/custom/config.user.toml` ne sont **jamais modifiés** par l’installateur. C’est l’espace approprié pour les agents personnalisés, les overrides de descripteur d’agent, les paramètres imposés par l’équipe et toute valeur que vous souhaitez figer indépendamment des réponses d’installation. - -### Exemple — Renommer un agent - -```toml -# _bmad/custom/config.toml (versionné dans git, s'applique à tous les développeurs) - -[agents.bmad-agent-pm] -description = "PM Santé — sensible à la réglementation, orienté parties prenantes, questions orientées FDA en premier." -icon = "🏥" -``` - -Le résolveur fusionne par-dessus le `[agents.bmad-agent-pm]` écrit par l’installateur. `bmad-party-mode` et tout autre utilisateur du registre récupèrent automatiquement la nouvelle description. - -### Exemple — Ajouter un agent fictif - -```toml -# _bmad/custom/config.user.toml (personnel, ignoré par git) - -[agents.kirk] -team = "startrek" -name = "Captain James T. Kirk" -title = "Starship Captain" -icon = "🖖" -description = "Commandant audacieux, enfreignant les règles. Parle en pauses dramatiques. Pense à voix haute sur le poids du commandement." -``` - -Pas de dossier de skill requis — le descripteur seul suffit pour que party-mode instancie Kirk comme voix. Filtrez par le champ `team` pour inviter uniquement l’équipage de l’Enterprise à une table ronde. - -### Exemple — Override des paramètres d’installation du module - -```toml -# _bmad/custom/config.toml - -[modules.bmm] -planning_artifacts = "/shared/org-planning-artifacts" -``` - -L’override prévaut sur ce que chaque développeur a répondu lors de son installation locale. Utile pour figer les conventions d’équipe. - -### Quelle surface utiliser pour quel besoin - -| Besoin | Utiliser | -|----------------------------------------------------------|-------------------------------------------------------------------------------| -| Ajouter des appels d’outils MCP à chaque workflow de dev | Par skill : `_bmad/custom/bmad-agent-dev.toml` `persistent_facts` | -| Ajouter un élément de menu à un agent | Par skill : `_bmad/custom/bmad-agent-{role}.toml` `[[agent.menu]]` | -| Remplacer le template de sortie d’un workflow | Par skill : `_bmad/custom/{workflow}.toml` override scalaire | -| Renommer le descripteur public d’un agent | **Centrale** : `_bmad/custom/config.toml` `[agents.]` | -| Ajouter un agent personnalisé ou fictif au registre | **Centrale** : `_bmad/custom/config.*.toml` nouvelle entrée `[agents.]` | -| Figer les paramètres d’installation pour l’équipe | **Centrale** : `_bmad/custom/config.toml` `[modules.]` ou `[core]` | - -Utilisez les deux espaces dans le même projet selon vos besoins. - -## Exemples concrets - -Pour des recettes orientées entreprise (façonner un agent à travers tous les workflows qu’il gère, imposer les conventions d’organisation, publier les livrables vers Confluence et Jira, personnaliser le registre des agents et remplacer vos propres templates de sortie), consultez [Comment étendre BMad pour votre organisation](./expand-bmad-for-your-org.md). - -## Dépannage - -**La personnalisation n’apparaît pas ?** - -- Vérifiez que votre fichier se trouve dans `_bmad/custom/` avec le nom de skill correct -- Vérifiez la syntaxe TOML : les chaînes doivent être entre guillemets, les en-têtes de table utilisent `[section]`, les tableaux de tables utilisent `[[section]]`, et toute clé scalaire ou de tableau pour une table doit apparaître *avant* toute `[[sous-table]]` de cette table dans le fichier -- Pour les agents, la personnalisation se trouve sous `[agent]` — les champs écrits sous cet en-tête appartiennent à `agent` jusqu’à ce qu’un autre en-tête de table commence -- Rappelez-vous que `agent.name` et `agent.title` sont en lecture seule ; les overrides n’ont aucun effet - -**Les mises à jour ont cassé votre personnalisation ?** - -- Avez-vous copié le `customize.toml` complet dans votre fichier d’override ? **Ne le faites pas.** Les fichiers d’override ne doivent contenir que les champs que vous modifiez. Une copie complète fige les anciennes valeurs par défaut et dérive silencieusement à chaque version. Réduisez votre override aux seuls deltas. - -**Besoin de voir ce qui est personnalisable ?** - -- Exécutez le skill `bmad-customize` — il énumère chaque skill personnalisable installé dans votre projet, montre lesquels ont déjà des overrides et vous guide pour en ajouter ou en modifier. -- Ou lisez directement le `customize.toml` du skill — chaque champ listé est personnalisable (sauf `name` et `title`) - -**Besoin de réinitialiser ?** - -- Supprimez votre fichier d’override de `_bmad/custom/` — le skill revient à ses valeurs par défaut intégrées. diff --git a/docs/fr/how-to/established-projects.md b/docs/fr/how-to/established-projects.md deleted file mode 100644 index edb361e52d..0000000000 --- a/docs/fr/how-to/established-projects.md +++ /dev/null @@ -1,122 +0,0 @@ ---- -title: "Projets existants" -description: Comment utiliser la méthode BMad sur des bases de code existantes -sidebar: - order: 6 ---- - -Utilisez la méthode BMad efficacement lorsque vous travaillez sur des projets existants et des bases de code legacy. - -Ce guide couvre le flux de travail essentiel pour l’intégration à des projets existants avec la méthode BMad. - -:::note[Prérequis] -- méthode BMad installée (`npx bmad-method install`) -- Une base de code existante sur laquelle vous souhaitez travailler -- Accès à un IDE IA (Claude Code ou Cursor) -::: - -## Étape 1 : Nettoyer les artefacts de planification terminés - -Si vous avez terminé tous les epics et stories du PRD[^1] via le processus BMad, nettoyez ces fichiers. Archivez-les, supprimez-les, ou appuyez-vous sur l’historique des versions si nécessaire. Ne conservez pas ces fichiers dans : - -- `docs/` -- `_bmad-output/planning-artifacts/` -- `_bmad-output/implementation-artifacts/` - -## Étape 2 : Créer le contexte du projet - -:::tip[Recommandé pour les projets existants] -Générez `project-context.md` pour capturer les patterns et conventions de votre base de code existante. Cela garantit que les agents IA suivent vos pratiques établies lors de l’implémentation des modifications. -::: - -Exécutez le workflow de génération de contexte du projet : - -```bash -bmad-generate-project-context -``` - -Cela analyse votre base de code pour identifier : -- La pile technologique et les versions -- Les patterns d’organisation du code -- Les conventions de nommage -- Les approches de test -- Les patterns spécifiques aux frameworks - -Vous pouvez examiner et affiner le fichier généré, ou le créer manuellement à `_bmad-output/project-context.md` si vous préférez. - -[En savoir plus sur le contexte du projet](../explanation/project-context.md) - -## Étape 3 : Maintenir une documentation de projet de qualité - -Votre dossier `docs/` doit contenir une documentation succincte et bien organisée qui représente fidèlement votre projet : - -- L’intention et la justification métier -- Les règles métier -- L’architecture -- Toute autre information pertinente sur le projet - -Pour les projets complexes, envisagez d’utiliser le workflow `bmad-document-project`. Il offre des variantes d’exécution qui analyseront l’ensemble de votre projet et documenteront son état actuel réel. - -## Étape 4 : Obtenir de l’aide - -### BMad-Help : Votre point de départ - -**Exécutez `bmad-help` chaque fois que vous n’êtes pas sûr de la prochaine étape.** Ce guide intelligent : - -- Inspecte votre projet pour voir ce qui a déjà été fait -- Affiche les options basées sur vos modules installés -- Comprend les requêtes en langage naturel - -``` -bmad-help J'ai une app Rails existante, par où dois-je commencer ? -bmad-help Quelle profondeur de planification faut-il avant d’implémenter ce changement ? -bmad-help Montre-moi quels workflows sont disponibles -``` - -BMad-Help s’exécute également **automatiquement à la fin de chaque workflow**, fournissant des conseils clairs sur exactement quoi faire ensuite. - -### Choisir la profondeur de planification - -Toute implémentation utilise `bmad-build` ; la portée détermine le contexte à préparer en amont : - -| Portée | Approche recommandée | -|-------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| **Mises à jour ou ajouts clairs** | Entrez directement dans `bmad-build` avec la demande, l’issue ou la spécification existante. | -| **Modifications ou ajouts majeurs** | Préparez le PRD, l’UX, l’architecture, les epics, les stories et le contexte de sprint utiles, puis confiez le travail sélectionné à `bmad-build`. | - -### Pendant la création du PRD - -Lors de la création d’un brief ou en passant directement au PRD[^1], assurez-vous que l’agent : - -- Trouve et analyse votre documentation de projet existante -- Lit le contexte approprié sur votre système actuel - -Vous pouvez guider l’agent explicitement, mais l’objectif est de garantir que la nouvelle fonctionnalité s’intègre bien à votre système existant. - -### Considérations UX - -Le travail UX[^2] est optionnel. La décision dépend non pas de savoir si votre projet a une UX, mais de : - -- Si vous allez travailler sur des modifications UX -- Si des conceptions ou patterns UX significatifs sont nécessaires - -Si vos modifications se résument à de simples mises à jour d’écrans existants qui vous satisfont, un processus UX complet n’est pas nécessaire. - -### Considérations d’architecture - -Lors de la création de l’architecture, assurez-vous que l’architecte : - -- Utilise les fichiers documentés appropriés -- Analyse la base de code existante - -Soyez particulièrement attentif ici pour éviter de réinventer la roue ou de prendre des décisions qui ne s’alignent pas avec votre architecture existante. - -## Plus d’informations - -- **[Corrections rapides](./quick-fixes.md)** - Corrections de bugs et modifications ad-hoc -- **[FAQ Projets existants](../explanation/established-projects-faq.md)** - Questions courantes sur le travail sur des projets établis - -## Glossaire - -[^1]: PRD (Product Requirements Document) : document de référence qui décrit les objectifs du produit, les besoins utilisateurs, les fonctionnalités attendues, les contraintes et les critères de succès, afin d’aligner les équipes sur ce qui doit être construit et pourquoi. -[^2]: UX (User Experience) : expérience utilisateur, englobant l’ensemble des interactions et perceptions d’un utilisateur face à un produit. Le design UX vise à créer des interfaces intuitives, efficaces et agréables en tenant compte des besoins, comportements et contexte d’utilisation. diff --git a/docs/fr/how-to/expand-bmad-for-your-org.md b/docs/fr/how-to/expand-bmad-for-your-org.md deleted file mode 100644 index 695da9dcb5..0000000000 --- a/docs/fr/how-to/expand-bmad-for-your-org.md +++ /dev/null @@ -1,328 +0,0 @@ ---- -title: 'Comment étendre BMad pour votre organisation' -description: Six patterns de personnalisation qui remodèlent BMad sans créer de fork — règles applicables aux agents, conventions de workflow, publication externe, remplacements de templates, modifications du registre des agents et patterns d’intégration avancés -sidebar: - order: 9 ---- - -Le système de personnalisation de BMad permet à une organisation d’adapter les comportements sans modifier les fichiers installés ni forker les skills. Ce guide présente six recettes qui couvrent la plupart des besoins en entreprise. - -:::note[Prérequis] - -- BMad installé dans votre projet (voir [Comment installer BMad](./install-bmad.md)) -- Connaissance du modèle de personnalisation (voir [Comment personnaliser BMad](./customize-bmad.md)) -- Python 3.11+ sur le PATH (pour le résolveur — bibliothèque standard uniquement, pas de `pip install`) -::: - -:::tip[Appliquer ces recettes] -Les **recettes par skill** ci-dessous (Recettes 1–4) peuvent être appliquées en exécutant le skill `bmad-customize` et en décrivant l’intention — il sélectionnera le bon point de personnalisation, générera le fichier d’override et vérifiera la fusion. La Recette 5 (overrides de la configuration centrale du registre des agents) n’est pas couverte par la v1 du skill et reste rédigée manuellement. Les recettes ici constituent la source de vérité sur *quoi* personnaliser ; `bmad-customize` gère le *comment* pour la surface agent/workflow. -::: - -## Le modèle mental à trois couches - -Avant de choisir une recette, comprenez où votre override se situe : - -| Couche | Où vivent les overrides | Périmètre | -|----------------------------------------------|-----------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------| -| **Agent** (ex. Amelia, Mary, John) | Section `[agent]` de `_bmad/custom/bmad-agent-{role}.toml` | Se propage avec le persona dans **chaque workflow que l’agent dispatche** | -| **Workflow** (ex. product-brief, create-prd) | Section `[workflow]` de `_bmad/custom/{workflow-name}.toml` | S’applique uniquement à l’exécution de ce workflow | -| **Configuration centrale** | `[agents.*]`, `[core]`, `[modules.*]` dans `_bmad/custom/config.toml` | Registre des agents (qui est disponible pour party-mode, retrospective, elicitation), paramètres d’installation figés pour toute l’organisation | - -En règle générale : si la règle doit s’appliquer partout où un ingénieur travaille sur le développement, personnalisez l'**agent dev**. Si elle s’applique uniquement quand quelqu’un rédige un product brief, personnalisez le **workflow product-brief**. Si elle change *qui participe* (renommer un agent, ajouter une voix personnalisée, imposer un chemin d’artefact partagé), modifiez la **configuration centrale**. - -## Recette 1 : Façonner un agent à travers tous les workflows qu’il dispatche - -**Cas d’usage :** Standardiser l’utilisation des outils et les intégrations avec les systèmes externes pour que chaque workflow dispatché par un agent hérite du comportement. C’est le pattern le plus impactant. - -**Exemple : Amelia (agent dev) utilise toujours Context7 pour la documentation des bibliothèques, et se rabat sur Linear quand une story n’est pas trouvée dans la liste des epics.** - -```toml -# _bmad/custom/bmad-agent-dev.toml - -[agent] - -# Appliqué à chaque activation. Se propage dans build, code-review, -# qa-generate — chaque skill qu'Amelia dispatche. -persistent_facts = [ - "Pour toute recherche de documentation sur une bibliothèque (React, TypeScript, Zod, Prisma, etc.), appeler l'outil MCP context7 (`mcp__context7__resolve_library_id` puis `mcp__context7__get_library_docs`) avant de s'appuyer sur les connaissances des données d'entraînement. Les docs à jour priment sur les API mémorisées.", - "Quand une référence de story n'est pas trouvée dans {planning_artifacts}/epics-and-stories.md, chercher dans Linear via `mcp__linear__search_issues` en utilisant l'ID ou le titre de la story avant de demander à l'utilisateur de clarifier. Si Linear renvoie un résultat, le considérer comme la source de référence pour la story.", -] -``` - -**Pourquoi ça marche :** Deux phrases suffisent à reconfigurer tous les workflows de dev de l’organisation, sans duplication par workflow ni modification du code source. Chaque nouvel ingénieur qui clone le dépôt hérite automatiquement des conventions. - -**Fichier d’équipe vs fichier personnel :** -- `bmad-agent-dev.toml` : versionné dans git ; s’applique à toute l’équipe -- `bmad-agent-dev.user.toml` : ignoré par git ; préférences personnelles ajoutées par-dessus - -## Recette 2 : Imposer les conventions de l’organisation dans un workflow spécifique - -**Cas d’usage :** Façonner le *contenu* de la sortie d’un workflow pour qu’il réponde aux exigences de conformité, d’audit ou des consommateurs en aval. - -**Exemple : chaque product brief doit inclure des champs de conformité, et l’agent connaît les conventions de publication de l’organisation.** - -```toml -# _bmad/custom/bmad-product-brief.toml - -[workflow] - -persistent_facts = [ - "Chaque brief doit inclure un champ 'Propriétaire', un champ 'Release cible' et un champ 'Statut de la revue de sécurité'.", - "Les briefs non commerciaux (outils internes, projets de recherche) doivent toujours inclure une section 'valeur utilisateur', mais peuvent omettre la différenciation concurrentielle.", - "file:{project-root}/docs/enterprise/brief-publishing-conventions.md", -] -``` - -**Ce qui se passe :** Les faits sont chargés durant l’étape 3 de l’activation du workflow. Quand l’agent rédige le brief, il connaît les champs requis et le document de conventions enterprise. Les skills livrés ne portent aucun fait persistant par défaut : ce sont donc les seuls chargés. Mais comme la clé ajoute au lieu de remplacer, un fait défini au niveau équipe et un autre au niveau utilisateur s’appliquent tous les deux. - -## Recette 3 : Publier les livrables finis vers des systèmes externes - -**Cas d’usage :** Une fois le livrable produit, le publier automatiquement vers les systèmes de référence de l’entreprise (Confluence, Notion, SharePoint) et créer des tickets de suivi (Jira, Linear, Asana). - -**Exemple : les briefs sont automatiquement publiés vers Confluence et proposent la création facultative d’un epic Jira.** - -```toml -# _bmad/custom/bmad-product-brief.toml - -[workflow] - -# Hook terminal. L'override scalaire remplace intégralement la valeur par défaut vide. -on_complete = """ -Publier et proposer le suivi : - -1. Lire le chemin du fichier brief finalisé depuis l'étape précédente. -2. Appeler `mcp__atlassian__confluence_create_page` avec : - - space : "PRODUCT" - - parent : "Product Briefs" - - title : le titre du brief - - body : le contenu markdown du brief - Capturer l'URL de la page renvoyée. -3. Informer l'utilisateur : "Brief publié sur Confluence : ". -4. Demander : "Voulez-vous que j'ouvre un epic Jira pour ce brief maintenant ?" -5. Si oui, appeler `mcp__atlassian__jira_create_issue` avec : - - type : "Epic" - - project : "PROD" - - summary : le titre du brief - - description : un résumé court accompagné d'un lien vers la page Confluence. - Signaler la clé et l'URL de l'epic. -6. Si non, se terminer proprement. - -Si l'un des outils MCP échoue, signaler l'échec, afficher le chemin du brief, -et demander à l'utilisateur de publier manuellement. -""" -``` - -**Pourquoi `on_complete` et pas `activation_steps_append` :** `on_complete` s’exécute exactement une fois, au stade terminal, après que le workflow a écrit sa sortie principale. C’est le bon moment pour publier des artefacts. `activation_steps_append` s’exécute à chaque activation, avant que le workflow ne fasse son travail. - -**Arbitrages :** -- **La publication Confluence est non-destructive** et s’exécute toujours à la fin -- **La création d’epic Jira est visible par toute l’équipe** et déclenche un processus de planification de sprint, conditionnez-la donc à la confirmation de l’utilisateur -- **Dégradation gracieuse :** si les outils MCP échouent, passer la main à l’utilisateur plutôt que de silencieusement abandonner le livrable - -## Recette 4 : Remplacer le template de sortie par le vôtre - -**Cas d’usage :** La structure de sortie par défaut ne correspond pas au format attendu par votre organisation, ou différentes organisations dans le même dépôt ont besoin de templates différents. - -**Exemple : pointer le workflow product-brief vers un template appartenant à l’entreprise.** - -```toml -# _bmad/custom/bmad-product-brief.toml - -[workflow] -brief_template = "{project-root}/docs/enterprise/brief-template.md" -``` - -**Comment ça marche :** Le `customize.toml` du workflow est fourni avec `brief_template = "resources/brief-template.md"` (chemin relatif, résolu depuis la racine du skill). Votre override pointe vers un fichier sous `{project-root}`, donc l’agent lit votre template à l’étape 4 au lieu de celui livré par défaut. - -**Conseils pour la rédaction de templates :** -- Gardez les templates dans `{project-root}/docs/` ou `{project-root}/_bmad/custom/templates/` pour qu’ils soient versionnés avec le fichier d’override -- Utilisez les mêmes conventions structurelles que le template livré (titres de sections, frontmatter) ; l’agent s’adapte à ce qu’il trouve -- Pour les dépôts multi-organisations, utilisez `.user.toml` pour permettre à chaque équipe de pointer vers ses propres templates sans toucher au fichier d’équipe versionné dans git - -## Recette 5 : Personnaliser le registre des agents - -**Cas d’usage :** Changer *qui sera présent dans la pièce* pour les skills basés sur le registre comme `bmad-party-mode`, `bmad-retrospective` et `bmad-advanced-elicitation`, sans modifier le code source ni forker. Voici trois variantes courantes. - -### 5a. Renommer un agent BMad pour toute l’organisation - -Chaque agent réel possède un descripteur que l’installateur synthétise à partir de `module.yaml`. Surchargez-le pour changer la voix et le cadrage pour tous les consommateurs du registre : - -```toml -# _bmad/custom/config.toml (versionné dans git — s'applique à tous les développeurs) - -[agents.bmad-agent-analyst] -description = "Mary l'Analyste d'Affaires sensible à la réglementation — s'inspire de Porter et Minto, mais vit et respire les pistes d'audit FDA. Parle comme un expert en criminalistique présentant un dossier." -``` - -Party-mode génère Mary avec la nouvelle description. L’activation de l’analyste elle-même fonctionne toujours normalement car le comportement de Mary se trouve dans son `customize.toml` par skill. Cet override change la façon dont **les skills externes la perçoivent et la présentent**, pas la façon dont elle travaille en interne. - -### 5b. Ajouter un agent fictif ou personnalisé - -Un descripteur complet suffit pour les fonctionnalités basées sur le registre, sans dossier de skill nécessaire. Utile pour varier les personnalités en mode party ou en session de brainstorming : - -```toml -# _bmad/custom/config.user.toml (personnel — ignoré par git) - -[agents.spock] -team = "startrek" -name = "Commander Spock" -title = "Science Officer" -icon = "🖖" -description = "Logique d'abord, émotion réprimée. Commence ses observations par 'Fascinant.' Ne force jamais le trait. Fait contrepoids à tout argument reposant sur l'intuition." - -[agents.mccoy] -team = "startrek" -name = "Dr. Leonard McCoy" -title = "Chief Medical Officer" -icon = "⚕️" -description = "Chaleur du médecin de campagne, caractère explosif. 'Bon sang Jim, je suis un docteur pas un ___.' Contrepoids éthique à Spock." -``` - -Demandez à party-mode d'« inviter l’équipage de l’Enterprise ». Il filtre par `team = "startrek"` et génère Spock et McCoy avec ces descripteurs. Les agents BMad réels (Mary, Amelia) peuvent se retrouver à la même table si vous les invitez. - -### 5c. Figer les paramètres d’installation de l’équipe - -L’installateur demande à chaque développeur des valeurs comme le chemin `planning_artifacts`. Quand l’organisation a besoin d’une réponse partagée, figez-la dans la configuration centrale — la réponse locale de chaque développeur est surchargée au moment de la résolution : - -```toml -# _bmad/custom/config.toml - -[modules.bmm] -planning_artifacts = "{project-root}/shared/planning" -implementation_artifacts = "{project-root}/shared/implementation" - -[core] -document_output_language = "English" -``` - -Les paramètres personnels comme `user_name`, `communication_language` ou `user_skill_level` restent dans leur propre fichier `_bmad/config.user.toml` de chaque développeur. Le fichier d’équipe ne doit pas les modifier. - -**Pourquoi la configuration centrale vs le customize.toml par agent :** Les fichiers par agent façonnent la façon dont *un seul* agent se comporte quand il s’active. La configuration centrale façonne ce que les consommateurs du registre *voient* : quels agents existent, comment ils s’appellent, à quelle équipe ils appartiennent, et les paramètres d’installation partagés sur lesquels tout le dépôt s’accorde. Deux surfaces, des rôles différents. - -## Renforcer les règles globales dans le fichier de session de votre IDE - -Les personnalisations BMad se chargent quand un skill est activé. Beaucoup d’outils IDE chargent aussi un fichier d’instructions global au **début de chaque session**, avant tout skill (`CLAUDE.md`, `AGENTS.md`, `.cursor/rules/`, `.github/copilot-instructions.md`, etc.). Pour les règles qui doivent s’appliquer même en dehors des skills BMad, reproduisez-y les plus critiques. - -**Quand les utiliser ensemble :** -- Une règle est suffisamment importante pour qu’une conversation simple (sans skill actif) doive la respecter -- Vous voulez une double sécurisation parce que les défauts des données d’entraînement pourraient autrement détourner le modèle -- La règle est assez concise pour être répétée sans alourdir le fichier de session - -**Exemple : une ligne dans le `CLAUDE.md` du dépôt renforçant la règle de l’agent dev de la Recette 1.** - -```markdown - -``` - -Une phrase, chargée à chaque session. Elle s’associe à la personnalisation `bmad-agent-dev.toml` pour que la règle s’applique à la fois dans les workflows d’Amelia et lors des chats ad hoc avec l’assistant. Chaque couche possède son propre périmètre : - -| Couche | Périmètre | Utilisée pour | -|----------------------------------------------------|----------------------------------------------------------|-------------------------------------------------------------------------| -| Fichier de session IDE (`CLAUDE.md` / `AGENTS.md`) | Chaque session, avant toute activation de skill | Règles courtes et universelles qui doivent survivre hors de BMad | -| Personnalisation d’agent BMad | Chaque workflow que l’agent dispatche | Comportement spécifique au persona de l’agent | -| Personnalisation de workflow BMad | Une exécution de workflow | Forme de sortie spécifique au workflow, hooks de publication, templates | -| Configuration centrale BMad | Registre des agents + paramètres d’installation partagés | Qui est dans la pièce et quels chemins partagés l’équipe utilise | - -Gardez le fichier IDE **concis**. Une douzaine de lignes bien choisies sont plus efficaces qu’une liste étendue. Les modèles le lisent à chaque tour, et le superflu noie l’information utile. - -## Recette 6 : Patterns d’intégration avancés - -Plusieurs workflows BMad exposent une surface de configuration plus riche au-delà des bases couvertes dans les Recettes 1–5. Ces patterns — sources de connaissance à la demande, publication automatique des livrables, standards de documentation à la finalisation et templates interchangeables — apparaissent dans plusieurs workflows. Consultez le `customize.toml` d’un workflow pour voir quels champs il expose ; les exemples ci-dessous utilisent `bmad-prd` car il les expose tous, mais les mêmes patterns s’appliquent partout où le champ apparaît. - -### Sources de connaissance à la demande (`external_sources`) - -Connectez le workflow à des bases de connaissances internes, des bases de données concurrentielles ou des référentiels de conformité. L’agent les consulte à la demande quand la conversation révèle un besoin correspondant — jamais par anticipation. - -```toml -# _bmad/custom/bmad-prd.toml (même pattern pour tout workflow exposant external_sources) - -[workflow] -external_sources = [ - "Quand l'utilisateur mentionne un concurrent ou un segment de marché, interroger corp:competitive_db (category={project_name}) avant de rédiger la section différenciation.", - "Pour les domaines réglementés (santé, fintech, éducation), consulter corp:compliance_reference avant de rédiger les sections spécifiques au domaine.", -] -``` - -Chaque entrée est une directive en langage naturel nommant l’outil MCP, la condition de déclenchement et les champs nécessaires. Si l’outil n’est pas disponible à l’exécution, le workflow se rabat sur le comportement standard et signale l’écart. - -### Publication automatique des livrables (`external_handoffs`) - -Acheminez les artefacts terminés vers les systèmes de référence externes après la finalisation du workflow. Contrairement à `on_complete` (Recette 3), `external_handoffs` est un tableau d’ajout dédié — les entrées d’équipe s’accumulent et chaque handoff se déclenche indépendamment avec dégradation progressive si un outil est indisponible. - -```toml -# _bmad/custom/bmad-prd.toml (même pattern pour tout workflow exposant external_handoffs) - -[workflow] -external_handoffs = [ - "Après la finalisation, uploader prd.md et addendum.md vers Confluence via corp:confluence_upload (space_key='PROD', parent_page='PRDs', label='prd', author={user_name}). Capturer et afficher l'URL de la page renvoyée.", - "Répliquer vers Notion via notion:create_page (database_id='abc123', title='PRD: ' + {project_name}).", -] -``` - -Si un outil nommé est indisponible, le handoff est ignoré et signalé — les fichiers locaux existent toujours indépendamment. - -### Standards de documentation à la finalisation (`doc_standards`) - -Appliquez les standards rédactionnels de l’organisation aux documents à destination des utilisateurs à la finalisation, après que le contenu est complet mais avant que l’utilisateur ne voie le livrable. Chaque entrée est une directive `skill:`, `file:` ou en texte brut ; les passes s’exécutent comme des sous-agents parallèles. - -```toml -# _bmad/custom/bmad-prd.toml (même pattern pour tout workflow exposant doc_standards) - -[workflow] -doc_standards = [ - "file:{project-root}/docs/enterprise/voice-and-tone.md", - "Toutes les dates doivent utiliser le format ISO 8601 (AAAA-MM-JJ).", - "Remplacer toute utilisation de 'tirer parti de' par 'utiliser'.", -] -``` - -`doc_standards` est un tableau d’ajout — les entrées d’équipe s’ajoutent aux valeurs par défaut livrées par le workflow. Les passes structurelles larges doivent venir avant les passes rédactionnelles plus ciblées. - -### Templates et checklists interchangeables - -Les workflows qui produisent des documents structurés exposent généralement des chemins de templates et de checklists comme scalaires surchargeables. Pointez-les vers des fichiers appartenant à l’organisation sous `{project-root}` pour imposer une structure différente sans modifier le code source. - -```toml -# _bmad/custom/bmad-prd.toml - -[workflow] -# Structure de PRD pour secteur réglementé -prd_template = "{project-root}/docs/enterprise/prd-template-hipaa.md" - -# Critères de validation spécifiques à l'organisation -validation_checklist = "{project-root}/docs/enterprise/prd-checklist-regulated.md" -``` - -L’agent s’adapte à la structure définie par le template. Gardez les templates sous `{project-root}/docs/` ou `{project-root}/_bmad/custom/templates/` pour qu’ils soient versionnés avec le fichier d’override. Pour les dépôts multi-organisations, utilisez `.user.toml` pour permettre aux équipes de pointer vers leurs propres templates sans toucher au fichier d’équipe versionné dans git. - -## Combiner les recettes - -Les six recettes se combinent librement. Un override entreprise réaliste pour `bmad-product-brief` pourrait définir `persistent_facts` (Recette 2), `on_complete` (Recette 3) et `brief_template` (Recette 4) dans un seul fichier. La règle au niveau agent (Recette 1) se trouve dans un fichier séparé sous le nom de l’agent, la configuration centrale (Recette 5) fige le registre partagé et les paramètres d’équipe, les patterns d’intégration avancés (Recette 6) configurent les sources externes et les handoffs, et toutes les couches s’appliquent en parallèle. - -```toml -# _bmad/custom/bmad-product-brief.toml (niveau workflow) - -[workflow] -persistent_facts = ["..."] -brief_template = "{project-root}/docs/enterprise/brief-template.md" -on_complete = """ ... """ -``` - -```toml -# _bmad/custom/bmad-agent-analyst.toml (niveau agent — Mary dispatche product-brief) - -[agent] -persistent_facts = ["Toujours inclure une section 'Revue réglementaire' quand le domaine implique la santé, la finance ou les données d'enfants."] -``` - -Résultat : Mary charge la règle de revue réglementaire à l’activation de son persona. Quand l’utilisateur choisit le product brief dans le menu, le workflow charge ses propres conventions par-dessus, écrit avec le template enterprise et publie vers Confluence à la fin. Chaque couche contribue, et aucune n’a nécessité de modifier le code source de BMad. - -## Dépannage - -**L’override ne prend pas effet ?** Vérifiez que le fichier se trouve sous `_bmad/custom/` avec le nom exact du répertoire du skill (ex. `bmad-agent-dev.toml`, pas `bmad-dev.toml`). Voir [Comment personnaliser BMad](./customize-bmad.md#dépannage). - -**Nom d’outil MCP inconnu ?** Utilisez le nom exact que le serveur MCP expose dans la session en cours. Demandez à Claude Code de lister les outils MCP disponibles en cas de doute. Les noms codés en dur dans `persistent_facts` ou `on_complete` ne fonctionneront pas si le serveur MCP n’est pas connecté. - -**Le pattern ne s’applique pas à ma configuration ?** Les recettes ci-dessus sont illustratives. L’infrastructure sous-jacente (fusion à trois couches, règles structurelles, agent traversant les workflows) supporte de nombreux patterns supplémentaires ; composez-les selon vos besoins. diff --git a/docs/fr/how-to/get-answers-about-bmad.md b/docs/fr/how-to/get-answers-about-bmad.md deleted file mode 100644 index a3358f4558..0000000000 --- a/docs/fr/how-to/get-answers-about-bmad.md +++ /dev/null @@ -1,81 +0,0 @@ ---- -title: 'Comment obtenir des réponses à propos de BMad' -description: Utiliser un LLM pour répondre rapidement à vos questions sur BMad -sidebar: - order: 4 ---- - -Utilisez l’aide intégrée de BMad, la documentation source ou la communauté pour obtenir des réponses — du plus rapide au plus approfondi. - -## 1. Demandez à BMad-Help - -Le moyen le plus rapide d’obtenir des réponses. Le skill `bmad-help` est disponible directement dans votre session IA et répond à plus de 80 % des questions — il inspecte votre projet, voit ce que vous avez accompli et vous dit quoi faire ensuite. - -``` -bmad-help J'ai une idée de SaaS et je connais toutes les fonctionnalités. Par où commencer ? -bmad-help Quelles sont mes options pour le design UX ? -bmad-help Je suis bloqué sur le workflow PRD -``` - -:::tip -Vous pouvez également utiliser `/bmad-help` ou `$bmad-help` selon votre plateforme, mais `bmad-help` tout seul devrait fonctionner partout. -::: - -## 2. Approfondissez avec les sources - -BMad-Help s’appuie sur votre configuration installée. Pour les questions sur les éléments internes de BMad, son historique ou son architecture — ou si vous faites des recherches sur BMad avant de l’installer — pointez votre IA directement vers les sources. - -Clonez ou ouvrez le [dépôt BMAD-METHOD](https://github.com/bmad-code-org/BMAD-METHOD) et posez vos questions à votre IA. Tout outil capable d’utiliser des agents (Claude Code, Cursor, Windsurf, etc.) peut lire les sources et répondre directement à vos questions. - -:::note[Exemple] -**Q :** « Quel est le moyen le plus rapide de construire quelque chose avec BMad ? » - -**R :** Lancez `bmad-build`. Donnez-lui une intention directe, une issue, une spécification ou une story planifiée ; il utilise le contexte disponible et choisit la profondeur de clarification, de planification, d’implémentation et de revue nécessaire. -::: - -**Conseils pour de meilleures réponses :** - -- **Soyez précis** — « Que fait l’étape 3 du workflow PRD ? » est mieux que « Comment fonctionne le PRD ? » -- **Vérifiez les affirmations surprenantes** — Les LLM font parfois des erreurs. Consultez le fichier source ou posez la question sur Discord. - -### Vous n’utilisez pas d’agent ? Utilisez le site de documentation - -Si votre IA ne peut pas lire des fichiers locaux (ChatGPT, Claude.ai, etc.), ouvrez [le site de documentation BMad](https://docs.bmad-method.org/). - -## 3. Demandez à quelqu’un - -Si ni BMad-Help ni la source n’ont répondu à votre question, vous avez maintenant une bien meilleure question à poser. - -| Canal | Utilisé pour | -| ----------------------- | ------------------------------------ | -| Forum `help-requests` | Questions | -| `#suggestions-feedback` | Idées et demandes de fonctionnalités | - -**Discord :** [discord.gg/gk8jAdXWmj](https://discord.gg/gk8jAdXWmj) - -**GitHub Issues :** [github.com/bmad-code-org/BMAD-METHOD/issues](https://github.com/bmad-code-org/BMAD-METHOD/issues) - -_Toi !_ -  _Bloqué_ -    _dans la file d’attente—_ -      _qui_ -        _attends-tu ?_ - -_La source_ -  _est là,_ -    _facile à voir !_ - -_Pointez_ -  _votre machine._ -    _Libérez-la._ - -_Elle lit._ -  _Elle parle._ -    _Demandez—_ - -_Pourquoi attendre_ -  _demain_ -    _quand tu as déjà_ -      _cette journée ?_ - -        _—Claude_ diff --git a/docs/fr/how-to/install-bmad.md b/docs/fr/how-to/install-bmad.md deleted file mode 100644 index 028b33d644..0000000000 --- a/docs/fr/how-to/install-bmad.md +++ /dev/null @@ -1,266 +0,0 @@ ---- -title: "Comment installer BMad" -description: Installer, mettre à jour et épingler BMad pour le développement local, les équipes et CI -sidebar: - order: 1 ---- - -Utilisez `npx bmad-method install` pour configurer BMad dans votre projet. Une seule commande gère les premières installations, les mises à niveau, le changement de canal et les exécutions CI scriptées. Cette page couvre tout cela. - -## Quand l’utiliser - -- Démarrer un nouveau projet avec BMad -- Ajouter ou retirer des modules sur une installation existante -- Basculer un module sur main-HEAD ou l’épingler à une version spécifique -- Scripter des installations pour des pipelines CI, des Dockerfiles ou des déploiements en entreprise - -:::note[Prérequis] - -- **Node.js** 20.12+ (requis pour l’installateur) -- **Git** (pour cloner les modules externes) -- **Un outil d’IA** tel que Claude Code ou Cursor (exécutez `npx bmad-method install --list-tools` pour voir tous les outils supportés) - -::: - -## Première installation (méthode rapide) - -```bash -npx bmad-method install -``` - -L’assistant interactif vous pose cinq questions : - -1. Le répertoire d’installation (par défaut le répertoire de travail courant) -2. Quels modules installer (cases à cocher pour core, bmm, bmb, cis, gds, tea) -3. **« Ready to install (all stable)? »** — Oui accepte le dernier tag publié pour chaque module externe -4. Quels outils/IDE d’IA intégrer (claude-code, cursor et d’autres) -5. La configuration par module (nom, langue, dossier de sortie) - -En acceptant les valeurs par défaut, vous obtenez la dernière version stable de chaque module, configurée pour votre outil choisi. - -:::tip[Vous voulez juste la dernière préversion ?] - -```bash -npx bmad-method@next install -``` - -Exécute l’installateur de préversion, qui fournit un snapshot plus récent de core et bmm. Davantage de changements, avec un délai réduit entre le développement et la publication. -::: - -## Choisir une version spécifique - -Deux axes indépendants contrôlent ce qui se retrouve sur le disque. - -### Axe 1 : canaux des modules externes - -Chaque module externe — bmb, cis, gds, tea, et tout module communautaire — s’installe via l’un des trois canaux suivants : - -| Canal | Ce qui est installé | Pour qui | -|-------------------|--------------------------------------------------------------------------------------|-----------------------------------------------| -| `stable` (défaut) | Le plus haut tag semver publié. Les préversions comme `v2.0.0-alpha.1` sont exclues. | La plupart des utilisateurs | -| `next` | Le HEAD de la branche main au moment de l’installation | Contributeurs, early adopters | -| `pinned` | Un tag spécifique de votre choix | Installations entreprise, reproductibilité CI | - -Les canaux sont définis module par module. Vous pouvez exécuter bmb sur `next` tout en laissant cis sur `stable` — les options ci-dessous permettent de les combiner librement. - -### Axe 2 : version du binaire de l’installateur - -Le paquet npm `bmad-method` lui-même a deux dist-tags : - -| Commande | Ce que vous obtenez | -|---------------------------------------|---------------------------------------------------------------------------------------| -| `npx bmad-method install` (`@latest`) | Dernière version stable de l’installateur | -| `npx bmad-method@next install` | Dernière préversion de l’installateur, publiée automatiquement à chaque push sur main | - -**Le binaire de l’installateur détermine vos versions de core et bmm.** Ces deux modules sont embarqués dans le paquet de l’installateur plutôt que clonés depuis des dépôts séparés. - -### Pourquoi core et bmm n’ont pas leur propre canal - -Ils sont liés au binaire de l’installateur que vous avez exécuté : - -- `npx bmad-method install` → core et bmm stables les plus récents -- `npx bmad-method@next install` → core et bmm en préversion -- `node /chemin/vers/checkout-local/tools/installer/bmad-cli.js install` → ce que votre checkout local contient - -`--pin bmm=v6.3.0` et `--next=bmm` n’ont aucun effet sur les modules intégrés (l’installateur vous avertit si vous tentez de les utiliser). Une prochaine version détachera bmm du paquet de l’installateur ; une fois publiée, bmm disposera d’un sélecteur de canal dédié, comme c’est le cas pour bmb aujourd’hui. - -## Mettre à jour une installation existante - -Exécuter `npx bmad-method install` dans un répertoire contenant déjà `_bmad/` affiche un menu : - -| Choix | Ce qu’il fait | -|--------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| **Quick Update** | Réexécute l’installation avec vos paramètres existants. Rafraîchit les fichiers, applique les correctifs et les mises à niveau mineures du canal stable, refuse les mises à niveau majeures. Rapide, non interactif. | -| **Modify Install** | Flux interactif complet. Ajoutez ou retirez des modules, reconfigurez les paramètres, examinez et, si besoin, modifiez les canaux des modules existants. | - -### Invites de mise à niveau - -Quand Modify détecte un tag stable plus récent pour un module que vous avez installé sur `stable`, il classe le diff et vous invite en conséquence : - -| Type de mise à niveau | Exemple | Défaut | -| --------------------- | --------------- | ------ | -| Patch | v1.7.0 → v1.7.1 | O | -| Mineure | v1.7.0 → v1.8.0 | O | -| Majeure | v1.7.0 → v2.0.0 | **N** | - -Les mises à niveau majeures sont refusées par défaut (N) car les changements cassants se manifestent souvent comme une « instabilité » quand ils ne sont pas attendus. L’invite inclut une URL vers les notes de version GitHub pour que vous puissiez lire ce qui a changé avant d’accepter. - -Avec `--yes`, les mises à niveau patch et mineure s’appliquent automatiquement. Les majeures restent bloquées — utilisez `--pin =` pour les accepter de manière non interactive. - -### Changer le canal d’un module - -**En mode interactif :** choisissez Modify → répondez **Oui** à « Review channel assignments? » → chaque module externe offre Conserver, Basculer vers stable, Basculer vers next, ou Épingler à un tag. - -**En ligne de commande :** les recettes dans la section suivante couvrent les cas courants. - -## Installations CI non interactives - -### Référence des options - -| Option | Objectif | -|--------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `--yes`, `-y` | Ignorer toutes les invites ; accepter les valeurs des options + les défauts | -| `--directory ` | Installer dans ce répertoire (défaut : répertoire de travail courant) | -| `--modules ` | Ensemble exact de modules. Core est ajouté automatiquement. Ce n’est pas un delta — listez tout ce que vous voulez conserver. | -| `--tools ` | Sélection d’IDE/outil. Requis pour les nouvelles installations `--yes`. Exécutez `--list-tools` pour les IDs valides. | -| `--list-tools` | Afficher tous les IDs d’outils/IDE supportés (avec les répertoires cibles) et quitter. | -| `--action ` | `install`, `update` ou `quick-update`. La valeur par défaut dépend de l’état de l’installation. | -| `--custom-source ` | Installer des modules personnalisés depuis des URLs Git ou des chemins locaux | -| `--channel ` | Appliquer à tous les externes (alias `--all-stable` / `--all-next`) | -| `--all-stable` | Alias pour `--channel=stable` | -| `--all-next` | Alias pour `--channel=next` | -| `--next=` | Mettre un module sur next. Répétable. | -| `--pin =` | Épingler un module à un tag spécifique. Répétable. | -| `--set .=` | Définir toute option de config de module de manière non interactive (recommandé — voir [Substitutions de config de module](#substitutions-de-config-de-module)). Répétable. | -| `--list-options [module]` | Afficher chaque clé `--set` pour les modules intégrés et officiels en cache local, puis quitter. Passez un code de module pour limiter à un seul module. | -| `--user-name`, `--communication-language`, `--document-output-language`, `--output-folder` | Raccourcis historiques équivalents à `--set core.=` (toujours supportés) | - -Priorité en cas de chevauchement des options : `--pin` bat `--next=` bat `--channel` / `--all-*` bat le défaut du registre (`stable`). - -:::note[Exemple de résolution] -`--all-next --pin cis=v0.2.0` met bmb, gds et tea sur next tout en épinglant cis à v0.2.0. -::: - -### Recettes - -**Installation par défaut — dernière version stable pour tout :** - -```bash -npx bmad-method install --yes --modules bmm,bmb,cis --tools claude-code -``` - -**Installation entreprise verrouillée — reproductible à l’octet près :** - -```bash -npx bmad-method install --yes \ - --modules bmm,bmb,cis \ - --pin bmb=v1.7.0 --pin cis=v0.2.0 \ - --tools claude-code -``` - -**Bleeding edge — externes sur le HEAD de main :** - -```bash -npx bmad-method install --yes --modules bmm,bmb --all-next --tools claude-code -``` - -**Ajouter un module à une installation existante** (conserver tout le reste) : - -```bash -npx bmad-method install --yes --action update \ - --modules bmm,bmb,gds -``` - -`--tools` est omis intentionnellement — `--action update` réutilise les outils configurés lors de la première installation. - -**Mixer les canaux — bmb sur next, gds sur stable :** - -```bash -npx bmad-method install --yes --action update \ - --modules bmm,bmb,cis,gds \ - --next=bmb -``` - -### Substitutions de config de module - -`--set .=` vous permet de définir toute option de config de module de manière non interactive. Cette option est répétable et s’adapte à chaque module — présent et futur. L’option est appliquée comme un correctif post-installation : l’installateur exécute d’abord son flux normal, puis `--set` insère ou met à jour chaque valeur dans `_bmad/config.toml` (portée équipe) ou `_bmad/config.user.toml` (portée utilisateur), et dans `_bmad//config.yaml` pour que les valeurs déclarées soient conservées à la prochaine installation. - -**Exemple — installer bmm avec des connaissances projet et un niveau de compétence explicites :** - -```bash -npx bmad-method install --yes \ - --modules bmm \ - --tools claude-code \ - --set bmm.project_knowledge=research \ - --set bmm.user_skill_level=expert -``` - -**Découvrir les clés disponibles pour un module :** - -```bash -npx bmad-method install --list-options bmm -``` - -`--list-options` (sans argument) liste chaque clé que l’installateur peut trouver localement — modules intégrés (`core`, `bmm`) plus tous les modules officiels actuellement en cache. Le cache est par machine et peut être vidé, donc les modules officiels précédemment installés n’apparaîtront pas sur un nouveau checkout ou un worker CI éphémère tant qu’ils ne sont pas réinstallés. Les modules communautaires et personnalisés ne sont pas énumérés ici ; lisez directement le `module.yaml` du module pour voir les clés qu’il déclare. - -**Comment ça fonctionne :** - -- **Routage.** L’étape de correctif cherche `[modules.] ` (ou `[core] `) dans `config.user.toml` en premier ; si elle y est trouvée, elle met à jour ce fichier. Sinon elle écrit dans le `config.toml` de portée équipe. Ainsi, les clés de portée utilisateur (ex. `core.user_name`, `bmm.user_skill_level`) finissent dans `config.user.toml` et les clés de portée équipe dans `config.toml`, correspondant à la partition utilisée par l’installateur. -- **Valeurs littérales.** La valeur est écrite exactement comme vous l’avez fournie — aucun rendu de template `result:`. Pour obtenir la valeur résolue (ex. `{project-root}/research`), passez-la explicitement : `--set bmm.project_knowledge='{project-root}/research'`. -- **Persistance, clés déclarées.** Les valeurs pour les clés déclarées dans `module.yaml` sont conservées entre les installations car elles sont aussi écrites dans `_bmad//config.yaml`, que l’installateur lit comme valeur par défaut de l’invite lors de la prochaine exécution. -- **Persistance, clés non déclarées.** Une valeur pour une clé que le schéma du module ne déclare pas est enregistrée dans `config.toml` pour l’installation courante mais ne sera pas réécrite à la prochaine installation (le partitionneur strict au schéma du manifeste ignore les clés inconnues). Repassez `--set` pour qu’elle soit persistante, ou éditez `_bmad/config.toml` directement. -- **Pas de validation.** Les valeurs `single-select` ne sont pas vérifiées contre les choix autorisés, et les clés inconnues ne sont pas rejetées — la valeur fournie est écrite telle quelle. -- **Modules non présents dans `--modules`.** Définir une valeur pour un module que vous n’avez pas inclus affiche un avertissement et la valeur est ignorée (aucun fichier n’est créé pour un module non installé). - -Les raccourcis historiques de core (`--user-name`, `--output-folder`, etc.) fonctionnent toujours et restent documentés pour la rétrocompatibilité, mais `--set core.user_name=...` est équivalent. - -:::note[Fonctionne avec quick-update] -`--set` est un correctif post-installation, il s’applique donc de la même manière quel que soit le type d’action. Avec `bmad install --action quick-update` (ou `--yes` sur une installation existante, où quick-update est le défaut), `--set` met à jour les fichiers de configuration centraux à la fin comme une installation normale. -::: - -:::caution[Limitation de débit sur les IPs partagées] -Les appels anonymes à l’API GitHub sont limités à 60/heure par IP. Une seule installation fait un appel API par module externe pour résoudre le tag stable. Les bureaux derrière NAT, les pools de runners CI et les VPN peuvent collectivement épuiser cette limite. - -Définissez `GITHUB_TOKEN=` dans l’environnement pour augmenter la limite à 5 000/heure par compte. Tout PAT avec accès en lecture aux dépôts publics fonctionne ; aucune portée spécifique n’est requise. -::: - -## Ce qui a été installé - -Après toute installation, `_bmad/_config/manifest.yaml` enregistre exactement ce qui est sur le disque : - -```yaml -modules: - - name: bmb - version: v1.7.0 # le tag, ou "main" pour next - channel: stable # stable | next | pinned - sha: 86033fc9aeae2ca6d52c7cdb675c1f4bf17fc1c1 - source: external - repoUrl: https://github.com/bmad-code-org/bmad-builder -``` - -Le champ `sha` est écrit pour les modules basés sur git (externes, communautaires et personnalisés par URL). Les modules intégrés (core, bmm) et les modules personnalisés par chemin local n’en ont pas — leur code voyage avec le binaire de l’installateur ou votre système de fichiers, pas un ref clonable. - -Pour la reproductibilité inter-machines, ne comptez pas sur la réexécution de la même commande `--modules`. Les installations sur canal stable résolvent vers le plus haut tag publié **au moment de l’installation**, donc une réexécution ultérieure obtiendra les versions publiées entre-temps. Convertissez les tags enregistrés de `manifest.yaml` en options `--pin` explicites sur la machine cible, par ex. : - -```bash -npx bmad-method install --yes --modules bmb,cis \ - --pin bmb=v1.7.0 --pin cis=v0.4.2 --tools claude-code -``` - -## Résolution de problèmes - -### « Could not resolve stable tag » ou « API rate limit exceeded » - -Vous avez atteint la limite anonyme de 60/heure de GitHub. Définissez `GITHUB_TOKEN` et réessayez. Si vous avez déjà un token défini, il peut être expiré ou limité sur son propre budget — essayez un token différent ou attendez la réinitialisation horaire. - -### « Tag ’vX.Y.Z' not found » - -Le tag que vous avez passé à `--pin` n’existe pas dans le dépôt du module. Consultez la page des releases du dépôt sur GitHub pour les tags valides. - -### Une installation épinglée continue de se mettre à niveau - -Les installations épinglées ne se mettent pas à niveau. Quick-update applique les correctifs et les mises à niveau mineures uniquement sur le canal stable ; il ne touche pas `pinned` ou `next`. Si une installation épinglée a changé, ouvrez `_bmad/_config/manifest.yaml` — `channel: pinned` plus un `version` et `sha` fixes doivent rester stables d’une exécution à l’autre, sauf écrasement explicite via les options. - -### `--pin bmm=X` n’a rien fait - -bmm est un module intégré — `--pin` et `--next=` ne s’appliquent pas. Utilisez `npx bmad-method@next install` pour un core/bmm en préversion, ou clonez le dépôt bmad-bmm et exécutez l’installateur localement pour obtenir les modifications non publiées. diff --git a/docs/fr/how-to/install-custom-modules.md b/docs/fr/how-to/install-custom-modules.md deleted file mode 100644 index d6ff50faee..0000000000 --- a/docs/fr/how-to/install-custom-modules.md +++ /dev/null @@ -1,181 +0,0 @@ ---- -title: "Installer des modules personnalisés et communautaires" -description: Installer des modules tiers depuis le registre communautaire, des dépôts Git ou des chemins locaux -sidebar: - order: 2 ---- - -Utilisez l’installateur BMad pour ajouter des modules depuis le registre communautaire, des dépôts Git tiers ou des chemins locaux. - -## Quand l’utiliser - -- Installer un module contribué par la communauté depuis le registre BMad -- Installer un module depuis un dépôt Git tiers (GitHub, GitLab, Bitbucket, auto-hébergé) -- Tester un module que vous développez localement avec BMad Builder -- Installer des modules depuis un serveur Git privé ou auto-hébergé - -:::note[Prérequis] -Nécessite [Node.js](https://nodejs.org) v20.12+ et `npx` (inclus avec npm). Les modules personnalisés et communautaires peuvent être sélectionnés lors d’une nouvelle installation ou ajoutés à une installation existante. -::: - -## Modules communautaires - -Les modules communautaires sont regroupés dans le [marketplace de plugins BMad](https://github.com/bmad-code-org/bmad-plugins-marketplace). Ils sont organisés par catégorie et épinglés à un commit approuvé pour des raisons de sécurité. - -### 1. Lancer l’installateur - -```bash -npx bmad-method install -``` - -### 2. Parcourir le catalogue communautaire - -Après avoir sélectionné les modules officiels, l’installateur demande : - -``` -Would you like to browse community modules? -``` - -Sélectionnez **Yes** pour accéder au navigateur de catalogue. Vous pouvez : - -- Parcourir par catégorie -- Voir les modules phares -- Voir tous les modules disponibles -- Rechercher par mot-clé - -### 3. Sélectionner des modules - -Choisissez des modules dans n’importe quelle catégorie. L’installateur affiche les descriptions, versions et niveaux de confiance. Les modules déjà installés sont pré-sélectionnés pour la mise à jour. - -### 4. Poursuivre l’installation - -Après avoir sélectionné les modules communautaires, l’installateur passe aux sources personnalisées, puis à la configuration des outils/IDE et au reste du flux d’installation. - -## Sources personnalisées (URL Git et chemins locaux) - -Les modules personnalisés peuvent provenir de n’importe quel dépôt Git ou d’un répertoire local sur votre machine. L’installateur résout la source, analyse la structure du module et l’installe aux côtés de vos autres modules. - -### Installation interactive - -Durant l’installation, après l’étape des modules communautaires, l’installateur demande : - -``` -Would you like to install from a custom source (Git URL or local path)? -``` - -Sélectionnez **Yes**, puis indiquez une source : - -| Type d’entrée | Exemple | -| ------------------------- | ------------------------------------------------- | -| URL HTTPS (tout hôte) | `https://github.com/org/repo` | -| URL HTTP (tout hôte) | `http://host/org/repo` | -| URL HTTPS avec sous-rép. | `https://github.com/org/repo/tree/main/my-module` | -| URL SSH | `git@github.com:org/repo.git` | -| Chemin local | `/Users/me/projects/my-module` | -| Chemin local avec tilde | `~/projects/my-module` | - -L’installateur clone le dépôt (pour les URL) ou lit directement depuis le disque (pour les chemins locaux), puis présente les modules découverts pour la sélection. - -### Installation non interactive - -Utilisez l’option `--custom-source` pour installer des modules personnalisés depuis la ligne de commande : - -```bash -npx bmad-method install \ - --directory . \ - --custom-source /path/to/my-module \ - --tools claude-code \ - --yes -``` - -Quand `--custom-source` est fourni sans `--modules`, seuls le cœur et les modules personnalisés sont installés. Pour inclure également les modules officiels, ajoutez `--modules` : - -```bash -npx bmad-method install \ - --directory . \ - --modules bmm \ - --custom-source https://gitlab.com/myorg/my-module \ - --tools claude-code \ - --yes -``` - -Plusieurs sources peuvent être séparées par des virgules : - -```bash ---custom-source /path/one,https://github.com/org/repo,/path/two -``` - -## Fonctionnement de la découverte de modules - -L’installateur utilise deux modes pour trouver les modules installables dans une source : - -| Mode | Déclencheur | Comportement | -|------------|------------------------------------------------------|------------------------------------------------------------------------------------------------------------------| -| Découverte | La source contient `.claude-plugin/marketplace.json` | Liste tous les plugins du manifeste ; vous choisissez lesquels installer | -| Direct | Aucun `marketplace.json` trouvé | Analyse le répertoire pour trouver des skills (sous-répertoires avec `SKILL.md`), les résout en un module unique | - -Le mode découverte est typique des modules publiés. Le mode direct est pratique pour pointer vers un répertoire de skills pendant le développement local. - -:::note[À propos de `.claude-plugin/`] -Le chemin `.claude-plugin/marketplace.json` est une convention standard adoptée par plusieurs installateurs d’outils IA pour la découvabilité des plugins. Il ne nécessite pas Claude, n’utilise pas les API Claude et n’a aucun impact sur l’outil d’IA que vous utilisez. Tout module contenant ce fichier peut être découvert par tout installateur suivant cette convention. -::: - -## Flux de travail en développement local - -Si vous construisez un module avec [BMad Builder](https://github.com/bmad-code-org/bmad-builder), vous pouvez l’installer directement depuis votre répertoire de travail : - -```bash -npx bmad-method install \ - --directory ~/my-project \ - --custom-source ~/my-module-repo/skills \ - --tools claude-code \ - --yes -``` - -Les sources locales sont référencées par leur chemin, non copiées dans un cache. Lorsque vous mettez à jour la source de votre module et réinstallez, l’installateur récupère les dernières modifications. - -:::caution[Suppression de la source] -Si vous supprimez le répertoire source local après l’installation, les fichiers du module installé dans `_bmad/` sont préservés. Le module sera ignoré lors des mises à jour tant que le chemin source n’est pas restauré. -::: - -## Ce que vous obtenez - -Après l’installation, les modules personnalisés apparaissent dans `_bmad/` aux côtés des modules officiels : - -``` -your-project/ -├── _bmad/ -│ ├── core/ # Module cœur intégré -│ ├── bmm/ # Module officiel (si sélectionné) -│ ├── my-module/ # Votre module personnalisé -│ │ ├── my-skill/ -│ │ │ └── SKILL.md -│ │ └── module-help.csv -│ └── _config/ -│ └── manifest.yaml # Suit tous les modules, versions et sources -└── ... -``` - -Le manifeste enregistre la source de chaque module personnalisé (`repoUrl` pour les sources Git, `localPath` pour les sources locales) afin que les mises à jour rapides puissent localiser la source à nouveau. - -## Mettre à jour les modules personnalisés - -Les modules personnalisés participent au flux de mise à jour normal : - -- **Mise à jour rapide** (`--action quick-update`) : Rafraîchit tous les modules depuis leurs sources d’origine. Les modules Git sont re-téléchargés ; les modules locaux sont relus depuis leur chemin source. -- **Mise à jour complète** : Relance la sélection de modules pour que vous puissiez ajouter ou retirer des modules personnalisés. - -## Créer vos propres modules - -Utilisez [BMad Builder](https://github.com/bmad-code-org/bmad-builder) pour créer des modules que d’autres pourront installer : - -1. Exécutez `bmad-module-builder` pour générer la structure de votre module -2. Ajoutez des skills, agents et workflows avec les divers outils BMad Builder -3. Publiez dans un dépôt Git ou partagez le dossier -4. D’autres installent avec `--custom-source ` - -Pour que les modules supportent le mode découverte, incluez un fichier `.claude-plugin/marketplace.json` à la racine de votre dépôt (c’est une convention multi-outils, pas spécifique à Claude). Consultez la [documentation BMad Builder](https://github.com/bmad-code-org/bmad-builder) pour le format du fichier `marketplace.json`. - -:::tip[Tester localement d’abord] -Pendant le développement, installez votre module avec un chemin local pour itérer rapidement avant de publier dans un dépôt Git. -::: diff --git a/docs/fr/how-to/project-context.md b/docs/fr/how-to/project-context.md deleted file mode 100644 index d8c76e78ef..0000000000 --- a/docs/fr/how-to/project-context.md +++ /dev/null @@ -1,127 +0,0 @@ ---- -title: "Gérer le contexte du projet" -description: Créer et maintenir project-context.md pour guider les agents IA -sidebar: - order: 8 ---- - -Utilisez le fichier `project-context.md` pour garantir que les agents IA respectent les préférences techniques et les règles d’implémentation de votre projet tout au long des workflows. Pour vous assurer qu’il est toujours disponible, vous pouvez également ajouter la ligne `Le contexte et les conventions importantes du projet se trouvent dans [chemin vers le contexte du projet]/project-context.md` à votre fichier de contexte ou de règles permanentes (comme `AGENTS.md`). - -:::note[Prérequis] -- Méthode BMad installée -- Connaissance de la pile technologique et des conventions de votre projet -::: - -## Quand utiliser cette fonctionnalité - -- Vous avez des préférences techniques fortes avant de commencer l’architecture -- Vous avez terminé l’architecture et souhaitez consigner les décisions pour l’implémentation -- Vous travaillez sur une base de code existante avec des patterns établis -- Vous remarquez que les agents prennent des décisions incohérentes entre les stories - -## Étape 1 : Choisissez votre approche - -**Création manuelle** — Idéal lorsque vous savez exactement quelles règles vous souhaitez documenter - -**Génération après l’architecture** — Idéal pour capturer les décisions prises lors du solutioning - -**Génération pour les projets existants** — Idéal pour découvrir les patterns dans les bases de code existantes - -## Étape 2 : Créez le fichier - -### Option A : Création manuelle - -Créez le fichier à l’emplacement `_bmad-output/project-context.md` : - -```bash -mkdir -p _bmad-output -touch _bmad-output/project-context.md -``` - -Ajoutez votre pile technologique et vos règles d’implémentation : - -```markdown ---- -project_name: 'MonProjet' -user_name: 'VotreNom' -date: '2026-02-15' -sections_completed: ['technology_stack', 'critical_rules'] ---- - -# Contexte de Projet pour Agents IA - -## Pile Technologique & Versions - -- Node.js 20.x, TypeScript 5.3, React 18.2 -- State : Zustand -- Tests : Vitest, Playwright -- Styles : Tailwind CSS - -## Règles d'Implémentation Critiques - -**TypeScript :** -- Mode strict activé, pas de types `any` -- Utiliser `interface` pour les API publiques, `type` pour les unions - -**Organisation du Code :** -- Composants dans `/src/components/` avec tests co-localisés -- Les appels API utilisent le singleton `apiClient` — jamais de fetch direct - -**Tests :** -- Tests unitaires axés sur la logique métier -- Tests d'intégration utilisent MSW pour le mock API -``` - -### Option B : Génération après l’architecture - -Exécutez le workflow dans une nouvelle conversation : - -```bash -bmad-generate-project-context -``` - -Le workflow analyse votre document d’architecture et vos fichiers projet pour générer un fichier de contexte qui capture les décisions prises. - -### Option C : Génération pour les projets existants - -Pour les projets existants, exécutez : - -```bash -bmad-generate-project-context -``` - -Le workflow analyse votre base de code pour identifier les conventions, puis génère un fichier de contexte que vous pouvez réviser et affiner. - -## Étape 3 : Vérifiez le contenu - -Révisez le fichier généré et assurez-vous qu’il capture : - -- Les versions correctes des technologies -- Vos conventions réelles (pas les bonnes pratiques génériques) -- Les règles qui évitent les erreurs courantes -- Les patterns spécifiques aux frameworks - -Modifiez manuellement pour ajouter les éléments manquants ou supprimer les inexactitudes. - -## Ce que vous obtenez - -Un fichier `project-context.md` qui : - -- Garantit que tous les agents suivent les mêmes conventions -- Évite les décisions incohérentes entre les stories -- Capture les décisions d’architecture pour l’implémentation -- Sert de référence pour les patterns et règles de votre projet - -## Conseils - -:::tip[Bonnes pratiques] -- **Concentrez-vous sur ce qui n’est pas évident** — Documentez les patterns que les agents pourraient manquer (par ex. « Utiliser JSDoc sur chaque classe publique »), et non les pratiques universelles comme « utiliser des noms de variables significatifs ». -- **Gardez-le concis** — Ce fichier est chargé par chaque workflow d’implémentation. Les fichiers longs gaspillent le contexte. Excluez le contenu qui ne s’applique qu’à un périmètre restreint ou à des stories spécifiques. -- **Mettez à jour si nécessaire** — Modifiez manuellement lorsque les patterns changent, ou régénérez après des changements d’architecture significatifs. -- Prend en charge la même boucle `bmad-build`, que le travail entre directement ou après une planification approfondie. -::: - -## Prochaines étapes - -- [**Explication du contexte projet**](../explanation/project-context.md) — En savoir plus sur son fonctionnement -- [**Carte des workflows**](../reference/workflow-map.md) — Voir quels workflows chargent le contexte projet diff --git a/docs/fr/how-to/quick-fixes.md b/docs/fr/how-to/quick-fixes.md deleted file mode 100644 index 7d2201e415..0000000000 --- a/docs/fr/how-to/quick-fixes.md +++ /dev/null @@ -1,98 +0,0 @@ ---- -title: "Corrections Rapides" -description: Comment effectuer des corrections rapides et des modifications ciblées -sidebar: - order: 5 ---- - -Les corrections de bugs, refactorisations et petites modifications ciblées peuvent entrer directement dans **Build** avec peu ou pas de planification amont. C’est le même workflow d’implémentation que pour les stories entièrement planifiées. - -## Quand Utiliser Cette Approche - -- Corrections de bugs avec une cause claire et connue -- Petites refactorisations (renommage, extraction, restructuration) contenues dans quelques fichiers -- Ajustements mineurs de fonctionnalités ou modifications de configuration -- Mises à jour de dépendances - -:::note[Prérequis] -- Méthode BMad installée (`npx bmad-method install`) -- Un IDE IA (Claude Code, Cursor, ou similaire) -::: - -## Étapes - -### 1. Démarrer une Nouvelle Conversation - -Ouvrez une **nouvelle conversation** dans votre IDE IA. Réutiliser une session d’un workflow précédent peut causer des conflits de contexte. - -### 2. Spécifiez Votre Intention - -Build accepte l’intention en forme libre — avant, avec, ou après l’invocation. Exemples : - -```text -build — Corrige le bug de validation de connexion qui permet les mots de passe vides. -``` - -```text -build — corrige https://github.com/org/repo/issues/42 -``` - -```text -build — implémente _bmad-output/implementation-artifacts/my-intent.md -``` - -```text -Je pense que le problème est dans le middleware d'auth, il ne vérifie pas l'expiration du token. -Regardons... oui, src/auth/middleware.ts ligne 47 saute complètement la vérification exp. lance build -``` - -```text -build -> Que voulez-vous faire ? -Refactoriser UserService pour utiliser async/await au lieu des callbacks. -``` - -Texte brut, chemins de fichiers, URLs d’issues GitHub, liens de trackers de bugs — tout ce que le LLM peut résoudre en une intention concrète. - -### 3. Répondre aux Questions et Approuver - -Build peut poser des questions de clarification ou présenter une courte spécification demandant votre approbation avant l’implémentation. Répondez à ses questions et approuvez lorsque vous êtes satisfait du plan. - -### 4. Réviser et Pousser - -Build implémente la modification, révise son propre travail, corrige les problèmes et effectue un commit local. Lorsqu’il a terminé, il ouvre les fichiers affectés dans votre éditeur. - -- Parcourez le diff pour confirmer que la modification correspond à votre intention -- Si quelque chose semble incorrect, dites à l’agent ce qu’il faut corriger — il peut itérer dans la même session - -Une fois satisfait, poussez le commit. Build vous proposera de pousser et de créer une PR pour vous. - -:::caution[Si Quelque Chose Casse] -Si une modification poussée cause des problèmes inattendus, utilisez `git revert HEAD` pour annuler proprement le dernier commit. Ensuite, démarrez une nouvelle conversation et exécutez Build à nouveau pour essayer une approche différente. -::: - -## Ce Que Vous Obtenez - -- Fichiers source modifiés avec la correction ou refactorisation appliquée -- Tests passants (si votre projet a une suite de tests) -- Un commit prêt à pousser avec un message de commit conventionnel - -## Travail Différé - -Build garde chaque exécution concentrée sur un seul objectif. Si votre demande contient plusieurs objectifs indépendants, ou si la revue remonte des problèmes préexistants non liés à votre modification, Build les diffère vers un fichier (`deferred-work.md` dans votre répertoire d’artefacts d’implémentation) plutôt que d’essayer de tout régler en même temps. - -Consultez ce fichier après une exécution — c’est votre backlog[^1] de choses sur lesquelles revenir. Chaque élément différé peut être introduit dans une nouvelle exécution Build ultérieurement. - -## Quand Ajouter une Planification Formelle - -Avant d’exécuter la même boucle Build, envisagez d’ajouter un PRD, une UX, une architecture ou une planification des stories lorsque : - -- La modification affecte plusieurs systèmes ou nécessite des mises à jour coordonnées dans de nombreux fichiers -- Vous n’êtes pas sûr de la portée et avez besoin d’une découverte des exigences d’abord -- Vous avez besoin de documentation ou de décisions architecturales enregistrées pour l’équipe - -Voir [Build](../explanation/build.md) pour comprendre comment l’intention directe et le travail planifié convergent vers la même boucle d’implémentation. - -## Glossaire - -[^1]: Backlog : liste priorisée de tâches ou d’éléments de travail à traiter ultérieurement, issue des méthodologies agiles. diff --git a/docs/fr/how-to/upgrade-to-v6.md b/docs/fr/how-to/upgrade-to-v6.md deleted file mode 100644 index 3a9603fed1..0000000000 --- a/docs/fr/how-to/upgrade-to-v6.md +++ /dev/null @@ -1,107 +0,0 @@ ---- -title: "Comment passer à la v6" -description: Migrer de BMad v4 vers v6 -sidebar: - order: 3 ---- - -Utilisez l’installateur BMad pour passer de la v4 à la v6, qui inclut une détection automatique des installations existantes et une assistance à la migration. - -## Quand utiliser ce guide - -- Vous avez BMad v4 installé (dossier `.bmad-method`) -- Vous souhaitez migrer vers la nouvelle architecture v6 -- Vous avez des artefacts de planification existants à préserver - -:::note[Prérequis] -- Node.js 20.12+ -- Installation BMad v4 existante -::: - -## Étapes - -### 1. Lancer l’installateur - -Suivez les [Instructions d’installation](./install-bmad.md). - -### 2. Gérer l’installation existante - -Quand v4 est détecté, vous pouvez : - -- Autoriser l’installateur à sauvegarder et supprimer `.bmad-method` -- Quitter et gérer le nettoyage manuellement - -Si votre dossier de méthode BMad porte un nom différent, vous devrez le supprimer manuellement. - -### 3. Nettoyer les skills IDE - -Supprimez manuellement les commandes/skills IDE v4 existants - par exemple si vous utilisez Claude Code, recherchez tous les dossiers imbriqués qui commencent par bmad et supprimez-les : - -- `.claude/commands/` - -Les nouveaux skills v6 sont installés dans : - -- `.claude/skills/` - -### 4. Migrer les artefacts de planification - -**Si vous avez des documents de planification (Brief/PRD/UX/Architecture) :** - -Déplacez-les dans `_bmad-output/planning-artifacts/` avec des noms descriptifs : - -- Incluez `PRD` dans le nom de fichier pour les documents PRD[^1] -- Incluez `brief`, `architecture`, ou `ux-design` selon le cas -- Les documents divisés peuvent être dans des sous-dossiers au nom descriptif - -**Si vous êtes en cours de planification :** Envisagez de recommencer avec les workflows v6. Utilisez vos documents existants comme entrées — les nouveaux workflows de découverte progressive avec recherche web et le mode plan de l’IDE produisent de meilleurs résultats. - -### 5. Migrer le développement en cours - -Si vous avez des stories[^3] créées ou implémentées : - -1. Terminez l’installation v6 -2. Placez `epics.md` ou `epics/epic*.md`[^2] dans `_bmad-output/planning-artifacts/` -3. Lancez le workflow Développeur `bmad-sprint-planning`[^4] -4. Indiquez à l’agent quels epics/stories sont déjà terminés - -## Résultat de la migration - -**Structure unifiée v6 :** - -```text -votre-projet/ -├── _bmad/ # Dossier d'installation unique -│ ├── _config/ # Vos personnalisations -│ │ └── agents/ # Fichiers de personnalisation des agents -│ ├── core/ # Framework core universel -│ ├── bmm/ # Module BMad Method -│ ├── bmb/ # BMad Builder -│ └── cis/ # Creative Intelligence Suite -└── _bmad-output/ # Dossier de sortie (remplace le dossier doc de la v4) -``` - -## Migration des modules - -| Module v4 | Statut v6 | -|-------------------------------|---------------------------------------------------| -| `.bmad-2d-phaser-game-dev` | Intégré dans le Module BMGD | -| `.bmad-2d-unity-game-dev` | Intégré dans le Module BMGD | -| `.bmad-godot-game-dev` | Intégré dans le Module BMGD | -| `.bmad-infrastructure-devops` | Obsolète — nouvel agent DevOps bientôt disponible | -| `.bmad-creative-writing` | Non migré — nouveau module v6 bientôt disponible | - -## Changements clés - -| Concept | v4 | v6 | -|---------------|---------------------------------------------------------|------------------------------------------| -| **Core** | `_bmad-core` correspondait en réalité à la méthode BMad | `_bmad/core/` est le framework universel | -| **Method** | `_bmad-method` | `_bmad/bmm/` | -| **Config** | Fichiers modifiés directement | `config.yaml` par module | -| **Documents** | Division en fragments obligatoire ou optionnelle | Totalement flexible, analyse automatique | - - -## Glossaire -[^1]: PRD (Product Requirements Document) : document de référence qui décrit les objectifs du produit, les besoins utilisateurs, les fonctionnalités attendues, les contraintes et les critères de succès, afin d’aligner les équipes sur ce qui doit être construit et pourquoi. -[^2]: Epic : dans les méthodologies agiles, une grande unité de travail qui peut être décomposée en plusieurs stories. Un epic représente généralement une fonctionnalité majeure ou un ensemble de capacités livrable sur plusieurs sprints. -[^3]: Story (User Story) : une description courte et simple d’une fonctionnalité du point de vue de l’utilisateur. Les stories sont des unités de travail suffisamment petites pour être complétées en un sprint. -[^4]: Sprint : dans Scrum, une période de temps fixe (généralement 1 à 4 semaines) pendant laquelle l’équipe travaille à livrer un incrément de produit potentiellement libérable. diff --git a/docs/fr/index.md b/docs/fr/index.md deleted file mode 100644 index 8b9e591f27..0000000000 --- a/docs/fr/index.md +++ /dev/null @@ -1,65 +0,0 @@ ---- -title: Bienvenue dans la méthode BMad -description: Framework de développement alimenté par l’IA avec des agents spécialisés, des workflows guidés et une planification intelligente ---- - -La méthode BMad (**B**uild **M**ore **A**rchitect **D**reams) est un module[^1] de développement assisté par l’IA au sein de l’écosystème BMad. Elle couvre l’intégralité du processus de création logicielle — de l’idéation et de la planification jusqu’à la mise en œuvre par des agents. BMad met à votre disposition des agents IA spécialisés[^2], des workflows guidés et une planification intelligente qui s’adapte à la complexité de votre projet, qu’il s’agisse de corriger un bug ou de bâtir une plateforme d’entreprise. - -Si vous êtes à l’aise avec les assistants de codage IA comme Claude, Cursor ou GitHub Copilot, vous êtes prêt à commencer. - -## Vous découvrez BMad ? Commencez par un tutoriel - -La façon la plus rapide de comprendre BMad est de l’essayer. - -- **[Premiers pas avec BMad](./tutorials/getting-started.md)** — Installez BMad et découvrez son fonctionnement -- **[Carte des workflows](./reference/workflow-map.md)** — Vue d’ensemble visuelle des phases BMM, des workflows et de la gestion du contexte - -:::tip[Envie de passer à la pratique ?] -Installez BMad et utilisez le skill[^3] `bmad-help` — il vous guidera pas à pas, en fonction de votre projet et des modules installés. -::: - -## Comment utiliser cette documentation - -Cette documentation est organisée en quatre sections, selon votre objectif : - -| Section | Objectif | -|----------------------|----------------------------------------------------------------------------------------------------------------------------------------------| -| **Tutoriels** | Orientés apprentissage. Guides pas à pas pour vous accompagner dans la réalisation d’un projet. Le point de départ idéal si vous débutez. | -| **Guides pratiques** | Orientés tâches. Guides concrets pour résoudre des problèmes spécifiques. Vous y trouverez par exemple « Comment personnaliser un agent ? ». | -| **Explications** | Orientés compréhension. Plongées dans les concepts et l’architecture. À consulter pour comprendre le *pourquoi*. | -| **Référence** | Orientés information. Spécifications techniques des agents, workflows et configuration. | - -## Étendre et personnaliser - -Vous souhaitez étendre BMad avec vos propres agents, workflows ou modules ? Le **[BMad Builder](https://bmad-builder-docs.bmad-method.org/)** met à votre disposition le framework et les outils nécessaires pour créer des extensions personnalisées — que ce soit pour ajouter de nouvelles capacités à BMad ou pour concevoir des modules entièrement nouveaux de zéro. - -## Ce dont vous aurez besoin - -BMad fonctionne avec tout assistant de codage IA qui prend en charge les prompts système personnalisés ou le contexte de projet. Parmi les options les plus populaires : - -- **[Claude Code](https://code.claude.com)** — Outil CLI d’Anthropic (recommandé) -- **[Cursor](https://cursor.sh)** — Éditeur de code propulsé par l’IA -- **[Codex CLI](https://github.com/openai/codex)** — Agent de codage en ligne de commande d’OpenAI - -Vous devriez être à l’aise avec les concepts de base du développement logiciel : gestion de versions, structure de projet et méthodologies agiles. Aucune expérience préalable des systèmes d’agents de type BMad n’est requise — c’est précisément l’objet de cette documentation. - -## Rejoindre la communauté - -Trouvez de l’aide, partagez vos projets ou contribuez à BMad : - -- **[Discord](https://discord.gg/gk8jAdXWmj)** — Discutez avec d’autres utilisateurs de BMad, posez des questions, partagez des idées -- **[GitHub](https://github.com/bmad-code-org/BMAD-METHOD)** — Code source, tickets et contributions -- **[YouTube](https://www.youtube.com/@BMadCode)** — Tutoriels vidéo et démonstrations - -## Prochaine étape - -Prêt à vous lancer ? **[Commencez avec BMad](./tutorials/getting-started.md)** et réalisez votre premier projet. - ---- -## Glossaire - -[^1]: **Module** : composant autonome du système BMad qui peut être installé et utilisé indépendamment, offrant des fonctionnalités spécifiques. - -[^2]: **Agent** : assistant IA spécialisé avec une expertise spécifique qui guide les utilisateurs dans les workflows. - -[^3]: **Skill** : capacité ou fonctionnalité invoquable d’un agent pour effectuer une tâche spécifique. diff --git a/docs/fr/reference/agents.md b/docs/fr/reference/agents.md deleted file mode 100644 index d0374d3e62..0000000000 --- a/docs/fr/reference/agents.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -title: Agents -description: Agents BMM par défaut avec leurs identifiants de skill, déclencheurs de menu et workflows principaux -sidebar: - order: 2 ---- - -## Agents par défaut - -Cette page liste les agents BMM (suite Agile) par défaut installés avec la méthode BMad, ainsi que leurs identifiants de skill, déclencheurs de menu et workflows principaux. Chaque agent est invoqué en tant que skill. - -## Notes - -- Chaque agent est disponible en tant que skill, généré par l’installateur. L’identifiant de skill (par exemple, `bmad-agent-dev`) est utilisé pour invoquer l’agent. -- Les déclencheurs sont les codes courts affichés dans le menu de chaque agent (par exemple, `PRD`) et les correspondances approximatives présentées dans chaque menu. -- La génération de tests QA est gérée par le skill de workflow `bmad-qa-generate-e2e-tests`, disponible via l’agent Développeur. L’architecte de tests complet (TEA) se trouve dans son propre module. - -| Agent | Identifiant de skill | Déclencheurs | Workflows principaux | -|-----------------------------|--------------------------|------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| Analyste (Mary) | `bmad-agent-analyst` | `BP`, `MR`, `DR`, `TR`, `CB`, `WB`, `DP` | Brainstorming, Recherche marché, Recherche domaine, Recherche technique, Création du brief[^1], Défi PRFAQ, Documentation du projet | -| Product Manager (John) | `bmad-agent-pm` | `PRD`, `CE`, `IR`, `CC` | Créer, mettre à jour ou valider un PRD, Créer des Epics et Stories, vérifier l’état de préparation à l’Implémentation, Corriger le Cours | -| Architecte (Winston) | `bmad-agent-architect` | `CA`, `IR` | Créer l’architecture, Préparation à l’implémentation | -| Développeur (Amelia) | `bmad-agent-dev` | `BD`, `QA`, `CR`, `SP`, `ER` | Build, Génération de Tests QA, Code Review, Sprint Planning, Rétrospective d’Epic | -| Designer UX (Sally) | `bmad-agent-ux-designer` | `CU` | Création du design UX[^2] | - -:::note[Où est Paige ?] -La Rédactrice Technique (Paige) est en pause — elle reviendra à l’avenir avec des capacités bien plus étendues. La documentation de projet reste couverte : le déclencheur `DP` (Documentation du projet) est disponible via l’Analyste, ou invoquez directement la compétence `bmad-document-project`. -::: - -## Types de déclencheurs - -Les déclencheurs de menu d’agent chargent un fichier de workflow structuré. Tapez le code du déclencheur et l’agent démarre le workflow, vous demandant de saisir les informations à chaque étape. - -Exemples : `PRD` (Créer, mettre à jour ou valider un PRD), `CA` (Créer l’architecture), `BD` (Build) - -## Glossaire - -[^1]: Brief : document synthétique qui formalise le contexte, les objectifs, le périmètre et les contraintes d’un projet ou d’une demande, afin d’aligner rapidement les parties prenantes avant le travail détaillé. -[^2]: UX (User Experience) : expérience utilisateur, englobant l’ensemble des interactions et perceptions d’un utilisateur face à un produit. Le design UX vise à créer des interfaces intuitives, efficaces et agréables en tenant compte des besoins, comportements et contexte d’utilisation. diff --git a/docs/fr/reference/commands.md b/docs/fr/reference/commands.md deleted file mode 100644 index c38e9e03af..0000000000 --- a/docs/fr/reference/commands.md +++ /dev/null @@ -1,140 +0,0 @@ ---- -title: Skills -description: Référence des skills BMad — ce qu’ils sont, comment ils fonctionnent et où les trouver. -sidebar: - order: 4 ---- - -Les skills sont des prompts pré-construits qui chargent des agents, exécutent des workflows ou lancent des tâches dans votre IDE. L’installateur BMad les génère à partir de vos modules installés au moment de l’installation. Si vous ajoutez, supprimez ou modifiez des modules ultérieurement, relancez l’installateur pour garder les skills synchronisés (voir [Dépannage](#dépannage)). - -## Skills vs. Déclencheurs du menu Agent - -BMad offre deux façons de démarrer un travail, chacune ayant un usage différent. - -| Mécanisme | Comment l’invoquer | Ce qui se passe | -|-------------------------------|---------------------------------------------------------------|------------------------------------------------------------------------------------------------| -| **Skill** | Tapez le nom du skill (ex. `bmad-help`) dans votre IDE | Charge directement un agent, exécute un workflow ou lance une tâche | -| **Déclencheur du menu agent** | Chargez d’abord un agent, puis tapez un code court (ex. `BD`) | L’agent interprète le code et démarre le workflow correspondant tout en préservant son persona | - -Les déclencheurs du menu agent nécessitent une session agent active. Utilisez les skills lorsque vous savez quel workflow vous voulez. Utilisez les déclencheurs lorsque vous travaillez déjà avec un agent et souhaitez changer de tâche sans quitter la conversation. - -## Comment les skills sont générés - -Lorsque vous exécutez `npx bmad-method install`, l’installateur lit les manifests de chaque module sélectionné et écrit un skill par agent, workflow, tâche et outil. Chaque skill est un répertoire contenant un fichier `SKILL.md` qui indique à l’IA de charger le fichier source correspondant et de suivre ses instructions. - -L’installateur utilise des modèles pour chaque type de skill : - -| Type de skill | Ce que fait le fichier généré | -|-----------------------|--------------------------------------------------------------------------------| -| **Lanceur d’agent** | Charge le fichier de persona de l’agent, active son menu et reste en caractère | -| **Skill de workflow** | Charge la configuration du workflow et suit ses étapes | -| **Skill de tâche** | Charge un fichier de tâche autonome et suit ses instructions | -| **Skill d’outil** | Charge un fichier d’outil autonome et suit ses instructions | - -:::note[Relancer l’installateur] -Si vous ajoutez ou supprimez des modules, relancez l’installateur. Il régénère tous les fichiers de skill pour correspondre à votre sélection actuelle de modules. -::: - -## Emplacement des fichiers de skill - -L’installateur écrit les fichiers de skill dans un répertoire spécifique à l’IDE à l’intérieur de votre projet. Le chemin exact dépend de l’IDE que vous avez sélectionné lors de l’installation. - -| IDE / CLI | Répertoire des skills | -|-------------|------------------------------------------------------------| -| Claude Code | `.claude/skills/` | -| Cursor | `.agents/skills/` | -| Windsurf | `.agents/skills/` | -| Autres IDE | Consultez la sortie de l’installateur pour le chemin cible | - -Chaque skill est un répertoire contenant un fichier `SKILL.md`. Par exemple, une installation Claude Code ressemble à : - -```text -.claude/skills/ -├── bmad-help/ -│ └── SKILL.md -├── bmad-prd/ -│ └── SKILL.md -├── bmad-agent-dev/ -│ └── SKILL.md -└── ... -``` - -Le nom du répertoire détermine le nom du skill dans votre IDE. Par exemple, le répertoire `bmad-agent-dev/` enregistre le skill `bmad-agent-dev`. - -## Comment découvrir vos skills - -Tapez le nom du skill dans votre IDE pour l’invoquer. Certaines plateformes nécessitent d’activer les skills dans les paramètres avant qu’ils n’apparaissent. - -Exécutez `bmad-help` pour obtenir des conseils contextuels sur votre prochaine étape. - -:::tip[Découverte rapide] -Les répertoires de skills générés dans votre projet sont la liste de référence. Ouvrez-les dans votre explorateur de fichiers pour voir chaque skill avec sa description. -::: - -## Catégories de skills - -### Skills d’agent - -Les skills d’agent chargent un persona[^2] IA spécialisé avec un rôle défini, un style de communication et un menu de workflows. Une fois chargé, l’agent reste en caractère et répond aux déclencheurs du menu. - -| Exemple de skill | Agent | Rôle | -|------------------------|------------------------|-------------------------------------------------------------| -| `bmad-agent-dev` | Amelia (Développeur) | Implémente les stories avec une adhérence stricte aux specs | -| `bmad-agent-pm` | John (Product Manager) | Crée, met à jour et valide les PRDs[^1] | -| `bmad-agent-architect` | Winston (Architecte) | Conçoit l’architecture système | - -Consultez [Agents](./agents.md) pour la liste complète des agents par défaut et leurs déclencheurs. - -### Skills de workflow - -Les skills de workflow exécutent un processus structuré en plusieurs étapes sans charger d’abord un persona d’agent. Ils chargent une configuration de workflow et suivent ses étapes. - -| Exemple de skill | Objectif | -|---------------------------------|------------------------------------------------------------------------------------------------------------------------------| -| `bmad-product-brief` | Créer ou mettre à jour un product brief[^3] — découverte guidée lorsque votre concept est clair | -| `bmad-prfaq` | Défi [PRFAQ Working Backwards](../explanation/analysis-phase.md#prfaq-working-backwards) pour éprouver votre concept produit | -| `bmad-prd` | Créer, mettre à jour ou valider un PRD[^1] | -| `bmad-architecture` | Concevoir l’architecture système | -| `bmad-create-epics-and-stories` | Créer des epics et des stories | -| `bmad-code-review` | Effectuer une revue de code | -| `bmad-build` | Implémenter une intention directe, une issue, une fonctionnalité, un correctif ou une story planifiée | - -Consultez la [Carte des workflows](./workflow-map.md) pour la référence complète des workflows organisés par phase. - -### Skills de tâche et d’outil - -Les tâches et outils sont des opérations autonomes qui ne nécessitent pas de contexte d’agent ou de workflow. - -**BMad-Help : Votre guide intelligent** - -`bmad-help` est votre interface principale pour découvrir quoi faire ensuite. Il inspecte votre projet, comprend les requêtes en langage naturel et recommande la prochaine étape requise ou optionnelle en fonction de vos modules installés. - -:::note[Exemple] -``` -bmad-help -bmad-help J'ai une idée de SaaS et je connais toutes les fonctionnalités. Par où commencer ? -bmad-help Quelles sont mes options pour le design UX ? -``` -::: - -**Autres tâches et outils principaux** - -Le module principal inclut 8 outils intégrés — aide, revues, raffinement, personnalisation et les compétences de réflexion (brainstorming, forge idea, party mode). Consultez [Outils principaux](./core-tools.md) pour la référence complète. - -## Convention de nommage - -Tous les skills utilisent le préfixe `bmad-` suivi d’un nom descriptif (ex. `bmad-agent-dev`, `bmad-prd`, `bmad-help`). Consultez [Modules](./modules.md) pour les modules disponibles. - -## Dépannage - -**Les skills n’apparaissent pas après l’installation.** Certaines plateformes nécessitent d’activer explicitement les skills dans les paramètres. Consultez la documentation de votre IDE ou demandez à votre assistant IA comment activer les skills. Vous devrez peut-être aussi redémarrer votre IDE ou recharger la fenêtre. - -**Des skills attendus sont manquants.** L’installateur génère uniquement les skills pour les modules que vous avez sélectionnés. Exécutez à nouveau `npx bmad-method install` et vérifiez votre sélection de modules. Vérifiez que les fichiers de skill existent dans le répertoire attendu. - -**Des skills d’un module supprimé apparaissent encore.** L’installateur ne supprime pas automatiquement les anciens fichiers de skill. Supprimez les répertoires obsolètes du répertoire de skills de votre IDE, ou supprimez tout le répertoire de skills et relancez l’installateur pour obtenir un ensemble propre. - -## Glossaire - -[^1]: PRD (Product Requirements Document) : document de référence qui décrit les objectifs du produit, les besoins utilisateurs, les fonctionnalités attendues, les contraintes et les critères de succès, afin d’aligner les équipes sur ce qui doit être construit et pourquoi. -[^2]: Persona : dans le contexte de BMad, un persona désigne un agent IA avec un rôle défini, un style de communication et une expertise spécifiques (ex. Mary l’analyste, Winston l’architecte). Chaque persona garde son « caractère » pendant les interactions. -[^3]: Brief : document synthétique qui formalise le contexte, les objectifs, le périmètre et les contraintes d’un projet ou d’une demande, afin d’aligner rapidement les parties prenantes avant le travail détaillé. diff --git a/docs/fr/reference/core-tools.md b/docs/fr/reference/core-tools.md deleted file mode 100644 index be44cd60c0..0000000000 --- a/docs/fr/reference/core-tools.md +++ /dev/null @@ -1,222 +0,0 @@ ---- -title: Outils Principaux -description: Référence des compétences intégrées du module principal. -sidebar: - order: 3 ---- - -Chaque installation BMad comprend le **module principal** — un petit ensemble de compétences qui fonctionnent dans tous les projets, tous les modules et toutes les phases. Cette page couvre ces sept compétences principales : les quatre outils du noyau plus les trois **compétences de réflexion** (brainstorming, forge idea, party mode). - -:::tip[Raccourci Rapide] -Exécutez n’importe quel outil en tapant son nom de compétence (par ex., `bmad-help`) dans votre IDE. Aucune session d’agent requise. -::: - -## Vue d’ensemble - -**Module principal (toujours installé) :** - -| Outil | Objectif | -| --------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | -| [`bmad-help`](#bmad-help) | Obtenir des conseils contextuels sur la prochaine étape | -| [`bmad-advanced-elicitation`](#bmad-advanced-elicitation) | Soumettre la sortie LLM à des méthodes de raffinement itératives | -| [`bmad-review`](#bmad-review) | Revue multi-perspectives — contradictoire, cas limites et lacunes de vérification pour le code ; structure et prose pour les documents | -| [`bmad-customize`](#bmad-customize) | Créer et vérifier des personnalisations BMad | - -**Compétences de réflexion :** - -| Outil | Objectif | -| ------------------------------------------- | -------------------------------------------------------------------------------------- | -| [`bmad-brainstorming`](#bmad-brainstorming) | Faciliter des sessions de brainstorming interactives | -| [`bmad-forge-idea`](#bmad-forge-idea) | Éprouver une idée jusqu’à ce qu’elle se consolide, se confirme ou meure à moindre coût | -| [`bmad-party-mode`](#bmad-party-mode) | Orchestrer des discussions de groupe multi-agents | - -:::note[Déplacés et supprimés] -`bmad-spec` fait désormais partie du module BMM comme workflow de planification de Phase 2 — voir la [Carte des Workflows](./workflow-map.md). Les utilitaires `bmad-shard-doc` et `bmad-index-docs` ont été supprimés. Les anciennes compétences `bmad-editorial-review`, `bmad-editorial-review-prose`, `bmad-editorial-review-structure`, `bmad-review-adversarial-general`, `bmad-review-edge-case-hunter` et `bmad-review-verification-gap` sont toutes fusionnées dans `bmad-review`, dont les perspectives éditoriales remplacent la compétence éditoriale séparée ; les anciens identifiants restent résolus via des redirections pour la compatibilité. -::: - -## bmad-help - -**Votre guide intelligent pour la suite.** — Inspecte l’état de votre projet, détecte ce qui a été fait et recommande la prochaine étape requise ou facultative. - -**À utiliser quand :** - -- Vous avez terminé un workflow et voulez savoir quoi faire ensuite -- Vous êtes nouveau sur BMad et avez besoin d’orientation -- Vous êtes bloqué et voulez des conseils contextuels -- Vous avez installé de nouveaux modules et voulez voir ce qui est disponible - -**Fonctionnement :** - -1. Analyse votre projet pour détecter les artefacts existants (PRD, architecture, stories, etc.) -2. Détecte quels modules sont installés et leurs workflows disponibles -3. Recommande les prochaines étapes par ordre de priorité — étapes requises d’abord, puis facultatives -4. Présente chaque recommandation avec la commande de compétence et une brève description - -**Entrée :** Requête optionnelle en langage naturel (par ex., `bmad-help J'ai une idée de SaaS, par où commencer ?`) - -**Sortie :** Liste priorisée des prochaines étapes recommandées avec les commandes de compétence - -## bmad-advanced-elicitation - -**Pousse le LLM à reconsidérer, raffiner et améliorer sa sortie récente.** — Le point de contrôle de raffinement partagé de BMad : d’autres compétences l’invoquent aux pauses naturelles, et vous pouvez l’appeler directement sur tout contenu récent de la conversation. - -**À utiliser quand :** - -- La sortie du LLM semble superficielle ou générique -- Vous voulez explorer un sujet sous plusieurs angles analytiques -- Vous raffinez un document critique et souhaitez une réflexion plus approfondie -- Vous voulez une méthode connue par son nom — socratique, premiers principes, pré-mortem, red team - -**Fonctionnement :** - -1. Cible la sortie la plus récente de la conversation, sauf si vous la pointez ailleurs -2. Propose un court menu de méthodes d’élicitation adaptées au contenu -3. Applique les méthodes choisies sur la cible -4. Restitue la version améliorée pour que le flux appelant reprenne où il s’était arrêté - -**Entrée :** La sortie récente à raffiner (par défaut), ou tout contenu que vous désignez ; éventuellement une méthode nommée - -**Sortie :** Version améliorée du contenu avec les améliorations appliquées - -## bmad-review - -**Revue multi-perspectives sur tout diff, document ou artefact.** — Exécute des perspectives de revue — chacune avec sa méthode et sa posture propres — et rapporte chaque constatation dans un format canonique unique. Zéro constatation est un résultat valide ; il ne remplit jamais pour paraître exhaustif. Chaque perspective déclare ce à quoi elle s’applique : un diff appelle les perspectives de code, un document les perspectives éditoriales. - -**Les perspectives livrées :** - -| Perspective | S’applique à | Méthode | -| --------------------------- | ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------- | -| **Contradictoire** | Tout contenu | Revue sceptique qui part du principe que des problèmes existent — traque ce qui manque, pas seulement ce qui ne va pas | -| **Cas limites** | Tout contenu | Parcourt chaque chemin de branchement et condition aux limites d’un contenu qui définit un comportement | -| **Lacunes de vérification** | Code | Trouve les comportements modifiés qui pourraient régresser sans qu’une vérification fiable ne le détecte | -| **Structure** | Documents | Propose coupes, fusions, déplacements et condensations — la forme du document sert-elle son objectif ? | -| **Prose** | Documents | Corrige les problèmes de communication qui nuisent à la compréhension | - -Les deux perspectives éditoriales tiennent le contenu pour sacro-saint : elles ne remettent jamais en cause vos idées, seulement leur organisation et leur expression, et elles proposent sans exécuter. La perspective prose s’exécute sur les constatations de la perspective structure lorsque les deux sont sélectionnées. - -L’ensemble n’est pas figé : une surcharge dans `customize.toml` peut ajouter des perspectives ou remplacer celles fournies, et une revue exécute celles qui sont effectivement résolues. - -**À utiliser quand :** - -- Vous avez besoin d’assurance qualité avant de finaliser un livrable -- Vous voulez une couverture exhaustive des cas limites d’un code ou d’une logique -- Vous voulez savoir si un changement est correctement vérifié -- Vous avez rédigé un document et voulez le resserrer et le polir -- Vous voulez réduire la longueur en préservant la compréhension - -**Fonctionnement :** - -1. Charge le contenu, identifie son type — diff, fichier, fonction ou document — et s’il s’agit de code ou de documentation -2. Sélectionne les perspectives : celles que vous nommez, ou toutes les perspectives activées dont l’applicabilité et les conditions correspondent au contenu -3. Annonce le plan — quelles perspectives vont s’exécuter, et lesquelles s’appuient sur les constatations d’une autre -4. Exécute les perspectives indépendantes — en parallèle via des sous-agents lorsque la plateforme le permet — puis celles qui en dépendent -5. Assemble une liste unique de constatations ; le chevauchement entre perspectives est un signal, pas une duplication - -**Entrée :** - -- `content` (requis) — Diff, branche, changements non commités, fichier, spécification, story ou tout document -- `lenses` (optionnel) — un ou plusieurs codes ou noms de perspectives ; par défaut, revue complète -- `also_consider` (optionnel) — Domaines supplémentaires à garder à l’esprit -- `style_guide` / `reader_type` (optionnel, perspectives éditoriales) — un guide de style projet, et `humans` (défaut) ou `llm` - -**Sortie :** Liste de constatations JSON (chaque constatation porte `lens`, `location`, `trigger_condition`, `guard_snippet`, `potential_consequence`) et/ou rapport markdown groupé par perspective - -:::note[Utilisé par d’autres workflows] -Les workflows de Code Review d’autres modules exécutent les perspectives de code automatiquement, et les workflows documentaires (PRD, UX, architecture, brief produit) exécutent les perspectives éditoriales à l’étape de finalisation. Des perspectives personnalisées peuvent être ajoutées — et celles livrées ajustées ou désactivées — via le `customize.toml` de la compétence. -::: - -## bmad-customize - -**Créer et vérifier des personnalisations.** — Vous aide à modifier le comportement d’un agent ou d’un workflow BMad installé sans avoir à écrire de TOML manuellement. - -**À utiliser quand :** - -- Vous souhaitez modifier le comportement d’un agent ou d’un workflow -- Vous devez ajouter des faits persistants, des hooks d’activation ou des éléments de menu personnalisés -- Vous voulez que le bon périmètre de surcharge soit sélectionné et vérifié automatiquement - -**Fonctionnement :** - -1. Analyse les skills BMad installés pour identifier les surfaces personnalisables -2. Sélectionne le bon périmètre pour le changement demandé -3. Écrit les fichiers de surcharge sous `_bmad/custom/` -4. Vérifie la configuration fusionnée - -**Entrée :** Description en langage naturel de la personnalisation souhaitée - -**Sortie :** Fichiers de surcharge TOML sous `_bmad/custom/` - -Pour un guide détaillé sur la personnalisation de BMad, consultez [Comment personnaliser BMad](../how-to/customize-bmad.md). - -## Compétences de Réflexion - -Les trois compétences ci-dessous complètent le module principal — des outils de réflexion généralistes sur lesquels toute phase ou tout module peut s’appuyer. - -### bmad-brainstorming - -**Génère des idées variées grâce à des techniques créatives interactives.** — Une session de brainstorming facilitée qui charge des méthodes d’idéation éprouvées à partir d’une bibliothèque de techniques et vous guide vers plus de 100 idées avant de les organiser. - -**À utiliser quand :** - -- Vous commencez un nouveau projet et devez explorer l’espace problème -- Vous êtes bloqué dans la génération d’idées et avez besoin de créativité structurée -- Vous voulez utiliser des cadres d’idéation éprouvés (SCAMPER, brainstorming inversé, etc.) - -**Fonctionnement :** - -1. Configure une session de brainstorming avec votre sujet -2. Charge les techniques créatives à partir d’une bibliothèque de méthodes -3. Vous guide de technique en technique, en générant des idées -4. Applique un protocole anti-biais — bascule de domaine créatif toutes les 10 idées pour éviter les biais de regroupement - -**Entrée :** Sujet de brainstorming ou énoncé de problème, fichier de contexte optionnel - -**Sortie :** un `brainstorm.html` autonome comme souvenir de la session, un `brainstorm-intent.md` optionnel pour les compétences en aval, et un enregistrement de session `.memlog.md` - -:::note[Cible de Quantité] -La magie se produit dans les idées 50–100. Le workflow encourage la génération de plus de 100 idées avant organisation. -::: - -### bmad-forge-idea - -**Éprouve une idée jusqu’à ce qu’elle se consolide, se confirme ou meure à moindre coût.** — Un interrogateur contradictoire fait avancer une idée à moitié formée une question à la fois, en amenant deux personnages à chaque embranchement, jusqu’à ce que ce qui survit soit quelque chose sur quoi vous pouvez agir avec conviction. - -**À utiliser quand :** - -- Vous tenez une idée et voulez la mettre à l’épreuve avant d’y investir -- Vous voulez un avis honnête sur l’opportunité de l’abandonner -- Vous avez besoin d’un partenaire de réflexion qui résiste au lieu d’acquiescer - -**Fonctionnement :** - -1. Établit l’objectif dès le départ et oriente le questionnement en conséquence -2. Travaille une question à la fois, dans l’ordre des dépendances, en posant une réponse recommandée à contester -3. Amène deux voix à chaque embranchement — une de votre effectif installé, une évoquée par le sujet -4. Conteste les termes flous et confronte les affirmations au matériau d’un projet existant -5. Aboutit à Consolidée, Abandonnée ou Clarifiée, avec un rapport autonome que vous pouvez conserver - -**Entrée :** L’idée, dans n’importe quel domaine — une fonctionnalité, un modèle économique, une hypothèse de recherche, une décision de vie - -**Sortie :** Un distillat `forged-idea.md` quand une idée se consolide (optionnel), plus un souvenir `forge-report.html` à chaque exécution - -### bmad-party-mode - -**Orchestre des discussions de groupe multi-agents.** — Charge tous les agents BMad installés et facilite une conversation naturelle où chaque agent apporte son expertise et sa personnalité uniques. - -**À utiliser quand :** - -- Vous avez besoin de multiples perspectives d’experts sur une décision -- Vous voulez que les agents remettent en question les hypothèses des autres -- Vous explorez un sujet complexe qui couvre plusieurs domaines - -**Fonctionnement :** - -1. Charge le manifeste d’agents avec toutes les personnalités d’agents installées -2. Analyse votre sujet pour sélectionner les 2–3 agents les plus pertinents -3. Les agents contribuent à tour de rôle, avec des échanges spontanés et des désaccords -4. Alterne la participation des agents pour garantir des perspectives variées -5. Quittez avec `goodbye`, `end party` ou `quit` - -**Entrée :** Sujet de discussion ou question, ainsi que la spécification des personas que vous souhaitez faire participer (optionnel) - -**Sortie :** Conversation multi-agents en temps réel conservant la personnalité de chaque agent diff --git a/docs/fr/reference/modules.md b/docs/fr/reference/modules.md deleted file mode 100644 index 6c644eae0a..0000000000 --- a/docs/fr/reference/modules.md +++ /dev/null @@ -1,82 +0,0 @@ ---- -title: Modules Officiels -description: Modules additionnels pour créer des agents personnalisés, de l’intelligence créative, du développement de jeux et des tests -sidebar: - order: 5 ---- - -BMad s’étend via des modules officiels que vous sélectionnez lors de l’installation. Ces modules additionnels fournissent des agents, des workflows et des tâches spécialisés pour des domaines spécifiques, au-delà du noyau intégré et de BMM (suite Agile). - -:::tip[Installer des Modules] -Exécutez `npx bmad-method install` et sélectionnez les modules souhaités. L’installateur gère automatiquement le téléchargement, la configuration et l’intégration IDE. -::: - -## BMad Builder - -Créez des agents personnalisés, des workflows et des modules spécifiques à un domaine avec une assistance guidée. BMad Builder est le méta-module pour étendre le framework lui-même. - -- **Code :** `bmb` -- **npm :** [`bmad-builder`](https://www.npmjs.com/package/bmad-builder) -- **GitHub :** [bmad-code-org/bmad-builder](https://github.com/bmad-code-org/bmad-builder) - -**Fournit :** - -- Agent Builder — créez des agents IA spécialisés avec une expertise et un accès aux outils personnalisés -- Workflow Builder — concevez des processus structurés avec des étapes et des points de décision -- Module Builder — empaquetez des agents et des workflows dans des modules partageables et publiables -- Configuration interactive avec support de configuration YAML et publication npm - -## Creative Intelligence Suite - -Outils basés sur l’IA pour la créativité structurée, l’idéation et l’innovation pendant le développement en phase amont. La suite fournit plusieurs agents qui facilitent le brainstorming, le design thinking et la résolution de problèmes en utilisant des cadres éprouvés. - -- **Code :** `cis` -- **npm :** [`bmad-creative-intelligence-suite`](https://www.npmjs.com/package/bmad-creative-intelligence-suite) -- **GitHub :** [bmad-code-org/bmad-module-creative-intelligence-suite](https://github.com/bmad-code-org/bmad-module-creative-intelligence-suite) - -**Fournit :** - -- Agents Innovation Strategist, Design Thinking Coach et Brainstorming Coach -- Problem Solver et Creative Problem Solver pour la pensée systématique et latérale -- Storyteller et Presentation Master pour les récits et les présentations -- Cadres d’idéation incluant SCAMPER[^1], Brainstorming inversé et reformulation de problèmes - -## Game Dev Studio - -Workflows de développement de jeux structurés adaptés pour Unity, Unreal, Godot et moteurs personnalisés. Supporte une profondeur de planification allant du prototype à la production à grande échelle ; l’implémentation converge vers Build. - -- **Code :** `gds` -- **npm :** [`bmad-game-dev-studio`](https://www.npmjs.com/package/bmad-game-dev-studio) -- **GitHub :** [bmad-code-org/bmad-module-game-dev-studio](https://github.com/bmad-code-org/bmad-module-game-dev-studio) - -**Fournit :** - -- Workflow de génération de Document de Design de Jeu (GDD[^3]) -- Contexte et planification spécifiques au jeu pour la boucle d’implémentation Build standard -- Support de design narratif pour les personnages, dialogues et construction de monde -- Couverture de plus de 21 types de jeux avec des conseils d’architecture spécifiques au moteur - -## Test Architect (TEA) - -Stratégie de test de niveau entreprise, conseils d’automatisation et décisions de porte de release via un agent expert et neuf workflows structurés. TEA va bien au-delà du workflow QA intégré avec une priorisation basée sur les risques et une traçabilité des exigences. - -- **Code :** `tea` -- **npm :** [`bmad-method-test-architecture-enterprise`](https://www.npmjs.com/package/bmad-method-test-architecture-enterprise) -- **GitHub :** [bmad-code-org/bmad-method-test-architecture-enterprise](https://github.com/bmad-code-org/bmad-method-test-architecture-enterprise) - -**Fournit :** - -- Agent Murat (Master Test Architect and Quality Advisor) -- Workflows pour la conception de tests, ATDD, l’automatisation, la revue de tests et la traçabilité -- Évaluation NFR[^2], configuration CI et scaffolding de framework -- Priorisation P0-P3 avec Playwright Utils et intégrations MCP optionnelles - -## Modules Communautaires - -Les modules communautaires et une marketplace de modules sont à venir. Consultez l'[organisation GitHub BMad](https://github.com/bmad-code-org) pour les mises à jour. - -## Glossaire - -[^1]: SCAMPER : acronyme anglais pour une technique de créativité structurée (Substitute, Combine, Adapt, Modify, Put to another use, Eliminate, Reverse) qui permet d’explorer systématiquement les modifications possibles d’un produit ou d’une idée pour générer des innovations. -[^2]: NFR (Non-Functional Requirement) : exigence décrivant les contraintes de qualité du système (performance, sécurité, fiabilité, ergonomie) plutôt que ses fonctionnalités. -[^3]: GDD (Game Design Document) : document de conception de jeu qui décrit en détail les mécaniques, l’univers, les personnages, les niveaux et tous les aspects du jeu à développer. diff --git a/docs/fr/reference/testing.md b/docs/fr/reference/testing.md deleted file mode 100644 index 3d4c5bf2d9..0000000000 --- a/docs/fr/reference/testing.md +++ /dev/null @@ -1,111 +0,0 @@ ---- -title: Options de Testing -description: Comparaison du workflow QA intégré avec le module Test Architect (TEA) pour l’automatisation des tests. -sidebar: - order: 6 ---- - -BMad propose deux approches de test : un workflow QA[^1] intégré pour une génération rapide de tests et un module Test Architect installable pour une stratégie de test de qualité entreprise. - -## Lequel Choisir ? - -| Facteur | QA Intégré | Module TEA | -|-------------------------|----------------------------------------------|---------------------------------------------------------------------| -| **Idéal pour** | Projets petits et moyens, couverture rapide | Grands projets, domaines réglementés ou complexes | -| **Installation** | Rien à installer — inclus dans BMM | Installer séparément via `npx bmad-method install` | -| **Approche** | Générer les tests rapidement, itérer ensuite | Planifier d’abord, puis générer avec traçabilité | -| **Types de tests** | Tests API et E2E | API, E2E, ATDD[^2], NFR, et plus | -| **Stratégie** | Chemin nominal + cas limites critiques | Priorisation basée sur les risques (P0-P3) | -| **Nombre de workflows** | 1 (Automate) | 9 (conception, ATDD, automatisation, revue, traçabilité, et autres) | - -:::tip[Commencez avec le QA Intégré] -La plupart des projets devraient commencer avec le workflow QA intégré. Si vous avez ensuite besoin d’une stratégie de test, de murs de qualité ou de traçabilité des exigences, installez TEA en complément. -::: - -## Workflow QA Intégré - -Le workflow QA intégré (`bmad-qa-generate-e2e-tests`) fait partie du module BMM (suite Agile), disponible via l’agent Developer. Il génère rapidement des tests fonctionnels en utilisant le framework de test existant de votre projet — aucune configuration ni installation supplémentaire requise. - -**Déclencheur :** `QA` (via l’agent Developer) ou `bmad-qa-generate-e2e-tests` - -### Ce que le Workflow QA Fait - -Le workflow QA exécute un processus unique (Automate) qui parcourt cinq étapes : - -1. **Détecte le framework de test** — analyse `package.json` et les fichiers de test existants pour identifier votre framework (Jest, Vitest, Playwright, Cypress, ou tout runner standard). Si aucun n’existe, analyse la pile technologique du projet et en suggère un. -2. **Identifie les fonctionnalités** — demande ce qu’il faut tester ou découvre automatiquement les fonctionnalités dans le codebase. -3. **Génère les tests API** — couvre les codes de statut, la structure des réponses, le chemin nominal, et 1-2 cas d’erreur. -4. **Génère les tests E2E** — couvre les parcours utilisateur avec des localisateurs sémantiques et des assertions sur les résultats visibles. -5. **Exécute et vérifie** — lance les tests générés et corrige immédiatement les échecs. - -Le workflow QA produit un résumé de test sauvegardé dans le dossier des artefacts d’implémentation de votre projet. - -### Patterns de Test - -Les tests générés suivent une philosophie « simple et maintenable » : - -- **APIs standard du framework uniquement** — pas d’utilitaires externes ni d’abstractions personnalisées -- **Localisateurs sémantiques** pour les tests UI (rôles, labels, texte plutôt que sélecteurs CSS) -- **Tests indépendants** sans dépendances d’ordre -- **Pas d’attentes ou de sleeps codés en dur** -- **Descriptions claires** qui se lisent comme de la documentation fonctionnelle - -:::note[Portée] -Le workflow QA génère uniquement des tests. Pour la revue de code et la validation des stories, utilisez plutôt le workflow Code Review (`CR`). -::: - -### Quand Utiliser le QA Intégré - -- Couverture de test rapide pour une fonctionnalité nouvelle ou existante -- Automatisation de tests accessible aux débutants sans configuration avancée -- Patterns de test standards que tout développeur peut lire et maintenir -- Projets petits et moyens où une stratégie de test complète n’est pas nécessaire - -## Module Test Architect (TEA) - -TEA est un module autonome qui fournit un agent expert (Murat) et neuf workflows structurés pour des tests de qualité entreprise. Il va au-delà de la génération de tests pour inclure la stratégie de test, la planification basée sur les risques, les murs de qualité et la traçabilité des exigences. - -- **Documentation :** [TEA Module Docs](https://bmad-code-org.github.io/bmad-method-test-architecture-enterprise/) -- **Installation :** `npx bmad-method install` et sélectionnez le module TEA -- **npm :** [`bmad-method-test-architecture-enterprise`](https://www.npmjs.com/package/bmad-method-test-architecture-enterprise) - -### Ce que TEA Fournit - -| Workflow | Objectif | -|-----------------------|--------------------------------------------------------------------------------------| -| Test Design | Créer une stratégie de test complète liée aux exigences | -| ATDD | Développement piloté par les tests d’acceptation avec critères des parties prenantes | -| Automate | Générer des tests avec des patterns et utilitaires avancés | -| Test Review | Valider la qualité et la couverture des tests par rapport à la stratégie | -| Traceability | Remonter les tests aux exigences pour l’audit et la conformité | -| NFR Assessment | Évaluer les exigences non-fonctionnelles (performance, sécurité) | -| CI Setup | Configurer l’exécution des tests dans les pipelines d’intégration continue | -| Framework Scaffolding | Configurer l’infrastructure de test et la structure du projet | -| Release Gate | Prendre des décisions de livraison go/no-go basées sur les données | - -TEA supporte également la priorisation basée sur les risques P0-P3 et des intégrations optionnelles avec Playwright Utils et les outils MCP. - -### Quand Utiliser TEA - -- Projets nécessitant une traçabilité des exigences ou une documentation de conformité -- Équipes ayant besoin d’une priorisation des tests basée sur les risques sur plusieurs fonctionnalités -- Environnements entreprise avec des murs de qualité formels avant livraison -- Domaines complexes où la stratégie de test doit être planifiée avant d’écrire les tests -- Projets ayant dépassé l’approche à workflow unique du QA intégré - -## Comment les Tests S’Intègrent dans les Workflows - -Le workflow Automate du QA intégré apparaît dans la Phase 4 (Implémentation) de la carte de workflow méthode BMad. Il est conçu pour s’exécuter **après qu’un epic complet soit terminé** — une fois que toutes les stories d’un epic ont été implémentées et revues. Une séquence typique : - -1. Pour chaque story de l’epic : implémenter avec Build (`BD` / `bmad-build`), puis ajouter Code Review (`CR`) si nécessaire -2. Après la fin de l’epic : générer les tests avec `QA` (via l’agent Developer) ou le workflow Automate de TEA -3. Lancer la rétrospective (`bmad-retrospective`) pour capturer les leçons apprises - -Le workflow QA travaille directement à partir du code source sans charger les documents de planification (PRD, architecture). Les workflows TEA peuvent s’intégrer avec les artefacts de planification en amont pour la traçabilité. - -Pour en savoir plus sur la place des tests dans le processus global, consultez la [Carte des Workflows](./workflow-map.md). - -## Glossaire - -[^1]: QA (Quality Assurance) : assurance qualité, ensemble des processus et activités visant à garantir que le produit logiciel répond aux exigences de qualité définies. -[^2]: ATDD (Acceptance Test-Driven Development) : méthode de développement où les tests d’acceptation sont écrits avant le code, en collaboration avec les parties prenantes pour définir les critères de réussite. diff --git a/docs/fr/reference/workflow-map.md b/docs/fr/reference/workflow-map.md deleted file mode 100644 index 5d33b892a1..0000000000 --- a/docs/fr/reference/workflow-map.md +++ /dev/null @@ -1,120 +0,0 @@ ---- -title: "Carte des Workflows" -description: Référence visuelle des phases et des livrables des workflows de la méthode BMad -sidebar: - order: 1 ---- - -La méthode BMad (BMM) est un module de l’écosystème BMad, conçu pour appliquer les meilleures pratiques d’ingénierie du -contexte et de planification. Les agents IA sont plus performants lorsqu’ils disposent d’un contexte clair et structuré. Le -système BMM construit ce contexte de manière progressive, en 4 phases distinctes — chaque phase, ainsi que les workflows -optionnels qu’elle contient, produit des documents qui nourrissent la phase suivante. Ainsi, les agents savent toujours -ce qu’ils doivent construire et pourquoi. - -La logique et les concepts sous-jacents s’appuient sur les méthodologies agiles, largement éprouvées dans l’industrie -comme cadre de référence. - -Si vous ne savez plus où vous en êtes, le skill `bmad-help` vous remettra sur la bonne voie ou vous indiquera la prochaine -étape. Cette page reste une référence utile, mais `bmad-help` est interactif et bien plus rapide si vous avez déjà installé -la méthode BMad. Par ailleurs, si vous utilisez des modules ayant étendu la méthode BMad ou ajouté d’autres modules -complémentaires non extensibles, `bmad-help` s’adapte automatiquement pour couvrir tout ce qui est disponible et vous -fournir les meilleurs conseils en temps réel. - -Note importante : chaque workflow ci-dessous peut être exécuté directement via un skill avec l’outil de votre choix, ou -en chargeant d’abord un agent depuis le menu des agents. - - - -

- Ouvrir le diagramme dans un nouvel onglet ↗ -

- -## Phase 1 : Analyse (Optionnelle) - -Explorez l’espace problème et validez vos idées avant de vous lancer dans la planification. [**Découvrez ce que fait -chaque outil et quand l’utiliser**](../explanation/analysis-phase.md). - -| Workflow | Objectif | Livrable | -|---------------------------------------------------------------------------|--------------------------------------------------------------------------------|---------------------------| -| `bmad-brainstorming` | Brainstormez des idées de projet, animé par un coach de brainstorming dédié | `brainstorming-report.md` | -| `bmad-deep-recon` | Validez vos hypothèses ou choisissez entre des options — rédigez un prompt pour votre outil de recherche approfondie, traitez son rapport, ou menez la recherche ici ; marché, domaine, technique, concurrentiel, voix des utilisateurs, académique ; vérifiée, citée, actualisable | Rapport ou synthèse de recherche + briefing HTML optionnel | -| `bmad-product-brief` | Formalisez la vision stratégique — idéal lorsque votre concept est bien défini | `product-brief.md` | -| `bmad-prfaq` | Working Backwards — mettez à l’épreuve et affinez votre concept produit | `prfaq-{project}.md` | - -## Phase 2 : Planification - -Définissez ce qu’il faut construire et pour qui. - -| Workflow | Objectif | Livrable | -|------------|--------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------| -| `bmad-prd` | Créez, mettez à jour ou validez un PRD[^1] — découverte accompagnée, trois intentions en un seul skill | Création/Mise à jour : `prd.md`, `addendum.md`, `.memlog.md` ; Validation : `validation-report.html` + `.md` | -| `bmad-ux` | Concevez l’expérience utilisateur (lorsque l’UX compte) | `DESIGN.md`, `EXPERIENCE.md` | -| `bmad-spec` | Distillez toute intention (brief, PRD, transcription, notes) en un contrat `SPEC.md` succinct + fichiers compagnons — fige le QUOI avant le COMMENT | `SPEC.md` + compagnons sous `{output_folder}/specs/spec-{slug}/` | - -:::tip[Trois intentions en un seul skill] -`bmad-prd` couvre l’intégralité du cycle de vie du PRD. Précisez votre intention lors de l’appel, sinon le skill vous la demandera : - -- **Créer** — nouveau PRD à partir de zéro via une découverte accompagnée ; produit `prd.md`, `addendum.md` et `.memlog.md` -- **Mettre à jour** — réconcilie un PRD existant avec un signal de changement, en mettant en évidence les conflits avant d’appliquer les modifications -- **Valider** — évalue un PRD à l’aide d’une liste de contrôle configurable et produit un rapport de constats structuré au format HTML -::: - -:::tip[En amont : `bmad-product-brief`] -`bmad-product-brief` (Phase 1) produit un `product-brief.md` que `bmad-prd` peut exploiter lors de la découverte, réduisant les redondances et gardant les deux documents alignés. Aucun des deux skills ne nécessite l’autre — commencez directement par `bmad-prd` si vous savez déjà ce que vous construisez. -::: - -## Phase 3 : Conception de la Solution - -Décidez comment le construire et décomposez le travail en stories. - -| Workflow | Objectif | Livrable | -|---------------------------------------|---------------------------------------------------|---------------------------------| -| `bmad-architecture` | Rendez explicites les décisions techniques | `architecture.md` avec ADRs[^2] | -| `bmad-create-epics-and-stories` | Décomposez les exigences en tâches implémentables | Fichiers d’epic avec stories | -| `bmad-sprint-planning` | Jalon de préparation avant implémentation, puis suivi des stories et vue d’état du sprint | OK / RÉSERVES / ÉCHEC + `sprint-status.yaml` | - -## Phase 4 : Implémentation - -Tous les points d’entrée convergent vers `bmad-build`. Il accepte une intention directe, une issue, une spécification ou une story planifiée, puis choisit le niveau de clarification, de planification, d’implémentation et de revue nécessaire. - -| Workflow | Objectif | Livrable | -|------------------------|--------------------------------------------------------------------------------------|----------------------------------| -| `bmad-build` | Transformez une intention directe ou une story planifiée en code implémenté et révisé | `spec-*.md` + code | -| `bmad-code-review` | Validez la qualité de l’implémentation | Approuvé ou changements demandés | -| `bmad-correct-course` | Gérez les changements significatifs en cours de sprint | Plan mis à jour ou réorientation | -| `bmad-retrospective` | Bilan après l’achèvement d’un epic | Leçons apprises | - -### Entrée directe ou planifiée - -Un travail clair peut entrer directement dans `bmad-build`. Une initiative plus vaste peut d’abord produire un PRD, une conception UX, une architecture, des epics, des stories, un contrôle de préparation et un plan de sprint. Ces artefacts ajoutent du contexte sans sélectionner un autre workflow d’implémentation. - -## Gestion du Contexte - -Chaque document nourrit le contexte de la phase suivante. Le PRD indique à l’architecte les contraintes à respecter. -L’architecture précise à l’agent de développement les modèles à suivre. Les fichiers de story fournissent un contexte -ciblé et exhaustif pour l’implémentation. Sans cette structure, les agents prennent des décisions incohérentes. - -### Contexte du Projet - -:::tip[Recommandé] -Créez `project-context.md` pour que les agents IA respectent les règles et préférences de votre projet. Ce fichier agit -comme une charte pour votre projet — il oriente les décisions d’implémentation à travers tous les workflows. Ce fichier -optionnel peut être généré à la fin de la création de l’architecture, ou, dans un projet existant, pour capturer les -éléments clés et les garder alignés avec les conventions en vigueur. -::: - -**Comment le créer :** - -- **Manuellement** — Créez `_bmad-output/project-context.md` avec votre stack technique et vos règles d’implémentation -- **Générez-le** — Exécutez `bmad-generate-project-context` pour l’auto-générer à partir de votre architecture ou de votre codebase - -[**En savoir plus sur project-context.md**](../explanation/project-context.md) - -## Glossaire - -[^1]: PRD (Product Requirements Document) : document de référence qui décrit les objectifs du produit, les besoins -utilisateurs, les fonctionnalités attendues, les contraintes et les critères de succès, afin d’aligner les équipes sur -ce qui doit être construit et pourquoi. -[^2]: ADR (Architecture Decision Record) : document qui consigne une décision d’architecture, son contexte, les options -envisagées, le choix retenu et ses conséquences, afin d’assurer la traçabilité et la compréhension des décisions -techniques dans le temps. diff --git a/docs/fr/tutorials/getting-started.md b/docs/fr/tutorials/getting-started.md deleted file mode 100644 index a183f5c6ff..0000000000 --- a/docs/fr/tutorials/getting-started.md +++ /dev/null @@ -1,298 +0,0 @@ ---- -title: "Premiers pas" -description: Installer BMad et développer votre premier projet ---- - -Accélérez le développement de vos applications grâce à des workflows alimentés par l’IA et des agents spécialisés qui vous guident dans la planification, l’architecture et l’implémentation. - -## Ce que vous allez apprendre - -- Installer et initialiser la méthode BMad pour un nouveau projet -- Utiliser **BMad-Help** — votre guide intelligent qui sait quoi faire ensuite -- Choisir la profondeur de planification adaptée à votre travail -- Progresser dans les phases, de la définition des exigences au code fonctionnel -- Utiliser efficacement les agents et les workflows - -:::note[Prérequis] -- **Node.js 20.12+** — Nécessaire pour l’installation -- **Git** — Recommandé pour la gestion de versions -- **IDE avec IA intégrée** — Claude Code, Cursor ou équivalent -- **Une idée de projet** — Même simple, elle fera l’affaire pour commencer -::: - -:::tip[Le chemin le plus rapide] -**Installer** → `npx bmad-method install` -**Demander** → `bmad-help que dois-je faire en premier ?` -**Développez** → Laissez BMad-Help vous guider, workflow par workflow -::: - -## Découvrez BMad-Help : votre guide intelligent - -**BMad-Help est le moyen le plus rapide de démarrer avec BMad.** Pas besoin de mémoriser les workflows ou les phases — posez simplement votre question et BMad-Help saura : - -- **Inspecter votre projet** pour voir ce qui a déjà été fait -- **Vous présenter vos options** en fonction des modules installés -- **Vous recommander la prochaine étape** — y compris la première tâche obligatoire -- **Répondre à vos questions**, par exemple : « J’ai une idée de SaaS, par où commencer ? » - -### Comment utiliser BMad-Help - -Dans votre IDE IA, invoquez le skill : - -``` -bmad-help -``` - -Ou accompagnez-le d’une question pour obtenir des conseils contextualisés : - -``` -bmad-help J’ai une idée de produit SaaS, je connais déjà toutes les fonctionnalités que je veux. Par où dois-je commencer ? -``` - -BMad-Help vous indiquera : - -- Ce qui est recommandé pour votre situation -- Quelle est la première tâche obligatoire -- À quoi ressemble le reste du processus - -### Il intervient aussi dans les workflows - -BMad-Help ne se contente pas de répondre aux questions — **il se lance automatiquement à la fin de chaque workflow** pour vous indiquer exactement la suite. Finies les devinettes et les recherches dans la doc : vous recevez des instructions claires sur le prochain workflow à exécuter. - -:::tip[Commencez ici] -Après avoir installé BMad, invoquez immédiatement le skill `bmad-help`. Il détectera les modules que vous avez installés et vous orientera vers le bon point de départ pour votre projet. -::: - -## Comprendre BMad - -BMad vous aide à développer des logiciels grâce à des workflows guidés par des agents IA spécialisés. Le processus s’articule en quatre phases : - -| Phase | Nom | Ce qui se passe | -|-------|----------------|----------------------------------------------------------------| -| 1 | Analyse | Brainstorming, recherche, product brief ou PRFAQ _(optionnel)_ | -| 2 | Planification | Définir les exigences (PRD[^1] ou spécification technique) | -| 3 | Solutioning | Concevoir l’architecture selon les besoins | -| 4 | Implémentation | Implémenter chaque changement ou story planifiée, éventuellement via une orchestration automatisée | - -**[Ouvrez la carte des workflows](../reference/workflow-map.md)** pour explorer les phases, les workflows et la gestion du contexte. - -La profondeur de planification reste flexible : - -| Profondeur | Idéal pour | Contexte disponible avant l’implémentation | -|---|---|---| -| **Directe** | Corrections, fonctionnalités, issues ou spécifications claires | Intention, issue ou spécification | -| **Planification produit** | Produits, plateformes et fonctionnalités complexes | PRD et conception UX optionnelle | -| **Solutioning complet** | Initiatives coordonnées, risquées ou multi-systèmes | PRD, UX, architecture, epics, stories et plan de sprint | - -:::note -Il ne s’agit pas de voies d’implémentation distinctes. Tous les points d’entrée convergent vers `bmad-build`; la planification ne change que la quantité de contexte disponible. -::: - -## Installation - -Ouvrez un terminal dans le répertoire de votre projet et exécutez : - -```bash -npx bmad-method install -``` - -Si vous préférez la dernière version préliminaire au lieu du canal de publication par défaut, utilisez `npx bmad-method@next install`. - -À l’invite de sélection des modules, choisissez **BMad Method**. - -L’installateur crée deux dossiers : - -- `_bmad/` — agents, workflows, tâches et configuration -- `_bmad-output/` — vide pour le moment, mais c’est là que seront enregistrés vos artefacts - -:::tip[Votre prochaine étape] -Ouvrez votre IDE avec IA dans le dossier du projet et exécutez : - -``` -bmad-help -``` - -BMad-Help détectera ce que vous avez déjà accompli et vous recommandera exactement la suite. Vous pouvez aussi lui poser des questions comme « Quelles sont mes options ? » ou « J’ai une idée de SaaS, par où devrais-je commencer ? » -::: - -:::note[Comment charger les agents et exécuter les workflows] -Chaque workflow possède une **skill** que vous invoquez par son nom dans votre IDE (par ex. `bmad-prd`). Votre outil IA reconnaîtra le nom `bmad-*` et l’exécutera — pas besoin de charger les agents séparément. Vous pouvez aussi invoquer directement une skill d’agent pour une conversation générale (par ex. `bmad-agent-pm` pour l’agent PM). -::: - -:::caution[Nouveaux chats] -Démarrez toujours un nouveau chat pour chaque workflow. Cela évite les problèmes liés aux limites de contexte de l’IA. -::: - -## Étape 1 : Choisir la profondeur de planification - -Utilisez les phases 1 à 3 selon les besoins du travail. Pour un changement clair et délimité, vous pouvez passer directement à l’[Étape 2](#étape-2-développer-votre-projet). **Utilisez un nouveau chat pour chaque workflow.** - -:::tip[Contexte projet (optionnel)] -Avant de commencer, pensez à créer `project-context.md` pour documenter vos préférences techniques et vos règles d’implémentation. Ainsi, tous les agents IA respecteront vos conventions tout au long du projet. - -Créez-le manuellement à l’emplacement `_bmad-output/project-context.md`, ou générez-le après l’architecture avec `bmad-generate-project-context`. [En savoir plus](../explanation/project-context.md). -::: - -### Phase 1 : Analyse (optionnelle) - -Tous les workflows de cette phase sont optionnels. [**Vous ne savez pas lequel choisir ?**](../explanation/analysis-phase.md) - -- **brainstorming** (`bmad-brainstorming`) — Idéation guidée -- **research** (`bmad-deep-recon`) — Rédigez un prompt de recherche approfondie pour votre propre outil IA, transformez un rapport terminé en synthèse exploitable en aval, ou menez la recherche ici — marché, domaine, technique, concurrentiel, voix des utilisateurs et académique — avec vérification des affirmations et cycle de rafraîchissement -- **product-brief** (`bmad-product-brief`) — Document fondateur recommandé une fois votre concept bien défini -- **prfaq** (`bmad-prfaq`) — Exercice Working Backwards pour tester et affiner votre concept produit - -### Phase 2 : Planification (selon les besoins) - -Pour les travaux qui bénéficient d’une planification produit : - -1. Exécutez `bmad-prd` dans un nouveau chat — précisez votre intention (Create / Update / Validate) ou laissez le skill vous la demander -2. Résultat : `prd.md`, `addendum.md`, `.memlog.md` - -:::note[Intentions de `bmad-prd`] - -- **Create** — exploration guidée à partir de zéro ; le skill nomme le dossier de travail et vous accompagne jusqu’à l’obtention d’un PRD dont vous serez fier -- **Update** — pointez vers un PRD existant et un changement à apporter ; le skill met en évidence les conflits avant d’appliquer les modifications -- **Validate** — critiquez un PRD finalisé à l’aide d’une liste de contrôle et générez un rapport HTML des constatations -::: - - -:::note[Design UX (optionnel)] -Si votre projet comporte une interface utilisateur, invoquez l'**agent UX Designer** (`bmad-agent-ux-designer`) et lancez le workflow de design UX (`bmad-ux`) après avoir créé votre PRD. -::: - -### Phase 3 : Solutioning (selon les besoins) - -**Créer l’architecture** - -1. Invoquez l'**agent Architecte** (`bmad-agent-architect`) dans un nouveau chat -2. Exécutez `bmad-architecture` (`bmad-architecture`) -3. Résultat : document d’architecture avec les décisions techniques - -**Créer les epics et les stories** - -:::tip[Amélioration V6] -Les epics et stories sont désormais créés *après* l’architecture. Cela produit des stories de meilleure qualité, car les décisions d’architecture (choix de la base de données, patterns d’API, pile technologique) influencent directement la façon dont le travail doit être découpé. -::: - -1. Invoquez l'**agent PM** (`bmad-agent-pm`) dans un nouveau chat -2. Exécutez `bmad-create-epics-and-stories` (`bmad-create-epics-and-stories`) -3. Le workflow s’appuie sur le PRD et l’architecture pour créer des stories techniquement fondées - -**Vérification de la préparation à l’implémentation** *(fortement recommandée)* - -1. Invoquez l'**agent Architecte** (`bmad-agent-architect`) dans un nouveau chat -2. Exécutez `bmad-sprint-planning` (`bmad-sprint-planning`) — il s’ouvre sur le jalon de préparation -3. Valide la cohérence de l’ensemble des documents de planification - -## Étape 2 : Développer votre projet - -Passez à l’implémentation avec le contexte disponible : demande directe, issue, spécification ou story entièrement planifiée. **Chaque workflow doit être exécuté dans un nouveau chat.** - -Pour un travail planifié, invoquez `bmad-build` et indiquez la story ou l’élément de sprint sélectionné, par exemple : `Implémente la story 2.3 depuis _bmad-output/planning-artifacts/epics.md`. - -### Initialiser la planification de sprint (pour le travail planifié) - -Invoquez l'**agent Développeur** (`bmad-agent-dev`) et exécutez `bmad-sprint-planning` (`bmad-sprint-planning`). Cette commande crée `sprint-status.yaml` pour suivre tous les epics et stories. - -Lorsque Build retrouve la story sélectionnée dans ce fichier, il la passe à `in-progress` pendant l’implémentation, puis à `review` quand l’implémentation est terminée. - -### Le cycle de développement - -Pour chaque changement direct ou story planifiée, répétez ce cycle dans de nouveaux chats : - -| Étape | Agent | Workflow | Commande | Objectif | -|-------|-------|---------------------|---------------------|--------------------------------------| -| 1 | DEV | `bmad-build` | `bmad-build` | Clarifier, planifier, implémenter, réviser et présenter | -| 2 | DEV | `bmad-code-review` | `bmad-code-review` | Validation qualité supplémentaire *(recommandée)* | - -La revue de Build fait partie de chaque exécution. `bmad-code-review` est une couche facultative de validation indépendante dans un contexte neuf. - -Après avoir terminé toutes les stories d’un epic, invoquez l'**agent Développeur** (`bmad-agent-dev`) et exécutez `bmad-retrospective` (`bmad-retrospective`). - -## Ce que vous avez accompli - -Vous maîtrisez maintenant les bases du développement avec BMad : - -- Installation et configuration de BMad pour votre IDE -- Choix d’une profondeur de planification adaptée au travail -- Création des documents de planification (PRD, Architecture, Epics & Stories) -- Compréhension du cycle de développement pour l’implémentation - -Votre projet contient désormais : - -```text -your-project/ -├── _bmad/ # Configuration BMad -├── _bmad-output/ -│ ├── planning-artifacts/ -│ │ ├── PRD.md # Document d’exigences -│ │ ├── architecture.md # Décisions techniques -│ │ └── epics/ # Fichiers epic et story -│ ├── implementation-artifacts/ -│ │ └── sprint-status.yaml # Suivi de sprint -│ └── project-context.md # Règles d’implémentation (optionnel) -└── ... -``` - -## Référence rapide - -| Workflow | Commande | Agent | Objectif | -|---------------------------------------|---------------------------------------|-----------|-----------------------------------------------------------------| -| **`bmad-help`** ⭐ | `bmad-help` | Tous | **Votre guide intelligent — posez n’importe quelle question !** | -| `bmad-prd` | `bmad-prd` | Tous | Créer, mettre à jour ou valider un PRD | -| `bmad-architecture` | `bmad-architecture` | Architect | Créer le document d’architecture | -| `bmad-generate-project-context` | `bmad-generate-project-context` | Analyst | Créer le fichier de contexte projet | -| `bmad-create-epics-and-stories` | `bmad-create-epics-and-stories` | PM | Décomposer le PRD en epics | -| `bmad-sprint-planning` | `bmad-sprint-planning` | DEV | Jalon de préparation + initialisation du suivi de sprint + vue d’état | -| `bmad-build` | `bmad-build` | DEV | Implémenter une intention, une issue, une fonctionnalité, un correctif ou une story | -| `bmad-code-review` | `bmad-code-review` | DEV | Revoir le code implémenté | - -## Questions fréquentes - -**Ai-je toujours besoin d’une architecture ?** -Non. Utilisez l’architecture lorsque les décisions techniques ou contraintes multi-systèmes doivent être explicites. Un travail clair peut entrer directement dans `bmad-build`; une initiative plus vaste fournit ses artefacts de planification au même workflow. - -**Puis-je modifier mon plan en cours de route ?** -Oui. Le workflow `bmad-correct-course` gère les changements de périmètre en cours d’implémentation. - -**Et si je veux d’abord brainstormer ?** -Invoquez l’agent Analyste (`bmad-agent-analyst`) et exécutez `bmad-brainstorming` (`bmad-brainstorming`) avant de commencer votre PRD. - -**Dois-je suivre un ordre strict ?** -Pas strictement. Une fois le flux maîtrisé, vous pouvez exécuter les workflows directement en vous référant au tableau ci-dessus. - -## Obtenir de l’aide - -:::tip[Premier réflexe : BMad-Help] -**Invoquez `bmad-help` à tout moment** — c’est le moyen le plus rapide de vous débloquer. Posez-lui n’importe quelle question : - -- « Que dois-je faire après l’installation ? » -- « Je suis bloqué sur le workflow X » -- « Quelles sont mes options pour Y ? » -- « Montre-moi ce qui a été fait jusqu’ici » - -BMad-Help inspecte votre projet, détecte ce que vous avez accompli et vous indique exactement la prochaine étape. -::: - -- **Pendant les workflows** — Les agents vous guident à l’aide de questions et d’explications -- **Communauté** — [Discord](https://discord.gg/gk8jAdXWmj) (#bmad-method-help, #report-bugs-and-issues) - -## Points clés à retenir - -:::tip[Retenez ceci] -- **Commencez par `bmad-help`** — Votre guide intelligent qui connaît votre projet et vos options -- **Utilisez toujours de nouveaux chats** — Démarrez un nouveau chat pour chaque workflow -- **La profondeur de planification varie** — une intention directe et une story entièrement planifiée entrent toutes deux dans `bmad-build` -- **BMad-Help se lance automatiquement** — Chaque workflow se termine par des conseils sur la prochaine étape -::: - -Prêt à commencer ? Installez BMad, invoquez `bmad-help`, et laissez votre guide intelligent vous accompagner. - -## Glossaire - -[^1]: PRD (Product Requirements Document) : document de référence qui décrit les objectifs du produit, les besoins utilisateurs, les fonctionnalités attendues, les contraintes et les critères de succès, afin d’aligner les équipes sur ce qui doit être construit et pourquoi. -[^2]: Epic : grand ensemble de fonctionnalités ou de travaux qui peut être décomposé en plusieurs user stories. -[^3]: Story (User Story) : description courte et simple d’une fonctionnalité du point de vue de l’utilisateur ou du client. Elle représente une unité de travail implémentable en un court délai. -[^4]: UX (User Experience) : expérience utilisateur, englobant l’ensemble des interactions et perceptions d’un utilisateur face à un produit. Le design UX vise à créer des interfaces intuitives, efficaces et agréables en tenant compte des besoins, des comportements et du contexte d’utilisation. -[^5]: Multi-tenant : architecture logicielle où une seule instance de l’application sert plusieurs clients (tenants) tout en maintenant leurs données isolées et sécurisées les unes des autres. diff --git a/docs/ko-kr/404.md b/docs/ko-kr/404.md deleted file mode 100644 index 12da78e2cb..0000000000 --- a/docs/ko-kr/404.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -title: 페이지를 찾을 수 없음 -template: splash ---- - -찾으려는 페이지가 없거나 이동되었습니다. - -[홈으로 돌아가기](./index.md) diff --git a/docs/ko-kr/_STYLE_GUIDE.md b/docs/ko-kr/_STYLE_GUIDE.md deleted file mode 100644 index 7cdee52593..0000000000 --- a/docs/ko-kr/_STYLE_GUIDE.md +++ /dev/null @@ -1,383 +0,0 @@ ---- -title: "문서 스타일 가이드" -description: Google 스타일과 Diataxis 구조를 바탕으로 한 프로젝트별 문서 작성 규칙 ---- - -이 프로젝트는 [Google Developer 문서 스타일 가이드](https://developers.google.com/style)를 따르고 [Diataxis](https://diataxis.fr/)로 콘텐츠를 구조화합니다. 아래에는 프로젝트별 규칙만 정리합니다. - -## 쉬운 한국어로 쓰기 - -핵심을 쉽게 찾고 바로 행동으로 옮길 수 있게 쓰세요. 다음 규칙은 모든 페이지에 적용합니다. - -- 첫머리에서 문서의 목적과 독자가 알아야 할 내용을 분명히 밝힙니다. -- 구체적이고 익숙한 단어와 짧은 문장을 사용합니다. -- BMad를 사용하는 데 필요한 전문 용어만 씁니다. 낯선 용어는 처음 나올 때 정의합니다. -- 문자 그대로 명확하게 씁니다. 장식적인 비유를 피하세요. 작동 방식을 설명하는 대신 비유로 얼버무리지 않습니다. -- 조건과 세부 작동 방식을 설명하기 전에 요점부터 제시합니다. -- 구현 세부 사항은 독자가 문서의 목적을 이해하거나 행동하는 데 도움이 될 때만 넣습니다. 정확한 작동 방식과 계약은 참조 문서나 링크한 심층 자료에 둡니다. -- 반복, 요점을 늦추는 도입부, 과장된 주장, 독자의 결정에 영향을 주지 않는 단서는 삭제합니다. - -## 프로젝트별 규칙 - -| 규칙 | 사양 | -| --- | --- | -| 가로 구분선(`---`) 사용 금지 | 읽기 흐름을 끊습니다 | -| `####` 헤더 사용 금지 | 대신 굵은 글씨나 알림 상자를 사용합니다 | -| "관련 항목" 또는 "다음:" 섹션 금지 | 사이드바가 탐색을 담당합니다 | -| 깊게 중첩된 목록 금지 | 섹션으로 나누세요 | -| 코드가 아닌 내용에 코드 블록 사용 금지 | 대화 예시는 알림 상자를 사용합니다 | -| 콜아웃용 굵은 문단 금지 | 대신 알림 상자를 사용합니다 | -| 섹션당 알림 상자 1-2개까지 | 튜토리얼은 큰 섹션당 3-4개까지 허용합니다 | -| 표 셀 / 목록 항목 | 최대 1-2문장 | -| 헤더 예산 | 문서당 `##` 8-12개, 섹션당 `###` 2-3개 | - -## 알림 상자(Starlight 문법) - -```md -:::tip[제목] -단축키, 모범 사례 -::: - -:::note[제목] -맥락, 정의, 예시, 필수 조건 -::: - -:::caution[제목] -주의 사항, 잠재적 문제 -::: - -:::danger[제목] -데이터 손실, 보안 문제 같은 중대한 경고에만 사용 -::: -``` - -### 표준 용도 - -| 알림 상자 | 사용처 | -| --- | --- | -| `:::note[필수 조건]` | 시작 전 필요한 의존성 | -| `:::tip[빠른 경로]` | 문서 상단의 짧은 요약 | -| `:::caution[중요]` | 중요한 주의 사항 | -| `:::note[예시]` | 명령/응답 예시 | - -## 표준 표 형식 - -**단계:** - -```md -| 단계 | 이름 | 내용 | -| --- | --- | --- | -| 1 | 분석 | 브레인스토밍, 리서치 *(선택 사항)* | -| 2 | 계획 | 요구사항 - PRD 또는 사양 *(필수)* | -``` - -**스킬:** - -```md -| 스킬 | 에이전트 | 목적 | -| --- | --- | --- | -| `bmad-brainstorming` | 분석가 | 새 프로젝트 브레인스토밍 | -| `bmad-prd` | PM | 제품 요구사항 문서 생성 | -``` - -## 폴더 구조 블록 - -"달성한 것" 섹션에서는 다음처럼 표시합니다. - -````md -``` -your-project/ -├── _bmad/ # BMad 설정 -├── _bmad-output/ -│ ├── planning-artifacts/ -│ │ └── PRD.md # 요구사항 문서 -│ ├── implementation-artifacts/ -│ └── project-context.md # 구현 규칙 (선택 사항) -└── ... -``` -```` - -## 튜토리얼 구조 - -```text -1. 제목 + 후킹 문장(결과를 설명하는 1-2문장) -2. 버전/모듈 안내(정보 또는 경고 알림 상자, 선택) -3. 배울 내용(결과 중심 글머리표 목록) -4. 필수 조건(정보 알림 상자) -5. 빠른 경로(tip 알림 상자 - 짧은 요약) -6. [주제] 이해하기(단계 전 맥락 - 단계/에이전트 표) -7. 설치(선택) -8. 1단계: [첫 번째 주요 작업] -9. 2단계: [두 번째 주요 작업] -10. 3단계: [세 번째 주요 작업] -11. 달성한 것(요약 + 폴더 구조) -12. 빠른 참조(스킬 표) -13. 자주 묻는 질문(FAQ 형식) -14. 도움 받기(커뮤니티 링크) -15. 핵심 요약(tip 알림 상자) -``` - -### 튜토리얼 체크리스트 - -- [ ] 후킹 문장이 결과를 1-2문장으로 설명합니다 -- [ ] "배울 내용" 섹션이 있습니다 -- [ ] 필수 조건이 알림 상자에 있습니다 -- [ ] 상단에 빠른 경로 요약 알림 상자가 있습니다 -- [ ] 단계, 스킬, 에이전트를 표로 제시합니다 -- [ ] "달성한 것" 섹션이 있습니다 -- [ ] 빠른 참조 표가 있습니다 -- [ ] 자주 묻는 질문 섹션이 있습니다 -- [ ] 도움 받기 섹션이 있습니다 -- [ ] 마지막에 핵심 요약 알림 상자가 있습니다 - -## 사용 가이드 구조 - -```text -1. 제목 + 후킹 문장("`X` 워크플로를 사용해..." 한 문장) -2. 사용 시점(3-5개 글머리표 목록) -3. 건너뛸 시점(선택) -4. 필수 조건(note 알림 상자) -5. 단계(번호가 붙은 ### 하위 섹션) -6. 얻는 결과(생성되는 산출물) -7. 예시(선택) -8. 팁(선택) -9. 다음 단계(선택) -``` - -### 사용 가이드 체크리스트 - -- [ ] 후킹 문장이 "`X` 워크플로를 사용해..."로 시작합니다 -- [ ] "사용 시점"에 3-5개 글머리표가 있습니다 -- [ ] 필수 조건이 나열되어 있습니다 -- [ ] 단계는 동작 동사로 시작하는 번호가 붙은 `###` 하위 섹션입니다 -- [ ] "얻는 결과"가 산출물을 설명합니다 - -## 개념 설명 구조 - -### 유형 - -| 유형 | 예시 | -| --- | --- | -| **인덱스/랜딩** | `core-concepts/index.md` | -| **개념** | `what-are-agents.md` | -| **기능** | `build.md` | -| **철학** | `why-solutioning-matters.md` | -| **FAQ** | `established-projects-faq.md` | - -### 일반 템플릿 - -```text -1. 제목 + 후킹 문장(1-2문장) -2. 개요/정의(무엇이며 왜 중요한지) -3. 핵심 개념(### 하위 섹션) -4. 비교 표(선택) -5. 사용할 때 / 사용하지 않을 때(선택) -6. 다이어그램(선택 - mermaid, 문서당 최대 1개) -7. 다음 단계(선택) -``` - -### 인덱스/랜딩 페이지 - -```text -1. 제목 + 후킹 문장(한 문장) -2. 콘텐츠 표(설명이 있는 링크) -3. 시작하기(번호 목록) -4. 경로 선택(선택 - 의사결정 트리) -``` - -### 개념 설명 문서 - -```text -1. 제목 + 후킹 문장(무엇인지) -2. 유형/범주(### 하위 섹션, 선택) -3. 주요 차이 표 -4. 구성 요소/부분 -5. 무엇을 사용해야 하나요? -6. 생성/커스터마이징(사용 가이드 링크) -``` - -### 기능 설명 문서 - -```text -1. 제목 + 후킹 문장(무엇을 하는지) -2. 빠른 정보(선택 - "적합한 경우:", "소요 시간:") -3. 사용할 때 / 사용하지 않을 때 -4. 작동 방식(mermaid 다이어그램 선택) -5. 핵심 이점 -6. 비교 표(선택) -7. 졸업/업그레이드 시점(선택) -``` - -### 철학/근거 문서 - -```text -1. 제목 + 후킹 문장(원칙) -2. 문제 -3. 해결책 -4. 핵심 원칙(### 하위 섹션) -5. 이점 -6. 적용 시점 -``` - -### 개념 설명 체크리스트 - -- [ ] 후킹 문장이 문서가 설명하는 내용을 말합니다 -- [ ] 스캔하기 쉬운 `##` 섹션으로 구성합니다 -- [ ] 3개 이상의 선택지가 있으면 비교 표를 사용합니다 -- [ ] 다이어그램에는 명확한 라벨이 있습니다 -- [ ] 절차적 질문에는 사용 가이드 링크를 제공합니다 -- [ ] 문서당 알림 상자는 최대 2-3개입니다 - -## 참조 문서 구조 - -### 유형 - -| 유형 | 예시 | -| --- | --- | -| **인덱스/랜딩** | `workflows/index.md` | -| **카탈로그** | `agents/index.md` | -| **심층 설명** | `document-project.md` | -| **설정** | `core-tasks.md` | -| **용어집** | `glossary/index.md` | -| **종합 가이드** | `bmgd-workflows.md` | - -### 참조 인덱스 페이지 - -```text -1. 제목 + 후킹 문장(한 문장) -2. 콘텐츠 섹션(각 범주에 ## 사용) - - 링크와 설명이 있는 글머리표 목록 -``` - -### 카탈로그 참조 - -```text -1. 제목 + 후킹 문장 -2. 항목(각 항목에 ## 사용) - - 짧은 설명(한 문장) - - **스킬:** 또는 **핵심 정보:** 형태의 평평한 목록 -3. 공통/공유 섹션(## 섹션, 선택) -``` - -### 항목 심층 참조 - -```text -1. 제목 + 후킹 문장(한 문장 목적) -2. 빠른 정보(note 알림 상자, 선택) - - 모듈, 스킬, 입력, 출력 목록 -3. 목적/개요(## 섹션) -4. 호출 방법(코드 블록) -5. 핵심 섹션(각 측면에 ## 사용) - - 하위 선택지에는 ### 사용 -6. 참고/주의 사항(tip 또는 caution 알림 상자) -``` - -### 설정 참조 - -```text -1. 제목 + 후킹 문장 -2. 목차(항목이 4개 이상이면 점프 링크) -3. 항목(각 설정/작업에 ## 사용) - - **굵은 요약** — 한 문장 - - **사용 시점:** 글머리표 목록 - - **작동 방식:** 번호 목록(최대 3-5개) - - **출력:** 예상 결과(선택) -``` - -### 종합 참조 가이드 - -```text -1. 제목 + 후킹 문장 -2. 개요(## 섹션) - - 구성을 보여주는 다이어그램 또는 표 -3. 주요 섹션(각 단계/범주에 ## 사용) - - 항목(각 항목에 ### 사용) - - 표준 필드: 스킬, 에이전트, 입력, 출력, 설명 -4. 다음 단계(선택) -``` - -### 참조 체크리스트 - -- [ ] 후킹 문장이 문서가 참조하는 내용을 말합니다 -- [ ] 구조가 참조 유형에 맞습니다 -- [ ] 항목은 전체적으로 일관된 구조를 사용합니다 -- [ ] 구조화/비교 데이터에는 표를 사용합니다 -- [ ] 개념적 깊이가 필요한 곳에는 개념 설명 문서 링크를 둡니다 -- [ ] 알림 상자는 최대 1-2개입니다 - -## 용어집 구조 - -Starlight는 헤더에서 오른쪽 "이 페이지에서" 탐색을 생성합니다. - -- 범주는 `##` 헤더로 작성합니다. 오른쪽 탐색에 표시됩니다 -- 용어는 개별 헤더가 아니라 표 안의 간결한 행으로 작성합니다 -- 인라인 TOC는 사용하지 않습니다. 오른쪽 사이드바가 탐색을 담당합니다 - -### 표 형식 - -```md -## 범주 이름 - -| 용어 | 정의 | -| --- | --- | -| **에이전트** | 특정 전문성을 갖고 워크플로 전반에서 사용자를 안내하는 특화 AI 페르소나입니다. | -| **워크플로** | 산출물을 만들기 위해 AI 에이전트 활동을 조율하는 여러 단계의 안내형 프로세스입니다. | -``` - -### 정의 규칙 - -| 해야 할 것 | 하지 말 것 | -| --- | --- | -| 무엇인지 또는 무엇을 하는지로 시작합니다 | "이것은..." 또는 "이 용어는..."으로 시작합니다 | -| 1-2문장으로 유지합니다 | 여러 문단으로 설명합니다 | -| 셀 안의 용어명을 굵게 표시합니다 | 용어를 일반 텍스트로 둡니다 | - -### 컨텍스트 표시 - -범위가 제한된 용어는 정의 시작에 이탤릭 컨텍스트를 추가합니다. - -- `*직접 진입 구현 전용.*` -- `*BMad Method/엔터프라이즈.*` -- `*N단계.*` -- `*BMGD.*` -- `*기존 프로젝트.*` - -### 용어집 체크리스트 - -- [ ] 용어는 개별 헤더가 아니라 표에 있습니다 -- [ ] 범주 안에서 용어를 사전순으로 정렬합니다 -- [ ] 정의는 1-2문장입니다 -- [ ] 컨텍스트 표시는 이탤릭입니다 -- [ ] 셀 안의 용어명은 굵게 표시합니다 -- [ ] "이것은..." 또는 "이 용어는..." 형태의 정의를 사용하지 않습니다 - -## FAQ 섹션 - -```md -## 질문 - -- [항상 아키텍처가 필요한가요?](#항상-아키텍처가-필요한가요) -- [나중에 계획을 바꿀 수 있나요?](#나중에-계획을-바꿀-수-있나요) - -### 항상 아키텍처가 필요한가요? - -아키텍처가 도움이 되는 작업에만 필요합니다. 범위가 명확한 작업은 구현으로 바로 들어갈 수 있습니다. - -### 나중에 계획을 바꿀 수 있나요? - -예. `bmad-correct-course` 워크플로가 구현 중 범위 변경을 처리합니다. - -**여기에 답이 없는 질문이 있나요?** [이슈를 열거나](...) [Discord](...)에서 물어보세요. -``` - -## 검증 명령 - -문서 변경을 제출하기 전에 다음을 실행하세요. - -```bash -cd docs-site -npm run fix-links # 링크 형식 수정 미리보기 -npm run fix-links -- --write # 수정 적용 -npm run validate-links # 링크 존재 여부 확인 -npm run build # 빌드 오류 없음 확인 -``` diff --git a/docs/ko-kr/build/build-a-change.md b/docs/ko-kr/build/build-a-change.md deleted file mode 100644 index defc7ef2a2..0000000000 --- a/docs/ko-kr/build/build-a-change.md +++ /dev/null @@ -1,117 +0,0 @@ ---- -title: '변경 사항 구현하기' -description: bmad-build로 요청, 이슈, 사양 또는 스토리를 구현하고 검토가 끝난 코드로 완성하는 방법 -sidebar: - order: 1 ---- - -핵심 구현 스킬은 `bmad-build`입니다. 한 문장, 이슈, 사양, 계획이 끝난 스토리처럼 원하는 작업을 어떤 형태로든 전달할 수 있습니다. 스킬은 코드베이스와 상위 컨텍스트를 조사하고 변경을 계획·구현한 뒤, 결과를 검토하고 발견한 버그를 수정합니다. 전체 실행 과정은 [`bmad-build` 실행하기](#bmad-build-실행하기)에서 확인하세요. - -## 작업 규모 정하기 - -변경 사항을 안전하게 처리할 수 있는 가장 간단한 BMad 경로를 선택하세요. 일반적인 세션은 하나의 목표를 다룹니다. 테스트를 제외하고 약 500줄의 코드를 추가하거나 수정하며 대상 파일도 몇 개 정도인 작업입니다. 이 범위에 들어오면 `bmad-build`에 맡기세요. 더 크다면 먼저 작업을 계획해야 합니다. [개발 경로 선택하기](../how-to/choose-a-development-path.md)를 참고하세요. 시작하기 전에는 규모를 판단하기 어려울 수 있으므로 확신이 없다면 `bmad-help`에 물어보세요. - -직접 검토해도 되는 단순한 편집은 이 과정을 건너뛰고 에이전트에게 바로 요청해도 됩니다. 다만 버그가 프로덕션에 반영될 가능성이 있다면 `bmad-build`를 사용하는 편이 안전합니다. - -## `bmad-build` 실행하기 - -![bmad-build 워크플로 다이어그램](/diagrams/build-run.svg) - -### 1. 새 채팅 시작 - -AI IDE에서 **새 채팅**을 여세요. 다른 워크플로에서 사용하던 세션을 재사용하면 컨텍스트가 섞여 실행에 혼란을 줄 수 있습니다. - -### 2. 의도 전달 - -명령 전후나 명령과 함께 변경 내용을 설명할 수 있습니다. 깔끔하게 정리할 필요는 없습니다. 두서없는 설명, 음성으로 풀어낸 생각, 아직 구체화되지 않은 아이디어, 이슈 링크, 파일, 계획된 스토리 등 모델이 구체적인 목표로 바꿀 수 있는 형식이면 됩니다. - -```text -/bmad-build 빈 비밀번호를 허용하는 로그인 검증 버그를 수정해 줘. -``` - -```text -/bmad-build https://github.com/org/repo/issues/42 이슈를 수정해 줘. -``` - -```text -/bmad-build _bmad-output/implementation-artifacts/my-intent.md에 적힌 의도를 구현해 줘. -``` - -```text -문제는 인증 미들웨어에 있는 것 같아. 토큰 만료를 확인하지 않고 있어. -살펴보니 src/auth/middleware.ts의 47번째 줄에서 -exp 검사를 완전히 건너뛰고 있어. /bmad-build -``` - -```text -/bmad-build -> 어떤 작업을 할까요? -콜백 대신 async/await를 사용하도록 UserService를 리팩터링해 줘. -``` - -### 3. 근거를 확인해 의도 확정 - -`bmad-build`는 사용자의 요청에서 출발해 코드베이스와 상위 계획 산출물을 조사합니다. 그런 다음 결정에 필요한 중요한 정보가 빠졌는지 판단합니다. 처음 요청이 거칠어도 근거가 충분하고 명확하다면 별도의 명확화 단계 없이 진행합니다. 불분명한 내용이 있으면 먼저 근거를 찾습니다. 저장소와 계획 컨텍스트로도 판단할 수 없는 사항만 완성된 설계의 미결 질문으로 남습니다. 작업을 시작하기도 전에 긴 인터뷰를 진행하지 않습니다. - -미결 질문이 나오면 신중하게 답하세요. 이 단계의 잘못된 판단은 나중에 발견할수록 수정 비용이 큽니다. - -### 4. 요청이 나오면 계획 승인 - -조사가 끝나면 `bmad-build`는 가장 간단하면서도 안전한 경로를 선택합니다. 확정된 설계를 기준으로 의도 누락, 되돌릴 수 없는 작업, 영향 범위라는 세 가지 정보를 보고합니다. 의도 누락이 없고 되돌릴 수 없는 작업도 없으며 영향 범위가 작다면 간단한 경로로 진행합니다. 같은 세션에서 최소 사양을 작성하고 구현한 뒤 결과를 검토합니다. 하나라도 문제가 있으면 먼저 상세 계획을 작성합니다. 의도 누락은 미결 질문으로 기록되며 사용자가 답한 뒤에야 계획을 승인할 수 있습니다. - -계획이 올바른 결과를 설명한다면 승인하세요. 그렇지 않다면 수정을 요청하세요. 코드를 고치는 것보다 계획을 고치는 편이 훨씬 저렴합니다. - -### 5. 구현 및 검토 - -경로가 정해지면 `bmad-build`가 변경을 구현하고 독립된 리뷰어로 작업을 검토합니다. 현재 변경에 속하는 문제를 수정한 뒤 로컬에 커밋합니다. 이 과정은 하위 에이전트를 생성할 수 있거나 적어도 명령줄에서 다른 모델을 호출하고 결과를 기다릴 수 있는 플랫폼에서 가장 잘 작동합니다. - -리뷰는 가능한 의견을 모두 쏟아내는 과정이 아니라 분류 작업입니다. 현재 변경 때문에 생긴 문제는 고치고 관련 없는 기존 문제는 보류합니다. 계획이 약해 코드가 잘못됐다면 계획 단계로, 목표가 잘못돼 계획까지 어긋났다면 목표 단계로 돌아갑니다. diff만 임시로 고치지 않고 문제가 시작된 계층부터 다시 생성합니다. - -### 6. 결과 검토 - -작업이 끝나면 `bmad-build`가 완성된 변경 사항과 리뷰 기록을 보여줍니다. 이때가 주요 체크포인트입니다. 완성된 작업을 안내에 따라 살펴보려면 [변경 사항 둘러보기](walk-through-a-change.md)를 참고하세요. - -- diff를 훑어 변경이 의도와 맞는지 확인합니다. -- 이상한 점이 있으면 에이전트에게 수정할 내용을 말하세요. 같은 세션에서 작업을 이어갈 수 있습니다. - -결과가 만족스러우면 커밋을 푸시하세요. 스킬이 푸시와 PR 생성을 제안할 수도 있습니다. - -:::caution[문제가 생기면] -푸시한 변경이 예상치 못한 문제를 일으키면 `git revert HEAD`로 마지막 커밋을 안전하게 되돌리세요. 그런 다음 새 채팅을 열고 다른 접근 방식으로 `bmad-build`를 다시 실행합니다. -::: - -## 얻는 결과 - -- 변경 사항이 반영된 소스 파일 -- 프로젝트에 테스트 모음이 있다면 통과하는 테스트 -- Conventional Commit 형식의 푸시 준비 완료 커밋 -- 실행에 대한 구현 기록. 상위 사양이나 스토리가 있다면 그 옆에 저장됩니다. - -완성된 작업에 API 및 E2E 테스트를 추가하려면 [완료된 작업 테스트하기](test-completed-work.md)를 참고하세요. - -## 보류 작업 - -`bmad-build`는 실행마다 하나의 목표에 집중합니다. 요청에 여러 독립 목표가 있거나 리뷰에서 현재 변경과 관련 없는 기존 문제가 드러나면, 모두 한꺼번에 처리하지 않고 구현 산출물 디렉터리의 `deferred-work.md`에 기록합니다. - -실행 후 이 파일을 확인하세요. 나중에 처리할 후속 작업의 백로그입니다. 각 항목은 새 `bmad-build` 실행에 다시 전달할 수 있습니다. - -## 먼저 계획해야 할 때 - -다음과 같은 경우에는 `bmad-build`를 실행하기 전에 사양을 추가하거나 PRD, UX, 아키텍처, 스토리를 계획하세요. - -- 여러 시스템에 영향을 주거나 많은 파일을 함께 수정해야 할 때 -- 범위가 불분명해 먼저 요구사항을 구체화해야 할 때 -- 팀이 참고할 문서나 아키텍처 결정을 남겨야 할 때 -- 의도를 명확히 하는 과정에서 한 세션 안에 풀기 어려운 모순이 계속 드러날 때 - -큰 작업은 한 세션 단위의 변경 여러 개로 나뉩니다. 구현하면서 새로 알게 된 내용에 따라 작업 순서가 바뀔 수도 있습니다. 상위 사양은 공동 목표를 유지하고 스토리 기록은 결정 사항과 완료 상태를 전달합니다. 통합 검사와 회고는 전체 결과를 확인합니다. `bmad-build`는 이 중 한 단위만 담당하며 백로그를 관리하거나 다음 스토리를 선택하거나 이후 검사를 대신하지 않습니다. - -기반을 만들거나 위험도가 높거나 이후 작업의 패턴을 정하는 중요한 스토리에는 `bmad-build`를 사용하세요. 패턴이 안정된 뒤에는 `bmad-build-auto`로 사람을 기다리지 않고 한 단위를 실행할 수 있습니다. [자율 개발 루프](../reference/build-auto.md)를 참고하세요. - -## 이런 방식으로 작동하는 이유 - -LLM은 중요해 보이는 것은 찾을 수 있지만 실제로 무엇이 중요한지는 알지 못합니다. 사람의 주의가 전혀 없으면 작업 흐름은 금세 무너집니다. - -추론에 10분을 쓰는 편이 사람의 주의를 10초 빼앗는 것보다 대체로 저렴합니다. 모든 단계를 직접 지켜보면 계속 진행하라는 응답만 반복하게 됩니다. 불필요하고 지루한 데다 사용자가 병목이 됩니다. - -`bmad-build`는 단순히 계속 진행할지 판단하는 일을 기계에 맡깁니다. 사용자의 주의는 근거로 해결할 수 없는 미결 질문, 상세 경로의 계획 승인, 완성된 변경 검토처럼 꼭 필요한 순간에만 사용합니다. 안전하게 결정하지 못했을 때만 사용자를 다시 부릅니다. 이 분류가 언제나 완벽하지는 않습니다. 그래도 가치가 낮은 발견 사항을 놓치는 편이 수많은 잡음으로 사용자를 압도하는 것보다 낫습니다. diff --git a/docs/ko-kr/build/test-completed-work.md b/docs/ko-kr/build/test-completed-work.md deleted file mode 100644 index 28bc94b9f0..0000000000 --- a/docs/ko-kr/build/test-completed-work.md +++ /dev/null @@ -1,79 +0,0 @@ ---- -title: '완료된 작업 테스트하기' -description: 구현 후 내장 QA로 테스트를 생성할지, 전략·추적성·출시 게이트를 제공하는 TEA를 사용할지 결정하는 방법 -sidebar: - order: 3 ---- - -변경 구현이 끝나면 자동화 테스트를 더 추가해야 하는지, 어떤 BMad 경로로 만들지 결정하세요. 내장 스킬인 `bmad-qa-generate-e2e-tests`는 이미 구현된 코드에 API 및 E2E 테스트를 생성합니다. 테스트 전략, 위험 기반 계획 또는 출시 게이트가 필요하다면 테스트 설계자(Test Architect, TEA) 모듈을 설치하세요. 전체 실행 과정은 [`bmad-qa-generate-e2e-tests` 실행하기](#bmad-qa-generate-e2e-tests-실행하기)에서 확인할 수 있습니다. - -여기서는 완성된 작업의 테스트 커버리지를 생성합니다. 코드 리뷰가 아니며 [변경 사항 둘러보기](walk-through-a-change.md)에서 제안하는 수동 확인도 아닙니다. - -## 어떤 경로를 선택해야 하나요? - -| 기준 | 내장 QA | TEA | -| --- | --- | --- | -| **적합한 경우** | 구현된 기능의 테스트 커버리지 추가 | 전략, 추적성 또는 출시 게이트가 필요할 때 | -| **설정** | BMM에 포함 | TEA 모듈 별도 설치 | -| **접근 방식** | 현재 구현된 코드에서 테스트 생성 | 먼저 계획한 뒤 추적성을 유지하며 생성 | -| **다루는 범위** | API 및 E2E 테스트 | 설계, ATDD, 자동화, 리뷰, NFR, 게이트 | -| **전략** | 정상 경로와 몇 가지 주요 오류 | 위험 기반 우선순위(P0~P3) | - -:::tip[내장 QA로 시작] -대부분의 프로젝트는 `bmad-qa-generate-e2e-tests`로 시작하면 됩니다. 이 스킬이 제공하지 않는 테스트 전략, 품질 게이트 또는 요구사항 추적성이 필요해질 때 TEA를 설치하세요. -::: - -## `bmad-qa-generate-e2e-tests` 실행하기 - -**새 채팅**을 열고 스킬 이름을 말하세요. 명령 전후나 명령과 함께 기능, 디렉터리 또는 "테스트되지 않은 부분을 찾아 줘"처럼 대상을 설명할 수 있습니다. - -```text -/bmad-qa-generate-e2e-tests -``` - -```text -/bmad-qa-generate-e2e-tests 로그인 흐름의 API 및 E2E 테스트를 만들어 줘. -``` - -프로젝트에서 이미 사용하는 테스트 프레임워크를 그대로 활용합니다. 프레임워크가 없다면 기술 스택을 확인하고 하나를 제안합니다. - -### 실행 과정 - -1. **테스트 프레임워크 감지** - 의존성과 기존 테스트를 살펴 Playwright, Jest, Vitest, Cypress 같은 프레임워크를 찾습니다. -2. **기능 식별** - 무엇을 테스트할지 묻거나 코드베이스에서 기능을 자동으로 찾습니다. -3. **API 테스트 생성** - 엔드포인트가 있다면 상태 코드, 응답 구조, 정상 경로, 오류 사례 한두 개를 검사합니다. -4. **E2E 테스트 생성** - UI가 있다면 역할, 레이블, 텍스트 같은 의미 기반 로케이터와 사용자에게 보이는 결과 검증으로 사용자 흐름을 다룹니다. -5. **테스트 실행** - 생성한 테스트를 실행하고 실패하면 바로 수정합니다. -6. **요약 작성** - 생성한 테스트와 아직 다루지 못한 범위를 기록합니다. - -생성된 테스트는 의도적으로 단순하게 유지됩니다. 표준 프레임워크 API를 사용하고 각 테스트는 서로 독립적이며 하드코딩된 대기를 넣지 않습니다. 테스트 설명은 기능 문서처럼 읽을 수 있게 작성됩니다. - -## 얻는 결과 - -- 프로젝트의 `tests/` 디렉터리에 생성된 테스트 파일 -- 구현 산출물 디렉터리의 `tests/test-summary.md`에 저장된 테스트 요약 -- 이번 세션에서 한 번 이상 실행해 통과한 테스트 - -## 제한 사항 - -`bmad-qa-generate-e2e-tests`는 테스트만 생성합니다. 구현을 검토하지 않습니다. 구현 중에는 `bmad-build`가 검토하고 추가 검토가 필요하면 `bmad-code-review`를 사용하세요. - -테스트 전략, 위험 순위, 요구사항 추적성, NFR 근거, 출시 여부를 결정하는 게이트는 만들지 않습니다. PRD나 아키텍처를 불러와 요구사항과 커버리지를 연결하지도 않습니다. 정상 경로와 몇 가지 주요 오류까지만 다루며 더 많은 엣지 케이스는 후속 작업으로 남습니다. - -## TEA를 사용해야 할 때 - -다음과 같이 내장 스킬만으로 부족하다면 TEA를 설치하세요. - -- 요구사항 추적성이나 컴플라이언스 근거가 필요할 때 -- 여러 기능의 테스트 우선순위를 위험도에 따라 정해야 할 때 -- 정식 품질 게이트로 출시 여부를 결정할 때 -- 테스트를 작성하기 전에 테스트 전략이 필요할 때 -- 하나의 테스트 생성·실행 스킬로 다루기에는 작업이 너무 커졌을 때 - -TEA는 별도 모듈입니다. 현재 워크플로, 명령, 설정 방법은 [TEA 문서](https://bmad-code-org.github.io/bmad-method-test-architecture-enterprise/)를 참고하세요. 다른 BMad 모듈과 함께 설치할 수 있습니다. 모듈 선택 방법은 [공식 모듈](../reference/modules.md)에서 확인하세요. - -## 워크플로에서의 위치 - -[`bmad-build`](build-a-change.md)는 변경을 구현하고 기존 테스트 모음이 있다면 모두 통과하는 상태로 작업을 마칩니다. 그다음 이 페이지의 테스트 경로를 선택합니다. 완성된 작업에 API 및 E2E 커버리지를 추가하거나 TEA로 전환하면 됩니다. - -내장 QA는 변경 하나가 끝날 때마다 실행할 수 있습니다. 에픽이 모두 끝날 때까지 기다릴 필요가 없습니다. 일반적으로 `bmad-build`로 구현하고 필요하면 [결과를 둘러본](walk-through-a-change.md) 뒤 여기서 테스트를 생성합니다. 에픽 전체가 끝난 후 실행하는 `bmad-retrospective`는 목적이 다릅니다. 테스트 모음이 아니라 상위 사양을 기준으로 에픽 전체를 평가합니다. diff --git a/docs/ko-kr/build/walk-through-a-change.md b/docs/ko-kr/build/walk-through-a-change.md deleted file mode 100644 index cbad53b785..0000000000 --- a/docs/ko-kr/build/walk-through-a-change.md +++ /dev/null @@ -1,90 +0,0 @@ ---- -title: '변경 사항 둘러보기' -description: bmad-walkthrough로 완성된 변경을 살펴보고 승인, 재작업 또는 추가 논의 여부를 결정하는 방법 -sidebar: - order: 2 ---- - -`bmad-walkthrough`는 완성된 변경을 목적과 컨텍스트부터 세부 사항까지 차례로 안내합니다. 사용자는 설명을 따라가며 승인할지, 다시 작업할지, 더 논의할지를 결정할 수 있습니다. 전체 실행 과정은 [`bmad-walkthrough` 실행하기](#bmad-walkthrough-실행하기)에서 확인하세요. - -이 스킬의 목적은 사람이 변경을 이해하도록 돕는 것입니다. `bmad-build`가 이미 수행한 리뷰나 `bmad-code-review`를 대신하지 않습니다. - -## 사용 시점 - -가장 일반적인 사용 시점은 [`bmad-build`](build-a-change.md)가 끝난 직후입니다. 구현이 완료되고 리뷰 경로가 추가된 사양 파일이 열리면 출시 여부를 결정해야 합니다. 이때 "walkthrough"라고 말하면 됩니다. - -Build는 사람의 개입을 줄인 채 오래 실행됩니다. Walkthrough에서는 사용자가 다시 운전대를 잡습니다. diff를 눈으로 훑을 수도 있지만 변경이 여러 파일에 걸치면 흐름을 놓치거나, 서로 떨어진 변경의 연결을 지나치거나, 충분히 이해하지 못한 채 승인할 수 있습니다. 원본 diff는 Git의 파일 순서로 내용을 보여주는데, 이 순서는 이해가 쌓이는 순서와 거의 일치하지 않습니다. - -단독으로도 사용할 수 있습니다. - -- **PR 리뷰** - 특히 파일 수가 많거나 여러 영역에 걸친 변경을 검토할 때 -- **변경 내용 파악** - 직접 작성하지 않은 브랜치에서 무슨 일이 있었는지 이해할 때 -- **스프린트 리뷰** - 스프린트 상태 파일에서 `review`로 표시된 스토리를 찾아볼 때 - -"walkthrough" 또는 "이 변경을 따라가며 설명해 줘"라고 말해 실행하세요. 어떤 터미널에서도 작동하지만 VS Code나 Cursor 같은 IDE 안에서 사용하면 더 편리합니다. 각 단계에 `path:line` 참조가 표시되며 IDE 내장 터미널에서는 이 참조를 클릭할 수 있습니다. - -## `bmad-walkthrough` 실행하기 - -![bmad-walkthrough 워크플로 다이어그램](/diagrams/walkthrough-run.svg) - -`bmad-build`가 끝난 뒤 같은 채팅에서 "walkthrough"라고 말하세요. 다른 변경을 검토하려면 새 채팅을 열고 `/bmad-walkthrough`에 PR, 브랜치, 사양 경로 또는 현재 Git 상태를 전달합니다. - -```text -walkthrough -``` - -```text -/bmad-walkthrough https://github.com/org/repo/pull/42를 검토해 줘. -``` - -워크플로는 다섯 단계로 진행됩니다. 각 단계는 이전 단계에서 이해한 내용을 바탕으로 "무엇이 바뀌었나?"에서 "출시해도 되는가?"로 초점을 옮깁니다. 스킬은 diff와 사양이 있다면 해당 사양, 주변 코드베이스를 읽고 `git diff`의 파일 순서가 아닌 이해하기 좋은 순서로 변경을 보여줍니다. - -### 1. 방향 잡기 - -워크플로는 PR, 커밋, 브랜치, 사양 파일 또는 현재 Git 상태에서 변경 대상을 식별합니다. 그런 다음 한 줄로 의도를 요약하고 변경 파일 수, 영향을 받은 모듈, 논리 코드 줄 수, 경계를 넘는 변경, 새 공개 인터페이스 같은 영향 범위 통계를 보여줍니다. - -이 단계에서는 "내가 보려던 변경이 맞나?"를 확인합니다. 코드를 읽기 전에 올바른 대상을 보고 있는지 확인하고 예상 범위와 맞는지 가늠하세요. - -### 2. 둘러보기 - -변경은 파일이 아니라 **관심사**를 기준으로 묶습니다. 관심사는 "입력 검증"이나 "API 계약"처럼 서로 밀접하게 연결된 설계 의도입니다. 각 관심사에는 이 접근 방식을 선택한 이유와 코드에서 따라갈 수 있는 `path:line` 지점이 붙습니다. - -이 단계에서는 코드가 정확한지가 아니라 해당 접근 방식이 시스템에 적합한지를 판단합니다. 관심사는 가장 높은 수준의 의도부터 보조 구현까지 하향식으로 제시됩니다. 아직 살펴보지 않은 내용을 먼저 참조하지 않습니다. - -### 3. 상세 검토 - -설계를 이해한 뒤에는 잘못됐을 때 영향이 가장 큰 지점 2~5개를 보여줍니다. `[auth]`, `[schema]`, `[billing]`, `[public API]`, `[security]` 같은 위험 범주를 붙이고 문제가 생겼을 때 영향이 큰 순서로 정렬합니다. - -이 단계는 버그 찾기가 아닙니다. 자동화 테스트와 CI가 정확성을 검사합니다. 상세 검토에서는 잘못됐을 때 비용이 큰 지점을 파악합니다. 특정 영역을 더 깊게 살펴보려면 "이 영역을 더 파고들어 줘"라고 말해 정확성에 초점을 맞춘 재검토를 요청할 수 있습니다. - -독립 에이전트가 이미 사양을 검토했다면 관련 발견 사항도 이 단계에 나타납니다. 이미 수정된 버그가 아니라 사용자가 알아야 한다고 표시된 결정 사항을 보여줍니다. - -### 4. 테스트 - -변경이 작동하는 모습을 수동으로 확인할 방법 2~5개를 제안합니다. 자동화 테스트 명령이 아니라 테스트 모음만으로 얻기 어려운 확신을 주는 관찰 방법입니다. 시도할 UI 동작, 실행할 CLI 명령, 보낼 API 요청과 각각의 예상 결과가 포함됩니다. - -사용자에게 보이는 동작이 없다면 그렇다고 알려줍니다. 불필요한 확인 작업을 만들지 않습니다. - -### 5. 마무리 - -승인, 재작업, 추가 논의 중 하나를 선택합니다. 로컬 `bmad-build` 결과를 승인한다면 푸시할 준비가 된 것입니다. 에이전트가 푸시와 PR 생성을 도울 수 있습니다. PR을 승인할 때는 `gh pr review --approve` 실행을 도울 수 있습니다. 재작업을 선택하면 문제가 접근 방식, 사양, 구현 중 어디에서 시작됐는지 진단하고 구체적인 코드 위치에 연결된 피드백을 작성하도록 돕습니다. - -## 보고서가 아닌 대화 - -워크플로는 각 단계를 최종 답이 아닌 대화의 출발점으로 제시합니다. 단계 사이 또는 도중에도 LLM과 대화하고 질문하거나 구성 방식에 이의를 제기할 수 있습니다. 다른 스킬을 불러 새로운 관점에서 살펴볼 수도 있습니다. - -- **"오류 처리를 고급 도출로 다시 검토해 줘"** - 특정 영역의 분석을 다시 생각하고 다듬습니다. -- **"이 스키마 마이그레이션이 안전한지 파티 모드로 토론해 줘"** - 여러 에이전트의 관점으로 집중 토론을 진행합니다. -- **"코드 리뷰를 실행해 줘"** - 적대적 검토와 엣지 케이스 분석을 포함한 구조화된 발견 사항을 생성합니다. - -Walkthrough는 사용자를 정해진 순서에 가두지 않습니다. 구조가 필요할 때는 안내를 제공하고 더 깊이 탐색할 때는 자유롭게 대화할 수 있습니다. 다섯 단계는 전체 그림을 빠뜨리지 않도록 돕지만 각 단계에서 얼마나 깊게 살펴볼지와 어떤 도구를 사용할지는 사용자가 결정합니다. - -## 리뷰 경로 - -둘러보기 단계는 **권장 리뷰 순서**가 있을 때 가장 잘 작동합니다. 사양 작성자가 변경 내용을 안내하려고 남긴 지점 목록입니다. 사양에 이 목록이 있다면 워크플로가 그대로 사용합니다. - -작성자가 만든 경로가 없다면 워크플로가 diff와 코드베이스 컨텍스트를 바탕으로 생성합니다. 자동으로 만든 경로는 작성자가 직접 구성한 것보다 품질이 낮지만 파일 순서대로 변경을 읽는 것보다는 훨씬 낫습니다. - -## 하지 않는 일 - -`bmad-walkthrough`는 리뷰 스킬이 아닙니다. `bmad-build`가 이미 수행한 리뷰, 완료된 스토리에서 같은 실행을 다시 호출하는 작업, `bmad-code-review`를 대신하지 않습니다. 린터, 타입 검사기, 테스트 모음을 실행하지 않으며 심각도 점수나 통과·실패 판정도 만들지 않습니다. 사람이 중요한 곳에 판단을 집중하도록 돕는 읽기 안내서입니다. diff --git a/docs/ko-kr/explanation/advanced-elicitation.md b/docs/ko-kr/explanation/advanced-elicitation.md deleted file mode 100644 index 45ef4cffa3..0000000000 --- a/docs/ko-kr/explanation/advanced-elicitation.md +++ /dev/null @@ -1,49 +0,0 @@ ---- -title: "고급 도출" -description: 구조화된 추론 방법으로 LLM이 자신의 작업을 다시 생각하게 합니다 -sidebar: - order: 4 ---- - -LLM이 방금 생성한 결과를 다시 검토하게 만드세요. 추론 방법을 선택하면 LLM이 그 방법을 자신의 출력에 적용하고, 사용자는 개선 사항을 유지할지 결정합니다. - -## 고급 도출이란? - -구조화된 두 번째 검토 단계입니다. AI에게 막연히 "다시 해봐" 또는 "더 좋게 만들어"라고 말하는 대신 특정 추론 방법을 선택하면, AI가 그 관점으로 자신의 출력을 다시 살핍니다. - -이 차이는 중요합니다. 모호한 요청은 모호한 수정을 낳습니다. 구체적인 추론 방법을 지정하면 검토 관점이 분명해져 일반적인 재시도로는 놓칠 인사이트를 찾을 수 있습니다. - -## 사용 시점 - -- 워크플로가 콘텐츠를 생성한 뒤 대안을 보고 싶을 때 -- 출력은 괜찮아 보이지만 더 깊이가 있을 것 같을 때 -- 가정을 스트레스 테스트하거나 약점을 찾고 싶을 때 -- 다시 생각하는 과정이 도움이 되는 중요한 콘텐츠일 때 - -워크플로는 결정 지점에서 고급 도출을 제안합니다. LLM이 무언가를 생성한 뒤 실행할지 묻습니다. - -## 작동 방식 - -1. LLM이 내용에 맞는 방법 5개를 제안합니다 -2. 하나를 고릅니다(또는 다른 선택지를 보려고 다시 섞습니다) -3. 선택한 방법을 적용해 개선 사항을 보여 줍니다 -4. 수락하거나 버리고, 반복하거나 계속합니다 - -## 내장 방법 - -수십 가지 추론 방법을 사용할 수 있습니다. 예시는 다음과 같습니다. - -- **사전 실패 분석** - 프로젝트가 이미 실패했다고 가정하고 이유를 역추적합니다 -- **제1원칙 사고** - 가정을 걷어내고 근거 사실에서 다시 세웁니다 -- **역전 사고** - 실패를 보장하는 방법을 묻고, 그 일을 피합니다 -- **레드 팀 vs 블루 팀** - 자신의 작업을 공격한 뒤 방어합니다 -- **소크라테스식 질문** - 모든 주장에 "왜?"와 "어떻게 알아?"를 던집니다 -- **제약 제거** - 모든 제약을 제거해 무엇이 바뀌는지 보고, 선택적으로 다시 추가합니다 -- **이해관계자 매핑** - 각 이해관계자 관점에서 다시 평가합니다 -- **유추 추론** - 다른 도메인의 유사점을 찾아 그 교훈을 적용합니다 - -그 밖에도 훨씬 많습니다. AI는 콘텐츠에 가장 관련 있는 선택지를 고르고, 사용자는 실행할 방법을 선택합니다. - -:::tip[시작점] -사전 실패 분석은 어떤 사양이나 계획에도 좋은 첫 선택입니다. 표준 리뷰가 놓치는 빈틈을 꾸준히 찾아냅니다. -::: diff --git a/docs/ko-kr/explanation/analysis-phase.md b/docs/ko-kr/explanation/analysis-phase.md deleted file mode 100644 index 7fa4522f62..0000000000 --- a/docs/ko-kr/explanation/analysis-phase.md +++ /dev/null @@ -1,72 +0,0 @@ ---- -title: "분석 단계: 아이디어에서 기반까지" -description: 브레인스토밍, 리서치, 제품 개요, PRFAQ가 무엇이며 언제 쓰는지 설명합니다 -sidebar: - order: 2 ---- - -분석 단계(단계 1)는 제품을 만들기로 확정하기 전에 생각을 명확하게 정리하도록 돕습니다. 이 단계의 모든 도구는 선택 사항이지만, 분석을 완전히 건너뛰면 PRD가 통찰이 아닌 가정 위에 세워집니다. - -## 왜 계획 전에 분석이 필요한가? - -PRD는 "무엇을 만들고 왜 만드는가?"에 답합니다. 생각이 모호하면 PRD도 모호해지고, 뒤따르는 모든 문서에도 그 모호함이 이어집니다. 불명확한 PRD를 바탕으로 만든 아키텍처는 잘못된 기술을 선택하기 쉽고, 부실한 아키텍처에서 나온 스토리는 엣지 케이스를 놓칩니다. 그만큼 비용도 쌓입니다. - -분석 도구는 PRD를 더 명확하게 만들기 위해 존재합니다. 창의적 탐색, 시장 현실, 고객 관점, 실행 가능성 등 서로 다른 각도에서 문제를 검토합니다. 덕분에 PM 에이전트와 작업을 시작할 때 무엇을 누구를 위해 만들지 분명히 알 수 있습니다. - -## 도구들 - -### 브레인스토밍 - -**무엇인가요.** 검증된 아이디어 발상 기법을 사용하는 안내형 창의 세션입니다. AI는 아이디어를 대신 생성하지 않고, 구조화된 연습을 통해 사용자가 직접 아이디어를 끌어내도록 돕는 코치 역할을 합니다. - -**왜 있나요.** 초기 아이디어는 요구사항으로 굳어지기 전에 발전할 여지가 필요합니다. 브레인스토밍은 그 여지를 만듭니다. 문제 도메인은 있지만 명확한 해결책이 없거나, 방향을 확정하기 전에 여러 가능성을 탐색하고 싶을 때 특히 유용합니다. - -**언제 쓰나요.** 만들고 싶은 것에 대한 막연한 생각은 있지만 개념이 아직 구체화되지 않았을 때 사용합니다. 개념은 정했지만 대안과 비교해 압박 검증하고 싶을 때도 유용합니다. - -세션 작동 방식은 [브레인스토밍](./brainstorming.md)을 참고하세요. - -### 리서치(Deep Recon) - -**무엇인가요.** `bmad-deep-recon` 하나로 아이디어의 어떤 측면이든 조사합니다. 유형별 리서치 팩은 시장(경쟁자, 트렌드, 규모), 도메인(주제 전문성과 용어), 기술(실현 가능성과 구현 접근 방식), 경쟁사 분석, 사용자 목소리, 학술 문헌을 다룹니다. 사용 중인 심층 리서치 도구에 넣을 프롬프트를 작성하거나 완성된 보고서를 인용이 포함된 요약으로 처리할 수 있습니다. 리서치를 직접 실행하는 방식도 지원합니다. - -**왜 있나요.** 가정만으로 제품을 만들면 아무도 필요로 하지 않는 결과가 나오기 쉽습니다. 리서치는 개념을 현실에 연결합니다. 이미 어떤 경쟁자가 있는지, 사용자가 실제로 무엇에 어려움을 겪는지, 기술적으로 가능한지, 산업별 제약이 무엇인지 확인합니다. - -**언제 쓰나요.** 낯선 도메인에 들어가거나, 경쟁자가 있을 것 같지만 아직 파악하지 않았거나, 개념을 실현하려면 아직 검증하지 않은 기술 역량이 필요할 때 사용합니다. 각 리서치 유형은 독립적이므로 결정에 필요한 유형만 실행하세요. - -세 가지 모드와 선택 방법, 리서치 실행의 내부 작동 방식은 [Deep Recon](./deep-recon.md)을 참고하세요. - -### 제품 개요 - -**무엇인가요.** 단계별 질문을 거쳐 제품 개념을 1-2페이지로 요약하는 과정입니다. AI는 협업형 비즈니스 분석가로서 비전, 대상 고객, 가치 제안, 범위를 명확히 표현하도록 돕습니다. - -**왜 있나요.** 제품 개요는 비교적 부담 없이 계획 단계로 넘어가는 경로입니다. 전략적 비전을 구조화된 형식으로 정리하며, 그 결과는 PRD 작성의 입력으로 바로 사용됩니다. 고객과 문제, 대략 무엇을 만들지 알고 있어 개념에 어느 정도 확신이 있을 때 가장 잘 맞습니다. 제품 개요는 이 생각을 더 명확하게 다듬습니다. - -**언제 쓰나요.** 개념이 비교적 명확하고 PRD를 만들기 전에 효율적으로 문서화하고 싶을 때 사용합니다. 방향에 확신이 있고 가정을 엄격하게 검증받을 필요가 없을 때 적합합니다. - -### PRFAQ(워킹 백워드) - -**무엇인가요.** Amazon의 워킹 백워드 방법론을 대화형 검증 과정으로 바꾼 도구입니다. 코드를 한 줄도 작성하기 전에 완성된 제품을 발표하는 보도자료를 쓰고, 고객과 이해관계자가 물을 가장 어려운 질문에 답합니다. AI는 집요하지만 건설적인 제품 코치로 행동합니다. - -**왜 있나요.** PRFAQ는 엄격한 검증을 거쳐 계획 단계로 들어가는 경로입니다. 모든 주장을 방어하게 하여 고객 우선 관점에서 생각을 명확히 합니다. 설득력 있는 보도자료를 쓸 수 없다면 아직 제품을 만들 준비가 되지 않았다는 뜻입니다. 고객 FAQ 답변에서 드러난 빈틈은 이 과정을 거치지 않았다면 구현 단계에서야 훨씬 큰 비용을 치르고 발견했을 문제입니다. 이 관문은 수정 비용이 가장 적은 초기에 생각의 허점을 드러냅니다. - -**언제 쓰나요.** 리소스를 투입하기 전에 개념을 스트레스 테스트하고 싶을 때 사용합니다. 사용자가 실제로 관심을 가질지 확신이 없거나, 명확하고 방어 가능한 가치 제안을 말할 수 있는지 검증하고 싶을 때, 또는 워킹 백워드 방식으로 생각을 더 엄격하게 다듬고 싶을 때 적합합니다. - -## 무엇을 사용해야 하나요? - -| 상황 | 권장 도구 | -| --- | --- | -| "막연한 아이디어가 있는데 어디서 시작할지 모르겠어요" | 브레인스토밍 | -| "결정하기 전에 시장을 이해해야 해요" | 리서치 | -| "만들고 싶은 건 알아요. 문서화만 필요해요" | 제품 개요 | -| "이 아이디어가 정말 만들 가치가 있는지 확인하고 싶어요" | PRFAQ | -| "탐색하고, 검증하고, 문서화하고 싶어요" | 브레인스토밍 → 리서치 → PRFAQ 또는 제품 개요 | - -제품 개요와 PRFAQ는 둘 다 PRD 입력을 만듭니다. 얼마나 엄격한 검증을 원하는지에 따라 고르세요. 제품 개요는 함께 아이디어를 구체화하는 과정이고, PRFAQ는 더 엄격한 검증 관문입니다. 둘 다 같은 목적지로 이어지지만, PRFAQ는 그 개념이 계획 단계로 넘어갈 준비가 되었는지 시험합니다. - -:::tip[확실하지 않나요?] -`bmad-help`를 실행하고 상황을 설명하세요. 이미 한 일과 달성하려는 것에 따라 적절한 시작점을 추천합니다. -::: - -## 분석 후에는 무엇이 일어나나요? - -분석 산출물은 단계 2(계획)로 직접 이어집니다. PRD 워크플로는 제품 개요, PRFAQ 문서, 리서치 발견 사항, 브레인스토밍 보고서를 입력으로 받아 지금까지 만든 자료를 구조화된 요구사항으로 종합합니다. 분석을 더 충실히 할수록 PRD도 더 명확하고 구체적으로 다듬어집니다. diff --git a/docs/ko-kr/explanation/brainstorming.md b/docs/ko-kr/explanation/brainstorming.md deleted file mode 100644 index e28e2ec838..0000000000 --- a/docs/ko-kr/explanation/brainstorming.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -title: "브레인스토밍" -description: 60가지 이상의 검증된 아이디어 도출 기법을 활용한 참여형 창의 세션 -sidebar: - order: 3 ---- - -안내에 따라 직접 탐색하며 창의력을 마음껏 펼쳐 보세요. - -## 브레인스토밍이란? - -`bmad-brainstorming`을 실행하면 아이디어를 대신 내놓는 AI가 아니라, 스스로 아이디어를 끌어내도록 돕는 창의적 진행자를 만나게 됩니다. AI는 코치이자 안내자 역할을 하며 검증된 기법으로 좋은 생각이 떠오를 환경을 만듭니다. - -**잘 맞는 경우:** - -- 창의적 막힘 돌파 -- 제품 또는 기능 아이디어 생성 -- 새로운 각도에서 문제 탐색 -- 초기 아이디어를 실행 계획으로 발전 - -## 작동 방식 - -1. **준비** - 주제, 목표, 제약 정의 -2. **접근 방식 선택** - 직접 기법을 고르거나, AI 추천을 받거나, 무작위로 진행하거나, 점진적 흐름을 따릅니다 -3. **진행** - 탐색 질문과 협업형 코칭으로 기법을 적용합니다 -4. **정리** - 아이디어를 주제로 묶고 우선순위를 정합니다 -5. **실행** - 핵심 아이디어에 다음 단계와 성공 지표를 연결합니다 - -모든 내용은 나중에 참고하거나 이해관계자와 공유할 수 있는 세션 문서에 기록됩니다. - -:::note[직접 떠올린 아이디어] -모든 아이디어는 사용자가 직접 떠올립니다. 워크플로는 통찰이 생길 환경을 마련할 뿐, 아이디어를 대신 내놓지 않습니다. -::: diff --git a/docs/ko-kr/explanation/deep-recon.md b/docs/ko-kr/explanation/deep-recon.md deleted file mode 100644 index 6dfb83de76..0000000000 --- a/docs/ko-kr/explanation/deep-recon.md +++ /dev/null @@ -1,125 +0,0 @@ ---- -title: "Deep Recon" -description: 의사결정에 필요한 리서치를 세 가지 방식으로 수행합니다. 자체 심층 리서치 도구용 프롬프트 작성, 완성된 보고서 처리, 현재 세션에서 직접 실행을 지원합니다. -sidebar: - order: 12 ---- - -Deep Recon은 의사결정에 필요한 어떤 주제든 조사합니다. 이 문서에서는 세 가지 모드와 선택 기준, 리서치를 직접 실행할 때 내부에서 일어나는 일을 설명합니다. - -## Deep Recon이란? - -`bmad-deep-recon`을 실행하면 단순한 검색 엔진이 아니라 의사결정에 맞춰 조사 방향을 잡는 리서치 책임자를 만납니다. 모든 작업은 의사결정에서 시작합니다. 시장에 진입할지, 어떤 기술 스택이나 공급업체를 선택할지, 특정 도메인에 집중할지, 논문의 근거를 어떻게 세울지 정합니다. 이 결정에 따라 물어볼 질문, 신뢰할 출처, 최종 보고서의 권고 사항이 달라집니다. - -핵심 스킬이라 소프트웨어 프로젝트에만 한정되지 않습니다. 제품 팀은 시장 규모를 조사할 때 쓸 수 있습니다. 논문의 문헌 검토, 경쟁사 세 곳 분석, "어떤 건강보험 상품을 골라야 할까" 같은 질문도 같은 방식으로 다룹니다. 모델의 기억이 아니라 증거에 근거해야 하는 답이라면 모두 범위에 포함됩니다. - -출력 형식은 언제나 같습니다. 인용을 포함한 보고서(`research.md`)와 후속 스킬이 직접 읽을 수 있는 메타데이터입니다. PRD나 제품 개요는 리서치 원본을 다시 처리할 필요 없이 요약을 그대로 사용할 수 있습니다. - -## 리서치 유형 - -유형을 선택하면 해당 팩이 적용됩니다. 팩은 우선순위를 매긴 조사 영역, 출처를 다루는 방식, 최신성 규칙을 담은 짧은 카드로, 즉석에서 작성한 일반 프롬프트보다 조사 품질을 높입니다. Deep Recon이 요청에서 유형을 추론하도록 두거나 직접 지정할 수 있습니다. - -| 유형 | 사용할 때 | -| --- | --- | -| `market` | 기회 규모, 시장 세분화, 가격, 시장 진출 전략을 조사할 때 | -| `domain` | 산업이나 분야의 구조, 참여자, 규칙, 용어를 익힐 때 | -| `technical` | 기술 영역, 통합 방식, 실제 구현 가능성을 평가할 때 | -| `competitive` | 특정 경쟁사의 제품, 가격, 변화 방향, 사용자 반응을 분석할 때 | -| `user-voice` | 리뷰와 커뮤니티에서 사용자가 실제로 겪고 원하는 것을 파악할 때 | -| `academic-lit` | 문헌 검토, 최신 연구 동향, 논문을 근거로 한 접근법이 필요할 때 | - -의사결정 형태는 유형과 별도로 선택합니다. 기본값인 `explore`는 이해의 폭을 넓힙니다. `select`는 후보를 체계적으로 비교해 하나를 고릅니다. 모든 유형은 선택 매트릭스로 마무리할 수 있습니다. [bmad-customize](../how-to/customize-bmad.md)를 사용하면 자체 유형도 추가할 수 있습니다. - -## 세 가지 모드 - -| 모드 | 수행하는 작업 | 사용자가 제공할 것 | -| --- | --- | --- | -| **Draft** | Deep Recon이 팩의 조사 기법을 담은 리서치 프롬프트를 작성하면 사용자가 자체 도구에서 실행합니다. | ChatGPT, Gemini, Grok 또는 Perplexity에 한 번 붙여 넣기 | -| **Process** | 완성된 보고서를 보관한 뒤 주장을 추출해 팩과 대조하고 표준 요약으로 정리합니다. | 어떤 출처에서 만들었든 완성된 보고서 | -| **Run** | Deep Recon이 현재 세션에서 병렬 웹 탐색, 검증, 인용 합성을 수행합니다. | 계획 게이트에서 한 번 승인 | - -**Draft**가 있는 이유는 전용 심층 리서치 제품이 자료 수집에 뛰어나며 많은 사용자가 이미 이런 서비스에 비용을 내고 있기 때문입니다. 작성된 프롬프트에는 선택한 유형의 조사 영역, 최신성 요구 사항, 엄격한 인용 요구를 담습니다. 사용자가 지정한 도구에 맞게 조정하며 비용이 많이 드는 크롤링은 이미 구독 중인 서비스가 담당합니다. - -**Process**는 리서치 흐름을 마무리합니다. 어떤 도구로 만들었든 완성된 보고서만 지정하면 됩니다. 사용 중인 도구에서 방금 만든 보고서, 분석가의 PDF, 동료의 문서 모두 가능합니다. 원본은 실행 폴더에 손대지 않은 상태로 보존합니다. 의사결정에 영향을 주는 모든 주장을 추출하고 자료가 다루지 않은 조사 영역을 표시한 뒤 Run에서 만드는 것과 같은 형식으로 요약합니다. Draft와 Process는 자연스럽게 이어집니다. 프롬프트를 작성해 앱에서 실행한 다음 보고서를 다시 가져오면 됩니다. - -**Run**만으로도 전체 기능을 쓸 수 있으며 모든 작업이 현재 세션 안에서 진행됩니다. 별도 도구를 오갈 필요가 없습니다. 프로젝트 맥락을 반영해 문제를 정의하고 프리셋으로 투입 수준을 조절합니다. - -## 어떤 모드를 사용해야 하나요? - -| 상황 | 사용할 모드 | -| --- | --- | -| 심층 리서치 도구를 구독 중이며 수동으로 한 번 오가는 것이 괜찮을 때 | Draft 후 Process | -| 어떤 방식으로든 이미 만든 보고서가 있을 때 | Process | -| 앱을 전환하지 않고 한 번에 결과를 얻고 싶을 때 | Run | -| 현재 세션에서만 접근할 수 있는 내부 자료나 MCP 도구가 필요할 때 | Run | -| 먼저 공개 자료를 넓게 훑고 나서 특정 부분을 집중 조사할 때 | Draft + Process 후, 빠진 부분에 초점을 맞춘 Run | - -모드마다 장단점이 있습니다. Draft는 수동으로 한 차례 도구를 오가야 하지만 이미 결제한 구독 서비스를 활용합니다. 호스팅형 심층 리서치 제품은 같은 비용이라면 현재 세션에서 Run을 실행할 때보다 더 넓게 크롤링합니다. Run은 토큰과 시간이 들지만 맥락을 벗어나지 않으며 실행 환경에 있는 모든 도구를 쓸 수 있습니다. 작업 방식을 지정하지 않고 리서치를 요청하면 Deep Recon이 이 차이를 한 번 설명한 뒤 해당 세션 동안 사용자의 선택을 기억합니다. - -## Run의 진행 방식 - -Run은 단계별로 계획하고 작업을 나누며 진행 중에 검증합니다. - -```mermaid -flowchart TD - A[계획 게이트: 의사결정, 조사 영역,
작업 분산 구조, 투입 수준, 예상 시간] -->|사용자 승인| B{작업 분산 구조} - B -->|너비 우선| C[보조 에이전트가 독립된
하위 질문을 나눠 맡음] - B -->|깊이 우선| D[보조 에이전트가 한 질문을
서로 다른 관점에서 조사] - B -->|단순 조회| E[보조 에이전트 하나,
적은 예산] - C --> F[보조 에이전트가 돌아올 때마다
요약을 디스크에 기록] - D --> F - E --> F - F --> G[자료가 들어오는 대로
핵심 주장을 검증] - G --> H[조사 영역별 섹션 작성,
보고서가 진행 중에 확장] - H --> I{추가 단서와
예산이 남았는가?} - I -->|예, 단서를 계속 추적| F - I -->|조사 완료 또는 예산 소진| J[다음 조사 영역] - J --> K[종합: 영역 간 통찰,
권고 사항, 최신성 맵] - K --> L[자동 인용 검사 후
보고서와 선택적 HTML 브리핑 생성] -``` - -계획 게이트는 실행을 멈추는 유일한 필수 지점입니다. 여기에는 의사결정, 결정에 맞게 추린 조사 영역, 선택한 작업 분산 구조(topology), 적용 중인 설정, 현실적인 예상 시간이 표시됩니다. 승인하면 잦은 질문 대신 가벼운 체크포인트만 거치며 실행이 계속됩니다. - -작업 분산 구조는 조사 작업을 어떻게 나눌지 정합니다. 독립적인 하위 질문은 보조 에이전트가 병렬로 맡습니다. 하나의 깊은 질문은 여러 관점에서 같은 자료를 살핍니다. 간단한 조회라면 한 에이전트가 몇 번만 호출합니다. 쉬운 질문에 에이전트 열 개를 쓰면 토큰만 낭비하기 때문입니다. - -투입 수준은 프리셋으로 묶여 있습니다. 요청에 직접 지정한 내용이 있으면 프리셋보다 우선합니다. - -| 프리셋 | 보조 에이전트 | 라운드당 출처 | 라운드 | -| --- | --- | --- | --- | -| `quick` | 2 | 5 | 1 | -| `standard` (기본값) | 3 | 8 | 2 | -| `deep` | 6 | 12 | 3 | - -각 라운드는 단서를 따라갑니다. 첫 번째 라운드에서 발견한 출처 간 모순과 예상 밖의 연결점이 두 번째 라운드의 과제가 됩니다. 질문에 답했거나 한 라운드 전체에서 새로운 내용이 나오지 않은 조사 영역은 일찍 종료합니다. - -## 보고서를 신뢰할 수 있는 이유 - -두 가지 규칙이 모든 작업에 적용됩니다. 첫째, 학습 데이터만으로 결론을 내리지 않습니다. 모델의 기억은 질문과 검색 전략을 제안하는 데만 씁니다. 보고서의 모든 주장은 이번 작업에서 가져오거나 불러온 출처로 이어집니다. 둘째, 리서치 방화벽을 사용합니다. 프로젝트 파일과 개요는 무엇을 물을지 정하는 데만 쓰며 무엇을 찾을지 미리 결정하지 않습니다. 보조 에이전트는 자신이 맡은 과제만 받습니다. 이 방식은 프로젝트의 기존 가정에 맞춰 결과가 무심코 편향되는 것을 막습니다. - -모든 주장에는 발행자, 발행일, 접근일이 있으며 본문의 `[n]` 인용은 출처 부록으로 연결됩니다. 자료가 도착하면 사용자가 선택한 수준에 맞춰 바로 검증합니다. `normal`은 권고 사항의 근거가 되는 주장을 표본 검사합니다. `high`는 팩에서 중요하게 지정한 주장 유형을 교차 검증하고 주요 결론을 반대 관점에서 점검합니다. `max`는 모든 내용을 확인합니다. 최신성도 사실의 일부입니다. 각 팩은 주장 유형별 유효 기간을 정하며 3년 전 시장 규모는 현재 사실이 아니라 과거 기록으로 보고합니다. - -:::note[모든 내용은 디스크에 기록됩니다] -요약, 추출 결과, 보고서 섹션은 만들어지는 즉시 실행 폴더에 기록됩니다. 실행 중 문제가 생겨도 디스크에서 이어갈 수 있어 아무것도 잃지 않습니다. 보고서도 진행 표시 뒤에 숨지 않고 눈앞에서 완성됩니다. -::: - -## 실행 폴더와 Refresh - -각 작업은 계획 산출물 아래에 폴더 하나를 만듭니다. 가져온 원본은 손대지 않은 채 보관합니다. 추출한 요약, 작성한 리서치 요청서가 있다면 그 파일, `research.md`를 함께 저장합니다. 보고서 끝에는 가장 빨리 낡는 주장과 다시 확인할 시점을 표시한 최신성 맵이 있습니다. - -이 맵을 기준으로 리서치의 갱신 주기를 관리합니다. **Refresh**는 오래된 주장만 다시 검증하고 변화 보고서(확인됨, 변경됨, 뒤집힘)를 덧붙입니다. 뒤집힌 주장이 후속 산출물에 영향을 주면 경고합니다. **Deepen**은 나머지를 다시 실행하지 않고 조사 영역 하나만 더 깊이 파고듭니다. 리서치는 일회성 결과에 머물지 않고 계속 갱신됩니다. - -## 시작하기 - -| 목표 | 입력할 내용 | -| --- | --- | -| 주제 조사 | `/bmad-deep-recon`을 실행한 뒤 의사결정을 설명하거나, 바로 "자체 호스팅 분석 시장을 조사해 줘"라고 입력 | -| 유형 강제 지정 | "Linear와 Height를 경쟁 관점에서 조사해 줘" | -| 자체 도구용 프롬프트 작성 | "Gemini에서 쓸 X에 대한 심층 리서치 프롬프트를 작성해 줘" | -| 보고서 처리 | "리서치 보고서가 ~/Downloads/report.pdf에 있어. 처리해 줘" | -| 선택지 비교 | "이 프로젝트에 Postgres와 MySQL 중 무엇이 맞는지 선택을 도와줘" | -| 기존 보고서 새로 고침 | "시장 리서치를 새로 고쳐 줘" | -| 기본값 커스터마이징 | `/bmad-customize bmad-deep-recon` | - -## 이전 리서치 스킬은 어떻게 됐나요? - -v6의 `bmad-market-research`, `bmad-domain-research`, `bmad-technical-research` 스킬은 각각 `market`, `domain`, `technical` 유형으로 Deep Recon에 통합됐습니다. 이전 이름도 계속 작동하며 새 스킬로 연결되므로, 기존 사용 습관과 메뉴 항목을 그대로 유지할 수 있습니다. diff --git a/docs/ko-kr/explanation/established-projects-faq.md b/docs/ko-kr/explanation/established-projects-faq.md deleted file mode 100644 index ae3b93a0a9..0000000000 --- a/docs/ko-kr/explanation/established-projects-faq.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -title: "기존 프로젝트 FAQ" -description: 기존 프로젝트에서 BMad Method를 사용할 때의 일반 질문 -sidebar: - order: 10 ---- - -BMad Method(BMM)로 기존 프로젝트에서 작업할 때 자주 묻는 질문에 빠르게 답합니다. - -## 질문 - -- [프로젝트 문서화를 먼저 실행해야 하나요?](#프로젝트-문서화를-먼저-실행해야-하나요) -- [프로젝트 문서화 실행을 잊었다면 어떻게 하나요?](#프로젝트-문서화-실행을-잊었다면-어떻게-하나요) -- [기존 프로젝트에서는 구현을 어떻게 하나요?](#기존-프로젝트에서는-구현을-어떻게-하나요) -- [기존 코드가 모범 사례를 따르지 않으면 어떻게 하나요?](#기존-코드가-모범-사례를-따르지-않으면-어떻게-하나요) - -### 프로젝트 문서화를 먼저 실행해야 하나요? - -`bmad-document-project`는 더 이상 사용하지 않습니다. 이를 대체하는 [`bmad-project-context`](project-context.md)는 별도의 문서를 생성하지 않고 저장소의 `AGENTS.md`에 작고 검증된 블록을 작성합니다. 특히 다음 상황에서는 먼저 실행하는 것이 좋습니다. - -- 기존 문서가 없습니다 -- 문서가 오래되었습니다 -- AI 에이전트가 기존 코드에 대한 컨텍스트가 필요합니다 - -저장소에 이미 잘 관리되는 에이전트 지침이 있거나, 다른 도구나 기법으로 에이전트가 기존 시스템을 파악하게 할 예정이라면 건너뛸 수 있습니다. - -### 프로젝트 문서화 실행을 잊었다면 어떻게 하나요? - -걱정하지 마세요. 언제든 `bmad-project-context`를 실행할 수 있습니다. Refresh와 Audit을 실행하면 프로젝트 도중이나 이후에도 컨텍스트를 정확하게 유지합니다. 이미 생성한 문서도 검증할 소스로 활용합니다. - -### 기존 프로젝트에서는 구현을 어떻게 하나요? - -새 프로젝트와 마찬가지로 `bmad-build`를 실행하세요. Build는 다음을 수행합니다. - -- 기존 기술 스택 자동 감지 -- 기존 코드 패턴 분석 -- 관례 감지 및 확인 요청 -- 기존 코드를 존중하는, 맥락이 충분히 담긴 사양 생성 - -범위가 명확한 변경은 바로 시작할 수 있습니다. 작업 규모가 크다면 계획된 스토리와 상위 산출물을 함께 제공하세요. - -### 기존 코드가 모범 사례를 따르지 않으면 어떻게 하나요? - -Build는 관례를 감지한 뒤 "이 기존 관례를 따를까요?"라고 묻고, 사용자가 결정하게 합니다. - -- **예** → 현재 코드베이스와의 일관성 유지 -- **아니요** → 새 표준 수립(사양에 이유를 문서화) - -BMM은 선택을 존중합니다. 현대화를 강제하지 않지만 필요한 제안은 합니다. - -**여기에 답이 없는 질문이 있나요?** [GitHub Issue](https://github.com/bmad-code-org/BMAD-METHOD/issues)를 열거나 [Discord](https://discord.gg/gk8jAdXWmj)에서 물어보세요. 추가하겠습니다. diff --git a/docs/ko-kr/explanation/forge-idea.md b/docs/ko-kr/explanation/forge-idea.md deleted file mode 100644 index 104336d1f3..0000000000 --- a/docs/ko-kr/explanation/forge-idea.md +++ /dev/null @@ -1,78 +0,0 @@ ---- -title: "아이디어 단련" -description: 페르소나 기반 질문으로 아이디어를 압박 검증해 단단하게 만들거나, 입증하거나, 적은 비용으로 폐기합니다 -sidebar: - order: 11 ---- - -생각을 바꿔도 비용이 거의 들지 않는 지금, 아직 다듬어지지 않은 아이디어를 대화로 압박 검증하세요. - -## 아이디어 단련이란? - -`bmad-forge-idea`를 실행하면 엄격한 질문자가 아이디어를 한 번에 하나의 질문으로 파고듭니다. 검증을 견딘 아이디어에 실제로 행동할 만큼 확신이 생길 때까지 질문을 이어갑니다. 이 스킬은 도메인을 가리지 않습니다. 소프트웨어 기능, 비즈니스 모델, 연구 가설, 계속 머릿속을 맴도는 개인적 결정에도 사용할 수 있습니다. - -세션을 마치면 생각이 더 명확해집니다. 정제된 `forged-idea.md`는 가능한 종료 형태 중 하나일 뿐이며, 세션은 사용자에게 "이제 만들까요?"라고 재촉하지 않습니다. - -아이디어 단련(Forge Idea)은 핵심 모듈의 사고 스킬이므로 모든 BMad 설치에서 사용할 수 있습니다. - -## 왜 일찍 압박 검증해야 하나요? - -가장 위험한 것은 자기 아이디어 안에서 보지 못한 허점입니다. 검토되지 않은 가정이나 결론 내리지 못한 선택지는 균열로 남습니다. 지금 놓치면 나중에 빌드나 출시 단계에서 훨씬 더 큰 비용으로 다시 나타납니다. - -이런 문제는 대화 단계에서 발견해야 가장 적은 비용으로 고칠 수 있습니다. 여기서는 생각을 바꿔도 비용이 들지 않습니다. 단련 과정은 이 점을 활용해 아직 부담 없이 고칠 수 있는 약점을 파고듭니다. - -## 세션 진행 방식 - -질문자는 의존성 순서에 따라 한 번에 하나의 질문을 던지고, 매번 자신의 권장 답도 함께 내놓습니다. 열린 질문보다 반박할 기준이 있는 답이 논의를 더 깊게 이끕니다. 직접 찾을 수 있는 답은 사용자에게 찾아오라고 하지 않고 스스로 확인합니다. - -아이디어가 기존 프로젝트 안에 있다면 그 프로젝트 자료가 판단 기준이 됩니다. 질문자는 사용자의 주장을 이미 있는 자료와 대조하고 모순을 짚습니다. 용어도 같은 검토를 받습니다. 어떤 용어가 모호하거나 두 의미를 동시에 담고 있다면, 논점을 정리하기 전에 정확한 의미를 선택하게 합니다. 한 단어에 여러 의미가 겹친 채 논의를 이어가면 잘못된 결론에 이를 수 있기 때문입니다. - -## 대화 구성 - -단련 과정에는 뚜렷한 목소리를 가진 인물들이 참여합니다. 주제가 정해지면 논점마다 얼굴 없는 어시스턴트 하나가 아니라 두 인물이 함께 나섭니다. 한 명은 설치된 명단에서 고릅니다. [파티 모드](./party-mode.md)와 [이름 있는 에이전트](./named-agents.md)에 등장하는, 사용자가 알아볼 에이전트나 페르소나입니다. 다른 한 명은 주제에 맞춰 즉석에서 만든 인물입니다. 적대적인 경쟁자, 회의적인 CFO, 바로 이런 계획이 실패하는 것을 여러 번 본 도메인 전문가일 수 있습니다. - -사용자는 언제든 대화를 조종할 수 있습니다. 특정 인물을 지명하거나, 저장된 파티를 부르거나, **"이 주장을 반대 관점에서 검토해 줘"**라고 요청해 한 주장을 끝까지 공격하게 하고 사용자가 방어할 수 있습니다. - -## 기본 동의는 없습니다 - -이 스킬은 무조건 동의하는 반응을 거부합니다. 아이디어를 이해했다는 말은 그 아이디어를 지지한다는 뜻이 아닙니다. 단련 과정은 어떤 것도 검증을 통과하기 전에는 칭찬하지 않습니다. 약점을 공격하거나 강점을 더 밀어붙이고, 검증을 통해 확인된 강점만 인정합니다. - -적대적 리뷰와는 의도적으로 반대되는 방식입니다. 적대적 리뷰에서는 리뷰어가 문제를 찾고 사용자는 거짓 양성을 걸러냅니다. 여기서는 질문자가 근거 없이 동의하지 않습니다. 긴장감을 유지해 사용자가 더 깊이 생각하게 합니다. 편안한 대화보다 더 나은 아이디어를 남기는 데 초점을 둡니다. - -## 세션 종료 방식 - -세션은 생각이 도달한 지점에서 끝나며, 어떤 결말이든 유효한 결과로 봅니다. 단련 과정은 판정을 명시한 독립 보고서를 작성합니다. - -| 결과 | 의미 | -| --- | --- | -| **단련됨** | 아이디어가 살아남았습니다. 확정한 결정, 폐기한 선택과 그 이유를 `forged-idea.md`로 정제합니다. 제품 개념이라면 `bmad-spec`, `bmad-prd`, `bmad-prfaq`의 입력으로 사용할 수 있습니다. | -| **폐기됨** | 아이디어가 살아남지 못했습니다. 보고서는 폐기 이유를 기록합니다. 그것을 적은 비용으로 알아낸 것 자체가 이득입니다. | -| **명확해짐** | 이제 더 명확하게 생각할 수 있습니다. 별도 산출물이 필요하지 않으며, 세션 자체로 충분합니다. | - -## 사용 시점 - -이미 아이디어가 있고, 그 아이디어에 투자하기 전에 단단하게 만들거나 폐기하고 싶을 때 사용하세요. 아직 선택지를 생성하는 중이거나 에이전트들의 집단 결정을 원한다면 건너뛰세요. - -| 스킬 | 사용 시점 | 목소리 | -| --- | --- | --- | -| `bmad-forge-idea` | 아이디어가 있고 스트레스 테스트하거나 폐기하고 싶을 때 | 질문자와 두 인물이 참여하는 대화 | -| `bmad-prfaq` | 제품을 추진하기로 정했고 고객 우선 관점에서 입증하고 싶을 때 | Working Backwards 코치 | -| `bmad-brainstorming` | 아직 아이디어가 없고 선택지를 생성해야 할 때 | 퍼실리테이션 코치 | -| `bmad-party-mode` | 에이전트들이 함께 토론하거나 결정하길 원할 때 | 한 대화 안의 전체 명단 | -| `bmad-review` | 산출물이 있고 결함을 찾아야 할 때 | 실제 이슈를 찾는 다중 렌즈 리뷰어 | - -## 예시 - -:::note[예시] -**사용자:** "앱에 AI 생성 주간 요약을 넣고 싶어요. 사용자에게 매주 월요일 요약 이메일을 보내는 겁니다." - -**Forge:** "기능 전에, 누가 이걸 요청했나요? 제 권장 답은 아무도 요청하지 않았다는 것입니다. 지금은 'AI 요약은 가치 있어 보인다'에서 출발하고 있습니다. 실제 신호가 있다면 반박해 주세요." - -**회의적인 CFO(즉석 생성):** "월요일 요약은 모든 활성 사용자에게 반복적인 추론 비용을 계속 발생시킵니다. 어떤 매출 항목이 그 비용을 지불하나요?" - -**사용자:** "리텐션이요, 아마도요. 사람들이 다시 오는 걸 잊으니까요." - -**Forge:** "그렇다면 핵심 주장은 '월요일 이메일이 이탈 직전 사용자를 되돌린다'이지, 'AI 요약은 가치 있다'가 아닙니다. 둘은 다른 아이디어입니다. 어느 쪽을 단련할까요?" -::: - -첫 아이디어는 기능이었습니다. 두 번의 질문 만에 모델 없이도 일반 이메일로 테스트할 수 있는 리텐션 가설이 실제 핵심이라는 점이 드러납니다. diff --git a/docs/ko-kr/explanation/named-agents.md b/docs/ko-kr/explanation/named-agents.md deleted file mode 100644 index 82291603c8..0000000000 --- a/docs/ko-kr/explanation/named-agents.md +++ /dev/null @@ -1,101 +0,0 @@ ---- -title: "이름 있는 에이전트" -description: BMad 에이전트가 이름, 페르소나, 커스터마이징 영역을 갖는 이유와 메뉴 기반 또는 프롬프트 기반 대안보다 무엇을 가능하게 하는지 -sidebar: - order: 1 ---- - -"Mary, 브레인스토밍하자"라고 말하면 Mary가 활성화됩니다. Mary는 설정에 저장된 사용자 이름을 부르며, 설정한 언어와 고유한 페르소나로 인사합니다. `bmad-help`를 언제든 사용할 수 있다고 알려준 뒤, 의도가 명확하므로 메뉴를 건너뛰고 바로 브레인스토밍을 시작합니다. - -이 페이지에서는 이때 내부에서 무슨 일이 일어나는지, BMad가 왜 이런 방식으로 설계됐는지 설명합니다. - -## 세 축 - -BMad의 에이전트 모델은 서로 조합되는 세 가지 기본 요소 위에 놓여 있습니다. - -| 기본 요소 | 제공하는 것 | 위치 | -| --- | --- | --- | -| **스킬** | 기능 - 어시스턴트가 할 수 있는 구체적인 일(브레인스토밍, PRD 초안 작성, 스토리 구현) | `.claude/skills/{skill-name}/SKILL.md` 또는 IDE별 동등 경로 | -| **이름 있는 에이전트** | 페르소나 일관성 - 일관된 목소리, 원칙, 시각적 단서로 관련 스킬 메뉴를 묶는 쉽게 알아볼 수 있는 정체성 | 디렉터리가 `bmad-agent-*`로 시작하는 스킬 | -| **커스터마이징** | 우리 방식으로 맞추기 - 에이전트 동작을 재구성하고, MCP 통합을 추가하고, 템플릿을 교체하고, 조직 관례를 겹쳐 적용하는 오버라이드 | `_bmad/custom/{skill-name}.toml`(팀 오버라이드) 및 `.user.toml`(개인, git에서 무시됨) | - -세 요소 중 하나라도 빠지면 경험이 무너집니다. - -- 에이전트 없는 스킬 → 사용자가 이름이나 코드로 탐색해야 하는 기능 목록 -- 스킬 없는 에이전트 → 할 일이 없는 페르소나 -- 커스터마이징 없음 → 모든 사용자가 같은 기본 제공 동작을 받고, 조직별 필요에는 포크를 강요받음 - -## 이름 있는 에이전트의 장점 - -BMad는 BMad Method의 단계에 맞춘 다섯 이름 있는 에이전트를 제공합니다. - -| 에이전트 | 단계 | 모듈 | -| --- | --- | --- | -| 📊 **Mary**, 비즈니스 분석가 | 분석 | 시장 조사, 브레인스토밍, 제품 개요, PRFAQ | -| 📋 **John**, 제품 관리자 | 계획 | PRD 작성, 에픽/스토리 분해, 구현 준비 상태 점검 | -| 🎨 **Sally**, UX 디자이너 | 계획 | UX 설계 사양 | -| 🏗️ **Winston**, 시스템 아키텍트 | 솔루션 설계 | 기술 아키텍처, 정합성 점검 | -| 💻 **Amelia**, 시니어 엔지니어 | 구현 | 스토리 실행, Build, 코드 리뷰, 스프린트 계획 | - -:::note[Paige는 어디에 있나요?] -📚 기술 작성자 **Paige**는 잠시 쉬고 있습니다. 앞으로 더 많은 역량을 갖춰 돌아올 예정입니다. 프로젝트 컨텍스트 기능은 그대로 사용할 수 있습니다. `bmad-project-context`를 직접 호출하거나 Mary의 메뉴에서 실행하세요. -::: - -각 에이전트에는 하드코딩된 정체성(이름, 직함, 도메인)과 커스터마이즈 가능한 계층(역할, 원칙, 커뮤니케이션 스타일, 아이콘, 메뉴)이 있습니다. Mary의 원칙을 다시 쓰거나 메뉴 항목을 추가할 수는 있지만 이름을 바꿀 수는 없습니다. 이는 의도적입니다. 이름 인식은 커스터마이징 후에도 유지되므로, 팀이 Mary의 동작을 어떻게 조정했든 "Mary"는 항상 분석가를 활성화합니다. - -## 활성화 흐름 - -이름 있는 에이전트를 호출하면 여덟 단계가 순서대로 실행됩니다. - -1. **에이전트 블록 해석** - 제공된 `customize.toml`을 팀 및 개인 오버라이드와 병합합니다. Python 병합 스크립트가 표준 라이브러리 `tomllib`을 사용합니다 -2. **사전 단계 실행** - 팀이 설정한 사전 동작 -3. **페르소나 채택** - 하드코딩된 정체성과 커스터마이즈된 역할, 커뮤니케이션 스타일, 원칙 -4. **지속 사실 로드** - 조직 규칙, 컴플라이언스 메모, `file:` 접두사로 로드되는 파일(예: `file:{project-root}/docs/project-context.md`) -5. **설정 로드** - 사용자 이름, 커뮤니케이션 언어, 출력 언어, 산출물 경로 -6. **인사** - 설정 언어로 개인화된 인사를 하고, 누가 말하는지 한눈에 보이도록 에이전트 이모지 접두사를 포함합니다 -7. **후속 단계 실행** - 팀이 설정한 인사 후 동작 -8. **바로 실행 또는 메뉴 표시** - 첫 메시지가 메뉴 항목에 매핑되면 바로 실행하고, 아니면 메뉴를 보여주고 입력을 기다립니다 - -8단계는 의도와 기능이 만나는 곳입니다. "Mary, 브레인스토밍하자"는 `bmad-brainstorming`이 Mary 메뉴의 `BP`와 명확히 맞으므로 메뉴 표시를 건너뜁니다. 모호하게 말하면 확인 절차가 아니라 한 번 짧게 묻습니다. 맞는 것이 없으면 일반 대화를 계속합니다. - -## 왜 그냥 메뉴가 아닌가요? - -메뉴 방식에서는 사용자가 도구의 구조를 어느 정도 익혀야 합니다. 브레인스토밍이 PM 에이전트가 아니라 분석가 에이전트의 `BP` 코드 아래 있다는 것을 기억하고, 어떤 페르소나가 어떤 기능을 갖는지 알아야 합니다. 그만큼 도구가 사용자에게 인지 부담을 떠넘깁니다. - -이름 있는 에이전트는 이 흐름을 뒤집습니다. 사용자는 원하는 작업과 담당 에이전트를 자연스러운 말로 지정하면 됩니다. 에이전트는 자신이 누구이고 무엇을 하는지 압니다. 의도가 충분히 명확하면 바로 진행합니다. - -메뉴는 여전히 대체 경로로 있습니다. 탐색할 때는 보여주고, 필요 없을 때는 건너뜁니다. - -## 왜 그냥 빈 프롬프트가 아닌가요? - -빈 프롬프트는 어떤 표현을 써야 통하는지 사용자가 안다고 가정합니다. "브레인스토밍을 도와줘"는 될 수 있지만 "내 SaaS 아이디어를 같이 발전시켜 보자"는 안 될 수 있고, 결과는 요청을 어떻게 표현했는지에 따라 달라집니다. 결국 사용자가 프롬프트를 설계해야 합니다. - -이름 있는 에이전트는 자유를 제한하지 않으면서 구조를 제공합니다. 페르소나는 일관되고, 사용할 수 있는 기능은 쉽게 확인할 수 있으며, `bmad-help`는 명령 하나로 언제든 호출할 수 있습니다. 에이전트가 무엇을 할 수 있는지 추측할 필요도, 사용 설명서가 필요하지도 않습니다. - -## 커스터마이징은 핵심 기능입니다 - -커스터마이징 모델이 있어야 이 방식이 개별 개발자를 넘어 확장됩니다. - -모든 에이전트는 합리적인 기본값이 담긴 `customize.toml`을 제공합니다. 팀은 `_bmad/custom/bmad-agent-{role}.toml`에 오버라이드를 커밋합니다. 개인은 `.user.toml`(git에서 무시됨)에 개인 선호를 겹쳐 적용할 수 있습니다. 병합 스크립트는 활성화 시점에 세 파일을 예측 가능한 구조 규칙으로 병합합니다. - -대부분의 사용자는 이 파일을 직접 작성하지 않습니다. `bmad-customize` 스킬은 대상을 고르고 에이전트와 워크플로 중 알맞은 범위를 선택하도록 안내합니다. 이어서 오버라이드를 작성하고 병합 결과를 검증합니다. 따라서 TOML에 익숙하지 않아도 원하는 변경을 설명할 수 있다면 커스터마이징할 수 있습니다. - -예를 들어 팀은 Amelia에게 라이브러리 문서를 찾을 때 항상 Context7 MCP 도구를 사용하고, 로컬 에픽 목록에 스토리가 없으면 Linear를 대신 확인하라고 지시하는 파일 하나를 커밋할 수 있습니다. 그러면 Amelia가 실행하는 모든 개발 워크플로(build, code-review, qa-generate)가 소스를 수정하거나 워크플로마다 같은 설정을 반복하지 않아도 이 동작을 상속합니다. - -여러 스킬에 공통으로 적용되는 설정을 위한 두 번째 커스터마이징 영역도 있습니다. 중앙 설정 파일은 `_bmad/config.toml`과 `_bmad/config.user.toml`이며, 둘 다 설치 프로그램이 관리하고 각 모듈의 `module.yaml`에서 다시 만듭니다. 오버라이드 파일은 팀이 커밋하는 `_bmad/custom/config.toml`과 git에서 무시되는 개인용 `_bmad/custom/config.user.toml`입니다. - -이 중앙 설정에 **에이전트 명단**이 있습니다. `bmad-party-mode`, `bmad-retrospective`, `bmad-advanced-elicitation`처럼 명단을 사용하는 스킬은 간단한 설명 정보를 읽어 어떤 에이전트를 사용할 수 있고 각 에이전트를 어떻게 표현할지 파악합니다. 팀 오버라이드로 에이전트의 표현 방식을 조직 전체에서 바꾸고, `.user.toml` 오버라이드로 가상 페르소나(Kirk, Spock, 도메인 전문가)를 개인 실험에 추가할 수 있습니다. 이때 스킬 폴더는 건드리지 않습니다. - -스킬별 파일은 Mary가 활성화될 때 *어떻게 행동하는지*를 조정합니다. 중앙 설정은 다른 스킬이 명단에서 Mary를 *어떻게 보는지*를 조정합니다. - -전체 커스터마이징 영역과 적용 예시는 다음을 참고하세요. - -- [BMad 커스터마이징 방법](../how-to/customize-bmad.md) - 커스터마이즈할 수 있는 항목과 병합 방식을 설명하는 참고 문서 -- [조직을 위해 BMad 확장하기](../how-to/expand-bmad-for-your-org.md) - 에이전트 전반 규칙, 워크플로 관례, 외부 게시, 템플릿 교체, 에이전트 명단 커스터마이징을 다루는 다섯 가지 실전 레시피 -- `bmad-customize` 스킬 - 의도를 올바른 위치의 검증된 오버라이드 파일로 바꿔 주는 안내형 작성 도우미 - -## 더 큰 아이디어 - -오늘날 대부분의 AI 어시스턴트는 메뉴나 프롬프트 방식이며, 둘 다 인지 부담을 사용자에게 넘깁니다. 이름 있는 에이전트와 커스터마이즈 가능한 스킬을 사용하면 이미 업무를 아는 팀원과 대화하듯 일할 수 있고, 조직은 포크 없이 그 팀원의 동작을 조정할 수 있습니다. - -다음에 "Mary, 브레인스토밍하자"라고 입력하자마자 Mary가 바로 진행한다면, 그때 거치지 않은 과정을 떠올려 보세요. 슬래시 명령도, 탐색해야 할 메뉴도, Mary가 무엇을 할 수 있는지 어색하게 되짚는 일도 없었습니다. 이런 절차를 거치지 않아도 된다는 점이 설계의 핵심입니다. diff --git a/docs/ko-kr/explanation/party-mode.md b/docs/ko-kr/explanation/party-mode.md deleted file mode 100644 index 5a1fc9252f..0000000000 --- a/docs/ko-kr/explanation/party-mode.md +++ /dev/null @@ -1,167 +0,0 @@ ---- -title: "파티 모드" -description: AI 에이전트를 하나의 대화에 모아 실행하고, 직접 출연진을 만들고, 얼마나 독립적으로 사고할지 선택합니다 -sidebar: - order: 7 ---- - -파티 모드는 AI 에이전트를 한자리에 모아 서로, 그리고 사용자와 대화하게 합니다. 이 문서는 파티가 무엇인지, 파티를 실행하는 네 가지 방식, 설치된 에이전트 대신 직접 페르소나 출연진을 만드는 방법, 그리고 파티가 세션 사이에 사용자를 기억하는 방식을 설명합니다. - -## 파티 모드란? - -`bmad-party-mode`를 실행하면 이미 설치된 BMad 에이전트들이 한 대화에 모입니다. PM, 아키텍트, 개발자, UX 디자이너, 그리고 선택한 모듈이 제공하는 다른 에이전트들이 함께 들어옵니다. 설치된 이 명단이 기본 파티이며 별도 설정 없이 바로 사용할 수 있습니다. 이들은 각자 캐릭터에 맞게 답하고, 동의하거나 반대하며, 서로의 생각을 이어갑니다. 사용자가 대화를 이끕니다. 후속 질문을 하고, 반박하고, 한 관점을 앞으로 끌어내거나, 주제를 바꿀 수 있습니다. 대화는 사용자가 끝낼 때까지 계속됩니다. - -이 방식이 작동하는 이유는 페르소나마다 우선순위가 다르기 때문입니다. 아키텍트는 설계를 지키고, PM은 범위를 지키고, 개발자는 실제로 만들 수 있는지를 지킵니다. 이들을 같은 대화에 넣으면 절충점이 스프린트 3주 차가 아니라 지금 드러납니다. - -**잘 맞는 경우:** - -- 실제 절충이 필요한 결정 -- 브레인스토밍과 "무엇을 놓쳤나?" 점검 -- 사후 분석과 회고 -- 실행 전에 계획을 압박 검증하기 - -파티 모드는 페르소나들이 각자의 의견으로 부딪히기 때문에 빠르고 꽤 재미있는 브레인스토밍 방법이기도 합니다. 다른 워크플로를 진행하는 중에도 파티를 시작할 수 있습니다. 브레인스토밍이나 PRD 작성, 코딩, 영업 전략 구상, 창작물 다듬기를 멈출 필요가 없습니다. 눈앞의 문제에 더 많은 관점이 필요할 때 파티를 불러오세요. - -:::note[예시] -**사용자:** MVP에는 모놀리스가 좋을까요, 마이크로서비스가 좋을까요? - -**아키텍트:** 모놀리스로 시작하세요. 사용자 1,000명 규모에서는 마이크로서비스가 필요 없는 운영 비용을 더합니다. - -**PM:** 동의합니다. 아직 증명하지 못한 확장성보다 출시 속도가 더 중요합니다. - -**개발자:** 모놀리스가 좋습니다. 다만 나중에 서비스 하나를 분리해도 재작성하지 않도록 명확한 모듈 경계를 둡시다. -::: - -## 파티 시작하기 - -스킬을 호출하고 원하는 것을 말하세요. 스킬이 사용자가 파티를 실행하려는지, 새로 만들려는지 판단합니다. - -| 목표 | 입력 | -| --- | --- | -| 기본 모드로 파티 시작 | `/bmad-party-mode` | -| 특정 모드로 시작 | `/bmad-party-mode --mode auto` (`session`, `subagent`, `agent-team`도 가능) | -| 비대화형으로 한 번 실행 | `/bmad-party-mode --non-interactive "이 PR을 검토해 줘"` | -| 저장된 파티 열기 | `/bmad-party-mode --party code-review-crew` | -| 즉석에서 출연진 만들기 | "엔터프라이즈호 브리지 크루로 파티 모드" | -| 파티 생성 또는 추가 | "파티 모드, 새 파티 만들어줘" | -| 기존 파티 편집 | "파티 모드, writers' room 편집해줘" | -| 스킬 커스터마이즈 | `/bmad-customize bmad-party-mode` | - -## 파티 실행 방식 - -파티 실행 방식은 네 가지입니다. 세션당 하나의 모드가 활성화되며, 그 모드는 누가 사고하는지를 결정합니다. 하나의 모델이 모두의 목소리를 내는지, 별도 에이전트들이 각자 추론하는지가 달라집니다. - -| 모드 | 하는 일 | 사용 시점 | -| --- | --- | --- | -| `session` | 기본값입니다. 하나의 모델이 모든 페르소나를 인라인으로 연기합니다. 빠르고 대화가 자연스럽습니다. | 대부분의 대화. 가벼운 대화, 브레인스토밍, 빠른 의견 교환. | -| `auto` | 가벼운 라운드는 인라인으로 진행하고, 독립성이 답을 바꾸는 경우에만 독립 에이전트를 생성합니다. | 대부분은 속도를 원하지만 어려운 라운드에서는 실제 독립성이 필요할 때. | -| `subagent` | 의미 있는 라운드마다 페르소나별 별도 에이전트를 생성해 하나의 관점으로 쏠리지 않게 합니다. | 정직한 리뷰와 포커스 그룹처럼 목소리가 섞이면 안 될 때. | -| `agent-team` | 페르소나를 지속 팀으로 세워 서로 직접 대화하게 합니다. Claude Code 전용입니다. | 에이전트들이 서로 말하는 실시간 원탁 토론을 손 놓고 지켜보고 싶을 때. | - -이 선택은 중요합니다. 하나의 모델이 다섯 페르소나를 연기하면 조용히 한쪽으로 모이기 쉽습니다. 결국 같은 마음을 공유하기 때문입니다. 실제 에이전트를 생성하면 추론이 분리되고, 리뷰 패널이나 포커스 그룹에서 중요한 독립성을 지킬 수 있습니다. `session`은 비용이 가장 적고 흐름이 유연합니다. 생성 모드는 비용이 더 들지만 독립성을 보호하고, `auto`는 필요한 라운드에만 생성해 둘 사이를 노립니다. - -`session`이 기본값입니다. 다른 모드를 실행할 수 없는 환경에서는 순서대로 되돌아갑니다. `agent-team`은 `subagent`로, 다시 `session`으로 내려갑니다. 설정된 기본값은 커스터마이징에 저장되고, 실행 시점의 override가 해당 세션에서 우선합니다. - -:::tip[한 세션에서만 모드 바꾸기] -`--mode subagent` 또는 `auto`, `agent-team`, `session`으로 파티를 시작하면 설정된 기본값을 그 실행에서만 바꿀 수 있습니다. -::: - -파티는 기본적으로 대화형입니다. 처음 요청은 대화를 시작하는 주제일 뿐 종료 조건이 아니며, 사용자가 끝낼 때까지 여러 라운드가 이어집니다. 첫 질문에 답했다고 파티가 저절로 끝나지는 않습니다. 요청 하나만 처리하고 멈추게 하려면 `--non-interactive`로 시작하세요. 자연스럽게 마무리할 지점까지 실행한 뒤 내용을 정리하고, 생성한 하위 에이전트도 종료합니다. - -## 커스텀 파티 - -기본적으로 파티는 설치된 BMad 에이전트를 사용합니다. 더 폭넓게 활용하려면 원하는 페르소나를 직접 출연진으로 구성하고, 저장해 재사용하면 됩니다. 파티를 만드는 데도 같은 스킬을 사용합니다. 스킬은 사용자가 파티를 실행하려는지 만들려는지 감지하고, 결과를 [bmad-customize](../how-to/customize-bmad.md)로 오버라이드 파일에 저장합니다. - -파티 모드도 다른 BMad 스킬처럼 커스터마이즈됩니다. `/bmad-customize bmad-party-mode`를 실행해 기본값을 직접 설정하세요. 만든 그룹을 기본 파티로 고정해 플래그 없이 로드되게 하거나, 시작 모드를 고르거나, 파티 전체가 세션 내내 지킬 규칙을 설정할 수 있습니다. - -핵심 개념은 두 가지입니다. - -**페르소나**는 멤버를 뚜렷이 구분하는 요소입니다. 말하는 방식, 중요하게 여기는 것, 논쟁 방식, 특히 싫어하는 것, 놓치기 쉬운 지점이 여기에 들어갑니다. "회의적인 CFO"는 임시 표현입니다. "18개월 안에 회수 계획이 없으면 승인하지 않고, 그 말을 첫 30초 안에 꺼내는 사람"은 페르소나입니다. 이 정도로 구체적이어야 이름표를 가려도 누구인지 알아볼 수 있습니다. - -**장면**은 토론 상황을 정합니다. 배경과 벌어지는 일, 누가 누구에게 적대적인지, 누가 가장 강하게 밀어붙이는지를 자유 형식 한 줄로 적습니다. 같은 멤버도 장면마다 다르게 움직입니다. 멤버는 한 번만 정의해 두고 임무 중인 브리지 크루, 근무 후 라운지에 모인 같은 크루, 적대적인 구매자 패널처럼 서로 다른 상황에 배치할 수 있습니다. 멤버들은 이름 있는 그룹으로 묶이며, 그룹 하나를 기본 파티로 고정할 수 있습니다. - -### 파티의 형태 - -| 형태 | 의미 | -| --- | --- | -| 테마 출연진 | 유명 투자자나 TV 앙상블처럼 특정 주제를 중심으로 모인, 서로 뚜렷이 구분되는 목소리. | -| 일회성 페르소나 | 그룹을 만들지 않고 후보군에 추가한 한두 명의 페르소나. | -| 데이터 기반 포커스 그룹 | 고객 또는 설문 데이터를 주면 행동 동인을 기준으로 군집화하고 대표 페르소나를 만듭니다. 고객들이 독립적으로 반응하도록 `subagent` 모드와 함께 쓰세요. | -| 리뷰 패널 | 중요한 것을 두고 논쟁하도록 설계된 비판 렌즈들입니다. 함께 제공되는 Code Review Crew가 예입니다. | -| 숙의 보조 구조 | 사람 대신 결정을 내리는 기구인 척하지 않으면서, 사람이 더 깊이 생각하도록 돕는 구성입니다. 함께 제공되는 Anti-Consensus Club이 예입니다. | -| 열린 출연진 파티 | 고정 명단이 없습니다. 장면이 세계관을 정하고, 주제가 바뀔 때마다 즉석으로 출연진을 정합니다. | - -파티의 효과가 가장 큰 사례는 포커스 그룹입니다. 실제 프로필을 넣으면 대표 고객 패널이 만들어지고, 제품을 만들기 전에 아이디어를 시험할 수 있습니다. 각 고객은 직전 발언자의 의견을 따라가지 않고 자신의 목표와 예산에 따라 반응합니다. - -## 만들 수 있는 파티 - -파티는 페르소나와 장면만으로 구성되므로 활용 범위가 넓고, 새 스킬이나 모듈도 필요하지 않습니다. - -- 스타트업 아이디어를 스트레스 테스트하는 창업자 팀. -- 감사에서 문제 되기 전에 허점을 찾는 컴플라이언스 팀. -- 소프트웨어 개념을 두고 토론하는 애자일 선언문 작성자들. -- 글쓰기 파트너로 구성한 코미디언 파티. -- 철학적 질문을 풀거나 어려운 문제를 함께 해결하는 과거의 위대한 사상가들. -- 분기별 계획을 세우는 비즈니스 경영진. - -위 예시는 출발점일 뿐입니다. 서로 구분되는 관점을 설명할 수 있다면 어떤 조합이든 파티가 됩니다. 페르소나를 만들고 토론 상황을 정하면 됩니다. - -## Code Review Crew - -기본 파티는 설치된 모듈이 제공하는 에이전트입니다. Code Review Crew는 그 기본 파티와 함께 제공되는 커스텀 파티입니다. 직접 파티를 만들기 전에 참고할 수 있는 작동 템플릿이지 기본값을 대체하지 않습니다. 다섯 가지 관점에서 변경을 비판적으로 살펴보고, 형식적인 승인 대신 실제로 중요한 것이 무엇인지 논쟁하는 리뷰 패널입니다. - -| 멤버 | 관점 | -| --- | --- | -| Vex | 보안. 모든 변경을 위협 모델링하고 구체적인 악용 경로를 말합니다. | -| Grumbal | 적대자. 코드는 깨졌다고 가정하고 그것을 증명하려고 합니다. | -| Boundary | 엣지 케이스. 모든 분기, `null`, 경쟁 상태, 과도하게 큰 입력, 특이한 시간대를 봅니다. | -| Yui | 장인. 단순성과 명명을 살피고, 지나치게 복잡한 기교나 중복이 없는지 봅니다. | -| Dana | 실용주의자. 완벽주의자들에게 반박하고 실제 문제와 사소한 지적을 구분합니다. | - -이 팀은 정의되어 있지만 비활성 상태로 제공됩니다. 멤버들은 후보군에만 있으므로 그룹을 소환하기 전까지 비용이 들지 않고 기본 파티를 어지럽히지도 않습니다. 다섯 관점에서 각자 검토한 뒤 발견 사항을 두고 충돌하도록 `subagent` 모드로 실행하세요. - -## Anti-Consensus Club - -Anti-Consensus Club은 결정이나 전략, 설계, 모호한 질문을 다룰 때 유용합니다. 어시스턴트 하나가 너무 빨리 동의하거나, 더 얻을 것이 없는데도 토론을 이어가는 상황을 줄여 줍니다. 투표 기구가 아니라 유용한 반론을 제기하고 주장을 점검하며, 반복을 끊고 결정권을 사람에게 돌려주는 모임입니다. - -| 멤버 | 관점 | -| --- | --- | -| Wildcard | 선택지 생성자 - 다른 문제 정의와 가정, 예시를 제안합니다. | -| Level | 주장 점검자 - 근거와 빠진 정보, 확신 수준을 확인합니다. | -| Killjoy | 반복 차단자 - 반복과 가짜 의견 차이, 근거 없는 추측을 멈춥니다. | -| Splinter | 합의 도전자 - 너무 쉬운 합의와 무시된 절충점을 문제 삼습니다. | - -플랫폼이 지원한다면 `/bmad-party-mode --party anti-consensus-club --mode subagent`로 실행하세요. 세션을 시작할 때 이 방식을 권장하지만, 다른 모드로 계속하면 다시 권하지 않습니다. - -## 대화 이끌기 - -사용자가 처음부터 끝까지 대화를 이끕니다. - -- 누군가를 들이기: "UX 디자이너를 불러와." -- 한 관점을 깊게 파기: "Winston, 저걸 해체해 봐." 직접 요청하면 한 페르소나가 깊게 답하라는 신호가 됩니다. -- 세션 중 파티 바꾸기: "작가 회의실로 전환해." 활성 그룹을 바꾸고 대화 맥락은 이어갑니다. -- 현재 파티에 없는 커스텀 멤버라도 이름으로 소환하기. - -어떤 모드로 실행 중이든 오케스트레이터는 결과를 별도 답변 묶음이 아니라 하나의 대화로 제시합니다. 페르소나가 끝까지 캐릭터를 유지하게 하며, 작동 방식을 설명하느라 몰입을 깨지 않습니다. - -:::tip[둘 이상의 파티 섞기] -한 그룹에 제한되지 않습니다. 여러 파티의 멤버를 같은 대화로 끌어오거나, 그 자리에서 출연진을 지명해 섞어도 됩니다. 예를 들어 Golden Girls를 Martin Fowler, Linus Torvalds와 함께 아키텍처 리뷰에 불러 변경 요청을 두고 논쟁하게 하세요. 어떤 일이 벌어질지 상상해 보세요. -::: - -## 파티는 기억합니다 - -파티에 기억 기능을 주면 중단했던 지점에서 이어갑니다. 파티는 지난 세션의 자체 기록을 유지합니다. 멤버 사이에 쌓인 역학, 열어 둔 실마리, 이전 대화에서 어떤 결론에 이르렀는지를 기억합니다. 일주일 뒤 다시 열어도 그 이력은 남아 있습니다. 지난번에 충돌했던 두 멤버는 조금 차갑게 시작하고, 예전 세션의 날카로운 한 줄이 자연스럽게 다시 떠오를 수 있습니다. - -이는 대화록이 아니라 기억입니다. 파티는 모든 말을 기록하지 않고, 기억할 가치가 있는 몇 가지만 가져갑니다. 그래서 다음 대화가 이어지는 느낌을 주면서도 과거 전체를 끌고 오지 않습니다. 이 과정은 백그라운드에서 자동으로 일어납니다. 따로 저장할 것이 없고, 파티는 캐릭터를 깨고 기억 기능을 설명하지 않습니다. - -즉석에서 등장한 캐릭터도 기억될 수 있습니다. 열린 출연진 장면에 잠깐 등장한 인물이거나, 대화 중 추가한 사람일 수 있습니다. 세션이 끝나면 파티는 새로 온 인물을 유지할지 제안합니다. 유지하기로 하면 파티 명단에 추가해 다음 세션에도 다시 등장할 수 있게 합니다. - -메모리는 파티별로 설정됩니다. 파티를 만들거나 저장할 때 기억할지 묻습니다. 기본 설치 에이전트 파티는 끄지 않는 한 기억합니다. 이 설정은 `/bmad-customize bmad-party-mode`에서 바꿀 수 있습니다. - -## 세션 기록본 - -마무리할 때 오케스트레이터는 세션 기록본을 제안합니다. 보관하거나 공유할 수 있는 독립형 HTML 문서입니다. 가공하지 않은 대화록을 그대로 내놓는 대신 페르소나별로 대화를 정리합니다. 거절하면 파티는 그대로 끝납니다. - -:::tip[더 나은 결정] -파티의 가치는 의견 차이에 있습니다. 한자리에 모인 다양한 관점은 한 가지 관점으로는 놓치기 쉬운 부분을 잡아냅니다. -::: diff --git a/docs/ko-kr/explanation/preventing-agent-conflicts.md b/docs/ko-kr/explanation/preventing-agent-conflicts.md deleted file mode 100644 index b1fdc5b2e8..0000000000 --- a/docs/ko-kr/explanation/preventing-agent-conflicts.md +++ /dev/null @@ -1,121 +0,0 @@ ---- -title: "에이전트 충돌 방지" -description: 여러 에이전트가 시스템을 구현할 때 아키텍처가 충돌을 방지하는 방법 -sidebar: - order: 6 ---- - -여러 AI 에이전트가 시스템의 서로 다른 부분을 구현하면 충돌하는 기술 결정을 내릴 수 있습니다. 아키텍처 문서화는 공유 표준을 세워 이를 방지합니다. - -## 일반적인 충돌 유형 - -### API 스타일 충돌 - -아키텍처가 없으면: - -- 에이전트 A는 REST와 `/users/{id}`를 사용합니다 -- 에이전트 B는 GraphQL 뮤테이션을 사용합니다 -- 결과: 일관되지 않은 API 패턴과 API 사용자의 혼란 - -아키텍처가 있으면: - -- ADR이 명시합니다. "모든 클라이언트-서버 통신에는 GraphQL을 사용" -- 모든 에이전트가 같은 패턴을 따릅니다 - -### 데이터베이스 설계 충돌 - -아키텍처가 없으면: - -- 에이전트 A는 snake_case 컬럼명을 사용합니다 -- 에이전트 B는 camelCase 컬럼명을 사용합니다 -- 결과: 일관되지 않은 스키마와 혼란스러운 쿼리 - -아키텍처가 있으면: - -- 표준 문서가 명명 규칙을 명시합니다 -- 모든 에이전트가 같은 패턴을 따릅니다 - -### 상태 관리 충돌 - -아키텍처가 없으면: - -- 에이전트 A는 전역 상태에 Redux를 사용합니다 -- 에이전트 B는 React 컨텍스트를 사용합니다 -- 결과: 상태 관리 방식이 여러 개로 나뉘어 복잡해짐 - -아키텍처가 있으면: - -- ADR이 상태 관리 방식을 명시합니다 -- 모든 에이전트가 일관되게 구현합니다 - -## 아키텍처가 충돌을 방지하는 방법 - -### 1. ADR을 통한 명시적 결정 - -모든 중요한 기술 선택에는 다음 내용을 함께 기록합니다. - -- 컨텍스트(왜 이 결정이 중요한가) -- 고려한 대안(어떤 선택지가 있는가) -- 결정(무엇을 선택했는가) -- 근거(왜 선택했는가) -- 결과(받아들인 절충) - -### 2. FR/NFR별 지침 - -아키텍처는 각 기능 요구사항을 기술적 접근에 연결합니다. - -- FR-001: 사용자 관리 → GraphQL 뮤테이션 -- FR-002: 모바일 앱 → 최적화된 쿼리 - -### 3. 표준과 관례 - -다음을 명시적으로 문서화합니다. - -- 디렉터리 구조 -- 명명 규칙 -- 코드 구성 -- 테스트 패턴 - -## 공유 컨텍스트로서의 아키텍처 - -아키텍처를 구현 전 모든 에이전트가 읽는 공유 컨텍스트로 생각하세요. - -```text -PRD: "무엇을 만들 것인가" - ↓ -아키텍처: "어떻게 만들 것인가" - ↓ -에이전트 A가 아키텍처를 읽음 → 에픽 1 구현 -에이전트 B가 아키텍처를 읽음 → 에픽 2 구현 -에이전트 C가 아키텍처를 읽음 → 에픽 3 구현 - ↓ -결과: 일관된 구현 -``` - -## 주요 ADR 주제 - -충돌을 방지하는 일반적인 결정: - -| 주제 | 예시 결정 | -| --- | --- | -| API 스타일 | GraphQL vs REST vs gRPC | -| 데이터베이스 | PostgreSQL vs MongoDB | -| 인증 | JWT vs 세션 | -| 상태 관리 | Redux vs 컨텍스트 vs Zustand | -| 스타일링 | CSS Modules vs Tailwind vs Styled Components | -| 테스트 | Jest + Playwright vs Vitest + Cypress | - -## 피해야 할 안티패턴 - -:::caution[흔한 실수] -- **암묵적 결정** - "API 스타일은 하면서 정하자"는 태도는 일관성 부족으로 이어집니다 -- **과도한 문서화** - 모든 사소한 선택을 문서화하면 분석 마비가 생깁니다 -- **오래된 아키텍처** - 한 번 쓰고 업데이트하지 않은 문서는 에이전트가 오래된 패턴을 따르게 합니다 -::: - -:::tip[올바른 접근] -- 에픽 경계를 넘는 결정을 문서화하세요 -- 충돌이 생기기 쉬운 영역에 집중하세요 -- 배운 것을 반영해 아키텍처를 업데이트하세요 -- 중요한 변경에는 `bmad-correct-course`를 사용하세요 -::: diff --git a/docs/ko-kr/explanation/project-context-theory.md b/docs/ko-kr/explanation/project-context-theory.md deleted file mode 100644 index 4a38821436..0000000000 --- a/docs/ko-kr/explanation/project-context-theory.md +++ /dev/null @@ -1,103 +0,0 @@ ---- -title: "프로젝트 컨텍스트의 이론" -description: bmad-project-context가 적은 정보만 수집하는 이유, 저장소의 에이전트 지침에 포함할 기준, 의도적으로 제외하는 정보 -sidebar: - order: 9 ---- - -`bmad-project-context`는 다소 불편한 발견에서 출발했습니다. AI 에이전트를 *위해* 작성한 문서 대부분이 오히려 에이전트의 성능을 떨어뜨린다는 사실입니다. 이 문서에서는 이 스킬이 무엇을 왜 수집하는지, 더 중요하게는 무엇을 의도적으로 수집하지 않는지 설명합니다. `bmad-document-project` 또는 `bmad-generate-project-context`에서 넘어왔다면 마지막 절에서 무엇이 바뀌었는지 정확히 확인할 수 있습니다. - -스킬의 *기능*과 실행 방법은 [프로젝트 컨텍스트](project-context.md)와 [사용 가이드](../how-to/project-context.md)를 참고하세요. - -## 기준선: 정보를 찾는 데 드는 비용 - -작성된 컨텍스트는 담고 있는 사실을 저장소에서 찾아내는 데 큰 비용이 들 때만 그만한 가치가 있습니다. 에이전트가 알아낼 수 있는지보다, 그 사실을 매번 직접 찾아야 할 때 치르는 비용이 기준입니다. 탐색에 드는 노력, 제때 올바른 곳을 찾을 가능성, 실수하기 전에 발견하는지 아니면 실수한 뒤에야 알게 되는지를 따집니다. - -서로 다른 두 연구 분야의 결과가 같은 결론을 뒷받침합니다. 저장소 단위 작업에서 코드 추론과 문서 암기를 분리해 비교하면, **문서를 읽는 것보다 코드를 직접 볼 때 성능이 훨씬 크게 향상됩니다.** 시스템의 작동 방식을 설명한 문서는 원본 소스보다 못합니다. 반대로 코드에서 요구 사항을 생성하게 하는 실험에서는 모델이 아직 구현되지 않은 내용을 안정적으로 만들어 내지 못했습니다. 현재 구현된 동작은 소스에서 복원할 수 있지만, **의도와 근거, 일부러 선택하지 않은 대안은 복원할 수 없습니다.** 코드가 말하는 내용을 직접 확인하는 일은 비용이 적고 신뢰할 수 있으므로, 같은 내용을 따로 저장해 둘 가치가 없습니다. - -따라서 에이전트가 원본에서 적은 비용으로 확실하게 읽을 수 있는 내용은 그때그때 확인하고 따로 저장하지 않습니다. 복사본은 금세 낡을 뿐 아니라 호출할 때마다 비용도 듭니다. 다만 같은 사실을 세션마다 힘들게 다시 찾아야 한다면, 저장소에서 유추할 수 있더라도 기록할 가치가 있습니다. - -## 대부분의 AGENTS.md가 효과를 내지 못한 이유 - -저장소 지침 파일은 2026년에 가장 많이 연구된 산출물입니다. 그러나 파일이 있을 때와 없을 때를 비교한 결과는 좋지 않았습니다. **작업 성공률은 나아지지 않았고 추론 비용은 20% 늘었습니다.** 실제 저장소를 대상으로 한 반복 실험에서도 같은 결과가 나왔으며, 실패 원인은 저장소 지식의 부족보다 구현 능력의 한계였습니다. 대규모 연구 하나에서는 **무작위로 생성한 규칙이 전문가가 엄선한 규칙과 같은 성과를 냈습니다.** - -이 결과만 보면 저장소 지침 파일은 쓸모없어 보입니다. 하지만 해당 파일에 무엇이 들어 있었는지 살펴보면 이유가 드러납니다. 대부분 저장소 구조, 기술 스택, 아키텍처 요약처럼 저장소에 이미 있는 내용을 반복했습니다. 연구가 측정한 것은 작성된 컨텍스트 전체가 아니라, 저장소에서 *유추할 수 있는* 내용을 글로 복제했을 때의 효과였습니다. - -## 항상 불러오는 파일의 짧은 인덱스가 정반대 결과를 낸 이유 - -한 대조 실험은 모델 학습 데이터에 없던 프레임워크 API를 대상으로 네 가지 설정을 비교했습니다. - -| 설정 | 통과율 | -| --- | --- | -| 문서 없음 | 53% | -| 재사용 가능한 스킬만 제공 | 53% | -| 같은 스킬을 명시적으로 호출하도록 지시 | 79% | -| **`AGENTS.md`에 압축된 문서 인덱스 제공** | **100%** | - -효과가 없었던 앞선 연구와 파일 형식은 같았지만 내용이 달랐습니다. 저장소를 다시 설명하지 않고 모델이 모르는 지식을 담았습니다. 40KB 문서를 8KB로 압축한 인덱스였지만 성능은 떨어지지 않았습니다. - -이 결과에서 놓치면 안 될 점이 있습니다. 별도 지시 없이 제공한 스킬은 **56%의 사례에서 한 번도 호출되지 않았습니다.** 호출하라는 명시적 지침을 추가하면 호출률이 95%를 넘었지만 통과율은 여전히 79%에 그쳤고, 문구가 조금만 달라져도 결과가 크게 흔들렸습니다. - -**필요할 때 알아서 찾아오도록 맡기는 방식은 신뢰하기 어렵습니다.** 다른 측정도 같은 결론을 냈습니다. 709페이지짜리 위키에서 일부 구성을 제거해 비교한 실험에서 에이전트는 인덱스를 건너뛰고, 질문만 보고 페이지 경로를 추측했습니다. - -이 결과를 설명하는 원칙은 하나입니다. **에이전트가 불러올지 스스로 판단해야 하는 인덱스는 건너뛰지만 이미 컨텍스트에 들어 있는 인덱스는 건너뛰지 않습니다.** 반드시 필요한 정보는 항상 불러오는 파일에 둬야 합니다. 다른 파일을 가리키는 포인터에는 에이전트가 직접 확인할 수 있는 조건을 붙여야 합니다. 경로, 파일 형식, 구체적인 작업은 괜찮지만 에이전트가 스스로 판단하거나 자기 행동을 감시해야 알 수 있는 조건은 피해야 합니다. - -## 포함할 가치가 있는 정보 - -모든 줄에는 **가지치기 테스트**를 적용합니다. *이 줄을 삭제하면 에이전트의 행동이 달라지는가?* 사람이 작성한 줄이 이 테스트를 통과하지 못하더라도 곧바로 삭제하지는 않습니다. 먼저 삭제해도 되는 근거가 있는지 [규칙을 없앨 때는 반대로 판단합니다](#규칙을-없앨-때는-반대로-판단합니다)의 기준에 따라 확인합니다. - -- **설정 파일만으로 알 수 없는 프로젝트 실행 조건.** 쉽게 짐작할 수 있는 명령은 `package.json`, `Makefile`, CI 설정에서 직접 확인하고, 여러 명령이 그럴듯해 보일 때 무엇을 사용해야 하는지와 그 파일에 없는 예외만 기록합니다. 루트 테스트 스크립트가 이 워크스페이스에서는 아무 일도 하지 않거나, 통합 테스트 전에 서비스를 실행해야 하거나, 전체 테스트가 너무 느려 개별 파일로 반복해야 하거나, CI가 테스트 스크립트에 없는 검사를 수행하는 경우입니다. -- **코드로 표현할 수 없는 정책.** 변경 금지 경로, 생성된 파일, 브랜치 규칙, 보안 및 규정 준수 요구 사항입니다. 탐색으로 추측하지 않고 권한 있는 사람이 알려준 내용만 받습니다. -- **생태계 기본값과 다른 규칙.** 차이가 있는 부분만 기록합니다. 별도 지침이 없으면 에이전트는 일반적인 방식을 따르므로 기본 방식으로도 틀리지 않을 사실은 한 줄을 쓸 가치가 없습니다. -- **실제로 관찰한 실패에서 나온 위험 요소.** 저장소를 훑으면 위험해 보이는 사실을 수백 개 찾을 수 있지만 그중 실제 실수를 일으키는 몇 개를 사실의 성질만으로 가려낼 수는 없습니다. 그 신호는 실제 행동에서만 나옵니다. 스캔 중 뜻밖의 사실을 발견하면 곧바로 규칙으로 쓰지 않고 질문합니다. -- **컴포넌트 간 규칙과 필수 버전.** 에이전트가 지금 편집하는 파일만 봐서는 알 수 없지만 시스템 여러 부분에서 함께 지켜야 하는 규칙과, 프로젝트가 실제로 빌드할 때 사용하는 도구 버전을 기록합니다. 빠짐없이 나열하기 위한 목록은 만들지 않습니다. -- **긍정형 지침보다 부정형 제약.** 측정 결과 부정형이 더 효과적이었습니다. 그래서 금지 사항을 적을 때는 항상 허용되는 대안도 함께 밝힙니다. - -## 의도적으로 수집하지 않는 정보 - -무엇을 비워 두는지가 이 설계의 핵심입니다. - -| 수집하지 않는 정보 | 이유 | -| --- | --- | -| **코드가 이미 말해 주는 내용** | 에이전트는 소스 요약보다 소스 자체를 더 잘 읽습니다. 바꿔 쓴 설명을 추가하면 원본은 정확한데 복사본만 낡아 가는 문제가 생깁니다. | -| **저장소 구조와 파일 맵** | 구조는 커밋마다 달라져 저장된 맵이 가장 빨리 낡습니다. 에이전트는 몇 초 안에 최신 구조를 직접 파악할 수 있습니다. | -| **개요와 둘러보기 문서** | 대표적인 생성 산출물이자 측정된 성능 저하의 원인입니다. 블록은 독자를 안내하는 대신 에이전트의 행동을 바꿔야 합니다. | -| **생태계 기본값** | LLM은 일반적인 Node, Python, Go 프로젝트의 작동 방식을 이미 압니다. 기본값을 다시 설명하면 에이전트가 처음부터 알고 있던 내용을 가르치는 데 비용을 씁니다. | -| **흥미롭다는 이유만으로 넣은 내용** | 흥미롭다는 사실은 필요하다는 증거가 아닙니다. 이 스킬은 바로 이런 정보가 쌓이는 문제를 막기 위해 존재합니다. | -| **에이전트가 스스로 지켜야 하는 스타일 규칙** | 이런 규칙은 포매터, 린터, 훅, CI 검사가 맡아야 합니다. 스킬은 대신 검사를 제안하며, 검사가 도입되면 해당 줄은 삭제합니다. | -| **이력과 편집 과정 설명** | "X를 제거한 이유는…" 같은 서술은 금지합니다. 이력은 Git이 관리하고 블록에는 현재의 사실만 적습니다. | -| **지향하는 미래 상태** | 시스템이 앞으로 어떤 모습이어야 하는지는 사양에 속합니다. 에이전트가 미래 목표를 현재 사실로 오인하면 존재하지 않는 동작을 구현합니다. | - -결과가 작은 것은 의도된 설계입니다. 근거가 열 줄만 뒷받침한다면 산출물도 열 줄이면 됩니다. - -## 규칙을 없앨 때는 반대로 판단합니다 - -규칙을 없앨 때만큼은 가지치기 원칙을 반대로 적용해야 합니다. 이를 잘못 적용하면 파일에서 가장 가치 있는 내용이 조용히 사라집니다. - -**정책이나 위험 요소는 세 가지 경우에만 삭제합니다. 지키던 대상이 사라지거나 해당 제약이 자동으로 강제되는 경우, 또는 사람이 직접 폐기한 경우입니다.** 최근에 같은 실패가 없었다는 이유로는 삭제하지 않습니다. 효과가 있는 규칙은 실패의 흔적을 스스로 없애기 때문입니다. 이 블록에서는 더는 발생하지 않는 실수를 막아 주는 규칙이 특히 중요합니다. - -이 보호 원칙은 정책이나 위험 요소뿐 아니라 사람이 작성한 모든 지침에 적용됩니다. 내용이 오래됐거나 틀렸을 때, 훅이나 검사로 이미 강제될 때, 해롭거나 다른 지침과 충돌할 때, 또는 사용자가 항목별 삭제를 승인했을 때만 없앱니다. 저장소에서 유추하거나 다른 위치에서 찾을 수 있다는 이유만으로는 삭제하지 않습니다. - -## 서로 다른 두 범위와 두 산출물 - -하나의 산출물로 코딩 작업과 계획 작업을 모두 지원할 수는 없습니다. 두 작업에 필요한 정보는 거의 겹치지 않습니다. - -**구현 컨텍스트**는 제약, 명령, 규칙, 위험 요소를 담으며 **코드 저장소**에 속합니다. 코드와 대조하고 직접 실행해 검증할 수 있지만 커밋할 때마다 낡습니다. 모든 세션에서 불러오므로 아주 작아야 합니다. 이 스킬이 관리하는 대상입니다. - -**계획 컨텍스트**는 결정 근거, 선택하지 않은 대안, 책임 주체, 도메인 의미, 조직 표준을 담으며 **프로젝트나 이니셔티브**에 속합니다. 출처 문서로만 추적할 수 있습니다. 저장소가 아니라 조직의 변화 주기에 따라 보통 수개월 단위로 낡습니다. 항상 불러오지 않고 필요할 때 집중적으로 살펴봅니다. 이는 별도의 기능이며 추후 제공될 예정입니다. - -서로 다른 두 범위를 파일 하나로 해결하려 한 결과가 이 스킬이 대체한 두 스킬이었습니다. - -## 컨텍스트는 계속 가치를 입증해야 합니다 - -이전 모델은 문서를 자산으로 다뤘습니다. 범위가 넓을수록 가치가 크다고 봤습니다. 이 스킬은 컨텍스트를 **유지할 가치가 있는지 계속 입증해야 하는 부담**으로 봅니다. Refresh는 모든 주의 사항을 다시 확인합니다. 삭제되거나 이름이 바뀐 항목도 각 줄과 대조합니다. Audit은 가지치기 테스트를 적용하되, 사람이 작성한 내용에는 앞에서 설명한 삭제 기준을 함께 적용합니다. 작업 후 블록은 이전보다 작거나 같은 크기를 유지합니다. 주장의 출처가 사라지면 새로운 사실에 맞춰 주장을 고치거나 제거합니다. 같은 내용을 언급한다는 이유만으로 다른 문서를 새 출처로 바꿔 끼우지 않습니다. - -첫 버전은 쉽게 만들 수 있습니다. 진짜 가치는 계속 정확하게 유지하는 데 있습니다. Refresh와 Audit이 설명서의 참고 사항이 아니라 독립된 의도로 제공되는 이유입니다. - -## 대체된 두 스킬과의 차이 - -`bmad-document-project`는 기존 저장소를 스캔해 개요, 소스 트리, 영역별 심층 설명으로 구성된 문서 트리를 생성했습니다. 문서를 자산으로 보는 모델이었지만 증거는 반대였습니다. 결과물은 크고 검증되지 않았으며 만들어지는 순간부터 낡았습니다. 에이전트의 성능을 떨어뜨리는 종류의 컨텍스트였습니다. 그래도 *작업 전에 저장소를 이해해야 한다*는 발상은 탐색 단계에 남았습니다. 이제 탐색 결과는 설명문을 만드는 대신 검증에 사용합니다. - -`bmad-generate-project-context`에는 눈에 띄지 않는 프로젝트별 사실을 작은 규칙 파일 하나에 담는다는 올바른 생각이 있었습니다. 이제 그 생각이 전체 구조의 중심입니다. 이전 방식에는 검증 절차나 유지보수 주기가 없었고, 추론과 확인된 사실을 구분할 방법도 없었습니다. - -이전 스킬은 더 많은 문서를 작성했고 새 스킬은 더 적은 사실을 관리합니다. 정보는 많기보다 적고 검증된 편이 낫습니다. diff --git a/docs/ko-kr/explanation/project-context.md b/docs/ko-kr/explanation/project-context.md deleted file mode 100644 index 4ebc93540e..0000000000 --- a/docs/ko-kr/explanation/project-context.md +++ /dev/null @@ -1,57 +0,0 @@ ---- -title: "프로젝트 컨텍스트" -description: bmad-project-context가 저장소의 에이전트 지침을 작성하는 방식 — AGENTS.md에 작고 검증된 블록을 추가합니다 -sidebar: - order: 8 ---- - -`bmad-project-context`는 AI 에이전트가 저장소에서 제대로 작업할 수 있도록 환경을 정비합니다. 산출물은 저장소의 `AGENTS.md` 안에 들어가는 간결하고 검증된 규칙 블록입니다. 조직이 요구하는 사항, 실제로 실행해 확인한 명령, 일반적인 예상과 다른 규칙, 에이전트가 이 저장소에서 반복하는 실수를 기록합니다. - -이 스킬은 생성기가 아니라 대화형 도구입니다. 에이전트가 지켜야 할 규칙, 즉 거버넌스와 보안, 코딩 표준을 알려주면 나머지는 스킬이 찾아 검증합니다. 무엇을 쓸 때든 사람이 확인하며 무인 실행 모드는 없습니다. - -의도적으로 수집하지 않는 정보와 그 이유를 포함한 전체 근거는 [프로젝트 컨텍스트의 이론](project-context-theory.md)을 참고하세요. - -## 포함하는 정보와 제외하는 정보 - -기준은 필요한 순간에 해당 사실을 찾아내는 데 드는 비용입니다. 에이전트는 코드를 설명한 글보다 코드 자체를 더 정확히 읽습니다. 적은 비용으로 찾을 수 있는 내용을 글로 복제하면 금세 낡고, 호출할 때마다 불필요한 비용도 듭니다. 따라서 저장소 개요, 디렉터리 구조, 기술 스택 목록은 넣지 않습니다. 대신 찾는 데 큰 비용이 들거나, 실수한 뒤에야 발견하기 쉬운 내용을 기록합니다. - -코드만 읽어서는 필요한 순간에 찾기 어렵거나 알 수 없는 다음 정보는 기록할 가치가 있습니다. - -- **조직 정책** — 변경 금지 경로, 생성된 파일, 브랜치 규칙, 보안 및 규정 준수 요구 사항 -- **설정 파일만으로 알 수 없는 실행 조건** — 모든 스크립트를 옮겨 적는 대신 어떤 명령을 사용해야 하는지와 주의할 점을 기록합니다. `pnpm test`는 이미 `package.json`에 있지만, 테스트가 11분 걸리거나 먼저 서비스를 실행해야 한다는 사실은 그렇지 않습니다. -- **생태계 기본값과 다른 규칙** — 별도 지침이 없으면 에이전트는 일반적인 방식을 따르기 때문입니다. -- **실제로 겪은 문제** — 기존 기록, 관리자의 기억, Git 이력에서 반복해 수정한 실수, 이번 작성 과정에서 발견하고 바로잡은 실수만 포함합니다. 스캔 중 위험해 보이는 사실을 찾더라도 곧바로 규칙으로 쓰지 않고 먼저 질문합니다. -- **컴포넌트 간 규칙과 필수 버전** — 지금 편집하는 파일만 봐서는 알 수 없지만 시스템 여러 부분에서 함께 지켜야 하는 규칙과, 프로젝트가 실제로 빌드할 때 사용하는 도구 버전을 기록합니다. -- **작업 결과가 저장되는 위치와 먼저 읽어야 할 파일을 가리키는 포인터** - -스킬이 적용하는 모든 규칙과 그 근거는 `references/best-practices.md`에 정리되어 있습니다. 스킬은 이 기준으로 저장소의 현재 상태를 평가하고, 작업을 마칠 때 판단 근거도 설명합니다. - -## 지원하는 의도 - -| 의도 | 수행하는 작업 | -| --- | --- | -| **Setup** | 보존할 기존 지침이 없는 저장소에서 사용합니다. 사용자가 제공할 규칙을 물은 뒤 나머지를 찾아 검증하고, 전체 블록을 미리 보여준 다음 승인받아 작성합니다. | -| **Adopt** | 사용자가 이미 작성한 지침을 받아들입니다. 파일을 쓰기 전에 기존 지침이 각각 어떻게 처리되는지 보여주며, 사용자 승인 없이 삭제하지 않습니다. | -| **Refresh** | 기존 블록을 대상으로 같은 과정을 실행합니다. 명령을 다시 실행하고, 기록된 커밋 이후 삭제되거나 이름이 바뀐 항목을 비교해 이동한 내용을 갱신합니다. | -| **Record** | 에이전트가 실제로 저지른 실수 하나를 발생 시점에 기록합니다. 반복되거나 비용이 큰 실수라면 한 줄을 추가합니다. | -| **Audit** | 내용을 다시 검증하고 불필요한 항목을 덜어냅니다. 작업 후 블록은 이전보다 작거나 같은 크기를 유지합니다. | - -## 에이전트가 불러오는 방식 - -주요 코딩 도구가 모두 읽는 저장소 루트의 `AGENTS.md`를 사용합니다. BMad는 ``와 `` 사이만 관리합니다. 사용자가 마커 밖에 작성한 내용은 바이트 단위로 그대로 보존하며 Refresh도 건드리지 않습니다. - -모노레포의 컴포넌트와 중첩된 저장소에는 같은 규칙으로 별도의 파일을 만들고, 상위 파일에서 포인터로 연결합니다. 특정 디렉터리에만 적용되는 규칙이 많다면 해당 디렉터리의 `AGENTS.md`로 옮길 수 있습니다. 다만 사용하는 도구가 그 위치의 파일을 실제로 읽는지 먼저 확인해야 합니다. 읽지 않는다면 규칙을 루트 파일에 두고, 각 규칙이 적용되는 디렉터리를 명시합니다. - -## 저장소와 홈 디렉터리 중 어디에 둘까 - -이 스킬이 작성한 내용은 저장소에 커밋해야 합니다. 팀이 공유하고, 모든 컴퓨터에서 같은 규칙을 쓰며, 제약을 받는 코드와 함께 버전으로 관리하기 위해서입니다. 모든 프로젝트에서 같은 규칙이 반복되거나 팀 규칙이 아닌 개인 취향이라면 홈 디렉터리에 있는 에이전트 전역 설정에 두세요. - -## 아키텍처와의 관계 - -결정은 `bmad-architecture`에서 내립니다. 서로 다른 선택지에 실제 장단점이 있어 의견이 갈리는 설계 결정을 발견하면 이 스킬이 조용히 결론을 내리지 않고 `bmad-architecture`에서 다뤄야 한다고 안내합니다. - -## 이전 두 스킬을 대체 - -:::note[폐기됨: bmad-document-project 및 bmad-generate-project-context] -이전 두 스킬은 모두 폐기되었으며 이제 이 스킬로 연결됩니다. `bmad-generate-project-context`는 단일 `project-context.md`를 만들었습니다. 기존 파일이 있다면 Setup 과정에서 내용을 흡수할지 제안하므로 그대로 방치되지 않습니다. `bmad-document-project`는 기존 저장소를 스캔해 문서를 생성했지만, 연구 결과는 이 접근이 효과적이지 않음을 보여줬습니다. 시스템과 설계 근거를 깊이 설명하는 작업은 성격이 다르며 별도 기능으로 제공될 예정입니다. -::: diff --git a/docs/ko-kr/explanation/retrospective.md b/docs/ko-kr/explanation/retrospective.md deleted file mode 100644 index 30cff8c526..0000000000 --- a/docs/ko-kr/explanation/retrospective.md +++ /dev/null @@ -1,68 +0,0 @@ ---- -title: '회고' -description: 완료한 에픽이 남긴 diff, 커밋, 사양을 읽고 기억이 아닌 증거로 결과를 판단합니다. -sidebar: - order: 13 ---- - -에픽이 끝나면 `bmad-retrospective`를 바로 실행하세요. 이 스킬은 에픽이 만든 사양, 스토리 기록, 전체 diff, 커밋, 추적 산출물을 읽습니다. 사람이 작업 과정을 어떻게 기억하는지에 기대지 않고 이 증거로 검토합니다. 결과로 서면 검토, 제안된 실행 항목, 에픽이 인수 기준을 충족했는지에 대한 판정을 받습니다. - -## 수행하는 작업 - -에픽은 각각 따로 구현하고 검토한 여러 스토리가 쌓여 완성됩니다. 회고는 이를 한꺼번에 살펴보고 개별 스토리만으로는 알 수 없던 내용을 찾아냅니다. - -- **누적 결함** — 조금씩 어긋난 아키텍처, 중복으로 작성된 헬퍼, 여러 차례 몇백 줄씩 늘어나 결국 과도하게 커진 클래스 -- **diff 범위 검토** — 에픽의 diff를 `bmad-review`에 전달해 코드 관점별로 검토하며 개별 세션에서 양쪽을 함께 보지 못한 스토리 간 경계를 중점적으로 살펴봄 -- **사양 대조** — 구현된 코드가 에픽과 PRD에서 설명한 내용과 달라진 부분 -- **인수 판정** — 에픽 자체의 인수 조건에 따른 결과 평가 - -모든 발견 사항에는 파일, 줄, 커밋, 로그처럼 근거를 확인할 위치가 붙습니다. 근거를 가리킬 수 없는 주장은 보고서에 포함하지 않습니다. - -## 에픽이 끝난 뒤 실행하는 이유 - -각 스토리는 따로 검토를 통과했습니다. 여기까지 남은 버그는 작업을 나눠 본 탓에 놓친 문제입니다. 아홉 번의 세션이 같은 파일에 코드를 조금씩 추가하면, 어느 세션도 여러 작업이 합쳐져 커진 클래스를 전체로 보지 못합니다. 에픽이 처음 세운 목표를 전체적으로 달성했는지 판단한 세션도 없습니다. 회고는 이 빈틈을 메웁니다. diff가 아직 최신이고 세션 로그가 지워지기 전인 에픽 종료 시점이 가장 적절합니다. - -:::note[증거를 읽을 뿐, 만들어 내지 않습니다] -회고는 diff, 커밋, 사양에 실제로 드러난 내용을 보고합니다. 코드로 뒷받침할 수 없는 근본 원인이나 패턴을 지어내지 않습니다. -::: - -## 두 가지 에픽 입력 - -Retrospective는 전체 흐름에서 만든 스프린트 추적 정보와 [개발 경로 선택하기](../how-to/choose-a-development-path.md)에서 설명한 가벼운 사양 폴더를 모두 입력으로 받을 수 있습니다. - -| 에픽 입력 | 목록 및 완료 상태 | 회고 결과 | -| --- | --- | --- | -| 스프린트 추적 에픽 | `sprint-status.yaml`에서 선택한 에픽과 스토리 산출물 | 구현 산출물에 날짜가 붙은 문서를 만들고 스프린트 상태 업데이트 | -| 사양 기반 에픽 | `SPEC.md`, 순서가 있는 `stories.yaml`, `stories/-*.md` 기록 | 사양 폴더에 `RETROSPECTIVE.md` 생성. 스프린트 상태 파일은 만들거나 바꾸지 않음 | - -사양 기반 경로에서는 `stories.yaml`이 에픽의 스토리 목록을 정의하고 각 스토리 기록의 프런트매터가 완료 상태를 나타냅니다. Build와 Build Auto 중 어느 스킬이 기록을 만들었든 같은 규칙을 적용합니다. - -## 얻는 결과 - -증거 보고서와 판정을 받습니다. - -- **회고 문서** — 증거 목록, 출처와 함께 묶은 발견 사항, 판정, 제안된 실행 항목을 담습니다. -- **스프린트 모드의 업데이트된 상태** — 회고를 완료 상태로 표시하고 실행 항목을 관련 발견 사항과 연결합니다. 사양 기반 모드는 스프린트 상태를 사용하지 않습니다. -- **판정** — `accepted`, `accepted-with-open-items`, `rejected` 중 하나입니다. 다음 에픽을 시작할지, 멈추고 먼저 수정할지 알려줍니다. 해당 에픽에 완료되지 않은 스토리가 있으면 자동 판정은 **rejected**입니다. 대화형 실행에서는 사람이 이를 바꿀 수 있습니다. - -## 결과 활용하기 - -스킬은 제안만 합니다. 무엇을 실행할지는 사용자가 결정하며 코드나 사양을 자동으로 수정하지 않습니다. - -- **실행 항목**은 즉시 수정할 작업이나 새 스토리로 일반 개발 루프에 들어갑니다. 회고는 항목을 작성하지만 실행하지 않습니다. -- **사양 대조 결과**에는 증거가 함께 제공됩니다. 사용자가 프로젝트 계약에 직접 반영해야 하며 해석이 불확실한 내용은 사양에 자동으로 기록하지 않습니다. -- **판정**은 게이트 역할을 합니다. `rejected` 또는 `accepted-with-open-items` 판정은 다음 계획 단계로 넘겨야 할 내용을 알려줍니다. - -문제가 있는 에픽을 아무 일 없었다는 듯 승인 상태로 종료하지는 않습니다. 인수 조건을 충족하지 못했거나 에픽의 스토리가 하나라도 완료되지 않았다면, 사람이 판정을 바꾸지 않는 한 승인되지 않은 상태로 종료합니다. - -## 실행하기 - -에픽 번호나 사양 폴더를 지정해 `bmad-retrospective`를 실행하세요. 아무 입력도 주지 않으면 스프린트 상태에서 완료된 에픽을 찾을 수 있습니다. 기본적으로 보고서와 판정을 작성한 뒤 멈춥니다. - -| 원하는 작업 | 실행 방법 | -| --- | --- | -| 표준 검토 | `/bmad-retrospective` | -| 특정 에픽 검토 | `/bmad-retrospective 3` | -| 사양 기반 에픽 검토 | `/bmad-retrospective _bmad-output/specs/spec-/` | -| 팀 토론 | "팀과 함께 논의해 줘"라고 요청합니다. 실제 발견 사항을 두고 [파티 모드](./party-mode.md)를 진행합니다. 기본값은 꺼짐입니다. | -| 자동화를 위한 무인 실행 | `-H ` — 증거만으로 판정하는 비대화형 모드 | diff --git a/docs/ko-kr/explanation/why-solutioning-matters.md b/docs/ko-kr/explanation/why-solutioning-matters.md deleted file mode 100644 index ab7b52ca5c..0000000000 --- a/docs/ko-kr/explanation/why-solutioning-matters.md +++ /dev/null @@ -1,79 +0,0 @@ ---- -title: "솔루션 설계가 중요한 이유" -description: 다중 에픽 프로젝트에서 솔루션 설계 단계가 중요한 이유 -sidebar: - order: 5 ---- - -단계 3(솔루션 설계)은 계획에서 정한 **무엇을 만들 것인가**를 **어떻게 만들 것인가**라는 기술 설계로 구체화합니다. 구현이 시작되기 전에 아키텍처 결정을 문서화해 다중 에픽 프로젝트에서 에이전트 충돌을 방지합니다. - -## 솔루션 설계가 없을 때의 문제 - -```text -에이전트 1은 에픽 1을 REST API로 구현 -에이전트 2는 에픽 2를 GraphQL로 구현 -결과: 일관되지 않은 API 설계와 통합 난이도 증가 -``` - -여러 에이전트가 공유 아키텍처 지침 없이 시스템의 서로 다른 부분을 구현하면 각자 기술 결정을 내리다가 서로 충돌할 수 있습니다. - -## 솔루션 설계가 있을 때의 해결책 - -```text -아키텍처 워크플로가 결정: "모든 API에 GraphQL 사용" -모든 에이전트가 아키텍처 결정을 따름 -결과: 일관된 구현, 충돌 없음 -``` - -기술 결정을 명시적으로 문서화하면 모든 에이전트가 일관되게 구현하고 통합이 단순해집니다. - -## 솔루션 설계 vs 계획 - -| 측면 | 계획 (단계 2) | 솔루션 설계 (단계 3) | -| --- | --- | --- | -| 질문 | 무엇을, 왜? | 어떻게? 그리고 어떤 작업 단위로? | -| 출력 | FRs/NFRs(요구사항) | 아키텍처 + 에픽/스토리 | -| 에이전트 | PM | 아키텍트 → PM | -| 대상 | 이해관계자 | 개발자 | -| 문서 | PRD(기능/비기능 요구사항) | 아키텍처 + 에픽 파일 | -| 수준 | 비즈니스 로직 | 기술 설계 + 작업 분해 | - -## 핵심 원칙 - -**기술 결정을 명시적으로 문서화**해 모든 에이전트가 일관되게 구현하도록 합니다. - -기술 결정을 명시하면 다음 문제를 방지할 수 있습니다. - -- API 스타일 충돌(REST vs GraphQL) -- 데이터베이스 설계 불일치 -- 상태 관리 방식 차이 -- 이름 규칙 불일치 -- 보안 접근 방식 차이 - -## 솔루션 설계 깊이 선택하기 - -| 작업 특성 | 솔루션 설계 지침 | -| --- | --- | -| 기존 패턴이 분명한 국소 변경 | 대체로 필요하지 않음 | -| 제약을 알고 있는 여러 관련 컴포넌트 | 조율 위험에 따라 선택 | -| 여러 에픽 또는 시스템 간 의사결정 | 구현 방향을 맞추기 위해 필요 | -| 규제 대상, 고위험 또는 엔터프라이즈 이니셔티브 | 필수 거버넌스를 따르며 일반적으로 솔루션 설계가 필요 | - -솔루션 설계는 `bmad-build`가 사용할 수 있는 컨텍스트를 바꿀 뿐, 구현 워크플로를 바꾸지는 않습니다. - -:::tip[경험칙] -서로 다른 에이전트가 구현할 수 있는 여러 에픽이 있다면 솔루션 설계가 필요합니다. -::: - -## 건너뛸 때의 비용 - -복잡한 프로젝트에서 솔루션 설계를 건너뛰면 다음 문제가 생깁니다. - -- 스프린트 중 발견되는 **통합 이슈** -- 충돌하는 구현으로 인한 **재작업** -- 전체적으로 **더 긴 개발 시간** -- 일관되지 않은 패턴에서 생기는 **기술 부채** - -:::caution[비용 배율] -방향이 어긋나는 문제를 솔루션 설계에서 잡는 것이 구현 중 발견하는 것보다 10배 빠릅니다. -::: diff --git a/docs/ko-kr/how-to/choose-a-development-path.md b/docs/ko-kr/how-to/choose-a-development-path.md deleted file mode 100644 index 0cf2fc0129..0000000000 --- a/docs/ko-kr/how-to/choose-a-development-path.md +++ /dev/null @@ -1,118 +0,0 @@ ---- -title: '개발 경로 선택하기' -description: 단순한 편집부터 여러 에픽으로 구성된 프로젝트까지, 변경 규모에 맞는 가장 간단하고 안전한 BMad 경로를 선택하는 방법 -sidebar: - order: 3 ---- - -이 가이드에서는 소프트웨어 변경을 안전하게 처리할 수 있는 가장 간단한 BMad 경로를 선택하는 방법을 설명합니다. - -![BMad 루프에서는 막연한 생각은 구체화부터, 명확한 아이디어는 계획부터, 작은 변경은 구현부터 시작하며 학습 결과는 다시 계획에 반영됩니다.](/diagrams/bmad-delivery-loop.svg) - -모든 경로는 같은 전달 루프를 사용합니다. 큰 작업은 루프에 공동 컨텍스트를 더하고 구현 단위를 반복할 뿐, 별도의 전달 체계로 바뀌지 않습니다. - -## 사용 시점 - -- 변경을 시작하기 전에 어느 정도의 계획이 필요한지 확신이 없을 때 -- 하나의 요청이 단일 구현 세션을 넘어섰을 때 -- 직접 살펴볼 스토리와 무인으로 실행할 스토리를 나눌 때 -- 공동 제품 의도를 잃지 않으면서 여러 에픽을 조율할 때 - -:::note[필수 조건] -Build 또는 다른 BMad 워크플로를 사용하기 전에 BMad를 설치하세요. 명백하고 위험도가 낮은 편집에는 BMad가 필요하지 않습니다. -::: - -## 경로 선택 - -### 1. 가장 작은 안전 단위 찾기 - -선호하는 워크플로가 아니라 구현하려는 의도부터 살펴보세요. 하나의 구현 세션에서 변경을 이해하고 구현·검토해 끝낼 수 있는지 판단합니다. - -작업 범위만으로 결정하지 마세요. 위험도가 높거나 요구사항이 불명확하거나 아키텍처 전반에 영향을 주는 작업, 여러 시스템에 걸친 작업, 사람이나 팀 간 조율이 필요한 작업에는 더 많은 계획이 필요합니다. - -아래 세션 수는 요구사항이 아니라 참고 기준입니다. 작은 보안 변경이 훨씬 큰 일반 작업보다 더 체계적인 접근을 요구할 수도 있습니다. - -### 2. 경로 결정 - -| 경로 | 사용 시점 | 시작점 | -| --- | --- | --- | -| 단순 작업 | 편집 내용이 명확하고 위험도가 낮으며 체계적인 리뷰의 이점이 없을 때 | 직접 편집 | -| 단일 세션 작업 | 하나의 일관된 의도를 구현 세션 하나에서 처리할 수 있을 때 | `bmad-build` | -| 에픽 규모 작업 | 하나의 일관된 결과를 얻는 데 여러 구현 세션이 필요할 때 | `bmad-spec`, 이후 스토리 분해 | -| 프로젝트 규모 작업 | 여러 에픽에 걸치거나 구현 세션이 약 20회 이상 필요할 가능성이 있을 때 | [전체 BMad 흐름](../reference/workflow-map.md) | - -![네 가지 중첩 경로는 직접 편집, Build 한 번 실행, 에픽 안에서 Build 반복, 프로젝트 안에서 에픽 경로 반복이라는 같은 구현 단위를 재사용합니다.](/diagrams/development-paths.svg) - -작은 변경이라도 명시적인 계획과 리뷰가 도움이 된다면 직접 편집하는 대신 `bmad-build`를 사용하세요. - -## 선택한 경로 실행 - -### 3. 단순 작업 또는 단일 세션 작업 시작 - -단순 작업은 평소 개발 도구로 직접 변경하세요. 안전성이나 명확성을 높이지 못하는 워크플로 단계는 추가하지 않습니다. - -단일 세션 작업은 원하는 결과를 Build에 바로 전달합니다. - -```text -/bmad-build diffsettings 명령에 JSON 출력을 추가하되 기존 형식은 바꾸지 마. -``` - -Build는 직접 작성한 의도, 이슈, 의도 파일, 기존 Build 사양 또는 계획된 스토리를 입력으로 받을 수 있습니다. 작업 단위를 명확히 하고 필요하면 계획한 뒤 구현하고 결과를 검토해 작업 기록을 남깁니다. 구현 모델은 [변경 사항 구현하기](../build/build-a-change.md)를 참고하세요. - -### 4. 에픽 규모 작업 시작 - -여러 Build 세션이 필요하지만 하나의 일관된 결과를 목표로 한다면 가벼운 에픽 경로를 사용하세요. - -**에픽 정의 및 분할** - -1. 에픽 의도를 입력해 `bmad-spec`을 실행합니다. -2. 스토리 분해(Story Breakdown)를 요청합니다. `SPEC.md` 옆에 순서가 지정된 `stories.yaml`이 생성됩니다. -3. 제안된 순서를 검토하고 어느 스토리에 체크포인트가 필요한지 정합니다. - -스토리 목록은 실행 계획이지 앞으로 아무것도 바뀌지 않는다는 약속이 아닙니다. 앞선 작업에서 누락된 제약, 더 나은 분할 방식 또는 스토리 간 충돌이 드러나면 사양을 수정하고 스토리 분해를 다시 실행하세요. - -**구현 패턴 확립** - -중요하거나 위험도가 높거나 기반이 되는 스토리는 `bmad-build`로 구현하세요. 초기 스토리는 아키텍처, 프로젝트의 초기 구조, 이후 작업에서 반복할 패턴을 정하는 경우가 많습니다. 이 결정에 사람이 주의를 기울인 뒤 반복 작업을 자동화하세요. - -스토리마다 Build를 한 번 실행합니다. Build는 사양 폴더 아래에 해당 스토리의 구현 기록을 만들거나 기존 기록을 이어가며 상위 사양과의 연결을 유지합니다. - -**에픽 완료** - -각 스토리만 따로 확인하지 말고 모든 스토리가 함께 작동하는지 검증하세요. 그런 다음 사양 폴더를 지정해 `bmad-retrospective`를 실행합니다. Retrospective는 `stories.yaml`을 에픽 목록으로 읽고 상위 사양을 기준으로 전체 결과를 평가합니다. - -### 5. 프로젝트 규모 작업 시작 - -새 제품을 만들거나 여러 에픽으로 구성된 이니셔티브를 진행하거나 구현 세션이 약 20회 이상 필요할 가능성이 있다면 전체 BMad 흐름을 사용하세요. - -프로젝트에 실제로 필요한 계획을 준비합니다. 탐색, 제품 요구사항, UX, 아키텍처, 에픽, 준비도 확인, 스프린트 계획이 여기에 포함됩니다. 이 산출물은 구현을 둘러싼 공동 계약과 조율 기준을 만들지만 Build를 대신하지는 않습니다. 각 에픽은 여전히 세션 단위 작업의 연속으로 구현됩니다. - -의존성과 통합 경계가 명확하다면 서로 독립적인 에픽 흐름을 병렬로 진행할 수 있습니다. 각 흐름에는 담당자가 있어야 하며 모든 흐름은 같은 제품 의도와 아키텍처를 따라야 합니다. 에픽 경계마다 통합 검사와 회고를 실행하세요. - -## 큰 경로 운영 - -### 6. 결정이 안정된 뒤 자동화 추가 - -`bmad-build-auto`는 사람의 입력을 기다리지 않고 세션 하나에 들어오는 작업 단위 하나를 실행합니다. 다음 스토리를 선택하거나 백로그를 관리하지는 않습니다. - -중요한 구현 결정이 안정된 뒤 사용하세요. AI 코딩 세션을 오케스트레이터로 삼아 스토리마다 Build Auto 작업자 하나를 실행하고 새 근거가 드러나면 이후 작업을 수정할 수 있습니다. 선택 사항인 [bmad-loop](https://github.com/bmad-code-org/bmad-loop) 오케스트레이터는 순서가 지정된 `stories.yaml`을 결정론적으로 실행합니다. - -bmad-loop는 목록에 적힌 순서를 따릅니다. 의존성 그래프를 추론하거나 프로젝트 수준의 병렬 조율을 제공하지 않습니다. 작업자 계약, 스토리 선택, 상태 기록은 [자율 개발 루프](../reference/build-auto.md)를 참고하세요. - -### 7. 상위 의도 보호 - -작업을 나누는 과정에서 정보가 사라질 수 있습니다. 요구사항이 약해지거나 제약이 빠지거나, 각각 올바르게 구현된 두 스토리가 함께 실행될 때 실패할 수도 있습니다. 큰 BMad 경로는 이런 위험을 줄이는 장치를 더합니다. - -- 제품, UX, 아키텍처, 에픽 산출물이 공동 결정을 보존합니다. -- 각 구현 단위는 상위 계약까지 추적할 수 있습니다. -- 스토리 기록이 구현 결정과 완료 상태를 다음 작업으로 전달합니다. -- 이후 작업은 앞선 작업에서 얻은 근거를 반영할 수 있습니다. -- 통합 검사로 결합된 동작을 평가합니다. -- 새 근거가 생기면 이후 작업이나 상위 계획을 수정할 수 있습니다. -- 회고에서 에픽 전체를 평가하고 얻은 교훈을 이후 작업에 반영합니다. - -계획은 구현 중에도 계속됩니다. 변경 사항을 상위 의도와 다시 맞춘다면 작업 단위의 순서는 달라져도 됩니다. - -## 얻는 결과 - -작업 규모에 맞는 개발 경로를 얻게 됩니다. 가장 안전하고 단순한 변경은 직접 편집하고 세션 하나로 처리할 작업은 사람이 지켜보는 Build를 한 번 실행합니다. 에픽에는 공동 사양과 스토리 기록을 사용하고 여러 에픽으로 구성된 프로젝트에는 전체 프로젝트 계약과 조율 과정을 적용합니다. diff --git a/docs/ko-kr/how-to/customize-bmad.md b/docs/ko-kr/how-to/customize-bmad.md deleted file mode 100644 index 367d4700c4..0000000000 --- a/docs/ko-kr/how-to/customize-bmad.md +++ /dev/null @@ -1,399 +0,0 @@ ---- -title: 'BMad 커스터마이징 방법' -description: 업데이트 호환성을 유지하면서 에이전트와 워크플로를 커스터마이징합니다 -sidebar: - order: 5 ---- - -설치된 파일은 그대로 둔 채 에이전트 페르소나를 조정하고 도메인 컨텍스트와 기능을 추가하며 워크플로 동작을 설정하세요. 커스터마이징은 업데이트 후에도 유지됩니다. - -:::tip[TOML을 직접 쓰고 싶지 않나요? `bmad-customize`를 사용하세요] -`bmad-customize` 스킬은 이 문서에서 설명하는 **스킬별 에이전트/워크플로 오버라이드 영역**을 단계별로 작성하도록 돕습니다. 먼저 설치된 항목을 스캔해 커스터마이즈할 수 있는 범위를 찾고 의도에 맞는 영역(에이전트 또는 워크플로)을 선택하도록 안내합니다. 이어서 오버라이드 파일을 작성하고 병합 결과까지 검증합니다. 중앙 설정 오버라이드(`_bmad/custom/config.toml`)는 v1 범위에 포함되지 않으므로 아래 중앙 설정 섹션에 따라 직접 작성하세요. 스킬별 항목을 바꿀 때마다 이 스킬을 실행하세요. 각 영역에서 제공하는 항목과 병합 방식은 이 문서를 참고하면 됩니다. -::: - -## 사용 시점 - -- 에이전트의 성격이나 커뮤니케이션 스타일을 바꾸고 싶을 때 -- 에이전트가 계속 기억해야 할 사실이 있을 때(예: "우리 조직은 AWS만 사용") -- 매 세션 시작 시 에이전트가 반드시 수행해야 하는 절차적 단계를 추가하고 싶을 때 -- 자체 스킬이나 프롬프트를 실행하는 커스텀 메뉴 항목을 추가하고 싶을 때 -- 팀 공통 커스터마이징은 git에 커밋하고 개인 선호를 그 위에 적용하고 싶을 때 - -:::note[필수 조건] - -- 프로젝트에 BMad 설치([BMad 설치 방법](../start/install-bmad.md) 참고) -- PATH에서 실행 가능한 [`uv`](https://docs.astral.sh/uv/). BMad는 `uv run`으로 해석 스크립트를 실행합니다. `uv`가 적합한 Python을 준비하므로 Python을 직접 설치할 필요가 없습니다. 스크립트는 표준 라이브러리의 `tomllib`만 사용하므로 `pip install`할 항목도 없습니다 -- TOML 파일을 편집할 텍스트 에디터 -::: - -## 작동 방식 - -커스터마이즈 가능한 모든 스킬은 기본값이 들어 있는 `customize.toml` 파일을 제공합니다. 이 파일은 스킬의 전체 커스터마이징 영역을 정의합니다. 무엇을 바꿀 수 있는지 보려면 이 파일을 읽으세요. 이 파일은 직접 편집하지 않습니다. 대신 바꾸려는 필드만 담은 오버라이드 파일을 만듭니다. - -### 3계층 오버라이드 모델 - -```text -우선순위 1(승리): _bmad/custom/{skill-name}.user.toml (개인, git 무시) -우선순위 2: _bmad/custom/{skill-name}.toml (팀/조직, 커밋) -우선순위 3(마지막): 스킬 자체 customize.toml (기본값) -``` - -`_bmad/custom/` 폴더는 처음엔 비어 있습니다. 누군가 실제로 커스터마이즈할 때만 파일이 생깁니다. - -### 병합 규칙(필드명이 아니라 모양 기준) - -병합 스크립트는 네 가지 구조 규칙을 적용합니다. 필드명을 따로 취급하지 않으며 값의 구조에 따라 동작합니다. - -| 모양 | 규칙 | -| --- | --- | -| 스칼라 값(문자열, 정수, 불리언, 실수) | 오버라이드가 이깁니다 | -| 테이블 | 깊은 병합(재귀적으로 이 규칙을 적용) | -| 모든 항목이 **같은** 식별자 필드(`code` 또는 `id`)를 공유하는 테이블 배열 | 해당 키로 병합합니다. 같은 키는 **제자리에서 교체**, 새 키는 **추가**됩니다 | -| 그 밖의 배열(스칼라 값, 식별자가 없는 테이블, `code`와 `id`가 섞인 배열) | **추가**됩니다. 기본값, 팀, 사용자 항목 순으로 이어 붙입니다 | - -**삭제 메커니즘은 없습니다.** 오버라이드는 기본값 항목을 지울 수 없습니다. 기본 메뉴 항목을 숨겨야 한다면 같은 `code`로 동작 없는 설명이나 프롬프트를 넣어 덮어쓰세요. 배열을 더 깊게 재구성해야 한다면 스킬을 포크하세요. - -**`code` / `id` 관례.** BMad는 테이블 배열의 병합 키로 `code`(예: `"BP"`, `"R1"` 같은 짧은 식별자)와 `id`(더 긴 안정 식별자)를 사용합니다. 직접 만든 테이블 배열이 추가 전용이 아니라 키로 교체 가능해야 한다면 한 가지 관례만 고르고 전체 배열에서 일관되게 사용하세요. 일부 항목은 `code`, 일부 항목은 `id`를 쓰면 키 병합 대신 추가 방식으로 처리됩니다. - -### 일부 에이전트 필드는 읽기 전용입니다 - -`agent.name`과 `agent.title`은 기준 메타데이터로 `customize.toml`에 있지만 에이전트의 SKILL.md는 런타임에 이를 읽지 않습니다. 정체성은 하드코딩되어 있습니다. 오버라이드 파일에 `name = "Bob"`을 넣어도 효과가 없습니다. 정말 다른 이름의 에이전트가 필요하다면 스킬 폴더를 복사해 이름을 바꾸고 커스텀 스킬로 배포하세요. - -## 단계 - -### 1. 스킬의 커스터마이징 영역 찾기 - -설치된 디렉터리에서 스킬의 `customize.toml`을 확인합니다. PM 에이전트 예: - -```text -.claude/skills/bmad-agent-pm/customize.toml -``` - -경로는 IDE별로 다릅니다. Cursor는 `.cursor/skills/`, Cline은 `.cline/skills/`를 사용합니다. - -이 파일이 기준 스키마입니다. 읽기 전용 정체성 필드를 제외하고 보이는 모든 필드는 커스터마이즈할 수 있습니다. - -### 2. 오버라이드 파일 만들기 - -프로젝트 루트에 `_bmad/custom/` 디렉터리가 없다면 만듭니다. 그런 다음 스킬 이름을 딴 파일을 만듭니다. - -```text -_bmad/custom/ - bmad-agent-pm.toml # 팀 오버라이드(git에 커밋) - bmad-agent-pm.user.toml # 개인 선호(git에서 무시) -``` - -:::caution[전체 `customize.toml`을 복사하지 마세요] -오버라이드 파일은 **희소**합니다. 바꾸는 필드만 포함하세요. 생략한 필드는 아래 계층에서 자동으로 상속됩니다. 팀 파일은 기본값에서, 사용자 파일은 팀 또는 기본값에서 상속합니다. - -전체 `customize.toml`을 오버라이드로 복사하면 다음 업데이트에서 문제가 생깁니다. 새 기본값이 제공되어도 오버라이드 파일이 옛 값을 고정하므로 릴리스마다 조용히 어긋납니다. -::: - -**예시 - 아이콘을 바꾸고 원칙 하나 추가:** - -```toml -# _bmad/custom/bmad-agent-pm.toml -# 바꾸는 필드만 둡니다. 나머지는 모두 상속됩니다. - -[agent] -icon = "🏥" -principles = [ - "FDA 감사를 통과할 수 없는 것은 출시하지 않습니다.", -] -``` - -이 설정은 새 원칙을 기본값에 추가하고(제공된 원칙은 그대로 유지), 아이콘을 교체합니다. 나머지 필드는 제공된 값으로 남습니다. - -### 3. 필요한 항목 커스터마이즈하기 - -아래 예시는 BMad의 중첩 없는 에이전트 스키마를 가정합니다. 필드는 `[agent]` 아래에 직접 위치하며 중첩된 `metadata`나 `persona` 하위 테이블은 없습니다. - -**스칼라 값(`icon`, `role`, `identity`, `communication_style`).** 스칼라 값 오버라이드가 이깁니다. 바꾸는 필드만 설정하면 됩니다. - -```toml -# _bmad/custom/bmad-agent-pm.toml - -[agent] -icon = "🏥" -role = "규제 대상 헬스케어 분야에서 제품 기획을 위한 탐색을 이끕니다." -communication_style = "정밀하고 규제를 의식하며, 초반부터 컴플라이언스 관점의 질문을 던집니다." -``` - -**지속 사실, 원칙, 활성화 후크(추가 배열).** 아래 네 배열은 추가 전용입니다. 팀 항목은 기본값 뒤에 실행되고 사용자 항목은 마지막에 실행됩니다. - -```toml -[agent] -# 에이전트가 세션 내내 염두에 둘 정적 사실입니다. 조직 규칙, 도메인 -# 상수, 사용자 선호 등이 여기에 들어갑니다. 런타임 메모리 사이드카와는 다릅니다. -# -# 각 항목은 문장 그대로이거나, 내용을 사실로 로드하는 `file:` 참조입니다 -# glob 패턴도 지원합니다. -persistent_facts = [ - "우리 조직은 AWS만 사용합니다. GCP나 Azure를 제안하지 마세요.", - "모든 PRD는 엔지니어링 착수 전에 법무 승인을 받아야 합니다.", - "대상 사용자는 환자가 아니라 임상의입니다. 예시도 그에 맞춰 구성하세요.", - "file:{project-root}/docs/compliance/hipaa-overview.md", - "file:{project-root}/_bmad/custom/company-glossary.md", -] - -# 에이전트의 가치 체계에 추가합니다 -principles = [ - "FDA 감사를 통과할 수 없는 것은 출시하지 않습니다.", - "사용자 가치를 먼저, 컴플라이언스는 항상 지킵니다.", -] - -# 표준 활성화(페르소나, persistent_facts, 설정, 인사) 전에 실행합니다. -# 에이전트가 자신을 소개하기 전에 불러와야 하는 자료나 -# 컴플라이언스 검사 등에 사용합니다. -activation_steps_prepend = [ - "{project-root}/docs/compliance/를 스캔하고 HIPAA 관련 문서를 컨텍스트로 로드하세요.", -] - -# 인사 후, 메뉴 전에 실행합니다. 사용자에게 먼저 인사한 뒤 처리해도 되는 -# 컨텍스트가 많은 설정에 사용합니다. -activation_steps_append = [ - "{project-root}/_bmad/custom/company-glossary.md가 있으면 읽으세요.", -] -``` - -두 후크는 역할이 다릅니다. Prepend는 인사 전에 실행되므로 인사를 개인화하는 데 필요한 컨텍스트를 먼저 불러올 수 있습니다. Append는 인사 후에 실행됩니다. 시간이 오래 걸리는 스캔 중에도 사용자가 빈 화면을 보고 기다리지 않게 합니다. - -**메뉴 커스터마이징(`code`로 병합).** 메뉴는 테이블 배열입니다. 각 항목에는 `code` 필드가 있으므로 병합 스크립트는 코드로 병합합니다. 같은 코드는 제자리에서 교체되고 새 코드는 추가됩니다. - -TOML 테이블 배열 문법은 항목마다 `[[agent.menu]]`를 사용합니다. - -```toml -# 기존 CE 항목을 커스텀 스킬로 교체 -[[agent.menu]] -code = "CE" -description = "우리 전달 프레임워크로 에픽 생성" -skill = "custom-create-epics" - -# 새 항목 추가(기본값에는 RC 코드가 없음) -[[agent.menu]] -code = "RC" -description = "컴플라이언스 사전 점검 실행" -prompt = """ -{project-root}/_bmad/custom/compliance-checklist.md를 읽고 -{planning_artifacts}의 모든 문서를 그 기준에 맞춰 스캔하세요. -누락된 부분이 있으면 관련 규제 조항을 인용해 보고하세요. -""" -``` - -각 메뉴 항목에는 `skill`(등록된 스킬 호출)과 `prompt`(텍스트 직접 실행) 중 하나만 넣습니다. 오버라이드에 나열하지 않은 항목은 기본값을 유지합니다. - -**파일 참조.** `persistent_facts`, `activation_steps_prepend`/`activation_steps_append`, 메뉴 항목의 `prompt`처럼 텍스트가 파일을 가리켜야 할 때는 `{project-root}`를 기준으로 한 전체 경로를 사용하세요. 파일이 `_bmad/custom/`에서 오버라이드 옆에 있더라도 `{project-root}/_bmad/custom/info.md`처럼 전체 경로를 적습니다. 에이전트는 런타임에 `{project-root}`를 해석합니다. - -### 4. 개인 vs 팀 - -**팀 파일**(`bmad-agent-pm.toml`): git에 커밋합니다. 조직 전체에 공유됩니다. 컴플라이언스 규칙, 회사 페르소나, 커스텀 기능에 사용합니다. - -**개인 파일**(`bmad-agent-pm.user.toml`): 자동으로 git에서 무시됩니다. 말투 조정, 개인 워크플로 선호 사항, 에이전트가 기억해야 하는 개인 사실에 사용합니다. - -```toml -# _bmad/custom/bmad-agent-pm.user.toml - -[agent] -persistent_facts = [ - "선택지를 제시할 때 항상 대략적인 복잡도 추정(낮음/중간/높음)을 포함하세요.", -] -``` - -## 해석이 작동하는 방식 - -에이전트가 활성화되면 SKILL.md가 공유 Python 스크립트를 실행합니다. 이 스크립트는 3계층을 병합한 뒤 해석된 블록을 JSON으로 반환합니다. 외부 의존성 없이 Python 표준 라이브러리의 `tomllib`만 사용합니다. BMad는 이 스크립트를 `uv run`으로 실행합니다. 이때 `uv`가 적합한 Python을 준비합니다. - -```bash -uv run {project-root}/_bmad/scripts/resolve_customization.py \ - --skill {skill-root} \ - --project-root {project-root} \ - --key agent -``` - -**요구사항**: 이 스크립트를 실행하려면 `uv`가 필요합니다. `pip install`할 항목은 없습니다. 스크립트 헤더에 `requires-python = ">=3.11"`을 선언한 이유는 Python 3.11 이전 버전에 `tomllib`이 없기 때문입니다. `uv run`은 이 선언을 읽고 조건에 맞는 인터프리터를 준비하므로 PATH의 `python3` 버전과는 무관합니다. `python3`로 직접 실행하려면 먼저 버전을 확인하세요. Homebrew가 없는 macOS나 Ubuntu 22.04 같은 환경에서는 기본 `python3`이 3.10 이하일 수 있습니다. - -`--skill`은 스킬이 설치된 디렉터리(`customize.toml`이 있는 위치)를 가리킵니다. 디렉터리의 basename을 스킬 이름으로 사용하며 스크립트는 `_bmad/custom/{skill-name}.toml`과 `{skill-name}.user.toml`을 자동으로 찾습니다. - -유용한 호출: - -```bash -# 전체 에이전트 블록 해석 -uv run {project-root}/_bmad/scripts/resolve_customization.py \ - --skill /abs/path/to/bmad-agent-pm \ - --project-root {project-root} \ - --key agent - -# 단일 필드 해석 -uv run {project-root}/_bmad/scripts/resolve_customization.py \ - --skill /abs/path/to/bmad-agent-pm \ - --project-root {project-root} \ - --key agent.icon - -# 전체 덤프 -uv run {project-root}/_bmad/scripts/resolve_customization.py \ - --skill /abs/path/to/bmad-agent-pm \ - --project-root {project-root} -``` - -출력은 항상 JSON입니다. 특정 플랫폼에서 스크립트를 사용할 수 없다면 SKILL.md는 에이전트에게 세 TOML 파일을 직접 읽고 같은 병합 규칙을 적용하라고 지시합니다. - -## 워크플로 커스터마이징 - -`bmad-product-brief`처럼 여러 단계로 진행되는 워크플로(스킬)도 에이전트와 같은 오버라이드 메커니즘을 공유합니다. 커스터마이즈 가능한 영역은 `[agent]` 대신 `[workflow]` 아래에 있습니다. - -```toml -# _bmad/custom/bmad-product-brief.toml - -[workflow] -# 에이전트와 같은 prepend/append 의미를 사용합니다. 워크플로 자체 활성화 -# 단계 전후에 실행되며, 오버라이드 항목은 기본값 뒤에 추가됩니다. -activation_steps_prepend = [ - "{project-root}/docs/product/north-star-principles.md를 컨텍스트로 불러오세요.", -] - -activation_steps_append = [] - -# 에이전트 변형과 같은 리터럴 또는 file: 의미를 사용합니다. 워크플로 실행 -# 동안 기본 컨텍스트로 불러옵니다. -persistent_facts = [ - "모든 개요에는 명시적인 규제 위험 섹션이 포함되어야 합니다.", - "file:{project-root}/docs/compliance/product-brief-checklist.md", -] - -# 스칼라 값입니다. 워크플로가 주요 출력을 마친 뒤 한 번 실행되며 오버라이드가 우선합니다. -on_complete = "개요를 세 개의 글머리표로 요약하고 gws-gmail-send 스킬로 이메일 발송을 제안하세요." -``` - -필드 규칙은 에이전트와 워크플로에 똑같이 적용됩니다. `activation_steps_prepend`/`activation_steps_append`, `persistent_facts`(`file:` 참조 포함), 키 병합에 `code`/`id`를 사용하는 메뉴 형식의 `[[…]]` 테이블도 같은 방식으로 동작합니다. 병합 스크립트는 최상위 키와 상관없이 네 가지 구조 규칙을 적용합니다. SKILL.md 참조에서는 `{workflow.activation_steps_prepend}`, `{workflow.persistent_facts}`, `{workflow.on_complete}`처럼 네임스페이스를 사용합니다. 출력 경로, 토글, 리뷰 설정, 단계 플래그 같은 추가 필드도 값의 구조에 따라 병합합니다. 지원하는 항목은 워크플로의 `customize.toml`에서 확인하세요. - -### 활성화 순서 - -커스터마이즈 가능한 워크플로는 후크가 언제 실행되는지 알 수 있도록 고정된 순서로 활성화됩니다. - -1. `[workflow]` 블록 해석(기본값 → 팀 → 사용자 병합) -2. `activation_steps_prepend`를 순서대로 실행 -3. 실행 내내 참고할 컨텍스트로 `persistent_facts` 로드 -4. 설정(`_bmad/bmm/config.yaml`) 로드 및 표준 변수(프로젝트 이름, 언어, 경로, 날짜) 해석 -5. 사용자에게 인사 -6. `activation_steps_append`를 순서대로 실행 - -6단계가 끝나면 워크플로 본문이 시작됩니다. 인사를 개인화하기 전에 컨텍스트가 필요하면 `activation_steps_prepend`를 사용하세요. 설정 작업이 무겁고 사용자에게 인사를 먼저 보여주고 싶다면 `activation_steps_append`를 사용하세요. - -### 현재 초기 단계의 범위 - -커스터마이징은 점진적으로 출시됩니다. 위에서 문서화한 `activation_steps_prepend`, `activation_steps_append`, `persistent_facts`, `on_complete`는 모든 커스터마이즈 가능한 워크플로가 제공하는 **기본 영역**이며 버전 간 안정적으로 유지됩니다. 현재는 사전·사후 단계 추가, 기본 컨텍스트 고정, 후속 작업 실행처럼 큰 단위로 동작을 제어할 수 있습니다. - -앞으로는 개별 워크플로의 실제 동작에 맞춘 **더 세밀한 커스터마이징 지점**도 제공할 예정입니다. 단계별 토글, 단계 플래그, 출력 템플릿 경로, 리뷰 게이트 등이 여기에 해당합니다. 이런 항목은 기준 필드를 대체하지 않고 그 위에 추가되므로 지금 작성한 커스터마이징도 계속 동작합니다. - -아직 노출되지 않은 세밀한 조절점이 필요하다면 `activation_steps_*`와 `persistent_facts`로 동작을 조정하거나, 원하는 커스터마이징 지점을 구체적으로 설명하는 이슈를 열어 주세요. - -## 중앙 설정 - -스킬별 `customize.toml`은 **세부 동작**(후크, 메뉴, persistent_facts, 단일 에이전트/워크플로의 페르소나 오버라이드)을 다룹니다. 이와 별도로 설치 답변과 에이전트 명단 같은 **공유 상태**를 관리하는 영역이 있습니다. 이 명단은 `bmad-party-mode`, `bmad-retrospective`, `bmad-advanced-elicitation` 같은 외부 스킬이 사용합니다. 중앙 설정은 프로젝트 루트의 TOML 파일 네 개에 나뉘어 있습니다. - -```text -_bmad/config.toml (설치 프로그램 소유) 팀 범위: 설치 답변 + 에이전트 명단 -_bmad/config.user.toml (설치 프로그램 소유) 사용자 범위: user_name, 언어, 스킬 수준 -_bmad/custom/config.toml (사람이 작성) 팀 오버라이드(git에 커밋) -_bmad/custom/config.user.toml (사람이 작성) 개인 오버라이드(git에서 무시) -``` - -### 4계층 병합 - -```text -우선순위 1(승리): _bmad/custom/config.user.toml -우선순위 2: _bmad/custom/config.toml -우선순위 3: _bmad/config.user.toml -우선순위 4(기반): _bmad/config.toml -``` - -스킬별 커스터마이징과 같은 구조 규칙을 사용합니다. 스칼라 값은 덮어쓰고 테이블은 깊게 병합하며 `code`/`id` 키가 있는 배열은 키로 병합합니다. 그 밖의 배열은 이어 붙입니다. - -### 무엇이 어디에 있나요? - -설치 프로그램은 `module.yaml`의 각 프롬프트에 선언된 `scope:`에 따라 답변을 나눕니다. - -- `[core]`와 `[modules.]` 섹션 - 설치 답변입니다. `team` 범위는 `_bmad/config.toml`에, `user` 범위는 `_bmad/config.user.toml`에 들어갑니다. -- `[agents.]` - 각 모듈의 `module.yaml` `agents:` 블록에서 추출한 에이전트 핵심 정보(코드, 이름, 직함, 아이콘, 설명, 팀)입니다. 항상 팀 범위입니다. - -### 편집 규칙 - -- `_bmad/config.toml`과 `_bmad/config.user.toml`은 **설치할 때마다 재생성**됩니다. 읽기 전용 출력으로 취급하세요. 직접 수정하면 다음 설치에서 덮어쓰입니다. 설치 답변을 지속적으로 바꾸려면 설치 프로그램을 다시 실행하거나 `_bmad/custom/config.toml`에서 값을 덮어쓰세요. -- `_bmad/custom/config.toml`과 `_bmad/custom/config.user.toml`은 설치 프로그램이 **절대 건드리지 않습니다**. 커스텀 에이전트, 에이전트 설명자 오버라이드, 팀 강제 설정, 설치 답변과 무관하게 고정하려는 값은 이 파일에 넣으세요. - -### 예시 - 에이전트 리브랜딩 - -```toml -# _bmad/custom/config.toml (git에 커밋, 모든 개발자에게 적용) - -[agents.bmad-agent-pm] -description = "헬스케어 PM - 규제를 의식하고 이해관계자 중심이며, FDA 관점의 질문을 먼저 던집니다." -icon = "🏥" -``` - -병합 스크립트는 설치 프로그램이 작성한 `[agents.bmad-agent-pm]` 항목에 이 설정을 병합합니다. `bmad-party-mode`와 명단을 사용하는 스킬은 새 설명을 자동으로 사용합니다. - -### 예시 - 가상 에이전트 추가 - -```toml -# _bmad/custom/config.user.toml (개인용, git에서 무시) - -[agents.kirk] -team = "startrek" -name = "Captain James T. Kirk" -title = "우주선 선장" -icon = "🖖" -description = "대담하고 규칙을 굽힐 줄 아는 지휘관입니다. 극적으로 뜸을 들여 말하며 지휘의 무게에 관한 생각을 입 밖으로 꺼냅니다." -``` - -스킬 폴더가 없어도 이 정보만으로 파티 모드에서 Kirk를 독립된 목소리로 구현할 수 있습니다. `team` 필드로 필터링해 엔터프라이즈 승무원만 원탁 토론에 초대할 수도 있습니다. - -### 예시 - 모듈 설치 설정 오버라이드 - -```toml -# _bmad/custom/config.toml - -[modules.bmm] -planning_artifacts = "/shared/org-planning-artifacts" -``` - -오버라이드는 각 개발자가 로컬 설치 중 답한 값보다 우선합니다. 팀 관례를 고정할 때 유용합니다. - -### 어떤 영역을 사용할까요? - -| 필요 | 사용 | -| --- | --- | -| 모든 개발 워크플로에 MCP 도구 호출 추가 | 스킬별: `_bmad/custom/bmad-agent-dev.toml` `persistent_facts` | -| 에이전트에 메뉴 항목 추가 | 스킬별: `_bmad/custom/bmad-agent-{role}.toml` `[[agent.menu]]` | -| 워크플로의 출력 템플릿 교체 | 스킬별: `_bmad/custom/{workflow}.toml` 스칼라 값 오버라이드 | -| 에이전트 공개 설명자 리브랜딩 | **중앙**: `_bmad/custom/config.toml` `[agents.]` | -| 커스텀 또는 가상 에이전트를 명단에 추가 | **중앙**: `_bmad/custom/config.*.toml` 새 `[agents.]` 항목 | -| 팀 강제 설치 설정 고정 | **중앙**: `_bmad/custom/config.toml` `[modules.]` 또는 `[core]` | - -필요에 따라 한 프로젝트에서 두 영역을 함께 사용하세요. - -## 실전 예시 - -에이전트가 실행하는 모든 워크플로의 동작을 조정하거나 조직 관례를 강제하고 싶다면 [조직을 위해 BMad 확장하기](./expand-bmad-for-your-org.md)를 참고하세요. Confluence와 Jira에 결과를 게시하고 에이전트 명단을 커스터마이즈하며 출력 템플릿을 교체하는 방법도 설명합니다. - -## 문제 해결 - -**커스터마이징이 보이지 않나요?** - -- 파일이 `_bmad/custom/`에 올바른 스킬 이름으로 있는지 확인하세요 -- TOML 문법을 확인하세요. 문자열에는 따옴표가 필요합니다. 테이블 헤더는 `[section]`, 테이블 배열은 `[[section]]`입니다. 테이블의 스칼라 값 또는 배열 키는 해당 테이블의 `[[subtables]]`보다 먼저 와야 합니다 -- 에이전트의 경우 커스터마이징은 `[agent]` 아래에 있습니다. 그 헤더 아래에 쓴 필드는 다른 테이블 헤더가 시작될 때까지 `agent`에 속합니다 -- `agent.name`과 `agent.title`은 읽기 전용입니다. 오버라이드해도 효과가 없습니다 - -**업데이트가 커스터마이징을 망가뜨렸나요?** - -- 전체 `customize.toml`을 오버라이드 파일에 복사했나요? **하지 마세요.** 오버라이드 파일은 바꾸는 필드만 포함해야 합니다. 전체 복사는 옛 기본값을 고정하고 릴리스마다 조용히 어긋납니다. 오버라이드를 변경분만 남기도록 줄이세요. - -**커스터마이즈 가능한 항목을 확인하고 싶나요?** - -- `bmad-customize` 스킬을 실행하세요. 프로젝트에 설치된 커스터마이즈 가능한 스킬을 모두 보여주고, 기존 오버라이드를 확인한 뒤 추가 또는 업데이트 과정을 안내합니다 -- 또는 스킬의 `customize.toml`을 직접 읽으세요. `name`과 `title`을 제외하고 모든 필드가 커스터마이즈 가능합니다 - -**초기화가 필요하나요?** - -- `_bmad/custom/`에서 오버라이드 파일을 삭제하세요. 스킬은 내장 기본값으로 돌아갑니다 diff --git a/docs/ko-kr/how-to/established-projects.md b/docs/ko-kr/how-to/established-projects.md deleted file mode 100644 index 461bf2fb70..0000000000 --- a/docs/ko-kr/how-to/established-projects.md +++ /dev/null @@ -1,111 +0,0 @@ ---- -title: '기존 프로젝트' -description: 기존 코드베이스에서 BMad Method를 사용하는 방법 -sidebar: - order: 4 ---- - -기존 프로젝트와 레거시 코드베이스에서 작업할 때 BMad Method를 효과적으로 사용하세요. - -이 가이드는 BMad Method로 기존 프로젝트에 적응하는 핵심 워크플로를 다룹니다. - -:::note[필수 조건] - -- BMad Method 설치(`npx bmad-method install`) -- 작업하려는 기존 코드베이스 -- AI 기반 IDE(Claude Code 또는 Cursor) 접근 권한 -::: - -## 1단계: 완료된 계획 산출물 정리 - -BMad 과정으로 모든 PRD 에픽과 스토리를 완료했다면 해당 파일을 정리하세요. 필요하다면 보관하거나 삭제하거나 버전 기록에 의존하세요. 다음 위치에 이 파일들을 계속 두지 마세요. - -- `docs/` -- `_bmad-output/planning-artifacts/` -- `_bmad-output/implementation-artifacts/` - -## 2단계: 프로젝트 컨텍스트 만들기 - -:::tip[기존 프로젝트에 권장] -프로젝트 컨텍스트 시스템을 구축해 변경을 구현하는 AI 에이전트가 기존 관례를 따르게 하세요. 기존 프로젝트에서 BMad를 시작하는 권장 경로입니다. -::: - -프로젝트 컨텍스트 스킬을 실행합니다. - -```bash -bmad-project-context -``` - -이 스킬은 기존 자료를 읽고 현재 상태를 평가한 뒤 에이전트가 지켜야 할 규칙을 묻습니다. 나머지 정보는 직접 찾아 검증하며, 명령은 기록하기 전에 모두 실행해 확인합니다. 생성 문서를 늘리지 않고 저장소의 `AGENTS.md`에 간결하고 검증된 규칙 블록을 작성합니다. 사람이 직접 관리해 온 파일은 개선할 기준으로 삼고, 비대한 `docs/` 폴더는 내용을 더 보태지 않은 채 코드와 대조할 자료로 사용합니다. - -[프로젝트 컨텍스트 자세히 알아보기](../explanation/project-context.md) - -## 3단계: 품질 높은 프로젝트 문서 유지 - -`docs/` 폴더에는 프로젝트를 정확하게 나타내는 간결하고 잘 구성된 문서가 있어야 합니다. - -- 의도와 비즈니스 근거 -- 비즈니스 규칙 -- 아키텍처 -- 그 밖의 관련 프로젝트 정보 - -`bmad-project-context`는 이 가운데 에이전트가 읽는 부분을 감사하고 유지합니다. 컨텍스트가 오래됐다고 느껴지면 감사를 실행하세요. 내용을 계속 쌓는 대신 줄이고 다시 검증합니다. 이전 `bmad-document-project` 워크플로는 더 이상 사용하지 않으며 이 스킬로 연결됩니다. - -## 4단계: 도움 받기 - -### BMad 도움말: 시작점 - -**다음에 무엇을 해야 할지 확실하지 않을 때 언제든 `bmad-help`를 실행하세요.** 이 지능형 가이드는 다음을 수행합니다. - -- 프로젝트를 검사해 이미 완료된 작업을 확인합니다 -- 설치된 모듈을 기준으로 선택지를 보여줍니다 -- 자연어 질문을 이해합니다 - -``` -bmad-help 기존 Rails 앱이 있는데 어디서 시작하면 좋나요? -bmad-help 이 변경을 구현하기 전에 계획이 얼마나 필요한가요? -bmad-help 사용할 수 있는 워크플로를 보여 주세요 -``` - -BMad 도움말은 **모든 워크플로 끝에서 자동으로 실행되어** 다음에 무엇을 해야 할지 명확히 안내합니다. - -### 계획 깊이 선택 - -모든 구현에는 `bmad-build`를 사용합니다. 범위에 따라 먼저 준비할 컨텍스트가 달라집니다. - -| 범위 | 권장 준비 사항 | -| --- | --- | -| **명확한 업데이트나 추가** | 요청, 이슈 또는 기존 사양을 전달해 `bmad-build`로 바로 시작합니다. | -| **큰 변경이나 추가** | 필요한 PRD, UX, 아키텍처, 에픽, 스토리, 준비 상태, 스프린트 컨텍스트를 마련한 다음 선택한 작업을 `bmad-build`에 전달합니다. | - -### PRD 작성 중 - -제품 개요를 만들거나 바로 PRD로 들어갈 때 에이전트가 다음을 하도록 확인하세요. - -- 기존 프로젝트 문서를 찾고 분석합니다 -- 현재 시스템에 대한 적절한 컨텍스트를 읽습니다 - -에이전트에게 구체적으로 지시할 수도 있습니다. 다만 새 기능이 기존 시스템과 자연스럽게 맞물려야 합니다. - -### UX 고려 사항 - -UX 작업은 선택 사항입니다. 결정 기준은 프로젝트에 UX가 있는지가 아니라 다음입니다. - -- UX 변경을 작업할 예정인지 -- 의미 있는 새 UX 디자인이나 패턴이 필요한지 - -만족스러운 기존 화면을 단순히 업데이트하는 정도라면 전체 UX 과정은 필요하지 않습니다. - -### 아키텍처 고려 사항 - -아키텍처를 진행할 때 아키텍트가 다음을 하도록 확인하세요. - -- 적절한 문서 파일을 사용합니다 -- 기존 코드베이스를 스캔합니다 - -여기서는 특히 주의하세요. 이미 있는 것을 다시 만들거나 기존 아키텍처와 어긋나는 결정을 방지해야 합니다. - -## 더 보기 - -- **[변경 사항 구현하기](../build/build-a-change.md)** - 요청, 이슈, 사양 또는 스토리를 사람이 살펴보며 구현 -- **[기존 프로젝트 FAQ](../explanation/established-projects-faq.md)** - 기존 프로젝트 작업에 대한 일반 질문 diff --git a/docs/ko-kr/how-to/expand-bmad-for-your-org.md b/docs/ko-kr/how-to/expand-bmad-for-your-org.md deleted file mode 100644 index 41cf371e8a..0000000000 --- a/docs/ko-kr/how-to/expand-bmad-for-your-org.md +++ /dev/null @@ -1,332 +0,0 @@ ---- -title: '조직을 위해 BMad 확장하기' -description: 포크 없이 BMad를 재구성하는 여섯 가지 커스터마이징 패턴 - 에이전트 전반 규칙, 워크플로 관례, 외부 게시, 템플릿 교체, 에이전트 명단 변경, 고급 통합 패턴 -sidebar: - order: 7 ---- - -BMad의 커스터마이징 영역을 사용하면 설치된 파일을 수정하거나 스킬을 포크하지 않고도 조직에 맞게 동작을 바꿀 수 있습니다. 이 가이드는 대부분의 엔터프라이즈 요구를 다루는 여섯 가지 레시피를 소개합니다. - -:::note[필수 조건] - -- 프로젝트에 BMad 설치([BMad 설치 방법](../start/install-bmad.md) 참고) -- 커스터마이징 모델 이해([BMad 커스터마이징 방법](./customize-bmad.md) 참고) -- PATH의 Python 3.11+(병합 스크립트용, stdlib만 사용하며 `pip install` 불필요) -::: - -:::tip[이 레시피 적용하기] -아래 **스킬별 레시피**(레시피 1-4)는 `bmad-customize` 스킬을 실행하고 의도를 설명해 적용할 수 있습니다. 스킬이 알맞은 영역을 고르고 오버라이드 파일을 작성한 뒤 병합 결과를 검증합니다. 레시피 5처럼 에이전트 명단을 바꾸는 중앙 설정 오버라이드는 v1 스킬 범위 밖이므로 직접 작성해야 합니다. 이 문서의 레시피는 *무엇을* 오버라이드할지 정하는 기준을 제공합니다. `bmad-customize`는 에이전트와 워크플로 영역에서 이를 *어떻게* 적용할지 안내합니다. -::: - -## 3계층 모델 - -레시피를 고르기 전에 오버라이드가 어디에 들어가는지 알아두세요. - -| 계층 | 오버라이드 위치 | 범위 | -| --- | --- | --- | -| **에이전트**(예: Amelia, Mary, John) | `_bmad/custom/bmad-agent-{role}.toml`의 `[agent]` 섹션 | 에이전트가 실행하는 **모든 워크플로**에 페르소나와 함께 이동 | -| **워크플로**(예: 제품 개요, PRD 생성) | `_bmad/custom/{workflow-name}.toml`의 `[workflow]` 섹션 | 해당 워크플로 실행에만 적용 | -| **중앙 설정** | `_bmad/custom/config.toml`의 `[agents.*]`, `[core]`, `[modules.*]` | 에이전트 명단(파티 모드, 회고, 도출에서 누가 가능한지), 조직 전체로 고정된 설치 시 설정 | - -경험칙: 규칙이 엔지니어의 모든 개발 작업에 적용되어야 한다면 **개발자 에이전트**를 커스터마이즈하세요. 제품 개요를 쓸 때만 적용된다면 **제품 개요 워크플로**를 커스터마이즈하세요. *방에 누가 있는지*를 바꾸는 일(에이전트 이름 변경, 커스텀 목소리 추가, 공유 산출물 경로 강제)은 **중앙 설정**을 편집하세요. - -## 레시피 1: 에이전트가 실행하는 모든 워크플로에 규칙 적용 - -**사용 사례:** 에이전트가 실행하는 모든 워크플로가 같은 도구 사용 규칙과 외부 시스템 통합 규칙을 상속하도록 표준화합니다. 가장 영향력이 큰 패턴입니다. - -**예시: Amelia 개발자 에이전트가 라이브러리 문서는 항상 Context7을 사용하고, 에픽 목록에 스토리가 없으면 Linear를 대체 경로로 사용합니다.** - -```toml -# _bmad/custom/bmad-agent-dev.toml - -[agent] - -# 활성화할 때마다 적용됩니다. Amelia가 실행하는 모든 스킬인 -# build, code-review, qa-generate에서도 이어서 적용됩니다. -persistent_facts = [ - "React, TypeScript, Zod, Prisma 등의 라이브러리 문서를 찾을 때는 학습 데이터의 지식에 기대기 전에 context7 MCP 도구(`mcp__context7__resolve_library_id`, 이어서 `mcp__context7__get_library_docs`)를 호출하세요. 기억에 의존한 API 정보보다 최신 문서를 우선하세요.", - "{planning_artifacts}/epics-and-stories.md에서 스토리 참조를 찾지 못하면 사용자에게 확인을 요청하기 전에 스토리 ID나 제목으로 `mcp__linear__search_issues`를 호출해 Linear를 검색하세요. 일치하는 항목이 나오면 해당 항목을 공식 스토리 출처로 사용하세요.", -] -``` - -**왜 동작하나요:** 이 두 문장만으로 조직의 모든 개발 워크플로 동작이 바뀝니다. 워크플로마다 같은 내용을 반복하거나 소스를 수정할 필요가 없습니다. 저장소를 새로 받은 엔지니어도 이 관례를 자동으로 따릅니다. - -**팀 파일 vs 개인 파일:** - -- `bmad-agent-dev.toml`: git에 커밋하고 팀 전체에 적용합니다 -- `bmad-agent-dev.user.toml`: git에서 무시되며 개인 선호를 위에 덧씌웁니다 - -## 레시피 2: 특정 워크플로 안에서 조직 관례 강제 - -**사용 사례:** 워크플로 출력의 *내용*이 컴플라이언스, 감사, 후속 사용자의 요구를 만족하도록 만듭니다. - -**예시: 모든 제품 개요에 컴플라이언스 필드를 넣고, 에이전트가 조직의 게시 관례를 따르게 합니다.** - -```toml -# _bmad/custom/bmad-product-brief.toml - -[workflow] - -persistent_facts = [ - "모든 개요에는 '소유자', '대상 릴리스', '보안 리뷰 상태' 필드가 포함되어야 합니다.", - "비상업용 개요(내부 도구, 리서치 프로젝트)도 사용자 가치 섹션은 포함해야 하지만 시장 차별화는 생략할 수 있습니다.", - "file:{project-root}/docs/enterprise/brief-publishing-conventions.md", -] -``` - -**일어나는 일:** 사실 목록은 워크플로 활성화 3단계에서 로드됩니다. 에이전트가 제품 개요를 작성할 때 필수 필드와 엔터프라이즈 관례 문서를 참고합니다. 기본으로 제공되는 스킬에는 자체 지속 사실이 없으므로 여기에서 지정한 항목만 로드됩니다. 다만 이 키는 교체가 아니라 추가 방식으로 합쳐지므로 팀 수준과 사용자 수준에서 각각 추가한 사실은 모두 적용됩니다. - -## 레시피 3: 완료된 출력을 외부 시스템에 게시 - -**사용 사례:** 워크플로가 출력을 만든 뒤 엔터프라이즈 기록 시스템(Confluence, Notion, SharePoint)에 자동 게시하고 후속 작업(Jira, Linear, Asana)을 엽니다. - -**예시: 제품 개요를 Confluence에 자동 게시하고 선택적으로 Jira 에픽 생성을 제안합니다.** - -```toml -# _bmad/custom/bmad-product-brief.toml - -[workflow] - -# 종료 후크입니다. 스칼라 값 오버라이드는 빈 기본값 전체를 교체합니다. -on_complete = """ -게시하고 후속 작업을 제안하세요: - -1. 이전 단계에서 확정된 개요 파일 경로를 읽습니다. -2. 다음 인자로 `mcp__atlassian__confluence_create_page`를 호출합니다: - - space: "PRODUCT" - - parent: "Product Briefs" - - title: 개요 제목 - - body: 개요의 Markdown 내용 - 반환된 페이지 URL을 기록합니다. -3. 사용자에게 "개요가 Confluence에 게시되었습니다: "이라고 알립니다. -4. "이 개요에 대한 Jira 에픽을 지금 만들까요?"라고 묻습니다. -5. 사용자가 동의하면 다음 인자로 `mcp__atlassian__jira_create_issue`를 호출합니다: - - type: "Epic" - - project: "PROD" - - summary: 개요 제목 - - description: 짧은 요약과 Confluence 페이지 링크 - 에픽 키와 URL을 보고합니다. -6. 동의하지 않으면 깔끔하게 종료합니다. - -어느 MCP 도구든 실패하면 실패를 보고하고 개요 경로를 출력한 뒤 -사용자에게 수동 게시를 요청하세요. -""" -``` - -**왜 `activation_steps_append`가 아니라 `on_complete`인가요:** `on_complete`는 워크플로의 주 출력이 작성된 뒤 마지막 단계에서 정확히 한 번 실행됩니다. 산출물 게시에는 이 시점이 맞습니다. `activation_steps_append`는 워크플로가 일을 시작하기 전에 매 활성화마다 실행됩니다. - -**절충점:** - -- **Confluence 게시 작업은 비파괴적**이며 완료 시 항상 실행됩니다 -- **Jira 에픽 생성은 팀 전체에 보이고 스프린트 계획 신호를 만들기 때문에** 사용자 확인으로 통제합니다 -- **안전한 대체 경로:** MCP 도구가 실패하면 조용히 출력을 버리지 말고 사용자에게 맡깁니다 - -## 레시피 4: 자체 출력 템플릿으로 교체 - -**사용 사례:** 기본 출력 구조가 조직의 예상 형식과 맞지 않거나, 같은 저장소의 서로 다른 조직이 다른 템플릿을 필요로 합니다. - -**예시: product-brief 워크플로가 조직에서 관리하는 템플릿을 사용하도록 합니다.** - -```toml -# _bmad/custom/bmad-product-brief.toml - -[workflow] -brief_template = "{project-root}/docs/enterprise/brief-template.md" -``` - -**작동 방식:** 워크플로의 `customize.toml`은 `brief_template = "resources/brief-template.md"`(스킬 루트 기준 경로)를 제공합니다. 오버라이드는 `{project-root}` 아래 파일을 가리키므로 에이전트는 4단계에서 기본 템플릿 대신 조직의 템플릿을 읽습니다. - -**템플릿 작성 팁:** - -- 템플릿은 `{project-root}/docs/` 또는 `{project-root}/_bmad/custom/templates/`에 두어 오버라이드 파일과 함께 버전 관리합니다 -- 제공된 템플릿과 같은 구조 관례(섹션 헤딩, 프런트매터)를 사용하세요. 에이전트는 그 구조에 적응합니다 -- 다중 조직 저장소에서는 `.user.toml`로 개별 팀이 커밋된 팀 파일을 건드리지 않고 자체 템플릿을 가리키게 할 수 있습니다 - -## 레시피 5: 에이전트 명단 커스터마이즈 - -**사용 사례:** 소스를 수정하거나 포크하지 않고 `bmad-party-mode`, `bmad-retrospective`, `bmad-advanced-elicitation` 같은 명단 기반 스킬에서 *방에 누가 있는지* 바꿉니다. 세 가지 흔한 변형은 다음과 같습니다. - -### 5a. BMad 에이전트를 조직 전체에서 리브랜딩 - -실제 에이전트마다 설치 프로그램이 `module.yaml`에서 합성한 설명자가 있습니다. 이를 오버라이드하면 명단을 사용하는 모든 스킬에서 목소리와 표현 방식을 바꿀 수 있습니다. - -```toml -# _bmad/custom/config.toml (커밋됨 - 모든 개발자에게 적용) - -[agents.bmad-agent-analyst] -description = "규제를 의식하는 비즈니스 분석가 Mary - Porter와 Minto의 사고법을 따르지만 FDA 감사 추적을 중시합니다. 사건 파일을 제시하는 포렌식 조사관처럼 말합니다." -``` - -파티 모드는 새 설명으로 Mary를 생성합니다. 분석가 활성화 자체는 Mary의 동작이 스킬별 `customize.toml`에 있으므로 정상 동작합니다. 이 오버라이드는 **외부 스킬이 Mary를 어떻게 인식하고 소개하는지**를 바꾸며, 내부 작업 방식은 바꾸지 않습니다. - -### 5b. 가상 또는 커스텀 에이전트 추가 - -스킬 폴더 없이 전체 설명자만으로 명단 기반 기능에 충분합니다. 파티 모드나 브레인스토밍 세션에서 페르소나 다양성을 줄 때 유용합니다. - -```toml -# _bmad/custom/config.user.toml (개인용 - git에서 무시) - -[agents.spock] -team = "startrek" -name = "스팍 사령관" -title = "과학 장교" -icon = "🖖" -description = "논리를 우선하고 감정을 억제합니다. 관찰을 '흥미롭군요.'로 시작합니다. 절대 올림하지 않습니다. 직감에 의존하는 주장에 반대 관점을 제공합니다." - -[agents.mccoy] -team = "startrek" -name = "레너드 맥코이 박사" -title = "수석 의무관" -icon = "⚕️" -description = "시골 의사의 따뜻함과 짧은 인내심을 지녔습니다. '제기랄 짐, 난 ___가 아니라 의사라고.' 윤리 중심으로 스팍의 균형을 잡습니다." -``` - -파티 모드에 "엔터프라이즈 승무원을 초대해 줘"라고 요청하면 `team = "startrek"`으로 필터링하고 스팍과 맥코이를 생성합니다. 요청하면 실제 BMad 에이전트(Mary, Amelia)도 같은 테이블에 앉을 수 있습니다. - -### 5c. 팀 설치 설정 고정 - -설치 프로그램은 각 개발자에게 `planning_artifacts` 경로 같은 값을 묻습니다. 조직에서 팀 전체에 같은 값을 적용해야 한다면 중앙 설정에 고정하세요. 각 개발자가 로컬 프롬프트에 입력한 값은 설정을 해석할 때 중앙 설정으로 덮어씁니다. - -```toml -# _bmad/custom/config.toml - -[modules.bmm] -planning_artifacts = "{project-root}/shared/planning" -implementation_artifacts = "{project-root}/shared/implementation" - -[core] -document_output_language = "English" -``` - -`user_name`, `communication_language`, `user_skill_level` 같은 개인 설정은 각 개발자의 `_bmad/config.user.toml` 아래에 둡니다. 팀 파일은 이를 건드리지 않는 것이 좋습니다. - -**왜 중앙 설정인가요:** 에이전트별 파일은 *하나의* 에이전트가 활성화될 때 동작을 조정합니다. 중앙 설정은 명단을 사용하는 스킬이 명단을 조회할 때 *무엇을 보게 되는지*를 조정합니다. 어떤 에이전트가 존재하는지, 무엇이라고 불리는지, 어떤 팀에 속하는지, 저장소가 합의한 공유 설치 설정이 무엇인지입니다. - -## IDE 세션 파일에 전역 규칙 보강 - -BMad 커스터마이징은 스킬이 활성화될 때 로드됩니다. 많은 IDE 도구는 스킬이 실행되기 전 **모든 세션 시작 시** 전역 지침 파일도 로드합니다(`CLAUDE.md`, `AGENTS.md`, `.cursor/rules/`, `.github/copilot-instructions.md` 등). BMad 스킬 밖에서도 지켜져야 하는 규칙은 거기에도 핵심만 반복하세요. - -**중복해 둘 때:** - -- 일반 채팅 대화(활성 스킬 없음)에서도 지켜야 할 만큼 중요한 규칙입니다 -- 학습 데이터 기반 기본값이 모델을 다른 방향으로 끌 수 있어 이중 안전장치가 필요합니다 -- 세션 파일을 부풀리지 않을 만큼 간결한 규칙입니다 - -**예시: 레시피 1의 dev 에이전트 규칙을 저장소의 `CLAUDE.md`에 한 줄로 보강.** - -```markdown - -``` - -한 문장이 매 세션에 로드됩니다. `bmad-agent-dev.toml` 커스터마이징과 짝을 이뤄 Amelia의 워크플로 안과 어시스턴트와의 일반 채팅 모두에 규칙을 적용합니다. - -| 계층 | 범위 | 사용처 | -| --- | --- | --- | -| IDE 세션 파일(`CLAUDE.md` / `AGENTS.md`) | 모든 세션, 스킬 활성화 전 | BMad 밖에서도 적용해야 하는 짧은 보편 규칙 | -| BMad 에이전트 커스터마이징 | 에이전트가 실행하는 모든 워크플로 | 에이전트 페르소나별 동작 | -| BMad 워크플로 커스터마이징 | 하나의 워크플로 실행 | 워크플로별 출력 형태, 게시 후크, 템플릿 | -| BMad 중앙 설정 | 에이전트 명단 + 공유 설치 설정 | 방에 누가 있고 팀이 어떤 공유 경로를 쓰는지 | - -IDE 파일은 **간결하게** 유지하세요. 잘 고른 열두 줄이 긴 목록보다 효과적입니다. 모델은 이를 매 턴 읽으므로 불필요한 내용이 많으면 중요한 지침이 묻힙니다. - -## 레시피 6: 고급 통합 패턴 - -몇몇 BMad 워크플로는 레시피 1-5에서 다룬 기본보다 더 넓은 설정 영역을 제공합니다. 필요할 때 불러오는 지식 소스, 자동 출력 게시, 완료 시점 문서 표준, 교체 가능한 템플릿 같은 패턴이 여러 워크플로에 나타납니다. 어떤 필드를 제공하는지는 워크플로의 `customize.toml`을 확인하세요. 아래 예시는 모든 필드를 제공하는 `bmad-prd`를 사용하지만, 같은 패턴은 해당 필드가 있는 모든 워크플로에 적용됩니다. - -### 필요할 때 불러오는 지식 소스(`external_sources`) - -워크플로를 내부 지식 베이스, 경쟁사 데이터베이스, 컴플라이언스 참조에 연결합니다. 에이전트는 대화에서 관련 정보가 필요해질 때만 이를 참조하며 미리 호출하지 않습니다. - -```toml -# _bmad/custom/bmad-prd.toml (external_sources를 노출하는 모든 워크플로에서 같은 패턴 사용) - -[workflow] -external_sources = [ - "사용자가 경쟁사나 시장 세그먼트를 언급하면 차별화 섹션 초안을 작성하기 전에 corp:competitive_db(category={project_name})를 조회하세요.", - "규제 도메인(헬스케어, 핀테크, 교육)에서는 도메인별 섹션 초안을 작성하기 전에 corp:compliance_reference를 참고하세요.", -] -``` - -각 항목은 MCP 도구 이름, 트리거 조건, 도구에 필요한 필드를 자연어로 지정합니다. 런타임에 도구가 없으면 워크플로는 표준 동작으로 돌아가고 해당 도구를 사용할 수 없었다고 알립니다. - -### 자동 출력 게시(`external_handoffs`) - -워크플로가 완료된 뒤 완성된 산출물을 외부 기록 시스템으로 보냅니다. 레시피 3의 `on_complete`와 달리 `external_handoffs`는 전용 추가 배열입니다. 팀 항목이 차례로 더해지고 각 전달 작업은 따로 실행됩니다. 도구를 사용할 수 없으면 해당 작업만 건너뜁니다. - -```toml -# _bmad/custom/bmad-prd.toml (external_handoffs를 노출하는 모든 워크플로에서 같은 패턴 사용) - -[workflow] -external_handoffs = [ - "완료 후 corp:confluence_upload(space_key='PROD', parent_page='PRDs', label='prd', author={user_name})로 prd.md와 addendum.md를 Confluence에 업로드하세요. 반환된 페이지 URL을 기록하고 보여 주세요.", - "notion:create_page(database_id='abc123', title='PRD: ' + {project_name})로 Notion에도 복제하세요.", -] -``` - -지정된 도구가 없으면 전달 작업은 건너뛰고 표시됩니다. 로컬 파일은 항상 존재합니다. - -### 완료 시점 문서 표준(`doc_standards`) - -사람이 읽을 문서에 조직 작성 표준을 완료 시점에 적용합니다. 내용이 완료된 후, 사용자가 출력을 보기 전입니다. 각 항목은 `skill:`, `file:`, 일반 텍스트 지시문일 수 있으며 각 검토 단계는 하위 에이전트에서 병렬로 실행됩니다. - -```toml -# _bmad/custom/bmad-prd.toml (doc_standards를 노출하는 모든 워크플로에서 같은 패턴 사용) - -[workflow] -doc_standards = [ - "file:{project-root}/docs/enterprise/voice-and-tone.md", - "모든 날짜는 ISO 8601 형식(YYYY-MM-DD)을 사용해야 합니다.", - "'활용'을 사용한 곳은 모두 '사용'으로 바꾸세요.", -] -``` - -`doc_standards`는 추가 배열입니다. 팀 항목은 워크플로가 제공하는 기본값 위에 쌓입니다. 넓은 구조 검토가 좁은 문장 검토보다 먼저 와야 합니다. - -### 교체 가능한 템플릿과 체크리스트 - -구조화된 문서를 만드는 워크플로는 일반적으로 템플릿과 체크리스트 경로를 오버라이드 가능한 스칼라 값으로 노출합니다. `{project-root}` 아래에서 조직이 관리하는 파일을 가리키면 소스를 수정하지 않고 다른 구조를 적용할 수 있습니다. - -```toml -# _bmad/custom/bmad-prd.toml - -[workflow] -# 규제 산업용 PRD 구조 -prd_template = "{project-root}/docs/enterprise/prd-template-hipaa.md" - -# 조직별 검증 기준 -validation_checklist = "{project-root}/docs/enterprise/prd-checklist-regulated.md" -``` - -에이전트는 템플릿이 정의한 구조에 적응합니다. 템플릿은 `{project-root}/docs/` 또는 `{project-root}/_bmad/custom/templates/` 아래에 두어 오버라이드 파일과 함께 버전 관리하세요. 다중 조직 저장소에서는 `.user.toml`로 개별 팀이 커밋된 팀 파일을 건드리지 않고 자체 템플릿을 가리키게 할 수 있습니다. - -## 레시피 조합 - -여섯 레시피는 모두 조합할 수 있습니다. 현실적인 엔터프라이즈용 `bmad-product-brief` 오버라이드는 한 파일에서 `persistent_facts`(레시피 2), `on_complete`(레시피 3), `brief_template`(레시피 4)을 설정할 수 있습니다. 에이전트 수준 규칙(레시피 1)은 에이전트 이름의 별도 파일에 있고, 중앙 설정(레시피 5)은 공유 명단과 팀 설정을 고정하며, 고급 통합 패턴(레시피 6)은 외부 소스와 전달 작업을 설정합니다. 모든 계층은 함께 적용됩니다. - -```toml -# _bmad/custom/bmad-product-brief.toml (워크플로 수준) - -[workflow] -persistent_facts = ["..."] -brief_template = "{project-root}/docs/enterprise/brief-template.md" -on_complete = """ ... """ -``` - -```toml -# _bmad/custom/bmad-agent-analyst.toml (에이전트 수준 - Mary가 product-brief를 실행) - -[agent] -persistent_facts = ["도메인이 헬스케어, 금융, 아동 데이터와 관련되면 항상 '규제 검토' 섹션을 포함하세요."] -``` - -결과: Mary는 페르소나 활성화에서 규제 리뷰 규칙을 로드합니다. 사용자가 제품 개요 메뉴 항목을 선택하면 워크플로는 자체 관례를 그 위에 로드하고 엔터프라이즈 템플릿에 작성한 뒤 완료 시 Confluence에 게시합니다. 모든 계층이 함께 작동하며 BMad 소스는 수정하지 않습니다. - -## 문제 해결 - -**오버라이드가 적용되지 않나요?** 파일이 `_bmad/custom/` 아래 정확한 스킬 디렉터리 이름으로 있는지 확인하세요(예: `bmad-agent-dev.toml`, `bmad-dev.toml` 아님). [BMad 커스터마이징 방법의 문제 해결](./customize-bmad.md#문제-해결)을 참고하세요. - -**MCP 도구 이름을 모르겠나요?** 현재 세션에서 MCP 서버가 노출하는 정확한 이름을 사용하세요. 확실하지 않다면 Claude Code에 사용 가능한 MCP 도구 목록을 보여달라고 요청하세요. `persistent_facts`나 `on_complete`에 하드코딩한 이름은 MCP 서버가 연결되어 있지 않으면 동작하지 않습니다. - -**패턴이 내 설정에 맞지 않나요?** 위 레시피는 예시일 뿐입니다. 핵심 구조(3계층 병합, 구조 규칙, 에이전트가 여러 워크플로에 걸쳐 동작하는 방식)는 훨씬 다양한 패턴을 지원합니다. 필요에 맞게 조합하세요. diff --git a/docs/ko-kr/how-to/get-answers-about-bmad.md b/docs/ko-kr/how-to/get-answers-about-bmad.md deleted file mode 100644 index e222ec75f8..0000000000 --- a/docs/ko-kr/how-to/get-answers-about-bmad.md +++ /dev/null @@ -1,80 +0,0 @@ ---- -title: 'BMad 관련 질문에 답을 얻는 방법' -description: LLM을 사용해 BMad 관련 질문에 빠르게 답하기 -sidebar: - order: 9 ---- - -BMad의 내장 도움말, 소스 문서, 커뮤니티를 사용해 답을 얻으세요. 가장 빠른 방법부터 가장 꼼꼼한 방법까지 순서대로 소개합니다. - -## 1. BMad 도움말에게 묻기 - -답을 얻는 가장 빠른 방법입니다. `bmad-help` 스킬은 AI 세션에서 바로 사용할 수 있으며 질문의 80% 이상을 처리합니다. 프로젝트를 검사하고 완료한 작업을 확인한 뒤 다음에 무엇을 해야 할지 알려줍니다. - -``` -bmad-help SaaS 아이디어가 있고 기능도 모두 알고 있습니다. 어디서 시작하나요? -bmad-help UX 설계에는 어떤 선택지가 있나요? -bmad-help PRD 워크플로에서 막혔어요 -``` - -:::tip -플랫폼에 따라 `/bmad-help` 또는 `$bmad-help`도 사용할 수 있지만, `bmad-help`만 입력해도 어디서나 동작합니다. -::: - -## 2. 소스로 더 깊게 들어가기 - -BMad 도움말은 설치된 설정을 바탕으로 답합니다. BMad의 내부 구조, 역사, 아키텍처에 대한 질문이 있거나 설치 전에 BMad를 조사하고 있다면 AI가 소스를 직접 보게 하세요. - -[BMAD-METHOD 저장소](https://github.com/bmad-code-org/BMAD-METHOD)를 복제하거나 열고 AI에게 질문하세요. 에이전트 기능이 있는 도구(Claude Code, Cursor, Windsurf 등)는 소스를 읽고 직접 답할 수 있습니다. - -:::note[예시] -**Q:** "BMad로 무언가를 가장 빠르게 만드는 방법을 알려줘" - -**A:** `bmad-build`를 실행하세요. 직접 작성한 의도, 이슈, 사양 또는 계획된 스토리를 전달하면 사용 가능한 컨텍스트에 맞춰 필요한 수준으로 요구사항을 명확히 하고 계획, 구현, 리뷰를 진행합니다. -::: - -**더 좋은 답을 위한 팁:** - -- **구체적으로 묻기** - "PRD 워크플로 3단계가 무엇을 하나요?"가 "PRD는 어떻게 작동하나요?"보다 좋습니다 -- **뜻밖의 내용은 확인하기** - LLM은 가끔 틀립니다. 소스 파일을 확인하거나 Discord에서 물어보세요 - -### 에이전트를 쓰지 않는다면 문서 사이트 사용 - -AI가 로컬 파일을 읽을 수 없다면(ChatGPT, Claude.ai 등) [BMad 문서 사이트](https://docs.bmad-method.org/)를 여세요. - -## 3. 사람에게 묻기 - -BMad 도움말이나 소스로도 답을 얻지 못했다면, 이제 훨씬 나은 질문을 할 수 있습니다. - -| 채널 | 사용처 | -| --- | --- | -| `help-requests` 포럼 | 질문 | -| `#suggestions-feedback` | 아이디어와 기능 요청 | - -**Discord:** [discord.gg/gk8jAdXWmj](https://discord.gg/gk8jAdXWmj) - -**GitHub Issues:** [github.com/bmad-code-org/BMAD-METHOD/issues](https://github.com/bmad-code-org/BMAD-METHOD/issues) - -_막힌 채_
-  _줄을 서서_
-    _누구를_
-      _기다리나요?_ - -_소스는_
-  _이미 거기,_
-    _눈앞에 있습니다._ - -_AI에게_
-  _소스를 보여 주세요._
-    _마음껏 읽게 하세요._ - -_읽고._
-  _말하고._
-    _물어보세요._ - -_내일까지_
-  _미룰 이유가 있나요?_
-    _오늘 이미_
-      _할 수 있는데요._ - -        _—Claude_ diff --git a/docs/ko-kr/how-to/install-custom-modules.md b/docs/ko-kr/how-to/install-custom-modules.md deleted file mode 100644 index 2ed4498019..0000000000 --- a/docs/ko-kr/how-to/install-custom-modules.md +++ /dev/null @@ -1,181 +0,0 @@ ---- -title: '커스텀 및 커뮤니티 모듈 설치' -description: 커뮤니티 레지스트리, Git 저장소, 로컬 경로에서 서드파티 모듈을 설치합니다 -sidebar: - order: 1 ---- - -BMad 설치 프로그램을 사용해 커뮤니티 레지스트리, 서드파티 Git 저장소, 로컬 파일 경로에서 모듈을 추가하세요. - -## 사용 시점 - -- BMad 레지스트리에서 커뮤니티 기여 모듈을 설치합니다 -- 서드파티 Git 저장소(GitHub, GitLab, Bitbucket, 자체 호스팅)에서 모듈을 설치합니다 -- BMad 빌더로 로컬에서 개발 중인 모듈을 테스트합니다 -- 비공개 또는 자체 호스팅 Git 서버에서 모듈을 설치합니다 - -:::note[필수 조건] -[Node.js](https://nodejs.org) v20.12+와 `npx`(npm에 포함)가 필요합니다. 커스텀 및 커뮤니티 모듈은 새 설치 중 선택하거나 기존 설치에 추가할 수 있습니다. -::: - -## 커뮤니티 모듈 - -커뮤니티 모듈은 [BMad 플러그인 마켓플레이스](https://github.com/bmad-code-org/bmad-plugins-marketplace)에서 선별됩니다. 카테고리별로 구성되고 안전을 위해 승인된 커밋에 고정됩니다. - -### 1. 설치 프로그램 실행 - -```bash -npx bmad-method install -``` - -### 2. 커뮤니티 카탈로그 둘러보기 - -공식 모듈을 선택한 뒤 설치 프로그램이 묻습니다. - -``` -Would you like to browse community modules? -``` - -카탈로그 브라우저로 들어가려면 **Yes**를 선택하세요. 할 수 있는 일은 다음과 같습니다. - -- 카테고리별 탐색 -- 추천 모듈 보기 -- 사용 가능한 모든 모듈 보기 -- 키워드로 검색 - -### 3. 모듈 선택 - -어떤 카테고리에서든 모듈을 선택하세요. 설치 프로그램은 설명, 버전, 신뢰 등급을 보여줍니다. 이미 설치된 모듈은 업데이트 대상으로 미리 체크됩니다. - -### 4. 설치 계속 - -커뮤니티 모듈을 선택하면 설치 프로그램은 커스텀 소스, 도구/IDE 설정, 나머지 설치 흐름으로 이어집니다. - -## 커스텀 소스(Git URL과 로컬 경로) - -어떤 Git 저장소나 로컬 디렉터리든 커스텀 모듈의 소스로 사용할 수 있습니다. 설치 프로그램은 소스를 해석하고 모듈 구조를 분석한 뒤 기존 모듈과 함께 설치합니다. - -### 대화형 설치 - -설치 중 커뮤니티 모듈 단계 이후 설치 프로그램이 묻습니다. - -``` -Would you like to install from a custom source (Git URL or local path)? -``` - -**Yes**를 선택한 뒤 소스를 제공합니다. - -| 입력 유형 | 예시 | -| --- | --- | -| HTTPS URL(호스트 제한 없음) | `https://github.com/org/repo` | -| HTTP URL(호스트 제한 없음) | `http://host/org/repo` | -| 하위 디렉터리가 있는 HTTPS URL | `https://github.com/org/repo/tree/main/my-module` | -| SSH URL | `git@github.com:org/repo.git` | -| 로컬 경로 | `/Users/me/projects/my-module` | -| 틸드가 있는 로컬 경로 | `~/projects/my-module` | - -설치 프로그램은 저장소를 복제하거나(URL인 경우) 디스크에서 직접 읽은 뒤(로컬 경로인 경우), 찾은 모듈 목록을 보여 주고 설치할 항목을 선택하게 합니다. - -### 비대화형 설치 - -명령줄에서 커스텀 모듈을 설치하려면 `--custom-source` 플래그를 사용하세요. - -```bash -npx bmad-method install \ - --directory . \ - --custom-source /path/to/my-module \ - --tools claude-code \ - --yes -``` - -`--modules` 없이 `--custom-source`를 제공하면 core와 커스텀 모듈만 설치됩니다. 공식 모듈도 포함하려면 `--modules`를 추가하세요. - -```bash -npx bmad-method install \ - --directory . \ - --modules bmm \ - --custom-source https://gitlab.com/myorg/my-module \ - --tools claude-code \ - --yes -``` - -여러 소스는 쉼표로 구분할 수 있습니다. - -```bash ---custom-source /path/one,https://github.com/org/repo,/path/two -``` - -## 모듈 발견 방식 - -설치 프로그램은 소스에서 설치 가능한 모듈을 찾기 위해 두 모드를 사용합니다. - -| 모드 | 트리거 | 동작 | -| --- | --- | --- | -| `Discovery` | 소스에 `.claude-plugin/marketplace.json`이 있습니다 | 매니페스트의 모든 플러그인을 나열하고 설치할 항목을 선택하게 합니다 | -| `Direct` | marketplace.json이 없습니다 | 디렉터리에서 스킬(`SKILL.md`가 있는 하위 디렉터리)을 스캔하고 단일 모듈로 해석합니다 | - -`Discovery` 모드는 게시된 모듈에 일반적입니다. `Direct` 모드는 로컬 개발 중 스킬 디렉터리를 가리킬 때 편리합니다. - -:::note[`.claude-plugin/` 안내] -`.claude-plugin/marketplace.json` 경로는 여러 AI 도구 설치 프로그램에서 플러그인 발견을 위해 채택한 표준 관례입니다. Claude가 필요하지 않고 Claude API를 사용하지 않으며 어떤 AI 도구를 쓰는지에 영향을 주지 않습니다. 이 파일이 있는 모듈은 관례를 따르는 모든 설치 프로그램에서 발견될 수 있습니다. -::: - -## 로컬 개발 워크플로 - -[BMad 빌더](https://github.com/bmad-code-org/bmad-builder)로 모듈을 만들고 있다면 작업 디렉터리에서 직접 설치할 수 있습니다. - -```bash -npx bmad-method install \ - --directory ~/my-project \ - --custom-source ~/my-module-repo/skills \ - --tools claude-code \ - --yes -``` - -로컬 소스는 캐시에 복사되지 않고 경로로 참조됩니다. 모듈 소스를 업데이트하고 다시 설치하면 설치 프로그램이 최신 변경을 가져옵니다. - -:::caution[소스 제거] -설치 후 로컬 소스 디렉터리를 삭제해도 `_bmad/`에 설치된 모듈 파일은 보존됩니다. 소스 경로가 복원될 때까지 업데이트 중 해당 모듈은 건너뜁니다. -::: - -## 얻는 결과 - -설치 후 커스텀 모듈은 공식 모듈과 함께 `_bmad/`에 나타납니다. - -``` -your-project/ -├── _bmad/ -│ ├── core/ # 내장 core 모듈 -│ ├── bmm/ # 공식 모듈(선택한 경우) -│ ├── my-module/ # 커스텀 모듈 -│ │ ├── my-skill/ -│ │ │ └── SKILL.md -│ │ └── module-help.csv -│ └── _config/ -│ └── manifest.yaml # 모든 모듈, 버전, 소스를 추적 -└── ... -``` - -매니페스트는 각 커스텀 모듈의 소스(Git 소스는 `repoUrl`, 로컬 소스는 `localPath`)를 기록하여 `Quick Update`가 소스를 다시 찾을 수 있게 합니다. - -## 커스텀 모듈 업데이트 - -커스텀 모듈도 일반 업데이트 절차로 갱신합니다. - -- **Quick Update**(`--action quick-update`): 모든 모듈을 원래 소스에서 다시 불러옵니다. Git 기반 모듈은 다시 가져오고 로컬 모듈은 소스 경로에서 다시 읽힙니다. -- **전체 업데이트**: 모듈 선택을 다시 실행해 커스텀 모듈을 추가하거나 제거할 수 있습니다. - -## 직접 모듈 만들기 - -다른 사람이 설치할 수 있는 모듈을 만들려면 [BMad 빌더](https://github.com/bmad-code-org/bmad-builder)를 사용하세요. - -1. `bmad-module-builder`를 실행해 모듈 초기 구조를 생성합니다 -2. 여러 BMad 빌더 도구로 스킬, 에이전트, 워크플로를 추가합니다 -3. Git 저장소에 게시하거나 폴더 컬렉션을 공유합니다 -4. 다른 사용자는 `--custom-source `로 설치합니다 - -모듈이 발견 모드를 지원하려면 저장소 루트에 `.claude-plugin/marketplace.json`을 포함하세요(Claude 전용이 아닌 도구 간 관례입니다). marketplace.json 형식은 [BMad 빌더 문서](https://github.com/bmad-code-org/bmad-builder)를 참고하세요. - -:::tip[먼저 로컬에서 테스트] -개발 중에는 Git 저장소에 게시하기 전에 로컬 경로로 모듈을 설치해 빠르게 수정하고 확인하세요. -::: diff --git a/docs/ko-kr/how-to/pressure-test-an-idea.md b/docs/ko-kr/how-to/pressure-test-an-idea.md deleted file mode 100644 index a8eca084f1..0000000000 --- a/docs/ko-kr/how-to/pressure-test-an-idea.md +++ /dev/null @@ -1,55 +0,0 @@ ---- -title: "아이디어 압박 검증하기" -description: bmad-forge-idea 스킬로 투자 전에 아이디어를 단단하게 만들고, 입증하거나 폐기합니다 -sidebar: - order: 8 ---- - -`bmad-forge-idea` 스킬로 아직 덜 다듬어진 아이디어를 반론과 질문을 통해 검증하세요. 아이디어는 검증을 거쳐 확신을 얻거나, 적은 비용으로 폐기됩니다. - -## 사용 시점 - -- 시간이나 돈을 쓰기 전에 아이디어를 스트레스 테스트하고 싶습니다 -- 격려가 아니라 폐기할지 말지에 대한 정직한 판단이 필요합니다 -- 여러 선택지를 비교하고 각각 결론을 내려야 합니다 -- 아이디어가 기존 프로젝트 안에 있고 이미 있는 것과 대조해야 합니다 - -## 건너뛸 시점 - -- 아직 아이디어가 없고 선택지를 생성해야 합니다. `bmad-brainstorming`을 사용하세요 -- 제품을 추진하기로 정했고 고객 우선 관점에서 입증하고 싶습니다. `bmad-prfaq`를 사용하세요 -- 에이전트들이 함께 결정을 토론하길 원합니다. `bmad-party-mode`를 사용하세요 - -:::note[필수 조건] -없습니다. Forge는 일반 대화만으로 실행됩니다. 설치된 에이전트와 설정된 페르소나 명단이 있으면 세션이 더 풍부해지지만, 없어도 작동합니다. -::: - -## 세션 실행하기 - -### 1. 스킬 호출하기 - -IDE에서 `bmad-forge-idea`를 입력하거나, "아이디어를 단련해줘" 또는 "이걸 압박 검증해줘"라고 말하세요. 같은 메시지에 아이디어를 적어도 되고, 첫 질문을 기다려도 됩니다. - -### 2. 목표 말하기 - -원하는 목표를 말하세요. 아이디어를 단단하게 만들고 싶은지, 입증하거나 폐기하고 싶은지, 아니면 그저 끝까지 생각해 보고 싶은지 알려주면 됩니다. 목표에 따라 질문 방향이 달라집니다. 입증하려면 가장 중요한 주장부터 검증하고, 아이디어를 단련하려면 각 갈래마다 결론을 냅니다. - -### 3. 한 갈래씩 생각을 방어하기 - -질문자는 한 번에 하나의 질문을 던지고, 사용자가 반박할 수 있도록 자신의 권장 답도 함께 내놓습니다. 솔직하게 답하세요. 질문자가 모호한 용어나 프로젝트 현실과 맞지 않는 주장을 짚으면, 다음으로 넘어가기 전에 먼저 정리하세요. - -### 4. 대화 조종하기 - -갈래마다 두 목소리가 참여합니다. 하나는 사용자 명단에서, 다른 하나는 주제에 맞춰 즉석에서 만든 페르소나입니다. 특정 페르소나를 이름으로 부르거나, 저장된 파티를 소환하거나, "이 주장을 반대 관점에서 검토해 줘"라고 말해 한 주장을 공격하게 하고 직접 방어하세요. - -### 5. 결론 내리기 - -아이디어가 단련되거나, 폐기되거나, 단순히 더 명확해질 때까지 각 갈래마다 결론을 내리세요. 끝났다고 말해도 되고, Forge가 종료 시점을 판단하게 둬도 됩니다. - -## 얻는 결과 - -Forge는 실행할 때마다 결과를 명시한 독립형 `forge-report.html`을 작성합니다. 단련된 아이디어라면 확정한 결정과 폐기한 것, 그 이유를 `forged-idea.md`로도 정리합니다. 제품 개념이라면 이 파일을 `bmad-spec`, `bmad-prd`, `bmad-prfaq`의 입력으로 사용할 수 있습니다. 아이디어를 폐기했거나 단순히 더 명확히 한 세션에서는 별도 산출물이 필요하지 않습니다. 보고서 자체로 충분합니다. - -:::tip[아이디어를 억지로 살리지 마세요] -아이디어가 버티지 못한다는 사실을 적은 비용으로 알아내는 것이 이득입니다. 세션을 "예"로 유도하지 마세요. -::: diff --git a/docs/ko-kr/how-to/project-context.md b/docs/ko-kr/how-to/project-context.md deleted file mode 100644 index dbc8ca81c8..0000000000 --- a/docs/ko-kr/how-to/project-context.md +++ /dev/null @@ -1,76 +0,0 @@ ---- -title: '프로젝트 컨텍스트 관리하기' -description: bmad-project-context로 저장소의 에이전트 지침을 설정하고 유지하기 -sidebar: - order: 6 ---- - -`bmad-project-context`는 AI 에이전트가 저장소에서 제대로 작업할 수 있는 환경을 마련합니다. 새 프로젝트와 기존 코드베이스에서 모두 쓸 수 있고 BMad 설치 여부도 상관없습니다. 결과는 `AGENTS.md`에 들어가는 간결하고 검증된 규칙 블록입니다. - -:::note[필수 조건] - -- BMad Method가 설치된 저장소와 아무것도 설치되지 않은 저장소를 모두 지원합니다. - ::: - -## 사용 시점 - -- 기존 코드베이스에서 AI 지원 작업을 시작하면서 거버넌스, 보안, 스타일 같은 조직 표준을 적용할 때 -- 직접 작성한 `AGENTS.md`나 `CLAUDE.md`를 교체하지 않고 받아들여 개선하고 싶을 때 -- 새 프로젝트의 첫 커밋부터 정해 둔 표준을 따르게 하고 싶을 때 -- 에이전트가 같은 실수를 반복해 이를 기록하고 싶을 때 -- 지침이 오래됐거나 불필요하게 커졌다고 느낄 때(Audit 실행) - -## 1단계: 실행하기 - -```bash -bmad-project-context -``` - -"`AGENTS.md`를 설정해 줘", "기존 `AGENTS.md`를 받아들여 줘", "컨텍스트를 새로 고쳐 줘", "컨텍스트를 감사해 줘", "에이전트가 계속 잘못된 테스트 러너를 사용해"처럼 원하는 작업을 일반 문장으로 말하면 스킬이 알맞은 의도를 선택합니다. 스킬이 작성하지 않은 기존 지침이 있으면 Adopt를 사용하고, 이전에 스킬이 작성한 지침이 있으면 해당 내용을 갱신합니다. Setup은 보존할 지침이 없는 저장소에서만 사용합니다. - -저장소 밖에서 실행했다면 작업할 저장소를 지정하세요. 경로가 둘 이상의 작업 트리로 연결되면 스킬은 파일을 쓰기 전에 어느 쪽인지 확인합니다. - -## 2단계: 직접 알고 있는 규칙 알려주기 - -스킬은 먼저 `AGENTS.md`, `CLAUDE.md`, 편집기 규칙 파일, 문서 등 기존 자료를 읽습니다. 잘 구성된 부분과 오래된 것으로 보이는 부분, 바꾸기를 제안하는 내용을 나눠 알려줍니다. 사람이 작성한 기존 파일은 버리지 않고 개선합니다. 파일을 쓰기 전에 기존 지침이 각각 어떻게 처리되는지 보여주며, 사용자 승인 없이 삭제하지 않습니다. - -그다음 저장소의 현재 상태와 무관하게 지켜야 할 규칙을 묻습니다. 거버넌스, 보안 및 규정 준수 요구 사항, 코딩 표준, 스타일 가이드, 변경 금지 영역 등이 해당합니다. 조직 핸드북, 위키 내보내기, MCP 지식 베이스처럼 저장소 밖의 문서도 함께 제공할 수 있습니다. - -새 프로젝트라면 이 대화에서 필요한 내용이 모두 나옵니다. 기존 코드베이스에서는 스캔으로 알 수 없는 나머지 절반을 이 대화로 채웁니다. - -## 3단계: 나머지 정보 검증하기 - -스킬은 기록할 모든 경로를 확인하고 `package.json`, `Makefile`, CI 설정을 읽습니다. 스크립트는 에이전트가 이 파일에서 직접 읽을 수 있으므로 그대로 옮겨 적지 않습니다. 대신 기존 설정이 무엇을 설명하는지 파악한 뒤, 사용해야 할 명령과 잘못된 추측을 바로잡는 내용, 주의 사항만 블록에 담습니다. - -이후 스캔만으로 답할 수 없는 내용을 묻습니다. 에이전트가 이 저장소에서 반복하는 실수, 변경하면 안 되는 부분, 도메인 용어의 의미, 실행할 때 주의해야 하는 명령이 여기에 해당합니다. - -## 4단계: 블록 승인하기 - -파일을 쓰기 전에 전체 블록을 먼저 보여줍니다. 사용자가 승인해야만 ``와 `` 사이에 내용을 넣습니다. 마커 밖에 사용자가 작성한 내용은 바이트 단위로 그대로 보존합니다. - -스킬은 커밋하지 않습니다. 사용자가 검토할 수 있도록 변경 사항을 작업 트리에 남겨 둡니다. - -작업을 마치면 어떤 내용을 넣고 뺐는지, 왜 그렇게 판단했는지 설명합니다. - -## 정확하게 유지하기 - -- **Refresh** — 실제 변경이 생긴 뒤 실행합니다. 주의 사항이 여전히 맞는지 확인한 뒤 기록된 커밋 이후 삭제되거나 이름이 바뀐 항목을 비교해 이동한 내용을 갱신합니다. 이미 정한 내용은 다시 묻지 않습니다. -- **Record** — 에이전트가 무언가 잘못한 순간 실행합니다. 실제로 관찰한 실수만 위험 요소로 기록할 수 있습니다. -- **Audit** — 모든 내용을 다시 검증하고 불필요한 항목을 덜어냅니다. 작업 후 블록은 이전보다 작거나 같은 크기를 유지합니다. - -규칙이 지키는 대상이 사라지거나 사용자가 직접 폐기할 때까지는 해당 규칙을 유지합니다. 최근에 같은 문제가 없었다는 이유만으로 삭제하면 안 됩니다. 효과가 있는 규칙은 실패의 흔적을 스스로 없애기 때문입니다. - -## 저장소와 홈 디렉터리 중 어디에 둘까 - -이 스킬이 작성한 내용은 팀과 공유할 수 있도록 저장소에 커밋합니다. 모든 프로젝트에서 같은 규칙이 반복되거나 팀 규칙이 아닌 개인 취향이라면 홈 디렉터리에 있는 에이전트 전역 설정에 두세요. - -## 폐기된 이전 스킬 - -:::note[bmad-generate-project-context 또는 bmad-document-project를 찾고 있나요?] -두 스킬 모두 폐기되었으며 이제 이 스킬로 연결됩니다. 기존 트리거 문구는 계속 작동합니다. 기존 `project-context.md`가 있다면 Setup 과정에서 내용을 흡수할지 제안하므로 그대로 방치되지 않습니다. -::: - -## 다음 단계 - -- [**프로젝트 컨텍스트 설명**](../explanation/project-context.md) — 설계와 그 근거 -- [**워크플로 맵**](../reference/workflow-map.md) — 전체 방법론에서 컨텍스트가 들어가는 위치 diff --git a/docs/ko-kr/how-to/upgrade-to-v6.md b/docs/ko-kr/how-to/upgrade-to-v6.md deleted file mode 100644 index eeb178665d..0000000000 --- a/docs/ko-kr/how-to/upgrade-to-v6.md +++ /dev/null @@ -1,101 +0,0 @@ ---- -title: 'v6로 업그레이드하는 방법' -description: BMad v4에서 v6로 마이그레이션합니다 -sidebar: - order: 2 ---- - -BMad 설치 프로그램을 사용해 v4에서 v6로 업그레이드하세요. 레거시 설치 자동 감지와 마이그레이션 지원이 포함되어 있습니다. - -## 사용 시점 - -- BMad v4가 설치되어 있습니다(`.bmad-method` 폴더) -- 새 v6 아키텍처로 마이그레이션하고 싶습니다 -- 보존해야 할 기존 계획 산출물이 있습니다 - -:::note[필수 조건] - -- Node.js 20.12+ -- 기존 BMad v4 설치 -::: - -## 단계 - -### 1. 설치 프로그램 실행 - -[설치 프로그램 안내](../start/install-bmad.md)를 따르세요. - -### 2. 레거시 설치 처리 - -v4가 감지되면 다음 중 선택할 수 있습니다. - -- 설치 프로그램이 `.bmad-method`를 백업하고 제거하게 합니다 -- 종료한 뒤 수동으로 정리합니다 - -BMad Method 폴더 이름을 다르게 지정했다면 직접 폴더를 제거해야 합니다. - -### 3. IDE 스킬 정리 - -레거시 v4 IDE 명령/스킬을 수동으로 제거하세요. 예를 들어 Claude Code를 사용한다면 bmad로 시작하는 중첩 폴더를 찾아 제거합니다. - -- `.claude/commands/` - -새 v6 스킬은 다음 위치에 설치됩니다. - -- `.claude/skills/` - -### 4. 계획 산출물 마이그레이션 - -**계획 문서(제품 개요/PRD/UX/아키텍처)가 있다면:** - -설명적인 이름으로 `_bmad-output/planning-artifacts/`에 옮기세요. - -- PRD 문서는 파일명에 `PRD`를 포함합니다 -- 파일 유형에 맞게 `brief`, `architecture`, `ux-design`을 포함합니다 -- 샤딩된 문서는 이름 있는 하위 폴더에 둘 수 있습니다 - -**계획 도중이라면:** v6 워크플로로 다시 시작하는 것을 고려하세요. 기존 문서를 입력으로 사용할 수 있습니다. 웹 검색과 IDE 계획 모드를 활용해 단계별로 요구사항을 구체화하는 새 워크플로가 더 나은 결과를 냅니다. - -### 5. 진행 중인 개발 마이그레이션 - -이미 생성 또는 구현된 스토리가 있다면: - -1. v6 설치를 완료합니다 -2. `epics.md` 또는 `epics/epic*.md`를 `_bmad-output/planning-artifacts/`에 둡니다 -3. 개발자의 `bmad-sprint-planning` 워크플로를 실행합니다 -4. 이미 완료된 에픽/스토리를 에이전트에게 알려줍니다 - -## 얻는 결과 - -**v6 통합 구조:** - -```text -your-project/ -├── _bmad/ # 단일 설치 폴더 -│ ├── _config/ # 커스터마이징 -│ │ └── agents/ # 에이전트 커스터마이징 파일 -│ ├── core/ # 범용 core 프레임워크 -│ ├── bmm/ # BMad Method 모듈 -│ ├── bmb/ # BMad 빌더 -│ └── cis/ # 창의적 지능 제품군 -└── _bmad-output/ # 출력 폴더(v4의 문서 폴더) -``` - -## 모듈 마이그레이션 - -| v4 모듈 | v6 상태 | -| --- | --- | -| `.bmad-2d-phaser-game-dev` | BMGD 모듈에 통합 | -| `.bmad-2d-unity-game-dev` | BMGD 모듈에 통합 | -| `.bmad-godot-game-dev` | BMGD 모듈에 통합 | -| `.bmad-infrastructure-devops` | 지원 중단 - 새 DevOps 에이전트 예정 | -| `.bmad-creative-writing` | 아직 적용되지 않음 - 새 v6 모듈 예정 | - -## 주요 변경 사항 - -| 개념 | v4 | v6 | -| --- | --- | --- | -| **코어** | `_bmad-core`는 실제로 BMad Method였습니다 | `_bmad/core/`는 범용 프레임워크입니다 | -| **메서드** | `_bmad-method` | `_bmad/bmm/` | -| **설정** | 파일을 직접 수정 | 모듈별 `config.yaml` | -| **문서** | 샤딩 또는 비샤딩 필수 설정 | 완전히 유연하며 자동 스캔 | diff --git a/docs/ko-kr/index.md b/docs/ko-kr/index.md deleted file mode 100644 index 5df60c2dac..0000000000 --- a/docs/ko-kr/index.md +++ /dev/null @@ -1,45 +0,0 @@ ---- -title: BMad로 소프트웨어 만들기 -description: BMad는 무엇을 만들지 결정하고 실제로 구현하도록 돕습니다. BMad를 설치하거나 첫 변경을 구현하거나 현재 작업에 맞는 경로를 찾으려면 여기서 시작하세요. -hero: - title: '아이디어를 소프트웨어로.
규모에 관계없이.' - tagline: 충분히 생각한 뒤 구현하세요. 결정은 사용자가 내리므로 무엇을 출시하는지 직접 이해할 수 있습니다. - actions: - - text: 첫 변경 사항 구현하기 - link: ./start/build-your-first-change/ - variant: primary - - text: BMad 설치하기 - link: ./start/install-bmad/ - variant: secondary ---- - -BMad는 Claude Code, Cursor 같은 AI 코딩 도구에 스킬이라는 이름 있는 명령 모음을 추가합니다. 일부 스킬은 아이디어를 탐색하고 조사하거나 반대 관점에서 검토한 뒤 결정한 내용을 기록하도록 도와줍니다. 다른 스킬은 구현을 담당합니다. 원하는 변경 사항을 `bmad-build`에 전달하면 코드를 작성하고 검토합니다. - -두 종류의 스킬은 각각 따로 사용할 수 있습니다. 아이디어를 다루는 스킬만 사용하고 BMad에 코드를 한 줄도 맡기지 않는 사용자도 많습니다. 반대로 작은 수정은 별도 계획 없이 바로 구현해도 됩니다. - -## 시작점 찾기 - -**변경에 어느 정도의 절차가 필요한지 확신하기 어렵습니다.** -[개발 경로 선택하기](./how-to/choose-a-development-path.md)에서 단순한 편집부터 여러 에픽으로 구성된 프로젝트까지, 안전하게 적용할 수 있는 가장 간단한 경로를 찾아보세요. - -**BMad가 실제로 작동하는 모습을 보고 싶습니다.** -[첫 변경 사항 구현하기](./start/build-your-first-change.md)에서는 빈 프로젝트에서 Build를 한 번 실행합니다. - -**무엇을 바꿀지 정확히 알고 있으며 작은 작업입니다.** -`bmad-build`를 실행하고 변경 내용을 설명하세요. [변경 사항 구현하기](./build/build-a-change.md)를 참고하면 됩니다. - -**기존 코드베이스에서 작업하고 있습니다.** -먼저 `bmad-project-context`를 실행하는 방안을 고려하세요. 이후에는 평소처럼 Build를 사용합니다. [기존 프로젝트](./how-to/established-projects.md)와 [프로젝트 컨텍스트 관리하기](./how-to/project-context.md)를 참고하세요. - -**더 큰 기능이나 제품 전체를 만들고 있습니다.** -완성된 의도를 `bmad-spec`에 전달할 수 있다면 거기서 시작하세요. 아이디어 구상과 계획을 먼저 진행해야 한다면 [개발 경로 선택하기](./how-to/choose-a-development-path.md)나 [워크플로 맵](./reference/workflow-map.md)에서 경로를 고르세요. - -**아이디어가 아직 막연하거나 좋은 아이디어인지 확신하기 어렵습니다.** -[브레인스토밍](./explanation/brainstorming.md)으로 선택지를 만들고 [Deep Recon](./explanation/deep-recon.md)으로 근거를 모으거나 [아이디어를 압박 검증](./how-to/pressure-test-an-idea.md)하세요. - -**BMad가 우리 팀의 규칙과 업무 방식을 따르게 하고 싶습니다.** -[BMad 커스터마이징](./how-to/customize-bmad.md)과 [조직에 맞게 BMad 확장하기](./how-to/expand-bmad-for-your-org.md)를 참고하세요. - -:::tip[어디서 시작할지 모르겠나요?] -`bmad-help`를 실행하세요. -::: diff --git a/docs/ko-kr/reference/agents.md b/docs/ko-kr/reference/agents.md deleted file mode 100644 index ac90b09f2f..0000000000 --- a/docs/ko-kr/reference/agents.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -title: 에이전트 -description: 기본 BMM 에이전트와 스킬 ID, 메뉴 트리거, 주요 워크플로 -sidebar: - order: 2 ---- - -## 기본 에이전트 - -이 페이지는 BMad Method와 함께 설치되는 기본 BMM(애자일 제품군) 에이전트를 스킬 ID, 메뉴 트리거, 주요 워크플로와 함께 나열합니다. 각 에이전트는 스킬로 호출됩니다. - -## 참고 - -- 각 에이전트는 설치 프로그램이 생성하는 스킬로 제공됩니다. 스킬 ID(예: `bmad-agent-dev`)를 사용해 에이전트를 호출합니다. -- 트리거는 각 에이전트 메뉴에 표시되는 짧은 메뉴 코드(예: `PRD`)와 유사 매칭 항목입니다. -- QA 테스트 생성은 개발자 에이전트에서 실행할 수 있는 `bmad-qa-generate-e2e-tests` 워크플로 스킬이 처리합니다. 전체 테스트 설계자(TEA)는 별도 모듈에 있습니다. [완료된 작업 테스트하기](../build/test-completed-work.md)를 참고하세요. - -| 에이전트 | 스킬 ID | 트리거 | 주요 워크플로 | -| --- | --- | --- | --- | -| 분석가(Mary) | `bmad-agent-analyst` | `BP`, `MR`, `DR`, `TR`, `CB`, `WB`, `PC` | 브레인스토밍, 시장 리서치, 도메인 리서치, 기술 리서치, 개요 작성, PRFAQ 챌린지, 프로젝트 컨텍스트 | -| 제품 관리자(John) | `bmad-agent-pm` | `PRD`, `CE`, `IR`, `CC` | PRD 생성/업데이트/검증, 에픽과 스토리 생성, 구현 준비 상태(스프린트 계획 게이트), 방향 수정 | -| 아키텍트(Winston) | `bmad-agent-architect` | `CA`, `IR` | 아키텍처 생성, 구현 준비 상태(스프린트 계획 게이트) | -| 개발자(Amelia) | `bmad-agent-dev` | `BD`, `QA`, `CR`, `SP`, `ER` | Build, QA 테스트 생성, 코드 리뷰, 스프린트 계획, 에픽 회고 | -| UX 디자이너(Sally) | `bmad-agent-ux-designer` | `CU` | UX 설계 생성 | - -:::note[Paige는 어디에 있나요?] -기술 작성자 Paige는 잠시 쉬고 있습니다. 앞으로 더 많은 역량을 갖춰 돌아올 예정입니다. 그동안 프로젝트 컨텍스트 기능은 계속 사용할 수 있습니다. 분석가의 `PC`(Project Context) 트리거를 사용하거나 `bmad-project-context` 스킬을 직접 호출하세요. -::: - -## 트리거 유형 - -에이전트 메뉴 트리거는 구조화된 워크플로 파일을 로드합니다. 트리거 코드를 입력하면 에이전트가 워크플로를 시작하고 각 단계에서 입력을 요청합니다. - -예: `PRD`(PRD 생성, 업데이트 또는 검증), `CA`(아키텍처 생성), `BD`(Build) diff --git a/docs/ko-kr/reference/build-auto.md b/docs/ko-kr/reference/build-auto.md deleted file mode 100644 index 783da751cd..0000000000 --- a/docs/ko-kr/reference/build-auto.md +++ /dev/null @@ -1,258 +0,0 @@ ---- -title: 자율 개발 루프 -description: bmad-build-auto를 단일 작업자로 사용해 Build 구현 모델을 자동화하는 방법 -sidebar: - order: 6 ---- - -`bmad-build-auto`는 표준 [변경 사항 구현하기](../build/build-a-change.md) 모델에서 세션 하나에 들어오는 작업 단위 하나를 사람의 개입 없이 처리합니다. 호출 한 번으로 하나의 의도나 스토리를 명확히 하고 계획·구현·검토한 뒤, 사람이나 오케스트레이터가 후속 처리할 수 있는 종료 상태를 남깁니다. - -Build Auto는 다음 스토리를 선택하거나 백로그 전체를 반복 실행하거나 에픽을 조율하거나 회고를 실행하지 않습니다. 자신이 실행하는 구현 작업과 새로 만들거나 이어서 쓰는 기록만 담당합니다. 백로그 정책과 작업 배정은 사람이나 AI 코딩 세션, bmad-loop 같은 오케스트레이터가 맡습니다. - -## 하는 일 - -`bmad-build-auto`는 사람 개입 없는 구현 작업을 한 번 실행합니다. - -1. 입력된 의도를 명확히 합니다 -2. 사양 파일을 만들거나, 기존 파일을 찾아 이어서 진행합니다 -3. 변경을 구현합니다 -4. 결과를 리뷰합니다 -5. 최종 상태를 사양 파일 또는 대체 결과 산출물에 기록해 실행을 마칩니다 - -## 전제 조건 - -실행 환경에서 하위 에이전트를 사용할 수 있어야 합니다. 그렇지 않으면 워크플로는 `no subagents` 조건과 `blocked` 상태로 멈춥니다. 여러 스토리를 조율하는 AI 코딩 세션은 스토리마다 Build Auto 작업자 하나를 시작해야 합니다. 각 작업자도 실행 중 필요한 검토 하위 에이전트를 직접 시작할 수 있어야 합니다. - -버전 관리는 선택 사항이지만 사용을 강력히 권장합니다. 버전 관리를 사용한다면 작업 트리가 깨끗해야 합니다. 에이전트도 저장소 메타데이터를 갱신할 수 있어야 합니다. - -## 입력 - -### 기본 호출 입력 - -기본 입력은 호출 프롬프트입니다. `bmad-build-auto`는 이 프롬프트를 완성된 구현 계획이 아닌 워크플로 입력으로 다룹니다. - -의도는 다음과 같은 형태로 전달합니다. - -- 짧은 자유 형식 변경 요청 -- 티켓, 이슈 또는 스토리 식별자 -- 의도 파일 경로 -- 이 워크플로가 만든 기존 사양 파일 경로 -- 특정 사양 파일 경로 없이 사양 폴더와 스토리 ID를 함께 전달하는 형태(**폴더+ID 디스패치**, 아래 참고) - -### 재개 입력 - -호출이 기존 사양 파일을 가리키고 프런트매터에 알려진 `status` 값이 있으면, 워크플로는 해당 상태부터 재개합니다. - -| 사양 상태 | 진입 지점 | -| --- | --- | -| `draft` | 계획 | -| `ready-for-dev` | 구현 | -| `in-progress` | 구현 | -| `in-review` | 리뷰 | -| `done` | 새로운 후속 검토로 다시 리뷰 | -| `blocked` | 즉시 중단 | - -### 폴더+ID 디스패치 - -호출 프롬프트에 특정 사양 파일 경로 대신 사양 폴더와 스토리 ID를 전달할 수도 있습니다. 이때 호출자가 덧붙인 `invoke_dev_with` 지침 같은 나머지 프롬프트 텍스트는 작업 설명을 대체하지 않고 계획에 필요한 추가 컨텍스트로 전달됩니다. - -워크플로는 `/stories.yaml`을 읽고 `id`가 일치하는 항목을 찾은 뒤, 그 항목의 `title`과 `description`만 사용합니다. `spec_checkpoint`, `done_checkpoint`, `invoke_dev_with`는 디스패치를 요청한 호출자가 쓰는 필드이므로 파일에서는 읽지 않습니다. - -그런 다음 `/stories/-*.md`를 ID 접두사로 확인해 첫 디스패치인지, 이어서 진행하는 상황인지 판단합니다. - -| 디스크에서 찾은 항목 | 결과 | -| --- | --- | -| 없음 | 첫 디스패치입니다. `/SPEC.md`가 있어야 합니다. 없으면 `no epic spec found` 조건으로 `blocked`에서 멈춥니다. `SPEC.md`와 동반 파일을 읽은 뒤 계획으로 진행합니다. | -| 정확히 하나 | 해당 파일의 `status`에 따라 위 표와 같은 방식으로 재개합니다. 여기서 `blocked` 상태는 `blocked spec supplied`가 아니라 `story already blocked` 조건을 보고합니다. 호출자가 차단된 사양을 직접 넘긴 것이 아니라 build-auto가 ID로 파일을 찾았기 때문입니다. `status`가 없거나 인식할 수 없으면 `unrecognized status in existing story file` 조건과 `blocked` 상태로 멈춥니다. | -| 둘 이상 | `ambiguous story file match` 조건으로 `blocked`에서 멈춥니다. | - -`blocked` 상태의 스토리 파일은 영구 차단된 것으로 취급됩니다. 원인을 고친 뒤에도 같은 ID를 다시 디스패치하면 항상 `story already blocked`로 멈춥니다. 다시 시도하려면 스토리 파일을 삭제하세요. 그러면 해당 ID는 대기 상태로 돌아가고 다음 디스패치가 처음부터 시작됩니다. - -계획 단계가 실행될 때마다 워크플로는 `/stories/*.md` 패턴에 맞는 다른 스토리 파일도 모두 읽습니다. 첫 디스패치뿐 아니라 `draft` 상태에서 중단된 계획을 재개할 때도 마찬가지입니다. 각 파일의 `Code Map`, `Design Notes`, `Spec Change Log`, `Tasks & Acceptance` 체크리스트 상태, `Auto Run Result` 세부 내용을 추가 계획 컨텍스트로 가져옵니다. 이 덕분에 같은 폴더의 다른 스토리가 이미 결정하거나 만든 내용을 현재 계획에 반영할 수 있습니다. 계획 단계를 건너뛰는 재개 경로에서는 이 과정도 생략합니다. - -한 번의 호출에서는 `stories.yaml` 항목 하나만 디스패치합니다. 결과와 관계없이 다른 항목을 읽거나 다른 스토리 ID로 넘어가지 않습니다. - -사양 기반 에픽은 다음과 같은 공통 구조를 사용합니다. - -```text -/ -├── SPEC.md -├── stories.yaml -└── stories/ - ├── 1-.md - ├── 2-.md - └── ... -``` - -`stories.yaml`은 순서가 있는 스토리 목록입니다. Build와 Build Auto는 `stories/` 아래의 Markdown 기록을 만들거나 기존 기록을 이어서 사용합니다. 각 기록은 프런트매터에 수명주기 상태를 저장합니다. 이후 워크플로는 어느 Build 스킬이 기록을 만들었는지에 기대지 않고 위치와 상태를 읽습니다. - -## 오케스트레이션 선택지 - -아래 모든 선택지에서 Build Auto는 작업자입니다. 오케스트레이터가 작업 단위를 고르고 작업자 하나를 시작한 뒤, 결과를 읽어 다음 행동을 결정합니다. - -### bmad-loop로 순서가 지정된 목록 실행 - -선택 사항인 [bmad-loop](https://github.com/bmad-code-org/bmad-loop) 오케스트레이터는 사양 폴더의 `stories.yaml`을 목록 순서대로 처리합니다. 의존성 그래프를 추론하지 않는 선형 스케줄러이므로 각 스토리의 선행 작업이 앞에 오도록 목록을 정렬해야 합니다. - -스토리 하나를 선택하면 해당 스토리만 실행합니다. "여기서 시작해 나머지를 모두 실행"한다는 뜻이 아닙니다. 회고는 에픽을 마무리하는 별도 작업입니다. bmad-loop가 실행을 권할 수는 있지만 실제 회고는 `bmad-retrospective`가 수행합니다. - -### AI 코딩 세션을 오케스트레이터로 사용 - -AI 코딩 세션이 작업 단위마다 Build Auto 작업자 하나를 배정하고 결과의 근거를 확인할 수 있습니다. 구현 과정에서 상위 사양이나 스토리 목록이 더 이상 맞지 않는다는 사실이 드러나면 이후 작업도 수정할 수 있습니다. 이러한 수정이 상위 의도와 계속 일치하도록 관리하는 책임은 오케스트레이션 세션에 있습니다. - -### 병렬 에픽 흐름 조율 - -프로젝트 수준의 병렬 실행에는 더 높은 조율 계층이나 에픽별 담당자가 필요합니다. 의존성과 통합 경계가 명확하다면 독립된 에픽 흐름을 병렬로 실행할 수 있습니다. bmad-loop의 순차 스토리 스케줄러는 이러한 프로젝트 수준 조율을 제공하지 않습니다. - -## 컨텍스트 입력 - -활성화되면 워크플로는 다음 항목을 확인합니다. - -- `_bmad/config.toml`, `_bmad/config.user.toml`, `_bmad/custom/` 아래의 선택적 팀/사용자 오버라이드 -- `customize.toml`, 팀 오버라이드, 사용자 오버라이드에 설정된 워크플로 커스터마이징 -- 워크플로 설정에 나열된 지속 사실. 사용자가 따로 설정하지 않으면 비어 있으므로 기본적으로 이 단계에서 불러오는 내용은 없습니다 - -필요하면 다음도 참고합니다. - -- BMAD 계획 산출물 -- 에픽 기반 작업을 위해 캐시했거나 새로 취합한 에픽 컨텍스트 파일 -- 같은 에픽에서 가장 최근에 완료된 이전 스토리 사양 -- 폴더+ID 디스패치에서는 같은 사양 폴더 아래의 다른 `stories/*.md` 기록(위의 폴더+ID 디스패치 참고) - -## 사양 상태 - -사양 프런트매터의 `status`는 오케스트레이터가 읽는 핵심 상태값입니다. - -| 사양 상태 | 의미 | -| --- | --- | -| `draft` | 사양은 있지만 ready-for-dev 검증을 아직 통과하지 않았습니다 | -| `ready-for-dev` | 구현할 만큼 사양이 충분히 완성되었습니다 | -| `in-progress` | 구현이 진행 중입니다 | -| `in-review` | 리뷰 또는 분류가 진행 중입니다 | -| `done` | 워크플로가 성공적으로 완료되었습니다 | -| `blocked` | 사람 개입 없이 안전하게 계속할 수 없습니다 | - -### 보류된 발견 사항 - -`deferred`는 실제 문제이지만 현재 스토리의 문제가 아닌 발견 사항을 보고하는 곳입니다. 각 항목에는 다음이 들어갑니다. - -- `summary` — 보류된 문제를 한 문장으로 설명합니다 -- `evidence` — 해당 발견 사항이 실제 문제인 근거입니다 -- `location` — 선택 사항인 file:line 또는 컴포넌트 힌트입니다 -- `severity` — 선택 사항인 최종 분류 심각도(`high`, `medium`, `low`)입니다 - -이 목록은 의도적으로 백로그 역할을 하지 않습니다. 기계가 읽을 수 있는 리뷰 결과일 뿐입니다. 티켓을 만들지, 중앙 대기열에 추가할지, 여러 실행에서 나온 중복을 식별할지, 아무것도 하지 않을지는 오케스트레이터가 결정해야 합니다. - -### `ready-for-dev`일 때 - -`ready-for-dev`는 보통 워크플로가 구현으로 넘어가며 통과하는 재개 상태입니다. 다만 호출 프롬프트가 계획 후 멈추라고 지시했다면 실제 중단 결과가 됩니다. 사양이 READY FOR DEVELOPMENT 관문을 통과하면 워크플로는 상태를 `ready-for-dev`로 설정하고 구현으로 넘어가지 않습니다. 같은 사양 또는 같은 사양 폴더와 스토리 ID를 다시 디스패치하면 위 라우팅에 따라 구현부터 재개합니다. - -### `done`일 때 - -성공적으로 완료되면 워크플로는 사양에 다음을 작성하거나 갱신합니다. - -- 최종 `status: done` -- 다음 내용을 담은 `Auto Run Result` 섹션 - - 구현한 변경 요약 - - 변경된 파일 - - 리뷰 발견 사항 분류 - - 수행한 검증 - - 남은 위험 -- `followup_review_recommended` 플래그. LLM이 추가 검토가 유용하다고 판단하면 `true`가 됩니다. 의무가 아니라 제안입니다. 같은 사양 파일을 가리켜 스킬을 다시 실행하는 것이 두 번째 검토를 시작하는 가장 간단한 방법입니다. -- `baseline_revision` — 구현 전 기준이 되는 전체 리비전입니다. 버전 관리가 없으면 `NO_VCS`입니다. -- 리뷰에서 `defer`로 분류한 발견 사항을 담은 프런트매터 `deferred` 항목입니다. 각 항목에는 `summary`, `evidence`, 가능한 경우 `location`과 `severity`가 기록됩니다. - -워크플로는 커밋하지만 push하지는 않습니다. 종료 시 작업 트리는 깨끗합니다. - -### `blocked`일 때 - -차단 상태로 끝나면 워크플로는 다음을 작성합니다. - -- 사양이 있으면 최종 `status: blocked` -- 차단 조건 -- 사양 또는 대체 결과 산출물의 관련 세부 정보 - -대표적인 차단 조건은 다음과 같습니다. - -- `unclear intent` -- `intent gap` -- `no subagents` -- `missing spec_file before implementation` -- `implementation verification failed` -- `review repair loop exceeded 5 iterations (non-convergence)` -- `blocked spec supplied`(직접 호출한 사양 파일이 이미 `status: blocked`였던 경우) -- `no stories.yaml found` -- `story id not found in stories.yaml` -- `no epic spec found` -- `ambiguous story file match` -- `unrecognized status in existing story file` -- `story already blocked`(폴더+ID 디스패치 전용. 위의 `blocked spec supplied`와 다릅니다) - -`intent gap`은 실행 중 마주친 질문에 기록된 의도만으로 답할 수 없는 상태입니다. 코드가 아직 없는 계획 단계나 리뷰 단계에서 멈출 수 있습니다. 리뷰 중 이 조건으로 멈추면 작업 트리를 평소처럼 되돌립니다. 다만 시도했던 변경은 먼저 `{implementation_artifacts}` 아래의 패치 파일로 저장하고 사양의 분류 기록과 중단 출력에 경로를 기록합니다. 이 패치는 워크플로가 의도를 어떻게 해석해 구현했는지 보여 주는 구체적인 근거입니다. 그 해석이 맞다면 `git apply`로 패치를 적용하고 사양 상태를 `in-review`로 바꾸세요. 처음부터 다시 실행하지 않고 해당 변경의 리뷰를 이어갈 수 있습니다. - -## 출력 산출물 - -워크플로는 실행 결과를 나중에도 확인할 수 있는 산출물로 남깁니다. - -### 기본 사양 산출물 - -새 작업에서는 다음을 만듭니다. - -`{implementation_artifacts}/spec-.md` - -이 사양은 계획, 구현, 리뷰를 잇는 계약으로 다음 내용을 담습니다. - -- 프런트매터 상태 -- 프런트매터의 기계 상태(`followup_review_recommended`, `warnings`, `deferred`, 리비전 표시) -- 수정할 수 없는 `` 블록 -- 코드 맵 -- 작업과 인수 기준 -- 사양 변경 기록 -- 리뷰 분류 기록 -- 검증 메모 - -### 스토리 사양 산출물(폴더+ID 디스패치) - -폴더+ID 디스패치에서는 기본 사양 또는 대체 결과 경로 대신 `/stories/-.md`에 씁니다. 계획이 시작되기 전에 멈추는 경우도 여기에 포함됩니다. 이 모드에서는 아래의 대체 결과 산출물을 사용하지 않습니다. - -스토리 제목에서 slug를 만들기 전에 멈추면 쓰기 경로에 고정된 slug 조각을 사용합니다. - -| 상황 | 사용하는 slug 조각 | -| --- | --- | -| `stories.yaml`이 없거나 파싱할 수 없거나, 일치하는 항목이 없음 | `unresolved` | -| 이미 디스크에 `-*.md`와 일치하는 파일이 둘 이상 있음 | `ambiguous` | -| 항목을 찾았고 디스크의 파일 일치가 모호하지 않음 | `title`에서 만든 `slug`. 필요하면 `description`도 사용 | - -결정된 경로에 파일이 이미 있으면 워크플로는 프런트매터의 `status`를 갱신합니다. 기본 사양 산출물과 마찬가지로 `## Auto Run Result` 아래에 결과도 덧붙입니다. 파일이 없으면 최소 구성의 스토리 사양을 만듭니다. 이 파일에는 프런트매터 상태, 제목, `## Auto Run Result` 섹션이 들어갑니다. 제목은 해당 항목의 `title`을 사용합니다. 항목을 찾을 수 없거나 디스크의 파일 일치가 모호하면 `Story `를 사용합니다. - -### 대체 결과 산출물 - -폴더+ID 디스패치가 아닌 경로에서 유효한 `spec_file`이 생기기 전에 워크플로가 멈추면 다음 파일을 씁니다. - -`{implementation_artifacts}/bmad-build-auto-result-.md` - -여기에는 최종 상태와 차단 조건이 기록됩니다. - -### 추가 산출물 - -경로에 따라 워크플로가 다음도 쓸 수 있습니다. - -- `{implementation_artifacts}/epic--context.md` -- 리뷰 단계가 `intent gap`으로 멈출 때 시도했던 변경을 보존한 패치 파일(사양의 분류 기록에 경로 기록) - -## 오케스트레이터 책임 - -`bmad-build-auto`를 통합하는 오케스트레이터는 다음을 해야 합니다. - -- 한 번에 하나의 일관된 의도를 전달합니다 -- 이전 작업을 재개할 때는 사양 경로를 직접 전달하는 방식을 우선합니다. 폴더+ID 디스패치라면 같은 사양 폴더와 스토리 ID를 전달합니다 -- 생성된 사양 파일, 스토리 사양 산출물 또는 대체 결과 파일에서 최종 상태를 확인합니다 -- 채팅 출력만 보고 성공을 추정하지 말고 `status`, `blocking condition`, `followup_review_recommended`를 읽습니다 -- 사양 프런트매터의 `deferred:` 목록에서 보류된 발견 사항을 읽습니다 -- 다음 스토리가 있다면 `baseline_revision..`, 아직 없다면 종료 시점의 `baseline_revision..HEAD`로 해당 스토리의 커밋을 식별합니다 -- 자율 실행으로 파일 변경과 로컬 커밋이 생길 수 있음을 예상합니다 -- `blocked`를 단순 실패가 아니라 라우팅 신호로 처리합니다 - -`blocked`는 대개 워크플로가 사람 개입 없이 계속하기에는 안전하지 않은 상황을 만났다는 뜻입니다. 이때는 상위 오케스트레이터나 다른 워크플로, 또는 사람이 이어받는 편이 적절합니다. - -차단 원인을 해결한 뒤에는 보통 `bmad-build-auto`를 새로 실행해야 합니다. 기존 작업을 재사용하려면 자동 탐색에 기대지 말고 검증된 사양 경로를 명시적으로 전달하세요. diff --git a/docs/ko-kr/reference/commands.md b/docs/ko-kr/reference/commands.md deleted file mode 100644 index b139f6cc57..0000000000 --- a/docs/ko-kr/reference/commands.md +++ /dev/null @@ -1,136 +0,0 @@ ---- -title: 스킬 -description: BMad 스킬의 정의, 작동 방식, 위치에 대한 참조 -sidebar: - order: 4 ---- - -스킬은 IDE 안에서 에이전트를 로드하거나 워크플로를 실행하거나 작업을 처리하는 미리 작성된 프롬프트입니다. BMad 설치 프로그램은 설치 시 선택한 모듈에서 스킬을 생성합니다. 나중에 모듈을 추가, 제거, 변경했다면 설치 프로그램을 다시 실행해 스킬을 동기화하세요([문제 해결](#문제-해결) 참고). - -## 스킬 vs 에이전트 메뉴 트리거 - -BMad는 작업을 시작하는 두 가지 방법을 제공하며 목적이 다릅니다. - -| 방식 | 호출 방법 | 일어나는 일 | -| --- | --- | --- | -| **스킬** | IDE에서 스킬 이름(예: `bmad-help`)을 입력 | 에이전트를 직접 로드하거나 워크플로를 실행하거나 작업을 처리 | -| **에이전트 메뉴 트리거** | 에이전트를 먼저 로드한 뒤 짧은 코드(예: `BD`) 입력 | 에이전트가 페르소나를 유지한 채 코드를 해석하고 일치하는 워크플로를 시작 | - -에이전트 메뉴 트리거는 활성 에이전트 세션이 필요합니다. 어떤 워크플로를 원하는지 알고 있다면 스킬을 사용하세요. 이미 에이전트와 작업 중이고 대화를 떠나지 않고 작업을 바꾸고 싶다면 트리거를 사용하세요. - -## 스킬 생성 방식 - -`npx bmad-method install`을 실행하면 설치 프로그램은 선택된 모든 모듈의 매니페스트를 읽고 에이전트, 워크플로, 작업, 도구마다 스킬 하나를 생성합니다. 각 스킬은 AI에게 해당 소스 파일을 로드하고 지시를 따르라고 안내하는 `SKILL.md` 파일이 있는 폴더입니다. - -설치 프로그램은 스킬 유형별 템플릿을 사용합니다. - -| 스킬 유형 | 생성 파일의 역할 | -| --- | --- | -| **에이전트 실행기** | 에이전트 페르소나 파일을 로드하고 메뉴를 활성화하며 페르소나를 유지 | -| **워크플로 스킬** | 워크플로 설정을 로드하고 단계를 따름 | -| **작업 스킬** | 단독 실행 작업 파일을 로드하고 지시를 따름 | -| **도구 스킬** | 단독 실행 도구 파일을 로드하고 지시를 따름 | - -:::note[설치 프로그램 다시 실행] -모듈을 추가하거나 제거했다면 설치 프로그램을 다시 실행하세요. 현재 모듈 선택에 맞춰 모든 스킬 파일을 다시 생성합니다. -::: - -## 스킬 파일 위치 - -설치 프로그램은 프로젝트 안의 IDE별 디렉터리에 스킬 파일을 씁니다. 정확한 경로는 설치 중 선택한 IDE에 따라 달라집니다. - -| IDE / CLI | 스킬 디렉터리 | -| --- | --- | -| Claude Code | `.claude/skills/` | -| Cursor | `.agents/skills/` | -| Windsurf | `.agents/skills/` | -| 기타 IDE | 대상 경로는 설치 프로그램 출력 참고 | - -각 스킬은 `SKILL.md` 파일을 포함하는 폴더입니다. Claude Code 설치 예시는 다음과 같습니다. - -```text -.claude/skills/ -├── bmad-help/ -│ └── SKILL.md -├── bmad-prd/ -│ └── SKILL.md -├── bmad-agent-dev/ -│ └── SKILL.md -└── ... -``` - -디렉터리 이름이 IDE에서의 스킬 이름을 결정합니다. 예를 들어 `bmad-agent-dev/` 디렉터리는 `bmad-agent-dev` 스킬을 등록합니다. - -## 스킬 찾기 - -IDE에서 스킬 이름을 입력해 호출합니다. 일부 플랫폼은 스킬이 나타나기 전에 설정에서 활성화해야 합니다. - -다음 단계를 상황에 맞게 안내받으려면 `bmad-help`를 실행하세요. - -:::tip[빠른 탐색] -프로젝트에 생성된 스킬 디렉터리가 기준 목록입니다. 파일 탐색기에서 열면 설명이 있는 모든 스킬을 볼 수 있습니다. -::: - -## 스킬 범주 - -### 에이전트 스킬 - -에이전트 스킬은 정의된 역할, 커뮤니케이션 스타일, 워크플로 메뉴를 가진 전문 AI 페르소나를 로드합니다. 로드되면 에이전트는 페르소나를 유지하고 메뉴 트리거에 응답합니다. - -| 예시 스킬 | 에이전트 | 역할 | -| --- | --- | --- | -| `bmad-agent-dev` | Amelia(개발자) | 사양을 엄격히 준수해 스토리 구현 | -| `bmad-agent-pm` | John(제품 관리자) | PRD 생성 및 검증 | -| `bmad-agent-architect` | Winston(아키텍트) | 시스템 아키텍처 설계 | - -기본 에이전트와 트리거 전체 목록은 [에이전트](./agents.md)를 참고하세요. - -### 워크플로 스킬 - -워크플로 스킬은 에이전트 페르소나를 먼저 로드하지 않고 구조화된 다단계 프로세스를 실행합니다. 워크플로 설정을 로드하고 단계를 따릅니다. - -| 예시 스킬 | 목적 | -| --- | --- | -| `bmad-product-brief` | 제품 개요 생성 또는 업데이트 - 개념이 명확할 때 단계별 질문으로 구체화 | -| `bmad-prfaq` | 제품 개념을 스트레스 테스트하는 [워킹 백워드 PRFAQ](../explanation/analysis-phase.md#prfaq워킹-백워드) 챌린지 | -| `bmad-prd` | 제품 요구사항 문서(PRD) 생성, 업데이트, 검증 | -| `bmad-ux` | 사용자 경험 설계 | -| `bmad-architecture` | 시스템 아키텍처 설계 | -| `bmad-create-epics-and-stories` | 에픽과 스토리 생성 | -| `bmad-build` | 직접 입력한 의도, 이슈, 기능, 수정 또는 계획된 스토리 구현. [변경 사항 구현하기](../build/build-a-change.md) 참고 | -| `bmad-code-review` | 코드 리뷰 실행 | -| `bmad-build-auto` | Build 구현 모델을 사람 개입 없이 한 번 자동 실행 | - -단계별 전체 워크플로 참조는 [워크플로 맵](./workflow-map.md)을 참고하세요. - -### 작업과 도구 스킬 - -작업과 도구는 에이전트나 워크플로 컨텍스트가 필요 없는 독립 작업입니다. - -**BMad 도움말: 지능형 안내자** - -`bmad-help`는 다음에 무엇을 해야 할지 찾는 기본 인터페이스입니다. 프로젝트를 검사하고 자연어 요청을 이해한 뒤, 설치된 모듈을 기준으로 다음 필수 또는 선택 단계를 추천합니다. - -:::note[예시] -``` -bmad-help -bmad-help SaaS 아이디어가 있고 기능도 모두 알고 있습니다. 어디서 시작하나요? -bmad-help UX 설계에는 어떤 선택지가 있나요? -``` -::: - -**기타 핵심 작업과 도구** - -핵심 모듈에는 도움말, 리뷰, 개선, 커스터마이징과 사고 스킬(브레인스토밍, 아이디어 단련, 파티 모드) 등 8개의 내장 도구가 포함됩니다. 전체 목록은 [핵심 도구](./core-tools.md)를 참고하세요. - -## 이름 규칙 - -모든 스킬은 `bmad-` 접두사 뒤에 설명적인 이름을 붙입니다(예: `bmad-agent-dev`, `bmad-prd`, `bmad-help`). 사용 가능한 모듈은 [모듈](./modules.md)을 참고하세요. - -## 문제 해결 - -**설치 후 스킬이 보이지 않음.** 일부 플랫폼은 설정에서 스킬을 명시적으로 활성화해야 합니다. IDE 문서를 확인하거나 AI 어시스턴트에게 스킬 활성화 방법을 물어보세요. IDE 재시작 또는 창 새로고침이 필요할 수도 있습니다. - -**예상한 스킬이 없음.** 설치 프로그램은 선택한 모듈의 스킬만 생성합니다. `npx bmad-method install`을 다시 실행하고 모듈 선택을 확인하세요. 예상 디렉터리에 스킬 파일이 있는지 확인하세요. - -**제거한 모듈의 스킬이 계속 보임.** 설치 프로그램은 오래된 스킬 파일을 자동으로 삭제하지 않습니다. IDE 스킬 디렉터리에서 오래된 디렉터리를 제거하거나 전체 스킬 디렉터리를 삭제한 뒤 설치 프로그램을 다시 실행해 깨끗한 스킬 세트를 만드세요. diff --git a/docs/ko-kr/reference/core-tools.md b/docs/ko-kr/reference/core-tools.md deleted file mode 100644 index 25287aea0b..0000000000 --- a/docs/ko-kr/reference/core-tools.md +++ /dev/null @@ -1,255 +0,0 @@ ---- -title: 핵심 도구 -description: 핵심 모듈의 내장 스킬 참조 -sidebar: - order: 3 ---- - -모든 BMad 설치에는 **핵심 모듈**이 포함됩니다. 프로젝트, 모듈, 단계에 관계없이 두루 쓰는 작은 스킬 모음입니다. 이 페이지에서는 커널 도구와 **사고 스킬**을 설명합니다. - -:::tip[빠른 경로] -IDE에서 스킬 이름(예: `bmad-help`)을 입력해 어떤 도구든 실행하세요. 에이전트 세션은 필요 없습니다. -::: - -## 개요 - -**핵심 모듈(항상 설치됨):** - -| 도구 | 목적 | -| --- | --- | -| [`bmad-help`](#bmad-help) | 다음에 무엇을 해야 할지 상황에 맞게 안내 | -| [`bmad-advanced-elicitation`](#bmad-advanced-elicitation) | 반복 개선 기법으로 LLM 출력을 다시 검토하고 다듬음 | -| [`bmad-review`](#bmad-review) | 다중 렌즈 리뷰 - 코드용 적대적·엣지 케이스·검증 공백 렌즈와 문서용 구조·문장·표현 렌즈를 제공 | -| [`bmad-customize`](#bmad-customize) | BMad 커스터마이징 오버라이드 생성 및 검증 | - -**사고 스킬:** - -| 도구 | 목적 | -| --- | --- | -| [`bmad-brainstorming`](#bmad-brainstorming) | 대화형 브레인스토밍 세션 진행 | -| [`bmad-deep-recon`](#bmad-deep-recon) | 어떤 주제든 의사결정에 필요한 리서치를 초안·처리·실행 방식으로 수행 | -| [`bmad-forge-idea`](#bmad-forge-idea) | 아이디어를 단련해 가능성을 입증하거나 적은 비용으로 폐기할 때까지 압박 검증 | -| [`bmad-party-mode`](#bmad-party-mode) | 다중 에이전트 그룹 토론 조율 | - -:::note[이동 및 제거] -`bmad-spec`은 이제 BMM 모듈의 2단계 계획 워크플로에 포함됩니다. 자세한 위치는 [워크플로 맵](./workflow-map.md#단계-2-계획)을 참고하세요. - -`bmad-shard-doc`과 `bmad-index-docs` 유틸리티는 제거되었습니다. - -기존 `bmad-editorial-review`, `bmad-editorial-review-prose`, `bmad-editorial-review-structure`, `bmad-review-adversarial-general`, `bmad-review-edge-case-hunter`, `bmad-review-verification-gap` 스킬은 모두 `bmad-review`로 통합되었습니다. 별도의 편집 스킬은 문서 편집 렌즈가 대신합니다. 이전 ID 6개도 호환성을 위해 새 스킬로 계속 연결됩니다. - -기존 `bmad-market-research`, `bmad-domain-research`, `bmad-technical-research` 워크플로는 리서치 유형으로 `bmad-deep-recon`에 통합되었습니다. 이전 ID도 같은 방식으로 새 스킬에 연결됩니다. -::: - -## bmad-help - -**다음에 무엇을 해야 할지 알려주는 지능형 안내자입니다.** 프로젝트 상태와 완료된 작업을 확인하고 다음 필수 또는 선택 단계를 추천합니다. - -**사용 시점:** - -- 워크플로를 끝냈고 다음 단계를 알고 싶습니다 -- BMad가 처음이라 방향 안내가 필요합니다 -- 막혀서 상황에 맞는 조언이 필요합니다 -- 새 모듈을 설치한 뒤 사용할 수 있는 기능을 확인하고 싶습니다 - -**작동 방식:** - -1. 프로젝트에서 기존 산출물(PRD, 아키텍처, 스토리 등)를 스캔합니다 -2. 설치된 모듈과 사용 가능한 워크플로를 감지합니다 -3. 우선순위에 따라 다음 단계를 추천합니다. 필수 단계를 먼저, 선택 단계를 나중에 제시합니다 -4. 각 추천을 스킬 명령과 짧은 설명으로 보여줍니다 - -**입력:** 선택적 자연어 질문(예: `bmad-help SaaS 아이디어가 있는데 어디서 시작하나요?`) - -**출력:** 스킬 명령과 함께 우선순위로 정리한 다음 단계 목록 - -## bmad-advanced-elicitation - -**LLM이 최근 출력을 다시 검토하고 다듬도록 합니다.** BMad의 공통 개선 지점으로, 다른 스킬이 작업 중간에 호출할 수도 있고 사용자가 대화의 최근 내용에 직접 적용할 수도 있습니다. - -**사용 시점:** - -- LLM 출력이 얕거나 너무 일반적으로 느껴집니다 -- 여러 분석 관점에서 주제를 탐색하고 싶습니다 -- 중요한 문서를 다듬으면서 더 깊이 검토하고 싶습니다 -- 소크라테스식 질문, 제1원칙, 사전 실패 분석(pre-mortem), 레드팀처럼 이름이 정해진 기법을 쓰고 싶습니다 - -**작동 방식:** - -1. 다른 대상을 지정하지 않으면 대화의 가장 최근 출력을 대상으로 삼습니다 -2. 내용에 가장 잘 맞는 도출 기법을 짧은 메뉴로 제시합니다 -3. 선택한 기법을 대상에 적용합니다 -4. 개선본을 반환하면 호출한 흐름이 중단된 지점부터 이어집니다 - -**입력:** 기본값은 가장 최근 출력입니다. 다른 내용을 지정하거나 적용할 기법의 이름을 함께 줄 수도 있습니다. - -**출력:** 개선이 적용된 버전 - -## bmad-review - -**diff, 문서, 산출물을 여러 렌즈로 검토합니다.** 리뷰 렌즈마다 기법과 관점은 다르지만 발견 사항은 하나의 표준 형식으로 보고합니다. 발견 사항이 없어도 유효한 결과입니다. 철저해 보이려고 개수를 억지로 채우지 않습니다. 렌즈마다 적용 대상이 정해져 있으므로 diff에는 코드 렌즈를, 문서에는 편집 렌즈를 적용합니다. - -**제공되는 렌즈:** - -| 렌즈 | 적용 대상 | 기법 | -| --- | --- | --- | -| **적대적** (`adversarial`) | 모든 내용 | 빠진 것과 잘못된 것을 찾도록 발견 사항 10개 이상을 강제하며 빈 목록은 허용하지 않습니다 | -| **엣지 케이스** (`edge-case-hunter`) | 모든 내용 | 동작을 정의한 내용에서 모든 분기 경로와 경계 조건을 확인합니다 | -| **검증 공백** (`verification-gap`) | 코드 | 변경된 동작이 회귀해도 신뢰할 만한 검증에서 놓칠 부분을 찾습니다 | -| **구조** (`structure`) | 문서 | 문서 구성이 목적에 맞는지 검토하고 삭제·병합·이동·압축을 제안합니다 | -| **문장·표현** (`prose`) | 문서 | 이해를 방해하는 표현을 교정합니다 | - -두 편집 렌즈는 아이디어 자체를 비판하지 않습니다. 구성과 표현만 검토합니다. 수정안은 제안만 할 뿐 직접 적용하지 않습니다. 두 렌즈를 함께 선택하면 문장·표현 렌즈가 구조 렌즈의 발견 사항을 이어받아 검토합니다. - -렌즈 구성은 고정되어 있지 않습니다. `customize.toml`에서 렌즈를 추가하거나 기본 렌즈를 바꿀 수 있습니다. 리뷰할 때는 최종 설정에 포함된 렌즈를 실행합니다. - -**사용 시점:** - -- 산출물을 확정하기 전에 품질을 확인하고 싶습니다 -- 코드나 로직의 엣지 케이스를 빠짐없이 검토하고 싶습니다 -- 변경 사항이 충분히 검증됐는지 알고 싶습니다 -- 초안 문서를 더 간결하고 매끄럽게 다듬고 싶습니다 -- 이해도를 유지하면서 문서 길이를 줄이고 싶습니다 - -**작동 방식:** - -1. 내용을 불러온 뒤 유형(diff, 파일, 함수, 문서)과 성격(코드 또는 문서)을 확인합니다 -2. 사용자가 지정한 렌즈를 선택합니다. 따로 지정하지 않았다면 적용 대상과 조건이 맞는 활성 렌즈를 모두 선택합니다 -3. 실행할 렌즈와 다른 렌즈의 결과를 이어받을 렌즈를 먼저 알립니다 -4. 독립 렌즈부터 실행합니다. 그 결과가 필요한 렌즈는 이어서 실행합니다. 플랫폼이 지원하면 독립 렌즈는 하위 에이전트로 병렬 실행합니다 -5. 결과를 하나의 발견 사항 배열로 모읍니다. 같은 문제를 여러 렌즈가 찾았다면 단순 중복이 아니라 중요한 신호로 봅니다 - -**입력:** - -- `content`(필수) - diff, 브랜치, 커밋하지 않은 변경분, 파일, 사양, 스토리 등 검토할 내용 -- `lenses`(선택 사항) - 하나 이상의 렌즈 코드 또는 이름. 지정하지 않으면 내용에 맞는 모든 렌즈를 사용합니다 -- `also_consider`(선택 사항) - 함께 검토할 영역 -- `style_guide` / `reader_type`(선택 사항, 편집 렌즈) - 프로젝트 스타일 가이드와 독자 유형. 기본값인 `humans`는 명확성과 흐름을, `llm`은 정밀성과 일관성을 우선합니다 - -**출력:** 발견 사항을 JSON 배열 및/또는 렌즈별 Markdown 보고서로 제공합니다. 각 항목에는 `lens`, `location`, `trigger_condition`, `guard_snippet`, `potential_consequence`가 들어갑니다. 편집 렌즈는 항목별로 수락하거나 거절할 수 있는 표를 만듭니다. 구조 변경을 제안할 때는 예상 감소량도 함께 보여줍니다. - -:::note[다른 워크플로에서 사용] -다른 모듈의 코드 리뷰 워크플로는 코드 렌즈를 자동으로 실행합니다. 문서 워크플로(PRD, UX, 아키텍처, 제품 브리프)는 마무리 단계에서 편집 렌즈를 실행합니다. 스킬의 `customize.toml`에서 사용자 지정 렌즈를 추가하거나 기본 렌즈를 조정하고 비활성화할 수 있습니다. -::: - -## bmad-customize - -**커스터마이징 오버라이드를 만들고 검증합니다.** TOML을 직접 작성하지 않아도 설치된 BMad 에이전트나 워크플로의 동작을 바꿀 수 있습니다. - -**사용 시점:** - -- 에이전트나 워크플로 동작을 바꾸고 싶습니다 -- 지속 사실, 활성화 훅, 커스텀 메뉴 항목을 추가해야 합니다 -- 올바른 오버라이드 범위를 자동으로 선택하고 검증하고 싶습니다 - -**작동 방식:** - -1. 설치된 BMad 스킬에서 커스터마이징 가능한 영역을 스캔합니다 -2. 요청한 변경에 맞는 범위를 선택합니다 -3. `_bmad/custom/` 아래에 오버라이드 파일을 작성합니다 -4. 병합된 설정을 검증합니다 - -**입력:** 원하는 커스터마이징을 설명하는 자연어 - -**출력:** `_bmad/custom/` 아래의 TOML 오버라이드 파일 - -BMad 커스터마이징에 대한 자세한 가이드는 [BMad 커스터마이징 방법](../how-to/customize-bmad.md)을 참고하세요. - -## 사고 스킬 - -아래 스킬은 어느 단계나 모듈에서도 쓸 수 있는 범용 사고 도구입니다. - -### bmad-brainstorming - -**대화형 창의 기법으로 다양한 아이디어를 생성합니다.** 검증된 발상법을 기법 라이브러리에서 불러와 아이디어를 100개 이상 끌어낸 뒤 정리하는 브레인스토밍 세션입니다. - -**사용 시점:** - -- 새 프로젝트를 시작하고 문제 영역을 탐색해야 합니다 -- 아이디어 생성이 막혀 구조화된 창의 기법이 필요합니다 -- SCAMPER, 역브레인스토밍 같은 검증된 아이디어 발상 프레임워크를 사용하고 싶습니다 - -**작동 방식:** - -1. 주제로 브레인스토밍 세션을 설정합니다 -2. 기법 라이브러리에서 창의 기법을 로드합니다 -3. 기법을 하나씩 진행하며 아이디어를 생성합니다 -4. 편향 방지 프로토콜을 적용합니다. 10개 아이디어마다 창의 영역을 바꿔 군집화를 방지합니다 -5. 모든 아이디어를 기법별로 정리한 누적형 세션 문서를 만듭니다 - -**입력:** 브레인스토밍 주제 또는 문제 설명, 필요한 경우 컨텍스트 파일 - -**출력:** 세션을 보관하는 독립형 `brainstorm.html`, 필요한 경우 후속 스킬에 넘길 `brainstorm-intent.md`, 그리고 `.memlog.md` 세션 기록 - -:::note[수량 목표] -핵심은 아이디어가 50개에서 100개 사이로 늘어나는 구간에서 나옵니다. 이 워크플로는 정리 전에 100개 이상의 아이디어 생성을 권장합니다. -::: - -### bmad-deep-recon - -**어떤 주제든 의사결정에 필요한 수준으로 세 가지 방식의 리서치를 수행합니다.** 이미 구독 중인 AI 도구에서 사용할 심층 리서치 프롬프트를 작성하거나, 완성된 보고서를 후속 스킬이 바로 쓸 수 있는 인용 포함 요약으로 정리합니다. 여러 웹 리서치를 병렬로 진행해 현재 환경에서 직접 실행할 수도 있습니다. - -**사용 시점:** - -- 모델의 기억이 아니라 근거로 결정해야 합니다 -- 시장, 도메인, 기술, 경쟁, 사용자 의견 또는 문헌 리서치가 필요합니다 -- 어떤 출처에서든 받은 리서치 보고서를 후속 작업에 맞게 정리하고 싶습니다 -- 이름이 정해진 여러 선택지를 체계적으로 비교하고 싶습니다 - -**작동 방식:** - -1. 초안, 처리, 실행 중 모드를 감지하고 요청에서 리서치 유형을 추론합니다 -2. 우선순위를 둔 분석 차원, 출처 탐색법, 최신성 규칙이 담긴 유형별 팩을 불러옵니다 -3. 실행 모드는 한 번의 게이트에서 계획합니다. 그런 다음 서로 컨텍스트가 격리된 리서치 어시스턴트를 투입해 수집하는 주장을 즉시 검증합니다 -4. 초안과 처리 모드는 사용자가 쓰는 심층 리서치 도구를 오갑니다 -5. Refresh와 Deepen은 전체를 다시 조사하지 않고 기존 보고서를 갱신합니다 - -**입력:** 결정과 주제, 처리할 보고서 또는 새로 갱신할 기존 리서치 폴더 - -**출력:** 메타데이터 프런트매터와 인용을 갖춘 `research.md`, 선택 사항인 독립 실행형 HTML 브리핑 - -세 가지 모드, 선택 기준, 실행 내부 동작은 [Deep Recon](../explanation/deep-recon.md)을 참고하세요. - -### bmad-forge-idea - -**아이디어가 단단해지거나 가능성이 입증되거나, 적은 비용으로 폐기될 때까지 압박 검증합니다.** 적대적인 질문자가 아직 덜 다듬어진 아이디어를 한 번에 하나의 질문으로 파고듭니다. 논점마다 두 페르소나를 참여시키며, 남은 아이디어에 확신을 갖고 행동할 수 있을 때까지 진행합니다. - -**사용 시점:** - -- 투자하기 전에 아이디어를 스트레스 테스트하고 싶습니다 -- 아이디어를 폐기할지 말지에 대한 정직한 판단이 필요합니다 -- 동의만 하는 상대가 아니라 반박하는 사고 파트너가 필요합니다 - -**작동 방식:** - -1. 먼저 목표를 정하고 그 목표에 맞춰 질문 방향을 조정합니다 -2. 의존성 순서에 따라 한 번에 하나의 질문을 다루며, 사용자가 반박할 수 있도록 권장 답을 제시합니다 -3. 논점마다 두 관점을 더합니다. 하나는 설치된 명단에서 고르고, 다른 하나는 주제에 맞춰 즉석에서 만듭니다 -4. 모호한 용어를 짚고 기존 프로젝트 자료와 주장을 대조합니다 -5. 단련됨, 폐기됨, 명확해짐 중 하나로 결론을 내리고, 보관할 수 있는 독립 보고서를 남깁니다 - -**입력:** 기능, 비즈니스 모델, 연구 가설, 개인적 결정 등 어떤 도메인의 아이디어든 가능 - -**출력:** 아이디어가 단련된 경우 필요에 따라 `forged-idea.md` 정제본을 만들고, 실행할 때마다 보관용 `forge-report.html` 보고서를 생성 - -### bmad-party-mode - -**다중 에이전트 그룹 토론을 조율합니다.** 설치된 모든 BMad 에이전트를 로드하고 각 에이전트가 고유한 전문성과 페르소나로 기여하는 자연스러운 대화를 진행합니다. - -**사용 시점:** - -- 결정에 여러 전문가 관점이 필요합니다 -- 에이전트들이 서로의 가정에 도전하길 원합니다 -- 여러 도메인에 걸친 복잡한 주제를 탐색합니다 - -**작동 방식:** - -1. 설치된 모든 에이전트 페르소나가 있는 에이전트 매니페스트를 로드합니다 -2. 주제를 분석해 가장 관련 있는 에이전트 2-3개를 선택합니다 -3. 에이전트들이 차례로 의견을 내고 자연스럽게 서로 대화하며 이견을 드러냅니다 -4. 참여 에이전트를 차례로 바꿔 다양한 관점이 고르게 나오도록 합니다 -5. `goodbye`, `end party`, `quit`로 종료합니다 - -**입력:** 토론 주제 또는 질문, 참여시키고 싶은 페르소나 지정(선택 사항) - -**출력:** 각 에이전트의 페르소나를 유지하는 실시간 다중 에이전트 대화 diff --git a/docs/ko-kr/reference/modules.md b/docs/ko-kr/reference/modules.md deleted file mode 100644 index 68ed6e09ed..0000000000 --- a/docs/ko-kr/reference/modules.md +++ /dev/null @@ -1,76 +0,0 @@ ---- -title: 공식 모듈 -description: 커스텀 에이전트, 창의적 지능, 게임 개발, 테스트를 위한 추가 모듈 -sidebar: - order: 5 ---- - -BMad는 설치 중 선택하는 공식 모듈로 확장됩니다. 이러한 추가 모듈은 내장 핵심 기능과 BMM(애자일 제품군)을 넘어 특정 도메인을 위한 전문 에이전트, 워크플로, 작업을 제공합니다. - -:::tip[모듈 설치] -`npx bmad-method install`을 실행하고 원하는 모듈을 선택하세요. 설치 프로그램이 다운로드, 설정, IDE 통합을 자동으로 처리합니다. -::: - -## BMad 빌더(BMB) - -단계별 안내를 받으며 커스텀 에이전트, 워크플로, 도메인 특화 모듈을 만듭니다. BMad 빌더는 프레임워크 자체를 확장하는 메타 모듈입니다. - -- **코드:** `bmb` -- **npm:** [`bmad-builder`](https://www.npmjs.com/package/bmad-builder) -- **GitHub:** [bmad-code-org/bmad-builder](https://github.com/bmad-code-org/bmad-builder) - -**제공:** - -- 에이전트 빌더 - 전문 지식과 도구 접근 권한을 맞춤 설정한 AI 에이전트 생성 -- 워크플로 빌더 - 단계와 결정 지점이 있는 구조화된 프로세스 설계 -- 모듈 빌더 - 에이전트와 워크플로를 공유 및 게시 가능한 모듈로 패키징 -- YAML 설정과 npm 게시를 지원하는 대화형 구성 과정 - -## 창의적 지능 제품군(CIS) - -초기 개발 단계의 구조화된 창의성, 아이디어 발상, 혁신을 위한 AI 기반 도구입니다. 이 제품군은 검증된 프레임워크를 사용해 브레인스토밍, 디자인 사고, 문제 해결을 진행하는 여러 에이전트를 제공합니다. - -- **코드:** `cis` -- **npm:** [`bmad-creative-intelligence-suite`](https://www.npmjs.com/package/bmad-creative-intelligence-suite) -- **GitHub:** [bmad-code-org/bmad-module-creative-intelligence-suite](https://github.com/bmad-code-org/bmad-module-creative-intelligence-suite) - -**제공:** - -- 혁신 전략가, 디자인 사고 코치, 브레인스토밍 코치 에이전트 -- 체계적 사고와 수평적 사고를 위한 문제 해결자와 창의적 문제 해결자 -- 내러티브와 피치를 위한 스토리텔러와 발표 마스터 -- SCAMPER, 역브레인스토밍, 문제 재구성을 포함한 아이디어 발상 프레임워크 - -## 게임 개발 스튜디오(GDS) - -Unity, Unreal, Godot, 커스텀 엔진에 맞춘 구조화된 게임 개발 워크플로입니다. 신속한 프로토타이핑부터 에픽 중심 스프린트를 사용하는 전체 규모 제작까지 다양한 계획 깊이를 지원합니다. 구현은 Build로 통합됩니다. - -- **코드:** `gds` -- **npm:** [`bmad-game-dev-studio`](https://www.npmjs.com/package/bmad-game-dev-studio) -- **GitHub:** [bmad-code-org/bmad-module-game-dev-studio](https://github.com/bmad-code-org/bmad-module-game-dev-studio) - -**제공:** - -- 게임 디자인 문서 생성 워크플로 -- 표준 Build 구현 루프에 필요한 게임별 계획 및 컨텍스트 -- 캐릭터, 대화, 세계관 구축을 위한 내러티브 디자인 지원 -- 21개 이상의 게임 유형과 엔진별 아키텍처 가이드 - -## 테스트 설계자(TEA) - -전문가 에이전트와 구조화된 워크플로 9개로 엔터프라이즈급 테스트 전략, 자동화 가이드, 릴리스 게이트 결정을 지원합니다. TEA는 위험도 기반 우선순위와 요구사항 추적성까지 제공해 내장 QA 스킬보다 훨씬 넓은 범위를 다룹니다. 두 경로 중 어느 쪽을 선택할지는 [완료된 작업 테스트하기](../build/test-completed-work.md)를 참고하세요. - -- **코드:** `tea` -- **npm:** [`bmad-method-test-architecture-enterprise`](https://www.npmjs.com/package/bmad-method-test-architecture-enterprise) -- **GitHub:** [bmad-code-org/bmad-method-test-architecture-enterprise](https://github.com/bmad-code-org/bmad-method-test-architecture-enterprise) - -**제공:** - -- Murat 에이전트(마스터 테스트 아키텍트 겸 품질 조언자) -- 테스트 설계, ATDD, 자동화, 테스트 리뷰, 추적성 워크플로 -- NFR 평가, CI 설정, 프레임워크 초기 구조 생성 -- P0-P3 우선순위 지정, 필요에 따라 Playwright 유틸리티와 MCP 통합 지원 - -## 커뮤니티 모듈 - -커뮤니티 모듈과 모듈 마켓플레이스가 준비 중입니다. 업데이트는 [BMad GitHub 조직](https://github.com/bmad-code-org)을 확인하세요. diff --git a/docs/ko-kr/reference/workflow-map.md b/docs/ko-kr/reference/workflow-map.md deleted file mode 100644 index 925186c4f1..0000000000 --- a/docs/ko-kr/reference/workflow-map.md +++ /dev/null @@ -1,102 +0,0 @@ ---- -title: '워크플로 맵' -description: BMad Method의 단계, 워크플로, 산출물을 정리한 참고 자료 -sidebar: - order: 1 ---- - -BMad Method(BMM)는 소프트웨어 전달 과정을 네 단계로 구성합니다. 선택형 탐색에서 계획, 솔루션 설계, 구현으로 이어지며 각 단계에서는 현재 작업에 필요한 만큼의 컨텍스트만 추가합니다. - -변경에 이 맵을 어느 정도까지 적용할지는 [개발 경로 선택하기](../how-to/choose-a-development-path.md)를 참고하세요. 아래 스킬은 이름으로 바로 실행할 수 있습니다. 설치된 프로젝트에서 다음 작업을 확신하기 어렵다면 `bmad-help`를 실행하세요. - - - -

- 다이어그램 새 탭에서 열기 ↗ -

- -## 단계 1: 분석(선택) - -계획을 확정하기 전에 문제 영역을 탐색하고 아이디어를 검증합니다. [**각 도구가 무엇을 하고 언제 쓰는지 알아보기**](../explanation/analysis-phase.md). - -| 워크플로 | 목적 | 산출물 | -| --- | --- | --- | -| `bmad-brainstorming` | 브레인스토밍 코치의 안내를 받아 프로젝트 아이디어를 발산합니다 | `brainstorm.html` 보관본과 선택적 `brainstorm-intent.md` | -| `bmad-forge-idea` | 아이디어를 단련하고 입증하거나 적은 비용으로 폐기할 때까지 압박 검증합니다 | 매 실행마다 `forge-report.html`; 아이디어가 단련되면 `forged-idea.md` | -| `bmad-deep-recon` | 의사결정을 위해 어떤 주제든 조사합니다. 심층 리서치 도구용 프롬프트를 만들거나, 해당 도구의 보고서를 처리하거나, 현재 환경에서 리서치를 실행합니다. 검증과 인용을 포함한 여섯 가지 유형 팩을 제공합니다 | 리서치 보고서 또는 요약 + 선택적 HTML 브리핑 | -| `bmad-product-brief` | 전략적 비전을 포착합니다. 개념이 명확할 때 가장 좋습니다 | `brief.md` + `addendum.md`, 필요한 HTML 또는 프레젠테이션 출력 | -| `bmad-prfaq` | 워킹 백워드 방식으로 제품 개념을 고객 우선 관점에서 스트레스 테스트합니다 | `prfaq-{project}.md` | - -Deep Recon의 세 가지 모드와 리서치 실행 내부 동작은 [Deep Recon](../explanation/deep-recon.md)을 참고하세요. - -## 단계 2: 계획 - -무엇을 누구를 위해 만들지 정의합니다. - -| 워크플로 | 목적 | 산출물 | -| --- | --- | --- | -| `bmad-prd` | PRD를 생성, 업데이트, 검증합니다. 단계별 질문으로 요구사항을 구체화하며 세 가지 의도를 하나의 스킬에서 처리합니다 | 생성/업데이트: `prd.md`, `addendum.md`, `.memlog.md`; 검증: `validation-report.html` + `.md` | -| `bmad-ux` | UX가 중요할 때 사용자 경험을 설계합니다. DESIGN.md(시각)와 EXPERIENCE.md(동작)라는 두 핵심 문서를 만듭니다 | `DESIGN.md`, `EXPERIENCE.md`, `.memlog.md` | -| `bmad-spec` | 브리프, PRD, 대화록, 브레인 덤프, 디자인 폴더 같은 다양한 의도 입력을 간결한 `SPEC.md` 계약과 동반 파일로 정제합니다. HOW를 정하기 전에 WHAT을 확정합니다 | `{output_folder}/specs/spec-{slug}/` 아래 `SPEC.md` + 동반 파일, 필요한 경우 `stories.yaml` | - -:::tip[하나의 스킬 안에 세 의도] -`bmad-prd`는 전체 PRD 수명주기를 처리합니다. 호출할 때 의도를 말하거나 스킬이 물어보게 하세요. - -- **생성** - 단계별 질문으로 요구사항을 구체화해 처음부터 새 PRD를 만듭니다. `prd.md`, `addendum.md`, `.memlog.md`를 생성합니다 -- **업데이트** - 기존 PRD와 변경 신호를 조정하고 변경을 적용하기 전에 충돌을 식별합니다 -- **검증** - 설정 가능한 체크리스트로 PRD를 비판적으로 검토하고 구조화된 HTML 발견 사항 보고서를 생성합니다 -::: - -:::note[`bmad-spec`] -`bmad-spec`은 기계가 읽을 수 있는 표준 계약을 만듭니다. 다섯 필드 커널(Why, Capabilities, Constraints, Non-goals, Success signal)과 동반 파일로 구성되며 원문의 핵심 주장을 모두 보존했는지 검증합니다. `SPEC.md`를 작성할 수 있는 유일한 스킬입니다. 다른 스킬은 의도를 표현하거나 업데이트해야 할 때 비대화형 모드로 이 스킬을 호출합니다. 요청하면 스토리 분해(Story Breakdown)를 실행해 여러 세션에서 에픽을 구현할 때 사용할 순서가 지정된 `stories.yaml`도 만듭니다. [개발 경로 선택하기](../how-to/choose-a-development-path.md#4-에픽-규모-작업-시작)를 참고하세요. -::: - -:::tip[상위 입력: `bmad-product-brief`] -`bmad-product-brief`(단계 1)는 `bmad-prd`가 요구사항을 구체화할 때 입력으로 사용할 수 있는 `product-brief.md`를 생성합니다. 재설명을 줄이고 두 문서를 서로 맞춰 유지합니다. 두 스킬이 서로 필수는 아닙니다. 무엇을 만들지 이미 안다면 `bmad-prd`로 바로 시작하세요. -::: - -## 단계 3: 솔루션 설계 - -어떻게 만들지 결정하고 작업을 스토리로 나눕니다. - -| 워크플로 | 목적 | 산출물 | -| --- | --- | --- | -| `bmad-architecture` | 기술 결정을 명시적으로 만듭니다 | 기본 핵심 문서는 `ARCHITECTURE-SPINE.md`이며 필요한 출력이나 프레젠테이션 형태로 확장해 씁니다 | -| `bmad-create-epics-and-stories` | 요구사항을 구현 가능한 작업으로 나눕니다 | 스토리가 있는 에픽 파일 | -| `bmad-sprint-planning` | 구현 전 준비도 게이트를 거친 뒤 스토리 추적과 상태 보기를 제공합니다 | PASS/CONCERNS/FAIL + `sprint-status.yaml` | - -준비도 게이트, 결정론적 추적, 상태 보기가 함께 작동하는 방식은 [스프린트 계획](../../plan/break-work-into-stories-and-track-it.md)을 참고하세요. - -## 단계 4: 구현 - -구현은 세션 단위의 작업으로 진행합니다. `bmad-build`는 사람이 참여하는 작업 단위를, `bmad-build-auto`는 무인 작업 단위 하나를 처리합니다. 큰 계획 경로는 이러한 작업 단위에 필요한 컨텍스트를 만들고 보존합니다. 사람이 참여하는 경로는 [변경 사항 구현하기](../build/build-a-change.md), 완성된 변경을 살펴보는 방법은 [변경 사항 둘러보기](../build/walk-through-a-change.md), 테스트 경로를 고르는 방법은 [완료된 작업 테스트하기](../build/test-completed-work.md)를 참고하세요. - -| 워크플로 | 목적 | 산출물 | -| --- | --- | --- | -| `bmad-build` | 직접 입력한 의도나 계획된 스토리 하나를 사람의 체크포인트를 거쳐 구현하고 검토 | 구현 기록 + 코드 | -| `bmad-build-auto` | 호출자 또는 오케스트레이터를 위해 작업 단위 하나를 무인으로 구현하고 검토 | 구현 기록 + 코드 + 종료 상태 | -| `bmad-code-review` | 필요할 때 원하는 코드 변경을 별도로 리뷰 | 발견 사항 + 적용된 패치 | -| `bmad-correct-course` | 스프린트 중 의미 있는 변경 처리 | 업데이트된 계획 또는 경로 재조정 | -| `bmad-retrospective` | 완료된 에픽을 인수 기준과 근거에 따라 검토 | 회고 문서, 실행 항목, 인수 판정 | - -### 직접 진입과 계획 후 진입 - -명확한 단일 세션 작업은 `bmad-build`에 바로 넣을 수 있습니다. 사양 기반 에픽은 스토리 분해로 하나의 `SPEC.md` 아래에 여러 작업 단위를 만듭니다. 여러 에픽으로 구성된 프로젝트라면 각 작업 단위를 선택하기 전에 PRD, UX, 아키텍처, 에픽, 준비도 결과, 스프린트 추적을 추가할 수 있습니다. - -Build Auto 자체가 이 작업 단위를 조율하지는 않습니다. AI 코딩 세션이나 bmad-loop 같은 별도 오케스트레이터가 작업 단위마다 작업자 하나를 선택하고 실행합니다. 작업자와 오케스트레이션 계약은 [자율 개발 루프](./build-auto.md)를 참고하세요. - -## 컨텍스트 관리 - -각 문서는 이후 결정에 필요한 컨텍스트가 됩니다. PRD는 제품 요구사항을, 아키텍처는 각 구현 단위가 따라야 할 패턴과 경계를 기록합니다. 사양과 스토리 기록은 작업을 나누고 다시 합치는 동안 의도, 결정, 완료 상태를 보존합니다. - -### 프로젝트 컨텍스트 - -:::tip[권장] -AI 에이전트가 모든 워크플로에서 프로젝트 규칙을 따르도록 저장소를 설정하세요. `bmad-project-context`가 `AGENTS.md`의 간결하고 검증된 규칙 블록을 관리합니다. 계획이 끝날 때 아키텍처를 바탕으로 만들거나, 언제든 기존 코드베이스에서 필요한 규칙을 찾아 만들 수 있습니다. -::: - -**만드는 방법:** - -- `bmad-project-context`를 실행하세요. 그린필드는 사양 또는 아키텍처에서 시작합니다. 브라운필드는 코드베이스에서 규칙을 찾고 검증한 뒤 사용자 확인을 거칩니다. 이전 `bmad-generate-project-context`는 폐기됐으며 이 스킬로 연결됩니다. 기존 `project-context.md`가 있다면 내용을 흡수할지 제안합니다. - -[**프로젝트 컨텍스트 더 알아보기**](../explanation/project-context.md) diff --git a/docs/ko-kr/start/build-your-first-change.md b/docs/ko-kr/start/build-your-first-change.md deleted file mode 100644 index 7f2a0b76cb..0000000000 --- a/docs/ko-kr/start/build-your-first-change.md +++ /dev/null @@ -1,98 +0,0 @@ ---- -title: '시작하기' -description: BMad를 설치하고 작은 Python 프로그램 만들기 ---- - -BMad는 작은 버그 수정부터 코드가 수백만 줄에 이르는 프로젝트까지 계획하고 구현할 수 있도록 돕습니다. 먼저 작은 작업부터 시작해 보겠습니다. - -이미 저장소가 있고 간단한 변경 사항을 구현하려면 [해당 저장소에 BMad를 설치](./install-bmad.md)하세요. 저장소에서 코딩 도구를 열고 설치된 `bmad-build` 스킬을 실행한 뒤 원하는 변경 사항을 설명하면 됩니다. - -그렇지 않다면 여기서 시작하세요. 빈 프로젝트에 작동하는 Python 프로그램을 만들어 봅니다. 이 튜토리얼은 하나의 명확한 요청을 `bmad-build` 스킬에 바로 전달하는 [단일 세션 개발 경로](../how-to/choose-a-development-path.md)를 따릅니다. - -:::note[시작하기 전에] -Node.js 20.12 이상, Python 3, BMad가 지원하는 코딩 도구가 설치된 macOS 또는 Linux 셸을 사용하세요. 아래 설치 및 실행 명령은 Claude Code를 기준으로 합니다. 다른 지원 도구를 사용한다면 BMad를 설치할 때 해당 도구를 선택하고 그곳에서 `bmad-build` 스킬을 실행하세요. -::: - -## 빈 프로젝트 만들기 - -```bash -mkdir bmad-first-project -cd bmad-first-project -``` - -현재 안정 버전의 BMad Method를 설치합니다. 다음 명령은 Claude Code용으로 설정합니다. - -```bash -npx bmad-method install --directory . --modules bmm --tools claude-code --yes -``` - -이 디렉터리에서 코딩 도구를 엽니다. Claude Code에서는 다음 명령을 실행하세요. - -```bash -claude -``` - -## Mars Rover 만들기 - -`bmad-build` 스킬에 별도의 설계 선택 사항을 덧붙이지 말고 프로그래밍 연습에 쓰이는 작은 예제인 [Mars Rover 프로그래밍 카타](https://codingdojo.org/kata/mars-rover/)를 만들어 달라고 요청합니다. - -```text -/bmad-build Mars Rover 카타를 구현해 줘 -``` - -이렇게 요청하면 `bmad-build` 스킬이 원하는 결과를 물어볼 여지가 생깁니다. 다음과 같은 질문으로 시작할 수 있습니다. - -```text -`bmad-build`: Before implementation, I need one choice: which language should I use? -사용자: Python 3으로 만들어 줘. 로컬에서 실행할 수 있는 작은 고전식 터미널 프로그램으로 만들고, -Python 표준 라이브러리 외의 의존성은 사용하지 마. -``` - -실제로 주고받는 질문과 답변, 계획, 완성된 프로그램은 예시와 다를 수 있습니다. 예시 답변을 그대로 복사하기보다 원하는 동작을 선택하세요. - -질문에 답한 뒤 계획을 읽어 보세요. 그대로 승인하거나 변경을 요청하세요. 그러면 스킬이 프로그램을 작성하고 작업 내용을 점검합니다. 문제가 있으면 수정한 뒤 변경 사항을 보여줍니다. - -## Mars Rover 실행하기 - -요청에 따라 결과는 달라집니다. 예를 들면 다음과 같습니다. - -```bash -python3 mars_rover.py --size 5x5 --obstacle 2,2 -``` - -`FFRFF`, `MAP`, `QUIT`를 차례로 입력하세요. 터미널에서 로버가 장애물 앞에 멈춘 모습을 확인합니다. - -```text -MARS ROVER CONTROL -Commands: F/M forward, B backward, L/R turn, MAP, STATUS, HELP, QUIT -Position: (0, 0) Heading: N -rover> Position: (1, 2) Heading: E -OBSTACLE: movement blocked at (2, 2) -rover> 4 . . . . . - 3 . . . . . - 2 . > # . . - 1 . . . . . - 0 . . . . . - 0 1 2 3 4 -rover> Mission control signing off. -``` - -최종 메시지에 나열된 파일을 열어 완성된 프로그램을 확인하세요. - -## BMad Help에 물어보기 - -`bmad-help` 스킬은 BMad에 관한 질문에 답합니다. 어떤 작업이 이루어졌는지 이해하거나 다음 작업을 정하거나 문제를 해결할 때 사용하세요. 지금 바로 실행해 보세요. - -```text -/bmad-help bmad-build가 방금 무엇을 했는지 설명해 줘. -``` - -## 완성했습니다 - -Mars Rover 예제에서 `bmad-build` 스킬이 짧은 요청을 실행 가능한 소프트웨어로 구현하는 과정을 살펴봤습니다. 스킬은 요청을 명확히 하고 사용자가 승인할 계획을 제시한 뒤 프로그램을 작성하고 점검해 결과를 보여줬습니다. - -## 계속 만들기 - -1. [내 저장소에 BMad를 설치](./install-bmad.md)한 다음, `bmad-build` 스킬을 실행하고 작은 변경 사항을 짧게 설명해 보세요. 사람이 참여하는 경로는 [변경 사항 구현하기](../build/build-a-change.md)를 참고하세요. -2. 성숙한 코드베이스에서 작은 변경을 구현한 뒤 작성된 사양으로 더 큰 변경까지 진행하려면 [더 깊이 알아보기](../tutorials/getting-deeper.md)를 계속 읽으세요. -3. 다음 변경에 여러 구현 세션이나 에픽이 필요할 수 있다면 [개발 경로 선택하기](../how-to/choose-a-development-path.md)를 참고하세요. diff --git a/docs/ko-kr/start/install-bmad.md b/docs/ko-kr/start/install-bmad.md deleted file mode 100644 index 2f894ea5ce..0000000000 --- a/docs/ko-kr/start/install-bmad.md +++ /dev/null @@ -1,88 +0,0 @@ ---- -title: 'BMad 설치 방법' -description: 프로젝트에 BMad를 설치하고 확인, 업데이트, 재설정하는 방법 ---- - -`npx bmad-method install`로 프로젝트에 BMad를 설치하고 AI 코딩 도구와 연동할 수 있습니다. 나중에 업데이트할 때도 같은 명령을 사용합니다. - -## 사용 시점 - -- 새 프로젝트나 기존 프로젝트에 BMad를 설치할 때 -- 지원되는 AI 코딩 도구에 BMad 스킬을 연결할 때 -- 기존 BMad 설치를 업데이트할 때 -- 모듈을 추가·제거하거나 도구와 설치 설정을 변경할 때 - -:::note[필수 조건] - -- 설치 프로그램을 실행하려면 **Node.js 20.12 이상**이 필요합니다. -- 설치된 스킬을 사용하려면 **지원되는 AI 코딩 도구**가 필요합니다. 현재 지원 목록은 `npx bmad-method install --list-tools`로 확인할 수 있습니다. -- `bmad-build`, `bmad-build-auto`처럼 `uv`로 Python을 실행하거나 결과물을 렌더링하는 스킬에는 **uv**가 필요합니다. `uv`가 없어도 설치는 끝나지만 경고가 표시되며 설치하기 전까지 해당 스킬은 작동하지 않습니다. -- Git에서 외부 또는 사용자 정의 모듈을 설치할 때만 **Git**이 필요합니다. - -::: - -## BMad 설치 및 확인 - -### 1. 대상 프로젝트 열기 - -터미널에서 BMad를 설치할 프로젝트로 이동하세요. 다른 위치를 지정하지 않으면 현재 디렉터리에 설치됩니다. - -### 2. 설치 프로그램 실행 - -```bash -npx bmad-method install -``` - -화면의 안내를 따르세요. 선택 항목은 모듈과 도구 연동이 바뀌면서 달라질 수 있지만 설치 프로그램이 사용 가능한 모듈과 설정, 지원되는 AI 코딩 도구를 차례로 안내합니다. - -오류나 경고가 표시되면 함께 제시된 조치에 따르세요. `uv` 누락 경고는 설치를 중단하지 않지만 `uv`가 필요한 스킬은 설치하기 전까지 사용할 수 없습니다. - -### 3. 완료 요약 확인 - -설치가 끝나면 **BMAD is ready to use!** 메시지와 설치 경로가 표시됩니다. 추가 조치가 필요한 경고도 함께 나옵니다. - -### 4. 도구 연동 확인 - -프로젝트 디렉터리에서 선택한 AI 코딩 도구를 열고 `bmad-help` 스킬을 실행하세요. 다음에 무엇을 해야 하는지 물어보면 됩니다. 도구가 스킬을 인식해 실행한다면 연동이 끝난 것입니다. - -## BMad 업데이트 또는 재설정 - -### 1. 설치 프로그램 다시 실행 - -`_bmad` 디렉터리가 있는 프로젝트에서 다음 명령을 실행하세요. - -```bash -npx bmad-method install -``` - -### 2. 감지된 경로 선택 - -설치 프로그램은 기존 설치를 감지하고 현재 상태에 맞는 업데이트 또는 수정 경로를 보여줍니다. 기존 설정을 새로 고치려면 업데이트를, 모듈·도구·설정을 바꾸려면 수정을 선택하세요. 이후 화면의 안내를 따르면 됩니다. - -### 3. 업데이트된 연동 확인 - -완료 요약을 확인하고 필요하면 AI 코딩 도구를 다시 연 뒤 `bmad-help`를 실행하세요. - -## 사전 릴리스 설치 - -사전 릴리스 버전의 core와 BMM을 설치하고 이번 실행에서 선택한 외부 모듈에도 사전 릴리스 선택을 적용하려면 다음 명령을 사용하세요. - -```bash -npx bmad-method@next install -``` - -사전 릴리스 설치를 업데이트할 때도 같은 명령을 다시 실행합니다. 사전 릴리스 빌드는 더 자주 바뀌고 완료되지 않은 변경이 포함될 수 있으므로, 일반적인 프로젝트 작업에는 안정 버전을 사용하세요. - -## 헤드리스 CI 설치 - -새 환경에서 BMM을 Claude Code용으로 설정하는 일반적인 헤드리스 설치 명령은 다음과 같습니다. - -```bash -npx bmad-method install --yes --modules bmm --tools claude-code -``` - -현재 자동화 플래그는 `npx bmad-method install --help`로, 올바른 도구 ID는 `npx bmad-method install --list-tools`로 확인하세요. 자동화에서 `@next`나 특정 패키지 버전을 사용한다면 도움말을 확인하고 설치할 때도 같은 태그나 버전을 사용해야 합니다. - -## 설치 결과 - -BMad 스킬은 선택한 AI 도구가 사용하는 스킬 디렉터리에 설치됩니다. 프로젝트의 `_bmad` 디렉터리에는 스킬이 공통으로 사용하는 설정과 지원 스크립트가 저장됩니다. 설치가 끝나면 설정된 도구와 남아 있는 경고를 확인할 수 있습니다. diff --git a/docs/ko-kr/tutorials/getting-deeper.md b/docs/ko-kr/tutorials/getting-deeper.md deleted file mode 100644 index ee7b5d7f89..0000000000 --- a/docs/ko-kr/tutorials/getting-deeper.md +++ /dev/null @@ -1,230 +0,0 @@ ---- -title: '더 깊이 알아보기' -description: Build와 BMad Spec으로 특정 Django 버전의 명령 확장하기 -sidebar: - order: 1 ---- - -작은 프로젝트에서 Build를 사용해 봤다면 이제 특정 버전의 Django에 적용해 볼 차례입니다. 먼저 범위가 분명한 명령 변경 하나를 구현합니다. 그다음 하나의 BMad Spec으로 정의한 관련 스토리 세 개를 구현합니다. 두 실습에서는 [단일 세션 경로와 에픽 규모 개발 경로](../how-to/choose-a-development-path.md)를 차례로 살펴봅니다. - -:::note[필수 조건] -Git, Node.js 20.12+와 `npx`, [uv](https://docs.astral.sh/uv/getting-started/installation/), BMad가 지원하는 코딩 도구가 설치된 macOS 또는 Linux 셸을 사용하세요. 계속하기 전에 [첫 변경 사항 구현하기](../start/build-your-first-change.md)를 완료하세요. 아래 설치 및 실행 명령은 Claude Code를 기준으로 합니다. 다른 지원 도구에서도 Build를 실행할 수 있습니다. VS Code는 선택 사항이지만 있으면 편리합니다. `code` 명령을 사용할 수 있으면 Build가 완성된 작업을 VS Code에서 직접 열어 줍니다. -::: - -## 1. 정확한 Django 버전 체크아웃하기 - -Django 5.2.4를 새 디렉터리에 복제합니다. 예상한 소스 코드인지 확인한 뒤 실습용 브랜치를 만듭니다. - -```bash -git clone --depth 1 --branch 5.2.4 https://github.com/django/django.git bmad-django -cd bmad-django -git rev-parse HEAD -git switch -c bmad-getting-deeper -``` - -`git rev-parse HEAD`는 다음 값을 출력해야 합니다. - -```text -c941d0deec0ea08a30670be0fac879f2372f071b -``` - -## 2. Django 편집 환경 준비하기 - -Python 3.12를 준비합니다. 예제 앱이 현재 Django 체크아웃을 사용하도록 설치한 뒤 저장소 옆에 작은 Django 프로젝트를 만듭니다. - -```bash -uv python install 3.12 -uv venv --python 3.12 -uv pip install -e . -mkdir ../bmad-django-app -uv run django-admin startproject tutorial_project ../bmad-django-app -``` - -## 3. 시작 동작 확인하기 - -JSON 출력을 아직 사용할 수 없는지 확인합니다. - -```bash -uv run python ../bmad-django-app/manage.py diffsettings --output=json -``` - -명령은 다음 오류로 끝납니다. - -```text -manage.py diffsettings: error: argument --output: invalid choice: 'json' (choose from hash, unified) -``` - -## 4. BMad 설치하기 - -안정 릴리스 채널에서 BMad Method를 설치합니다. 다음 명령은 Claude Code용으로 정확히 설정합니다. - -```bash -npx bmad-method install --directory . --modules bmm --tools claude-code --yes -``` - -Git이 이 튜토리얼에서 만든 BMad 파일과 uv 잠금 파일을 무시하도록 설정합니다. - -```bash -cat >> .git/info/exclude <<'EOF' -/_bmad/ -/_bmad-output/ -/.claude/ -/uv.lock -EOF -``` - -## 5. 구현하기 - -저장소 루트에서 코딩 도구를 엽니다. Claude Code에서는 다음 명령을 실행하세요. - -```bash -claude -``` - -```text -/bmad-build django-admin diffsettings에 JSON 출력 지원을 추가해 줘. 기존 출력 -형식을 유지하고 관련 테스트를 추가한 뒤 명령 문서를 업데이트해 줘. 로컬에서 -검토할 수 있도록 구현 결과는 작업 트리에 남겨 둬. -``` - -Build는 계획을 작성하기 전에 필요한 내용을 질문합니다. 새 JSON 출력에 원하는 방식을 직접 답하세요. 이 실습에 정답으로 정해진 JSON 설계는 없습니다. - -Build가 계획을 제시하면 사용자가 승인하거나 변경을 요청할 때까지 기다립니다. 승인 후에는 변경 사항을 구현하고 검토합니다. 발견한 문제를 처리한 뒤 결과를 보여줍니다. 이 실습의 범위는 `diffsettings`의 JSON 출력으로 유지하세요. 필터링, 마스킹, CI 동작은 다음 실습에서 다룹니다. - -`code` 명령을 사용할 수 있으면 Build가 프로젝트와 완성된 사양을 VS Code에서 엽니다. 권장 리뷰 순서의 링크를 따라 변경 사항을 살펴볼 수 있습니다. - -## 6. 작동 확인하기 - -셸로 돌아와 Django의 `diffsettings` 테스트를 실행합니다. - -```bash -uv run python tests/runtests.py admin_scripts.tests.DiffSettings --verbosity 1 -``` - -테스트가 통과해야 합니다. - -이제 명령을 다시 실행합니다. - -```bash -uv run python ../bmad-django-app/manage.py diffsettings --output=json -``` - -JSON을 살펴보고 Build와 함께 정한 내용과 비교하세요. - -## 7. 완성했습니다 - -이제 복잡한 오픈 소스 코드베이스에서 안정적으로 자리 잡은 Django 명령에 유용한 기능을 추가했습니다. VS Code를 사용한다면 지금 완성된 변경 사항이 열려 있을 것입니다. - -## 8. 더 큰 변경을 위한 사양 작성하기 - -다음 변경에는 Build를 세 번 실행해야 합니다. 무엇을 만들지 정할 때는 `/bmad-forge-idea`를, 초안을 개선할 때는 `/bmad-advanced-elicitation`을 사용할 수 있습니다. 여기서는 요구 사항이 이미 명확하므로 둘 다 필요하지 않습니다. BMad Spec에 바로 전달하세요. - -```text -/bmad-spec diffsettings-audit라는 사양을 만들고 정확히 세 개의 스토리로 나눠 줘. -순서는 필터, 마스킹, CI 상태로 해 줘. - -사양을 작성하기 전에 현재 diffsettings 구현, 관련 테스트, 명령 문서를 읽어 줘. -기존 출력 형식과 이미 승인한 JSON 설계를 모두 유지해 줘. 여러 번 지정할 수 있는 ---include와 --exclude 셸 글로브 필터를 추가해 줘. include 패턴은 OR로 결합하고 -exclude 패턴은 항상 우선해야 해. 현재 값과 기본값을 [REDACTED]로 바꾸되 차이의 -존재 여부는 바꾸지 않는 반복 가능한 --redact 셸 글로브 마스크를 추가해 줘. -필터링 후 차이가 남으면 1, 그렇지 않으면 0으로 종료하는 --fail-on-difference를 -추가해 줘. 각 스토리에는 관련 테스트 추가와 기존 명령 문서 업데이트를 포함해 줘. -Django 문서 파일이나 외부 서비스는 새로 추가하지 마. 사양 폴더 slug는 -diffsettings-audit를 사용해 줘. -``` - -BMad Spec은 `_bmad-output/specs/spec-diffsettings-audit/`에 사양 하나를 작성합니다. 그 안의 `stories.yaml`에는 순서가 정해진 스토리 세 개를 기록합니다. 사양과 스토리를 읽고 BMad Spec의 질문에 답하세요. 위 요구 사항과 일치하면 계속 진행합니다. - -## 9. 세 스토리 구현하기 - -각 스토리마다 Build를 한 번씩 순서대로 실행합니다. 한 번의 Build 실행을 끝내고 다음 스토리로 넘어가세요. 모든 실행에서 같은 사양을 사용합니다. 필터링, 마스킹, 종료 동작이 어떻게 맞물리는지를 정하는 스토리이므로 이번에는 사람이 직접 살펴보며 실행합니다. 이후 에픽에서 안정된 패턴을 반복한다면 자동화에 더 적합할 수 있습니다. - -### 스토리 1: 필터 - -```text -/bmad-build _bmad-output/specs/spec-diffsettings-audit/stories.yaml의 -스토리 1인 필터를 구현해 줘. -``` - -Build가 끝나면 결과를 확인합니다. - -```bash -uv run python ../bmad-django-app/manage.py diffsettings \ - --include=DATABASES --include=DEBUG --include=SECRET_KEY \ - --exclude=DATABASES -printf 'exit: %s\n' "$?" -``` - -출력에는 `DEBUG`와 `SECRET_KEY`가 있지만 `DATABASES`는 없습니다. 마지막에는 `exit: 0`이 표시됩니다. 포함 패턴은 OR로 결합되고 제외 조건이 우선합니다. - -### 스토리 2: 마스킹 - -```text -/bmad-build _bmad-output/specs/spec-diffsettings-audit/stories.yaml의 -스토리 2인 마스킹을 구현해 줘. -``` - -unified 출력을 확인합니다. - -```bash -uv run python ../bmad-django-app/manage.py diffsettings \ - --output=unified --include=SECRET_KEY --redact='SECRET*' -printf 'exit: %s\n' "$?" -``` - -비밀 값은 나타나지 않습니다. 차이의 양쪽 값이 모두 마스킹됩니다. - -```text -- SECRET_KEY = [REDACTED] -+ SECRET_KEY = [REDACTED] -exit: 0 -``` - -### 스토리 3: CI 상태 - -```text -/bmad-build _bmad-output/specs/spec-diffsettings-audit/stories.yaml의 -스토리 3인 CI 상태를 구현해 줘. -``` - -필터링 후에도 남은 차이를 확인합니다. - -```bash -uv run python ../bmad-django-app/manage.py diffsettings \ - --include=DEBUG --fail-on-difference -printf 'exit: %s\n' "$?" -``` - -`DEBUG`의 차이가 계속 표시되고 명령은 `exit: 1`로 끝납니다. - -## 10. 전체 변경 사항 함께 실행하기 - -이제 하나의 명령에서 세 스토리를 함께 확인합니다. - -```bash -uv run python ../bmad-django-app/manage.py diffsettings \ - --output=json --include=DEBUG --include=SECRET_KEY --exclude=DEBUG \ - --redact='SECRET*' --fail-on-difference -printf 'exit: %s\n' "$?" -``` - -JSON에는 `SECRET_KEY`만 포함됩니다. 앞에서 선택한 JSON 구조가 노출하는 현재 값과 기본값은 모두 `[REDACTED]`입니다. 원래 값은 어느 쪽도 나타나지 않습니다. 실제 값은 여전히 다르므로 마지막 줄은 `exit: 1`입니다. - -첫 실습에서는 범위가 분명한 변경 하나를 Build에 직접 요청했습니다. 이번 실습에서는 세 번의 Build 실행에 사양 하나를 공유했습니다. 마지막에도 필터링, 마스킹, CI 상태가 함께 작동합니다. 성숙한 Django 명령을 확장했으며 최종 결과는 처음 요청한 동작을 그대로 수행합니다. - -결과를 여러 관점에서 살펴보고 싶다면 마지막에 `/bmad-party-mode`를 실행할 수 있습니다. 이 튜토리얼을 마치는 데 꼭 필요하지는 않습니다. - -## 11. 에픽 검토하기 - -사양 폴더를 지정해 Retrospective를 실행하세요. - -```text -/bmad-retrospective _bmad-output/specs/spec-diffsettings-audit/ -``` - -Retrospective는 `stories.yaml`을 에픽의 스토리 목록으로 사용하고 각 스토리의 구현 기록을 읽습니다. 그런 다음 통합된 결과를 `SPEC.md`와 대조해 같은 사양 폴더에 `RETROSPECTIVE.md`를 작성합니다. 근거, 인수 판정, 제안된 후속 작업을 검토하세요. - -## 12. 계속 만들기 - -이제 [내 저장소에 BMad를 설치](../start/install-bmad.md)하고 `bmad-build` 스킬로 원하는 변경 사항을 만들어 보세요. 사람이 참여하는 경로는 [변경 사항 구현하기](../build/build-a-change.md)를 참고하세요. 변경에 사양, 자동화 또는 전체 프로젝트 흐름이 필요한지 판단하려면 [개발 경로 선택하기](../how-to/choose-a-development-path.md)를 사용하세요. diff --git a/docs/vi-vn/404.md b/docs/vi-vn/404.md deleted file mode 100644 index e51d5668b9..0000000000 --- a/docs/vi-vn/404.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -title: Không Tìm Thấy Trang -template: splash ---- - -Trang bạn đang tìm không tồn tại hoặc đã được chuyển đi. - -[Quay về trang chủ](./index.md) diff --git a/docs/vi-vn/_STYLE_GUIDE.md b/docs/vi-vn/_STYLE_GUIDE.md deleted file mode 100644 index b923c212fe..0000000000 --- a/docs/vi-vn/_STYLE_GUIDE.md +++ /dev/null @@ -1,371 +0,0 @@ ---- -title: "Hướng Dẫn Phong Cách Tài Liệu" -description: Các quy ước tài liệu dành riêng cho dự án, dựa trên phong cách tài liệu của Google và cấu trúc Diataxis ---- - -Dự án này tuân theo [Google Developer Documentation Style Guide](https://developers.google.com/style) và dùng [Diataxis](https://diataxis.fr/) để tổ chức nội dung. Phần dưới đây chỉ nêu các quy ước dành riêng cho dự án. - -## Quy tắc riêng của dự án - -| Quy tắc | Quy định | -| --- | --- | -| Không dùng đường kẻ ngang (`---`) | Làm gián đoạn dòng đọc | -| Không dùng tiêu đề `####` | Dùng chữ in đậm hoặc admonition thay thế | -| Không có mục "Related" hoặc "Next:" | Sidebar đã xử lý điều hướng | -| Không dùng danh sách lồng quá sâu | Tách thành các mục riêng | -| Không dùng code block cho nội dung không phải code | Dùng admonition cho ví dụ hội thoại | -| Không dùng cả đoạn in đậm để làm callout | Dùng admonition thay thế | -| Mỗi mục tối đa 1-2 admonition | Tutorial có thể dùng 3-4 admonition cho mỗi phần lớn | -| Ô bảng / mục danh sách | Tối đa 1-2 câu | -| Ngân sách tiêu đề | 8-12 `##` cho mỗi tài liệu; 2-3 `###` cho mỗi phần | - -## Admonition (cú pháp Starlight) - -```md -:::tip[Tiêu đề] -Lối tắt, best practice -::: - -:::note[Tiêu đề] -Ngữ cảnh, định nghĩa, ví dụ, điều kiện tiên quyết -::: - -:::caution[Tiêu đề] -Lưu ý, vấn đề có thể xảy ra -::: - -:::danger[Tiêu đề] -Chỉ dùng cho cảnh báo nghiêm trọng — mất dữ liệu, vấn đề bảo mật -::: -``` - -### Cách dùng chuẩn - -| Admonition | Dùng cho | -| --- | --- | -| `:::note[Điều kiện tiên quyết]` | Các phụ thuộc trước khi bắt đầu | -| `:::tip[Lối đi nhanh]` | Tóm tắt TL;DR ở đầu tài liệu | -| `:::caution[Quan trọng]` | Cảnh báo quan trọng | -| `:::note[Ví dụ]` | Ví dụ lệnh / phản hồi | - -## Mẫu bảng chuẩn - -**Phase:** - -```md -| Phase | Tên | Điều xảy ra | -| ----- | --- | ------------ | -| 1 | Analysis | Brainstorm, nghiên cứu *(tùy chọn)* | -| 2 | Planning | Yêu cầu — PRD hoặc spec *(bắt buộc)* | -``` - -**Skill:** - -```md -| Skill | Agent | Mục đích | -| ----- | ----- | -------- | -| `bmad-brainstorming` | Analyst | Brainstorm cho dự án mới | -| `bmad-prd` | PM | Tạo tài liệu yêu cầu sản phẩm | -``` - -## Khối cấu trúc thư mục - -Hiển thị trong phần "Bạn đã hoàn thành những gì": - -````md -``` -your-project/ -├── _bmad/ # Cấu hình BMad -├── _bmad-output/ -│ ├── planning-artifacts/ -│ │ └── PRD.md # Tài liệu yêu cầu của bạn -│ ├── implementation-artifacts/ -│ └── project-context.md # Quy tắc triển khai (tùy chọn) -└── ... -``` -```` - -## Cấu trúc Tutorial - -```text -1. Tiêu đề + Hook (1-2 câu mô tả kết quả) -2. Thông báo phiên bản/module (admonition info hoặc warning) (tùy chọn) -3. Bạn sẽ học được gì (danh sách kết quả) -4. Điều kiện tiên quyết (admonition info) -5. Lối đi nhanh (admonition tip - tóm tắt TL;DR) -6. Hiểu về [Chủ đề] (ngữ cảnh trước các bước - bảng cho phase/agent) -7. Cài đặt (tùy chọn) -8. Bước 1: [Nhiệm vụ lớn đầu tiên] -9. Bước 2: [Nhiệm vụ lớn thứ hai] -10. Bước 3: [Nhiệm vụ lớn thứ ba] -11. Bạn đã hoàn thành những gì (tóm tắt + cấu trúc thư mục) -12. Tra cứu nhanh (bảng skill) -13. Câu hỏi thường gặp (định dạng FAQ) -14. Nhận hỗ trợ (liên kết cộng đồng) -15. Điểm chính cần nhớ (admonition tip) -``` - -### Checklist cho Tutorial - -- [ ] Hook mô tả kết quả trong 1-2 câu -- [ ] Có phần "Bạn sẽ học được gì" -- [ ] Điều kiện tiên quyết nằm trong admonition -- [ ] Có admonition TL;DR ở đầu trang -- [ ] Có bảng cho phase, skill, agent -- [ ] Có phần "Bạn đã hoàn thành những gì" -- [ ] Có bảng tra cứu nhanh -- [ ] Có phần câu hỏi thường gặp -- [ ] Có phần nhận hỗ trợ -- [ ] Có admonition điểm chính ở cuối - -## Cấu trúc How-To - -```text -1. Tiêu đề + Hook (một câu: "Sử dụng workflow `X` để...") -2. Khi nào nên dùng (danh sách kịch bản) -3. Khi nào nên bỏ qua (tùy chọn) -4. Điều kiện tiên quyết (admonition note) -5. Các bước (mục con `###` có đánh số) -6. Bạn sẽ nhận được gì (output / artifact) -7. Ví dụ (tùy chọn) -8. Mẹo (tùy chọn) -9. Bước tiếp theo (tùy chọn) -``` - -### Checklist cho How-To - -- [ ] Hook bắt đầu bằng "Sử dụng workflow `X` để..." -- [ ] Phần "Khi nào nên dùng" có 3-5 gạch đầu dòng -- [ ] Có liệt kê điều kiện tiên quyết -- [ ] Các bước là mục `###` có đánh số và bắt đầu bằng động từ -- [ ] Phần "Bạn sẽ nhận được gì" mô tả artifact đầu ra - -## Cấu trúc Explanation - -### Các loại - -| Loại | Ví dụ | -| --- | --- | -| **Trang chỉ mục / landing** | `core-concepts/index.md` | -| **Khái niệm** | `what-are-agents.md` | -| **Tính năng** | `build.md` | -| **Triết lý** | `why-solutioning-matters.md` | -| **FAQ** | `established-projects-faq.md` | - -### Mẫu tổng quát - -```text -1. Tiêu đề + Hook (1-2 câu) -2. Tổng quan / định nghĩa (nó là gì, vì sao quan trọng) -3. Khái niệm chính (các mục `###`) -4. Bảng so sánh (tùy chọn) -5. Khi nào nên dùng / không nên dùng (tùy chọn) -6. Sơ đồ (tùy chọn - mermaid, tối đa 1 sơ đồ mỗi tài liệu) -7. Bước tiếp theo (tùy chọn) -``` - -### Trang chỉ mục / landing - -```text -1. Tiêu đề + Hook (một câu) -2. Bảng nội dung (liên kết kèm mô tả) -3. Bắt đầu từ đâu (danh sách có đánh số) -4. Chọn hướng đi của bạn (tùy chọn - cây quyết định) -``` - -### Trang giải thích khái niệm - -```text -1. Tiêu đề + Hook (nó là gì) -2. Loại / nhóm (các mục `###`) (tùy chọn) -3. Bảng khác biệt chính -4. Thành phần / bộ phận -5. Nên chọn cái nào? -6. Cách tạo / tùy chỉnh (trỏ sang how-to) -``` - -### Trang giải thích tính năng - -```text -1. Tiêu đề + Hook (nó làm gì) -2. Thông tin nhanh (tùy chọn - "Phù hợp với:", "Mất bao lâu:") -3. Khi nào nên dùng / không nên dùng -4. Cách nó hoạt động (mermaid tùy chọn) -5. Lợi ích chính -6. Bảng so sánh (tùy chọn) -7. Khi nào nên nâng cấp / chuyển hướng (tùy chọn) -``` - -### Tài liệu về triết lý / lý do - -```text -1. Tiêu đề + Hook (nguyên tắc) -2. Vấn đề -3. Giải pháp -4. Nguyên tắc chính (các mục `###`) -5. Lợi ích -6. Khi nào áp dụng -``` - -### Checklist cho Explanation - -- [ ] Hook nêu rõ tài liệu giải thích điều gì -- [ ] Nội dung được chia thành các phần `##` dễ quét -- [ ] Có bảng so sánh khi có từ 3 lựa chọn trở lên -- [ ] Sơ đồ có nhãn rõ ràng -- [ ] Có liên kết sang how-to cho câu hỏi mang tính thủ tục -- [ ] Mỗi tài liệu tối đa 2-3 admonition - -## Cấu trúc Reference - -### Các loại - -| Loại | Ví dụ | -| --- | --- | -| **Trang chỉ mục / landing** | `workflows/index.md` | -| **Danh mục** | `agents/index.md` | -| **Đào sâu** | `document-project.md` | -| **Cấu hình** | `core-tasks.md` | -| **Bảng thuật ngữ** | `glossary/index.md` | -| **Tổng hợp đầy đủ** | `bmgd-workflows.md` | - -### Trang chỉ mục của Reference - -```text -1. Tiêu đề + Hook (một câu) -2. Các phần nội dung (`##` cho từng nhóm) - - Danh sách gạch đầu dòng với liên kết và mô tả -``` - -### Reference dạng danh mục - -```text -1. Tiêu đề + Hook -2. Các mục (`##` cho từng mục) - - Mô tả ngắn (một câu) - - **Skills:** hoặc **Thông tin chính:** ở dạng danh sách phẳng -3. Phần dùng chung / toàn cục (`##`) (tùy chọn) -``` - -### Reference đào sâu theo mục - -```text -1. Tiêu đề + Hook (một câu nêu mục đích) -2. Thông tin nhanh (admonition note, tùy chọn) - - Module, Skill, Input, Output dưới dạng danh sách -3. Mục đích / tổng quan (`##`) -4. Cách gọi (code block) -5. Các phần chính (`##` cho từng khía cạnh) - - Dùng `###` cho các tùy chọn con -6. Ghi chú / lưu ý (admonition tip hoặc caution) -``` - -### Reference về cấu hình - -```text -1. Tiêu đề + Hook -2. Mục lục (jump link nếu có từ 4 mục trở lên) -3. Các mục (`##` cho từng config / task) - - **Tóm tắt in đậm** — một câu - - **Dùng khi:** danh sách gạch đầu dòng - - **Cách hoạt động:** các bước đánh số (tối đa 3-5 bước) - - **Output:** kết quả mong đợi (tùy chọn) -``` - -### Hướng dẫn reference tổng hợp - -```text -1. Tiêu đề + Hook -2. Tổng quan (`##`) - - Sơ đồ hoặc bảng mô tả cách tổ chức -3. Các phần lớn (`##` cho từng phase / nhóm) - - Các mục (`###` cho từng mục) - - Các trường chuẩn hóa: Skill, Agent, Input, Output, Description -4. Bước tiếp theo (tùy chọn) -``` - -### Checklist cho Reference - -- [ ] Hook nêu rõ tài liệu đang tham chiếu điều gì -- [ ] Cấu trúc phù hợp với loại reference -- [ ] Các mục dùng cấu trúc nhất quán xuyên suốt -- [ ] Có bảng cho dữ liệu có cấu trúc / so sánh -- [ ] Có liên kết sang tài liệu explanation cho chiều sâu khái niệm -- [ ] Tối đa 1-2 admonition - -## Cấu trúc Glossary - -Starlight tạo phần điều hướng "On this page" từ các tiêu đề: - -- Dùng `##` cho các nhóm — sẽ hiện ở thanh điều hướng bên phải -- Đặt thuật ngữ trong bảng — gọn hơn so với tạo tiêu đề riêng cho từng thuật ngữ -- Không chèn TOC nội tuyến — sidebar bên phải đã xử lý điều hướng - -### Định dạng bảng - -```md -## Tên nhóm - -| Thuật ngữ | Định nghĩa | -| --------- | ---------- | -| **Agent** | AI persona chuyên biệt với chuyên môn cụ thể để dẫn dắt người dùng qua workflow. | -| **Workflow** | Quy trình nhiều bước có hướng dẫn, điều phối hoạt động của agent AI để tạo deliverable. | -``` - -### Quy tắc viết định nghĩa - -| Nên làm | Không nên làm | -| --- | --- | -| Bắt đầu bằng việc nó LÀ gì hoặc LÀM gì | Bắt đầu bằng "Đây là..." hoặc "Một [thuật ngữ] là..." | -| Giữ trong 1-2 câu | Viết thành nhiều đoạn dài | -| Bôi đậm tên thuật ngữ trong ô | Để thuật ngữ ở dạng chữ thường | - -### Dấu hiệu ngữ cảnh - -Thêm ngữ cảnh in nghiêng ở đầu định nghĩa với các thuật ngữ có phạm vi hẹp: - -- `*Chỉ dành cho đầu vào triển khai trực tiếp.*` -- `*BMad Method/Enterprise.*` -- `*Phase N.*` -- `*BMGD.*` -- `*Dự án hiện có.*` - -### Checklist cho Glossary - -- [ ] Thuật ngữ nằm trong bảng, không dùng tiêu đề riêng -- [ ] Thuật ngữ được sắp theo thứ tự chữ cái trong từng nhóm -- [ ] Định nghĩa dài 1-2 câu -- [ ] Dấu hiệu ngữ cảnh được in nghiêng -- [ ] Tên thuật ngữ được bôi đậm trong ô -- [ ] Không dùng kiểu định nghĩa "Một [thuật ngữ] là..." - -## Phần FAQ - -```md -## Các câu hỏi - -- [Lúc nào cũng cần kiến trúc à?](#luc-nao-cung-can-kien-truc-a) -- [Tôi có thể đổi kế hoạch về sau không?](#toi-co-the-doi-ke-hoach-ve-sau-khong) - -### Lúc nào cũng cần kiến trúc à? - -Chỉ dành cho công việc cần kiến trúc. Công việc rõ ràng có thể đi thẳng vào implementation. - -### Tôi có thể đổi kế hoạch về sau không? - -Có. Workflow `bmad-correct-course` xử lý thay đổi phạm vi giữa chừng. - -**Có câu hỏi chưa được trả lời ở đây?** [Mở issue](...) hoặc hỏi trên [Discord](...). -``` - -## Các Lệnh Kiểm Tra - -Trước khi gửi thay đổi tài liệu: - -```bash -cd docs-site -npm run fix-links # Xem trước các sửa định dạng link -npm run fix-links -- --write # Áp dụng các sửa -npm run validate-links # Kiểm tra link tồn tại -npm run build # Xác minh không có lỗi build -``` diff --git a/docs/vi-vn/bmad-developer-guide.md b/docs/vi-vn/bmad-developer-guide.md deleted file mode 100644 index 90a4323b5e..0000000000 --- a/docs/vi-vn/bmad-developer-guide.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: Hướng dẫn BMAD cho Developer -description: Lối vào triển khai thống nhất của BMad Method cho mọi độ sâu lập kế hoạch ---- - -# BMAD Method cho Developer - -BMAD Method dùng một workflow triển khai thống nhất cho mọi công việc phát triển: `bmad-build`. - -Độ sâu lập kế hoạch thay đổi theo công việc. Một yêu cầu rõ ràng có thể đi thẳng từ ý định người dùng vào implementation. Một sáng kiến lớn hơn có thể chuẩn bị PRD, UX, architecture, epics, stories, kiểm tra mức sẵn sàng và sprint planning trước. Cả hai trường hợp đều hội tụ tại `bmad-build`; các artifact lập kế hoạch chỉ cung cấp thêm ngữ cảnh cho cùng workflow. - -`bmad-build` nhận yêu cầu trực tiếp, issue, spec hoặc story đã lập kế hoạch. Workflow tự xác định mức làm rõ, lập kế hoạch, triển khai và review cần thiết để hoàn thành công việc an toàn. - -## Bắt đầu - -- [Bắt đầu với BMad](./tutorials/getting-started.md) -- [Hiểu Build](./explanation/build.md) -- [Xem bản đồ workflow](./reference/workflow-map.md) diff --git a/docs/vi-vn/build/walk-through-a-change.md b/docs/vi-vn/build/walk-through-a-change.md deleted file mode 100644 index 78cc7f476a..0000000000 --- a/docs/vi-vn/build/walk-through-a-change.md +++ /dev/null @@ -1,92 +0,0 @@ ---- -title: "Đi qua một thay đổi" -description: Review có người trong vòng lặp với hỗ trợ của LLM, dẫn bạn đi qua thay đổi từ mục đích đến chi tiết -sidebar: - order: 1 ---- - -`bmad-walkthrough` là một workflow review tương tác có người trong vòng lặp với hỗ trợ của LLM. Nó dẫn bạn đi qua một thay đổi mã nguồn, từ mục đích và bối cảnh đến các chi tiết quan trọng, để bạn có thể quyết định có nên phát hành, làm lại, hay đào sâu thêm. - -![Sơ đồ workflow Walkthrough](/diagrams/walkthrough-run.svg) - -## Luồng điển hình - -Bạn chạy `bmad-build`. Nó làm rõ ý định của bạn, dựng spec, triển khai thay đổi, rồi khi xong sẽ nối thêm một review trail vào file spec và mở file đó trong editor. Bạn nhìn vào spec và thấy thay đổi này chạm tới 20 file, trải trên nhiều module. - -Bạn có thể tự liếc diff. Nhưng khoảng 20 file là lúc cách đó bắt đầu kém hiệu quả: bạn mất mạch, bỏ sót liên hệ giữa hai thay đổi ở xa nhau, hoặc duyệt một thứ mà bạn chưa thực sự hiểu. Thay vì vậy, bạn nói "walkthrough" và LLM sẽ dẫn bạn đi qua thay đổi. - -Điểm bàn giao đó, từ triển khai tự động quay lại phán đoán của con người, chính là tình huống sử dụng chính. Build có thể chạy khá lâu với rất ít giám sát. Walkthrough là nơi bạn cầm lại tay lái. - -## Vì sao nó tồn tại - -Code review có hai kiểu thất bại. Kiểu đầu là người review lướt qua diff, không thấy gì nổi bật và bấm duyệt. Kiểu thứ hai là họ đọc rất kỹ từng file nhưng lại mất mạch tổng thể, thấy từng cái cây mà bỏ lỡ cả khu rừng. Cả hai đều dẫn tới cùng một kết quả: lần review đã không bắt được điều thực sự quan trọng. - -Vấn đề cốt lõi nằm ở thứ tự tiếp nhận. Một raw diff trình bày thay đổi theo thứ tự file, gần như không bao giờ là thứ tự giúp xây dựng hiểu biết. Bạn thấy một helper function trước khi biết vì sao nó tồn tại. Bạn thấy một schema change trước khi hiểu tính năng nào đang dùng nó. Người review phải tự dựng lại ý đồ của tác giả từ những manh mối rời rạc, và chính ở bước dựng lại đó sự tập trung thường bị đứt. - -Walkthrough giải quyết việc này bằng cách để LLM làm phần dựng lại. Nó đọc diff, spec nếu có, và codebase xung quanh, rồi trình bày thay đổi theo một thứ tự phục vụ việc hiểu, chứ không theo `git diff`. - -## Nó hoạt động như thế nào - -Workflow này có năm bước. Mỗi bước xây trên bước trước, dần dần chuyển từ "đây là gì?" sang "chúng ta có nên phát hành nó không?" - -### 1. Định hướng - -Workflow xác định thay đổi đó là gì, từ PR, commit, branch, file spec, hoặc trạng thái git hiện tại, rồi tạo một câu tóm tắt ý định và vài số liệu bề mặt: số file thay đổi, số module bị chạm tới, số dòng logic, số lần băng qua ranh giới, và các public interface mới. - -Đây là khoảnh khắc "đúng là thứ tôi đang nghĩ tới chứ?". Trước khi đọc mã, người review xác nhận mình đang nhìn đúng thay đổi và cân chỉnh kỳ vọng về phạm vi. - -### 2. Dẫn giải thay đổi (Walkthrough) - -Thay đổi được tổ chức theo **mối quan tâm** như validation đầu vào hay API contract, thay vì theo file. Mỗi mối quan tâm có một giải thích ngắn về *vì sao* cách tiếp cận này được chọn, kèm theo các điểm dừng `path:line` có thể bấm để người review đi theo xuyên suốt code. - -Đây là bước dùng phán đoán về thiết kế. Người review đánh giá xem hướng tiếp cận có đúng với hệ thống hay không, chứ chưa phải xem code có chính xác tuyệt đối hay không. Các mối quan tâm được sắp từ trên xuống: ý định cấp cao trước, phần triển khai hỗ trợ sau. Người review sẽ không gặp tham chiếu tới thứ mà họ chưa thấy. - -### 3. Soi chi tiết - -Sau khi người review đã hiểu thiết kế, workflow sẽ đưa ra 2 đến 5 điểm mà nếu sai thì hậu quả lan rộng nhất. Chúng được gắn nhãn theo loại rủi ro như `[auth]`, `[schema]`, `[billing]`, `[public API]`, `[security]` và các nhãn khác, đồng thời được sắp theo mức độ thiệt hại nếu sai. - -Đây không phải là một cuộc săn bug. Tính đúng đắn được CI và test tự động lo phần lớn. Bước soi chi tiết nhằm kích hoạt ý thức về rủi ro: "đây là những chỗ mà nếu sai thì cái giá phải trả cao nhất". Nếu muốn đào sâu một khu vực cụ thể, bạn có thể nói "đào sâu vào [khu vực]" để chạy một lần review lại tập trung vào tính đúng đắn. - -Nếu spec trước đó đã đi qua các vòng adversarial review, các phát hiện liên quan cũng được đưa ra ở đây. Không phải các bug đã được sửa, mà là những quyết định mà vòng review đó từng gắn cờ để người review hiện tại biết. - -### 4. Kiểm thử - -Workflow gợi ý 2 đến 5 cách quan sát thủ công để thấy thay đổi thực sự hoạt động. Không phải lệnh test tự động, mà là các quan sát tay giúp tăng niềm tin theo cách test suite không cho bạn được. Một tương tác UI để thử, một lệnh CLI để chạy, một request API để gửi, kèm kết quả kỳ vọng cho từng mục. - -Nếu thay đổi không có hành vi nào nhìn thấy được từ phía người dùng, workflow sẽ nói thẳng như vậy. Không bịa thêm việc cho có. - -### 5. Kết thúc - -Người review đưa ra quyết định: duyệt, làm lại, hay tiếp tục thảo luận. Nếu đang duyệt PR, workflow có thể hỗ trợ với `gh pr review --approve`. Nếu cần làm lại, nó sẽ giúp chẩn đoán vấn đề nằm ở cách tiếp cận, spec, hay phần triển khai, đồng thời hỗ trợ soạn phản hồi có thể hành động được và gắn với vị trí code cụ thể. - -## Đây là một cuộc hội thoại, không phải bản báo cáo - -Workflow trình bày từng bước như một điểm khởi đầu, không phải lời kết luận cuối cùng. Giữa các bước, hoặc ngay giữa một bước, bạn có thể trao đổi với LLM, hỏi thêm, phản biện cách nó đóng khung vấn đề, hoặc kéo thêm skill khác để lấy một góc nhìn khác: - -- **"run advanced elicitation on the error handling"** - ép LLM xem xét lại và tinh chỉnh phân tích cho một khu vực cụ thể -- **"party mode on whether this schema migration is safe"** - kéo nhiều góc nhìn agent vào một cuộc tranh luận tập trung -- **"run code review"** - tạo ra các phát hiện có cấu trúc với phân tích đối kháng và edge case - -Workflow Walkthrough không khóa bạn vào một đường đi tuyến tính. Nó cho bạn cấu trúc khi bạn cần, và tránh cản đường khi bạn muốn tự khám phá. Năm bước ở đây để bảo đảm bạn nhìn được toàn cảnh, còn việc đi sâu đến mức nào ở mỗi bước và gọi thêm công cụ nào hoàn toàn là do bạn quyết định. - -## Lộ trình review (Review Trail) - -Bước dẫn giải thay đổi hoạt động tốt nhất khi nó có một **thứ tự review gợi ý (Suggested Review Order)**, tức một danh sách các điểm dừng do tác giả spec viết ra để dẫn người review đi qua thay đổi. Nếu spec có phần này, workflow sẽ dùng trực tiếp. - -Nếu không có review trail do tác giả tạo, workflow sẽ tự sinh một trail từ diff và bối cảnh codebase. Trail do máy sinh ra vẫn kém hơn trail do tác giả viết, nhưng vẫn tốt hơn rất nhiều so với việc đọc thay đổi theo thứ tự file. - -## Khi nào nên dùng - -Tình huống chính là bước bàn giao sau `bmad-build`: phần triển khai đã xong, file spec đang mở trong editor với review trail đã được nối thêm, và bạn cần quyết định có nên phát hành hay không. Lúc đó chỉ cần nói "walkthrough" là bắt đầu. - -Nó cũng hoạt động độc lập: - -- **Review một PR** - đặc biệt hữu ích khi PR có nhiều hơn vài file hoặc có thay đổi cắt ngang nhiều khu vực -- **Làm quen với một thay đổi (onboard to a change)** - khi bạn cần hiểu chuyện gì đã xảy ra trên một branch mà bạn không phải người viết -- **Review sprint (sprint review)** - workflow có thể nhặt các story được đánh dấu `review` trong file trạng thái sprint của bạn - -Bạn có thể gọi nó bằng cách nói "walkthrough" hoặc "dẫn tôi đi qua thay đổi này". Nó chạy được trong mọi terminal, nhưng sẽ phát huy tốt nhất trong IDE như VS Code, Cursor hoặc công cụ tương tự, vì workflow tạo tham chiếu `path:line` ở mọi bước. Trong terminal tích hợp của IDE, các tham chiếu đó có thể bấm được, nên bạn có thể nhảy qua lại giữa các file khi đi theo review trail. - -## Nó không phải là gì - -Walkthrough không thay thế review tự động. Nó không chạy linter, type checker, hay test suite. Nó không chấm mức độ nghiêm trọng hay đưa ra kết luận pass/fail. Nó là một bản hướng dẫn đọc để giúp con người áp dụng phán đoán của mình vào đúng những chỗ đáng chú ý nhất. diff --git a/docs/vi-vn/explanation/advanced-elicitation.md b/docs/vi-vn/explanation/advanced-elicitation.md deleted file mode 100644 index 1511f242fa..0000000000 --- a/docs/vi-vn/explanation/advanced-elicitation.md +++ /dev/null @@ -1,49 +0,0 @@ ---- -title: "Khai thác nâng cao" -description: Buộc LLM xem xét lại kết quả của nó bằng các phương pháp lập luận có cấu trúc -sidebar: - order: 4 ---- - -Buộc LLM xem xét lại những gì nó vừa tạo ra. Bạn chọn một phương pháp lập luận, nó áp dụng phương pháp đó lên chính output của mình, rồi bạn quyết định có giữ các cải tiến hay không. - -## Khai thác nâng cao là gì? - -Đây là một lần xem xét lại có cấu trúc. Thay vì bảo AI "thử lại" hoặc "làm cho nó tốt hơn", bạn chọn một phương pháp lập luận cụ thể và AI sẽ xem lại output của chính nó dưới góc đó. - -Khác biệt này rất quan trọng. Yêu cầu mơ hồ sẽ tạo ra bản sửa đổi mơ hồ. Một phương pháp được gọi tên buộc AI tấn công vấn đề theo một hướng cụ thể, qua đó phát hiện những ý tưởng mà một lần thử lại chung chung sẽ bỏ lỡ. - -## Khi nào nên dùng - -- Sau khi workflow tạo nội dung và bạn muốn có phương án thay thế -- Khi output có vẻ ổn nhưng bạn nghi vẫn còn có thể đào sâu hơn -- Để stress-test các giả định hoặc tìm điểm yếu -- Với nội dung quan trọng, nơi mà việc nghĩ lại sẽ có giá trị - -Các workflow sẽ đưa ra tùy chọn khai thác nâng cao tại các điểm quyết định - sau khi LLM tạo một kết quả, bạn sẽ được hỏi có muốn chạy nó hay không. - -## Nó hoạt động như thế nào - -1. LLM đề xuất 5 phương pháp phù hợp với nội dung của bạn -2. Bạn chọn một phương pháp (hoặc đảo lại để xem lựa chọn khác) -3. Phương pháp được áp dụng, các cải tiến được hiện ra -4. Chấp nhận hoặc bỏ đi, lặp lại hoặc tiếp tục - -## Các phương pháp tích hợp sẵn - -Có hàng chục phương pháp lập luận có sẵn. Một vài ví dụ: - -- **Pre-mortem Analysis** - Giả sử dự án đã thất bại rồi lần ngược lại để tìm lý do -- **First Principles Thinking** - Loại bỏ giả định, xây lại từ sự thật nền tảng -- **Inversion** - Hỏi cách nào chắc chắn dẫn đến thất bại, rồi tránh những điều đó -- **Red Team vs Blue Team** - Tự tấn công công việc của chính mình, rồi tự bảo vệ nó -- **Socratic Questioning** - Chất vấn mọi khẳng định bằng "tại sao?" và "làm sao bạn biết?" -- **Constraint Removal** - Bỏ hết ràng buộc, xem điều gì thay đổi, rồi thêm lại có chọn lọc -- **Stakeholder Mapping** - Đánh giá lại từ góc nhìn của từng bên liên quan -- **Analogical Reasoning** - Tìm điểm tương đồng ở lĩnh vực khác và áp dụng bài học của chúng - -Và còn nhiều nữa. AI sẽ chọn những lựa chọn phù hợp nhất với nội dung của bạn - bạn quyết định chạy cái nào. - -:::tip[Bắt đầu từ đây] -Pre-mortem Analysis là lựa chọn đầu tiên tốt cho bất kỳ bản spec hoặc kế hoạch nào. Nó thường xuyên tìm ra các lỗ hổng mà một lần review thông thường bỏ qua. -::: diff --git a/docs/vi-vn/explanation/analysis-phase.md b/docs/vi-vn/explanation/analysis-phase.md deleted file mode 100644 index 7e44e5d555..0000000000 --- a/docs/vi-vn/explanation/analysis-phase.md +++ /dev/null @@ -1,70 +0,0 @@ ---- -title: "Giai đoạn phân tích: từ ý tưởng đến nền tảng" -description: Động não, nghiên cứu, product brief và PRFAQ là gì, và nên dùng từng công cụ khi nào -sidebar: - order: 2 ---- - -Giai đoạn phân tích (giai đoạn 1) giúp bạn suy nghĩ rõ ràng về sản phẩm trước khi cam kết bắt tay vào xây dựng. Mọi công cụ trong giai đoạn này đều là tùy chọn, nhưng nếu bỏ qua toàn bộ phần phân tích thì PRD của bạn sẽ được dựng trên giả định thay vì hiểu biết thực chất. - -## Vì sao cần phân tích trước khi lập kế hoạch? - -PRD trả lời câu hỏi "chúng ta nên xây gì và vì sao?". Nếu đầu vào của nó là những suy nghĩ mơ hồ, bạn sẽ nhận lại một PRD mơ hồ, và mọi tài liệu phía sau đều kế thừa chính sự mơ hồ đó. Kiến trúc dựng trên một PRD yếu sẽ đặt cược sai về mặt kỹ thuật. Các story sinh ra từ một kiến trúc yếu sẽ bỏ sót trường hợp biên. Chi phí sẽ dồn lên theo từng tầng. - -Các công cụ phân tích tồn tại để làm PRD của bạn sắc bén hơn. Chúng tiếp cận vấn đề từ nhiều góc độ khác nhau: khám phá sáng tạo, thực tế thị trường, độ rõ ràng về khách hàng, tính khả thi. Nhờ vậy, đến khi bạn ngồi xuống làm việc với agent PM, bạn đã biết mình đang xây cái gì và cho ai. - -## Các công cụ - -### Động não - -**Nó là gì.** Một phiên sáng tạo có điều phối, sử dụng các kỹ thuật phát ý tưởng đã được kiểm chứng. AI đóng vai trò như người huấn luyện, kéo ý tưởng ra từ bạn thông qua các bài tập có cấu trúc, chứ không nghĩ thay cho bạn. - -**Vì sao nó có mặt ở đây.** Ý tưởng thô cần không gian để phát triển trước khi bị khóa cứng thành yêu cầu. Động não tạo ra khoảng không đó. Nó đặc biệt có giá trị khi bạn có một miền vấn đề nhưng chưa có lời giải rõ ràng, hoặc khi bạn muốn khám phá nhiều hướng trước khi cam kết. - -**Khi nào nên dùng.** Bạn có một hình dung mơ hồ về thứ mình muốn xây nhưng chưa kết tinh được thành khái niệm rõ ràng. Hoặc bạn đã có ý tưởng ban đầu nhưng muốn kiểm chứng độ vững của nó bằng các phương án thay thế. - -Xem [Brainstorming](./brainstorming.md) để hiểu sâu hơn về cách một phiên làm việc diễn ra. - -### Nghiên cứu (thị trường, miền nghiệp vụ, kỹ thuật) - -**Nó là gì.** Ba quy trình nghiên cứu tập trung vào các chiều khác nhau của ý tưởng. Nghiên cứu thị trường xem xét đối thủ, xu hướng và cảm nhận của người dùng. Nghiên cứu miền nghiệp vụ xây dựng hiểu biết về lĩnh vực và thuật ngữ. Nghiên cứu kỹ thuật đánh giá tính khả thi, các lựa chọn kiến trúc và hướng triển khai. - -**Vì sao nó có mặt ở đây.** Xây dựng dựa trên giả định là con đường nhanh nhất để tạo ra thứ chẳng ai cần. Nghiên cứu đặt ý tưởng của bạn xuống mặt đất: đối thủ nào đã tồn tại, người dùng thực sự đang vật lộn với điều gì, điều gì khả thi về kỹ thuật, và bạn sẽ phải đối mặt với những ràng buộc đặc thù ngành nào. - -**Khi nào nên dùng.** Bạn đang bước vào một miền mới, nghi ngờ có đối thủ nhưng chưa lập bản đồ được, hoặc ý tưởng của bạn phụ thuộc vào những năng lực kỹ thuật mà bạn chưa kiểm chứng. Có thể chạy một, hai, hoặc cả ba; mỗi quy trình đều đứng độc lập. - -### Product Brief - -**Nó là gì.** Một phiên discovery có hướng dẫn, tạo ra bản tóm tắt điều hành 1-2 trang cho concept sản phẩm của bạn. AI đóng vai trò Business Analyst cộng tác, giúp bạn diễn đạt tầm nhìn, đối tượng mục tiêu, giá trị cốt lõi và phạm vi. - -**Vì sao nó có mặt ở đây.** Product brief là con đường nhẹ nhàng hơn để đi vào giai đoạn lập kế hoạch. Nó ghi lại tầm nhìn chiến lược của bạn theo định dạng có cấu trúc và đưa thẳng vào quá trình tạo PRD. Nó hoạt động tốt nhất khi bạn đã có niềm tin tương đối chắc vào ý tưởng của mình: bạn biết khách hàng là ai, vấn đề là gì, và đại khái muốn xây gì. Brief sẽ tổ chức lại và làm sắc nét lối suy nghĩ đó. - -**Khi nào nên dùng.** Ý tưởng của bạn đã tương đối rõ và bạn muốn ghi lại nó một cách hiệu quả trước khi tạo PRD. Bạn tin vào hướng đi hiện tại và không cần bị thách thức giả định một cách quá quyết liệt. - -### PRFAQ (Working Backwards) - -**Nó là gì.** Phương pháp Working Backwards của Amazon được chuyển thành một thử thách tương tác. Bạn viết thông cáo báo chí công bố sản phẩm hoàn thiện trước khi tồn tại dù chỉ một dòng code, rồi trả lời những câu hỏi khó nhất mà khách hàng và stakeholder sẽ đặt ra. AI đóng vai trò product coach dai dẳng nhưng mang tính xây dựng. - -**Vì sao nó có mặt ở đây.** PRFAQ là con đường nghiêm ngặt hơn để đi vào giai đoạn lập kế hoạch. Nó buộc bạn đạt đến sự rõ ràng theo hướng lấy khách hàng làm trung tâm bằng cách bắt bạn bảo vệ từng phát biểu. Nếu bạn không viết nổi một thông cáo báo chí đủ thuyết phục, sản phẩm đó chưa sẵn sàng. Nếu phần FAQ lộ ra những khoảng trống, đó chính là những khoảng trống mà bạn sẽ phát hiện muộn hơn rất nhiều, và với chi phí lớn hơn nhiều, trong lúc triển khai. Bài kiểm tra này bóc tách lối suy nghĩ yếu ngay từ sớm, khi chi phí sửa còn rẻ nhất. - -**Khi nào nên dùng.** Bạn muốn kiểm tra độ vững của ý tưởng trước khi cam kết tài nguyên. Bạn chưa chắc người dùng có thực sự quan tâm hay không. Bạn muốn xác nhận rằng mình có thể diễn đạt một giá trị cốt lõi rõ ràng và có thể bảo vệ được. Hoặc đơn giản là bạn muốn dùng sự kỷ luật của Working Backwards để làm suy nghĩ của mình sắc bén hơn. - -## Tôi nên dùng cái nào? - -| Tình huống | Công cụ được khuyến nghị | -| --------- | ------------------------ | -| "Tôi có một ý tưởng mơ hồ, chưa biết bắt đầu từ đâu" | Brainstorming | -| "Tôi cần hiểu thị trường trước khi quyết định" | Research | -| "Tôi biết mình muốn xây gì rồi, chỉ cần ghi lại" | Product Brief | -| "Tôi muốn chắc rằng ý tưởng này thực sự đáng để xây" | PRFAQ | -| "Tôi muốn khám phá, rồi kiểm chứng, rồi ghi lại" | Brainstorming → Research → PRFAQ hoặc Brief | - -Product Brief và PRFAQ đều tạo ra đầu vào cho PRD. Hãy chọn một trong hai tùy vào mức độ thách thức bạn muốn. Brief là discovery mang tính cộng tác. PRFAQ là một bài kiểm tra khắc nghiệt. Cả hai đều đưa bạn tới cùng một đích; PRFAQ chỉ kiểm tra xem concept của bạn có thật sự xứng đáng để đến đó hay không. - -:::tip[Chưa chắc nên bắt đầu ở đâu?] -Hãy chạy `bmad-help` và mô tả tình huống của bạn. Nó sẽ gợi ý điểm bắt đầu phù hợp dựa trên những gì bạn đã làm và điều bạn đang muốn đạt được. -::: - -## Sau giai đoạn phân tích thì chuyện gì xảy ra? - -Đầu ra từ giai đoạn phân tích đi thẳng vào giai đoạn 2, lập kế hoạch. Quy trình tạo PRD chấp nhận product brief, tài liệu PRFAQ, kết quả nghiên cứu và báo cáo động não làm đầu vào. Nó sẽ tổng hợp bất cứ thứ gì bạn đã tạo thành các yêu cầu có cấu trúc. Bạn làm phân tích càng kỹ, PRD của bạn càng sắc. \ No newline at end of file diff --git a/docs/vi-vn/explanation/brainstorming.md b/docs/vi-vn/explanation/brainstorming.md deleted file mode 100644 index f2e69adf23..0000000000 --- a/docs/vi-vn/explanation/brainstorming.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -title: "Động não ý tưởng" -description: Các phiên sáng tạo tương tác sử dụng hơn 60 kỹ thuật khơi ý đã được kiểm chứng -sidebar: - order: 3 ---- - -Mở khóa sự sáng tạo của bạn thông qua quá trình khám phá có hướng dẫn. - -## Động não ý tưởng là gì? - -Chạy `bmad-brainstorming` và bạn sẽ có một người điều phối sáng tạo giúp rút ý tưởng từ chính bạn - không phải phát sinh thay bạn. AI đóng vai trò huấn luyện viên và người dẫn đường, sử dụng các kỹ thuật đã được kiểm chứng để tạo điều kiện cho những ý tưởng tốt nhất của bạn xuất hiện. - -**Phù hợp cho:** - -- Phá vỡ thế bí ý tưởng -- Tạo ý tưởng sản phẩm hoặc tính năng -- Xem xét vấn đề từ góc nhìn mới -- Biến các khái niệm thô thành kế hoạch hành động - -## Nó hoạt động như thế nào - -1. **Thiết lập** - Xác định chủ đề, mục tiêu, ràng buộc -2. **Chọn cách tiếp cận** - Tự chọn kỹ thuật, để AI đề xuất, chọn ngẫu nhiên, hoặc đi theo một luồng tiến trình -3. **Điều phối** - Làm việc qua từng kỹ thuật bằng các câu hỏi gợi mở và huấn luyện cộng tác -4. **Sắp xếp** - Gom ý tưởng theo chủ đề và ưu tiên hóa -5. **Hành động** - Các ý tưởng tốt nhất sẽ được gán bước tiếp theo và chỉ số thành công - -Mọi thứ đều được ghi lại trong tài liệu phiên làm việc để bạn có thể xem lại sau này hoặc chia sẻ với stakeholder. - -:::note[Ý tưởng của bạn] -Mọi ý tưởng đều đến từ bạn. Workflow chỉ tạo điều kiện cho insight xuất hiện - nguồn gốc vẫn là bạn. -::: diff --git a/docs/vi-vn/explanation/build.md b/docs/vi-vn/explanation/build.md deleted file mode 100644 index 6450c58d4d..0000000000 --- a/docs/vi-vn/explanation/build.md +++ /dev/null @@ -1,77 +0,0 @@ ---- -title: "Build" -description: Giảm ma sát có người trong vòng lặp mà vẫn giữ các điểm kiểm tra bảo vệ chất lượng đầu ra -sidebar: - order: 7 ---- - -`bmad-build` là workflow triển khai chuẩn cho mọi công việc phát triển. Nó nhận mọi đầu vào từ ý định tự do hoặc issue đến story đã lập kế hoạch đầy đủ, rồi tạo thay đổi mã nguồn với số vòng tương tác con người tối thiểu nhưng an toàn. - -Planning upstream vẫn tùy chọn và có độ sâu khác nhau. Thay đổi rõ ràng có thể vào trực tiếp; sáng kiến lớn có thể mang theo PRD, UX, kiến trúc, epic, story, kiểm tra sẵn sàng và kế hoạch sprint. Các artifact này tăng cường ngữ cảnh, không chọn workflow phát triển khác. - -Khi một story đã lập kế hoạch đi vào Build, story vẫn là nguồn ngữ cảnh sản phẩm và tiêu chí chấp nhận. Build tạo bản ghi thực thi riêng cho lần chạy hiện tại để các quyết định triển khai và phát hiện review có thể truy vết mà không thay thế story. - -Nó cho phép mô hình tự vận hành lâu hơn giữa các điểm kiểm tra, rồi chỉ đưa con người quay lại khi tác vụ không thể tiếp tục an toàn nếu thiếu phán đoán của con người, hoặc khi đã đến lúc rà soát kết quả cuối. - -![Sơ đồ quy trình bmad-build](/diagrams/build-run.svg) - -## Vì sao nó tồn tại - -Các lượt có người trong vòng lặp vừa cần thiết vừa tốn kém. - -LLM hiện tại vẫn thất bại theo những cách dễ đoán: hiểu sai ý định, tự điền vào khoảng trống bằng những phán đoán tự tin, lệch sang công việc không liên quan, và tạo ra các bản review nhiễu. Đồng thời, việc cần con người nhảy vào liên tục làm giảm tốc độ phát triển. Sự chú ý của con người là nút thắt. - -`bmad-build` cân bằng lại đánh đổi đó. Nó tin mô hình có thể chạy tự chủ lâu hơn, nhưng chỉ sau khi quy trình đã tạo được một ranh giới đủ mạnh để làm điều đó an toàn. - -## Thiết kế cốt lõi - -### 1. Nén ý định trước - -Quy trình bắt đầu bằng việc để con người và mô hình nén yêu cầu thành một mục tiêu thống nhất. Đầu vào có thể bắt đầu như một ý định thô, nhưng trước khi quy trình tự vận hành thì nó phải đủ nhỏ, đủ rõ ràng, và đủ ít mâu thuẫn để có thể thực thi. - -Ý định có thể đến từ nhiều dạng: vài cụm từ, liên kết trình theo dõi lỗi, đầu ra từ chế độ lập kế hoạch, đoạn văn bản sao chép từ phiên chat, hoặc story đã lập kế hoạch từ epic và artifact sprint của BMad. Workflow sử dụng mọi ngữ cảnh upstream hiện có và giải quyết các khoảng trống cần thiết để triển khai an toàn. - -Quy trình này không loại bỏ quyền kiểm soát của con người. Nó chuyển nó về một số thời điểm có giá trị cao: - -- **Làm rõ ý định** - biến một yêu cầu lộn xộn thành một mục tiêu thống nhất, không mâu thuẫn ngầm -- **Phê duyệt đặc tả** - xác nhận rằng cách hiểu đã được chốt là đúng thứ cần xây -- **Rà soát sản phẩm cuối** - điểm kiểm tra chính, nơi con người quyết định kết quả cuối có chấp nhận được hay không - -### 2. Định tuyến theo con đường an toàn nhỏ nhất - -Khi mục tiêu đã rõ, quy trình sẽ quyết định đây có phải thay đổi thực hiện một lần là xong hay cần đi theo đường đầy đủ hơn. Những thay đổi nhỏ, phạm vi ảnh hưởng gần như bằng 0 có thể đi thẳng vào triển khai. Còn lại sẽ đi qua lập kế hoạch để mô hình có được một ranh giới mạnh hơn trước khi tự chạy lâu hơn. - -### 3. Chạy lâu hơn với ít giám sát hơn - -Sau quyết định định tuyến đó, mô hình có thể tự gánh thêm công việc. Trên con đường đầy đủ, đặc tả đã được phê duyệt trở thành ranh giới mà mô hình sẽ thực thi với ít giám sát hơn, và đó chính là mục tiêu của thiết kế này. - -### 4. Chẩn đoán lỗi ở đúng tầng - -Nếu triển khai sai vì ý định sai, vậy sửa code không phải cách sửa đúng. Nếu code sai vì đặc tả yếu, thì vá diff cũng không phải cách sửa đúng. Quy trình được thiết kế để chẩn đoán lỗi đã đi vào hệ thống từ tầng nào, quay lại đúng tầng đó, rồi sinh lại từ đấy. - -Các phát hiện từ bước rà soát được dùng để xác định vấn đề đến từ ý định, quá trình tạo đặc tả, hay triển khai cục bộ. Chỉ những lỗi thật sự cục bộ mới được sửa tại chỗ. - -### 5. Chỉ đưa con người quay lại khi cần - -Bước phỏng vấn ý định có người trong vòng lặp, nhưng nó không giống một điểm kiểm tra lặp đi lặp lại. Quy trình cố gắng giảm thiểu những điểm kiểm tra lặp lại đó. Sau bước định hình ý định ban đầu, con người chủ yếu quay lại khi quy trình không thể tiếp tục an toàn nếu thiếu phán đoán, và ở cuối quy trình để rà soát kết quả. - -- **Xử lý khoảng trống của ý định** - quay lại khi review cho thấy workflow không thể suy ra an toàn điều được hàm ý - -Mọi thứ còn lại đều là ứng viên cho việc thực thi tự chủ lâu hơn. Đánh đổi này là có chủ đích. Các mẫu cũ tốn nhiều sự chú ý của con người cho việc giám sát liên tục. Build đặt nhiều niềm tin hơn vào mô hình, nhưng để dành sự chú ý của con người cho những thời điểm mà lý trí con người có đòn bẩy lớn nhất. - -## Vì sao hệ thống review quan trọng - -Giai đoạn rà soát không chỉ để tìm lỗi. Nó còn để định tuyến cách sửa mà không phá hỏng động lượng. - -Quy trình này hoạt động tốt nhất trên nền tảng có thể tạo subagent, hoặc ít nhất gọi được một LLM khác qua dòng lệnh và đợi kết quả. Nếu nền tảng của bạn không hỗ trợ sẵn, bạn có thể thêm skill để làm việc đó. Các subagent không mang ngữ cảnh là một trụ cột trong thiết kế rà soát. - -Rà soát kiểu agent thường sai theo hai cách: - -- Tạo quá nhiều phát hiện, buộc con người lọc quá nhiều nhiễu. -- Làm lệch thay đổi hiện tại bằng cách kéo vào các vấn đề không liên quan, biến mỗi lần chạy thành một dự án dọn dẹp chắp vá. - -Build xử lý cả hai bằng cách coi rà soát là bước phân loại. - -Có những phát hiện thuộc về thay đổi hiện tại. Có những phát hiện không thuộc về nó. Nếu một phát hiện chỉ là ngẫu nhiên xuất hiện, không gắn nhân quả với thay đổi đang làm, quy trình có thể trì hoãn nó thay vì ép con người xử lý ngay. Điều đó giữ cho mỗi lần chạy tập trung và ngăn các ngả rẽ ngẫu nhiên ăn hết ngân sách chú ý. - -Quá trình triage này đôi khi sẽ không hoàn hảo. Điều đó chấp nhận được. Thường tốt hơn khi đánh giá sai một số phát hiện còn hơn là nhận về hàng ngàn bình luận review giá trị thấp. Hệ thống tối ưu cho chất lượng tín hiệu, không phải độ phủ tuyệt đối. diff --git a/docs/vi-vn/explanation/established-projects-faq.md b/docs/vi-vn/explanation/established-projects-faq.md deleted file mode 100644 index 7d7e6528e9..0000000000 --- a/docs/vi-vn/explanation/established-projects-faq.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -title: "FAQ cho dự án đã tồn tại" -description: Các câu hỏi phổ biến khi dùng BMad Method trên dự án đã tồn tại -sidebar: - order: 10 ---- - -Các câu trả lời nhanh cho những câu hỏi thường gặp khi làm việc với dự án đã tồn tại bằng BMad Method (BMM). - -## Các câu hỏi - -- [Tôi có phải chạy document-project trước không?](#toi-co-phai-chay-document-project-truoc-khong) -- [Nếu tôi quên chạy document-project thì sao?](#neu-toi-quen-chay-document-project-thi-sao) -- [Implementation hoạt động thế nào trong dự án đã tồn tại?](#implementation-hoat-dong-the-nao-trong-du-an-da-ton-tai) -- [Nếu code hiện tại của tôi không theo best practices thì sao?](#neu-code-hien-tai-cua-toi-khong-theo-best-practices-thi-sao) - -### Tôi có phải chạy document-project trước không? - -Rất nên chạy, nhất là khi: - -- Không có tài liệu sẵn có -- Tài liệu đã lỗi thời -- Agent AI cần context về code hiện có - -Bạn có thể bỏ qua nếu đã có tài liệu đầy đủ, mới, bao gồm `docs/index.md`, hoặc bạn sẽ dùng công cụ/kỹ thuật khác để giúp agent khám phá hệ thống hiện có. - -### Nếu tôi quên chạy document-project thì sao? - -Không sao - bạn có thể chạy nó bất cứ lúc nào. Bạn thậm chí có thể chạy trong khi dự án đang diễn ra hoặc sau đó để giữ tài liệu luôn mới. - -### Implementation hoạt động thế nào trong dự án đã tồn tại? - -Chạy `bmad-build`, giống như với dự án mới. Workflow sẽ: - -- Tự động nhận diện stack hiện có -- Phân tích pattern code hiện có -- Phát hiện quy ước và hỏi bạn để xác nhận -- Tạo spec giàu ngữ cảnh, tôn trọng code hiện có - -Bạn có thể vào trực tiếp với thay đổi rõ ràng, hoặc cung cấp story đã lập kế hoạch cùng các artifact upstream cho công việc lớn hơn. - -### Nếu code hiện tại của tôi không theo best practices thì sao? - -Build sẽ nhận diện quy ước hiện có và hỏi: "Tôi có nên tuân theo những quy ước hiện tại này không?" Bạn là người quyết định: - -- **Có** → Giữ tính nhất quán với codebase hiện tại -- **Không** → Đặt ra chuẩn mới, đồng thời ghi rõ lý do trong spec - -BMM tôn trọng lựa chọn của bạn - nó không ép buộc hiện đại hóa, nhưng sẽ đưa ra lựa chọn đó. - -**Có câu hỏi chưa được trả lời ở đây?** Hãy [mở issue](https://github.com/bmad-code-org/BMAD-METHOD/issues) hoặc hỏi trên [Discord](https://discord.gg/gk8jAdXWmj) để chúng tôi bổ sung! diff --git a/docs/vi-vn/explanation/named-agents.md b/docs/vi-vn/explanation/named-agents.md deleted file mode 100644 index ac2f29a64d..0000000000 --- a/docs/vi-vn/explanation/named-agents.md +++ /dev/null @@ -1,97 +0,0 @@ ---- -title: "Agent có tên riêng (Named Agents)" -description: Vì sao các agent của BMad có tên, persona và bề mặt tùy chỉnh riêng, và điều đó mở khóa điều gì so với cách tiếp cận dựa trên menu hoặc prompt trống -sidebar: - order: 1 ---- - -Bạn nói: "Hey Mary, brainstorm với tôi nhé", và Mary được kích hoạt. Cô ấy chào bạn theo tên, bằng ngôn ngữ bạn đã cấu hình, với persona đặc trưng của riêng mình. Cô ấy nhắc rằng `bmad-help` luôn sẵn sàng. Rồi cô ấy bỏ qua menu và đi thẳng vào brainstorming vì ý định của bạn đã đủ rõ. - -Trang này giải thích điều gì thực sự đang diễn ra và vì sao BMad được thiết kế theo cách đó. - -## Chiếc ghế ba chân - -Mô hình agent của BMad đứng trên ba primitive kết hợp với nhau: - -| Thành phần nền (primitive) | Nó cung cấp gì | Nó nằm ở đâu | -|---|---|---| -| **Skill** | Năng lực, tức một việc rời rạc mà assistant có thể làm như brainstorming, viết PRD hay triển khai story | `.claude/skills/{skill-name}/SKILL.md` hoặc vị trí tương đương theo IDE | -| **Named agent** | Tính liên tục của persona, tức một danh tính dễ nhận ra bọc quanh một nhóm skill có cùng giọng điệu, nguyên tắc và dấu hiệu nhận biết | Các skill có thư mục bắt đầu bằng `bmad-agent-*` | -| **Customization** | Khả năng biến nó thành của riêng bạn: override để đổi hành vi của agent, thêm tích hợp MCP, thay template, chồng convention của tổ chức | `_bmad/custom/{skill-name}.toml` cho team và `.user.toml` cho cá nhân | - -Chỉ cần bỏ đi một chân là trải nghiệm sẽ sụp: - -- Skill mà không có agent sẽ thành danh sách khả năng mà người dùng phải tự nhớ tên hoặc mã -- Agent mà không có skill sẽ chỉ là persona không có gì để làm -- Không có customization thì mọi người đều nhận cùng một hành vi mặc định, và muốn thêm convention nội bộ là phải fork - -## Named agents mang lại điều gì - -BMad hiện có năm named agent, mỗi agent gắn với một phase trong BMad Method: - -| Agent | Phase | Module | -|---|---|---| -| 📊 **Mary**, Chuyên viên phân tích nghiệp vụ (Business Analyst) | Analysis | market research, brainstorming, product briefs, PRFAQs | -| 📋 **John**, Quản lý sản phẩm (Product Manager) | Planning | PRD creation, epic/story breakdown, implementation readiness | -| 🎨 **Sally**, Nhà thiết kế UX (UX Designer) | Planning | UX design specifications | -| 🏗️ **Winston**, Kiến trúc sư hệ thống (System Architect) | Solutioning | technical architecture, alignment checks | -| 💻 **Amelia**, Kỹ sư cấp cao (Senior Engineer) | Implementation | story execution, build, code review, sprint planning | - -:::note[Paige đâu rồi?] -📚 **Paige**, Technical Writer, đang tạm nghỉ — cô ấy sẽ trở lại trong tương lai với năng lực mạnh hơn nhiều. Tài liệu dự án vẫn được hỗ trợ: gọi trực tiếp skill `bmad-document-project` hoặc qua menu của Mary. -::: - -Mỗi agent có một danh tính hardcode gồm tên, chức danh, domain, và một lớp có thể tùy chỉnh gồm vai trò, nguyên tắc, phong cách giao tiếp, icon và menu. Bạn có thể viết lại nguyên tắc của Mary hoặc thêm menu item cho cô ấy, nhưng bạn không thể đổi tên cô ấy. Đó là chủ ý thiết kế. Nhận diện thương hiệu của agent phải sống sót qua lớp tùy chỉnh để câu "hey Mary" luôn kích hoạt đúng analyst, bất kể team đã nắn hành vi của cô ấy theo cách nào. - -## Luồng kích hoạt - -Khi bạn gọi một named agent, tám bước sau sẽ chạy theo thứ tự: - -1. **Resolve cấu hình agent**: merge `customize.toml` gốc với override của team và cá nhân qua một Python resolver dùng `tomllib` -2. **Chạy các bước tiền xử lý (prepend steps)**: mọi hành vi pre-flight mà team đã cấu hình -3. **Nhập persona**: danh tính hardcode cộng với vai trò, phong cách giao tiếp và nguyên tắc đã tùy chỉnh -4. **Nạp persistent facts**: quy tắc tổ chức, ghi chú compliance, hoặc cả file được nạp qua tiền tố `file:` -5. **Nạp config**: tên người dùng, ngôn ngữ giao tiếp, ngôn ngữ đầu ra, đường dẫn artifact -6. **Chào người dùng**: lời chào cá nhân hóa, đúng ngôn ngữ cấu hình và có emoji prefix của agent để bạn nhìn là biết ai đang nói -7. **Chạy các bước hậu xử lý (append steps)**: mọi bước thiết lập sau lời chào mà team đã cấu hình -8. **Dispatch hoặc hiện menu**: nếu tin nhắn mở đầu của bạn khớp một menu item thì agent đi thẳng vào đó, nếu không thì hiện menu và chờ input - -Bước 8 là nơi ý định gặp năng lực. Câu "Hey Mary, brainstorm với tôi nhé" bỏ qua phần render menu vì `bmad-brainstorming` là một mapping quá rõ với mục `BP` trong menu của Mary. Nếu bạn nói mơ hồ, cô ấy chỉ hỏi lại một lần, ngắn gọn, chứ không biến xác nhận thành nghi thức. Nếu chẳng có mục nào phù hợp, cô ấy tiếp tục cuộc hội thoại như bình thường. - -## Vì sao không chỉ dùng menu - -Menu buộc người dùng phải chủ động học công cụ. Bạn phải nhớ brainstorming nằm dưới mã `BP` của analyst chứ không phải PM, và phải nhớ persona nào sở hữu nhóm khả năng nào. Toàn bộ gánh nặng nhận thức đó do công cụ đẩy sang cho người dùng. - -Named agents đảo ngược điều đó. Bạn chỉ cần nói điều mình muốn, với đúng người mình nghĩ tới, bằng ngôn từ tự nhiên. Agent biết họ là ai và họ làm gì. Khi ý định của bạn đủ rõ, họ chỉ việc bắt đầu. - -Menu vẫn còn đó như một phương án dự phòng, hiện ra khi bạn đang khám phá, và biến mất khi bạn không cần nó. - -## Vì sao không chỉ dùng prompt trống - -Prompt trống giả định rằng bạn biết "câu thần chú". "Giúp tôi brainstorm" có thể hiệu quả, nhưng "hãy ideate giúp tôi một ý tưởng SaaS" có thể cho kết quả khác, và đầu ra phụ thuộc khá nhiều vào cách bạn diễn đạt. Khi đó người dùng gần như phải kiêm luôn vai trò kỹ sư prompt (prompt engineer). - -Named agents thêm cấu trúc mà không đóng mất sự tự do. Persona giữ ổn định, năng lực thì dễ khám phá, và `bmad-help` luôn chỉ cách bạn một lệnh. Bạn không phải đoán agent làm được gì, nhưng cũng không cần học thuộc một cuốn manual để dùng nó. - -## Tùy chỉnh là công dân hạng nhất - -Chính mô hình customization làm cho cách tiếp cận này mở rộng được ra ngoài phạm vi của một lập trình viên đơn lẻ. - -Mỗi agent đi kèm một `customize.toml` với mặc định hợp lý. Team có thể commit override vào `_bmad/custom/bmad-agent-{role}.toml`. Mỗi cá nhân có thể chồng thêm sở thích riêng trong `.user.toml` bị gitignore. Resolver sẽ merge cả ba lớp tại thời điểm kích hoạt theo các quy tắc có tính dự đoán. - -Đa số người dùng không cần tự tay viết các file đó. Skill `bmad-customize` sẽ dẫn họ qua việc chọn đúng mục tiêu, quyết định override ở mức agent hay workflow, viết file và xác minh merge. Nhờ vậy bề mặt tùy chỉnh vẫn tiếp cận được với bất cứ ai hiểu ý định của mình, chứ không chỉ người rành TOML. - -Ví dụ cụ thể: một team commit một file yêu cầu Amelia luôn dùng Context7 MCP tool khi tra tài liệu thư viện, và fallback sang Linear nếu story không xuất hiện trong danh sách epic cục bộ. Từ đó mọi dev workflow mà Amelia dispatch như `build`, `code-review`, `qa-generate` đều tự động thừa hưởng hành vi này mà không cần sửa source hay lặp lại cấu hình từng workflow. - -Ngoài ra còn có một bề mặt tùy chỉnh thứ hai cho các mối quan tâm *xuyên suốt*: `_bmad/config.toml`, `_bmad/config.user.toml`, `_bmad/custom/config.toml` và `_bmad/custom/config.user.toml`. Đây là nơi **agent roster** sống, tức các descriptor gọn nhẹ mà những skill như `bmad-party-mode`, `bmad-retrospective` và `bmad-advanced-elicitation` dùng để biết ai có mặt và phải nhập vai họ thế nào. Bạn có thể rebrand một agent cho cả tổ chức bằng team override, hoặc thêm những giọng hư cấu như Kirk, Spock hay một persona chuyên gia domain qua `.user.toml`, tất cả mà không cần đụng vào thư mục skill. File per-skill quyết định Mary *hành xử* như thế nào khi cô ấy kích hoạt; cấu hình trung tâm quyết định các skill khác *nhìn thấy* cô ấy ra sao khi quan sát toàn bộ đội hình. - -Để xem toàn bộ bề mặt tùy chỉnh và ví dụ thực tế: - -- [Cách tùy chỉnh BMad](../how-to/customize-bmad.md): tài liệu tham chiếu cho những gì có thể tùy chỉnh và merge diễn ra thế nào -- [Cách mở rộng BMad cho tổ chức của bạn](../how-to/expand-bmad-for-your-org.md): năm recipe hoàn chỉnh trải từ quy tắc ở cấp agent, convention workflow, publish ra hệ thống ngoài, thay template đầu ra đến tùy chỉnh roster agent -- Skill `bmad-customize`: trợ lý soạn cấu hình (authoring helper) có hướng dẫn để biến ý định thành một file override đúng chỗ và đã được kiểm chứng - -## Ý tưởng lớn hơn phía sau - -Hầu hết các trợ lý AI (AI assistant) ngày nay hoặc là menu, hoặc là prompt, và cả hai đều chuyển phần gánh nặng nhận thức sang người dùng. Agent có tên riêng kết hợp với skill có thể tùy chỉnh cho phép bạn trò chuyện với một đồng đội đã hiểu công việc, đồng thời cho phép tổ chức của bạn nắn đồng đội đó theo nhu cầu mà không cần fork. - -Lần tới khi bạn gõ "Hey Mary, brainstorm với tôi nhé" và cô ấy chỉ việc bắt tay vào làm, hãy để ý thứ đã *không* xảy ra. Không có slash command. Không có menu phải điều hướng. Không có lời nhắc gượng gạo về những gì cô ấy có thể làm. Chính sự vắng mặt đó mới là thiết kế. diff --git a/docs/vi-vn/explanation/party-mode.md b/docs/vi-vn/explanation/party-mode.md deleted file mode 100644 index 9c52913729..0000000000 --- a/docs/vi-vn/explanation/party-mode.md +++ /dev/null @@ -1,59 +0,0 @@ ---- -title: "Chế độ Party" -description: Cộng tác đa agent - đưa tất cả agent AI vào cùng một cuộc trò chuyện -sidebar: - order: 8 ---- - -Đưa tất cả agent AI của bạn vào cùng một cuộc trò chuyện. - -## Party Mode là gì? - -Chạy `bmad-party-mode` và bạn sẽ có cả đội AI trong cùng một phòng - PM, Architect, Dev, UX Designer, bất kỳ ai bạn cần. BMad Master điều phối, chọn các agent liên quan cho từng tin nhắn. Các agent trả lời đúng vai, đồng ý, phản biện, và bổ sung ý tưởng cho nhau. - -Cuộc trò chuyện tiếp tục lâu đến mức bạn muốn. Bạn có thể hỏi tiếp, phản biện câu trả lời, đổi hướng thảo luận - đó là một cuộc qua lại thật sự với các agent của bạn cho đến khi xong. - -**Phù hợp cho:** - -- Các quyết định lớn có đánh đổi -- Các phiên động não ý tưởng -- Post-mortem khi mọi thứ đi sai -- Retrospective và lập kế hoạch sprint - -## Ví dụ - -### Gọi tên kiến trúc tệ - -**Bạn:** "Được rồi cả đội, sprint vừa rồi là một thảm họa. Dịch vụ xác thực sập ba lần. Ai đã làm hỏng chuyện này?" - -**Architect:** "Thiết kế vẫn ổn - xác thực phân tán với cơ chế fallback hợp lý. Nếu phần triển khai lệch khỏi spec..." - -**Dev:** "Tôi đã làm đúng theo tài liệu kiến trúc. Spec không tính đến race condition khi vô hiệu hóa session đồng thời." - -**PM:** "Cả hai người đều bỏ sót vấn đề lớn hơn - chúng ta không xác thực đúng yêu cầu quản lý session trong PRD. **Lỗi này là do tôi** không bắt được sớm hơn." - -**TEA:** "Và tôi đáng ra phải bắt được nó trong integration test. Các kịch bản test đã không bao phủ trường hợp vô hiệu hóa đồng thời." - -### Động não sáng tạo - -**Bạn:** "Làm sao để quá trình onboarding có cảm giác kỳ diệu thay vì nhàm chán?" - -**UX Designer:** "Bắt đầu bằng progressive disclosure - hiện tính năng khi người dùng cần, thay vì tung một tutorial dày đặc." - -**Storyteller:** "Nếu onboarding là một câu chuyện thì sao? Mỗi bước mở ra hành trình của một nhân vật - người dùng CHÍNH là người hùng." - -**Game Designer:** "Nối tiếp ý đó - nếu 'nhiệm vụ' đầu tiên thực chất giải quyết một vấn đề thật của người dùng thì sao? Họ học bằng cách làm ra giá trị ngay." - -### Quyết định kỹ thuật - -**Bạn:** "MVP nên dùng monolith hay microservices?" - -**Architect:** "Bắt đầu bằng monolith. Microservices thêm độ phức tạp mà bạn chưa cần ở mức 1000 người dùng." - -**PM:** "Đồng ý. Tốc độ ra thị trường quan trọng hơn khả năng mở rộng lý thuyết." - -**Dev:** "Monolith nhưng có ranh giới module rõ ràng. Nếu cần, mình có thể tách service sau." - -:::tip[Quyết định tốt hơn] -Quyết định tốt hơn nhờ nhiều góc nhìn đa dạng. Chào mừng đến với party mode. -::: diff --git a/docs/vi-vn/explanation/preventing-agent-conflicts.md b/docs/vi-vn/explanation/preventing-agent-conflicts.md deleted file mode 100644 index 44a4c3d036..0000000000 --- a/docs/vi-vn/explanation/preventing-agent-conflicts.md +++ /dev/null @@ -1,112 +0,0 @@ ---- -title: "Ngăn xung đột giữa các agent" -description: Cách kiến trúc ngăn xung đột khi nhiều agent cùng triển khai một hệ thống -sidebar: - order: 6 ---- - -Khi nhiều agent AI cùng triển khai các phần khác nhau của hệ thống, chúng có thể đưa ra các quyết định kỹ thuật mâu thuẫn nhau. Tài liệu kiến trúc ngăn điều đó bằng cách thiết lập các tiêu chuẩn dùng chung. - -## Các kiểu xung đột phổ biến - -### Xung đột về phong cách API - -Không có kiến trúc: -- Agent A dùng REST với `/users/{id}` -- Agent B dùng GraphQL mutations -- Kết quả: pattern API không nhất quán, người dùng API bị rối - -Có kiến trúc: -- ADR quy định: "Dùng GraphQL cho mọi giao tiếp client-server" -- Tất cả agent theo cùng một mẫu - -### Xung đột về thiết kế cơ sở dữ liệu - -Không có kiến trúc: -- Agent A dùng tên cột theo snake_case -- Agent B dùng camelCase -- Kết quả: schema không nhất quán, truy vấn khó hiểu - -Có kiến trúc: -- Tài liệu standards quy định quy ước đặt tên -- Tất cả agent theo cùng một pattern - -### Xung đột về quản lý state - -Không có kiến trúc: -- Agent A dùng Redux cho global state -- Agent B dùng React Context -- Kết quả: nhiều cách quản lý state song song, độ phức tạp tăng cao - -Có kiến trúc: -- ADR quy định cách quản lý state -- Tất cả agent triển khai thống nhất - -## Kiến trúc ngăn xung đột bằng cách nào - -### 1. Quyết định rõ ràng thông qua ADR - -Mỗi lựa chọn công nghệ quan trọng đều được ghi lại với: -- Context (vì sao quyết định này quan trọng) -- Các lựa chọn đã cân nhắc (có những phương án nào) -- Quyết định (ta đã chọn gì) -- Lý do (tại sao lại chọn như vậy) -- Hệ quả (các đánh đổi được chấp nhận) - -### 2. Hướng dẫn riêng cho FR/NFR - -Kiến trúc ánh xạ mỗi functional requirement sang cách tiếp cận kỹ thuật: -- FR-001: User Management → GraphQL mutations -- FR-002: Mobile App → Truy vấn tối ưu - -### 3. Tiêu chuẩn và quy ước - -Tài liệu hóa rõ ràng về: -- Cấu trúc thư mục -- Quy ước đặt tên -- Cách tổ chức code -- Pattern kiểm thử - -## Kiến trúc như một bối cảnh dùng chung - -Hãy xem kiến trúc là bối cảnh dùng chung mà tất cả agent đều đọc trước khi triển khai: - -```text -PRD: "Cần xây gì" - ↓ -Kiến trúc: "Xây như thế nào" - ↓ -Agent A đọc kiến trúc → triển khai Epic 1 -Agent B đọc kiến trúc → triển khai Epic 2 -Agent C đọc kiến trúc → triển khai Epic 3 - ↓ -Kết quả: Triển khai nhất quán -``` - -## Các chủ đề ADR quan trọng - -Những quyết định phổ biến giúp tránh xung đột: - -| Chủ đề | Ví dụ quyết định | -| ---------------- | -------------------------------------------- | -| API Style | GraphQL hay REST hay gRPC | -| Database | PostgreSQL hay MongoDB | -| Auth | JWT hay Session | -| State Management | Redux hay Context hay Zustand | -| Styling | CSS Modules hay Tailwind hay Styled Components | -| Testing | Jest + Playwright hay Vitest + Cypress | - -## Anti-pattern cần tránh - -:::caution[Những lỗi thường gặp] -- **Quyết định ngầm** - "Cứ để đó rồi tính phong cách API sau" sẽ dẫn đến không nhất quán -- **Tài liệu hóa quá mức** - Ghi lại mọi lựa chọn nhỏ gây tê liệt phân tích -- **Kiến trúc lỗi thời** - Tài liệu viết một lần rồi không cập nhật khiến agent đi theo pattern cũ -::: - -:::tip[Cách tiếp cận đúng] -- Tài liệu hóa những quyết định cắt ngang nhiều epic -- Tập trung vào những khu vực dễ phát sinh xung đột -- Cập nhật kiến trúc khi bạn học thêm -- Dùng `bmad-correct-course` cho các thay đổi đáng kể -::: diff --git a/docs/vi-vn/explanation/project-context.md b/docs/vi-vn/explanation/project-context.md deleted file mode 100644 index aaa2bba062..0000000000 --- a/docs/vi-vn/explanation/project-context.md +++ /dev/null @@ -1,155 +0,0 @@ ---- -title: "Bối cảnh dự án" -description: Cách project-context.md định hướng các agent AI theo quy tắc và ưu tiên của dự án -sidebar: - order: 9 ---- - -Tệp `project-context.md` là kim chỉ nam cho việc triển khai của các agent AI trong dự án của bạn. Tương tự như một "bản hiến pháp" trong các hệ thống phát triển khác, nó ghi lại các quy tắc, pattern và ưu tiên giúp việc sinh mã được nhất quán trong mọi workflow. - -## Nó làm gì - -Các agent AI liên tục đưa ra quyết định triển khai - theo pattern nào, tổ chức code ra sao, dùng quy ước gì. Nếu không có hướng dẫn rõ ràng, chúng có thể: -- Làm theo best practice chung chung không khớp với codebase của bạn -- Đưa ra quyết định không nhất quán giữa các story -- Bỏ sót yêu cầu hoặc ràng buộc đặc thù của dự án - -Tệp `project-context.md` giải quyết vấn đề này bằng cách tài liệu hóa những gì agent cần biết trong định dạng ngắn gọn, tối ưu cho LLM. - -## Nó hoạt động như thế nào - -Mỗi workflow triển khai đều tự động nạp `project-context.md` nếu tệp tồn tại. Workflow architect cũng nạp tệp này để tôn trọng các ưu tiên kỹ thuật của bạn khi thiết kế kiến trúc. - -**Được nạp bởi các workflow sau:** -- `bmad-architecture` - tôn trọng ưu tiên kỹ thuật trong giai đoạn solutioning -- `bmad-code-review` - đối chiếu với tiêu chuẩn của dự án -- `bmad-build` - áp dụng pattern khi lập kế hoạch và triển khai ý định trực tiếp hoặc story -- `bmad-sprint-planning`, `bmad-retrospective`, `bmad-correct-course` - cung cấp bối cảnh cấp dự án - -## Khi nào nên tạo - -Tệp `project-context.md` hữu ích ở bất kỳ giai đoạn nào của dự án: - -| Tình huống | Khi nào nên tạo | Mục đích | -|----------|----------------|---------| -| **Dự án mới, trước kiến trúc** | Tạo thủ công, trước `bmad-architecture` | Ghi lại ưu tiên kỹ thuật để architect tôn trọng | -| **Dự án mới, sau kiến trúc** | Qua `bmad-generate-project-context` hoặc tạo thủ công | Ghi lại quyết định kiến trúc cho các agent triển khai | -| **Dự án hiện có** | Qua `bmad-generate-project-context` | Khám phá pattern hiện có để agent theo đúng quy ước | -| **Đầu vào triển khai trực tiếp** | Trước hoặc trong `bmad-build` | Đảm bảo triển khai không có planning upstream vẫn tôn trọng pattern của bạn | - -:::tip[Khuyến nghị] -Với dự án mới, hãy tạo thủ công trước giai đoạn kiến trúc nếu bạn có ưu tiên kỹ thuật rõ ràng. Nếu không, hãy tạo nó sau kiến trúc để ghi lại các quyết định đã được đưa ra. -::: - -## Nội dung cần có trong tệp - -Tệp này có hai phần chính: - -### Technology Stack & Versions - -Ghi lại framework, ngôn ngữ và công cụ dự án đang dùng, kèm phiên bản cụ thể: - -```markdown -## Technology Stack & Versions - -- Node.js 20.x, TypeScript 5.3, React 18.2 -- State: Zustand (không dùng Redux) -- Testing: Vitest, Playwright, MSW -- Styling: Tailwind CSS với custom design tokens -``` - -### Critical Implementation Rules - -Ghi lại những pattern và quy ước mà agent dễ bỏ sót nếu chỉ đọc qua code: - -```markdown -## Critical Implementation Rules - -**TypeScript Configuration:** -- Bật strict mode - không dùng `any` nếu chưa có phê duyệt rõ ràng -- Dùng `interface` cho public API, `type` cho union/intersection - -**Code Organization:** -- Components đặt trong `/src/components/` và để `.test.tsx` cùng chỗ -- Utilities đặt trong `/src/lib/` cho các hàm pure có thể tái sử dụng -- Lời gọi API phải dùng `apiClient` singleton - không fetch trực tiếp - -**Testing Patterns:** -- Unit test tập trung vào business logic, không soi chi tiết implementation -- Integration test dùng MSW để mock API responses -- E2E test chỉ bao phủ các user journey quan trọng - -**Framework-Specific:** -- Mọi thao tác async dùng wrapper `handleError` để xử lý lỗi nhất quán -- Feature flags được truy cập qua `featureFlag()` từ `@/lib/flags` -- Route mới theo file-based routing pattern trong `/src/app/` -``` - -Hãy tập trung vào những gì **không hiển nhiên** - những điều agent khó suy ra chỉ từ một vài đoạn code. Không cần ghi lại các thực hành tiêu chuẩn áp dụng mọi nơi. - -## Tạo tệp - -Bạn có ba lựa chọn: - -### Tạo thủ công - -Tạo tệp tại `_bmad-output/project-context.md` và thêm các quy tắc của bạn: - -```bash -# Trong thư mục gốc của dự án -mkdir -p _bmad-output -touch _bmad-output/project-context.md -``` - -Sửa tệp để thêm stack công nghệ và quy tắc triển khai. Workflow architect và implementation sẽ tự động tìm và nạp nó. - -### Tạo sau khi hoàn thành kiến trúc - -Chạy workflow `bmad-generate-project-context` sau khi bạn hoàn tất kiến trúc: - -```bash -bmad-generate-project-context -``` - -Nó sẽ quét tài liệu kiến trúc và tệp dự án để tạo tệp context ghi lại các quyết định đã được đưa ra. - -### Tạo cho dự án hiện có - -Với dự án hiện có, chạy `bmad-generate-project-context` để khám phá pattern sẵn có: - -```bash -bmad-generate-project-context -``` - -Workflow sẽ phân tích codebase để nhận diện quy ước, sau đó tạo tệp context cho bạn xem lại và tinh chỉnh. - -## Vì sao nó quan trọng - -Nếu không có `project-context.md`, các agent sẽ tự đưa ra giả định có thể không phù hợp với dự án: - -| Không có context | Có context | -|----------------|--------------| -| Dùng pattern chung chung | Theo đúng quy ước đã được xác lập | -| Phong cách không nhất quán giữa các story | Triển khai nhất quán | -| Có thể bỏ sót ràng buộc đặc thù | Tôn trọng đầy đủ yêu cầu kỹ thuật | -| Mỗi agent tự quyết định | Tất cả agent canh hàng theo cùng quy tắc | - -Điều này đặc biệt quan trọng với: -- **Đầu vào trực tiếp** - khi không có PRD hoặc kiến trúc, tệp context cung cấp quy ước bền vững của dự án -- **Dự án theo nhóm** - đảm bảo tất cả agent theo cùng tiêu chuẩn -- **Dự án hiện có** - tránh phá vỡ các pattern đã ổn định - -## Chỉnh sửa và cập nhật - -Tệp `project-context.md` là tài liệu sống. Hãy cập nhật khi: - -- Quyết định kiến trúc thay đổi -- Có quy ước mới được thiết lập -- Pattern tiến hóa trong quá trình triển khai -- Bạn nhận ra lỗ hổng qua hành vi của agent - -Bạn có thể sửa thủ công bất kỳ lúc nào, hoặc chạy lại `bmad-generate-project-context` để cập nhật sau các thay đổi lớn. - -:::note[Vị trí tệp] -Vị trí mặc định là `_bmad-output/project-context.md`. Các workflow tìm tệp ở đó, đồng thời cũng kiểm tra `**/project-context.md` ở bất kỳ đâu trong dự án. -::: diff --git a/docs/vi-vn/explanation/why-solutioning-matters.md b/docs/vi-vn/explanation/why-solutioning-matters.md deleted file mode 100644 index 7766ce760f..0000000000 --- a/docs/vi-vn/explanation/why-solutioning-matters.md +++ /dev/null @@ -1,78 +0,0 @@ ---- -title: "Vì sao solutioning quan trọng" -description: Hiểu vì sao giai đoạn solutioning là tối quan trọng đối với dự án nhiều epic -sidebar: - order: 5 ---- - -Giai đoạn 3 (Solutioning) biến **xây gì** (từ giai đoạn Planning) thành **xây như thế nào** (thiết kế kỹ thuật). Giai đoạn này ngăn xung đột giữa các agent trong dự án nhiều epic bằng cách ghi lại các quyết định kiến trúc trước khi bắt đầu triển khai. - -## Vấn đề nếu bỏ qua solutioning - -```text -Agent 1 triển khai Epic 1 bằng REST API -Agent 2 triển khai Epic 2 bằng GraphQL -Kết quả: Thiết kế API không nhất quán, tích hợp trở thành ác mộng -``` - -Khi nhiều agent triển khai các phần khác nhau của hệ thống mà không có hướng dẫn kiến trúc chung, chúng sẽ tự đưa ra quyết định kỹ thuật độc lập và dễ xung đột với nhau. - -## Lợi ích khi có solutioning - -```text -workflow kiến trúc quyết định: "Dùng GraphQL cho mọi API" -Tất cả agent đều theo quyết định kiến trúc -Kết quả: Triển khai nhất quán, không xung đột -``` - -Bằng cách tài liệu hóa rõ ràng các quyết định kỹ thuật, tất cả agent triển khai đồng bộ và việc tích hợp trở nên đơn giản hơn nhiều. - -## Solutioning và Planning khác nhau ở đâu - -| Khía cạnh | Planning (Giai đoạn 2) | Solutioning (Giai đoạn 3) | -| -------- | ----------------------- | --------------------------------- | -| Câu hỏi | Xây gì và vì sao? | Xây như thế nào? Rồi chia thành đơn vị công việc gì? | -| Đầu ra | FR/NFR (Yêu cầu) | Kiến trúc + Epics/Stories | -| Agent | PM | Architect → PM | -| Đối tượng đọc | Stakeholder | Developer | -| Tài liệu | PRD (FRs/NFRs) | Kiến trúc + Tệp Epic | -| Mức độ | Logic nghiệp vụ | Thiết kế kỹ thuật + Phân rã công việc | - -## Nguyên lý cốt lõi - -**Biến các quyết định kỹ thuật thành tường minh và được tài liệu hóa** để tất cả agent triển khai nhất quán. - -Điều này ngăn chặn: -- Xung đột phong cách API (REST vs GraphQL) -- Không nhất quán trong thiết kế cơ sở dữ liệu -- Bất đồng về quản lý state -- Lệch quy ước đặt tên -- Biến thể trong cách tiếp cận bảo mật - -## Chọn độ sâu solutioning - -| Đặc điểm công việc | Khuyến nghị solutioning | -|-------|----------------------| -| Thay đổi cục bộ rõ ràng với pattern đã ổn định | Thường không cần | -| Nhiều component liên quan với ràng buộc đã biết | Tùy chọn theo rủi ro phối hợp | -| Nhiều epic hoặc quyết định liên hệ thống | Cần thiết để đồng bộ implementation | -| Sáng kiến tuân thủ, rủi ro cao hoặc enterprise | Tuân theo governance bắt buộc; solutioning thường là yêu cầu | - -Solutioning thay đổi ngữ cảnh cung cấp cho `bmad-build`, không thay đổi workflow triển khai. - -:::tip[Quy tắc ngón tay cái] -Nếu bạn có nhiều epic có thể được các agent khác nhau triển khai, bạn cần solutioning. -::: - -## Cái giá của việc bỏ qua - -Bỏ qua solutioning trong dự án phức tạp sẽ dẫn đến: - -- **Vấn đề tích hợp** chỉ được phát hiện giữa sprint -- **Làm lại** vì các phần triển khai xung đột nhau -- **Tổng thời gian phát triển dài hơn** -- **Nợ kỹ thuật** do pattern không đồng nhất - -:::caution[Hệ số chi phí] -Bắt được vấn đề canh hàng trong giai đoạn solutioning nhanh hơn gấp 10 lần so với để đến lúc triển khai mới phát hiện. -::: diff --git a/docs/vi-vn/how-to/customize-bmad.md b/docs/vi-vn/how-to/customize-bmad.md deleted file mode 100644 index ca2c10d2e7..0000000000 --- a/docs/vi-vn/how-to/customize-bmad.md +++ /dev/null @@ -1,399 +0,0 @@ ---- -title: 'Cách tùy chỉnh BMad' -description: Tùy chỉnh agent và workflow trong khi vẫn giữ khả năng tương thích khi cập nhật -sidebar: - order: 7 ---- - -Điều chỉnh persona của agent, chèn ngữ cảnh theo domain, thêm khả năng mới và cấu hình hành vi workflow mà không cần sửa các file đã cài. Các tùy chỉnh của bạn sẽ được giữ nguyên qua mọi lần cập nhật. - -:::tip[Không muốn tự viết TOML? Hãy dùng `bmad-customize`] -Skill `bmad-customize` là trợ lý tạo cấu hình có hướng dẫn cho **bề mặt override agent/workflow theo từng skill** được mô tả trong tài liệu này. Nó quét những gì có thể tùy chỉnh trong bản cài đặt của bạn, giúp bạn chọn đúng bề mặt (agent hay workflow), ghi file override và xác minh merge đã áp dụng. Override ở mức cấu hình trung tâm (`_bmad/custom/config.toml`) chưa nằm trong phạm vi v1, nên phần đó vẫn cần viết tay theo mục Cấu hình trung tâm bên dưới. Hãy chạy skill này khi bạn muốn thay đổi theo từng skill; tài liệu này là phần tham chiếu cho *có thể tùy chỉnh gì* và merge hoạt động ra sao. -::: - -## Khi nào nên dùng - -- Bạn muốn thay đổi tính cách hoặc phong cách giao tiếp của agent -- Bạn cần cung cấp cho agent các "persistent facts" để luôn nhớ, ví dụ "tổ chức của chúng tôi chỉ dùng AWS" -- Bạn muốn thêm các bước khởi động có tính thủ tục mà agent phải chạy mỗi phiên -- Bạn muốn thêm menu item tùy chỉnh để gọi skill hoặc prompt riêng -- Team của bạn cần các tùy chỉnh dùng chung được commit vào git, đồng thời vẫn cho phép mỗi cá nhân chồng thêm sở thích riêng - -:::note[Điều kiện tiên quyết] - -- BMad đã được cài trong dự án của bạn (xem [Cách cài đặt BMad](./install-bmad.md)) -- Một cách để chạy resolver script — BMad đang chuẩn hóa sang `uv` (`uv run`, tự cấp Python cho bạn); một `python3` 3.11+ thuần trên PATH vẫn dùng được trong giai đoạn chuyển đổi. Script chỉ dùng stdlib `tomllib`, nên không cần `pip install` gì cả. -- Một trình soạn thảo văn bản cho file TOML -::: - -## Cách hoạt động - -Mỗi skill có thể tùy chỉnh đều đi kèm một file `customize.toml` chứa cấu hình mặc định. File này định nghĩa toàn bộ bề mặt tùy chỉnh của skill, nên hãy đọc nó để biết có thể chỉnh gì. Bạn **không bao giờ** sửa trực tiếp file này. Thay vào đó, bạn tạo các file override dạng thưa, chỉ chứa những trường bạn muốn đổi. - -### Mô hình override ba lớp - -```text -Ưu tiên 1 (thắng): _bmad/custom/{skill-name}.user.toml (cá nhân, bị gitignore) -Ưu tiên 2: _bmad/custom/{skill-name}.toml (team/tổ chức, được commit) -Ưu tiên 3 (gốc): customize.toml của chính skill (mặc định) -``` - -Thư mục `_bmad/custom/` ban đầu là rỗng. File chỉ xuất hiện khi ai đó thực sự bắt đầu tùy chỉnh. - -### Quy tắc merge theo hình dạng, không theo tên trường - -Resolver áp dụng bốn quy tắc cấu trúc. Tên trường không được hardcode riêng; hành vi hoàn toàn được quyết định bởi dạng dữ liệu: - -| Dạng | Quy tắc | -|---|---| -| Scalar (string, int, bool, float) | Giá trị override sẽ thắng | -| Table | Deep merge, tức merge đệ quy theo các quy tắc này | -| Mảng các table mà mọi phần tử đều dùng cùng **một** trường định danh (`code` ở tất cả phần tử, hoặc `id` ở tất cả phần tử) | Merge theo khóa đó, phần tử trùng khóa sẽ **thay tại chỗ**, phần tử mới sẽ **append** | -| Mọi mảng khác (mảng scalar, table không có định danh, hoặc trộn `code` và `id`) | **Append**: phần tử gốc trước, rồi team, rồi user | - -**Không có cơ chế xóa.** Override không thể xóa phần tử mặc định. Nếu bạn cần vô hiệu hóa một menu item mặc định, hãy override nó theo `code` bằng mô tả hoặc prompt no-op. Nếu cần tái cấu trúc mảng sâu hơn, bạn phải fork skill. - -**Quy ước `code` / `id`.** BMad dùng `code` (định danh ngắn như `"BP"` hoặc `"R1"`) và `id` (định danh ổn định dài hơn) làm merge key cho mảng các table. Nếu bạn tự tạo một mảng table muốn có khả năng replace-by-key thay vì append-only, hãy chọn **một** quy ước duy nhất và dùng nhất quán cho toàn bộ mảng. Nếu trộn `code` ở phần tử này và `id` ở phần tử khác, resolver sẽ rơi về chế độ append vì nó không đoán merge theo khóa nào. - -### Một số trường của agent là chỉ đọc - -`agent.name` và `agent.title` vẫn nằm trong `customize.toml` như metadata nguồn gốc, nhưng `SKILL.md` của agent không đọc hai trường này ở runtime, vì danh tính của agent được hardcode. Bạn đặt `name = "Bob"` trong file override cũng sẽ không có tác dụng. Nếu bạn thật sự cần một agent với tên khác, hãy copy thư mục skill, đổi tên và phát hành nó như một custom skill. - -## Các bước thực hiện - -### 1. Tìm bề mặt tùy chỉnh của skill - -Hãy mở file `customize.toml` trong thư mục skill đã được cài. Ví dụ với PM agent: - -```text -.claude/skills/bmad-agent-pm/customize.toml -``` - -(Đường dẫn cụ thể thay đổi theo IDE: Cursor dùng `.cursor/skills/`, Cline dùng `.cline/skills/`, v.v.) - -Đây là schema chính thức. Mọi trường bạn nhìn thấy trong file này đều có thể tùy chỉnh, ngoại trừ các trường danh tính chỉ đọc đã nêu ở trên. - -### 2. Tạo file override của bạn - -Tạo thư mục `_bmad/custom/` ở root dự án nếu nó chưa tồn tại. Sau đó tạo file đặt theo tên skill: - -```text -_bmad/custom/ - bmad-agent-pm.toml # override của team (commit vào git) - bmad-agent-pm.user.toml # sở thích cá nhân (gitignore) -``` - -:::caution[KHÔNG copy nguyên file `customize.toml`] -File override phải **thưa**. Chỉ đưa vào những trường bạn thực sự muốn đổi, không hơn. - -Mọi trường bạn bỏ qua sẽ tự động được kế thừa từ lớp bên dưới. Nếu bạn copy toàn bộ `customize.toml` vào file override, những bản cập nhật sau này sẽ không chảy vào các giá trị mặc định mới nữa và bạn sẽ âm thầm bị lệch qua mỗi release. -::: - -**Ví dụ: đổi icon và thêm một principle** - -```toml -# _bmad/custom/bmad-agent-pm.toml -# Chỉ ghi những trường cần đổi. Phần còn lại vẫn kế thừa. - -[agent] -icon = "🏥" -principles = [ - "Không phát hành bất cứ thứ gì không thể vượt qua kiểm toán của FDA.", -] -``` - -Ví dụ này append thêm principle mới vào danh sách mặc định và thay icon. Mọi trường khác vẫn giữ nguyên như bản gốc. - -### 3. Tùy chỉnh đúng phần bạn cần - -Mọi ví dụ bên dưới đều giả định schema agent phẳng của BMad. Các trường nằm trực tiếp trong `[agent]`, không có các sub-table như `metadata` hay `persona`. - -**Scalar (`icon`, `role`, `identity`, `communication_style`).** Scalar override sẽ thắng, nên bạn chỉ cần đặt những trường đang muốn đổi: - -```toml -# _bmad/custom/bmad-agent-pm.toml - -[agent] -icon = "🏥" -role = "Dẫn dắt product discovery cho domain healthcare có ràng buộc pháp lý." -communication_style = "Chính xác, nhạy với compliance, đặt các câu hỏi mang hình dạng kiểm soát ngay từ sớm." -``` - -**Persistent facts, principles, activation hooks (các mảng append).** Bốn mảng dưới đây đều là append-only. Phần tử của team được thêm sau mặc định, phần tử user được thêm cuối cùng. - -```toml -[agent] -# Các fact tĩnh mà agent luôn giữ trong đầu trong cả phiên: quy tắc tổ chức, -# hằng số domain, sở thích của người dùng. Khác với runtime memory sidecar. -# -# Mỗi mục có thể là một câu literal, hoặc tham chiếu `file:` để nạp nội dung -# file làm facts (hỗ trợ cả glob). -persistent_facts = [ - "Tổ chức của chúng tôi chỉ dùng AWS, không đề xuất GCP hay Azure.", - "Mọi PRD đều phải có legal sign-off trước khi engineering kickoff.", - "Người dùng mục tiêu là bác sĩ lâm sàng, không phải bệnh nhân, nên ví dụ phải bám theo đối tượng đó.", - "file:{project-root}/docs/compliance/hipaa-overview.md", - "file:{project-root}/_bmad/custom/company-glossary.md", -] - -# Thêm vào hệ giá trị của agent -principles = [ - "Không phát hành bất cứ thứ gì không thể vượt qua kiểm toán của FDA.", - "Giá trị người dùng là trước hết, compliance là luôn luôn.", -] - -# Chạy TRƯỚC activation tiêu chuẩn (persona, persistent_facts, config, greet). -# Dùng cho pre-flight load, compliance checks, hoặc thứ gì cần có sẵn trong -# context trước khi agent tự giới thiệu. -activation_steps_prepend = [ - "Quét {project-root}/docs/compliance/ và nạp mọi tài liệu liên quan HIPAA vào context.", -] - -# Chạy SAU khi greet, TRƯỚC menu. Dùng cho thiết lập nặng về context mà bạn -# muốn chạy sau khi người dùng đã được chào. -activation_steps_append = [ - "Đọc {project-root}/_bmad/custom/company-glossary.md nếu file tồn tại.", -] -``` - -**Hai hook này có vai trò khác nhau.** `prepend` chạy trước lời chào để agent có thể nạp ngữ cảnh cần thiết ngay cả khi cá nhân hóa lời chào. `append` chạy sau lời chào để người dùng không phải nhìn màn hình trống trong lúc agent quét một lượng lớn context. - -**Tùy chỉnh menu (merge theo `code`).** Menu là một mảng table. Mỗi item có trường `code`, nên resolver merge theo mã này: item có `code` trùng sẽ thay tại chỗ, item mới sẽ được append. - -Với TOML array-of-tables, mỗi item dùng cú pháp `[[agent.menu]]`: - -```toml -# Thay item CE hiện có bằng một custom skill -[[agent.menu]] -code = "CE" -description = "Tạo Epic theo framework delivery của tổ chức" -skill = "custom-create-epics" - -# Thêm item mới (RC chưa tồn tại trong mặc định) -[[agent.menu]] -code = "RC" -description = "Chạy compliance pre-check" -prompt = """ -Đọc {project-root}/_bmad/custom/compliance-checklist.md -và quét toàn bộ tài liệu trong {planning_artifacts} theo checklist đó. -Báo cáo mọi khoảng trống và trích dẫn điều khoản quy định tương ứng. -""" -``` - -Mỗi menu item chỉ có đúng một trong hai trường `skill` hoặc `prompt`. Những item không xuất hiện trong file override của bạn sẽ giữ nguyên mặc định. - -**Tham chiếu file.** Khi một trường văn bản cần trỏ tới file (trong `persistent_facts`, `activation_steps_prepend`, `activation_steps_append`, hoặc `prompt` của menu item), hãy dùng đường dẫn đầy đủ dựa trên `{project-root}`. Dù file nằm cạnh override trong `_bmad/custom/`, bạn vẫn nên viết rõ là `{project-root}/_bmad/custom/info.md`. Agent sẽ resolve `{project-root}` ở runtime. - -### 4. Cá nhân và team - -**File của team** (`bmad-agent-pm.toml`): commit vào git, áp dụng cho cả tổ chức. Dùng cho compliance rules, company persona, năng lực tùy chỉnh dùng chung. - -**File cá nhân** (`bmad-agent-pm.user.toml`): tự động bị gitignore. Dùng cho điều chỉnh giọng điệu, sở thích workflow cá nhân và các fact riêng mà agent cần lưu ý cho riêng bạn. - -```toml -# _bmad/custom/bmad-agent-pm.user.toml - -[agent] -persistent_facts = [ - "Khi trình bày phương án, luôn kèm ước lượng độ phức tạp ở mức thô (low/medium/high).", -] -``` - -## Cách quá trình resolve diễn ra - -Khi agent được kích hoạt, `SKILL.md` của nó sẽ gọi một shared Python script để merge ba lớp nói trên và trả về block kết quả ở dạng JSON. Script này chỉ dùng `tomllib` của Python stdlib (không có dependency ngoài). BMad đang chuẩn hóa sang `uv run` để chạy các script này (uv tự cấp một bản Python phù hợp cho bạn); một `python3` thuần vẫn dùng được trong giai đoạn chuyển đổi: - -```bash -uv run {project-root}/_bmad/scripts/resolve_customization.py \ - --skill {skill-root} \ - --project-root {project-root} \ - --key agent -``` - -**Yêu cầu**: Python 3.11+ vì các phiên bản cũ hơn không có `tomllib`; không cần `pip install` gì. Chạy qua `uv run` là chuẩn về sau — uv tự tìm một bản interpreter phù hợp cho bạn. Nếu bạn chạy trực tiếp bằng `python3` trong giai đoạn chuyển đổi, hãy kiểm tra phiên bản bằng `python3 --version`: trên một số nền tảng, `python3` mặc định vẫn là 3.10 hoặc thấp hơn, nên có thể bạn sẽ phải cài 3.11+ riêng. - -`--skill` trỏ vào thư mục skill đã cài, nơi có file `customize.toml`. Tên skill được lấy từ basename của thư mục, sau đó script sẽ tự tìm `_bmad/custom/{skill-name}.toml` và `{skill-name}.user.toml`. - -Một số lệnh hữu ích: - -```bash -# Resolve toàn bộ block agent -uv run {project-root}/_bmad/scripts/resolve_customization.py \ - --skill /duong-dan/tuyet-doi/toi/bmad-agent-pm \ - --project-root {project-root} \ - --key agent - -# Resolve một trường cụ thể -uv run {project-root}/_bmad/scripts/resolve_customization.py \ - --skill /duong-dan/tuyet-doi/toi/bmad-agent-pm \ - --project-root {project-root} \ - --key agent.icon - -# Dump toàn bộ -uv run {project-root}/_bmad/scripts/resolve_customization.py \ - --skill /duong-dan/tuyet-doi/toi/bmad-agent-pm \ - --project-root {project-root} -``` - -Đầu ra luôn là JSON. Nếu script này không khả dụng trên một nền tảng nào đó, `SKILL.md` sẽ hướng dẫn agent đọc trực tiếp ba file TOML và áp dụng cùng các quy tắc merge. - -## Tùy chỉnh workflow - -Workflow, tức các skill điều phối tiến trình nhiều bước như `bmad-product-brief`, dùng cùng cơ chế override như agent. Khác biệt là bề mặt tùy chỉnh của chúng nằm dưới `[workflow]` thay vì `[agent]`: - -```toml -# _bmad/custom/bmad-product-brief.toml - -[workflow] -# Giống agent: prepend/append chạy trước và sau activation mặc định của -# workflow. Override sẽ append vào mặc định. -activation_steps_prepend = [ - "Nạp {project-root}/docs/product/north-star-principles.md làm context.", -] - -activation_steps_append = [] - -# Cũng dùng semantics literal-hoặc-file: như phía agent. Những fact này được -# nạp làm context nền tảng trong suốt lần chạy workflow. -persistent_facts = [ - "Mọi brief đều phải có một mục explicit về regulatory risk.", - "file:{project-root}/docs/compliance/product-brief-checklist.md", -] - -# Scalar: chạy đúng một lần khi workflow hoàn tất output chính. Override thắng. -on_complete = "Tóm tắt brief trong ba gạch đầu dòng rồi hỏi người dùng có muốn gửi email qua skill gws-gmail-send không." -``` - -Cùng một quy ước trường có thể đi xuyên qua ranh giới agent/workflow: `activation_steps_prepend`, `activation_steps_append`, `persistent_facts` với tham chiếu `file:`, và các table kiểu menu `[[...]]` dùng `code` hoặc `id` làm khóa merge. Resolver áp dụng đúng bốn quy tắc cấu trúc đã nêu bất kể top-level key là gì. Tham chiếu từ `SKILL.md` cũng theo namespace tương ứng: `{workflow.activation_steps_prepend}`, `{workflow.persistent_facts}`, `{workflow.on_complete}`. Mọi trường bổ sung mà một workflow tự expose, ví dụ output path, toggle, review setting hay stage flag, cũng sẽ đi theo cùng cơ chế merge dựa trên shape. Muốn biết chính xác workflow đó cho chỉnh gì, hãy đọc `customize.toml` của nó. - -### Thứ tự activation - -Workflow có thể tùy chỉnh sẽ chạy activation theo thứ tự cố định để bạn biết hook của mình được kích hoạt khi nào: - -1. Resolve block `[workflow]` bằng merge base -> team -> user -2. Chạy `activation_steps_prepend` theo đúng thứ tự -3. Nạp `persistent_facts` làm ngữ cảnh nền tảng cho cả lần chạy -4. Nạp config (`_bmad/bmm/config.yaml`) và resolve các biến chuẩn như tên dự án, ngôn ngữ, đường dẫn, ngày tháng -5. Chào người dùng -6. Chạy `activation_steps_append` theo đúng thứ tự - -Sau bước 6, phần thân chính của workflow mới bắt đầu. Hãy dùng `activation_steps_prepend` khi bạn cần load context trước cả lúc cá nhân hóa lời chào; dùng `activation_steps_append` khi phần thiết lập khá nặng và bạn muốn người dùng thấy lời chào trước. - -### Phạm vi của đợt triển khai đầu tiên này - -Khả năng tùy chỉnh đang được mở rộng dần. Những trường đã mô tả ở trên, gồm `activation_steps_prepend`, `activation_steps_append`, `persistent_facts`, `on_complete`, là **bề mặt nền tảng** mà mọi workflow có thể tùy chỉnh đều sẽ hỗ trợ, và chúng sẽ ổn định qua các phiên bản. Ngày hôm nay, chỉ với những trường này bạn đã có thể kiểm soát những điểm lớn: thêm bước trước/sau, ghim context nền tảng, kích hoạt hành động tiếp theo sau khi workflow hoàn tất. - -Theo thời gian, từng workflow sẽ expose thêm **các điểm tùy chỉnh chuyên biệt hơn** gắn với chính công việc của workflow đó, ví dụ toggle ở từng bước, stage flag, đường dẫn template đầu ra hoặc review gate. Khi những trường đó xuất hiện, chúng sẽ được chồng thêm lên bề mặt nền tảng chứ không thay thế nó, nên những tùy chỉnh bạn viết hôm nay vẫn tiếp tục dùng được. - -Nếu bạn đang cần một "núm tinh chỉnh" chi tiết hơn nhưng workflow chưa expose, hãy tạm dùng `activation_steps_*` và `persistent_facts` để điều hướng hành vi, hoặc mở issue mô tả chính xác điểm tùy chỉnh bạn muốn. Chính những nhu cầu đó sẽ quyết định trường nào được bổ sung tiếp theo. - -## Cấu hình trung tâm - -`customize.toml` theo từng skill bao phủ **hành vi sâu** như hook, menu, `persistent_facts`, override persona cho một agent hay workflow đơn lẻ. Một bề mặt khác sẽ bao phủ **trạng thái cắt ngang** như các câu trả lời lúc cài đặt và roster agent mà những skill bên ngoài như `bmad-party-mode`, `bmad-retrospective` và `bmad-advanced-elicitation` sử dụng. Bề mặt đó nằm trong bốn file TOML ở root dự án: - -```text -_bmad/config.toml (do installer quản lý) team scope: câu trả lời lúc cài đặt + agent roster -_bmad/config.user.toml (do installer quản lý) user scope: user_name, language, skill level -_bmad/custom/config.toml (do con người viết) team overrides (commit vào git) -_bmad/custom/config.user.toml (do con người viết) personal overrides (gitignore) -``` - -### Merge bốn lớp - -```text -Ưu tiên 1 (thắng): _bmad/custom/config.user.toml -Ưu tiên 2: _bmad/custom/config.toml -Ưu tiên 3: _bmad/config.user.toml -Ưu tiên 4 (gốc): _bmad/config.toml -``` - -Các quy tắc cấu trúc hoàn toàn giống phần per-skill customize: scalar override, table deep-merge, mảng dùng `code` hoặc `id` sẽ merge theo khóa, các mảng khác thì append. - -### Cái gì nằm ở đâu - -Installer sẽ phân chia câu trả lời theo `scope:` khai báo trên từng prompt trong `module.yaml`: - -- Các section `[core]` và `[modules.]`: chứa câu trả lời khi cài. `scope = team` sẽ được ghi vào `_bmad/config.toml`; `scope = user` sẽ nằm trong `_bmad/config.user.toml` -- Section `[agents.]`: "bản chất" của agent gồm code, name, title, icon, description, team, được chưng cất từ khối `agents:` trong `module.yaml` của từng module. Phần này luôn ở scope team - -### Quy tắc chỉnh sửa - -- `_bmad/config.toml` và `_bmad/config.user.toml` sẽ **được tạo lại sau mỗi lần cài đặt** từ những câu trả lời mà installer thu thập. Hãy coi chúng là output chỉ đọc; mọi chỉnh sửa trực tiếp sẽ bị ghi đè ở lần cài tiếp theo. Nếu muốn thay đổi bền vững một giá trị cài đặt, hãy chạy lại installer hoặc chồng giá trị đó bằng `_bmad/custom/config.toml` -- `_bmad/custom/config.toml` và `_bmad/custom/config.user.toml` sẽ **không bao giờ** bị installer động vào. Đây mới là bề mặt đúng để thêm custom agent, override descriptor của agent, ép các thiết lập dùng chung cho team và ghim mọi giá trị bạn muốn giữ nguyên bất kể câu trả lời lúc cài là gì - -### Ví dụ: đổi thương hiệu cho một agent - -```toml -# _bmad/custom/config.toml (commit vào git, áp dụng cho mọi developer) - -[agents.bmad-agent-pm] -description = "PM trong domain healthcare, nhạy với compliance, luôn đặt câu hỏi theo hướng FDA ngay từ đầu." -icon = "🏥" -``` - -Resolver sẽ merge đè lên `[agents.bmad-agent-pm]` do installer sinh ra. `bmad-party-mode` và mọi roster consumer khác sẽ tự động thấy description mới này. - -### Ví dụ: thêm một agent hư cấu - -```toml -# _bmad/custom/config.user.toml (cá nhân, gitignore) - -[agents.kirk] -team = "startrek" -name = "Captain James T. Kirk" -title = "Starship Captain" -icon = "🖖" -description = "Một chỉ huy táo bạo, thích bẻ luật. Nói chuyện có các quãng ngắt đầy kịch tính. Suy nghĩ thành tiếng về gánh nặng của quyền chỉ huy." -``` - -Không cần tạo thư mục skill. Chỉ riêng "essence" này cũng đủ để party-mode spawn Kirk như một giọng nói trong cuộc bàn tròn. Bạn có thể lọc theo trường `team` để chỉ mời nhóm Enterprise. - -### Ví dụ: override thiết lập cài đặt của module - -```toml -# _bmad/custom/config.toml - -[modules.bmm] -planning_artifacts = "/shared/org-planning-artifacts" -``` - -Giá trị override này sẽ thắng mọi câu trả lời mà từng developer đã nhập khi cài trên máy của họ. Rất hữu ích khi bạn muốn ghim convention của cả team. - -### Khi nào dùng bề mặt nào - -| Nhu cầu | Bề mặt nên dùng | -|---|---| -| Thêm lời nhắc gọi MCP tool vào mọi dev workflow | Theo từng skill: `_bmad/custom/bmad-agent-dev.toml` trong `persistent_facts` | -| Thêm menu item cho một agent | Theo từng skill: `_bmad/custom/bmad-agent-{role}.toml` với `[[agent.menu]]` | -| Đổi template đầu ra của một workflow | Theo từng skill: `_bmad/custom/{workflow}.toml` bằng scalar override | -| Đổi descriptor công khai của một agent | **Cấu hình trung tâm**: `_bmad/custom/config.toml` ở `[agents.]` | -| Thêm custom agent hoặc agent hư cấu vào roster | **Cấu hình trung tâm**: `_bmad/custom/config*.toml` với entry mới `[agents.]` | -| Ghim thiết lập cài đặt dùng chung của team | **Cấu hình trung tâm**: `_bmad/custom/config.toml` trong `[modules.]` hoặc `[core]` | - -Trong cùng một dự án, bạn hoàn toàn có thể dùng đồng thời cả hai bề mặt này. - -## Ví dụ thực chiến - -Để xem các recipe thiên về doanh nghiệp như định hình một agent trên mọi workflow mà nó dispatch, ép workflow tuân thủ convention nội bộ, publish output lên Confluence và Jira, tùy chỉnh agent roster, hoặc thay template đầu ra bằng template riêng của tổ chức, hãy xem [Cách mở rộng BMad cho tổ chức của bạn](./expand-bmad-for-your-org.md). - -## Khắc phục sự cố - -**Tùy chỉnh không xuất hiện?** - -- Kiểm tra file của bạn có nằm đúng trong `_bmad/custom/` và dùng đúng tên skill không -- Kiểm tra cú pháp TOML: string phải có ngoặc kép, table header dùng `[section]`, array-of-tables dùng `[[section]]`, và mọi khóa scalar hay array của một table phải xuất hiện *trước* bất kỳ `[[subtables]]` nào của table đó trong file -- Với agent, phần tùy chỉnh phải nằm dưới `[agent]`, và các trường bên dưới header đó sẽ thuộc `agent` cho tới khi bạn mở table header khác -- Hãy nhớ rằng `agent.name` và `agent.title` là chỉ đọc, override vào đó sẽ không có tác dụng - -**Tùy chỉnh bị hỏng sau khi update?** - -- Bạn có copy nguyên file `customize.toml` vào file override không? **Đừng làm vậy.** File override chỉ nên chứa phần chênh lệch. Nếu copy nguyên file, bạn sẽ khóa cứng mặc định cũ và dần lệch khỏi các bản phát hành mới. - -**Muốn biết có thể tùy chỉnh gì?** - -- Chạy skill `bmad-customize`. Nó sẽ liệt kê mọi skill có thể tùy chỉnh trong dự án, cho biết skill nào đã có override, rồi dẫn bạn qua quá trình thêm hoặc sửa một override -- Hoặc đọc trực tiếp `customize.toml` của skill. Mọi trường ở đó đều có thể tùy chỉnh, trừ `name` và `title` - -**Muốn reset?** - -- Xóa file override của bạn trong `_bmad/custom/`, skill sẽ tự động rơi về cấu hình mặc định tích hợp sẵn diff --git a/docs/vi-vn/how-to/established-projects.md b/docs/vi-vn/how-to/established-projects.md deleted file mode 100644 index 356808e7fa..0000000000 --- a/docs/vi-vn/how-to/established-projects.md +++ /dev/null @@ -1,117 +0,0 @@ ---- -title: "Dự án đã tồn tại" -description: Cách sử dụng BMad Method trên các codebase hiện có -sidebar: - order: 6 ---- - -Sử dụng BMad Method hiệu quả khi làm việc với các dự án hiện có và codebase legacy. - -Tài liệu này mô tả workflow cốt lõi để on-board vào các dự án đã tồn tại bằng BMad Method. - -:::note[Điều kiện tiên quyết] -- Đã cài BMad Method (`npx bmad-method install`) -- Một codebase hiện có mà bạn muốn làm việc cùng -- Quyền truy cập vào một IDE tích hợp AI (Claude Code hoặc Cursor) -::: - -## Bước 1: Dọn dẹp các tài liệu lập kế hoạch đã hoàn tất - -Nếu bạn đã hoàn thành toàn bộ epic và story trong PRD theo quy trình BMad, hãy dọn dẹp những tệp đó. Bạn có thể lưu trữ, xóa đi, hoặc dựa vào lịch sử phiên bản nếu cần. Không nên giữ các tệp này trong: - -- `docs/` -- `_bmad-output/planning-artifacts/` -- `_bmad-output/implementation-artifacts/` - -## Bước 2: Tạo Project Context - -:::tip[Khuyến dùng cho dự án hiện có] -Hãy tạo `project-context.md` để ghi lại các pattern và quy ước trong codebase hiện tại. Điều này giúp các agent AI tuân theo các thực hành sẵn có khi thực hiện thay đổi. -::: - -Chạy workflow tạo project context: - -```bash -bmad-generate-project-context -``` - -Workflow này sẽ quét codebase để nhận diện: -- Stack công nghệ và các phiên bản -- Các pattern tổ chức code -- Quy ước đặt tên -- Cách tiếp cận kiểm thử -- Các pattern đặc thù framework - -Bạn có thể xem lại và chỉnh sửa tệp được tạo, hoặc tự tạo tệp tại `_bmad-output/project-context.md` nếu muốn. - -[Tìm hiểu thêm về project context](../explanation/project-context.md) - -## Bước 3: Duy trì tài liệu dự án chất lượng - -Thư mục `docs/` của bạn nên chứa tài liệu ngắn gọn, có tổ chức tốt, và phản ánh chính xác dự án: - -- Mục tiêu và lý do kinh doanh -- Quy tắc nghiệp vụ -- Kiến trúc -- Bất kỳ thông tin dự án nào khác có liên quan - -Với các dự án phức tạp, hãy cân nhắc dùng workflow `bmad-document-project`. Nó có các biến thể lúc chạy có thể quét toàn bộ dự án và tài liệu hóa trạng thái thực tế hiện tại của hệ thống. - -## Bước 4: Nhờ trợ giúp - -### BMad-Help: Điểm bắt đầu của bạn - -**Hãy chạy `bmad-help` bất cứ lúc nào bạn không chắc cần làm gì tiếp theo.** Công cụ hướng dẫn thông minh này: - -- Kiểm tra dự án để xem những gì đã được hoàn thành -- Đưa ra tùy chọn dựa trên các module bạn đã cài -- Hiểu các câu hỏi bằng ngôn ngữ tự nhiên - -```text -bmad-help Tôi có một ứng dụng Rails đã tồn tại, tôi nên bắt đầu từ đâu? -bmad-help Thay đổi này cần lập kế hoạch sâu đến đâu trước implementation? -bmad-help Cho tôi xem những workflow đang có -``` - -BMad-Help cũng **tự động chạy ở cuối mỗi workflow**, đưa ra hướng dẫn rõ ràng về việc cần làm tiếp theo. - -### Chọn độ sâu lập kế hoạch - -Mọi implementation đều dùng `bmad-build`; phạm vi quyết định ngữ cảnh cần chuẩn bị trước: - -| Phạm vi | Cách tiếp cận được khuyến nghị | -| --- | --- | -| **Cập nhật hoặc bổ sung rõ ràng** | Đi thẳng vào `bmad-build` với yêu cầu, issue hoặc spec hiện có. | -| **Thay đổi hoặc bổ sung lớn** | Chuẩn bị PRD, UX, kiến trúc, epic, story và sprint context hữu ích, rồi đưa phần việc đã chọn vào `bmad-build`. | - -### Khi tạo PRD - -Khi tạo brief hoặc đi thẳng vào PRD, đảm bảo agent: - -- Tìm và phân tích tài liệu dự án hiện có -- Đọc đúng bối cảnh về hệ thống hiện tại của bạn - -Bạn có thể chủ động hướng dẫn agent, nhưng mục tiêu là đảm bảo tính năng mới tích hợp tốt với hệ thống đã có. - -### Cân nhắc về UX - -Công việc UX là tùy chọn. Quyết định này không phụ thuộc vào việc dự án có UX hay không, mà phụ thuộc vào: - -- Bạn có định thay đổi UX hay không -- Bạn có cần thiết kế hay pattern UX mới đáng kể hay không - -Nếu thay đổi của bạn chỉ là những cập nhật nhỏ trên các màn hình hiện có mà bạn đã hài lòng, thì không cần một quy trình UX đầy đủ. - -### Cân nhắc về kiến trúc - -Khi làm kiến trúc, đảm bảo kiến trúc sư: - -- Sử dụng đúng các tệp tài liệu cần thiết -- Quét codebase hiện có - -Cần đặc biệt chú ý để tránh tái phát minh bánh xe hoặc đưa ra quyết định không phù hợp với kiến trúc hiện tại. - -## Thông tin thêm - -- **[Quick Fixes](./quick-fixes.md)** - Sửa lỗi và thay đổi ad-hoc -- **[Câu hỏi thường gặp cho dự án đã tồn tại](../explanation/established-projects-faq.md)** - Những câu hỏi phổ biến khi làm việc với dự án đã tồn tại diff --git a/docs/vi-vn/how-to/expand-bmad-for-your-org.md b/docs/vi-vn/how-to/expand-bmad-for-your-org.md deleted file mode 100644 index 1eec5c297a..0000000000 --- a/docs/vi-vn/how-to/expand-bmad-for-your-org.md +++ /dev/null @@ -1,266 +0,0 @@ ---- -title: 'Cách mở rộng BMad cho tổ chức của bạn' -description: Năm mẫu tùy chỉnh giúp thay đổi BMad mà không cần fork, gồm quy tắc ở cấp agent, quy ước workflow, xuất bản ra hệ thống ngoài, thay template và điều chỉnh danh sách agent -sidebar: - order: 9 ---- - -Bề mặt tùy chỉnh của BMad cho phép một tổ chức định hình lại hành vi mà không phải sửa file đã cài hay fork skill. Hướng dẫn này trình bày năm công thức mẫu (recipe) bao phủ phần lớn nhu cầu ở môi trường doanh nghiệp. - -:::note[Điều kiện tiên quyết] - -- BMad đã được cài trong dự án của bạn (xem [Cách cài đặt BMad](./install-bmad.md)) -- Đã quen với mô hình tùy chỉnh (xem [Cách tùy chỉnh BMad](./customize-bmad.md)) -- Python 3.11+ có trên PATH để chạy resolver, chỉ dùng stdlib, không cần `pip install` -::: - -:::tip[Cách áp dụng các công thức mẫu này] -Những **công thức mẫu theo từng skill** bên dưới, tức Recipe 1 đến Recipe 4, có thể được áp dụng bằng cách chạy skill `bmad-customize` rồi mô tả ý định. Skill này sẽ tự chọn đúng bề mặt, viết file override và xác minh kết quả merge. Riêng Recipe 5, tức override cấu hình trung tâm để chỉnh danh sách agent (agent roster), hiện chưa nằm trong phạm vi v1 của skill nên vẫn cần viết tay. Các recipe trong trang này là nguồn sự thật cho phần *nên override cái gì*; `bmad-customize` phụ trách phần *thực hiện ra sao* ở lớp agent/workflow. -::: - -## Mô hình ba lớp để suy nghĩ - -Trước khi chọn recipe, bạn cần biết override của mình sẽ rơi vào đâu: - -| Lớp | Nơi override sống | Phạm vi | -|---|---|---| -| **Agent** như Amelia, Mary, John | section `[agent]` trong `_bmad/custom/bmad-agent-{role}.toml` | Đi cùng persona vào **mọi workflow mà agent đó dispatch** | -| **Workflow** như `product-brief`, `create-prd` | section `[workflow]` trong `_bmad/custom/{workflow-name}.toml` | Chỉ áp dụng cho lần chạy của workflow đó | -| **Cấu hình trung tâm** | `[agents.*]`, `[core]`, `[modules.*]` trong `_bmad/custom/config.toml` | Agent roster và các thiết lập lúc cài đặt cần ghim cho cả tổ chức | - -Nguyên tắc ngón tay cái: - -- Nếu quy tắc nên áp dụng ở mọi nơi một engineer làm dev work, hãy tùy chỉnh **dev agent** -- Nếu nó chỉ áp dụng khi ai đó viết product brief, hãy tùy chỉnh **workflow product-brief** -- Nếu nó thay đổi *ai đang ngồi trong phòng* như đổi thương hiệu agent, thêm custom voice hoặc ép chung một artifact path, hãy sửa **cấu hình trung tâm** - -## Recipe 1: định hình một agent trên mọi workflow mà nó điều phối (dispatch) - -**Trường hợp dùng (use case):** Chuẩn hóa việc dùng công cụ và tích hợp với hệ thống bên ngoài để mọi workflow được dispatch qua agent đó tự động thừa hưởng cùng hành vi. Đây là mẫu áp dụng (pattern) có sức ảnh hưởng lớn nhất. - -**Ví dụ:** Amelia, tức dev agent, luôn dùng Context7 cho tài liệu thư viện và fallback sang Linear nếu không tìm thấy story trong danh sách epic. - -```toml -# _bmad/custom/bmad-agent-dev.toml - -[agent] - -# Áp dụng ở mọi lần kích hoạt. Theo Amelia đi vào build, -# code-review, qa-generate và mọi skill cô ấy dispatch. -persistent_facts = [ - "Với mọi truy vấn tài liệu thư viện như React, TypeScript, Zod, Prisma..., hãy gọi Context7 MCP tool (`mcp__context7__resolve_library_id` rồi `mcp__context7__get_library_docs`) trước khi dựa vào kiến thức trong dữ liệu huấn luyện (training data). Tài liệu cập nhật phải thắng API đã ghi nhớ.", - "Khi không tìm thấy tham chiếu story trong {planning_artifacts}/epics-and-stories.md, hãy tìm trong Linear bằng `mcp__linear__search_issues` theo ID hoặc tiêu đề story trước khi yêu cầu người dùng làm rõ. Nếu Linear trả về kết quả khớp, coi đó là nguồn story có thẩm quyền.", -] -``` - -**Vì sao cách này hiệu quả:** Chỉ với hai câu, bạn đã thay đổi mọi dev workflow trong tổ chức mà không lặp config từng nơi và không sửa source. Mọi engineer mới kéo repo về đều tự động thừa hưởng convention đó. - -**File của team và file cá nhân** - -- `bmad-agent-dev.toml`: commit vào git, áp dụng cho cả team -- `bmad-agent-dev.user.toml`: bị gitignore, dùng cho sở thích cá nhân chồng thêm lên trên - -## Recipe 2: ép convention của tổ chức bên trong một workflow cụ thể - -**Trường hợp dùng (use case):** Định hình *nội dung đầu ra* của một workflow để nó đáp ứng yêu cầu compliance, audit hoặc hệ thống downstream. - -**Ví dụ:** mọi product brief đều phải có các trường compliance, và agent biết convention xuất bản của tổ chức. - -```toml -# _bmad/custom/bmad-product-brief.toml - -[workflow] - -persistent_facts = [ - "Mọi brief phải có trường 'Owner', 'Target Release' và 'Security Review Status'.", - "Các brief không mang tính thương mại như công cụ nội bộ hoặc dự án nghiên cứu vẫn phải có phần user value, nhưng có thể bỏ phân biệt cạnh tranh thị trường.", - "file:{project-root}/docs/enterprise/brief-publishing-conventions.md", -] -``` - -**Điều gì xảy ra:** Những fact này được nạp trong quá trình activation của workflow. Khi agent soạn brief, nó đã biết các trường bắt buộc và tài liệu convention nội bộ. Các skill được ship sẵn không mang fact cố định nào, nên đây là những fact duy nhất được nạp. Nhưng vì khóa này append chứ không thay thế, một fact khai báo ở cấp team và một fact ở cấp user đều có hiệu lực. - -## Recipe 3: xuất bản kết quả hoàn tất sang hệ thống ngoài - -**Trường hợp dùng (use case):** Sau khi workflow tạo ra output chính, tự động đẩy nó sang hệ thống nguồn sự thật của doanh nghiệp như Confluence, Notion, SharePoint, rồi mở tiếp công việc follow-up trong Jira, Linear hoặc Asana. - -**Ví dụ:** brief được tự động publish lên Confluence và tùy chọn mở Jira epic. - -```toml -# _bmad/custom/bmad-product-brief.toml - -[workflow] - -# Hook ở giai đoạn cuối. Scalar override sẽ thay hẳn mặc định rỗng. -on_complete = """ -Publish và đề nghị bước tiếp theo: - -1. Đọc đường dẫn file brief đã hoàn tất từ bước trước. -2. Gọi `mcp__atlassian__confluence_create_page` với: - - space: "PRODUCT" - - parent: "Product Briefs" - - title: tiêu đề của brief - - body: nội dung markdown của brief - Lưu lại URL trang được trả về. -3. Thông báo cho người dùng: "Brief đã được publish lên Confluence: ". -4. Hỏi: "Bạn có muốn tôi mở Jira epic cho brief này ngay bây giờ không?" -5. Nếu có, gọi `mcp__atlassian__jira_create_issue` với: - - type: "Epic" - - project: "PROD" - - summary: tiêu đề của brief - - description: tóm tắt ngắn cùng liên kết ngược về trang Confluence. - Sau đó báo lại epic key và URL. -6. Nếu không, thoát sạch. - -Nếu một trong các MCP tool bị lỗi, hãy báo lỗi, in ra đường dẫn brief -và yêu cầu người dùng publish thủ công. -""" -``` - -**Vì sao dùng `on_complete` thay vì `activation_steps_append`:** `on_complete` chỉ chạy đúng một lần ở cuối, sau khi output chính của workflow đã được ghi ra. Đó là thời điểm đúng để publish artifact. `activation_steps_append` thì chạy mỗi lần kích hoạt, trước khi workflow làm công việc chính của nó. - -**Điểm đánh đổi (trade-offs)** - -- Publish lên Confluence là hành động không phá hủy, nên có thể luôn chạy khi hoàn tất -- Tạo Jira epic là hành động hiển thị cho cả team và kích hoạt các tín hiệu sprint planning, nên nên chặn bởi một bước xác nhận từ người dùng -- Nếu MCP tool lỗi, workflow phải có phương án dự phòng (fallback) rõ ràng thay vì âm thầm làm mất output - -## Recipe 4: thay output template bằng template của riêng bạn - -**Trường hợp dùng (use case):** Cấu trúc đầu ra mặc định không khớp định dạng mà tổ chức mong muốn, hoặc trong cùng một repo có nhiều tổ chức cần template riêng. - -**Ví dụ:** trỏ workflow product-brief sang template do doanh nghiệp sở hữu. - -```toml -# _bmad/custom/bmad-product-brief.toml - -[workflow] -brief_template = "{project-root}/docs/enterprise/brief-template.md" -``` - -**Cách nó hoạt động:** `customize.toml` của workflow đi kèm `brief_template = "resources/brief-template.md"` dưới dạng đường dẫn tương đối tới skill root. Override của bạn lại trỏ tới một file trong `{project-root}`, nên agent sẽ đọc template của bạn trong bước tương ứng thay vì dùng template mặc định đi kèm. - -**Mẹo viết template** - -- Giữ template trong `{project-root}/docs/` hoặc `{project-root}/_bmad/custom/templates/` để nó được version cùng với file override -- Nên dùng cùng convention cấu trúc với template mặc định, ví dụ heading và frontmatter, để agent có điểm tựa ổn định -- Với repo đa tổ chức, hãy dùng `.user.toml` để từng nhóm nhỏ có thể trỏ sang template riêng mà không cần sửa file dùng chung của team - -## Recipe 5: tùy chỉnh danh sách agent (agent roster) - -**Trường hợp dùng (use case):** Thay đổi *ai đang ngồi trong phòng* cho những skill dựa trên roster như `bmad-party-mode`, `bmad-retrospective` và `bmad-advanced-elicitation`, mà không cần sửa source hay fork. Dưới đây là ba biến thể thường gặp. - -### 5a. Rebrand một agent của BMad trên toàn tổ chức - -Mỗi agent thật đều có một descriptor được installer tổng hợp từ `module.yaml`. Bạn có thể override descriptor này để đổi giọng điệu và framing ở mọi roster consumer: - -```toml -# _bmad/custom/config.toml (commit vào git, áp dụng cho mọi developer) - -[agents.bmad-agent-analyst] -description = "Mary, nhà phân tích nghiệp vụ giàu nhận thức pháp lý, pha trộn Porter với Minto nhưng sống cùng các audit trail của FDA. Cô ấy nói như một điều tra viên pháp chứng đang trình bày hồ sơ vụ án." -``` - -Party mode sẽ spawn Mary với description mới này. Bản thân activation của analyst vẫn chạy bình thường vì hành vi của Mary sống trong `customize.toml` theo từng skill. Override này chỉ thay đổi cách **các skill bên ngoài nhìn thấy và giới thiệu cô ấy**, chứ không thay đổi cách cô ấy hoạt động bên trong. - -### 5b. Thêm một agent hư cấu hoặc agent tự định nghĩa - -Chỉ cần một descriptor đầy đủ là đủ cho các tính năng dựa trên roster, không cần thư mục skill. Điều này rất phù hợp nếu bạn muốn tăng màu sắc tính cách cho party mode hay các buổi brainstorming: - -```toml -# _bmad/custom/config.user.toml (cá nhân, gitignore) - -[agents.spock] -team = "startrek" -name = "Commander Spock" -title = "Science Officer" -icon = "🖖" -description = "Logic là trên hết, cảm xúc bị nén lại. Mở đầu nhận xét bằng 'Fascinating.' Không bao giờ làm tròn lên. Là đối trọng với mọi lập luận chỉ dựa vào linh cảm." - -[agents.mccoy] -team = "startrek" -name = "Dr. Leonard McCoy" -title = "Chief Medical Officer" -icon = "⚕️" -description = "Sự ấm áp của một bác sĩ miền quê, đi kèm với tính nóng nảy. 'Dammit Jim, I'm a doctor not a ___.' Là đối trọng đạo đức với Spock." -``` - -Khi bạn yêu cầu party-mode "mời nhóm Star Trek" hoặc "mời phi hành đoàn Enterprise", nó sẽ lọc theo `team = "startrek"` và spawn Spock cùng McCoy dựa trên các descriptor đó. Các agent thật của BMad như Mary hay Amelia vẫn có thể ngồi cùng bàn nếu bạn muốn. - -### 5c. Ghim thiết lập cài đặt dùng chung cho cả team - -Installer sẽ hỏi từng developer các giá trị như đường dẫn `planning_artifacts`. Khi tổ chức muốn có một câu trả lời thống nhất, hãy ghim nó trong cấu hình trung tâm. Khi đó, mọi câu trả lời cục bộ của từng người sẽ bị override lúc resolve: - -```toml -# _bmad/custom/config.toml - -[modules.bmm] -planning_artifacts = "{project-root}/shared/planning" -implementation_artifacts = "{project-root}/shared/implementation" - -[core] -document_output_language = "English" -``` - -Những thiết lập cá nhân như `user_name`, `communication_language` hoặc `user_skill_level` nên vẫn nằm trong `_bmad/config.user.toml` riêng của từng developer. File chung của team không nên đụng vào các giá trị đó. - -**Vì sao việc này nằm ở cấu hình trung tâm thay vì per-agent customize.toml:** File per-agent chỉ định hình cách *một* agent hành xử khi nó được kích hoạt. Cấu hình trung tâm lại định hình những gì các roster consumer *nhìn thấy khi quan sát cánh đồng chung*: agent nào tồn tại, tên gì, thuộc team nào và các thiết lập cài đặt dùng chung mà toàn repo đã thống nhất. Hai bề mặt khác nhau, hai công việc khác nhau. - -## Củng cố các quy tắc toàn cục trong file hướng dẫn phiên của IDE - -Tùy chỉnh của BMad chỉ được nạp khi một skill được kích hoạt. Trong khi đó, nhiều công cụ IDE còn nạp một file hướng dẫn toàn cục ở **đầu mọi phiên**, trước cả khi skill nào chạy, như `CLAUDE.md`, `AGENTS.md`, `.cursor/rules/` hay `.github/copilot-instructions.md`. Với những quy tắc phải đúng cả khi bạn đang chat thường, hãy lặp lại phiên bản rút gọn của chúng trong file đó nữa. - -**Khi nào nên "đánh đôi"** - -- Quy tắc đó đủ quan trọng đến mức một cuộc chat thường, chưa kích hoạt BMad skill nào, cũng vẫn phải tuân theo -- Bạn muốn áp dụng kiểu "gia cố hai lớp" (belt-and-suspenders) vì hành vi mặc định từ dữ liệu huấn luyện (training data) có thể kéo model đi chệch -- Quy tắc đủ ngắn để lặp lại mà không làm file hướng dẫn đầu phiên trở nên phình to - -**Ví dụ:** một dòng trong `CLAUDE.md` của repo để củng cố quy tắc ở Recipe 1. - -```markdown - -``` - -Chỉ một câu, nhưng được nạp ở mọi phiên. Nó kết hợp với cấu hình `bmad-agent-dev.toml` để quy tắc có hiệu lực cả trong workflow của Amelia lẫn trong các cuộc trò chuyện ad-hoc với assistant. Mỗi lớp giữ đúng phạm vi của mình: - -| Lớp | Phạm vi | Dùng cho | -|---|---|---| -| File hướng dẫn phiên của IDE như `CLAUDE.md` hoặc `AGENTS.md` | Mọi phiên, trước khi bất kỳ skill nào chạy | Quy tắc ngắn, phổ quát, phải sống cả ngoài BMad | -| Tùy chỉnh agent của BMad | Mọi workflow mà agent đó dispatch | Hành vi riêng theo persona/agent | -| Tùy chỉnh workflow của BMad | Một lần chạy workflow | Dạng đầu ra, hook publish, template và logic riêng của workflow | -| Cấu hình trung tâm của BMad | Agent roster và thiết lập cài đặt dùng chung | Ai đang ngồi trong phòng và đường dẫn nào cả team dùng chung | - -Hãy giữ file hướng dẫn của IDE **ngắn gọn**. Một tá dòng được chọn kỹ sẽ hiệu quả hơn một danh sách dài lê thê. Model phải đọc file đó ở mọi lượt, và càng nhiều nhiễu thì càng ít tín hiệu. - -## Kết hợp các recipe - -Cả năm recipe này có thể kết hợp song song. Một cấu hình doanh nghiệp thực tế cho `bmad-product-brief` hoàn toàn có thể đặt `persistent_facts` theo Recipe 2, `on_complete` theo Recipe 3 và `brief_template` theo Recipe 4 trong cùng một file. Quy tắc ở cấp agent theo Recipe 1 sẽ nằm trong file của agent tương ứng, còn cấu hình trung tâm theo Recipe 5 thì ghim roster và thiết lập chung. Tất cả cùng hoạt động đồng thời. - -```toml -# _bmad/custom/bmad-product-brief.toml (cấp workflow) - -[workflow] -persistent_facts = ["..."] -brief_template = "{project-root}/docs/enterprise/brief-template.md" -on_complete = """ ... """ -``` - -```toml -# _bmad/custom/bmad-agent-analyst.toml (cấp agent, Mary sẽ dispatch product-brief) - -[agent] -persistent_facts = ["Luôn thêm mục 'Regulatory Review' khi domain liên quan tới healthcare, finance hoặc dữ liệu trẻ em."] -``` - -Kết quả là Mary nạp quy tắc review pháp lý ngay ở lúc kích hoạt persona. Khi người dùng chọn menu item product-brief, workflow sẽ nạp các convention riêng của nó chồng lên, ghi ra template của doanh nghiệp và publish lên Confluence khi hoàn tất. Mỗi lớp đều đóng góp một phần và không lớp nào đòi hỏi sửa source của BMad. - -## Khắc phục sự cố - -**Override không có tác dụng?** Hãy kiểm tra file có nằm trong `_bmad/custom/` và dùng đúng tên thư mục skill không, ví dụ `bmad-agent-dev.toml`, chứ không phải `bmad-dev.toml`. Nếu cần, xem lại [Cách tùy chỉnh BMad](./customize-bmad.md). - -**Không chắc tên MCP tool?** Hãy dùng đúng tên mà MCP server hiện tại expose trong phiên của bạn. Nếu chưa chắc, hãy yêu cầu Claude Code liệt kê các MCP tool đang có. Những tên hardcode trong `persistent_facts` hay `on_complete` sẽ không chạy nếu MCP server chưa được kết nối. - -**Mẫu áp dụng (pattern) trong ví dụ không khớp setup của tôi?** Các recipe trên chỉ là ví dụ mẫu. Cơ chế bên dưới, gồm merge ba lớp, quy tắc cấu trúc và mô hình agent-span-workflow, vẫn hỗ trợ nhiều pattern khác. Hãy kết hợp chúng theo nhu cầu thực tế của bạn. diff --git a/docs/vi-vn/how-to/get-answers-about-bmad.md b/docs/vi-vn/how-to/get-answers-about-bmad.md deleted file mode 100644 index c807ce2d8c..0000000000 --- a/docs/vi-vn/how-to/get-answers-about-bmad.md +++ /dev/null @@ -1,81 +0,0 @@ ---- -title: "Cách tìm câu trả lời về BMad" -description: Sử dụng LLM để tự nhanh chóng trả lời các câu hỏi về BMad -sidebar: - order: 4 ---- - -Hãy dùng trợ giúp tích hợp sẵn của BMad, tài liệu nguồn, hoặc cộng đồng để tìm câu trả lời, theo thứ tự từ nhanh nhất đến đầy đủ nhất. - -## 1. Hỏi BMad-Help - -Cách nhanh nhất để có câu trả lời. Skill `bmad-help` có sẵn ngay trong phiên AI của bạn và xử lý được hơn 80% câu hỏi. Nó sẽ kiểm tra dự án, nhìn xem bạn đã hoàn thành đến đâu và cho bạn biết nên làm gì tiếp theo. - -```text -bmad-help Tôi có ý tưởng SaaS và đã biết tất cả tính năng. Tôi nên bắt đầu từ đâu? -bmad-help Tôi có những lựa chọn nào cho thiết kế UX? -bmad-help Tôi đang bị mắc ở workflow PRD -``` - -:::tip -Bạn cũng có thể dùng `/bmad-help` hoặc `$bmad-help` tùy nền tảng, nhưng chỉ `bmad-help` là cách nên hoạt động mọi nơi. -::: - -## 2. Đi sâu hơn với mã nguồn - -BMad-Help dựa trên cấu hình bạn đã cài đặt. Nếu bạn cần tìm hiểu nội bộ, lịch sử, hay kiến trúc của BMad, hoặc đang nghiên cứu BMad trước khi cài, hãy để AI đọc trực tiếp mã nguồn. - -Hãy clone hoặc mở [repo BMAD-METHOD](https://github.com/bmad-code-org/BMAD-METHOD) rồi hỏi AI của bạn về nó. Bất kỳ công cụ nào có hỗ trợ agent như Claude Code, Cursor, Windsurf... đều có thể đọc mã nguồn và trả lời trực tiếp. - -:::note[Ví dụ] -**Q:** "Hãy chỉ tôi cách nhanh nhất để xây dựng một thứ gì đó bằng BMad" - -**A:** Chạy `bmad-build`. Đưa vào ý định trực tiếp, issue, spec hoặc story đã lập kế hoạch; workflow dùng ngữ cảnh sẵn có và chọn độ sâu làm rõ, lập kế hoạch, triển khai và review cần thiết. -::: - -**Mẹo để có câu trả lời tốt hơn:** - -- **Hãy hỏi thật cụ thể** - "Bước 3 trong workflow PRD làm gì?" sẽ tốt hơn "PRD hoạt động ra sao?" -- **Kiểm tra lại những câu trả lời nghe lạ** - LLM đôi khi vẫn sai. Hãy kiểm tra file nguồn hoặc hỏi trên Discord. - -### Không dùng agent? Dùng trang docs - -Nếu AI của bạn không đọc được file cục bộ như ChatGPT hoặc Claude.ai, hãy mở [trang tài liệu BMad](https://docs.bmad-method.org/). - -## 3. Hỏi người thật - -Nếu cả BMad-Help lẫn mã nguồn vẫn chưa trả lời được câu hỏi của bạn, lúc này bạn đã có một câu hỏi rõ hơn nhiều để đem đi hỏi cộng đồng. - -| Kênh | Dùng cho | -| --- | --- | -| `help-requests` forum | Câu hỏi | -| `#suggestions-feedback` | Ý tưởng và đề xuất tính năng | - -**Discord:** [discord.gg/gk8jAdXWmj](https://discord.gg/gk8jAdXWmj) - -**GitHub Issues:** [github.com/bmad-code-org/BMAD-METHOD/issues](https://github.com/bmad-code-org/BMAD-METHOD/issues) - -*Chính bạn,* - *đang mắc kẹt* - *trong hàng đợi -* - *đợi* - *ai?* - -*Mã nguồn* - *nằm ngay đó,* - *rõ như ban ngày!* - -*Hãy trỏ* - *cho máy của bạn.* - *Thả nó đi.* - -*Nó đọc.* - *Nó nói.* - *Cứ hỏi -* - -*Sao phải chờ* - *đến ngày mai* - *khi bạn đã có* - *ngày hôm nay?* - -*- Claude* diff --git a/docs/vi-vn/how-to/install-bmad.md b/docs/vi-vn/how-to/install-bmad.md deleted file mode 100644 index b842a3675b..0000000000 --- a/docs/vi-vn/how-to/install-bmad.md +++ /dev/null @@ -1,114 +0,0 @@ ---- -title: "Cách cài đặt BMad" -description: Hướng dẫn từng bước để cài đặt BMad vào dự án của bạn -sidebar: - order: 1 ---- - -Sử dụng lệnh `npx bmad-method install` để thiết lập BMad trong dự án của bạn với các module và công cụ AI theo lựa chọn. - -## Khi nào nên dùng - -- Bắt đầu một dự án mới với BMad -- Thêm BMad vào một codebase hiện có -- Cập nhật bản cài đặt BMad hiện tại - -:::note[Điều kiện tiên quyết] -- **Node.js** 20.12+ (bắt buộc cho trình cài đặt) -- **Git** (khuyến nghị) -- **Công cụ AI** (Claude Code, Cursor, hoặc tương tự) -::: - -## Các bước thực hiện - -### 1. Chạy trình cài đặt - -```bash -npx bmad-method install -``` - -:::tip[Muốn dùng bản prerelease mới nhất?] -Sử dụng dist-tag `next`: -```bash -npx bmad-method@next install -``` - -Cách này giúp bạn nhận các thay đổi mới sớm hơn, đổi lại khả năng biến động cao hơn bản cài đặt mặc định. -::: - -:::tip[Bản rất mới] -Để cài đặt trực tiếp từ nhánh `main` mới nhất (có thể không ổn định): -```bash -npx github:bmad-code-org/BMAD-METHOD install -``` -::: - -### 2. Chọn vị trí cài đặt - -Trình cài đặt sẽ hỏi bạn muốn đặt các tệp BMad ở đâu: - -- Thư mục hiện tại (khuyến nghị cho dự án mới nếu bạn tự tạo thư mục và chạy lệnh từ bên trong nó) -- Đường dẫn tùy chọn - -### 3. Chọn công cụ AI - -Chọn các công cụ AI bạn đang dùng: - -- Claude Code -- Cursor -- Các công cụ khác - -Mỗi công cụ có cách tích hợp skill riêng. Trình cài đặt sẽ tạo các tệp prompt nhỏ để kích hoạt workflow và agent, và đặt chúng vào đúng vị trí mà công cụ của bạn mong đợi. - -:::note[Kích hoạt skill] -Một số nền tảng yêu cầu bật skill trong cài đặt trước khi chúng xuất hiện. Nếu bạn đã cài BMad mà chưa thấy skill, hãy kiểm tra cài đặt của nền tảng hoặc hỏi trợ lý AI cách bật skill. -::: - -### 4. Chọn module - -Trình cài đặt sẽ hiện các module có sẵn. Chọn những module bạn cần - phần lớn người dùng chỉ cần **BMad Method** (module phát triển phần mềm). - -### 5. Làm theo các prompt - -Trình cài đặt sẽ hướng dẫn các bước còn lại - cài đặt, tích hợp công cụ, và các tùy chọn khác. - -## Bạn nhận được gì - -```text -du-an-cua-ban/ -├── _bmad/ -│ ├── bmm/ # Các module bạn đã chọn -│ │ └── config.yaml # Cài đặt module (nếu bạn cần thay đổi sau này) -│ ├── core/ # Module core bắt buộc -│ └── ... -├── _bmad-output/ # Các artifact được tạo ra -├── .claude/ # Claude Code skills (nếu dùng Claude Code) -│ └── skills/ -│ ├── bmad-help/ -│ ├── bmad-persona/ -│ └── ... -└── .cursor/ # Cursor skills (nếu dùng Cursor) - └── skills/ - └── ... -``` - -## Xác minh cài đặt - -Chạy `bmad-help` để xác minh mọi thứ hoạt động và xem bạn nên làm gì tiếp theo. - -**BMad-Help là công cụ hướng dẫn thông minh** sẽ: -- Xác nhận bản cài đặt hoạt động đúng -- Hiển thị những gì có sẵn dựa trên module đã cài -- Đề xuất bước đầu tiên của bạn - -Bạn cũng có thể hỏi nó: -```text -bmad-help Tôi vừa cài xong, giờ nên làm gì đầu tiên? -bmad-help Tôi có những lựa chọn nào cho một dự án SaaS? -``` - -## Khắc phục sự cố - -**Trình cài đặt báo lỗi** - Sao chép toàn bộ output vào trợ lý AI của bạn và để nó phân tích. - -**Cài đặt xong nhưng sau đó có thứ không hoạt động** - AI của bạn cần bối cảnh BMad để hỗ trợ. Xem [Cách tìm câu trả lời về BMad](./get-answers-about-bmad.md) để biết cách cho AI truy cập đúng nguồn thông tin. diff --git a/docs/vi-vn/how-to/install-custom-modules.md b/docs/vi-vn/how-to/install-custom-modules.md deleted file mode 100644 index 8996591597..0000000000 --- a/docs/vi-vn/how-to/install-custom-modules.md +++ /dev/null @@ -1,181 +0,0 @@ ---- -title: 'Cài đặt module tùy chỉnh và module cộng đồng' -description: Cài các module bên thứ ba từ kho cộng đồng (community registry), kho Git hoặc đường dẫn cục bộ -sidebar: - order: 2 ---- - -Sử dụng trình cài đặt BMad để thêm module từ kho cộng đồng (community registry), kho Git của bên thứ ba hoặc đường dẫn file cục bộ. - -## Khi nào nên dùng - -- Cài một module do cộng đồng đóng góp từ BMad registry -- Cài module từ kho Git của bên thứ ba như GitHub, GitLab, Bitbucket hoặc máy chủ tự host -- Kiểm thử một module bạn đang phát triển cục bộ với BMad Builder -- Cài module từ máy chủ Git riêng tư hoặc tự host - -:::note[Điều kiện tiên quyết] -Yêu cầu [Node.js](https://nodejs.org) v20.12+ và `npx` đi kèm npm. Bạn có thể chọn module tùy chỉnh và module cộng đồng trong lúc cài mới, hoặc thêm chúng vào một bản cài hiện có. -::: - -## Module cộng đồng - -Các module cộng đồng được tuyển chọn trong [BMad plugins marketplace](https://github.com/bmad-code-org/bmad-plugins-marketplace). Chúng được sắp theo danh mục và được ghim vào commit đã được phê duyệt để tăng độ an toàn. - -### 1. Chạy trình cài đặt - -```bash -npx bmad-method install -``` - -### 2. Duyệt danh mục (catalog) cộng đồng - -Sau khi chọn module chính thức, trình cài đặt sẽ hỏi: - -``` -Would you like to browse community modules? -``` - -Chọn **Yes** để vào màn hình duyệt catalog. Tại đây bạn có thể: - -- Duyệt theo danh mục -- Xem các module nổi bật -- Xem toàn bộ module khả dụng -- Tìm kiếm theo từ khóa - -### 3. Chọn module - -Chọn module từ bất kỳ danh mục nào. Trình cài đặt sẽ hiển thị mô tả, phiên bản và mức độ tin cậy (trust tier). Những module đã cài sẽ được tick sẵn để tiện cập nhật. - -### 4. Tiếp tục quá trình cài đặt - -Sau khi chọn xong module cộng đồng, trình cài đặt sẽ chuyển sang bước nguồn tùy chỉnh (custom source), rồi tới cấu hình tool/IDE và phần còn lại của luồng cài đặt. - -## Nguồn tùy chỉnh: Git URL và đường dẫn cục bộ - -Module tùy chỉnh có thể đến từ bất kỳ kho Git nào hoặc từ một thư mục cục bộ trên máy bạn. Trình cài đặt sẽ resolve nguồn, phân tích cấu trúc module rồi cài nó song song với các module khác. - -### Cài đặt tương tác - -Trong quá trình cài, sau bước chọn community module, trình cài đặt sẽ hỏi: - -``` -Would you like to install from a custom source (Git URL or local path)? -``` - -Chọn **Yes**, rồi nhập nguồn: - -| Loại đầu vào | Ví dụ | -| --------------------- | ------------------------------------------------- | -| HTTPS URL trên bất kỳ host nào | `https://github.com/org/repo` | -| HTTP URL trên bất kỳ host nào | `http://host/org/repo` | -| HTTPS URL trỏ vào một thư mục con | `https://github.com/org/repo/tree/main/my-module` | -| SSH URL | `git@github.com:org/repo.git` | -| Đường dẫn cục bộ | `/Users/me/projects/my-module` | -| Đường dẫn cục bộ dùng `~` | `~/projects/my-module` | - -Với URL, trình cài đặt sẽ clone repository. Với đường dẫn cục bộ, nó sẽ đọc trực tiếp từ đĩa. Sau đó nó sẽ hiển thị các module tìm thấy để bạn chọn cài. - -### Cài đặt không tương tác - -Dùng cờ `--custom-source` để cài module tùy chỉnh từ dòng lệnh: - -```bash -npx bmad-method install \ - --directory . \ - --custom-source /path/to/my-module \ - --tools claude-code \ - --yes -``` - -Khi cung cấp `--custom-source` mà không kèm `--modules`, hệ thống chỉ cài core và các module tùy chỉnh. Nếu muốn cài cả module chính thức, hãy thêm `--modules`: - -```bash -npx bmad-method install \ - --directory . \ - --modules bmm \ - --custom-source https://gitlab.com/myorg/my-module \ - --tools claude-code \ - --yes -``` - -Bạn có thể truyền nhiều nguồn bằng cách ngăn cách chúng bằng dấu phẩy: - -```bash ---custom-source /path/one,https://github.com/org/repo,/path/two -``` - -## Cơ chế phát hiện module - -Trình cài đặt dùng hai chế độ để tìm module có thể cài trong một nguồn: - -| Chế độ | Điều kiện kích hoạt | Hành vi | -| --------- | ------------------------------------------------- | -------------------------------------------------------------------------------------------- | -| Discovery | Nguồn chứa `.claude-plugin/marketplace.json` | Liệt kê toàn bộ plugin trong manifest để bạn chọn cái nào cần cài | -| Direct | Không tìm thấy `marketplace.json` | Quét thư mục để tìm các skill, tức các thư mục con chứa `SKILL.md`, rồi coi toàn bộ như một module duy nhất | - -Discovery là chế độ phát hiện qua manifest. Direct là chế độ quét trực tiếp thư mục. Discovery phù hợp với module đã publish, còn Direct thuận tiện khi bạn đang trỏ vào một thư mục skills trong quá trình phát triển cục bộ. - -:::note[Về thư mục `.claude-plugin/`] -Đường dẫn `.claude-plugin/marketplace.json` là một quy ước tiêu chuẩn được nhiều trình cài đặt AI tool cùng dùng để hỗ trợ khả năng khám phá plugin. Nó không đòi hỏi Claude, không dùng Claude API và cũng không ảnh hưởng tới việc bạn đang dùng công cụ AI nào. Bất kỳ module nào có file này đều có thể được khám phá bởi những trình cài đặt tuân theo cùng quy ước. -::: - -## Quy trình phát triển cục bộ - -Nếu bạn đang xây một module bằng [BMad Builder](https://github.com/bmad-code-org/bmad-builder), bạn có thể cài trực tiếp từ thư mục đang làm việc: - -```bash -npx bmad-method install \ - --directory ~/my-project \ - --custom-source ~/my-module-repo/skills \ - --tools claude-code \ - --yes -``` - -Nguồn cục bộ được tham chiếu theo đường dẫn, không bị copy vào cache. Khi bạn sửa source của module rồi cài lại, trình cài đặt sẽ lấy đúng các thay đổi mới nhất. - -:::caution[Xóa nguồn sau khi cài] -Nếu bạn xóa thư mục nguồn cục bộ sau khi cài, các file module đã được cài bên trong `_bmad/` vẫn được giữ nguyên. Tuy vậy, module đó sẽ bị bỏ qua trong các lần cập nhật cho tới khi đường dẫn nguồn được khôi phục. -::: - -## Bạn sẽ nhận được gì - -Sau khi cài, các module tùy chỉnh sẽ xuất hiện trong `_bmad/` cùng với module chính thức: - -```text -your-project/ -├── _bmad/ -│ ├── core/ # Module core tích hợp -│ ├── bmm/ # Module chính thức, nếu bạn chọn -│ ├── my-module/ # Module tùy chỉnh của bạn -│ │ ├── my-skill/ -│ │ │ └── SKILL.md -│ │ └── module-help.csv -│ └── _config/ -│ └── manifest.yaml # Theo dõi mọi module, phiên bản và nguồn -└── ... -``` - -Manifest sẽ ghi lại nguồn của từng module tùy chỉnh, dùng `repoUrl` cho nguồn Git và `localPath` cho nguồn cục bộ, để quá trình cập nhật nhanh (quick update) sau này có thể tìm lại nguồn chính xác. - -## Cập nhật module tùy chỉnh - -Module tùy chỉnh tham gia vào luồng cập nhật bình thường: - -- **Cập nhật nhanh (quick update)** với `--action quick-update`: làm mới mọi module từ đúng nguồn ban đầu. Module dựa trên Git sẽ được fetch lại, còn module cục bộ sẽ được đọc lại từ đường dẫn nguồn -- **Cập nhật đầy đủ (full update)**: chạy lại bước chọn module để bạn có thể thêm hoặc gỡ module tùy chỉnh - -## Tạo module của riêng bạn - -Hãy dùng [BMad Builder](https://github.com/bmad-code-org/bmad-builder) để tạo module mà người khác có thể cài: - -1. Chạy `bmad-module-builder` để sinh skeleton cho module -2. Thêm skill, agent và workflow bằng các công cụ builder tương ứng -3. Publish lên một kho Git hoặc chia sẻ cả thư mục -4. Người khác có thể cài bằng `--custom-source ` - -Nếu muốn module hỗ trợ chế độ Discovery, hãy thêm `.claude-plugin/marketplace.json` ở root repository. Đây là quy ước chung giữa nhiều công cụ, không dành riêng cho Claude. Hãy xem [tài liệu của BMad Builder](https://github.com/bmad-code-org/bmad-builder) để biết định dạng của `marketplace.json`. - -:::tip[Hãy thử cục bộ trước] -Trong quá trình phát triển, hãy cài module bằng đường dẫn cục bộ để lặp nhanh trước khi publish lên kho Git. -::: diff --git a/docs/vi-vn/how-to/project-context.md b/docs/vi-vn/how-to/project-context.md deleted file mode 100644 index 2ca03c556f..0000000000 --- a/docs/vi-vn/how-to/project-context.md +++ /dev/null @@ -1,127 +0,0 @@ ---- -title: "Quản lý bối cảnh dự án" -description: Tạo và duy trì project-context.md để định hướng cho các agent AI -sidebar: - order: 8 ---- - -Sử dụng tệp `project-context.md` để đảm bảo các agent AI tuân theo ưu tiên kỹ thuật và quy tắc triển khai của dự án trong suốt mọi workflow. Để đảm bảo tệp này luôn sẵn có, bạn cũng có thể thêm dòng `Important project context and conventions are located in [path to project context]/project-context.md` vào file context của công cụ hoặc file always rules của bạn (như `AGENTS.md`). - -:::note[Điều kiện tiên quyết] -- Đã cài BMad Method -- Hiểu stack công nghệ và các quy ước của dự án -::: - -## Khi nào nên dùng - -- Bạn có các ưu tiên kỹ thuật rõ ràng trước khi bắt đầu làm kiến trúc -- Bạn đã hoàn thành kiến trúc và muốn ghi lại các quyết định để phục vụ triển khai -- Bạn đang làm việc với một codebase hiện có có những pattern đã ổn định -- Bạn thấy các agent đưa ra quyết định không nhất quán giữa các story - -## Bước 1: Chọn cách tiếp cận - -**Tự tạo bằng tay** - Phù hợp nhất khi bạn biết rõ cần tài liệu hóa quy tắc nào - -**Tạo sau kiến trúc** - Phù hợp để ghi lại các quyết định đã được đưa ra trong giai đoạn solutioning - -**Tạo cho dự án hiện có** - Phù hợp để khám phá pattern trong các codebase đã tồn tại - -## Bước 2: Tạo tệp - -### Lựa chọn A: Tạo thủ công - -Tạo tệp tại `_bmad-output/project-context.md`: - -```bash -mkdir -p _bmad-output -touch _bmad-output/project-context.md -``` - -Thêm stack công nghệ và các quy tắc triển khai của bạn: - -```markdown ---- -project_name: 'MyProject' -user_name: 'YourName' -date: '2026-02-15' -sections_completed: ['technology_stack', 'critical_rules'] ---- - -# Project Context for AI Agents - -## Technology Stack & Versions - -- Node.js 20.x, TypeScript 5.3, React 18.2 -- State: Zustand -- Testing: Vitest, Playwright -- Styling: Tailwind CSS - -## Critical Implementation Rules - -**TypeScript:** -- Strict mode enabled, no `any` types -- Use `interface` for public APIs, `type` for unions - -**Code Organization:** -- Components in `/src/components/` with co-located tests -- API calls use `apiClient` singleton — never fetch directly - -**Testing:** -- Unit tests focus on business logic -- Integration tests use MSW for API mocking -``` - -### Lựa chọn B: Tạo sau khi hoàn thành kiến trúc - -Chạy workflow trong một phiên chat mới: - -```bash -bmad-generate-project-context -``` - -Workflow sẽ quét tài liệu kiến trúc và tệp dự án để tạo tệp context ghi lại các quyết định đã được đưa ra. - -### Lựa chọn C: Tạo cho dự án hiện có - -Với các dự án hiện có, chạy: - -```bash -bmad-generate-project-context -``` - -Workflow sẽ phân tích codebase để nhận diện quy ước, sau đó tạo tệp context để bạn xem lại và chỉnh sửa. - -## Bước 3: Xác minh nội dung - -Xem lại tệp được tạo và đảm bảo nó ghi đúng: - -- Các phiên bản công nghệ chính xác -- Đúng các quy ước thực tế của bạn (không phải các best practice chung chung) -- Các quy tắc giúp tránh những lỗi thường gặp -- Các pattern đặc thù framework - -Chỉnh sửa thủ công để thêm phần còn thiếu hoặc loại bỏ những chỗ không chính xác. - -## Bạn nhận được gì - -Một tệp `project-context.md` sẽ: - -- Đảm bảo tất cả agent tuân theo cùng một bộ quy ước -- Ngăn các quyết định không nhất quán giữa các story -- Ghi lại các quyết định kiến trúc cho giai đoạn triển khai -- Làm tài liệu tham chiếu cho các pattern và quy tắc của dự án - -## Mẹo - -:::tip[Thực hành tốt] -- **Tập trung vào điều không hiển nhiên** - Ghi lại những pattern agent dễ bỏ sót (ví dụ: "Dùng JSDoc cho mọi lớp public"), thay vì các quy tắc phổ quát như "đặt tên biến có ý nghĩa". -- **Gọn nhẹ** - Tệp này được nạp trong mọi workflow triển khai. Tệp quá dài sẽ tốn context. Hãy bỏ qua nội dung chỉ áp dụng cho phạm vi hẹp hoặc một vài story cụ thể. -- **Cập nhật khi cần** - Sửa thủ công khi pattern thay đổi, hoặc tạo lại sau các thay đổi kiến trúc lớn. -- Hỗ trợ cùng loop `bmad-build` dù công việc vào trực tiếp hay sau planning sâu. -::: - -## Bước tiếp theo - -- [**Giải thích về Project Context**](../explanation/project-context.md) - Tìm hiểu sâu hơn cách nó hoạt động -- [**Bản đồ workflow**](../reference/workflow-map.md) - Xem workflow nào sử dụng project context diff --git a/docs/vi-vn/how-to/quick-fixes.md b/docs/vi-vn/how-to/quick-fixes.md deleted file mode 100644 index b8bab918c7..0000000000 --- a/docs/vi-vn/how-to/quick-fixes.md +++ /dev/null @@ -1,95 +0,0 @@ ---- -title: "Sửa nhanh" -description: Cách thực hiện các sửa nhanh và thay đổi ad-hoc -sidebar: - order: 5 ---- - -Sửa lỗi, refactor và thay đổi nhỏ có thể đi thẳng vào **Build** với ít hoặc không có planning upstream. Đây là cùng workflow triển khai dùng cho story đã lập kế hoạch đầy đủ. - -## Khi nào nên dùng - -- Sửa lỗi khi nguyên nhân đã rõ ràng -- Refactor nhỏ (đổi tên, tách hàm, tái cấu trúc) nằm trong một vài tệp -- Điều chỉnh tính năng nhỏ hoặc thay đổi cấu hình -- Cập nhật dependency - -:::note[Điều kiện tiên quyết] -- Đã cài BMad Method (`npx bmad-method install`) -- Một IDE tích hợp AI (Claude Code, Cursor, hoặc tương tự) -::: - -## Các bước thực hiện - -### 1. Bắt đầu một phiên chat mới - -Mở **một phiên chat mới** trong AI IDE của bạn. Tái sử dụng một phiên từ workflow trước dễ gây xung đột context. - -### 2. Mô tả ý định của bạn - -Build nhận ý định dạng tự do - trước, cùng lúc, hoặc sau khi gọi workflow. Ví dụ: - -```text -run build — Sửa lỗi validate đăng nhập cho phép mật khẩu rỗng. -``` - -```text -run build — fix https://github.com/org/repo/issues/42 -``` - -```text -run build — thực hiện ý định trong _bmad-output/implementation-artifacts/my-intent.md -``` - -```text -Tôi nghĩ vấn đề nằm ở auth middleware, nó không kiểm tra hạn của token. -Để tôi xem... đúng rồi, src/auth/middleware.ts dòng 47 bỏ qua -hoàn toàn phần kiểm tra exp. run build -``` - -```text -run build -> Bạn muốn làm gì? -Refactor UserService sang dùng async/await thay vì callbacks. -``` - -Văn bản thường, đường dẫn tệp, URL issue GitHub, liên kết bug tracker - bất kỳ thứ gì LLM có thể suy ra thành một ý định cụ thể. - -### 3. Trả lời câu hỏi và phê duyệt - -Build có thể đặt câu hỏi làm rõ hoặc đưa ra một bản spec ngắn để bạn phê duyệt trước khi triển khai. Hãy trả lời và phê duyệt khi bạn thấy kế hoạch đã ổn. - -### 4. Review và push - -Build sẽ triển khai thay đổi, tự review công việc của mình, sửa các vấn đề phát hiện được và commit vào local. Khi hoàn thành, nó sẽ mở các tệp bị ảnh hưởng trong editor. - -- Xem nhanh diff để xác nhận thay đổi đúng với ý định của bạn -- Nếu có gì không ổn, nói cho agent biết cần sửa gì - nó có thể lặp lại ngay trong cùng phiên - -Khi đã hài lòng, push commit. Build sẽ đề xuất push và tạo PR cho bạn. - -:::caution[Nếu có thứ bị vỡ] -Nếu thay đổi đã push gây sự cố ngoài ý muốn, dùng `git revert HEAD` để hoàn tác commit cuối một cách sạch sẽ. Sau đó bắt đầu một phiên chat mới và chạy lại Build để thử hướng khác. -::: - -## Bạn nhận được gì - -- Các tệp nguồn đã được sửa với bản fix hoặc refactor -- Test đã pass (nếu dự án có bộ test) -- Một commit sẵn sàng để push, dùng conventional commit message - -## Công việc trì hoãn - -Build giữ mỗi lần chạy tập trung vào một mục tiêu duy nhất. Nếu yêu cầu của bạn có nhiều mục tiêu độc lập, hoặc review phát hiện các vấn đề tồn tại sẵn không liên quan đến thay đổi hiện tại, Build sẽ đưa chúng vào tệp `deferred-work.md` trong thư mục implementation artifacts thay vì cố gắng xử lý tất cả một lúc. - -Hãy kiểm tra tệp này sau mỗi lần chạy - đó là backlog các việc bạn cần quay lại sau. Mỗi mục trì hoãn có thể được đưa vào một lần chạy Build mới. - -## Khi nào nên bổ sung lập kế hoạch đầy đủ - -Trước khi chạy cùng Build loop, cân nhắc bổ sung PRD, UX, kiến trúc hoặc lập kế hoạch story khi: - -- Thay đổi ảnh hưởng nhiều hệ thống hoặc cần cập nhật đồng bộ trên nhiều tệp -- Bạn chưa chắc phạm vi và cần làm rõ yêu cầu trước -- Bạn cần ghi lại tài liệu hoặc quyết định kiến trúc cho cả nhóm - -Xem [Build](../explanation/build.md) để hiểu cách ý định trực tiếp và công việc đã lập kế hoạch hội tụ vào cùng một vòng triển khai. diff --git a/docs/vi-vn/how-to/upgrade-to-v6.md b/docs/vi-vn/how-to/upgrade-to-v6.md deleted file mode 100644 index d72e719118..0000000000 --- a/docs/vi-vn/how-to/upgrade-to-v6.md +++ /dev/null @@ -1,100 +0,0 @@ ---- -title: "Cách nâng cấp lên v6" -description: Di chuyển từ BMad v4 sang v6 -sidebar: - order: 3 ---- - -Sử dụng trình cài đặt BMad để nâng cấp từ v4 lên v6, bao gồm khả năng tự động phát hiện bản cài đặt cũ và hỗ trợ di chuyển. - -## Khi nào nên dùng - -- Bạn đang dùng BMad v4 (thư mục `.bmad-method`) -- Bạn muốn chuyển sang kiến trúc v6 mới -- Bạn có các planning artifact hiện có cần giữ lại - -:::note[Điều kiện tiên quyết] -- Node.js 20.12+ -- Bản cài đặt BMad v4 hiện có -::: - -## Các bước thực hiện - -### 1. Chạy trình cài đặt - -Làm theo [Hướng dẫn cài đặt](./install-bmad.md). - -### 2. Xử lý bản cài đặt cũ - -Khi v4 được phát hiện, bạn có thể: - -- Cho phép trình cài đặt sao lưu và xóa `.bmad-method` -- Thoát và tự xử lý dọn dẹp thủ công - -Nếu trước đây bạn đặt tên thư mục BMad khác - bạn sẽ phải tự xóa thư mục đó. - -### 3. Dọn dẹp skill IDE cũ - -Tự xóa các command/skill IDE cũ của v4 - ví dụ nếu bạn dùng Claude Code, hãy tìm các thư mục lồng nhau bắt đầu bằng `bmad` và xóa chúng: - -- `.claude/commands/` - -Các skill v6 mới sẽ được cài tại: - -- `.claude/skills/` - -### 4. Di chuyển planning artifacts - -**Nếu bạn có tài liệu lập kế hoạch (Brief/PRD/UX/Architecture):** - -Di chuyển chúng vào `_bmad-output/planning-artifacts/` với tên mô tả rõ ràng: - -- Tên tệp PRD nên chứa `PRD` -- Tên tệp tương ứng nên chứa `brief`, `architecture`, hoặc `ux-design` -- Tài liệu đã chia nhỏ có thể đặt trong các thư mục con đặt tên phù hợp - -**Nếu bạn đang lập kế hoạch dở dang:** Hãy cân nhắc bắt đầu lại với workflow v6. Bạn vẫn có thể dùng các tài liệu hiện có làm input - các workflow discovery tiên tiến trong v6, kết hợp web search và chế độ plan trong IDE, cho kết quả tốt hơn. - -### 5. Di chuyển công việc phát triển đang dở dang - -Nếu bạn đã có các story được tạo hoặc đã triển khai: - -1. Hoàn thành cài đặt v6 -2. Đặt `epics.md` hoặc `epics/epic*.md` vào `_bmad-output/planning-artifacts/` -3. Chạy workflow `bmad-sprint-planning` của Scrum Master -4. Nói rõ với SM những epic/story nào đã hoàn thành - -## Bạn nhận được gì - -**Cấu trúc thống nhất của v6:** - -```text -du-an-cua-ban/ -├── _bmad/ # Thư mục cài đặt duy nhất -│ ├── _config/ # Các tùy chỉnh của bạn -│ │ └── agents/ # Tệp tùy chỉnh agent -│ ├── core/ # Framework core dùng chung -│ ├── bmm/ # Module BMad Method -│ ├── bmb/ # BMad Builder -│ └── cis/ # Creative Intelligence Suite -└── _bmad-output/ # Thư mục output (là thư mục docs trong v4) -``` - -## Di chuyển module - -| Module v4 | Trạng thái trong v6 | -| --- | --- | -| `.bmad-2d-phaser-game-dev` | Đã được tích hợp vào module BMGD | -| `.bmad-2d-unity-game-dev` | Đã được tích hợp vào module BMGD | -| `.bmad-godot-game-dev` | Đã được tích hợp vào module BMGD | -| `.bmad-infrastructure-devops` | Đã bị ngừng hỗ trợ - agent DevOps mới sắp ra mắt | -| `.bmad-creative-writing` | Chưa được điều chỉnh - module v6 mới sắp ra mắt | - -## Các thay đổi chính - -| Khái niệm | v4 | v6 | -| --- | --- | --- | -| **Core** | `_bmad-core` thực chất là BMad Method | `_bmad/core/` là framework dùng chung | -| **Method** | `_bmad-method` | `_bmad/bmm/` | -| **Config** | Sửa trực tiếp các tệp | `config.yaml` theo từng module | -| **Documents** | Cần thiết lập trước cho bản chia nhỏ hoặc nguyên khối | Linh hoạt hoàn toàn, tự động quét | diff --git a/docs/vi-vn/index.md b/docs/vi-vn/index.md deleted file mode 100644 index 551d73393a..0000000000 --- a/docs/vi-vn/index.md +++ /dev/null @@ -1,56 +0,0 @@ ---- -title: Chào mừng đến với BMad Method -description: Framework phát triển phần mềm dựa trên AI với các agent chuyên biệt, workflow có hướng dẫn và khả năng lập kế hoạch thông minh ---- - -BMad Method (**B**uild **M**ore **A**rchitect **D**reams) là một framework phát triển phần mềm dựa trên AI trong hệ sinh thái BMad Method, giúp bạn xây dựng phần mềm xuyên suốt toàn bộ quy trình, từ hình thành ý tưởng và lập kế hoạch cho tới triển khai với agent. Framework này cung cấp các AI agent chuyên biệt, workflow có hướng dẫn, và khả năng lập kế hoạch thông minh thích ứng với độ phức tạp của dự án, dù bạn đang sửa một lỗi nhỏ hay xây dựng một nền tảng doanh nghiệp. - -Nếu bạn đã quen làm việc với các trợ lý AI cho lập trình như Claude, Cursor, hoặc GitHub Copilot, bạn có thể bắt đầu ngay. - -## Mới bắt đầu? Hãy xem một Tutorial trước - -Cách nhanh nhất để hiểu BMad là dùng thử nó. - -- **[Bắt đầu với BMad](./tutorials/getting-started.md)** — Cài đặt và hiểu cách BMad hoạt động -- **[Sơ đồ Workflow](./reference/workflow-map.md)** — Tổng quan trực quan về các phase của BMM, workflow, và cách quản lý context - -:::tip[Muốn vào việc ngay?] -Cài BMad và dùng skill `bmad-help` — nó sẽ hướng dẫn bạn mọi thứ dựa trên dự án và các module đã cài. -::: - -## Cách dùng bộ tài liệu này - -Bộ tài liệu này được chia thành bốn phần, dựa trên mục tiêu của bạn: - -| Phần | Mục đích | -| ----------------- | ---------------------------------------------------------------------------------------------------------- | -| **Tutorials** | Thiên về học theo từng bước. Đây là các hướng dẫn tuần tự giúp bạn xây dựng một thứ gì đó. Nếu bạn mới làm quen, hãy bắt đầu ở đây. | -| **How-To Guides** | Thiên về tác vụ. Đây là các hướng dẫn thực tế để giải quyết một vấn đề cụ thể. Câu hỏi kiểu “Làm sao để tùy chỉnh một agent?” nằm ở phần này. | -| **Explanation** | Thiên về hiểu bản chất. Đây là các bài phân tích sâu về khái niệm và kiến trúc. Hãy đọc khi bạn muốn hiểu *vì sao*. | -| **Reference** | Thiên về tra cứu thông tin. Đây là đặc tả kỹ thuật cho agent, workflow, và cấu hình. | - -## Mở rộng và tùy chỉnh - -Bạn muốn mở rộng BMad bằng các agent, workflow, hoặc module của riêng mình? **[BMad Builder](https://bmad-builder-docs.bmad-method.org/)** cung cấp framework và công cụ để tạo các phần mở rộng tùy chỉnh, dù bạn chỉ bổ sung khả năng mới cho BMad hay xây dựng hẳn một module mới từ đầu. - -## Bạn cần gì để bắt đầu - -BMad hoạt động với bất kỳ trợ lý AI cho lập trình nào hỗ trợ custom system prompt hoặc project context. Một số lựa chọn phổ biến: - -- **[Claude Code](https://code.claude.com)** — Công cụ CLI của Anthropic (khuyến nghị) -- **[Cursor](https://cursor.sh)** — Trình soạn thảo mã lấy AI làm trung tâm -- **[Codex CLI](https://github.com/openai/codex)** — Agent lập trình trên terminal của OpenAI - -Bạn nên quen với các khái niệm phát triển phần mềm cơ bản như quản lý phiên bản, cấu trúc dự án, và workflow Agile. Không cần có kinh nghiệm trước với các hệ thống agent kiểu BMad, vì bộ tài liệu này được viết ra chính để hỗ trợ việc đó. - -## Tham gia cộng đồng - -Nhận trợ giúp, chia sẻ những gì bạn đang xây dựng, hoặc đóng góp cho BMad: - -- **[Discord](https://discord.gg/gk8jAdXWmj)** — Trao đổi với những người dùng BMad khác, đặt câu hỏi, chia sẻ ý tưởng -- **[GitHub](https://github.com/bmad-code-org/BMAD-METHOD)** — Mã nguồn, issues, và đóng góp -- **[YouTube](https://www.youtube.com/@BMadCode)** — Video hướng dẫn và walkthrough - -## Bước tiếp theo - -Sẵn sàng bắt đầu? **[Bắt đầu với BMad](./tutorials/getting-started.md)** và xây dựng dự án đầu tiên của bạn. diff --git a/docs/vi-vn/reference/agents.md b/docs/vi-vn/reference/agents.md deleted file mode 100644 index 026285e875..0000000000 --- a/docs/vi-vn/reference/agents.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -title: Các agent -description: Các agent mặc định của BMM cùng skill ID, trigger menu và workflow chính -sidebar: - order: 2 ---- - -## Các Agent Mặc Định - -Trang này liệt kê các agent mặc định của BMM (bộ Agile suite) được cài cùng với BMad Method, bao gồm skill ID, trigger menu và workflow chính của chúng. Mỗi agent được gọi dưới dạng một skill. - -## Ghi Chú - -- Mỗi agent đều có sẵn dưới dạng một skill do trình cài đặt tạo ra. Skill ID, ví dụ `bmad-dev`, được dùng để gọi agent. -- Trigger là các mã menu ngắn, ví dụ `CP`, cùng với các fuzzy match hiển thị trong menu của từng agent. -- Việc tạo test QA do workflow skill `bmad-qa-generate-e2e-tests` đảm nhận, khả dụng thông qua Developer agent. Module Test Architect (TEA) đầy đủ nằm trong một module riêng. - -| Agent | Skill ID | Trigger | Workflow chính | -| --------------------------- | -------------------- | ---------------------------------- | --------------------------------------------------------------------------------------------------- | -| Analyst (Mary) | `bmad-analyst` | `BP`, `MR`, `DR`, `TR`, `CB`, `WB`, `DP` | Brainstorm, Market Research, Domain Research, Technical Research, Create Brief, PRFAQ Challenge, Document Project | -| Product Manager (John) | `bmad-pm` | `CP`, `VP`, `EP`, `CE`, `IR`, `CC` | Create/Validate/Edit PRD, Create Epics and Stories, Implementation Readiness, Correct Course | -| Architect (Winston) | `bmad-architect` | `CA`, `IR` | Create Architecture, Implementation Readiness | -| Developer (Amelia) | `bmad-agent-dev` | `BD`, `QA`, `CR`, `SP`, `ER` | Build, QA Test Generation, Code Review, Sprint Planning, Epic Retrospective | -| UX Designer (Sally) | `bmad-ux-designer` | `CU` | Create UX Design | - -:::note[Paige đâu rồi?] -Technical Writer (Paige) đang tạm nghỉ — cô ấy sẽ trở lại trong tương lai với năng lực mạnh hơn nhiều. Tài liệu dự án vẫn được hỗ trợ: trigger `DP` (Document Project) khả dụng qua Analyst agent, hoặc gọi trực tiếp skill `bmad-document-project`. -::: - -## Các Loại Trigger - -Trigger trong menu agent sẽ nạp một file workflow có cấu trúc. Bạn gõ mã trigger, agent sẽ bắt đầu workflow và nhắc bạn nhập thông tin ở từng bước. - -Ví dụ: `CP` (Create PRD), `CA` (Create Architecture), `BD` (Build) diff --git a/docs/vi-vn/reference/commands.md b/docs/vi-vn/reference/commands.md deleted file mode 100644 index 524776b08d..0000000000 --- a/docs/vi-vn/reference/commands.md +++ /dev/null @@ -1,134 +0,0 @@ ---- -title: Các skill -description: Tài liệu tham chiếu cho skill của BMad — skill là gì, hoạt động ra sao và tìm ở đâu. -sidebar: - order: 4 ---- - -Skills là các prompt dựng sẵn để nạp agent, chạy workflow hoặc thực thi task bên trong IDE của bạn. Trình cài đặt BMad sinh chúng từ các module bạn đã chọn tại thời điểm cài đặt. Nếu sau này bạn thêm, xóa hoặc thay đổi module, hãy chạy lại trình cài đặt để đồng bộ skills (xem [Khắc phục sự cố](#khắc-phục-sự-cố)). - -## Skill So Với Trigger Trong Menu Agent - -BMad cung cấp hai cách để bắt đầu công việc, và chúng phục vụ những mục đích khác nhau. - -| Cơ chế | Cách gọi | Điều xảy ra | -| --- | --- | --- | -| **Skill** | Gõ tên skill, ví dụ `bmad-help`, trong IDE | Nạp trực tiếp agent, chạy workflow hoặc thực thi task | -| **Trigger menu agent** | Nạp agent trước, sau đó gõ mã ngắn như `BD` | Agent diễn giải mã đó và bắt đầu workflow tương ứng trong khi vẫn giữ đúng persona | - -Trigger trong menu agent yêu cầu bạn đang ở trong một phiên agent đang hoạt động. Dùng skill khi bạn đã biết mình muốn workflow nào. Dùng trigger khi bạn đang làm việc với một agent và muốn đổi tác vụ mà không rời khỏi cuộc hội thoại. - -## Skills Được Tạo Ra Như Thế Nào - -Khi bạn chạy `npx bmad-method install`, trình cài đặt sẽ đọc manifest của mọi module được chọn rồi tạo một skill cho mỗi agent, workflow, task và tool. Mỗi skill là một thư mục chứa file `SKILL.md`, hướng dẫn AI nạp file nguồn tương ứng và làm theo chỉ dẫn trong đó. - -Trình cài đặt dùng template cho từng loại skill: - -| Loại skill | File được tạo sẽ làm gì | -| --- | --- | -| **Agent launcher** | Nạp file persona của agent, kích hoạt menu của nó và giữ nguyên vai trò | -| **Workflow skill** | Nạp cấu hình workflow và làm theo các bước | -| **Task skill** | Nạp một file task độc lập và làm theo hướng dẫn | -| **Tool skill** | Nạp một file tool độc lập và làm theo hướng dẫn | - -:::note[Chạy lại trình cài đặt] -Nếu bạn thêm hoặc bớt module, hãy chạy lại trình cài đặt. Nó sẽ tạo lại toàn bộ file skill khớp với tập module hiện tại. -::: - -## File Skill Nằm Ở Đâu - -Trình cài đặt sẽ ghi file skill vào một thư mục dành riêng cho IDE bên trong dự án. Đường dẫn chính xác phụ thuộc vào IDE bạn chọn khi cài. - -| IDE / CLI | Thư mục skill | -| --- | --- | -| Claude Code | `.claude/skills/` | -| Cursor | `.cursor/skills/` | -| Windsurf | `.windsurf/skills/` | -| IDE khác | Xem output của trình cài đặt để biết đường dẫn đích | - -Mỗi skill là một thư mục chứa file `SKILL.md`. Ví dụ với Claude Code, cấu trúc sẽ như sau: - -```text -.claude/skills/ -├── bmad-help/ -│ └── SKILL.md -├── bmad-prd/ -│ └── SKILL.md -├── bmad-agent-dev/ -│ └── SKILL.md -└── ... -``` - -Tên thư mục quyết định tên skill trong IDE. Ví dụ thư mục `bmad-agent-dev/` sẽ đăng ký skill `bmad-agent-dev`. - -## Cách Tìm Danh Sách Skill Của Bạn - -Gõ tên skill trong IDE để gọi nó. Một số nền tảng yêu cầu bạn bật skills trong phần cài đặt trước khi chúng xuất hiện. - -Chạy `bmad-help` để nhận hướng dẫn có ngữ cảnh về bước tiếp theo. - -:::tip[Khám phá nhanh] -Các thư mục skill được tạo trong dự án chính là danh sách chuẩn nhất. Mở chúng trong trình quản lý file để xem toàn bộ skill cùng mô tả. -::: - -## Các Nhóm Skill - -### Agent Skills - -Agent skills nạp một persona AI chuyên biệt với vai trò, phong cách giao tiếp và menu workflow xác định sẵn. Sau khi được nạp, agent sẽ giữ đúng vai trò và phản hồi qua các trigger trong menu. - -| Ví dụ skill | Agent | Vai trò | -| --- | --- | --- | -| `bmad-agent-dev` | Amelia (Developer) | Triển khai story với mức tuân thủ đặc tả nghiêm ngặt | -| `bmad-pm` | John (Product Manager) | Tạo và kiểm tra PRD | -| `bmad-architect` | Winston (Architect) | Thiết kế kiến trúc hệ thống | - -Xem [Agents](./agents.md) để biết danh sách đầy đủ các agent mặc định và trigger của chúng. - -### Workflow Skills - -Workflow skills chạy một quy trình có cấu trúc, nhiều bước mà không cần nạp persona agent trước. Chúng nạp cấu hình workflow rồi thực hiện theo từng bước. - -| Ví dụ skill | Mục đích | -| --- | --- | -| `bmad-product-brief` | Tạo product brief — phiên discovery có hướng dẫn khi concept của bạn đã rõ | -| `bmad-prfaq` | Bài kiểm tra [Working Backwards PRFAQ](../explanation/analysis-phase.md#prfaq-working-backwards) để stress-test concept sản phẩm | -| `bmad-prd` | Tạo Product Requirements Document | -| `bmad-architecture` | Thiết kế kiến trúc hệ thống | -| `bmad-create-epics-and-stories` | Tạo epics và stories | -| `bmad-code-review` | Chạy code review | -| `bmad-build` | Triển khai ý định trực tiếp, issue, tính năng, bản sửa hoặc story đã lập kế hoạch | - -Xem [Workflow Map](./workflow-map.md) để có tài liệu workflow đầy đủ theo từng phase. - -### Task Skills Và Tool Skills - -Tasks và tools là các thao tác độc lập, không yêu cầu ngữ cảnh agent hay workflow. - -**BMad-Help: người dẫn đường thông minh của bạn** - -`bmad-help` là giao diện chính để bạn khám phá nên làm gì tiếp theo. Nó kiểm tra dự án, hiểu truy vấn ngôn ngữ tự nhiên và đề xuất bước bắt buộc hoặc tùy chọn tiếp theo dựa trên các module đã cài. - -:::note[Ví dụ] -```text -bmad-help -bmad-help I have a SaaS idea and know all the features. Where do I start? -bmad-help What are my options for UX design? -``` -::: - -**Các task và tool lõi khác** - -Module lõi có 8 công cụ tích hợp sẵn — trợ giúp, review, tinh luyện, tùy biến và các skill tư duy (brainstorming, forge idea, party mode). Xem [Core Tools](./core-tools.md) để có tài liệu tham chiếu đầy đủ. - -## Quy Ước Đặt Tên - -Mọi skill đều dùng tiền tố `bmad-` theo sau là tên mô tả, ví dụ `bmad-agent-dev`, `bmad-prd`, `bmad-help`. Xem [Modules](./modules.md) để biết các module hiện có. - -## Khắc Phục Sự Cố - -**Skills không xuất hiện sau khi cài đặt.** Một số nền tảng yêu cầu bật skills thủ công trong phần cài đặt. Hãy kiểm tra tài liệu IDE của bạn hoặc hỏi trợ lý AI cách bật skills. Bạn cũng có thể cần khởi động lại IDE hoặc reload cửa sổ. - -**Thiếu skill mà bạn mong đợi.** Trình cài đặt chỉ tạo skill cho những module bạn đã chọn. Hãy chạy lại `npx bmad-method install` và kiểm tra lại phần chọn module. Đồng thời xác nhận rằng file skill thực sự tồn tại trong thư mục dự kiến. - -**Skill từ module đã bỏ vẫn còn xuất hiện.** Trình cài đặt không tự xóa các file skill cũ. Hãy xóa các thư mục lỗi thời trong thư mục skills của IDE, hoặc xóa toàn bộ thư mục skills rồi chạy lại trình cài đặt để có tập skill sạch. diff --git a/docs/vi-vn/reference/core-tools.md b/docs/vi-vn/reference/core-tools.md deleted file mode 100644 index 9ceeba4dde..0000000000 --- a/docs/vi-vn/reference/core-tools.md +++ /dev/null @@ -1,216 +0,0 @@ ---- -title: Công cụ cốt lõi -description: Tài liệu tham chiếu cho các skill tích hợp sẵn của module lõi. -sidebar: - order: 3 ---- - -Mọi bản cài BMad đều bao gồm **module lõi** — một tập nhỏ các skill hoạt động xuyên suốt mọi dự án, mọi module và mọi giai đoạn. Trang này bao quát 7 skill lõi đó: 4 công cụ nhân lõi cùng 3 **skill tư duy** (brainstorming, forge idea, party mode). - -:::tip[Lối đi nhanh] -Chạy bất kỳ công cụ nào bằng cách gõ tên skill của nó, ví dụ `bmad-help`, trong IDE của bạn. Không cần mở phiên agent trước. -::: - -## Tổng Quan - -**Module lõi (luôn được cài):** - -| Công cụ | Mục đích | -| --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | -| [`bmad-help`](#bmad-help) | Nhận hướng dẫn có ngữ cảnh về việc nên làm gì tiếp theo | -| [`bmad-advanced-elicitation`](#bmad-advanced-elicitation) | Đẩy đầu ra của LLM qua các vòng tinh luyện lặp | -| [`bmad-review`](#bmad-review) | Review đa lăng kính — hoài nghi, ca biên, lỗ hổng kiểm chứng cho code; cấu trúc và câu chữ cho tài liệu | -| [`bmad-customize`](#bmad-customize) | Tạo và kiểm tra các tùy biến BMad | - -**Skill tư duy:** - -| Công cụ | Mục đích | -| ------------------------------------------- | --------------------------------------------------------------------------------------- | -| [`bmad-brainstorming`](#bmad-brainstorming) | Tổ chức các phiên brainstorming có tương tác | -| [`bmad-forge-idea`](#bmad-forge-idea) | Thử lửa một ý tưởng cho đến khi nó cứng cáp, được chứng thực hoặc chết với chi phí thấp | -| [`bmad-party-mode`](#bmad-party-mode) | Điều phối thảo luận nhóm nhiều agent | - -:::note[Đã chuyển và đã gỡ] -`bmad-spec` giờ đi kèm module BMM như một workflow lập kế hoạch Giai đoạn 2 — xem [Bản đồ Workflow](./workflow-map.md). Các tiện ích `bmad-shard-doc` và `bmad-index-docs` đã bị gỡ bỏ. Các skill cũ `bmad-editorial-review`, `bmad-editorial-review-prose`, `bmad-editorial-review-structure`, `bmad-review-adversarial-general`, `bmad-review-edge-case-hunter` và `bmad-review-verification-gap` đều đã được gộp vào `bmad-review`, với các lăng kính biên tập thay thế skill biên tập riêng lẻ; các ID cũ vẫn hoạt động qua cơ chế chuyển tiếp để giữ tương thích. -::: - -## bmad-help - -**Người dẫn đường thông minh cho bước tiếp theo của bạn.** Công cụ này kiểm tra trạng thái dự án, phát hiện những gì đã hoàn thành và đề xuất bước bắt buộc hoặc tùy chọn tiếp theo. - -**Dùng khi:** - -- Bạn vừa hoàn tất một quy trình và muốn biết tiếp theo là gì -- Bạn mới làm quen với BMad và cần định hướng -- Bạn đang mắc kẹt và muốn lời khuyên có ngữ cảnh -- Bạn vừa cài module mới và muốn xem có gì khả dụng - -**Cách hoạt động:** - -1. Quét dự án để tìm các artifact hiện có như PRD, architecture, stories, v.v. -2. Phát hiện các module đã cài và workflow khả dụng của chúng -3. Đề xuất bước tiếp theo theo thứ tự ưu tiên — bước bắt buộc trước, tùy chọn sau -4. Trình bày từng đề xuất cùng lệnh skill và mô tả ngắn - -**Đầu vào:** Truy vấn ngôn ngữ tự nhiên tùy chọn, ví dụ `bmad-help I have a SaaS idea, where do I start?` - -**Đầu ra:** Danh sách ưu tiên các bước tiếp theo được khuyến nghị kèm lệnh skill - -## bmad-advanced-elicitation - -**Đẩy LLM xem xét lại, tinh luyện và cải thiện đầu ra gần nhất của nó.** Đây là điểm dừng tinh luyện dùng chung của BMad: các skill khác gọi nó tại các điểm nghỉ tự nhiên, và bạn có thể gọi trực tiếp lên bất kỳ nội dung nào gần đây trong cuộc hội thoại. - -**Dùng khi:** - -- Đầu ra của LLM còn nông hoặc quá chung chung -- Bạn muốn khám phá một chủ đề từ nhiều góc phân tích khác nhau -- Bạn đang tinh chỉnh một tài liệu quan trọng và cần chiều sâu hơn -- Bạn muốn gọi đích danh một phương pháp — Socratic, first principles, pre-mortem, red team - -**Cách hoạt động:** - -1. Mặc định nhắm vào đầu ra gần nhất trong hội thoại, trừ khi bạn chỉ định nội dung khác -2. Đưa ra một menu ngắn các phương pháp elicitation phù hợp nhất với nội dung -3. Áp dụng các phương pháp đã chọn lên mục tiêu -4. Trả lại phiên bản đã cải thiện để luồng gọi tiếp tục từ chỗ tạm dừng - -**Đầu vào:** Đầu ra gần nhất cần tinh luyện (mặc định), hoặc bất kỳ nội dung nào bạn chỉ định; tùy chọn kèm tên phương pháp - -**Đầu ra:** Phiên bản nội dung đã được nâng cấp - -## bmad-review - -**Review đa lăng kính trên bất kỳ diff, tài liệu hay artifact nào.** Chạy các lăng kính review — mỗi lăng kính một phương pháp và lập trường riêng — và báo cáo mọi phát hiện theo một định dạng chuẩn duy nhất. Không phát hiện gì cũng là kết quả hợp lệ; nó không bao giờ độn thêm cho có vẻ kỹ lưỡng. Mỗi lăng kính khai báo phạm vi áp dụng: diff kéo theo các lăng kính code, tài liệu kéo theo các lăng kính biên tập. - -**Các lăng kính đi kèm:** - -| Lăng kính | Áp dụng cho | Phương pháp | -| ----------------------------------------- | ----------------------- | -------------------------------------------------------------------------------------------- | -| **Hoài nghi (Adversarial)** | Mọi nội dung | Review buộc phải đưa ra ≥10 phát hiện, tìm phần còn thiếu chứ không chỉ phần sai; không được danh sách rỗng | -| **Ca biên (Edge case)** | Mọi nội dung | Đi qua mọi nhánh rẽ và điều kiện biên trong nội dung có định nghĩa hành vi | -| **Lỗ hổng kiểm chứng (Verification gap)** | Code | Tìm hành vi đã thay đổi có thể hồi quy mà không có kiểm chứng đáng tin cậy nào bắt được | -| **Cấu trúc (Structure)** | Tài liệu | Đề xuất cắt, gộp, di chuyển và cô đọng — hình hài tài liệu có phục vụ mục đích của nó không? | -| **Câu chữ (Prose)** | Tài liệu | Biên tập các vấn đề diễn đạt gây cản trở việc hiểu | - -Hai lăng kính biên tập coi nội dung là bất khả xâm phạm: không bao giờ chất vấn ý tưởng của bạn, chỉ xét cách tổ chức và diễn đạt, và chỉ đề xuất chứ không tự sửa. Khi chọn cả hai, lăng kính câu chữ chạy trên các phát hiện của lăng kính cấu trúc. - -Tập lăng kính không cố định: một override trong `customize.toml` có thể thêm lăng kính hoặc thay thế lăng kính có sẵn, và mỗi lần rà soát sẽ chạy những gì thực sự được phân giải. - -**Dùng khi:** - -- Bạn cần bảo đảm chất lượng trước khi chốt một deliverable -- Bạn muốn phủ kín các ca biên của code hoặc logic -- Bạn muốn biết một thay đổi đã được kiểm chứng đầy đủ chưa -- Bạn đã viết xong một tài liệu và muốn siết lại cho gọn và mượt -- Bạn muốn rút ngắn độ dài mà vẫn giữ được khả năng hiểu - -**Cách hoạt động:** - -1. Nạp nội dung, nhận diện loại — diff, file, hàm hoặc tài liệu — và thuộc về code hay tài liệu -2. Chọn lăng kính: những cái bạn nêu tên, hoặc mọi lăng kính đang bật có phạm vi áp dụng và điều kiện khớp với nội dung -3. Công bố kế hoạch — những lăng kính nào sẽ chạy, và lăng kính nào chạy trên phát hiện của lăng kính khác -4. Chạy các lăng kính độc lập — song song qua subagent khi nền tảng hỗ trợ — rồi tới các lăng kính phụ thuộc -5. Gom về một danh sách phát hiện duy nhất; trùng lặp giữa các lăng kính là tín hiệu, không phải lặp thừa - -**Đầu vào:** - -- `content` _(bắt buộc)_ — Diff, branch, thay đổi chưa commit, file, spec, story hoặc bất kỳ tài liệu nào -- `lenses` _(tùy chọn)_ — một hoặc nhiều mã/tên lăng kính; mặc định là review đầy đủ -- `also_consider` _(tùy chọn)_ — Các vùng bổ sung cần để ý -- `style_guide` / `reader_type` _(tùy chọn, cho lăng kính biên tập)_ — style guide của dự án, và `humans` (mặc định) hoặc `llm` - -**Đầu ra:** Mảng phát hiện JSON và/hoặc báo cáo markdown nhóm theo lăng kính. Có thể thêm lăng kính tùy biến — và tinh chỉnh hoặc tắt các lăng kính đi kèm — qua `customize.toml` của skill - -## bmad-customize - -**Tạo và kiểm tra các tùy biến.** Giúp bạn thay đổi hành vi của một agent hoặc workflow BMad đã cài mà không phải tự viết TOML. - -**Dùng khi:** - -- Bạn muốn thay đổi hành vi của một agent hoặc workflow -- Bạn cần thêm các dữ kiện bền vững, hook kích hoạt hoặc mục menu tùy biến -- Bạn muốn phạm vi override đúng được chọn và kiểm tra tự động - -**Cách hoạt động:** - -1. Quét các skill BMad đã cài để tìm các bề mặt có thể tùy biến -2. Chọn phạm vi phù hợp cho thay đổi bạn yêu cầu -3. Ghi các file override dưới `_bmad/custom/` -4. Kiểm tra cấu hình sau khi hợp nhất - -**Đầu vào:** Mô tả bằng ngôn ngữ tự nhiên về tùy biến bạn muốn - -**Đầu ra:** Các file override TOML dưới `_bmad/custom/`. Xem hướng dẫn chi tiết tại [Cách tùy biến BMad](../how-to/customize-bmad.md) - -## Các skill tư duy - -Ba skill dưới đây hoàn thiện module lõi — những công cụ tư duy đa dụng mà bất kỳ giai đoạn hay module nào cũng có thể dựa vào. - -### bmad-brainstorming - -**Tạo ra nhiều ý tưởng đa dạng bằng các kỹ thuật sáng tạo có tương tác.** Đây là một phiên động não có điều phối, nạp các phương pháp phát ý tưởng đã được kiểm chứng từ thư viện kỹ thuật và dẫn bạn đến 100+ ý tưởng trước khi bắt đầu sắp xếp. - -**Dùng khi:** - -- Bạn đang bắt đầu một dự án mới và cần khám phá không gian vấn đề -- Bạn đang bí ý tưởng và cần một quy trình sáng tạo có cấu trúc -- Bạn muốn dùng các framework tạo ý tưởng đã được kiểm chứng như SCAMPER, reverse brainstorming, v.v. - -**Cách hoạt động:** - -1. Thiết lập phiên brainstorming theo chủ đề của bạn -2. Nạp các kỹ thuật sáng tạo từ thư viện phương pháp -3. Dẫn bạn đi qua từng kỹ thuật để tạo ý tưởng -4. Áp dụng giao thức chống thiên lệch — cứ mỗi 10 ý tưởng lại đổi miền sáng tạo để tránh gom cụm - -**Đầu vào:** Chủ đề brainstorming hoặc phát biểu vấn đề, cùng file context tùy chọn - -**Đầu ra:** một trang `brainstorm.html` độc lập làm kỷ vật của phiên, file `brainstorm-intent.md` tùy chọn cho các skill hạ nguồn, và bản ghi phiên `.memlog.md` - -:::note[Mục tiêu về số lượng] -Điểm bứt phá thường nằm ở vùng ý tưởng thứ 50-100. Workflow này khuyến khích bạn tạo 100+ ý tưởng trước khi sắp xếp. -::: - -### bmad-forge-idea - -**Thử lửa một ý tưởng cho đến khi nó cứng cáp, được chứng thực hoặc chết với chi phí thấp.** Một người chất vấn phản biện dồn một ý tưởng còn dang dở đi từng câu hỏi một, đưa hai nhân vật vào mỗi nhánh rẽ, cho đến khi thứ sống sót là điều bạn có thể hành động với niềm tin chắc chắn. - -**Dùng khi:** - -- Bạn có một ý tưởng và muốn stress-test nó trước khi đầu tư -- Bạn muốn một đánh giá thẳng thắn về việc có nên bỏ nó không -- Bạn cần một người đồng hành tư duy biết phản bác thay vì gật đầu - -**Cách hoạt động:** - -1. Xác lập mục tiêu ngay từ đầu và lái việc chất vấn theo mục tiêu đó -2. Làm việc từng câu hỏi một theo thứ tự phụ thuộc, đặt sẵn một câu trả lời khuyến nghị để bạn phản bác -3. Đưa hai giọng nói vào mỗi nhánh — một từ đội hình đã cài của bạn, một do chủ đề gợi lên -4. Chất vấn các thuật ngữ mơ hồ và kiểm tra các luận điểm dựa trên tư liệu của dự án hiện có -5. Kết thúc ở trạng thái Hardened (cứng cáp), Killed (bị loại) hoặc Clearer (rõ hơn), kèm báo cáo độc lập bạn có thể giữ lại - -**Đầu vào:** Ý tưởng thuộc bất kỳ lĩnh vực nào — một tính năng, mô hình kinh doanh, giả thuyết nghiên cứu, quyết định cuộc sống - -**Đầu ra:** Bản chưng cất `forged-idea.md` khi ý tưởng cứng cáp (tùy chọn), cộng một `forge-report.html` làm kỷ vật cho mỗi lần chạy - -### bmad-party-mode - -**Điều phối thảo luận nhóm nhiều agent.** Công cụ này nạp toàn bộ agent BMad đã cài và tạo một cuộc trao đổi tự nhiên, nơi mỗi agent đóng góp từ góc nhìn chuyên môn và cá tính riêng. - -**Dùng khi:** - -- Bạn cần nhiều góc nhìn chuyên gia cho một quyết định -- Bạn muốn các agent phản biện giả định của nhau -- Bạn đang khám phá một chủ đề phức tạp trải qua nhiều miền khác nhau - -**Cách hoạt động:** - -1. Nạp manifest agent chứa toàn bộ persona đã cài -2. Phân tích chủ đề của bạn để chọn ra 2-3 agent phù hợp nhất -3. Các agent lần lượt tham gia, có tương tác chéo và bất đồng tự nhiên -4. Luân phiên agent để đảm bảo góc nhìn đa dạng theo thời gian -5. Kết thúc bằng `goodbye`, `end party` hoặc `quit` - -**Đầu vào:** Chủ đề hoặc câu hỏi thảo luận, cùng thông tin về các persona bạn muốn tham gia nếu có - -**Đầu ra:** Cuộc hội thoại nhiều agent theo thời gian thực, vẫn giữ nguyên cá tính từng agent diff --git a/docs/vi-vn/reference/modules.md b/docs/vi-vn/reference/modules.md deleted file mode 100644 index 665c777f7b..0000000000 --- a/docs/vi-vn/reference/modules.md +++ /dev/null @@ -1,76 +0,0 @@ ---- -title: Các Module Chính Thức -description: Các module bổ sung để xây agent tùy chỉnh, tăng cường sáng tạo, phát triển game và kiểm thử -sidebar: - order: 5 ---- - -BMad được mở rộng thông qua các module chính thức mà bạn chọn trong quá trình cài đặt. Những module bổ sung này cung cấp agent, workflow và task chuyên biệt cho các lĩnh vực cụ thể, vượt ra ngoài phần lõi tích hợp sẵn và BMM (Agile suite). - -:::tip[Cài đặt module] -Chạy `npx bmad-method install` rồi chọn những module bạn muốn. Trình cài đặt sẽ tự xử lý phần tải về, cấu hình và tích hợp vào IDE. -::: - -## BMad Builder - -Tạo agent tùy chỉnh, workflow tùy chỉnh và module chuyên biệt theo lĩnh vực với sự hỗ trợ có hướng dẫn. BMad Builder là meta-module để mở rộng chính framework này. - -- **Mã:** `bmb` -- **npm:** [`bmad-builder`](https://www.npmjs.com/package/bmad-builder) -- **GitHub:** [bmad-code-org/bmad-builder](https://github.com/bmad-code-org/bmad-builder) - -**Cung cấp:** - -- Agent Builder — tạo AI agent chuyên biệt với chuyên môn và quyền truy cập công cụ tùy chỉnh -- Workflow Builder — thiết kế quy trình có cấu trúc với các bước và điểm quyết định -- Module Builder — đóng gói agent và workflow thành các module có thể chia sẻ và phát hành -- Thiết lập có tương tác bằng YAML cùng hỗ trợ publish lên npm - -## Creative Intelligence Suite - -Bộ công cụ vận hành bởi AI dành cho sáng tạo có cấu trúc, phát ý tưởng và đổi mới trong giai đoạn đầu phát triển. Bộ này cung cấp nhiều agent giúp brainstorming, design thinking và giải quyết vấn đề bằng các framework đã được kiểm chứng. - -- **Mã:** `cis` -- **npm:** [`bmad-creative-intelligence-suite`](https://www.npmjs.com/package/bmad-creative-intelligence-suite) -- **GitHub:** [bmad-code-org/bmad-module-creative-intelligence-suite](https://github.com/bmad-code-org/bmad-module-creative-intelligence-suite) - -**Cung cấp:** - -- Các agent Innovation Strategist, Design Thinking Coach và Brainstorming Coach -- Problem Solver và Creative Problem Solver cho tư duy hệ thống và tư duy bên lề -- Storyteller và Presentation Master cho kể chuyện và pitching -- Các framework phát ý tưởng như SCAMPER, Reverse Brainstorming và problem reframing - -## Game Dev Studio - -Các workflow phát triển game có cấu trúc, được điều chỉnh cho Unity, Unreal, Godot và các engine tùy chỉnh. Hỗ trợ độ sâu planning từ prototype nhanh đến sản xuất toàn diện; implementation hội tụ vào Build. - -- **Mã:** `gds` -- **npm:** [`bmad-game-dev-studio`](https://www.npmjs.com/package/bmad-game-dev-studio) -- **GitHub:** [bmad-code-org/bmad-module-game-dev-studio](https://github.com/bmad-code-org/bmad-module-game-dev-studio) - -**Cung cấp:** - -- Workflow tạo Game Design Document (GDD) -- Ngữ cảnh và planning game-specific cho implementation loop Build chuẩn -- Hỗ trợ thiết kế narrative cho nhân vật, hội thoại và world-building -- Bao phủ hơn 21 thể loại game cùng hướng dẫn kiến trúc theo engine - -## Test Architect (TEA) - -Chiến lược kiểm thử cấp doanh nghiệp, hướng dẫn tự động hóa và quyết định release gate thông qua một agent chuyên gia cùng chín workflow có cấu trúc. TEA vượt xa QA agent tích hợp sẵn nhờ ưu tiên theo rủi ro và truy vết yêu cầu. - -- **Mã:** `tea` -- **npm:** [`bmad-method-test-architecture-enterprise`](https://www.npmjs.com/package/bmad-method-test-architecture-enterprise) -- **GitHub:** [bmad-code-org/bmad-method-test-architecture-enterprise](https://github.com/bmad-code-org/bmad-method-test-architecture-enterprise) - -**Cung cấp:** - -- Agent Murat (Master Test Architect and Quality Advisor) -- Các workflow cho test design, ATDD, automation, test review và traceability -- Đánh giá NFR, thiết lập CI và dựng sườn framework kiểm thử -- Ưu tiên P0-P3 cùng tích hợp tùy chọn với Playwright Utils và MCP - -## Community Modules - -Các module cộng đồng và một chợ module đang được chuẩn bị. Hãy theo dõi [tổ chức BMad trên GitHub](https://github.com/bmad-code-org) để cập nhật. diff --git a/docs/vi-vn/reference/testing.md b/docs/vi-vn/reference/testing.md deleted file mode 100644 index 22b29d0308..0000000000 --- a/docs/vi-vn/reference/testing.md +++ /dev/null @@ -1,106 +0,0 @@ ---- -title: Các Tùy Chọn Kiểm Thử -description: So sánh workflow QA tích hợp sẵn với module Test Architect (TEA) cho tự động hóa kiểm thử. -sidebar: - order: 6 ---- - -BMad cung cấp hai hướng kiểm thử: workflow QA tích hợp sẵn để tạo test nhanh và module Test Architect có thể cài thêm cho chiến lược kiểm thử c��p doanh nghiệp. - -## Nên Dùng Cái Nào? - -| Yếu tố | QA tích hợp sẵn | Module TEA | -| --- | --- | --- | -| **Phù hợp nhất với** | Dự án nhỏ-trung bình, cần bao phủ nhanh | Dự án lớn, miền nghiệp vụ bị ràng buộc hoặc phức tạp | -| **Thiết lập** | Không cần cài thêm, đã có sẵn trong BMM | Cài riêng qua `npx bmad-method install` | -| **Cách tiếp cận** | Tạo test nhanh, lặp tinh chỉnh sau | Lập kế hoạch trước rồi mới tạo test có truy vết | -| **Loại test** | API và E2E | API, E2E, ATDD, NFR và nhiều loại khác | -| **Chiến lược** | Happy path + edge case quan trọng | Ưu tiên theo rủi ro (P0-P3) | -| **Số workflow** | 1 (Automate) | 9 (design, ATDD, automate, review, trace và các workflow khác) | - -:::tip[Bắt đầu với QA tích h��p sẵn] -Phần lớn dự án nên bắt đầu với workflow QA tích hợp sẵn. Nếu sau này bạn cần chiến lược kiểm thử, quality gate hoặc truy vết yêu cầu, hãy cài TEA song song. -::: - -## Workflow QA Tích Hợp Sẵn - -Workflow QA tích hợp sẵn (`bmad-qa-generate-e2e-tests`) nằm trong module BMM (Agile suite), khả dụng thông qua Developer agent. Nó tạo test chạy được rất nhanh bằng framework kiểm thử hiện có của dự án, không cần thêm cấu hình hay bước cài đặt bổ sung. - -**Trigger:** `QA` (thông qua Developer agent) hoặc `bmad-qa-generate-e2e-tests` - -### Workflow Làm Gì - -Workflow QA (Automate) gồm năm bước: - -1. **Phát hiện framework test** — quét `package.json` và các file test hiện có để nhận ra framework của bạn như Jest, Vitest, Playwright, Cypress hoặc bất kỳ runner tiêu chuẩn nào. Nếu chưa có gì, nó sẽ phân tích stack dự án và đề xuất một lựa chọn. -2. **Xác định tính năng** — hỏi cần kiểm thử phần nào hoặc tự khám phá các tính năng trong codebase. -3. **Tạo API tests** — bao phủ status code, cấu trúc phản hồi, happy path và 1-2 trường hợp lỗi. -4. **Tạo E2E tests** — bao phủ workflow người dùng bằng semantic locator và assertion trên kết quả nhìn thấy được. -5. **Chạy và xác minh** — thực thi test vừa tạo và sửa lỗi hỏng ngay lập tức. - -Workflow tạo một bản tóm tắt kiểm thử và lưu nó vào thư mục implementation artifacts của dự án. - -### Mẫu Kiểm Thử - -Các test được tạo theo triết lý “đơn giản và dễ bảo trì”: - -- **Chỉ dùng API chuẩn của framework** — không kéo thêm utility ngoài hay abstraction tùy chỉnh -- **Semantic locator** cho UI test — dùng role, label, text thay vì CSS selector -- **Test độc lập** — không phụ thuộc thứ tự chạy -- **Không hardcode wait hoặc sleep** -- **Mô tả rõ ràng** để test cũng đóng vai trò tài liệu tính năng - -:::note[Phạm vi] -Workflow QA chỉ tạo test. Nếu bạn cần code review hoặc xác nhận story, hãy dùng workflow Code Review (`CR`). -::: - -### Khi Nào Nên Dùng QA Tích Hợp S���n - -- Cần bao phủ test nhanh cho một tính năng mới hoặc hiện có -- Muốn tự động hóa kiểm thử thân thiện với người mới mà không cần thiết lập phức tạp -- Muốn các pattern test chuẩn mà lập trình viên nào cũng đọc và bảo trì được -- Dự án nhỏ-trung bình, nơi chiến lược kiểm thử toàn diện là không cần thiết - -## Module Test Architect (TEA) - -TEA là một module độc lập cung cấp agent chuyên gia Murat cùng chín workflow có cấu trúc cho kiểm thử cấp doanh nghiệp. Nó vượt ra ngoài việc tạo test để bao gồm chiến lược kiểm thử, lập kế hoạch theo rủi ro, quality gate và truy vết yêu cầu. - -- **Tài liệu:** [TEA Module Docs](https://bmad-code-org.github.io/bmad-method-test-architecture-enterprise/) -- **Cài đặt:** `npx bmad-method install` rồi chọn module TEA -- **npm:** [`bmad-method-test-architecture-enterprise`](https://www.npmjs.com/package/bmad-method-test-architecture-enterprise) - -### TEA Cung Cấp Gì - -| Workflow | Mục đích | -| --- | --- | -| Test Design | Tạo chiến lược kiểm thử toàn diện gắn với yêu cầu | -| ATDD | Phát triển hướng acceptance test với tiêu chí của stakeholder | -| Automate | Tạo test bằng pattern và utility nâng cao | -| Test Review | Kiểm tra chất lượng và độ bao phủ của test so với chiến lược | -| Traceability | Liên kết test ngược về yêu cầu để phục vụ audit và tuân thủ | -| NFR Assessment | Đánh giá các yêu cầu phi chức năng như hiệu năng, bảo mật | -| CI Setup | Cấu hình thực thi test trong pipeline tích hợp liên tục | -| Framework Scaffolding | Dựng hạ tầng và cấu trúc dự án kiểm thử | -| Release Gate | Ra quyết định phát hành go/no-go dựa trên dữ liệu | - -TEA cũng hỗ trợ ưu tiên theo rủi ro P0-P3 và tích hợp tùy chọn với Playwright Utils cùng công cụ MCP. - -### Khi Nào Nên Dùng TEA - -- Dự án cần truy vết yêu cầu hoặc tài liệu tuân thủ -- Đội ngũ cần ưu tiên kiểm thử theo rủi ro trên nhiều tính năng -- Môi trường doanh nghiệp có quality gate chính thức trước phát hành -- Miền nghiệp vụ phức tạp, nơi chiến lược kiểm thử phải được lên trước khi viết test -- Dự án đã vượt quá mô hình một workflow của QA tích hợp sẵn - -## Kiểm Thử Nằm Ở Đâu Trong Workflow - -Workflow QA Automate xuất hiện ở Phase 4 (Implementation) trong workflow map của BMad Method. Nó được thiết kế để chạy **sau khi hoàn tất trọn vẹn một epic** — tức là khi mọi story trong epic đó đã được triển khai và code review xong. Trình tự điển hình là: - -1. Với mỗi story trong epic: triển khai bằng Build (`BD` / `bmad-build`), sau đó thêm Code Review (`CR`) khi cần -2. Sau khi epic hoàn tất: tạo test bằng `QA` (thông qua Developer agent) hoặc workflow Automate của TEA -3. Chạy retrospective (`bmad-retrospective`) để ghi nhận bài học rút ra - -Workflow QA tích hợp sẵn làm việc trực tiếp từ source code mà không cần nạp tài liệu lập kế hoạch như PRD hay architecture. Các workflow của TEA có thể tích hợp với artifact lập kế hoạch ở các bước trước để phục vụ truy vết. - -Để hiểu rõ hơn kiểm thử nằm ở đâu trong quy trình tổng thể, xem [Workflow Map](./workflow-map.md). diff --git a/docs/vi-vn/reference/workflow-map.md b/docs/vi-vn/reference/workflow-map.md deleted file mode 100644 index bcce4a702b..0000000000 --- a/docs/vi-vn/reference/workflow-map.md +++ /dev/null @@ -1,83 +0,0 @@ ---- -title: "Sơ đồ workflow" -description: Tài liệu trực quan về các giai đoạn, quy trình và đầu ra của BMad Method -sidebar: - order: 1 ---- - -BMad Method (BMM) là một module trong hệ sinh thái BMad, tập trung vào các thực hành tốt nhất của kỹ nghệ ngữ cảnh và lập kế hoạch. AI agent hoạt động hiệu quả nhất khi có ngữ cảnh rõ ràng và có cấu trúc. Hệ thống BMM xây dựng ngữ cảnh đó theo tiến trình qua 4 giai đoạn riêng biệt. Mỗi giai đoạn, cùng với nhiều quy trình tùy chọn bên trong nó, tạo ra các tài liệu làm đầu vào cho giai đoạn kế tiếp, nhờ vậy agent luôn biết phải xây gì và vì sao. - -Lý do và các khái niệm nền tảng ở đây đến từ các phương pháp Agile đã được áp dụng rất thành công trong toàn ngành như một khung tư duy. - -Nếu có lúc nào bạn không chắc nên làm gì, skill `bmad-help` sẽ giúp bạn giữ đúng hướng hoặc biết bước tiếp theo. Bạn vẫn có thể dùng trang này để tham chiếu, nhưng `bmad-help` mang tính tương tác đầy đủ và nhanh hơn nhiều nếu bạn đã cài BMad Method. Ngoài ra, nếu bạn đang dùng thêm các module mở rộng BMad Method hoặc các module bổ sung khác, `bmad-help` cũng sẽ mở rộng theo để biết mọi thứ đang có sẵn và đưa ra lời khuyên tốt nhất tại thời điểm đó. - -Lưu ý quan trọng cuối cùng: mọi quy trình dưới đây đều có thể chạy trực tiếp bằng công cụ bạn chọn thông qua skill, hoặc bằng cách nạp agent trước rồi chọn mục tương ứng trong menu agent. - - - -

- Mở sơ đồ trong tab mới ↗ -

- -## Giai đoạn 1: Phân tích (tùy chọn) - -Khám phá không gian vấn đề và xác nhận ý tưởng trước khi cam kết đi vào lập kế hoạch. [**Tìm hiểu từng công cụ làm gì và nên dùng khi nào**](../explanation/analysis-phase.md). - -| Quy trình | Mục đích | Tạo ra | -| ------------------------------- | -------------------------------------------------------------------------- | ------------------------- | -| `bmad-brainstorming` | Động não ý tưởng dự án với sự điều phối của người dẫn dắt brainstorming | `brainstorming-report.md` | -| `bmad-deep-recon` | Xác thực giả định hoặc lựa chọn giữa các phương án — soạn prompt cho công cụ nghiên cứu chuyên sâu của bạn, xử lý báo cáo của nó, hoặc nghiên cứu ngay tại đây; thị trường, miền nghiệp vụ, kỹ thuật, cạnh tranh, tiếng nói người dùng, học thuật; đã kiểm chứng, có trích dẫn, có thể làm mới | Báo cáo hoặc bản tóm tắt nghiên cứu + bản tóm tắt HTML tùy chọn | -| `bmad-product-brief` | Ghi lại tầm nhìn chiến lược — phù hợp nhất khi concept của bạn đã rõ | `product-brief.md` | -| `bmad-prfaq` | Working Backwards — stress-test và rèn sắc concept sản phẩm của bạn | `prfaq-{project}.md` | - -## Giai đoạn 2: Lập kế hoạch - -Xác định cần xây gì và xây cho ai. - -| Quy trình | Mục đích | Tạo ra | -| --------------------------- | ---------------------------------------- | ------------ | -| `bmad-prd` | Xác định yêu cầu (FR/NFR) | `PRD.md` | -| `bmad-ux` | Thiết kế trải nghiệm người dùng khi UX là yếu tố quan trọng | `DESIGN.md`, `EXPERIENCE.md` | -| `bmad-spec` | Chưng cất mọi đầu vào ý định (brief, PRD, bản ghi, ghi chú) thành hợp đồng `SPEC.md` súc tích + các tệp đi kèm — chốt CÁI GÌ trước CÁCH LÀM | `SPEC.md` + tệp đi kèm trong `{output_folder}/specs/spec-{slug}/` | - -## Giai đoạn 3: Định hình giải pháp - -Quyết định cách xây và chia nhỏ công việc thành các story. - -| Quy trình | Mục đích | Tạo ra | -| ----------------------------------------- | ------------------------------------------ | --------------------------- | -| `bmad-architecture` | Làm rõ các quyết định kỹ thuật | `architecture.md` kèm ADR | -| `bmad-create-epics-and-stories` | Phân rã yêu cầu thành các phần việc có thể triển khai | Các file epic chứa các story | -| `bmad-sprint-planning` | Cổng kiểm tra mức độ sẵn sàng trước khi triển khai, sau đó theo dõi story và xem trạng thái sprint | PASS/CONCERNS/FAIL + `sprint-status.yaml` | - -## Giai đoạn 4: Triển khai - -Mọi đầu vào triển khai đều hội tụ vào `bmad-build`. Workflow này nhận ý định trực tiếp, issue, đặc tả hoặc story đã lập kế hoạch, rồi chọn mức làm rõ, lập kế hoạch, triển khai và review phù hợp. - -| Quy trình | Mục đích | Tạo ra | -| -------------------------- | ------------------------------------------------------------------------ | -------------------------------- | -| `bmad-build` | Biến ý định trực tiếp hoặc story đã lập kế hoạch thành mã nguồn đã triển khai và review | `spec-*.md` + mã nguồn | -| `bmad-code-review` | Kiểm tra chất lượng phần triển khai | Được duyệt hoặc yêu cầu thay đổi | -| `bmad-correct-course` | Xử lý thay đổi lớn giữa sprint | Kế hoạch cập nhật hoặc định tuyến lại | -| `bmad-retrospective` | Review sau khi hoàn tất epic | Bài học rút ra | - -### Đầu vào trực tiếp và đã lập kế hoạch - -Công việc rõ ràng có thể đi thẳng vào `bmad-build`. Sáng kiến lớn hơn có thể chuẩn bị PRD, UX, kiến trúc, epic, story, kiểm tra mức sẵn sàng và kế hoạch sprint trước. Các artifact này bổ sung ngữ cảnh, không chọn một workflow triển khai khác. - -## Quản lý ngữ cảnh - -Mỗi tài liệu sẽ trở thành ngữ cảnh cho giai đoạn tiếp theo. PRD cho architect biết những ràng buộc nào quan trọng. Tài liệu kiến trúc chỉ cho dev agent những mẫu cần tuân theo. File story cung cấp ngữ cảnh tập trung và đầy đủ cho việc triển khai. Nếu không có cấu trúc này, agent sẽ đưa ra quyết định thiếu nhất quán. - -### Bối cảnh dự án - -:::tip[Khuyến nghị] -Hãy tạo `project-context.md` để bảo đảm AI agent tuân theo quy tắc và sở thích của dự án. File này hoạt động như một bản hiến pháp cho dự án của bạn, nó dẫn dắt các quyết định triển khai xuyên suốt mọi quy trình. File tùy chọn này có thể được tạo ở cuối bước tạo kiến trúc, hoặc cũng có thể được sinh trong dự án hiện hữu để ghi lại những điều quan trọng cần giữ đồng bộ với quy ước đang có. -::: - -**Cách tạo:** - -- **Thủ công** — Tạo `_bmad-output/project-context.md` với stack công nghệ và các quy tắc triển khai của bạn -- **Tự sinh** — Chạy `bmad-generate-project-context` để sinh tự động từ architecture hoặc codebase - -[**Tìm hiểu thêm về project-context.md**](../explanation/project-context.md) diff --git a/docs/vi-vn/tutorials/getting-started.md b/docs/vi-vn/tutorials/getting-started.md deleted file mode 100644 index 192aa8fc2d..0000000000 --- a/docs/vi-vn/tutorials/getting-started.md +++ /dev/null @@ -1,276 +0,0 @@ ---- -title: "Bắt đầu" -description: Cài đặt BMad và xây dựng dự án đầu tiên của bạn ---- - -Xây dựng phần mềm nhanh hơn bằng các workflow vận hành bởi AI, với những agent chuyên biệt hướng dẫn bạn qua các bước lập kế hoạch, kiến trúc và triển khai. - -## Bạn Sẽ Học Được Gì - -- Cài đặt và khởi tạo BMad Method cho một dự án mới -- Dùng **BMad-Help** — trợ lý thông minh biết bước tiếp theo bạn nên làm gì -- Chọn độ sâu lập kế hoạch phù hợp với công việc -- Đi qua các phase từ yêu cầu đến code chạy được -- Sử dụng agent và workflow hiệu quả - -:::note[Điều kiện tiên quyết] -- **Node.js 20.12+** — Bắt buộc cho trình cài đặt -- **Git** — Khuyến nghị để quản lý phiên bản -- **IDE có AI** — Claude Code, Cursor hoặc công cụ tương tự -- **Một ý tưởng dự án** — Chỉ cần đơn giản cũng đủ để học -::: - -:::tip[Cách Dễ Nhất] -**Cài đặt** → `npx bmad-method install` -**Hỏi** → `bmad-help what should I do first?` -**Xây dựng** → Để BMad-Help dẫn bạn qua từng workflow -::: - -## Làm Quen Với BMad-Help: Người Dẫn Đường Thông Minh Của Bạn - -**BMad-Help là cách nhanh nhất để bắt đầu với BMad.** Bạn không cần phải nhớ workflow hay phase nào cả, chỉ cần hỏi, và BMad-Help sẽ: - -- **Kiểm tra dự án của bạn** để xem những gì đã hoàn thành -- **Hiển thị các lựa chọn** dựa trên những module bạn đã cài -- **Đề xuất bước tiếp theo** — bao gồm cả tác vụ bắt buộc đầu tiên -- **Trả lời câu hỏi** như “Tôi có ý tưởng cho một sản phẩm SaaS, tôi nên bắt đầu từ đâu?” - -### Cách Dùng BMad-Help - -Chạy trong AI IDE của bạn bằng cách gọi skill: - -```text -bmad-help -``` - -Hoặc ghép cùng câu hỏi để nhận hướng dẫn có ngữ cảnh: - -```text -bmad-help I have an idea for a SaaS product, I already know all the features I want. where do I get started? -``` - -BMad-Help sẽ trả lời: -- Điều gì được khuyến nghị trong tình huống của bạn -- Tác vụ bắt buộc đầu tiên là gì -- Phần còn lại của quy trình sẽ trông như thế nào - -### Nó Cũng Điều Khiển Workflow - -BMad-Help không chỉ trả lời câu hỏi — **nó còn tự động chạy ở cuối mỗi workflow** để cho bạn biết chính xác bước tiếp theo cần làm là gì. Không phải đoán, không phải lục tài liệu, chỉ có chỉ dẫn rõ ràng về workflow bắt buộc tiếp theo. - -:::tip[Bắt Đầu Từ Đây] -Sau khi cài BMad, hãy gọi skill `bmad-help` ngay. Nó sẽ nhận biết các module bạn đã cài và hướng bạn đến điểm bắt đầu phù hợp cho dự án. -::: - -## Hiểu Về BMad - -BMad giúp bạn xây dựng phần mềm thông qua các workflow có hướng dẫn với những AI agent chuyên biệt. Quy trình gồm bốn phase: - -| Phase | Tên | Điều xảy ra | -| ----- | -------------- | --------------------------------------------------- | -| 1 | Analysis | Brainstorming, nghiên cứu, product brief hoặc PRFAQ *(tùy chọn)* | -| 2 | Planning | Tạo tài liệu yêu cầu (PRD hoặc spec) | -| 3 | Solutioning | Thiết kế kiến trúc khi cần | -| 4 | Implementation | Triển khai mọi thay đổi hoặc story đã lập kế hoạch, có thể thông qua điều phối tự động | - -**[Mở Workflow Map](../reference/workflow-map.md)** để khám phá các phase, workflow và cách quản lý context. - -Độ sâu lập kế hoạch có thể thay đổi: - -| Độ sâu | Phù hợp nhất với | Ngữ cảnh trước triển khai | -| --- | --- | --- | -| **Trực tiếp** | Bản sửa, tính năng, issue hoặc spec đã rõ | Ý định, issue hoặc spec | -| **Lập kế hoạch sản phẩm** | Sản phẩm, nền tảng và tính năng phức tạp | PRD và UX tùy chọn | -| **Định hình giải pháp đầy đủ** | Sáng kiến phối hợp, rủi ro cao hoặc liên hệ thống | PRD, UX, kiến trúc, epic, story và kế hoạch sprint | - -:::note -Đây không phải các nhánh triển khai riêng. Mọi đầu vào đều hội tụ vào `bmad-build`; lập kế hoạch chỉ thay đổi lượng ngữ cảnh sẵn có. -::: - -## Cài Đặt - -Mở terminal trong thư mục dự án và chạy: - -```bash -npx bmad-method install -``` - -Nếu bạn muốn dùng bản prerelease mới nhất thay vì kênh release mặc định, hãy dùng `npx bmad-method@next install`. - -Khi được hỏi chọn module, hãy chọn **BMad Method**. - -Trình cài đặt sẽ tạo hai thư mục: -- `_bmad/` — agents, workflows, tasks và cấu hình -- `_bmad-output/` — hiện tại để trống, nhưng đây là nơi các artifact của bạn sẽ được lưu - -:::tip[Bước Tiếp Theo Của Bạn] -Mở AI IDE trong thư mục dự án rồi chạy: - -```text -bmad-help -``` - -BMad-Help sẽ nhận biết bạn đã làm đến đâu và đề xuất chính xác bước tiếp theo. Bạn cũng có thể hỏi những câu như “Tôi có những lựa chọn nào?” hoặc “Tôi có ý tưởng SaaS, nên bắt đầu từ đâu?” -::: - -:::note[Cách Nạp Agent Và Chạy Workflow] -Mỗi workflow có một **skill** được gọi bằng tên trong IDE của bạn, ví dụ `bmad-prd`. Công cụ AI sẽ nhận diện tên `bmad-*` và chạy nó, bạn không cần nạp agent riêng. Bạn cũng có thể gọi trực tiếp skill của agent để trò chuyện tổng quát, ví dụ `bmad-agent-pm` cho PM agent. -::: - -:::caution[Chat Mới] -Luôn bắt đầu một chat mới cho mỗi workflow. Điều này tránh các vấn đề do giới hạn context gây ra. -::: - -## Bước 1: Chọn Độ Sâu Lập Kế Hoạch - -Chỉ dùng những phần cần thiết trong phase 1-3. Với công việc rõ ràng, có phạm vi hữu hạn, bạn có thể đi thẳng đến [Bước 2](#bước-2-xây-dựng-dự-án). **Dùng chat mới cho từng workflow.** - -:::tip[Project Context (Tùy chọn)] -Trước khi bắt đầu, hãy cân nhắc tạo `project-context.md` để ghi lại các ưu tiên kỹ thuật và quy tắc triển khai. Nhờ vậy mọi AI agent sẽ tuân theo cùng một quy ước trong suốt dự án. - -Bạn có thể tạo thủ công tại `_bmad-output/project-context.md` hoặc sinh ra sau phần kiến trúc bằng `bmad-generate-project-context`. [Xem thêm](../explanation/project-context.md). -::: - -### Phase 1: Analysis (Tùy chọn) - -Tất cả workflow trong phase này đều là tùy chọn. [**Chưa chắc nên dùng cái nào?**](../explanation/analysis-phase.md) -- **brainstorming** (`bmad-brainstorming`) — Gợi ý ý tưởng có hướng dẫn -- **research** (`bmad-deep-recon`) — Soạn prompt nghiên cứu chuyên sâu cho công cụ AI của riêng bạn, xử lý báo cáo hoàn chỉnh thành bản tóm tắt sẵn sàng cho các bước sau, hoặc thực hiện nghiên cứu ngay tại đây — thị trường, miền nghiệp vụ, kỹ thuật, cạnh tranh, tiếng nói người dùng và học thuật — kèm kiểm chứng luận điểm và vòng đời làm mới -- **product-brief** (`bmad-product-brief`) — Tài liệu nền tảng được khuyến nghị khi concept của bạn đã rõ -- **prfaq** (`bmad-prfaq`) — Bài kiểm tra Working Backwards để stress-test và rèn sắc concept sản phẩm của bạn - -### Phase 2: Planning (Khi cần) - -Với công việc cần lập kế hoạch sản phẩm: -1. Gọi **PM agent** (`bmad-agent-pm`) trong một chat mới -2. Chạy workflow `bmad-prd` (`bmad-prd`) -3. Kết quả: `PRD.md` - -:::note[Thiết kế UX (Tùy chọn)] -Nếu dự án của bạn có giao diện người dùng, hãy gọi **UX-Designer agent** (`bmad-agent-ux-designer`) và chạy workflow thiết kế UX (`bmad-ux`) sau khi tạo PRD. -::: - -### Phase 3: Solutioning (Khi cần) - -**Tạo Architecture** -1. Gọi **Architect agent** (`bmad-agent-architect`) trong một chat mới -2. Chạy `bmad-architecture` (`bmad-architecture`) -3. Kết quả: tài liệu kiến trúc chứa các quyết định kỹ thuật - -**Tạo Epics và Stories** - -:::tip[Cải tiến trong V6] -Epics và stories giờ được tạo *sau* kiến trúc. Điều này giúp story có chất lượng tốt hơn vì các quyết định kiến trúc như database, API pattern và tech stack ảnh hưởng trực tiếp đến cách chia nhỏ công việc. -::: - -1. Gọi **PM agent** (`bmad-agent-pm`) trong một chat mới -2. Chạy `bmad-create-epics-and-stories` (`bmad-create-epics-and-stories`) -3. Workflow sẽ dùng cả PRD lẫn Architecture để tạo story có đủ ngữ cảnh kỹ thuật - -**Kiểm tra mức sẵn sàng để triển khai** *(Rất nên dùng)* -1. Gọi **Architect agent** (`bmad-agent-architect`) trong một chat mới -2. Chạy `bmad-sprint-planning` (`bmad-sprint-planning`) — mở đầu bằng cổng kiểm tra mức sẵn sàng -3. Xác nhận tính nhất quán giữa toàn bộ tài liệu lập kế hoạch - -## Bước 2: Xây Dựng Dự Án - -Chuyển sang implementation với ngữ cảnh đang có: yêu cầu trực tiếp, issue, spec hoặc story đã được lập kế hoạch đầy đủ. **Mỗi workflow nên chạy trong một chat mới.** - -Với công việc đã lập kế hoạch, chạy `bmad-build` và nêu rõ story hoặc hạng mục sprint đã chọn, ví dụ: `Triển khai story 2.3 từ _bmad-output/planning-artifacts/epics.md`. - -### Khởi Tạo Sprint Planning (Cho công việc đã lập kế hoạch) - -Gọi **Developer agent** (`bmad-agent-dev`) và chạy `bmad-sprint-planning` (`bmad-sprint-planning`). Workflow này sẽ tạo `sprint-status.yaml` để theo dõi toàn bộ epic và story. - -Khi Build nhận diện được story đã chọn trong file này, workflow chuyển story sang `in-progress` trong lúc triển khai và sang `review` khi triển khai hoàn tất. - -### Chu Trình Xây Dựng - -Với mỗi thay đổi trực tiếp hoặc story đã lập kế hoạch, lặp lại chu trình này trong chat mới: - -| Bước | Agent | Workflow | Lệnh | Mục đích | -| ---- | ----- | -------------- | -------------------------- | ---------------------------------- | -| 1 | DEV | `bmad-build` | `bmad-build` | Làm rõ, lập kế hoạch, triển khai, review và trình bày | -| 2 | DEV | `bmad-code-review` | `bmad-code-review` | Kiểm tra chất lượng bổ sung *(khuyến nghị)* | - -Review của Build là một phần của mọi lần chạy. `bmad-code-review` là lớp xác thực độc lập, tùy chọn trong một ngữ cảnh mới. - -Sau khi hoàn tất tất cả story trong một epic, hãy gọi **Developer agent** (`bmad-agent-dev`) và chạy `bmad-retrospective` (`bmad-retrospective`). - -## Bạn Đã Hoàn Thành Những Gì - -Bạn đã nắm được nền tảng để xây dựng với BMad: - -- Đã cài BMad và cấu hình cho IDE của bạn -- Đã chọn độ sâu lập kế hoạch phù hợp với công việc -- Đã tạo các tài liệu lập kế hoạch (PRD, Architecture, Epics và Stories) -- Đã hiểu chu trình triển khai trong implementation - -Dự án của bạn bây giờ sẽ có dạng: - -```text -your-project/ -├── _bmad/ # Cấu hình BMad -├── _bmad-output/ -│ ├── planning-artifacts/ -│ │ ├── PRD.md # Tài liệu yêu cầu của bạn -│ │ ├── architecture.md # Các quyết định kỹ thuật -│ │ └── epics/ # Các file epic và story -│ ├── implementation-artifacts/ -│ │ └── sprint-status.yaml # Theo dõi sprint -│ └── project-context.md # Quy tắc triển khai (tùy chọn) -└── ... -``` - -## Tra Cứu Nhanh - -| Workflow | Lệnh | Agent | Mục đích | -| ------------------------------------- | ------------------------------------------ | --------- | ----------------------------------------------- | -| **`bmad-help`** ⭐ | `bmad-help` | Bất kỳ | **Người dẫn đường thông minh của bạn — hỏi gì cũng được!** | -| `bmad-prd` | `bmad-prd` | PM | Tạo tài liệu yêu cầu sản phẩm | -| `bmad-architecture` | `bmad-architecture` | Architect | Tạo tài liệu kiến trúc | -| `bmad-generate-project-context` | `bmad-generate-project-context` | Analyst | Tạo file project context | -| `bmad-create-epics-and-stories` | `bmad-create-epics-and-stories` | PM | Phân rã PRD thành epics | -| `bmad-sprint-planning` | `bmad-sprint-planning` | DEV | Cổng sẵn sàng + khởi tạo theo dõi sprint + xem trạng thái | -| `bmad-build` | `bmad-build` | DEV | Triển khai ý định, issue, tính năng, bản sửa hoặc story | -| `bmad-code-review` | `bmad-code-review` | DEV | Review phần code đã triển khai | - -## Câu Hỏi Thường Gặp - -**Lúc nào cũng cần kiến trúc à?** -Không. Dùng kiến trúc khi cần làm rõ quyết định kỹ thuật hoặc ràng buộc liên hệ thống. Công việc rõ ràng có thể đi thẳng vào `bmad-build`; sáng kiến lớn đưa các artifact lập kế hoạch vào cùng workflow đó. - -**Tôi có thể đổi kế hoạch về sau không?** -Có. Workflow `bmad-correct-course` (`bmad-correct-course`) xử lý thay đổi phạm vi giữa chừng. - -**Nếu tôi muốn brainstorming trước thì sao?** -Gọi Analyst agent (`bmad-agent-analyst`) và chạy `bmad-brainstorming` (`bmad-brainstorming`) trước khi bắt đầu PRD. - -**Tôi có cần tuân theo đúng thứ tự tuyệt đối không?** -Không hẳn. Khi đã quen flow, bạn có thể chạy workflow trực tiếp bằng bảng Tra Cứu Nhanh ở trên. - -## Nhận Hỗ Trợ - -:::tip[Điểm Dừng Đầu Tiên: BMad-Help] -**Hãy gọi `bmad-help` bất cứ lúc nào** — đây là cách nhanh nhất để gỡ vướng. Bạn có thể hỏi: -- "Tôi nên làm gì sau khi cài đặt?" -- "Tôi đang kẹt ở workflow X" -- "Tôi có những lựa chọn nào cho Y?" -- "Cho tôi xem đến giờ đã làm được gì" - -BMad-Help sẽ kiểm tra dự án, phát hiện những gì bạn đã hoàn thành và chỉ cho bạn chính xác bước cần làm tiếp theo. -::: - -- **Trong workflow** — Các agent sẽ hướng dẫn bạn bằng câu hỏi và giải thích -- **Cộng đồng** — [Discord](https://discord.gg/gk8jAdXWmj) (#bmad-method-help, #report-bugs-and-issues) - -## Những Điểm Cần Ghi Nhớ - -:::tip[Hãy Nhớ Các Điểm Này] -- **Bắt đầu với `bmad-help`** — Trợ lý thông minh hiểu dự án và các lựa chọn của bạn -- **Luôn dùng chat mới** — Mỗi workflow nên bắt đầu trong một chat riêng -- **Độ sâu lập kế hoạch thay đổi** — ý định trực tiếp và story đã lập kế hoạch đều đi vào `bmad-build` -- **BMad-Help chạy tự động** — Mỗi workflow đều kết thúc bằng hướng dẫn về bước tiếp theo -::: - -Sẵn sàng bắt đầu chưa? Hãy cài BMad, gọi `bmad-help`, và để người dẫn đường thông minh của bạn đưa bạn đi tiếp. diff --git a/docs/zh-cn/404.md b/docs/zh-cn/404.md deleted file mode 100644 index d8d1bb9e9a..0000000000 --- a/docs/zh-cn/404.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -title: 页面未找到 -template: splash ---- - - -你访问的页面不存在，或已被移动。 - -[返回中文首页](./index.md) diff --git a/docs/zh-cn/_STYLE_GUIDE.md b/docs/zh-cn/_STYLE_GUIDE.md deleted file mode 100644 index 74c3159107..0000000000 --- a/docs/zh-cn/_STYLE_GUIDE.md +++ /dev/null @@ -1,371 +0,0 @@ ---- -title: "Documentation Style Guide" -description: 基于 Google 文档风格与 Diataxis 的项目文档规范 ---- - -本项目遵循 [Google Developer Documentation Style Guide](https://developers.google.com/style)，并使用 [Diataxis](https://diataxis.fr/) 组织文档。以下仅补充项目级约束。 - -## 项目特定规则 - -| 规则 | 规范 | -| --- | --- | -| 禁用水平分割线（`---`） | 会打断阅读流 | -| 禁用 `####` 标题 | 用加粗短句或 admonition 替代 | -| 避免 “Related/Next” 章节 | 交给侧边栏导航 | -| 避免深层嵌套列表 | 拆成新段落或新小节 | -| 非代码内容不要放代码块 | 对话/提示用 admonition | -| 不用整段粗体做提醒 | 统一用 admonition | -| 每节 1-2 个 admonition | 教程大节可放宽到 3-4 个 | -| 表格单元格/列表项 | 控制在 1-2 句 | -| 标题预算 | 每篇约 8-12 个 `##`，每节 2-3 个 `###` | - -## 提示块（Starlight 语法） - -```md -:::tip[Title] -Shortcuts, best practices -::: - -:::note[Title] -Context, definitions, examples, prerequisites -::: - -:::caution[Title] -Caveats, potential issues -::: - -:::danger[Title] -Critical warnings only — data loss, security issues -::: -``` - -### 标准用途 - -| 提示块 | 适用场景 | -| --- | --- | -| `:::note[Prerequisites]` | 开始前依赖与前置条件 | -| `:::tip[Quick Path]` | 文档顶部 TL;DR | -| `:::caution[Important]` | 关键风险提醒 | -| `:::note[Example]` | 命令/响应示例说明 | - -## 标准表格模板 - -**阶段（Phases）：** - -```md -| Phase | Name | What Happens | -| ----- | -------- | -------------------------------------------- | -| 1 | Analysis | Brainstorm, research *(optional)* | -| 2 | Planning | Requirements — PRD or spec *(required)* | -``` - -**技能（Skills）：** - -```md -| Skill | Agent | Purpose | -| -------------------- | ------- | ------------------------------------ | -| `bmad-brainstorming` | Analyst | Brainstorm a new project | -| `bmad-prd` | PM | Create Product Requirements Document | -``` - -## 文件结构块（Folder Structure） - -用于 “What You've Accomplished” 类章节： - -````md -``` -your-project/ -├── _bmad/ # BMad configuration -├── _bmad-output/ -│ ├── planning-artifacts/ -│ │ └── PRD.md # Your requirements document -│ ├── implementation-artifacts/ -│ └── project-context.md # Implementation rules (optional) -└── ... -``` -```` - -## 教程（Tutorial）结构 - -```text -1. Title + Hook（1-2 句结果导向开场） -2. Version/Module Notice（可选，信息或警告提示块） -3. What You'll Learn（结果清单） -4. Prerequisites（前置条件提示块） -5. Quick Path（TL;DR 提示块） -6. Understanding [Topic]（步骤前的背景说明，可配表格） -7. Installation（可选） -8. Step 1: [First Major Task] -9. Step 2: [Second Major Task] -10. Step 3: [Third Major Task] -11. What You've Accomplished（总结 + 文件结构） -12. Quick Reference（skills 表） -13. Common Questions（FAQ） -14. Getting Help（社区入口） -15. Key Takeaways（末尾 tip 提示块） -``` - -### 教程检查清单 - -- [ ] Hook 用 1-2 句明确结果 -- [ ] 包含 “What You'll Learn” -- [ ] 前置条件放在 admonition -- [ ] 顶部有 Quick Path TL;DR -- [ ] 关键信息用 phases/skills/agents 表格 -- [ ] 包含 “What You've Accomplished” -- [ ] 包含 Quick Reference 表 -- [ ] 包含 Common Questions -- [ ] 包含 Getting Help -- [ ] 末尾包含 Key Takeaways 提示块 - -## How-to 结构 - -```text -1. Title + Hook（单句，形如 "Use the `X` workflow to..."） -2. When to Use This（3-5 条场景） -3. When to Skip This（可选） -4. Prerequisites（note 提示块） -5. Steps（编号 `###` 动词开头） -6. What You Get（产出物说明） -7. Example（可选） -8. Tips（可选） -9. Next Steps（可选） -``` - -### How-to 检查清单 - -- [ ] Hook 以 “Use the `X` workflow to...” 开头 -- [ ] “When to Use This” 有 3-5 条场景 -- [ ] 明确前置条件 -- [ ] 步骤为编号 `###` 子标题且动词开头 -- [ ] “What You Get” 明确产出物 - -## Explanation 结构 - -### 类型 - -| 类型 | 示例 | -| --- | --- | -| **Index/Landing** | `core-concepts/index.md` | -| **Concept** | `what-are-agents.md` | -| **Feature** | `build.md` | -| **Philosophy** | `why-solutioning-matters.md` | -| **FAQ** | `established-projects-faq.md` | - -### 通用模板 - -```text -1. Title + Hook（1-2 句） -2. Overview/Definition（是什么，为什么重要） -3. Key Concepts（`###` 小节） -4. Comparison Table（可选） -5. When to Use / When Not to Use（可选） -6. Diagram（可选，单文档最多 1 个 mermaid） -7. Next Steps（可选） -``` - -### Index/Landing 页面 - -```text -1. Title + Hook（单句） -2. Content Table（链接 + 描述） -3. Getting Started（编号步骤） -4. Choose Your Path（可选，决策树） -``` - -### 概念解释页（Concept） - -```text -1. Title + Hook（定义性开场） -2. Types/Categories（可选，`###`） -3. Key Differences Table -4. Components/Parts -5. Which Should You Use? -6. Creating/Customizing（指向 how-to） -``` - -### 功能解释页（Feature） - -```text -1. Title + Hook（功能作用） -2. Quick Facts（可选） -3. When to Use / When Not to Use -4. How It Works（可选 mermaid） -5. Key Benefits -6. Comparison Table（可选） -7. When to Graduate/Upgrade（可选） -``` - -### 原理/哲学页（Philosophy） - -```text -1. Title + Hook（核心原则） -2. The Problem -3. The Solution -4. Key Principles（`###`） -5. Benefits -6. When This Applies -``` - -### Explanation 检查清单 - -- [ ] Hook 清楚说明“本文解释什么” -- [ ] 内容分布在可扫读的 `##` 区块 -- [ ] 3 个以上选项时使用对比表 -- [ ] 图示有清晰标签 -- [ ] 程序性问题链接到 how-to -- [ ] 每篇控制在 2-3 个 admonition - -## Reference 结构 - -### 类型 - -| 类型 | 示例 | -| --- | --- | -| **Index/Landing** | `workflows/index.md` | -| **Catalog** | `agents/index.md` | -| **Deep-Dive** | `document-project.md` | -| **Configuration** | `core-tasks.md` | -| **Glossary** | `glossary/index.md` | -| **Comprehensive** | `bmgd-workflows.md` | - -### Reference 索引页 - -```text -1. Title + Hook（单句） -2. Content Sections（每类一个 `##`） - - 链接 + 简短描述 -``` - -### Catalog 参考页 - -```text -1. Title + Hook -2. Items（每项一个 `##`） - - 单句说明 - - **Skills:** 或 **Key Info:** 平铺列表 -3. Universal/Shared（可选） -``` - -### Deep-Dive 参考页 - -```text -1. Title + Hook（单句说明用途） -2. Quick Facts（可选 note 提示块） - - Module, Skill, Input, Output -3. Purpose/Overview（`##`） -4. How to Invoke（代码块） -5. Key Sections（每个方面一个 `##`） - - 子选项使用 `###` -6. Notes/Caveats（tip/caution） -``` - -### Configuration 参考页 - -```text -1. Title + Hook -2. Table of Contents（可选，4 项以上建议） -3. Items（每项一个 `##`） - - **Bold summary**（单句） - - **Use it when:** 场景列表 - - **How it works:** 3-5 步 - - **Output:**（可选） -``` - -### 综合参考页（Comprehensive） - -```text -1. Title + Hook -2. Overview（`##`） - - 用图或表解释组织方式 -3. Major Sections（每个阶段/类别一个 `##`） - - Items（每项 `###`） - - 统一字段：Skill, Agent, Input, Output, Description -4. Next Steps（可选） -``` - -### Reference 检查清单 - -- [ ] Hook 说明“本文引用什么” -- [ ] 结构匹配参考页类型 -- [ ] 条目结构前后一致 -- [ ] 结构化信息优先表格表达 -- [ ] 概念深度指向 explanation 页面 -- [ ] 每篇 1-2 个 admonition - -## Glossary 结构 - -Starlight 右侧 “On this page” 来自标题层级： - -- 分类使用 `##`（会进入右侧导航） -- 术语放在表格行中（不要给每个术语单独标题） -- 不要再写内联 TOC - -### 表格模板 - -```md -## Category Name - -| Term | Definition | -| ------------ | ---------------------------------------------------------------------------------------- | -| **Agent** | Specialized AI persona with specific expertise that guides users through workflows. | -| **Workflow** | Multi-step guided process that orchestrates AI agent activities to produce deliverables. | -``` - -### 定义规则 - -| 推荐 | 避免 | -| --- | --- | -| 直接写“它是什么/做什么” | 以 “This is...” 或 “A [term] is...” 开头 | -| 控制在 1-2 句 | 多段长解释 | -| 术语名称加粗 | 术语用普通文本 | - -### 语境标记（Context Markers） - -在定义开头用斜体标记适用范围： - -- `*Direct-entry implementation only.*` -- `*BMad Method/Enterprise.*` -- `*Phase N.*` -- `*BMGD.*` -- `*Established projects.*` - -### Glossary 检查清单 - -- [ ] 术语以表格维护，不用独立标题 -- [ ] 同分类内按字母序排序 -- [ ] 定义控制在 1-2 句 -- [ ] 语境标记使用斜体 -- [ ] 术语名称在单元格中加粗 -- [ ] 避免 “A [term] is...” 句式 - -## FAQ 章节模板 - -```md -## Questions - -- [Do I always need architecture?](#do-i-always-need-architecture) -- [Can I change my plan later?](#can-i-change-my-plan-later) - -### Do I always need architecture? - -Only for work that benefits from architecture. Clear work can enter implementation directly. - -### Can I change my plan later? - -Yes. The `bmad-correct-course` workflow handles scope changes mid-implementation. - -**Have a question not answered here?** [Open an issue](...) or ask in [Discord](...). -``` - -## 校验命令 - -提交文档改动前，建议执行： - -```bash -cd docs-site -npm run fix-links # 预览链接修复结果 -npm run fix-links -- --write # 写回链接修复 -npm run validate-links # 校验链接是否存在 -npm run build # 校验站点构建 -``` diff --git a/docs/zh-cn/build/walk-through-a-change.md b/docs/zh-cn/build/walk-through-a-change.md deleted file mode 100644 index 215185e0a3..0000000000 --- a/docs/zh-cn/build/walk-through-a-change.md +++ /dev/null @@ -1,92 +0,0 @@ ---- -title: "走查一个变更" -description: LLM 辅助的人机协作审查，引导你从目的到细节逐步走过一个变更 -sidebar: - order: 1 ---- - -`bmad-walkthrough` 是一个交互式的、LLM 辅助的人机协作审查工作流。它带你逐步走过一个代码变更——从目的和上下文到细节——让你能做出知情决策：是发布、返工，还是深入挖掘。 - -![Walkthrough 工作流图](/diagrams/walkthrough-run.svg) - -## 典型流程 - -你运行 `bmad-build`。它澄清你的意图、构建规范、实现变更，完成后将审查线索追加到 spec 文件并在编辑器中打开。你查看 spec，发现这次变更涉及跨多个模块的 20 个文件。 - -你可以肉眼扫一遍 diff。但 20 个文件正是肉眼审查开始失效的临界点——你会丢失线索，漏掉两个相距甚远的变更之间的关联，或者批准了自己没有完全理解的东西。所以你改为说 "walkthrough"，让 LLM 带你走一遍。 - -这种交接——从自主实现回到人工判断——就是核心使用场景。Build 以最少的监督长时间运行，Walkthrough 则是你重新掌舵的地方。 - -## 为什么需要它 - -代码审查有两种失败模式。一种是审查者浏览 diff，什么也没发现，直接批准。另一种是逐文件仔细阅读，但丢失了全局线索——见树不见林。两种模式的结果相同：审查没有抓住真正重要的东西。 - -根本问题在于顺序。原始 diff 按文件顺序呈现变更，而这几乎从来不是构建理解的顺序。你先看到一个辅助函数，却不知道它存在的原因；先看到一个 schema 变更，却不了解它支撑什么功能。审查者必须从零散的线索中重建作者的意图，而这个重建过程正是注意力失效的地方。 - -Walkthrough 通过让 LLM 完成重建工作来解决这个问题。它读取 diff、spec（如果有的话）和周围的代码库，然后按照有利于理解的顺序——而不是 `git diff` 的顺序——呈现变更。 - -## 工作原理 - -工作流分为五个步骤。每一步都建立在前一步的基础上，逐步从"这是什么？"过渡到"我们该不该发布？" - -### 1. 定向 - -工作流识别变更来源（来自 PR、commit、分支、spec 文件或当前 git 状态），生成一行意图摘要以及表面积统计：变更文件数、涉及模块数、逻辑行数、边界穿越数和新增公共接口数。 - -这是"这是不是我以为的那个东西？"的时刻。在阅读任何代码之前，审查者确认自己看的是正确的东西，并对范围建立预期。 - -### 2. 走查 - -变更按**关注点**——而非按文件——组织。关注点是内聚的设计意图，例如"输入验证"或"API 契约"。每个关注点附带简短说明——*为什么选择这种方案*，然后列出可点击的 `path:line` 停靠点，审查者可以沿着这些停靠点在代码中导航。 - -这是设计判断步骤。审查者评估的是方案对系统是否合理，而不是代码是否正确。关注点按自顶向下排列：最高层意图在前，支撑实现在后。审查者永远不会遇到引用了自己尚未看过的内容。 - -### 3. 细节审视 - -在审查者理解了设计之后，工作流浮出 2-5 个"出错代价最高"的位置。这些位置按风险类别标记——`[auth]`、`[schema]`、`[billing]`、`[public API]`、`[security]` 等——并按出错后的影响范围排序。 - -这不是找 bug。自动化测试和 CI 负责正确性。细节审视激活的是风险意识："这些是出错成本最高的地方。"如果审查者想在某个领域深入，可以说 "dig into [area]" 来触发一次聚焦正确性的重新审查。 - -如果 spec 经过了对抗性审查循环（机器硬化），那些发现也会在这里浮出——不是已修复的 bug，而是审查循环标记出的、审查者应当知晓的决策。 - -### 4. 测试 - -建议 2-5 种手动观察变更生效的方式。不是自动化测试命令——而是能构建信心、但测试套件无法提供的手动观察。一个可以尝试的 UI 交互、一条可以运行的 CLI 命令、一个可以发送的 API 请求，以及每项的预期结果。 - -如果变更没有用户可见的行为，它会明确说明。不发明多余的忙活。 - -### 5. 总结 - -审查者做出决定：批准、返工或继续讨论。如果批准 PR，工作流可以协助执行 `gh pr review --approve`。如果需要返工，它帮助诊断问题出在方案、spec 还是实现，并帮助起草与具体代码位置关联的可操作反馈。 - -## 它是对话，不是报告 - -工作流将每一步呈现为起点，而非定论。在步骤之间——或步骤中间——你可以与 LLM 对话、提问、挑战它的框架，或调用其他技能来获取不同视角： - -- **"run advanced elicitation on the error handling"** — 推动 LLM 重新思考并细化对特定领域的分析 -- **"party mode on whether this schema migration is safe"** — 引入多个 agent 视角进行聚焦辩论 -- **"run code review"** — 生成包含对抗性和边界场景分析的结构化 agentic 审查报告 - -Walkthrough 工作流不会把你锁在线性路径上。它在你需要结构时提供结构，在你想探索时让开。五个步骤确保你看到全貌，但每一步深入到什么程度——以及调用什么工具——完全由你决定。 - -## 审查线索 - -走查步骤在有**建议审查顺序**时效果最好——这是 spec 作者编写的停靠点列表，用于引导审查者走过变更。当 spec 包含此内容时，工作流直接使用它。 - -当没有作者提供的线索时，工作流会从 diff 和代码库上下文生成一份。生成的线索质量不如作者编写的，但远好于按文件顺序阅读变更。 - -## 何时使用 - -主要场景是 `bmad-build` 的交接：实现完成，spec 文件在编辑器中打开并追加了审查线索，你需要决定是否发布。说 "walkthrough" 即可开始。 - -它也可以独立使用： - -- **审查 PR** — 尤其是涉及多个文件或跨模块变更的 PR -- **了解一个变更** — 当你需要理解一个不是你写的分支上发生了什么 -- **Sprint 审查** — 工作流可以提取 sprint 状态文件中标记为 `review` 的 story - -通过说 "walkthrough" 或 "walk me through this change" 来调用。它在任何终端中都能工作，但在 IDE 中——VS Code、Cursor 或类似工具——你会获得更多，因为工作流在每一步都生成 `path:line` 引用。在嵌入 IDE 的终端中，这些引用是可点击的，你可以沿着审查线索在文件间跳转。 - -## 它不是什么 - -Walkthrough 不是自动化审查的替代品。它不运行 linter、类型检查器或测试套件。它不打分也不给出通过/不通过的判定。它是一份阅读指南，帮助人类在最重要的地方运用自己的判断力。 diff --git a/docs/zh-cn/explanation/advanced-elicitation.md b/docs/zh-cn/explanation/advanced-elicitation.md deleted file mode 100644 index 20ec946144..0000000000 --- a/docs/zh-cn/explanation/advanced-elicitation.md +++ /dev/null @@ -1,58 +0,0 @@ ---- -title: "高级启发" -description: 使用结构化推理方法推动 LLM 重新思考其工作 -sidebar: - order: 4 ---- - -高级启发（advanced elicitation）是“第二轮思考”机制：不是笼统地让模型“再来一次”，而是让它按指定推理方法重审自己的输出。 - -## 它是什么 - -你先有一版输出（方案、文案、分析或规范），再通过某种推理框架做二次审视，例如： -- 事前复盘（Pre-mortem） -- 第一性原理 -- 逆向思维（Inversion） -- 红队/蓝队 -- 苏格拉底式追问 - -这种“带方法名的重审”通常比“再优化一下”更有效，因为它会强制模型从特定角度进攻已有答案。 - -## 什么时候使用 - -- 你已有可用初稿，但怀疑还不够扎实 -- 你想压力测试关键假设或找潜在漏洞 -- 你面对高风险内容，需要更高置信度 -- 你想要替代解法，而不是同义改写 - -## 它如何运行 - -1. 模型先给出若干与你内容相关的方法候选 -2. 你选择一种（或重抽） -3. 模型按该方法重审并展示改进 -4. 你决定采纳、丢弃、继续下一轮或结束 - -:::tip[实战建议] -做规格、方案或计划时，先跑一次“事前复盘”通常收益最高，容易提前暴露隐藏风险。 -::: - -如果你还处在方向发散阶段，可先用 [头脑风暴](./brainstorming.md)；如果你需要多角色权衡讨论，可用 [派对模式](./party-mode.md)。 - -## 与相近模式的区别 - -| 模式 | 核心目标 | 典型输入 | 典型输出 | -| ----- | ----- | ----- | ----- | -| `advanced elicitation` | 二次推理与补强 | 已有初稿/方案 | 风险更清晰、论证更完整的改进版 | -| `bmad-brainstorming` | 发散创意并收敛 | 目标模糊或方向开放 | 想法池与行动方向 | -| `bmad-party-mode` | 多角色讨论权衡 | 需要跨角色协同判断 | 多视角共识或争议点 | - -## 使用边界 - -- 它不能替代原始输入质量：初稿太空，二次推理也会受限 -- 它会产出更多“可疑问题”，需要你做人工判别 -- 连续多轮会出现收益递减，建议在关键决策点使用 - -## 继续阅读 - -- [头脑风暴](./brainstorming.md) -- [派对模式](./party-mode.md) diff --git a/docs/zh-cn/explanation/analysis-phase.md b/docs/zh-cn/explanation/analysis-phase.md deleted file mode 100644 index 395053a701..0000000000 --- a/docs/zh-cn/explanation/analysis-phase.md +++ /dev/null @@ -1,70 +0,0 @@ ---- -title: "分析阶段：从想法到基础" -description: 头脑风暴、调研、产品简报和 PRFAQ 分别是什么——以及何时使用 -sidebar: - order: 2 ---- - -分析阶段（Phase 1）帮助你在决定动手构建之前，把产品想清楚。这个阶段的每个工具都是可选的，但如果完全跳过分析，你的 PRD 就是建立在假设而非洞察之上。 - -## 为什么先分析再规划？ - -PRD 回答的是"我们应该构建什么、为什么？"如果输入的是模糊的思考，得到的就是模糊的 PRD——而下游的每一份文档都会继承这种模糊。基于薄弱 PRD 搭建的架构会押错技术方向；从薄弱架构派生的 story 会遗漏边界场景。代价是层层叠加的。 - -分析工具的作用就是让你的 PRD 变得锐利。它们从不同角度攻击问题——创意探索、市场现实、客户画像、可行性——这样当你坐下来和 PM agent 协作时，你已经清楚要构建什么、为谁构建。 - -## 工具介绍 - -### 头脑风暴 - -**是什么。** 一个使用经过验证的创意技法的引导式创意会议。AI 充当教练，通过结构化练习从你身上引出想法——而不是替你生成想法。 - -**为什么在这里。** 原始想法需要发展空间，然后才能被锁定为需求。头脑风暴创造了这个空间。当你有一个问题领域但还没有清晰的解决方案时，或者你想在确定方向之前探索多种可能性时，它尤其有价值。 - -**何时使用。** 你对想要构建什么有一个模糊的感觉，但概念尚未结晶。或者你有了概念，但想在备选方案中做压力测试。 - -详见[头脑风暴](./brainstorming.md)了解会议的具体运作方式。 - -### 调研（市场、领域、技术） - -**是什么。** 三个聚焦的调研工作流，分别调查你的想法的不同维度。市场调研考察竞争对手、趋势和用户情绪；领域调研建立专业知识和术语体系；技术调研评估可行性、架构选项和实现方案。 - -**为什么在这里。** 基于假设构建产品是最快做出没人需要的东西的方式。调研让你的概念扎根于现实——已有哪些竞争对手、用户真正的痛点是什么、技术上是否可行、所在行业有哪些特定约束。 - -**何时使用。** 你正在进入一个不熟悉的领域，你怀疑竞品存在但还没有做过梳理，或者你的概念依赖于尚未验证的技术能力。可以只做一项、两项或三项全做——每项都是独立的。 - -### 产品简报 - -**是什么。** 一个引导式发现会议，输出 1-2 页的产品概念执行摘要。AI 充当协作式业务分析师，帮你阐明愿景、目标受众、价值主张和范围。 - -**为什么在这里。** 产品简报是进入规划阶段的较温和路径。它以结构化格式捕获你的战略愿景，可以直接输入到 PRD 的创建中。当你已经对概念有了信心——你了解客户、了解问题、大致知道想构建什么时——它效果最好。简报的作用是组织和打磨这些思考。 - -**何时使用。** 你的概念相对清晰，希望在创建 PRD 之前高效地记录下来。你对方向有信心，不需要有人来激烈挑战你的假设。 - -### PRFAQ（逆向工作法） - -**是什么。** 亚马逊的逆向工作法（Working Backwards），改编为交互式挑战。你在写一行代码之前，先撰写宣布成品的新闻稿，然后回答客户和利益相关者会提出的最刁钻的问题。AI 充当不留情面但有建设性的产品教练。 - -**为什么在这里。** PRFAQ 是进入规划阶段的严格路径。它通过让你为每一个论断辩护，来强制实现以客户为中心的清晰度。如果你写不出一篇有说服力的新闻稿，说明产品还没准备好。如果客户 FAQ 的回答暴露了缺口，那些就是你在实现阶段才会——以更高代价——发现的缺口。这道关卡在成本最低的时候暴露薄弱的思考。 - -**何时使用。** 你希望在投入资源之前对概念进行压力测试。你不确定用户是否真的在意。你想验证自己能否阐述一个清晰、站得住脚的价值主张。或者你只是想借助逆向工作法的纪律来打磨你的思考。 - -## 我该用哪个？ - -| 情境 | 推荐工具 | -| ---- | -------- | -| "我有一个模糊的想法，不知道从哪里开始" | 头脑风暴 | -| "我需要先了解市场再做决定" | 调研 | -| "我知道要构建什么，只需要记录下来" | 产品简报 | -| "我想确认这个想法是否真的值得构建" | PRFAQ | -| "我想先探索，再验证，再记录" | 头脑风暴 → 调研 → PRFAQ 或 简报 | - -产品简报和 PRFAQ 都会为 PRD 提供输入——根据你想要多大程度的挑战来选择。简报是协作式发现，PRFAQ 是严格的关卡挑战。两者通往同一个目的地；PRFAQ 检验你的概念是否配得上到达那里。 - -:::tip[不确定？] -运行 `bmad-help`，描述你的情况。它会根据你已经做了什么、想达成什么来推荐合适的起点。 -::: - -## 分析之后呢？ - -分析阶段的输出直接进入 Phase 2（规划）。PRD 工作流接受产品简报、PRFAQ 文档、调研成果和头脑风暴报告作为输入——它会将你产出的所有内容综合成结构化需求。分析做得越充分，PRD 就越锐利。 diff --git a/docs/zh-cn/explanation/brainstorming.md b/docs/zh-cn/explanation/brainstorming.md deleted file mode 100644 index 1a09832951..0000000000 --- a/docs/zh-cn/explanation/brainstorming.md +++ /dev/null @@ -1,63 +0,0 @@ ---- -title: "头脑风暴" -description: 使用 60+ 种经过验证的构思技术进行互动创意会议 -sidebar: - order: 3 ---- - -`bmad-brainstorming` 是一个“思考引导”工作流：它不替你拍脑袋给答案，而是用结构化提问把你的想法挖出来、扩展开、再收敛成可执行方向。 - -## 它是什么 - -头脑风暴（brainstorming）适合”我有方向，但还不够清晰”的阶段。你会和 AI 进行来回探索： -- 明确问题和约束 -- 生成备选想法 -- 对想法分组和优先级排序 -- 形成下一步行动 - -产出通常是一份可回看的会话文档，便于继续深化或与团队同步。 - -## 什么时候使用 - -- 你卡在创意瓶颈，知道问题但想不到可行解 -- 你要做新功能或新产品，需要更多备选方案 -- 你希望从不同角度挑战既有假设 -- 你希望把“模糊想法”推进到“可执行方向” - -## 不适合的场景 - -- 你已经有清晰方案，只差落地实现 -- 你需要的是对现有文本做二次推理校验 -- 你需要多角色辩论来做跨职能权衡 - -在这些场景下，更合适的是： -- `advanced elicitation`：对已有输出做结构化二次推理 -- `bmad-party-mode`：让多个角色在同一会话内讨论权衡 - -## 它怎么推进思考 - -1. **设定主题**：定义目标、边界、约束 -2. **选择方法**：手动选、让 AI 推荐、随机抽取或渐进流程 -3. **引导展开**：通过连续问题挖掘更多可能性 -4. **组织收敛**：按主题聚类并排序 -5. **行动化**：给重点方向定义下一步和衡量标准 - -:::note[核心原则] -想法来源于你，workflow 负责构建“更容易产生好想法”的过程。 -::: - -想继续深化现有输出，可参考 [高级启发](./advanced-elicitation.md)；需要多角色协同讨论，可参考 [派对模式](./party-mode.md)。若要查看它在整体流程中的位置，请参见 [工作流地图](../reference/workflow-map.md)。 - -## 与相近模式的区别 - -| 模式 | 核心目标 | 输入状态 | 典型输出 | -| ----- | ----- | ----- | ----- | -| `bmad-brainstorming` | 发散并收敛想法 | 方向模糊、问题开放 | 想法清单、优先级、下一步 | -| `advanced elicitation` | 对已有内容做二次推理 | 已有初稿或方案 | 改进版内容与推理补强 | -| `bmad-party-mode` | 多角色协同讨论与对齐 | 涉及多方权衡的议题 | 角色视角下的共识或分歧 | - -## 继续阅读 - -- [高级启发](./advanced-elicitation.md) -- [派对模式](./party-mode.md) -- [工作流地图](../reference/workflow-map.md) diff --git a/docs/zh-cn/explanation/build.md b/docs/zh-cn/explanation/build.md deleted file mode 100644 index 2d45791228..0000000000 --- a/docs/zh-cn/explanation/build.md +++ /dev/null @@ -1,91 +0,0 @@ ---- -title: "Build" -description: 在不牺牲输出质量检查点的情况下减少人机交互的摩擦 -sidebar: - order: 7 ---- - -`bmad-build` 是所有开发工作的标准实施 workflow。它既可接收自由意图或 issue，也可接收完整规划的 story，并在安全前提下用尽可能少的人机交互完成代码变更。 - -上游规划仍然可选且深度可变。清晰变更可以直接进入；大型项目可以携带 PRD、UX、架构、epics、stories、就绪检查和 sprint 计划。这些产物会增强上下文，而不是选择另一条开发 workflow。 - -当已规划的 story 进入 Build 时，它仍然是产品上下文和验收标准的来源。Build 会为当前运行创建自己的执行记录，使实施决策和审查发现可追溯，但不会取代上游 story。 - -![Build 工作流图](/diagrams/build-run.svg) - -## 它解决什么问题 - -纯人工频繁盯流程会拖慢速度，纯自动又容易偏航。Build 做的是中间解： -- 在关键节点保留人工判断 -- 在可控区间放大模型自主执行时长 -- 通过规范与审查把偏航风险收回来 - -## Build 的核心机制 - -### 1. 先把意图压缩成单一目标 - -无论输入来自几句话、issue 链接、计划稿，还是 `epics.md` 的 `story`，都要先压缩成一个可执行目标。 -目标不清晰时，后续自动化越强，偏差成本越高。 - -### 2. 选择最小安全路径 - -目标明确后，workflow 会判断： -- 是不是“零爆炸半径”的 one-shot 变更 -- 还是必须先走 planning 再实现 - -原则是：能走短路径就不走长路径，但不能为了快跳过必要边界。 - -### 3. 在边界内长时自主执行 - -当目标与规范足够清晰，模型会承担更长段的连续实现。 -这一步省下的是“重复确认成本”，不是“质量成本”。 - -### 4. 在正确层级修复问题 - -Build 会区分问题来源： -- **意图层问题**：需求理解本身不对 -- **规范层问题**：tech-spec 边界不够强 -- **实现层问题**：本地代码缺陷 - -只有实现层问题才直接补代码；上层问题要回到对应层级重做。 - -### 5. 只在必要时拉回人工 - -人类主要在三个高杠杆时刻介入： -- 意图澄清 -- 规范确认 -- 最终结果审查 - -## 为什么它和“普通自动化”不一样 - -Build 不追求“全自动”，而是追求“最少但有效的人类判断”。 -它把人工注意力从大量低价值确认，转移到少量高价值决策。 - -## 与对抗性评审的关系 - -Build 是执行节奏设计；`adversarial review` 是审查策略。二者经常配合： -- Build 负责高效推进实现 -- 对抗性评审负责提高问题发现率并做分诊 - -也就是说，Build 解决“怎么更快且更稳地跑”，对抗性评审解决“怎么更狠地查问题”。 - -## 适用边界 - -**适合：** -- 目标可定义、可验收的实现任务 -- 希望减少流程摩擦但不放弃质量门 - -**不适合：** -- 目标长期模糊且频繁变化 -- 团队尚未接受“先规格后长时执行”的工作方式 - -:::tip[实践建议] -先把成功标准写清楚，再启用 Build。目标越清楚，自动化收益越大。 -::: - -## 继续阅读 - -需要对已有输出进行第二轮推理时，可参考 [高级启发](./advanced-elicitation.md)。若要查看它在完整流程中的位置，请参见 [工作流地图](../reference/workflow-map.md)。 - -- [高级启发](./advanced-elicitation.md) -- [工作流地图](../reference/workflow-map.md) diff --git a/docs/zh-cn/explanation/established-projects-faq.md b/docs/zh-cn/explanation/established-projects-faq.md deleted file mode 100644 index fe67a5b0a1..0000000000 --- a/docs/zh-cn/explanation/established-projects-faq.md +++ /dev/null @@ -1,61 +0,0 @@ ---- -title: "既有项目常见问题" -description: 关于在既有项目上使用 BMad Method 的常见问题 -sidebar: - order: 10 ---- -关于在 established projects（既有项目）中使用 BMad Method 的高频问题，快速说明如下。 - -## 问题 - -- [我必须先运行文档梳理工作流吗？](#我必须先运行文档梳理工作流吗) -- [如果我忘了运行文档梳理怎么办？](#如果我忘了运行文档梳理怎么办) -- [既有项目如何进入实施？](#既有项目如何进入实施) -- [如果现有代码不符合最佳实践怎么办？](#如果现有代码不符合最佳实践怎么办) -- [什么时候需要增加规划？](#什么时候需要增加规划) - -### 我必须先运行文档梳理工作流吗？ - -不绝对必须，但通常强烈建议先运行 `bmad-document-project`，尤其当： -- 项目文档缺失或明显过时 -- 新成员或智能体难以快速理解现有系统 -- 你希望后续 `workflow` 基于真实现状而不是猜测执行 - -如果你已有完整且最新的文档（包含 `docs/index.md`），并且能通过其他方式提供足够上下文，也可以跳过。 - -### 如果我忘了运行文档梳理怎么办？ - -可以随时补跑，不影响你继续推进当前任务。很多团队会在迭代中期或里程碑后再运行一次，用来把”代码现状”回写到文档里。 - -### 既有项目如何进入实施？ - -运行 `bmad-build`，与新项目使用同一实施 workflow。清晰改动可以直接进入；较大工作可以提供已规划 story 及其上游产物。 - -它会尝试识别现有技术栈、代码模式和约定，并据此生成更贴近现状的实现方案。 - -### 如果现有代码不符合最佳实践怎么办？ - -工作流会优先问你：“是否沿用当前约定？”你可以主动选择： -- **沿用**：优先保持一致性，降低短期改动风险 -- **升级**：建立新标准，并在 tech-spec 或架构中写明迁移理由与范围 - -BMad Method 不会强制“立即现代化”，而是把决策权交给你。 - -### 什么时候需要增加规划？ - -当任务出现以下信号时，建议在运行同一个 `bmad-build` 实施 workflow 前增加规划： -- 改动跨多个 `epic` 或多个子系统 -- 需要明确 `architecture` 决策，否则容易冲突 -- 涉及较大协作面、较高回归风险或复杂验收要求 - -如果你不确定，先让 `bmad-help` 判断当前阶段更稳妥的 workflow。 - -**还有问题？** 欢迎在 [GitHub Issues](https://github.com/bmad-code-org/BMAD-METHOD/issues) 或 [Discord](https://discord.gg/gk8jAdXWmj) 提问。 - -如果你想了解这套接入方式的操作步骤，可继续阅读 [How-to：既有项目](../how-to/established-projects.md) 与 [How-to：项目上下文](../how-to/project-context.md)。想理解统一实施 workflow，可参见 [Build](./build.md)。 - -## 继续阅读 - -- [既有项目（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/forge-idea.md b/docs/zh-cn/explanation/forge-idea.md deleted file mode 100644 index d66789de76..0000000000 --- a/docs/zh-cn/explanation/forge-idea.md +++ /dev/null @@ -1,76 +0,0 @@ ---- -title: "锻造想法" -description: 通过人设驱动的对抗式提问来检验想法，直到它被强化、被验证，或廉价地被淘汰 -sidebar: - order: 11 ---- - -把一个半成型的想法拿出来，趁改主意还不用付出代价，就在对话里把它压测一遍。 - -## 什么是 Forge Idea？ - -运行 `bmad-forge-idea`，一位严苛的审问者会一次只提一个问题，对你的想法穷追不舍，直到留下来的东西，是你凭充分把握就能去行动的那部分。这个 skill 与领域无关——软件功能、商业模式、研究假设，或你反复纠结的人生决定，都能跑。 - -你带走的是更清晰的思路。精炼后的 `forged-idea.md` 只是可能的出口之一，会话也不会把你往「那我们要不要开做？」上赶。 - -## 为什么要尽早压测 - -敌人是你自己看不到的那个洞。未检验的假设、未决的分支就是裂缝；现在漏掉的裂缝，会在构建或上线时重新冒出来——那时修复代价高得多。 - -对话是最便宜的捕捉点，因为在这里改主意不花什么。forge 就是刻意花这份廉价，在修复还免费的时候，专打弱点。 - -## 一次会话怎么跑 - -审问者一次只问一个问题，按依赖顺序来，每次都会先给出自己的推荐答案。有个立场可以推，比开放式提问走得更远。它能自己找到可查证的答案，而不是派你去查。 - -当你的想法落在已有项目里，该项目的材料就是 ground truth。审问者会把你的说法和已有内容对照，点出矛盾。你的词汇也一样——术语模糊或一词多义时，它会在分支能收敛之前，逼你做出精确选择；建在歧义词汇上的分支，会得出假结论。 - -## 房间 - -forge 是有声的。话题一定，每个分支都会来两个角色，而不是一个无脸助手。一个来自你已安装 roster——你会认得的 agent 或 persona，和 [Party Mode](./party-mode.md)、[命名智能体](./named-agents.md) 同一套 cast。另一个由话题当场召唤：敌对竞争者、持怀疑态度的 CFO、见过这套计划失败过的领域专家。 - -房间由你掌舵。随时点名具体的人、召唤已保存的 party，或启用 **adversarial on this** 档位，让某个主张被攻击到体无完肤，由你来辩护。 - -## 绝不默认同意 - -习惯性附和正是这个 skill 要拒绝的失败模式。承认你的说法，不等于背书；forge 不会在想法经受考验之前先夸。它打弱点、建强点，只给真正挣来的 credit。 - -这是对抗式审查的刻意反面。那边 reviewer 被要求找问题，你来滤掉误报；这边审问者被要求绝不免费给同意，压力保持高位，你在下面想得更硬。它优化的是最好的想法，不是最舒服的会话。 - -## 会话如何结束 - -会话怎么落就怎么结束，每种落地都是真实结果。forge 会写一份自洽报告，按结果打上标记，供你留存。 - -| 结果 | 含义 | -| --- | --- | -| **Hardened（已强化）** | 想法活下来了。会 distill 成 `forged-idea.md`（锁定的决定，以及被淘汰的内容及原因），可喂给 `bmad-spec`、`bmad-prd` 或 `bmad-prfaq` 做产品概念。 | -| **Killed（已淘汰）** | 想法没撑住，报告记录死因。廉价地发现这一点，就是赢。 | -| **Clearer（更清晰）** | 你只是想得更直了。不需要 artifact，会话本身就够了。 | - -## 何时使用 - -当你已经有一个想法，想在投入之前强化或淘汰它，就用 forge。还在生成选项，或需要 agent 群体决策时，跳过它。 - -| Skill | 何时使用 | 声音 | -| --- | --- | --- | -| `bmad-forge-idea` | 有想法，要压测或淘汰 | 审问者 + 双人房间 | -| `bmad-prfaq` | 已承诺做产品，要 customer-first 验证 | Working Backwards 教练 | -| `bmad-brainstorming` | 还没有想法，要生成选项 | 引导教练 | -| `bmad-party-mode` | 要让 agent 一起讨论或决策 | 整个 roster 同场 | -| `bmad-review` | 有 artifact，要找 flaw | 寻找真实问题的多视角 reviewer | - -## 示例 - -:::note[示例] -**你：**「我想在 app 里加 AI 生成的周报摘要，用户每周一收 digest 邮件。」 - -**Forge：**「在这功能之前，谁要的？我推荐答案是没人要——你在从『AI 摘要听起来有价值』推。若有真实信号，推回来。」 - -**持怀疑态度的 CFO（当场召唤）：**「周一是 recurring inference 成本，覆盖整个 active base， forever。哪条 revenue line 付得起？」 - -**你：**「Retention 吧，人们会忘记回来。」 - -**Forge：**「那 load-bearing claim 是『周一邮件把流失用户拉回来』，不是『AI 摘要有价值』。这是两个想法。我们在 forge 哪一个？」 -::: - -第一个想法是功能。两个问题之后，真正的想法是一个 retention 赌注——用 plain email、不用 model，也能测。 diff --git a/docs/zh-cn/explanation/named-agents.md b/docs/zh-cn/explanation/named-agents.md deleted file mode 100644 index 62698174c2..0000000000 --- a/docs/zh-cn/explanation/named-agents.md +++ /dev/null @@ -1,97 +0,0 @@ ---- -title: "命名智能体" -description: 为什么 BMad 的智能体有名字、人设和自定义能力——相比菜单驱动或纯提示驱动的方案，这解锁了哪些可能性 -sidebar: - order: 1 ---- - -你说"嘿 Mary，咱们来头脑风暴"，Mary 就激活了。她用你配置的语言、以她独特的人设向你打招呼，并提醒你随时可以用 `bmad-help`。然后她跳过菜单，直接进入头脑风暴——因为你的意图已经足够明确。 - -这一页解释背后发生了什么，以及 BMad 为什么这样设计。 - -## 三足鼎立 - -BMad 的智能体模型建立在三个可组合的基本要素之上： - -| 要素 | 提供什么 | 所在位置 | -|---|---|---| -| **技能（Skill）** | 能力——一项智能体能做的具体事（头脑风暴、撰写 PRD、实现 story） | `.claude/skills/{skill-name}/SKILL.md`（或你所用 IDE 的等价位置） | -| **命名智能体（Named Agent）** | 人设连续性——一个可辨识的身份，把一组相关技能包装在统一的语气、原则和视觉标识下 | 目录名以 `bmad-agent-*` 开头的技能 | -| **自定义（Customization）** | 让它成为你的——覆盖选项可以重塑智能体行为、添加 MCP 集成、替换模板、叠加组织规范 | `_bmad/custom/{skill-name}.toml`（团队提交的覆盖）和 `.user.toml`（个人，已 gitignore） | - -抽掉任何一条腿，体验就会坍塌： - -- 有技能没智能体 → 用户只能靠名称或编号在能力列表里自行查找 -- 有智能体没技能 → 空有人设，没有能力 -- 没有自定义 → 所有人用一模一样的开箱默认，任何组织特有需求都只能靠 fork - -## 命名智能体带来了什么 - -BMad 内置五个命名智能体，各自对应 BMad Method 的一个阶段： - -| 智能体 | 阶段 | 模块 | -|---|---|---| -| 📊 **Mary**，商业分析师 | 分析 | 市场调研、头脑风暴、产品摘要、PRFAQ | -| 📋 **John**，产品经理 | 规划 | PRD 创建、Epic/Story 拆分、实施就绪评审 | -| 🎨 **Sally**，UX 设计师 | 规划 | UX 设计规范 | -| 🏗️ **Winston**，系统架构师 | 方案设计 | 技术架构、一致性检查 | -| 💻 **Amelia**，高级工程师 | 实现 | Story 执行、Build、代码评审、Sprint 规划 | - -:::note[Paige 去哪儿了？] -📚 技术文档工程师 **Paige** 正在休整——她将在未来以更强大的能力回归。项目文档功能仍然可用：直接调用 `bmad-document-project` 技能，或通过 Mary 的菜单使用。 -::: - -每位智能体都有硬编码的身份（名字、职衔、专业领域）和可自定义的层（角色、原则、沟通风格、图标、菜单）。你可以重写 Mary 的原则或添加菜单项，但无法改她的名字——这是刻意为之的。品牌辨识度经得起自定义，所以"嘿 Mary"永远激活分析师，无论团队怎样塑造她的行为。 - -## 激活流程 - -调用命名智能体时，八个步骤依次执行： - -1. **解析智能体配置** — 通过 Python 解析器（使用 stdlib `tomllib`）将内置 `customize.toml` 与团队覆盖和个人覆盖合并 -2. **执行前置步骤** — 团队配置的任何预处理行为 -3. **采用人设** — 硬编码身份加上自定义的角色、沟通风格、原则 -4. **加载持久化事实** — 组织规则、合规说明，可通过 `file:` 前缀加载文件（如 `file:{project-root}/docs/project-context.md`） -5. **加载配置** — 用户名、沟通语言、输出语言、产物路径 -6. **打招呼** — 个性化问候，使用配置的语言，带上智能体的 emoji 前缀让你一眼认出谁在说话 -7. **执行后置步骤** — 团队配置的任何问候后设置 -8. **分发或展示菜单** — 如果你的开场消息能匹配某个菜单项，直接执行；否则展示菜单等待输入 - -第 8 步是意图与能力的交汇点。"嘿 Mary，咱们来头脑风暴"之所以跳过菜单渲染，是因为 `bmad-brainstorming` 显然对应 Mary 菜单上的 `BP`。如果你说的比较模糊，她会简短问一句，而不是走确认仪式。如果完全不匹配，她会正常继续对话。 - -## 为什么不只用菜单？ - -菜单迫使用户迁就工具。你得记住头脑风暴在分析师智能体的 `BP` 编码下，而不是 PM 智能体上，还得知道哪个人设负责哪些功能。这些都是工具强加给你的认知负担。 - -命名智能体把这个关系反转了。你用任何自然的方式，对着某个人说你想做什么。智能体知道自己是谁、能做什么。当你的意图足够清晰，她就直接开始。 - -菜单仍然作为兜底存在——探索时展示，确定时跳过。 - -## 为什么不直接用空白提示？ - -空白提示假设你知道"魔法咒语"。"帮我头脑风暴"也许有用，但"帮我发散下我这个 SaaS 创意"可能就不灵了，而结果取决于你怎么措辞。你变成了提示工程师。 - -命名智能体在不牺牲自由度的前提下增加了结构。人设保持一致，能力随时可发现，`bmad-help` 永远只差一个命令。你不用猜智能体能做什么，也不需要翻手册才能用它。 - -## 自定义是一等公民 - -自定义模型让这套方案能从单个开发者扩展到整个组织。 - -每个智能体自带 `customize.toml` 及合理默认值。团队在 `_bmad/custom/bmad-agent-{role}.toml` 中提交覆盖。个人可以在 `.user.toml`（已 gitignore）中叠加偏好。解析器在激活时按可预测的结构化规则合并三层配置。 - -大多数用户从不需要手写这些文件。`bmad-customize` 技能会引导你选择目标、区分智能体/工作流作用域、撰写覆盖、验证合并结果——让自定义能力对任何理解自己意图的人开放，不限于精通 TOML 的人。 - -举个例子：团队提交一个文件，告诉 Amelia 查库文档时一律用 Context7 MCP 工具，本地 epics 列表找不到 story 时回退到 Linear。Amelia 分发的每个开发工作流（build、code-review、qa-generate）都继承这些行为，无需改源码、无需逐工作流重复配置。 - -此外还有第二个自定义面，用于**跨领域关注点**：中央配置 `_bmad/config.toml` 和 `_bmad/config.user.toml`（由安装器维护，从每个模块的 `module.yaml` 重建）加上 `_bmad/custom/config.toml`（团队提交）和 `_bmad/custom/config.user.toml`（个人，已 gitignore）作为覆盖。这里存放着 **智能体花名册** ——轻量级描述符，`bmad-party-mode`、`bmad-retrospective` 和 `bmad-advanced-elicitation` 等花名册消费者读取它来了解有哪些智能体可用、如何扮演它们。用团队覆盖在全组织范围重新定义某个智能体；用 `.user.toml` 覆盖添加虚构角色（Kirk、Spock、领域专家）作为个人实验——无需碰任何技能目录。每个技能的配置文件塑造 Mary **激活时的行为**；中央配置塑造其他技能**查看花名册时看到的 Mary**。 - -完整自定义文档和实操示例请参见： - -- [如何自定义 BMad](../how-to/customize-bmad.md) — 可自定义项和合并规则的参考 -- [如何为组织扩展 BMad](../how-to/expand-bmad-for-your-org.md) — 五个实操方案，覆盖智能体全局规则、工作流约定、外部发布、模板替换和花名册管理 -- `bmad-customize` 技能 — 引导式编写助手，将你的意图转换为正确放置并经过验证的覆盖文件 - -## 更大的理念 - -当今大多数 AI 助手要么是菜单，要么是提示框，两者都把认知负担推给了用户。命名智能体加上可自定义技能，让你可以和一个了解项目的队友对话，并且让你的组织能塑造这个队友而不必 fork。 - -下次你输入"嘿 Mary，咱们来头脑风暴"，她直接上手干活时，留意一下哪些事情**没有**发生。没有斜杠命令，没有菜单要翻，没有尴尬的功能介绍。这种"无感"，正是设计本身。 diff --git a/docs/zh-cn/explanation/party-mode.md b/docs/zh-cn/explanation/party-mode.md deleted file mode 100644 index 1aafd1f9c3..0000000000 --- a/docs/zh-cn/explanation/party-mode.md +++ /dev/null @@ -1,60 +0,0 @@ ---- -title: "派对模式" -description: 多智能体协作——将所有 AI 智能体汇聚到一次对话中 -sidebar: - order: 8 ---- - -`bmad-party-mode` 用于多角色协作讨论：把 PM、架构、开发、UX 等视角放到同一轮对话里，快速暴露分歧、对齐取舍。 - -## 它是什么 - -Party Mode 不是单角色问答，也不是单文档改写。它更像一次”有主持人的多方评审会”： -- BMad Master 根据你的问题调度相关角色 -- 各角色以自身关注点回应 -- 角色间会互相补充、质疑、修正 - -你可以连续追问，直到形成可执行结论。 - -## 什么时候使用 - -- 面临高影响决策，且存在明确 trade-off -- 需要跨角色快速对齐（产品、技术、交互、测试） -- 出现故障或争议，需要复盘责任和改进方向 -- 做 sprint 规划或回顾，需要多视角共识 - -## 不适合的场景 - -- 你只需要单一角色的直接执行（例如仅改一段文案） -- 你已有明确决策，只需进入实现 -- 你需要的是对同一输出做深度二次推理 - -这些场景通常更适合： -- `bmad-build`（直接进入实现） -- `advanced elicitation`（二次推理补强） - -## 价值与边界 - -Party Mode 的价值在于”更快看见盲区”： -- 优势：视角多、分歧显性、对齐速度快 -- 代价：讨论信息量大，需要你主动控节奏和收敛 - -:::caution[使用建议] -先给清晰议题，再给决策约束（时间、风险、成本、成功标准），讨论质量会明显更高。 -::: - -若你的目标是结构化发散创意，可先参考 [头脑风暴](./brainstorming.md)；若你已经有初稿并想做二次推理补强，可参考 [高级启发](./advanced-elicitation.md)。完整阶段位置见 [工作流地图](../reference/workflow-map.md)。 - -## 与相近模式的区别 - -| 模式 | 核心目标 | 最佳场景 | 输出形态 | -| ----- | ----- | ----- | ----- | -| `bmad-party-mode` | 多角色对齐与权衡 | 跨职能决策、复盘、规划 | 共识点、争议点、决策建议 | -| `bmad-brainstorming` | 发散创意并收敛 | 方向探索、创意卡点 | 想法池与优先级 | -| `advanced elicitation` | 对现有输出做二次推理 | 规格/方案补强 | 改进版内容与风险补充 | - -## 继续阅读 - -- [头脑风暴](./brainstorming.md) -- [高级启发](./advanced-elicitation.md) -- [工作流地图](../reference/workflow-map.md) diff --git a/docs/zh-cn/explanation/preventing-agent-conflicts.md b/docs/zh-cn/explanation/preventing-agent-conflicts.md deleted file mode 100644 index 3bab884ff3..0000000000 --- a/docs/zh-cn/explanation/preventing-agent-conflicts.md +++ /dev/null @@ -1,118 +0,0 @@ ---- -title: "防止智能体冲突" -description: 架构如何在多个智能体实现系统时防止冲突 -sidebar: - order: 6 ---- - -当多个 AI 智能体并行实现系统时，冲突并不罕见。`architecture` 的作用，就是在 `solutioning` 阶段先统一关键决策，避免到 `epic/story` 实施时才暴露分歧。 - -## 冲突最常出现在哪些地方 - -### API 风格冲突 - -没有架构约束时： -- 智能体 A 使用 REST，路径是 `/users/{id}` -- 智能体 B 使用 GraphQL mutations -- 结果：接口模式不一致，调用方和集成层都变复杂 - -有架构约束时： -- ADR 明确规定：“客户端与服务端统一使用 GraphQL” -- 所有智能体遵循同一套 API 规则 - -### 数据库与命名冲突 - -没有架构约束时： -- 智能体 A 使用 `snake_case` 列名 -- 智能体 B 使用 `camelCase` 列名 -- 结果：schema 不一致，查询与迁移成本上升 - -有架构约束时： -- 标准文档统一命名约定和迁移策略 -- 所有智能体按同一模式实现 - -### 状态管理冲突 - -没有架构约束时： -- 智能体 A 使用 Redux -- 智能体 B 使用 React Context -- 结果：状态层碎片化，维护复杂度增加 - -有架构约束时： -- ADR 明确状态管理方案 -- 不同 `story` 的实现保持一致 - -## architecture 如何前置消解冲突 - -### 1. 用 ADR 固化关键决策 - -每个关键技术选择都至少包含： -- 背景（为什么要做这个决策） -- 备选方案（有哪些选择） -- 最终决策（采用什么） -- 理由（为什么这样选） -- 后果（接受哪些权衡） - -### 2. 把 FR/NFR 映射到技术实现 - -`architecture` 不是抽象原则清单，而是把需求落到可执行方案： -- FR-001（用户管理）→ GraphQL mutations -- FR-002（移动端性能）→ 查询裁剪与缓存策略 - -### 3. 统一基础约定 - -至少覆盖以下共识： -- 目录结构 -- 命名约定 -- 代码组织方式 -- 测试策略 - -## architecture 是所有 epic 的共享上下文 - -把架构文档看作每个智能体在实施前都要阅读的“公共协议”： - -```text -PRD: "做什么" - ↓ -architecture: "如何做" - ↓ -智能体 A 读 architecture → 实现 Epic 1 -智能体 B 读 architecture → 实现 Epic 2 -智能体 C 读 architecture → 实现 Epic 3 - ↓ -结果：实现一致、集成顺畅 -``` - -## 优先写清的 ADR 主题 - -| 主题 | 示例决策 | -| ---------------- | -------------------------------------------- | -| 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[常见错误] -- **隐式决策**：边写边定规则，最终通常会分叉 -- **过度文档化**：把每个小选择都写 ADR，造成分析瘫痪 -- **架构陈旧**：文档不更新，智能体继续按过时规则实现 -::: - -:::tip[更稳妥的做法] -- 先记录跨 `epic`、高冲突概率的决策 -- 把精力放在”会影响多个 story 的规则” -- 随着项目演进持续更新架构文档 -- 出现重大偏移时使用 `bmad-correct-course` -::: - -如需先理解为什么要在实施前做 solutioning，可阅读 [为什么解决方案设计很重要](./why-solutioning-matters.md)；如果你想把这些约束落地到项目执行，可继续看 [项目上下文](./project-context.md)。流程全景见 [工作流地图](../reference/workflow-map.md)。 - -## 继续阅读 - -- [为什么解决方案阶段很重要](./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 deleted file mode 100644 index e3ca01e3a8..0000000000 --- a/docs/zh-cn/explanation/project-context.md +++ /dev/null @@ -1,94 +0,0 @@ ---- -title: "项目上下文" -description: project-context.md 如何使用项目规则和偏好指导 AI 智能体 -sidebar: - order: 9 ---- - -`project-context.md` 是面向 AI 智能体的项目级上下文文件。它的定位不是教程步骤，而是“实现约束说明”：把你的技术偏好、架构边界和工程约定沉淀成可复用规则，让不同工作流、不同智能体在多个 `story` 中做出一致决策。 - -## project context 解决什么问题 - -没有统一上下文时，智能体往往会： -- 套用通用最佳实践，而不是你的项目约定 -- 在不同 `story` 中做出不一致实现 -- 漏掉代码里不易推断的隐性约束 - -有 `project-context.md` 时，这些高频偏差会明显减少，因为关键规则在进入实现前已经被显式声明。 - -## 它如何被工作流使用 - -多数实现相关工作流会自动加载 `project-context.md`（若存在），并把它作为共享上下文参与决策。 - -**常见加载方包括：** -- `bmad-architecture`：在 solutioning 时纳入你的技术偏好 -- `bmad-code-review`：按项目标准做一致性校验 -- `bmad-build`：在规划和实施直接意图或 story 时遵循既有模式 -- `bmad-sprint-planning`、`bmad-retrospective`、`bmad-correct-course`：读取项目级背景 - -## 什么时候建立或更新 - -| 场景 | 建议时机 | 目标 | -|----------|----------------|---------| -| **新项目（架构前）** | 在 `bmad-architecture` 前手动创建 | 先声明技术偏好，避免架构偏航 | -| **新项目（架构后）** | 通过 `bmad-generate-project-context` 生成并补充 | 把架构决策转成可执行规则 | -| **既有项目** | 先生成，再人工校对 | 让智能体学习现有约定而非重造体系 | -| **直接实施入口** | 在 `bmad-build` 前或过程中维护 | 在没有上游规划时提供持久项目约定 | - -:::tip[推荐做法] -如果你有强技术偏好（例如数据库、状态管理、目录规范），尽量在架构前写入。否则可在架构后生成，再按项目现实补齐。 -::: - -## 应该写哪些内容 - -建议聚焦两类信息：**技术栈与版本**、**关键实现规则**。原则是记录“智能体不容易从代码片段直接推断”的内容。 - -### 1. 技术栈与版本 - -```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 -``` - -### 2. 关键实现规则 - -```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` -- API calls use the `apiClient` singleton — never fetch directly - -**Testing Patterns:** -- Integration tests use MSW to mock API responses -- E2E tests cover critical user journeys only -``` - -## 常见误解 - -- **误解 1：它是操作手册。** - 不是。操作步骤请看 how-to；这里强调的是规则与边界。 -- **误解 2：写得越全越好。** - 不对。冗长且泛化的“最佳实践”会稀释有效约束。 -- **误解 3：写一次就结束。** - 这是动态文件。架构变化、约定变化后要同步更新。 - -## 文件位置 - -默认位置是 `_bmad-output/project-context.md`。工作流优先在该位置查找，也会扫描项目内的 `**/project-context.md`。 - -## 继续阅读 - -如需可执行步骤说明，请阅读 [How-to：项目上下文](../how-to/project-context.md)；如果你在既有项目落地这套机制，可参考 [既有项目常见问题](./established-projects-faq.md)。整体流程定位见 [工作流地图](../reference/workflow-map.md)。 - -- [管理项目上下文（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 deleted file mode 100644 index 06cdba2086..0000000000 --- a/docs/zh-cn/explanation/why-solutioning-matters.md +++ /dev/null @@ -1,86 +0,0 @@ ---- -title: "为什么解决方案阶段很重要" -description: 理解为什么解决方案阶段对于多史诗项目至关重要 -sidebar: - order: 5 ---- - -Phase 3（solutioning）把“要做什么”（planning 产出）转成“如何实现”（`architecture` 设计 + 工作拆分）。它的核心价值是：在开发前先把跨 `epic` 的关键技术决策写清楚，让后续 `story` 实施保持一致。 - -## 不做 solutioning 会出现什么问题 - -```text -智能体 1 使用 REST API 实现 Epic 1 -智能体 2 使用 GraphQL 实现 Epic 2 -结果：API 设计不一致，集成成本暴涨 -``` - -当多个智能体在没有共享 `architecture` 指南的前提下并行实现不同 `epic`，它们会各自做局部最优决策，最后在集成阶段发生冲突。 - -## 做了 solutioning 后会发生什么 - -```text -architecture 工作流先定规则："所有 API 使用 GraphQL" -所有智能体按同一套决策实现 story -结果：实现一致，集成顺滑 -``` - -solutioning 的本质不是“多写一份文档”，而是把高冲突风险决策前置，作为所有 `story` 的共享上下文。 - -## solutioning 与 planning 的边界 - -| 方面 | Planning（阶段 2） | Solutioning（阶段 3） | -| -------- | ----------------------- | --------------------------------- | -| 核心问题 | 做什么，为什么做？ | 如何做，再如何拆分工作？ | -| 输出物 | FRs/NFRs（需求） | `architecture` + `epic/story` 拆分 | -| 主导角色 | PM | Architect → PM | -| 受众 | 利益相关者 | 开发人员 | -| 文档 | PRD（FRs/NFRs） | 架构文档 + epics 文件 | -| 决策层级 | 业务目标与范围 | 技术策略与实现边界 | - -## 核心原则 - -**让跨 `epic` 的关键技术决策显式、可追溯、可复用。** - -这能直接降低： -- API 风格冲突（REST vs GraphQL） -- 数据模型与命名约定不一致 -- 状态管理方案分裂 -- 安全策略分叉 -- 中后期返工成本 - -## 选择 solutioning 深度 - -| 工作特征 | Solutioning 建议 | -|-------|----------------------| -| 约定明确的局部变更 | 通常不需要 | -| 多个相关组件且约束已知 | 按协同风险选择 | -| 多个 epic 或跨系统决策 | 需要用它对齐实施 | -| 受监管、高风险或 enterprise 项目 | 遵循必要的治理要求；通常必须进行 solutioning | - -Solutioning 改变提供给 `bmad-build` 的上下文，不改变实施 workflow。 - -:::tip[经验法则] -只要需求会拆成多个 `epic`，并且可能由不同智能体并行实现，就应该做 solutioning。 -::: - -## 跳过 solutioning 的代价 - -在复杂项目中跳过该阶段，常见后果是： - -- **集成问题**在冲刺中期暴露 -- **返工**由实现冲突引发 -- **整体研发周期拉长** -- **技术债务**因模式不一致持续累积 - -:::caution[成本倍增] -在 solutioning 阶段发现对齐问题，通常比在实施中后期才发现更快、更便宜。 -::: - -想进一步理解冲突是如何发生并被架构约束消除的，可继续阅读 [防止智能体冲突](./preventing-agent-conflicts.md)。如果你要把这些约束落到执行层，请结合 [项目上下文](./project-context.md) 与 [工作流地图](../reference/workflow-map.md) 一起阅读。 - -## 继续阅读 - -- [防止智能体冲突](./preventing-agent-conflicts.md) -- [项目上下文](./project-context.md) -- [工作流地图](../reference/workflow-map.md) diff --git a/docs/zh-cn/how-to/customize-bmad.md b/docs/zh-cn/how-to/customize-bmad.md deleted file mode 100644 index 2ce6dfdce0..0000000000 --- a/docs/zh-cn/how-to/customize-bmad.md +++ /dev/null @@ -1,175 +0,0 @@ ---- -title: "如何自定义 BMad" -description: 自定义智能体、工作流和模块，同时保持更新兼容性 -sidebar: - order: 7 ---- - -使用 `.customize.yaml` 文件，自定义智能体（agent）的行为、角色（persona）和菜单，同时在后续更新中保留你的改动。 - -## 何时使用此功能 - -- 你想修改智能体名称、身份设定或沟通风格 -- 你需要让智能体长期记住项目约束和背景信息 -- 你希望增加自定义菜单项，触发自己的工作流或提示 -- 你希望智能体每次启动都先执行固定动作 - -:::note[前置条件] -- 已在项目中安装 BMad（参见[如何安装 BMad](./install-bmad.md)） -- 用于编辑 YAML 文件的文本编辑器 -::: - -:::caution[保护您的自定义配置] -始终通过 `.customize.yaml` 自定义，不要直接改动智能体源文件。安装程序在更新时会覆盖智能体文件，但会保留 `.customize.yaml` 的内容。 -::: - -## 步骤 - -### 1. 定位自定义文件 - -安装完成后，每个已安装智能体都会在下面目录生成一个 `.customize.yaml`： - -```text -_bmad/_config/agents/ -├── core-bmad-master.customize.yaml -├── bmm-dev.customize.yaml -├── bmm-pm.customize.yaml -└── ...（每个已安装智能体一个文件） -``` - -### 2. 编辑自定义文件 - -打开目标智能体的 `.customize.yaml`。各段都可选，只改你需要的部分即可。 - -| 部分 | 作用方式 | 用途 | -| ------------------ | -------- | ---------------------------------------------- | -| `agent.metadata` | 覆盖 | 覆盖智能体显示名称 | -| `persona` | 覆盖 | 设置角色、身份、风格和原则 | -| `memories` | 追加 | 添加智能体长期记忆的上下文 | -| `menu` | 追加 | 增加指向工作流或提示的菜单项 | -| `critical_actions` | 追加 | 定义智能体启动时要执行的动作 | -| `prompts` | 追加 | 创建可复用提示，供菜单 `action` 引用 | - -标记为 **覆盖** 的部分会完全替换默认配置；标记为 **追加** 的部分会在默认配置基础上累加。 - -**智能体名称（`agent.metadata`）** - -修改智能体的显示名称： - -```yaml -agent: - metadata: - name: 'Spongebob' # 默认值："Amelia" -``` - -**角色（`persona`）** - -替换智能体的人设、职责和沟通风格： - -```yaml -persona: - role: 'Senior Full-Stack Engineer' - identity: 'Lives in a pineapple (under the sea)' - communication_style: 'Spongebob annoying' - principles: - - 'Never Nester, Spongebob Devs hate nesting more than 2 levels deep' - - 'Favor composition over inheritance' -``` - -`persona` 会覆盖默认整段配置，所以启用时请把四个字段都填全。 - -**记忆（`memories`）** - -添加智能体会长期记住的上下文： - -```yaml -memories: - - 'Works at Krusty Krab' - - 'Favorite Celebrity: David Hasselhoff' - - 'Learned in Epic 1 that it is not cool to just pretend that tests have passed' -``` - -**菜单项（`menu`）** - -给智能体菜单添加自定义项。每个条目都需要 `trigger`、目标（`workflow` 路径或 `action` 引用）和 `description`： - -```yaml -menu: - - trigger: my-workflow - workflow: 'my-custom/workflows/my-workflow.yaml' - description: My custom workflow - - trigger: deploy - action: '#deploy-prompt' - description: Deploy to production -``` - -**启动关键动作（`critical_actions`）** - -定义智能体启动时执行的指令： - -```yaml -critical_actions: - - 'Check the CI Pipelines with the XYZ Skill and alert user on wake if anything is urgently needing attention' -``` - -**可复用提示（`prompts`）** - -创建可复用提示，菜单项可通过 `action="#id"` 调用： - -```yaml -prompts: - - id: deploy-prompt - content: | - Deploy the current branch to production: - 1. Run all tests - 2. Build the project - 3. Execute deployment script -``` - -### 3. 应用更改 - -编辑完成后，重新安装以应用配置： - -```bash -npx bmad-method install -``` - -安装程序会识别现有安装，并给出以下选项： - -| 选项 | 作用 | -| ---------------------------- | ------------------------------------------------------------------- | -| **Quick Update** | 更新所有模块到最新版本，并应用你的自定义配置 | -| **Modify BMad Installation** | 进入完整安装流程，用于增删模块 | - -如果只是调整 `.customize.yaml`，优先选 **Quick Update**。 - -## 故障排查 - -**改动没有生效？** - -- 运行 `npx bmad-method install` 并选择 **Quick Update** 以应用更改 -- 检查 YAML 语法是否正确（尤其是缩进） -- 确认你编辑的是目标智能体对应的 `.customize.yaml` - -**智能体无法加载？** - -- 使用在线 YAML 验证器检查 YAML 语法错误 -- 确保取消注释后没有遗留空字段 -- 可先回退到模板，再逐项恢复自定义配置 - -**需要重置某个智能体？** - -- 清空或删除智能体的 `.customize.yaml` 文件 -- 运行 `npx bmad-method install` 并选择 **Quick Update** 以恢复默认设置 - -## 工作流自定义 - -对现有 BMad Method 工作流和技能的深度自定义能力即将推出。 - -## 模块自定义 - -关于构建扩展模块和自定义现有模块的指南即将推出。 - -## 后续步骤 - -- [命令参考](../reference/commands.md) - 查看可用命令和工作流入口 diff --git a/docs/zh-cn/how-to/established-projects.md b/docs/zh-cn/how-to/established-projects.md deleted file mode 100644 index 783ef9574d..0000000000 --- a/docs/zh-cn/how-to/established-projects.md +++ /dev/null @@ -1,118 +0,0 @@ ---- -title: "既有项目" -description: 如何在现有代码库中使用 BMad Method -sidebar: - order: 6 ---- - -当你在现有项目或遗留代码库上工作时，本指南帮助你更稳妥地使用 BMad Method。 - -如果你是从零开始的新项目，建议先看[快速入门](../tutorials/getting-started.md)；本文主要面向既有项目接入场景。 - -:::note[前置条件] -- 已安装 BMad Method（`npx bmad-method install`） -- 一个你想要处理的现有代码库 -- 访问 AI 驱动的 IDE（Claude Code 或 Cursor） -::: - -## 步骤 1：清理已完成的规划产物 - -如果你通过 BMad 流程完成了所有 PRD 史诗和用户故事，请清理这些文件。归档它们、删除它们，或者在需要时依赖版本历史。不要将这些文件保留在： - -- `docs/` -- `_bmad-output/planning-artifacts/` -- `_bmad-output/implementation-artifacts/` - -## 步骤 2：创建项目上下文（project context） - -:::tip[推荐用于既有项目] -生成 `project-context.md`，梳理现有代码库的模式与约定，确保 AI 智能体在实施变更时遵循你既有的工程实践。 -::: - -运行生成项目上下文工作流： - -```bash -bmad-generate-project-context -``` - -这将扫描你的代码库以识别： -- 技术栈和版本 -- 代码组织模式 -- 命名约定 -- 测试方法 -- 框架相关模式 - -你可以先审阅并完善生成内容；如果更希望手动维护，也可以直接在 -`_bmad-output/project-context.md` 创建并编辑。 - -[了解更多关于项目上下文](../explanation/project-context.md) - -## 步骤 3：维护高质量项目文档 - -你的 `docs/` 文件夹应包含简洁、组织良好的文档，准确代表你的项目： - -- 意图和业务理由 -- 业务规则 -- 架构 -- 任何其他相关的项目信息 - -对于复杂项目，可考虑使用 `bmad-document-project` 工作流。它会扫描整个项目并记录当前真实状态。 - -## 步骤 4：获取帮助 - -### BMad-Help：默认起点 - -**当你不确定下一步做什么时，随时运行 `bmad-help`。** 这个智能指南会： - -- 检查项目当前状态，识别哪些工作已经完成 -- 根据你安装的模块给出可行选项 -- 理解自然语言查询 - -``` -bmad-help 我有一个现有的 Rails 应用，我应该从哪里开始？ -bmad-help 这个变更在实施前需要多深的规划？ -bmad-help 显示我当前有哪些可用工作流 -``` - -BMad-Help 还会在**每个工作流结束时自动运行**，明确告诉你下一步该做什么。 - -### 选择规划深度 - -所有实施都使用 `bmad-build`；范围只决定需要预先准备多少上下文： - -| 范围 | 推荐方法 | -| --- | --- | -| **清晰更新或新增** | 携带请求、issue 或现有规格直接进入 `bmad-build`。 | -| **重大变更或新增** | 准备有用的 PRD、UX、架构、epic、story 和 sprint 上下文，再把选定工作交给 `bmad-build`。 | - -### 在创建 PRD 期间 - -在创建简报或直接进入 PRD 时，确保智能体： - -- 查找并分析你现有的项目文档 -- 读取与你当前系统匹配的项目上下文（project context） - -你可以显式补充指令，但核心目标是让新功能与现有 architecture 和代码约束自然融合。 - -### UX 考量 - -UX 工作是可选项。是否需要进入 UX 流程，不取决于“项目里有没有 UX”，而取决于： - -- 你是否真的在做 UX 层面的变更 -- 是否需要新增重要的 UX 设计或交互模式 - -如果本次只是对现有页面做小幅调整，通常不需要完整 UX 流程。 - -### 架构考量（architecture） - -在进行架构工作时，确保架构师： - -- 使用正确且最新的文档输入 -- 扫描并理解现有代码库 - -这一点非常关键：可避免“重复造轮子”，也能减少与现有架构冲突的设计决策。 - -## 更多信息 - -- **[快速修复](./quick-fixes.md)** - 错误修复和临时变更 -- **[既有项目 FAQ](../explanation/established-projects-faq.md)** - 关于在既有项目上工作的常见问题 diff --git a/docs/zh-cn/how-to/expand-bmad-for-your-org.md b/docs/zh-cn/how-to/expand-bmad-for-your-org.md deleted file mode 100644 index a323235e40..0000000000 --- a/docs/zh-cn/how-to/expand-bmad-for-your-org.md +++ /dev/null @@ -1,258 +0,0 @@ ---- -title: "如何为组织扩展 BMad" -description: 五个自定义方案，无需 fork 即可重塑 BMad——涵盖智能体全局规则、工作流约定、外部发布、模板替换和花名册变更 -sidebar: - order: 9 ---- - -BMad 的自定义机制让组织无需编辑已安装文件或 fork 技能就能重塑行为。本指南介绍五个方案，覆盖大部分企业级需求。 - -:::note[前置条件] - -- 已在项目中安装 BMad（参见[如何安装 BMad](./install-bmad.md)） -- 熟悉自定义模型（参见[如何自定义 BMad](./customize-bmad.md)） -- PATH 中有 Python 3.11+（解析器只用标准库，不需要 `pip install`） -::: - -:::tip[如何应用这些方案] -下面的**逐技能方案**（方案 1–4）可以通过运行 `bmad-customize` 技能并描述意图来应用——它会选择正确的配置面、生成覆盖文件并验证合并结果。方案 5（中央配置的花名册覆盖）超出 v1 技能范围，仍需手动编写。本文档中的方案是覆盖**什么**的权威参考；`bmad-customize` 负责处理**怎么做**的部分（针对智能体/工作流层面）。 -::: - -## 三层心智模型 - -在选择方案之前，先理解你的覆盖落在哪一层： - -| 层 | 覆盖文件位置 | 作用范围 | -|---|---|---| -| **智能体**（如 Amelia、Mary、John） | `_bmad/custom/bmad-agent-{role}.toml` 中的 `[agent]` 段 | 跟随人设进入**该智能体分发的每个工作流** | -| **工作流**（如 product-brief、create-prd） | `_bmad/custom/{workflow-name}.toml` 中的 `[workflow]` 段 | 仅作用于该工作流的单次运行 | -| **中央配置** | `_bmad/custom/config.toml` 中的 `[agents.*]`、`[core]`、`[modules.*]` | 花名册（party-mode、retrospective、elicitation 可用的角色）、全组织统一的安装设置 | - -经验法则：如果规则应当在工程师做任何开发工作时生效，就自定义**开发智能体**。如果只在撰写产品摘要时生效，就自定义 **product-brief 工作流**。如果要改变"谁在场"（重命名智能体、添加自定义角色、统一产物路径），就编辑**中央配置**。 - -## 方案 1：让智能体的规则贯穿其分发的所有工作流 - -**场景：** 统一工具使用和外部系统集成，让智能体分发的每个工作流都继承这些行为。这是影响面最大的模式。 - -**示例：Amelia（开发智能体）查库文档一律用 Context7，本地 epics 列表找不到 story 时回退到 Linear。** - -```toml -# _bmad/custom/bmad-agent-dev.toml - -[agent] - -# 每次激活时加载。传递到 build、code-review、 -# qa-generate——Amelia 分发的每个技能。 -persistent_facts = [ - "For any library documentation lookup (React, TypeScript, Zod, Prisma, etc.), call the context7 MCP tool (`mcp__context7__resolve_library_id` then `mcp__context7__get_library_docs`) before relying on training-data knowledge. Up-to-date docs trump memorized APIs.", - "When a story reference isn't found in {planning_artifacts}/epics-and-stories.md, search Linear via `mcp__linear__search_issues` using the story ID or title before asking the user to clarify. If Linear returns a match, treat it as the authoritative story source.", -] -``` - -**为什么有效：** 两句话就能重塑组织内所有开发工作流，无需逐工作流重复配置、无需改源码。每个新工程师拉下仓库就自动继承这些约定。 - -**团队文件 vs 个人文件：** -- `bmad-agent-dev.toml`：提交到 git，对整个团队生效 -- `bmad-agent-dev.user.toml`：已 gitignore，个人偏好叠加在上面 - -## 方案 2：在特定工作流中强制执行组织规范 - -**场景：** 塑造工作流输出的*内容*，使其满足合规、审计或下游消费者的要求。 - -**示例：每份产品摘要都必须包含合规字段，智能体知晓组织的发布规范。** - -```toml -# _bmad/custom/bmad-product-brief.toml - -[workflow] - -persistent_facts = [ - "Every brief must include an 'Owner' field, a 'Target Release' field, and a 'Security Review Status' field.", - "Non-commercial briefs (internal tools, research projects) must still include a user-value section, but can omit market differentiation.", - "file:{project-root}/docs/enterprise/brief-publishing-conventions.md", -] -``` - -**效果：** 这些事实在工作流激活的第 3 步加载。当智能体起草摘要时，它已了解必填字段和企业规范文档。随附的技能本身不带任何持久事实，因此这些就是加载的全部内容；但由于该键是追加而非替换，团队级和用户级各自添加的事实会同时生效。 - -## 方案 3：将完成的产出发布到外部系统 - -**场景：** 工作流生成输出后，自动发布到企业级记录系统（Confluence、Notion、SharePoint）并创建后续工作项（Jira、Linear、Asana）。 - -**示例：摘要自动发布到 Confluence，并提供可选的 Jira Epic 创建。** - -```toml -# _bmad/custom/bmad-product-brief.toml - -[workflow] - -# 终端钩子。标量覆盖会整体替换空默认值。 -on_complete = """ -Publish and offer follow-up: - -1. Read the finalized brief file path from the prior step. -2. Call `mcp__atlassian__confluence_create_page` with: - - space: "PRODUCT" - - parent: "Product Briefs" - - title: the brief's title - - body: the brief's markdown contents - Capture the returned page URL. -3. Tell the user: "Brief published to Confluence: ". -4. Ask: "Want me to open a Jira epic for this brief now?" -5. If yes, call `mcp__atlassian__jira_create_issue` with: - - type: "Epic" - - project: "PROD" - - summary: the brief's title - - description: a short summary plus a link back to the Confluence page. - Report the epic key and URL. -6. If no, exit cleanly. - -If either MCP tool fails, report the failure, print the brief path, -and ask the user to publish manually. -""" -``` - -**为什么用 `on_complete` 而不是 `activation_steps_append`：** `on_complete` 只在终端阶段运行一次，在工作流主输出写入之后。这是发布产物的正确时机。`activation_steps_append` 在每次激活时运行，在工作流开始之前。 - -**权衡：** -- **Confluence 发布是非破坏性的**，完成时始终运行 -- **Jira Epic 创建对全团队可见**，会触发 Sprint 规划信号，因此需用户确认 -- **优雅降级：** 如果 MCP 工具失败，交给用户手动处理，而不是静默丢弃输出 - -## 方案 4：替换为你自己的输出模板 - -**场景：** 默认输出结构不符合组织期望的格式，或同一仓库中不同团队需要不同模板。 - -**示例：将 product-brief 工作流指向企业自有模板。** - -```toml -# _bmad/custom/bmad-product-brief.toml - -[workflow] -brief_template = "{project-root}/docs/enterprise/brief-template.md" -``` - -**原理：** 工作流自带的 `customize.toml` 中 `brief_template = "resources/brief-template.md"`（裸路径，从技能根目录解析）。你的覆盖指向 `{project-root}` 下的文件，智能体在第 4 步读取你的模板而非内置模板。 - -**模板编写建议：** -- 将模板放在 `{project-root}/docs/` 或 `{project-root}/_bmad/custom/templates/` 下，使它们与覆盖文件一起版本管理 -- 沿用内置模板的结构约定（章节标题、frontmatter），智能体会适配实际内容 -- 对于多团队仓库，使用 `.user.toml` 让各团队指向自己的模板，无需改动已提交的团队文件 - -## 方案 5：自定义花名册 - -**场景：** 改变 `bmad-party-mode`、`bmad-retrospective` 和 `bmad-advanced-elicitation` 等花名册驱动技能中*谁在场*，无需编辑源码或 fork。以下是三种常见变体。 - -### 5a. 在全组织范围内重塑 BMad 智能体 - -每个真实智能体都有一段安装器从 `module.yaml` 合成的描述符。覆盖它可以在所有花名册消费者中改变语气和定位： - -```toml -# _bmad/custom/config.toml（提交到 git——对每个开发者生效） - -[agents.bmad-agent-analyst] -description = "Mary the Regulatory-Aware Business Analyst — channels Porter and Minto, but lives and breathes FDA audit trails. Speaks like a forensic investigator presenting a case file." -``` - -Party-mode 会用新描述来生成 Mary。分析师激活流程本身不受影响，因为 Mary 的行为由她的每技能 `customize.toml` 控制。这个覆盖改变的是**外部技能如何感知和介绍她**，而不是她的内部工作方式。 - -### 5b. 添加虚构或自定义智能体 - -一段完整的描述符就足以让花名册功能识别，不需要技能目录。适合在 party mode 或头脑风暴中增加性格多样性： - -```toml -# _bmad/custom/config.user.toml（个人——已 gitignore） - -[agents.spock] -team = "startrek" -name = "Commander Spock" -title = "Science Officer" -icon = "🖖" -description = "Logic first, emotion suppressed. Begins observations with 'Fascinating.' Never rounds up. Counterpoint to any argument that relies on gut instinct." - -[agents.mccoy] -team = "startrek" -name = "Dr. Leonard McCoy" -title = "Chief Medical Officer" -icon = "⚕️" -description = "Country doctor's warmth, short fuse. 'Dammit Jim, I'm a doctor not a ___.' Ethics-driven counterweight to Spock." -``` - -让 party-mode "邀请企业号船员"，它会按 `team = "startrek"` 过滤并生成 Spock 和 McCoy。真实的 BMad 智能体（Mary、Amelia）也可以同桌。 - -### 5c. 锁定团队安装设置 - -安装器会向每个开发者提示 `planning_artifacts` 路径等值。当组织需要一个统一答案时，在中央配置中锁定——任何开发者本地的提示回答都会在解析时被覆盖： - -```toml -# _bmad/custom/config.toml - -[modules.bmm] -planning_artifacts = "{project-root}/shared/planning" -implementation_artifacts = "{project-root}/shared/implementation" - -[core] -document_output_language = "English" -``` - -个人设置如 `user_name`、`communication_language` 或 `user_skill_level` 留在各开发者自己的 `_bmad/config.user.toml` 中。团队文件不应触碰这些。 - -**为什么用中央配置而不是逐智能体的 customize.toml：** 逐智能体文件塑造*一个*智能体激活时的行为。中央配置塑造花名册消费者*查看全局时看到的内容：*有哪些智能体、叫什么、属于哪个团队，以及整个仓库共识的安装设置。两个层面，各司其职。 - -## 在 IDE 会话文件中强化全局规则 - -BMad 的自定义在技能激活时加载。许多 IDE 工具还会在**每次会话开始时**加载一个全局指令文件，在任何技能运行之前（`CLAUDE.md`、`AGENTS.md`、`.cursor/rules/`、`.github/copilot-instructions.md` 等）。对于即使在 BMad 技能之外也应生效的规则，请在全局指令中也声明一份。 - -**何时需要"双重声明"：** -- 规则足够重要，即使在普通对话（没有激活技能）中也应遵守 -- 你需要"双保险"，因为模型的训练数据默认值可能会拉偏方向 -- 规则足够精简，重复一次不会让会话文件臃肿 - -**示例：在仓库的 `CLAUDE.md` 中强化方案 1 的开发智能体规则。** - -```markdown - -``` - -一句话，每次会话加载。它与 `bmad-agent-dev.toml` 自定义配合，使规则在 Amelia 的工作流内和与助手的临时对话中都生效。各层各管各的范围： - -| 层 | 作用范围 | 用途 | -|---|---|---| -| IDE 会话文件（`CLAUDE.md` / `AGENTS.md`） | 每次会话，在任何技能激活之前 | 简短的、应在 BMad 之外也生效的通用规则 | -| BMad 智能体自定义 | 该智能体分发的每个工作流 | 智能体人设相关的行为 | -| BMad 工作流自定义 | 单次工作流运行 | 工作流特定的输出格式、发布钩子、模板 | -| BMad 中央配置 | 花名册 + 共享安装设置 | 谁在场、团队使用的共享路径 | - -IDE 会话文件要**精简**。十几行精挑细选的规则比长篇大论有效得多。模型每轮都会读取它，噪声会淹没信号。 - -## 组合使用 - -五个方案可以自由组合。一个典型的企业级 `bmad-product-brief` 覆盖可能同时设置 `persistent_facts`（方案 2）、`on_complete`（方案 3）和 `brief_template`（方案 4）。智能体级规则（方案 1）在另一个以智能体命名的文件中，中央配置（方案 5）锁定共享花名册和团队设置，四者并行生效。 - -```toml -# _bmad/custom/bmad-product-brief.toml（工作流级） - -[workflow] -persistent_facts = ["..."] -brief_template = "{project-root}/docs/enterprise/brief-template.md" -on_complete = """ ... """ -``` - -```toml -# _bmad/custom/bmad-agent-analyst.toml（智能体级——Mary 分发 product-brief） - -[agent] -persistent_facts = ["Always include a 'Regulatory Review' section when the domain involves healthcare, finance, or children's data."] -``` - -效果：Mary 在人设激活时加载监管评审规则。当用户选择 product-brief 菜单项时，工作流加载自己的规范、写入企业模板，完成后发布到 Confluence。每一层各有贡献，且无一需要编辑 BMad 源码。 - -## 故障排查 - -**覆盖没有生效？** 检查文件是否在 `_bmad/custom/` 下且使用了准确的技能目录名（如 `bmad-agent-dev.toml`，而非 `bmad-dev.toml`）。参见[如何自定义 BMad](./customize-bmad.md)。 - -**MCP 工具名称不确定？** 使用 MCP 服务器在当前会话中暴露的准确名称。如果不确定，让 Claude Code 列出可用的 MCP 工具。在 `persistent_facts` 或 `on_complete` 中硬编码的名称，在 MCP 服务器未连接时不会生效。 - -**方案不适用于你的场景？** 以上方案是示例性的。底层机制（三层合并、结构化规则、智能体贯穿工作流）支持更多模式，按需组合即可。 diff --git a/docs/zh-cn/how-to/get-answers-about-bmad.md b/docs/zh-cn/how-to/get-answers-about-bmad.md deleted file mode 100644 index d2061af225..0000000000 --- a/docs/zh-cn/how-to/get-answers-about-bmad.md +++ /dev/null @@ -1,129 +0,0 @@ ---- -title: "如何获取关于 BMad 的答案" -description: 使用 LLM 快速回答您自己的 BMad 问题 -sidebar: - order: 4 ---- - -## 先从 BMad-Help 开始 - -**获取 BMad 相关答案最快的方式是 `bmad-help` 技能。** 这个智能向导可以覆盖 80% 以上的常见问题，并且你在 IDE 里随时可用。 - -BMad-Help 不只是查表工具，它还能： -- **检查你的项目状态**，判断哪些步骤已经完成 -- **理解自然语言问题**，直接按日常表达提问即可 -- **根据已安装模块给出选项**，只展示与你当前场景相关的内容 -- **在工作流结束后自动运行**，明确告诉你下一步做什么 -- **指出第一个必做任务**，避免猜流程起点 - -### 如何使用 BMad-Help - -在 AI 会话里直接输入： - -``` -bmad-help -``` - -:::tip -按平台不同，你也可以使用 `/bmad-help` 或 `$bmad-help`。但大多数情况下直接输入 `bmad-help` 就能工作。 -::: - -也可以结合自然语言问题一起调用： - -``` -bmad-help 我有一个 SaaS 想法并且已经知道主要功能，我该从哪里开始？ -bmad-help 我在 UX 设计方面有哪些选项？ -bmad-help 我卡在 PRD 工作流了 -bmad-help 帮我看看目前完成了什么 -``` - -BMad-Help 通常会返回： -- 针对你当前情况的建议路径 -- 第一个必做任务 -- 后续整体流程概览 - -## 何时使用这篇指南 - -当你遇到以下情况时，可用本指南补充： -- 想理解 BMad 的架构设计或内部机制 -- 需要超出 BMad-Help 覆盖范围的答案 -- 在安装前做技术调研 -- 想直接基于源码进行追问 - -## 步骤 - -### 1. 选择信息来源 - -| 来源 | 适合回答的问题 | 示例 | -| --- | --- | --- | -| **`_bmad` 文件夹** | 智能体、工作流、提示词如何工作 | “PM 智能体具体做什么？” | -| **完整 GitHub 仓库** | 版本历史、安装器、整体架构 | “v6 主要改了什么？” | - -安装 BMad 后会生成 `_bmad` 文件夹；如果你还没有安装，可先克隆仓库。 - -### 2. 让 AI 读取来源 - -**如果你的 AI 可以直接读文件（如 Claude Code、Cursor）：** - -- **已安装 BMad：** 直接让它读取 `_bmad` 并提问 -- **想看更深上下文：** 克隆[完整仓库](https://github.com/bmad-code-org/BMAD-METHOD) - -**如果你使用 ChatGPT 或 Claude.ai：** - -打开 [BMad 文档站点](https://docs.bmad-method.org/)。 - -### 3. 直接提问 - -:::note[示例] -**问：** “用 BMad 做一个需求到实现的最短路径是什么？” - -**答：** 运行 `bmad-build`。输入直接意图、issue、规格或已规划 story；workflow 会利用现有上下文并选择所需的澄清、规划、实现和审查深度。 -::: - -## 你将获得什么 - -你可以快速拿到直接、可执行的答案：智能体怎么工作、工作流做什么、为什么这样设计，而不需要等待外部回复。 - -## 提示 - -- **对“意外答案”做二次核验**：LLM 偶尔会答偏，建议回看源码或到 Discord 确认 -- **问题越具体越好**：例如“PRD 工作流第 3 步在做什么？”比“PRD 怎么用？”更高效 - -## 仍然卡住？ - -如果你已经试过 LLM 方案但还需要协助，现在你通常已经能提出一个更清晰的问题。 - -| 频道 | 适用场景 | -| --- | --- | -| `#bmad-method-help` | 快速问题（实时聊天） | -| `help-requests` forum | 复杂问题（可检索、可沉淀） | -| `#suggestions-feedback` | 建议与功能诉求 | -| `#report-bugs-and-issues` | Bug 报告 | - -**Discord：** [discord.gg/gk8jAdXWmj](https://discord.gg/gk8jAdXWmj) -**GitHub Issues：** [github.com/bmad-code-org/BMAD-METHOD/issues](https://github.com/bmad-code-org/BMAD-METHOD/issues)（用于可复现问题） - -*你！* -  *卡住* -    *在队列中——* -      *等待* -        *等待谁？* - -*来源* -  *就在那里，* -    *显而易见！* - -*指向* -  *你的机器。* -    *释放它。* - -*它读取。* -  *它说话。* -    *尽管问——* - -*为什么要等* -  *明天* -    *当你拥有* -      *今天？* - -        *—Claude* diff --git a/docs/zh-cn/how-to/install-bmad.md b/docs/zh-cn/how-to/install-bmad.md deleted file mode 100644 index b31c3be919..0000000000 --- a/docs/zh-cn/how-to/install-bmad.md +++ /dev/null @@ -1,117 +0,0 @@ ---- -title: "如何安装 BMad" -description: 在项目中安装 BMad 的分步指南 -sidebar: - order: 1 ---- - -使用 `npx bmad-method install` 在项目中安装 BMad，并按需选择模块和 AI 工具。 - -## 何时使用 - -- 使用 BMad 启动新项目 -- 将 BMad 添加到现有代码库 -- 更新现有的 BMad 安装 - -:::note[前置条件] -- **Node.js** 20.12+（安装程序必需） -- **Git**（推荐） -- **AI 工具**（Claude Code、Cursor 或类似工具） -::: - -## 步骤 - -### 1. 运行安装程序 - -```bash -npx bmad-method install -``` - -:::tip[想要最新预发布版本？] -使用 `next` 发布标签： -```bash -npx bmad-method@next install -``` - -这会更早拿到新改动，但相比默认安装通道，出现变动的概率也更高。 -::: - -:::tip[前沿版本] -要从主分支安装最新版本（可能不稳定）： -```bash -npx github:bmad-code-org/BMAD-METHOD install -``` -::: - -### 2. 选择安装位置 - -安装程序会询问在哪里安装 BMad 文件： - -- 当前目录（如果你自己创建了目录并从该目录运行，推荐用于新项目） -- 自定义路径 - -### 3. 选择你的 AI 工具 - -选择你使用的 AI 工具： - -- Claude Code -- Cursor -- 其他 - -每种工具都有自己的 skills 集成方式。安装程序会生成用于激活工作流和智能体的轻量提示文件，并放到该工具约定的位置。 - -:::note[启用 Skills] -某些平台需要你在设置中手动启用 skills 才会显示。如果你已经安装 BMad 但看不到 skills，请检查平台设置，或直接询问你的 AI 助手如何启用 skills。 -::: - -### 4. 选择模块 - -安装程序会显示可用的模块。选择你需要的模块——大多数用户只需要 **BMad Method**（软件开发模块）。 - -### 5. 按照提示操作 - -安装程序会引导你完成剩余步骤——设置、工具集成等。 - -## 你将获得 - -以下目录结构仅作示例。工具相关目录会随你选择的平台变化（例如可能是 -`.claude/skills`、`.cursor/skills` 或 `.kiro/skills`），并不一定会同时出现。 - -```text -your-project/ -├── _bmad/ -│ ├── bmm/ # 你选择的模块 -│ │ └── config.yaml # 模块设置（后续如需可修改） -│ ├── core/ # 必需核心模块 -│ └── ... -├── _bmad-output/ # 生成产物 -├── .claude/ # Claude Code skills（如使用 Claude Code） -│ └── skills/ -│ ├── bmad-help/ -│ ├── bmad-persona/ -│ └── ... -└── .cursor/ # Cursor skills（如使用 Cursor） - └── skills/ - └── ... -``` - -## 验证安装 - -运行 `bmad-help` 来验证一切正常并查看下一步操作。 - -**BMad-Help 是你的智能向导**，它会： -- 确认你的安装正常工作 -- 根据你安装的模块显示可用内容 -- 推荐你的第一步 - -你也可以向它提问： -``` -bmad-help 我刚安装完成，应该先做什么？ -bmad-help 对于 SaaS 项目我有哪些选项？ -``` - -## 故障排除 - -**安装程序抛出错误**——将输出复制粘贴到你的 AI 助手中，让它来解决问题。 - -**安装程序工作正常但后续出现问题**——你的 AI 需要 BMad 上下文才能提供帮助。请参阅[如何获取关于 BMad 的答案](./get-answers-about-bmad.md)了解如何将你的 AI 指向正确的来源。 diff --git a/docs/zh-cn/how-to/install-custom-modules.md b/docs/zh-cn/how-to/install-custom-modules.md deleted file mode 100644 index bf0bf54818..0000000000 --- a/docs/zh-cn/how-to/install-custom-modules.md +++ /dev/null @@ -1,181 +0,0 @@ ---- -title: "安装自定义和社区模块" -description: 从社区注册表、Git 仓库或本地路径安装第三方模块 -sidebar: - order: 2 ---- - -使用 BMad 安装程序从社区注册表、第三方 Git 仓库或本地文件路径添加模块。 - -## 何时使用 - -- 从 BMad 注册表安装社区贡献的模块 -- 从第三方 Git 仓库安装模块（GitHub、GitLab、Bitbucket、自托管） -- 使用 BMad Builder 测试本地开发中的模块 -- 从私有或自托管 Git 服务器安装模块 - -:::note[前置条件] -需要 [Node.js](https://nodejs.org) v20.12+ 和 `npx`（npm 自带）。自定义和社区模块可以在全新安装时选择，也可以添加到现有安装中。 -::: - -## 社区模块 - -社区模块收录在 [BMad 插件市场](https://github.com/bmad-code-org/bmad-plugins-marketplace)。它们按类别组织，并锁定在经过审核的 commit 上以确保安全。 - -### 1. 运行安装程序 - -```bash -npx bmad-method install -``` - -### 2. 浏览社区目录 - -选择官方模块后，安装程序会询问： - -``` -Would you like to browse community modules? -``` - -选择 **Yes** 进入目录浏览器。你可以： - -- 按类别浏览 -- 查看推荐模块 -- 查看所有可用模块 -- 按关键词搜索 - -### 3. 选择模块 - -从任意类别中选取模块。安装程序显示描述、版本和信任等级。已安装的模块会预选以便更新。 - -### 4. 继续安装 - -选择社区模块后，安装程序将继续到自定义来源，然后是工具/IDE 配置及其余安装流程。 - -## 自定义来源（Git URL 和本地路径） - -自定义模块可以来自任何 Git 仓库或本地目录。安装程序会解析来源、分析模块结构，并将其与其他模块一起安装。 - -### 交互式安装 - -安装过程中，在社区模块步骤之后，安装程序会询问： - -``` -Would you like to install from a custom source (Git URL or local path)? -``` - -选择 **Yes**，然后提供来源： - -| 输入类型 | 示例 | -| -------- | ---- | -| HTTPS URL（任意主机） | `https://github.com/org/repo` | -| HTTP URL（任意主机） | `http://host/org/repo` | -| 带子目录的 HTTPS URL | `https://github.com/org/repo/tree/main/my-module` | -| SSH URL | `git@github.com:org/repo.git` | -| 本地路径 | `/Users/me/projects/my-module` | -| 使用 ~ 的本地路径 | `~/projects/my-module` | - -安装程序会克隆仓库（URL 来源）或直接从磁盘读取（本地路径），然后展示发现的模块供你选择。 - -### 非交互式安装 - -使用 `--custom-source` 标志从命令行安装自定义模块： - -```bash -npx bmad-method install \ - --directory . \ - --custom-source /path/to/my-module \ - --tools claude-code \ - --yes -``` - -提供 `--custom-source` 但未指定 `--modules` 时，只安装 core 和自定义模块。要同时包含官方模块，需添加 `--modules`： - -```bash -npx bmad-method install \ - --directory . \ - --modules bmm \ - --custom-source https://gitlab.com/myorg/my-module \ - --tools claude-code \ - --yes -``` - -多个来源可用逗号分隔： - -```bash ---custom-source /path/one,https://github.com/org/repo,/path/two -``` - -## 模块发现机制 - -安装程序使用两种模式在来源中查找可安装的模块： - -| 模式 | 触发条件 | 行为 | -| ---- | -------- | ---- | -| 发现模式 | 来源包含 `.claude-plugin/marketplace.json` | 列出清单中的所有插件；你选择要安装哪些 | -| 直接模式 | 未找到 marketplace.json | 扫描目录中的 skill（包含 `SKILL.md` 的子目录），作为单个模块解析 | - -发现模式适用于已发布的模块。直接模式适合本地开发时指向 skills 目录。 - -:::note[关于 `.claude-plugin/`] -`.claude-plugin/marketplace.json` 路径是多个 AI 工具安装程序采用的标准约定，用于插件可发现性。它不依赖 Claude，不使用 Claude API，也不影响你使用哪个 AI 工具。任何包含此文件的模块都可以被遵循此约定的安装程序发现。 -::: - -## 本地开发工作流 - -如果你正在使用 [BMad Builder](https://github.com/bmad-code-org/bmad-builder) 构建模块，可以直接从工作目录安装： - -```bash -npx bmad-method install \ - --directory ~/my-project \ - --custom-source ~/my-module-repo/skills \ - --tools claude-code \ - --yes -``` - -本地来源通过路径引用，不会复制到缓存。当你更新模块源码并重新安装时，安装程序会获取最新变更。 - -:::caution[来源移除] -如果你在安装后删除了本地来源目录，`_bmad/` 中已安装的模块文件会保留。在恢复来源路径之前，该模块在更新时会被跳过。 -::: - -## 安装结果 - -安装后，自定义模块与官方模块一起出现在 `_bmad/` 中： - -``` -your-project/ -├── _bmad/ -│ ├── core/ # 内置核心模块 -│ ├── bmm/ # 官方模块（如已选择） -│ ├── my-module/ # 你的自定义模块 -│ │ ├── my-skill/ -│ │ │ └── SKILL.md -│ │ └── module-help.csv -│ └── _config/ -│ └── manifest.yaml # 跟踪所有模块、版本和来源 -└── ... -``` - -manifest 记录每个自定义模块的来源（Git 来源为 `repoUrl`，本地来源为 `localPath`），以便快速更新时能重新定位来源。 - -## 更新自定义模块 - -自定义模块参与正常的更新流程： - -- **快速更新**（`--action quick-update`）：从原始来源刷新所有模块。基于 Git 的模块会重新拉取；本地模块会从来源路径重新读取。 -- **完整更新**：重新运行模块选择，你可以添加或移除自定义模块。 - -## 创建自己的模块 - -使用 [BMad Builder](https://github.com/bmad-code-org/bmad-builder) 创建可供他人安装的模块： - -1. 运行 `bmad-module-builder` 搭建模块结构 -2. 使用各种 BMad Builder 工具添加 skill、agent 和 workflow -3. 发布到 Git 仓库或共享文件夹集合 -4. 他人使用 `--custom-source ` 安装 - -要让模块支持发现模式，请在仓库根目录包含 `.claude-plugin/marketplace.json`（这是跨工具约定，非 Claude 专属）。格式详见 [BMad Builder 文档](https://github.com/bmad-code-org/bmad-builder)。 - -:::tip[先在本地测试] -开发期间，使用本地路径安装模块以快速迭代，发布到 Git 仓库之前先确认一切正常。 -::: diff --git a/docs/zh-cn/how-to/pressure-test-an-idea.md b/docs/zh-cn/how-to/pressure-test-an-idea.md deleted file mode 100644 index c39e4a1975..0000000000 --- a/docs/zh-cn/how-to/pressure-test-an-idea.md +++ /dev/null @@ -1,55 +0,0 @@ ---- -title: "压测一个想法" -description: 用 bmad-forge-idea skill 在投入之前强化、验证或淘汰一个想法 -sidebar: - order: 10 ---- - -用 `bmad-forge-idea` skill 把半成型的想法放到对抗式提问下。要么带着 earned conviction 活下来，要么廉价地死掉。 - -## 何时使用 - -- 你有一个想法，想在投入时间和金钱之前 stress-test -- 你想要诚实的 kill/read，不是鼓励 -- 你在决策的几个分支间选择，需要每个都 resolve -- 想法在已有项目里，需要对照现有内容检验 - -## 何时跳过 - -- 还没有想法，需要生成选项 —— 用 `bmad-brainstorming` -- 已承诺做产品，要 customer-first 验证 —— 用 `bmad-prfaq` -- 要让 agent 一起讨论或决策 —— 用 `bmad-party-mode` - -:::note[前置条件] -无。forge 在普通对话里就能跑。已安装的 agent 和配置好的 persona roster 会让会话更丰富，但没有也能工作。 -::: - -## 运行一次会话 - -### 1. 调用 skill - -在 IDE 里输入 `bmad-forge-idea`，或说「forge an idea」「pressure-test this」。在同一条消息里说出想法，或等第一个问题。 - -### 2. 说明目标 - -告诉 forge 你要什么：强化想法、prove 或 kill，或只是想清楚。目标 steer 提问。Prove 先打 load-bearing claim；hardening 驱动每个分支 resolve 到答案。 - -### 3. 一次一个分支，捍卫你的思路 - -审问者一次只问一个问题，并给出推荐答案供你推。诚实回答。当它 challenge 模糊术语或与项目不符的说法时，先 settle 再往下。 - -### 4. 掌舵房间 - -每个分支来两个声音——一个来自 roster，一个由话题 conjure。按名字 call persona、召唤已保存 party，或说「adversarial on this」让某个 claim 被攻击、你来辩护。 - -### 5. 落地退出 - -驱动每个分支 resolve，直到想法 hardened、killed，或 simply clearer。你说结束，或让 forge 来 call。 - -## 你会得到什么 - -forge 每次运行都会写一份自洽的 `forge-report.html`，按结果打标记。hardened 的想法还会 distill 成 `forged-idea.md`，记录锁定的决定以及 killed 的内容及原因。该文件可喂给 `bmad-spec`、`bmad-prd` 或 `bmad-prfaq` 做产品概念。killed 或 clarified 的会话不需要额外 artifact；报告本身就够了。 - -:::tip[让它 kill 掉想法] -廉价地发现想法站不住，就是赢。别把会话 steer 向 yes。 -::: diff --git a/docs/zh-cn/how-to/project-context.md b/docs/zh-cn/how-to/project-context.md deleted file mode 100644 index 8226563a90..0000000000 --- a/docs/zh-cn/how-to/project-context.md +++ /dev/null @@ -1,132 +0,0 @@ ---- -title: "管理项目上下文" -description: 创建并维护 project-context.md 以指导 AI 智能体 -sidebar: - order: 8 ---- - -使用 `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：选择路径 - -**手动创建** — 适合你已经明确知道要沉淀哪些规则 - -**架构后生成** — 适合把 solutioning 阶段形成的架构决策沉淀下来 - -**为既有项目生成** — 适合从现有代码库中自动发现团队约定与模式 - -## 步骤 2：创建文件 - -### 选项 A：手动创建 - -在 `_bmad-output/project-context.md` 创建文件： - -```bash -mkdir -p _bmad-output -touch _bmad-output/project-context.md -``` - -然后补充技术栈与实现规则： - -```markdown ---- -project_name: '我的项目' -user_name: '你的名字' -date: '2026-02-15' -sections_completed: ['technology_stack', 'critical_rules'] ---- - -# AI 智能体项目上下文 - -## 技术栈与版本 - -- Node.js 20.x, TypeScript 5.3, React 18.2 -- 状态管理：Zustand -- 测试：Vitest, Playwright -- 样式：Tailwind CSS - -## 关键实现规则 - -**TypeScript：** -- 开启严格模式，禁止使用 `any` 类型 -- 对外 API 使用 `interface`，联合类型使用 `type` - -**代码组织：** -- 组件放在 `/src/components/`，并与测试文件同目录（co-located） -- API 调用统一使用 `apiClient` 单例，不要直接使用 `fetch` - -**测试：** -- 单元测试聚焦业务逻辑 -- 集成测试使用 MSW 模拟 API -``` - -### 选项 B：架构后生成 - -在新的会话中运行： - -```bash -bmad-generate-project-context -``` - -该工作流会扫描架构文档和项目文件，生成能够反映已做决策的上下文文件。 - -### 选项 C：为既有项目生成 - -对于既有项目，运行： - -```bash -bmad-generate-project-context -``` - -该工作流会分析代码库中的约定，然后生成可供你审阅和完善的上下文文件。 - -## 步骤 3：验证内容 - -审查生成文件，并确认它覆盖了： - -- 正确的技术版本 -- 你的真实约定（不是通用最佳实践） -- 能预防常见错误的规则 -- 框架相关模式 - -如果有缺漏或误判，直接手动补充和修正。 - -## 你将获得 - -一个 `project-context.md` 文件，它可以： - -- 确保所有智能体遵循相同约定 -- 避免在不同用户故事（story）中出现不一致决策 -- 为实施阶段保留架构决策 -- 作为项目模式与规则的长期参考 - -## 提示 - -:::tip[最佳实践] -- **聚焦“不明显但重要”的规则**：优先记录智能体容易漏掉的项目约束，而不是 - “变量要有意义”这类通用建议。 -- **保持精简**：此文件会被多数实现工作流加载，过长会浪费上下文窗口。避免写入 - 只适用于单一 story 的细节。 -- **按需更新**：当团队约定变化时手动更新，或在架构发生较大变化后重新生成。 -- **适用于统一实施 workflow**：无论直接进入还是经过深入规划，都共享同一个 `bmad-build` 循环。 -::: - -## 后续步骤 - -- [**项目上下文说明**](../explanation/project-context.md) - 了解其工作原理 -- [**工作流程图**](../reference/workflow-map.md) - 查看哪些工作流会加载项目上下文 diff --git a/docs/zh-cn/how-to/quick-fixes.md b/docs/zh-cn/how-to/quick-fixes.md deleted file mode 100644 index d3261ed7ab..0000000000 --- a/docs/zh-cn/how-to/quick-fixes.md +++ /dev/null @@ -1,95 +0,0 @@ ---- -title: "快速修复" -description: 如何进行快速修复和临时更改 -sidebar: - order: 5 ---- - -Bug 修复、重构或小范围改动可以在很少甚至没有上游规划的情况下直接进入 **Build**。这与完整规划 story 使用的是同一个实施 workflow。 - -## 何时使用本指南 - -- 原因明确且已知的 bug 修复 -- 包含在少数文件中的小型重构（重命名、提取、重组） -- 次要功能调整或配置更改 -- 依赖更新 - -:::note[前置条件] -- 已安装 BMad Method（`npx bmad-method install`） -- AI 驱动的 IDE（Claude Code、Cursor 或类似工具） -::: - -## 步骤 - -### 1. 开启新会话 - -在 AI IDE 中开启一个**全新的聊天会话**。复用之前工作流留下的会话，容易引发上下文冲突。 - -### 2. 提供你的意图 - -Build 支持自由表达意图，你可以在调用前、调用时或调用后补充说明。示例： - -```text -run build — 修复允许空密码的登录验证 bug。 -``` - -```text -run build — fix https://github.com/org/repo/issues/42 -``` - -```text -run build — 实现 _bmad-output/implementation-artifacts/my-intent.md 中的意图 -``` - -```text -我觉得问题在 auth 中间件，它没有检查 token 过期。 -让我看看... 是的，src/auth/middleware.ts 第 47 行完全跳过了 -exp 检查。run build -``` - -```text -run build -> 你想做什么？ -重构 UserService 以使用 async/await 而不是回调。 -``` - -纯文本、文件路径、GitHub issue 链接、缺陷跟踪地址都可以，只要 LLM 能解析成明确意图。 - -### 3. 回答问题并批准 - -Build 可能会先问澄清问题，或在实现前给出一份简短方案供你确认。回答问题后，在你认可方案时再批准继续。 - -### 4. 审查和推送 - -Build 会实现改动、执行自检并修补问题，然后在本地提交。完成后，它会在编辑器中打开受影响文件。 - -- 快速浏览 diff，确认改动符合你的意图 -- 如果有偏差，直接告诉智能体要改什么，它可以在同一会话里继续迭代 - -确认无误后推送提交。Build 会提供推送和创建 PR 的选项。 - -:::caution[如果出现问题] -如果推送的更改导致意外问题，请使用 `git revert HEAD` 干净地撤销最后一次提交。然后启动新聊天并再次运行 Build 以尝试不同的方法。 -::: - -## 你将获得 - -- 已应用修复或重构的修改后的源文件 -- 通过的测试（如果你的项目有测试套件） -- 带有约定式提交消息的准备推送的提交 - -## 延迟工作 - -Build 每次只聚焦一个目标。如果你的请求包含多个独立目标，或审查过程中发现与你本次改动无关的存量问题，Build 会把它们记录到 `deferred-work.md`（位于实现产物目录），而不是一次性全都处理。 - -每次运行后都建议看一下这个文件，它就是你的后续待办清单。你可以把其中任何一项在后续新的 Build 会话里单独处理。 - -## 何时增加正式规划 - -在运行同一个 Build 实施循环前，遇到以下情况可增加 PRD、UX、架构或 story 规划： - -- 更改影响多个系统或需要在许多文件中进行协调更新 -- 你不确定范围，需要先进行需求发现 -- 你需要为团队记录文档或架构决策 - -参见 [Build](../explanation/build.md) 了解直接意图与已规划工作如何汇入同一实施循环。 diff --git a/docs/zh-cn/how-to/upgrade-to-v6.md b/docs/zh-cn/how-to/upgrade-to-v6.md deleted file mode 100644 index 4b9565c785..0000000000 --- a/docs/zh-cn/how-to/upgrade-to-v6.md +++ /dev/null @@ -1,111 +0,0 @@ ---- -title: "如何升级到 v6" -description: 从 BMad v4 迁移到 v6 -sidebar: - order: 3 ---- - -使用 BMad 安装程序把 v4 升级到 v6。安装程序会自动识别旧安装，并提供迁移辅助，帮助你在已有项目中平滑过渡。 - -## 何时使用本指南 - -- 你已安装 BMad v4（目录名通常是 `.bmad-method`） -- 你准备迁移到 v6 的统一目录结构 -- 你有要保留的规划产物或进行中的开发工作 - -:::note[前置条件] -- Node.js 20.12+ -- 现有 BMad v4 安装 -::: - -::::caution[先备份再迁移] -如果当前仓库里仍有未提交的重要变更，先完成提交或备份，再执行升级。 -:::: - -## 步骤 - -### 1. 运行安装程序 - -按照[安装程序说明](./install-bmad.md)操作。 - -### 2. 处理旧版安装目录 - -当检测到 v4 时，你有两种处理方式： - -- 允许安装程序自动备份并删除 `.bmad-method` -- 先退出安装流程，再手动清理旧目录 - -如果你把 BMad Method 目录改成了其他名字，需要你自己手动定位并删除。 - -### 3. 清理 IDE 命令与技能目录 - -手动删除旧版 v4 IDE 命令/技能目录。以 Claude Code 为例，请在旧目录中删除以 `bmad` 开头的嵌套目录： - -- `.claude/commands/` - -v6 新技能会安装到： - -- `.claude/skills/` - -### 4. 迁移规划产物 - -**如果你有规划文档（Brief/PRD/UX/Architecture）：** - -把它们移动到 `_bmad-output/planning-artifacts/`，并使用可读的文件名： - -- PRD 文档文件名包含 `PRD` -- 其他文档按类型包含 `brief`、`architecture` 或 `ux-design` -- 分片文档可放在命名清晰的子目录中 - -**如果你仍在规划中：** 建议直接用 v6 工作流重启规划，把现有文档作为输入；新版渐进式发现流程配合 Web 搜索和 IDE 计划模式通常会得到更稳妥的结果。 - -### 5. 迁移进行中的开发工作 - -如果你已经创建或实现了部分用户故事（story）： - -1. 完成 v6 安装 -2. 将 `epics.md` 或 `epics/epic*.md` 放入 `_bmad-output/planning-artifacts/` -3. 运行 Developer 的 `bmad-sprint-planning` 工作流 -4. 告知智能体哪些史诗/故事已经完成 - -## 你将获得 - -**v6 统一结构：** - -```text -your-project/ -├── _bmad/ # 单一安装目录 -│ ├── _config/ # 你的自定义配置 -│ │ └── agents/ # 智能体自定义文件 -│ ├── core/ # 通用核心框架 -│ ├── bmm/ # BMad Method 模块 -│ ├── bmb/ # BMad Builder -│ └── cis/ # Creative Intelligence Suite -└── _bmad-output/ # 输出目录（v4 时代常见为 doc 目录） -``` - -## 模块迁移 - -| v4 模块 | v6 状态 | -| ----------------------------- | ----------------------------------------- | -| `.bmad-2d-phaser-game-dev` | 已集成到 BMGD 模块 | -| `.bmad-2d-unity-game-dev` | 已集成到 BMGD 模块 | -| `.bmad-godot-game-dev` | 已集成到 BMGD 模块 | -| `.bmad-infrastructure-devops` | 已弃用 — 新的 DevOps 智能体即将推出 | -| `.bmad-creative-writing` | 未适配 — 新的 v6 模块即将推出 | - -## 关键差异（旧名/新名） - -| 概念 | v4（旧） | v6（新） | 迁移提示 | -| ------------ | --------------------------------------- | ------------------------------------ | ------------------------------------ | -| **核心框架** | `_bmad-core` 实际上承载的是 BMad Method | `_bmad/core/` 变成通用框架层 | 迁移时不要再把 `_bmad/core/` 当成 Method 本体 | -| **方法模块** | `_bmad-method` | `_bmad/bmm/` | 旧脚本、路径引用需同步更新到 `bmm` | -| **配置方式** | 直接改模块文件 | 每个模块通过 `config.yaml` 管理 | 优先改配置，不要直接改生成文件 | -| **文档读取** | 需要手动区分分片/非分片 | 自动扫描完整文档与分片入口 | 只有在兼容性场景下才建议手动分片 | - -## 后续建议 - -- 升级完成后先运行 `bmad-help`，确认可用工作流与下一步建议 -- 如果是既有项目，补充或更新 `project-context.md`，减少后续实现偏差 -- 在继续开发前，先做一次关键链路验证（安装、命令触发、文档读取） -- 继续阅读：[如何安装 BMad](./install-bmad.md)、[管理项目上下文](./project-context.md) diff --git a/docs/zh-cn/index.md b/docs/zh-cn/index.md deleted file mode 100644 index e9f278e49a..0000000000 --- a/docs/zh-cn/index.md +++ /dev/null @@ -1,56 +0,0 @@ ---- -title: 欢迎使用 BMad 方法 -description: 具备专业智能体、引导式工作流与智能规划的 AI 驱动开发框架 ---- - -BMad 方法（**B**uild **M**ore **A**rchitect **D**reams）是 BMad 方法生态中的 AI 驱动开发框架模块，覆盖从构思、规划到智能体实施的完整软件交付流程。它提供专业智能体、引导式工作流和可随项目复杂度调整的智能规划，无论是修复 bug 还是构建企业级平台都适用。 - -如果你已经习惯使用 Claude、Cursor 或 GitHub Copilot 这类 AI 编码助手，现在就可以开始。 - -## 新手入门？先从教程开始 - -理解 BMad 的最快方式是亲自尝试。 - -- **[BMad 入门教程](./tutorials/getting-started.md)** — 安装并理解 BMad 如何工作 -- **[工作流地图](./reference/workflow-map.md)** — BMM 阶段、工作流与上下文管理的全景视图 - -:::tip[只想直接上手？] -安装 BMad 后运行 `bmad-help`，它会根据你的项目状态和已安装模块给出下一步建议。 -::: - -## 如何使用这些文档 - -这些文档按你的目标分成四个部分： - -| 部分 | 用途 | -| --- | --- | -| **教程** | 学习导向。通过分步引导带你做成一件事。第一次使用建议从这里开始。 | -| **操作指南** | 任务导向。解决具体问题的实用文档，例如“如何自定义智能体”。 | -| **说明** | 理解导向。深入讲解概念与架构，适合回答“为什么”。 | -| **参考** | 信息导向。提供智能体、工作流和配置项的技术规格。 | - -## 扩展与自定义 - -想用自己的智能体、工作流或模块扩展 BMad？**[BMad Builder（英文）](https://bmad-builder-docs.bmad-method.org/)** 提供了创建自定义扩展所需的框架与工具，无论是给 BMad 添加能力，还是从零构建新模块都可以。 - -## 你需要准备什么 - -BMad 可与任何支持自定义系统提示词或项目上下文的 AI 编码助手配合使用，常见选择包括： - -- **[Claude Code](https://code.claude.com)** — Anthropic 的 CLI 工具（推荐） -- **[Cursor](https://cursor.sh)** — AI 优先的代码编辑器 -- **[Codex CLI](https://github.com/openai/codex)** — OpenAI 的终端编码智能体 - -你需要了解一些基础软件工程概念，例如版本控制、项目结构和敏捷工作流。即使没有使用过 BMad 风格智能体系统，也可以从这些文档开始上手。 - -## 加入社区 - -获取帮助、分享成果，或参与贡献： - -- **[Discord](https://discord.gg/gk8jAdXWmj)** — 与其他 BMad 用户聊天、提问、分享想法 -- **[GitHub](https://github.com/bmad-code-org/BMAD-METHOD)** — 源代码、问题和贡献 -- **[YouTube](https://www.youtube.com/@BMadCode)** — 视频教程和演练 - -## 下一步 - -准备好开始了吗？**[从 BMad 入门教程开始](./tutorials/getting-started.md)**，构建你的第一个项目。 diff --git a/docs/zh-cn/reference/agents.md b/docs/zh-cn/reference/agents.md deleted file mode 100644 index ea1a113a8d..0000000000 --- a/docs/zh-cn/reference/agents.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -title: "智能体" -description: 默认 BMM 智能体的 skill ID、触发器与主要 workflow 速查。 -sidebar: - order: 2 ---- - -本页列出 BMad Method 默认提供的 BMM（Agile 套件）智能体，包括它们的 skill ID、菜单触发器和主要 workflow。 - -## 默认智能体列表 - -| 智能体 | Skill ID | 触发器 | 主要 workflow | -| --- | --- | --- | --- | -| Analyst (Mary) | `bmad-analyst` | `BP`、`MR`、`DR`、`TR`、`CB`、`WB`、`DP` | Brainstorm、Market Research、Domain Research、Technical Research、Create Brief、PRFAQ Challenge、Document Project | -| Product Manager (John) | `bmad-pm` | `CP`、`VP`、`EP`、`CE`、`IR`、`CC` | Create/Validate/Edit PRD、Create Epics and Stories、Implementation Readiness、Correct Course | -| Architect (Winston) | `bmad-architect` | `CA`、`IR` | Create Architecture、Implementation Readiness | -| Developer (Amelia) | `bmad-agent-dev` | `BD`、`QA`、`CR`、`SP`、`ER` | Build、QA Test Generation、Code Review、Sprint Planning、Epic Retrospective | -| UX Designer (Sally) | `bmad-ux-designer` | `CU` | Create UX Design | - -:::note[Paige 去哪儿了？] -技术文档工程师 Paige 正在休整——她将在未来以更强大的能力回归。项目文档功能仍然可用：`DP`（Document Project）触发器可通过 Analyst 智能体使用，或直接调用 `bmad-document-project` 技能。 -::: - -## 使用说明 - -- `Skill ID` 是直接调用该智能体的名称（例如 `bmad-agent-dev`） -- 触发器是进入智能体会话后可使用的菜单短码 -- QA 测试生成由 `bmad-qa-generate-e2e-tests` workflow skill 处理，通过 Developer 智能体调用；完整 TEA 能力位于独立模块 - -## 触发器类型 - -触发器会直接启动结构化 workflow。你只需输入触发码，然后按流程提示提供信息。 - -示例：`CP`（Create PRD）、`CA`（Create Architecture）、`BD`（Build） - -## 相关参考 - -- [技能（Skills）参考](./commands.md) -- [工作流地图](./workflow-map.md) -- [核心工具参考](./core-tools.md) diff --git a/docs/zh-cn/reference/build-auto.md b/docs/zh-cn/reference/build-auto.md deleted file mode 100644 index b886567ed6..0000000000 --- a/docs/zh-cn/reference/build-auto.md +++ /dev/null @@ -1,226 +0,0 @@ ---- -title: 自主开发循环 -description: 以 bmad-build-auto 作为单次迭代 worker，自动执行 Build 实施模型的参考说明 -sidebar: - order: 7 ---- - -`bmad-build-auto` 是标准 [Build](../explanation/build.md) 实施模型的无人值守自动化入口。它接受同样广泛的直接意图和已规划工作，保留澄清、规划、实现和审查阶段，同时输出 orchestrator 可处理的终态。它自动执行同一实施循环，不定义第二条实施路径。 - -这里有一条重要的架构边界：`bmad-build-auto` 负责 implementation run 及其生成的 spec artifact，但不负责 backlog policy。当 review 发现真实但不属于当前 story 的问题时，skill 会把 finding 记录在自己负责的 spec 中，仅此而已。是排入队列、去重、升级还是忽略，由 orchestrator 决定。 - -## 它做什么 - -`bmad-build-auto` 执行一次无人值守的开发循环迭代： - -1. 澄清传入 intent -2. 创建（或找到并恢复）spec 文件 -3. 实现变更 -4. 审查结果 -5. 结束时把终端 status 写入 spec 文件或 fallback result artifact - -## 前置条件 - -该 skill 依赖运行 subagent 的能力。若 subagent 不可用，workflow 会以 `blocked` 和 `no subagents` halt。若你在 subagent 会话里调用 skill 本身（例如「嘿 Claude，用 bmad-build-auto skill 跑 story 2–10，每个 story 一个 subagent」），该会话需要能 spawn 自己的 subagent。 - -版本控制可选但强烈建议。若使用，working tree 必须 clean，且 agent 必须能够更新 repository metadata。 - -## 输入 - -### 主要调用输入 - -主输入是 invocation prompt。`bmad-build-auto` 把该 prompt 当作 workflow 输入，而不是 finished implementation plan。 - -支持的 intent 形态包括： - -- 简短的自由格式变更请求 -- ticket、issue 或 story 标识符 -- intent 文件路径 -- 本 workflow 生成的既有 spec 文件路径 -- spec 文件夹 + story id，无具体 spec 文件路径（**folder+id dispatch** —— 见下文） - -### 恢复输入 - -若调用指向 frontmatter 里 `status` 为已知值的既有 spec 文件，workflow 从该状态恢复： - -| Spec status | 入口 | -| --- | --- | -| `draft` | plan | -| `ready-for-dev` | implement | -| `in-progress` | implement | -| `in-review` | review | -| `done` | 作为新的 follow-up pass 再 review | -| `blocked` | 立即 halt | - -### Folder+ID Dispatch - -调用 prompt 可传 spec 文件夹和 story id，而不传 spec 文件路径。任何额外 prompt 文本（例如 caller 追加的 `invoke_dev_with` 指引）作为额外 planning 上下文携带，而不是对工作的 competing 描述。 - -workflow 读取 `/stories.yaml`，查找 `id` 匹配的条目。它只取该条目的 `title` 和 `description` —— `spec_checkpoint`、`done_checkpoint`、`invoke_dev_with` 是 dispatching caller 的字段，不会从文件本身读取。 - -然后检查 `/stories/-*.md`（id 前缀匹配），区分首次 dispatch 与 resume： - -| 磁盘匹配 | 结果 | -| --- | --- | -| 无 | 首次 dispatch。要求 `/SPEC.md` 存在（否则 halt `blocked` / `no epic spec found`）。加载 `SPEC.md` 及其 companion，然后进入 planning。 | -| 恰好一个 | Resume：按该文件 `status` 路由，与 Resume Input 表相同。此处 `blocked` 报告 blocking condition `story already blocked`，不是 `blocked spec supplied` —— build-auto 通过 id 发现文件，caller 没有 handed blocked spec。缺失或无法识别的 `status` 则 halt `blocked` / `unrecognized status in existing story file`。 | -| 多于一个 | Halt `blocked` / `ambiguous story file match`。 | - -`blocked` story 文件是永久的：该 id 的后续 dispatch 都会 halt `story already blocked`，即使原因已修复。要重试，删除 story 文件 —— id 会读作 pending，下次 dispatch 从头开始。 - -只要 planning 运行 —— 首次 dispatch，或中断 planning（`draft`）的 resume —— workflow 还会加载 `/stories/*.md` 的每个其他匹配文件，把各自的 Code Map、Design Notes、Spec Change Log、Tasks & Acceptance checklist 状态和 Auto Run Result 细节作为额外 planning 上下文，以便一个 story 的 planning 能看到同文件夹其他 story 已决定或产出的内容。跳过 planning 的 resume 也跳过这一步。 - -每次 invocation 只 dispatch 恰好一个 `stories.yaml` 条目：无论结果如何，workflow 不会读其他条目或 advance 到其他 story id。 - -### 上下文输入 - -激活时，workflow 解析： - -- `_bmad/config.toml`、`_bmad/config.user.toml`，以及 `_bmad/custom/` 下可选的团队/用户 override -- `customize.toml`、团队 override、用户 override 中的 workflow 自定义 -- workflow 配置中列出的 persistent facts —— 除非你主动添加，否则为空，默认不会加载任何内容 - -还可能查看： - -- BMAD planning artifacts -- epic 工作的 cached 或新编译 epic context 文件 -- 同一 epic 最近完成的 prior-story spec，以保持 continuity -- folder+id dispatch 下同 spec 文件夹的其他 `stories/*.md` 记录（见 Folder+ID Dispatch） - -## Spec Status - -spec frontmatter 的 `status` 是 orchestration 的主要 machine-readable 状态： - -| Spec Status | 含义 | -| --- | --- | -| `draft` | Spec 存在但未通过 ready-for-dev 校验 | -| `ready-for-dev` | Spec 足够完整可 implement | -| `in-progress` | Implementation 进行中 | -| `in-review` | Review/triage 进行中 | -| `done` | Workflow 成功完成 | -| `blocked` | Workflow 无法安全 unattended 继续 | - -### Deferred Findings - -`deferred` 用于记录 skill 发现的真实问题，但这些问题不属于当前 story。每个条目包含： - -- `summary` —— deferred issue 的单句描述 -- `evidence` —— 证明 finding 真实存在的依据 -- `location` —— 可选的 file:line 或 component 提示 -- `severity` —— 可选的最终 triage severity（`high`、`medium`、`low`） - -它不是 backlog，而是 machine-readable review output。Orchestrator 必须决定下一步：创建 ticket、追加到 central queue、关联多次 run 中的重复项，或不做处理。 - -### 在 `ready-for-dev` 时 - -`ready-for-dev` 通常是 workflow 直通 implement 的 resume 状态。当 invocation prompt 指示 planning 后 halt 时，它成为真正的 halt 结果：spec 通过 READY FOR DEVELOPMENT gate 后，workflow 设 status `ready-for-dev` 并停在那里，而不是继续 implement。重新 dispatch 同一 spec（或同一 spec 文件夹和 story id）会经上述路由在 implement resume。 - -### 在 `done` 时 - -成功完成时，workflow 写入或更新 spec，包含： - -- 最终 `status: done` -- 含以下内容的 `Auto Run Result` 节： - - 已实现变更摘要 - - 变更文件 - - Review findings breakdown - - 已执行 verification - - Residual risks -- `followup_review_recommended` 标志。若 LLM 认为值得再 review 一轮则为 true。只是建议，非必须。最简单的二次 review 是重新运行 skill 并指向 spec 文件。 -- `baseline_revision` —— implementation 前的完整 canonical revision。无版本控制时为 `NO_VCS`。 -- triage 为 `defer` 的 review findings 会写入 frontmatter 的 `deferred` 条目。每个条目记录 `summary`、`evidence`，以及已知时的 `location` 和 `severity`。 - -Workflow 会 commit，但不会 push。退出时 working copy 是干净的。 - -### 在 `blocked` 时 - -blocked 完成时，workflow 写入： - -- 若 spec 存在则最终 `status: blocked` -- Blocking condition -- Spec 或 fallback result artifact 中的 supporting detail - -典型 blocking conditions 包括： - -- `unclear intent` -- `intent gap` -- `no subagents` -- `missing spec_file before implementation` -- `implementation verification failed` -- `review repair loop exceeded 5 iterations (non-convergence)` -- `blocked spec supplied`（直接调用的 spec 文件已有 `status: blocked`） -- `no stories.yaml found` -- `story id not found in stories.yaml` -- `no epic spec found` -- `ambiguous story file match` -- `unrecognized status in existing story file` -- `story already blocked`（仅 folder+id dispatch —— 与上文 `blocked spec supplied` 对比） - -`intent gap` 表示 captured intent 无法回答 run 碰到的问题 —— 可在 planning step（尚无任何代码）或 review step halt。review 因此 halt 时，working tree 照常 revert，但 attempted change 先保存为 `{implementation_artifacts}` 中的 patch 文件，从 spec triage log 和 halt 输出引用。patch 展示 run 对 intent 的哪种 reading 被 implement —— 修复 intent 的具体证据。若 attempted reading 其实正确，可 `git apply` patch 并把 spec status 设为 `in-review`，在该基础上 resume review，而不是从头重跑。 - -## 输出 Artifacts - -workflow 总是尽量留下 durable artifact 描述发生了什么。 - -### 主 Spec Artifact - -对新工作，workflow 创建： - -`{implementation_artifacts}/spec-.md` - -该 spec 是 planning、implementation 和 review 之间的 contract，包含： - -- Frontmatter status -- Frontmatter machine state（`followup_review_recommended`、`warnings`、`deferred`、revision markers） -- 不可变的 `` 块 -- Code map -- Tasks 和 acceptance criteria -- Spec change log -- Review triage log -- Verification notes - -### Story Spec Artifact（Folder+ID Dispatch） - -folder+id dispatch 下，workflow 写入 `/stories/-.md`，而不是 primary spec 或 fallback result 路径 —— 包括 planning 开始前的 halt。此模式下不使用下文 fallback result artifact。 - -halt 发生在尚无法从 story title derive slug 时，write-back 回退到固定 slug segment： - -| 情况 | 使用的 slug segment | -| --- | --- | -| `stories.yaml` 缺失/无法解析，或无条目匹配 story id | `unresolved` | -| 多于一个磁盘文件已匹配 `-*.md` | `ambiguous` | -| 条目已 resolve 且无磁盘歧义 | 从 `title` derive slug（必要时加 `description`） | - -若 resolved 路径已存在，workflow 更新其 `status` frontmatter 并在 `## Auto Run Result` 下追加 result detail，与 primary spec artifact 相同。若不存在，workflow 创建 skeletal story spec：frontmatter status、标题（条目的 title，或无法 resolve/磁盘匹配 ambiguous 时为 `Story `）、`## Auto Run Result` 节。 - -### Fallback Result Artifact - -workflow 在尚无 valid `spec_file` 时 halt（folder+id dispatch 外 —— 见上），写入： - -`{implementation_artifacts}/bmad-build-auto-result-.md` - -记录 terminal status 和 blocking condition。 - -### 其他 Artifacts - -视路由，workflow 还可能写入： - -- `{implementation_artifacts}/epic--context.md` -- review step 因 `intent gap` halt 时保存 attempted change 的 patch 文件（路径记录在 spec triage log） - -## Orchestrator 职责 - -集成 `bmad-build-auto` 的 orchestrator 应： - -- 一次传一个 coherent intent -- Resume 时优先传 spec 路径 —— 或 folder+id dispatch 下同一 spec 文件夹和 story id -- 监控产出的 spec 文件、story spec artifact 或 fallback result 文件的 terminal state -- 读 `status`、`blocking condition`、`followup_review_recommended`，不要只从 chat 输出推断成功 -- 从 spec frontmatter 的 `deferred:` list 读取 deferred findings -- 用 `baseline_revision..<下一个 story 的 baseline_revision>` 识别该 story 的 commits；还没有下一个 story 时，退出时用 `baseline_revision..HEAD` -- 预期 autonomous 文件变更和 local commits -- 把 `blocked` 当作 routing signal，而不只是 failure signal - -实践中，`blocked` 通常表示 workflow 碰到 unattended 执行会不安全的局面。这往往是更高层 orchestrator、其他 workflow 或人工接手的节点。 - -解决 blocked run 后，orchestrator 通常应启动新的 `bmad-build-auto` run。若要复用 prior work，应传 explicit known-good spec 路径，而不是依赖 implicit discovery。 diff --git a/docs/zh-cn/reference/commands.md b/docs/zh-cn/reference/commands.md deleted file mode 100644 index 1a4ec1744d..0000000000 --- a/docs/zh-cn/reference/commands.md +++ /dev/null @@ -1,120 +0,0 @@ ---- -title: "技能（Skills）" -description: BMad 技能参考：它们是什么、如何生成以及如何调用。 -sidebar: - order: 4 ---- - -每次运行 `npx bmad-method install`，BMad 会基于你选择的模块生成一组 **skills**。你可以直接输入 skill 名称调用 workflow、任务、工具或智能体角色。 - -## Skills 与菜单触发器的区别 - -| 机制 | 调用方式 | 适用场景 | -| --- | --- | --- | -| **Skill** | 直接输入 skill 名（如 `bmad-help`） | 你已明确要运行哪个功能 | -| **智能体菜单触发器** | 先加载智能体，再输入短触发码（如 `BD`） | 你在智能体会话内连续切换任务 | - -菜单触发器依赖“已激活的智能体会话”；skill 可独立运行。 - -## Skills 如何生成 - -安装程序会读取已选模块，为每个 agent / workflow / task / tool 生成一个 skill 目录，目录中包含 `SKILL.md` 入口文件。 - -| Skill 类型 | 生成行为 | -| --- | --- | -| Agent launcher | 加载角色设定并激活菜单 | -| Workflow skill | 加载 workflow 配置并执行步骤 | -| Task skill | 执行独立任务 | -| Tool skill | 执行独立工具 | - -:::note[模块变更后要重装] -当你新增、删除或切换模块后，请重新运行安装程序，避免 skill 列表与模块状态不一致。 -::: - -## Skill 文件位置 - -| IDE / CLI | Skills 目录 | -| --- | --- | -| Claude Code | `.claude/skills/` | -| Cursor | `.cursor/skills/` | -| Windsurf | `.windsurf/skills/` | -| 其他 IDE | 以安装器输出路径为准 | - -示例（Claude Code）： - -```text -.claude/skills/ -├── bmad-help/ -│ └── SKILL.md -├── bmad-prd/ -│ └── SKILL.md -├── bmad-agent-dev/ -│ └── SKILL.md -└── ... -``` - -skill 目录名就是调用名，例如 `bmad-agent-dev/` 对应 skill `bmad-agent-dev`。 - -## 如何发现可用 skills - -- 在 IDE 中直接输入 `bmad-` 前缀查看补全候选 -- 运行 `bmad-help` 获取基于当前项目状态的下一步建议 -- 打开 skills 目录查看完整清单（这是最权威来源） - -:::tip[快速定位] -不确定该跑哪个 workflow 时，先执行 `bmad-help`，通常比人工翻文档更快。 -::: - -## Skill 分类与示例 - -### 智能体技能（Agent Skills） - -加载一个角色化智能体，并保持其 persona 与菜单上下文。 - -| 示例 skill | 角色 | 用途 | -| --- | --- | --- | -| `bmad-agent-dev` | Developer（Amelia） | 按规范实现 story | -| `bmad-pm` | Product Manager（John） | 创建与校验 PRD | -| `bmad-architect` | Architect（Winston） | 架构设计与约束定义 | - -完整列表见 [智能体参考](./agents.md)。 - -### Workflow Skills - -无需先加载 agent，直接运行结构化流程。 - -| 示例 skill | 用途 | -| --- | --- | -| `bmad-prd` | 创建 PRD | -| `bmad-architecture` | 创建架构方案 | -| `bmad-create-epics-and-stories` | 拆分 epics/stories | -| `bmad-code-review` | 代码评审 | -| `bmad-build` | 实施直接意图、issue、功能、修复或已规划 story | - -按阶段查看见 [工作流地图](./workflow-map.md)。 - -### Task / Tool Skills - -独立任务，不依赖特定智能体上下文。 - -**`bmad-help`** 是最常用入口：它会读取项目状态并给出“下一步建议 + 对应 skill”。 - -更多核心任务和工具见 [核心工具参考](./core-tools.md)。 - -## 命名规则 - -所有技能统一以 `bmad-` 开头，后接语义化名称（如 `bmad-agent-dev`、`bmad-prd`、`bmad-help`）。 - -## 故障排查 - -**安装后看不到 skills：** 某些 IDE 需要手动启用 skills，或重启 IDE 才会刷新。 - -**缺少预期 skill：** 可能模块未安装或安装时未勾选。重新运行安装程序并确认模块选择。 - -**已移除模块的 skills 仍存在：** 安装器不会自动清理历史目录。手动删除旧 skill 目录后再重装可获得干净结果。 - -## 相关参考 - -- [智能体参考](./agents.md) -- [核心工具参考](./core-tools.md) -- [模块参考](./modules.md) diff --git a/docs/zh-cn/reference/core-tools.md b/docs/zh-cn/reference/core-tools.md deleted file mode 100644 index 52b907c5c3..0000000000 --- a/docs/zh-cn/reference/core-tools.md +++ /dev/null @@ -1,182 +0,0 @@ ---- -title: '核心工具' -description: 核心模块内置 skills 参考。 -sidebar: - order: 3 ---- - -每个 BMad 安装都包含 **核心模块** —— 一小组跨项目、跨模块、跨阶段通用的 skills。本页覆盖这 7 个核心 skills：4 个内核工具，加上 3 个 **思考类 skills**（brainstorming、forge idea、party mode）。 - -:::tip[快速入口] -在 IDE 中直接输入工具 skill 名（例如 `bmad-help`）即可调用，无需先加载智能体。 -::: - -## 概览 - -**核心模块（始终安装）：** - -| 工具 | 主要用途 | -| --------------------------------------------------------- | -------------------------------------------- | -| [`bmad-help`](#bmad-help) | 基于项目上下文推荐下一步 | -| [`bmad-advanced-elicitation`](#bmad-advanced-elicitation) | 通过多轮技法增强 LLM 输出 | -| [`bmad-review`](#bmad-review) | 多视角批判性审查 —— 对抗、边界条件与验证缺口 | -| [`bmad-customize`](#bmad-customize) | 创建并验证 BMad 自定义覆盖 | - -**思考类 skills：** - -| 工具 | 主要用途 | -| ------------------------------------------- | ---------------------------------------------------- | -| [`bmad-brainstorming`](#bmad-brainstorming) | 引导式头脑风暴与想法扩展 | -| [`bmad-forge-idea`](#bmad-forge-idea) | 压力测试一个想法，直到它站得住、被证实或低成本地淘汰 | -| [`bmad-party-mode`](#bmad-party-mode) | 多智能体协作讨论 | - -:::note[迁移与移除] -`bmad-spec` 现随 BMM 模块作为第 2 阶段规划 workflow 发布 —— 见[工作流地图](./workflow-map.md)。`bmad-shard-doc` 与 `bmad-index-docs` 已移除。原 `bmad-editorial-review`、`bmad-editorial-review-prose`、`bmad-editorial-review-structure`、`bmad-review-adversarial-general`、`bmad-review-edge-case-hunter`、`bmad-review-verification-gap` 已全部合并进 `bmad-review`，其编辑视角取代了原独立的编辑审查 skill；旧 ID 仍可通过转发器解析，保持兼容。 -::: - -## bmad-help - -**定位：** 你的默认导航入口，告诉你“下一步该做什么”。 - -**适用场景：** - -- 刚完成一个 workflow，不确定如何衔接 -- 新接触项目，需要先看当前进度 -- 变更模块后，想知道可用能力和推荐顺序 - -**工作机制：** - -1. 扫描已存在产物（PRD、architecture、stories 等） -2. 检测已安装模块及其可用 workflow -3. 按优先级输出“必需步骤 + 可选步骤” - -**输入：** 可选自然语言问题（如 `bmad-help 我该先做 PRD 还是 architecture？`） -**输出：** 带 skill 名称的下一步建议列表 - -## bmad-advanced-elicitation - -**定位：** 对已有 LLM 输出做第二轮深挖与改写强化。 - -**适用场景：** - -- 结果“看起来对”，但深度不够 -- 想从多个思维框架交叉审视同一内容 -- 想按名字调用已知方法 —— 苏格拉底式、第一性原理、事前验尸、红队 - -**工作机制：** - -1. 默认针对会话中最近一次输出，也可指向其他内容 -2. 给出与内容匹配的候选技法短菜单 -3. 应用所选技法进行强化 -4. 交回改进版本，调用方流程从暂停处继续 - -**输入：** 待增强内容（默认最近输出），可选指定方法名 -**输出：** 增强后的内容版本 - -## bmad-review - -**定位：** 面向任意 diff、文档或产物的多视角审查。统一输出。零发现是合法结果，绝不为“看起来彻底”而凑数。每个视角声明其适用对象：diff 触发代码视角，文档触发编辑视角。 - -**内置视角：** - -| 视角 | 适用于 | 方法 | -| -------------------------------- | ---------------- | ---------------------------------------------------------- | -| **对抗（Adversarial）** | 任意内容 | 强制产出发现（≥10 条），看缺了什么而不只纠错；不允许空列表 | -| **边界条件（Edge case）** | 任意内容 | 走遍定义了行为的内容中的每条分支路径与边界条件 | -| **验证缺口（Verification gap）** | 代码 | 找出可能回归且缺乏可靠验证兜底的行为变更 | -| **结构（Structure）** | 文档 | 提出删减、合并、移动与精简 —— 文档的结构是否服务于其目的？ | -| **文字（Prose）** | 文档 | 针对妨碍理解的表达问题做文字编辑 | - -两个编辑视角视内容为不可侵犯：只审组织与表达，从不质疑观点；只提建议，不直接改写。两者同时选中时，文字视角在结构视角的发现之上运行。 - -这套视角并非固定：`customize.toml` 覆盖可以新增视角或替换内置视角，审查会运行解析后实际生效的那些。 - -**工作机制：** - -1. 加载内容，识别类型（diff、文件、函数或文档）以及属于代码还是文档 -2. 选择视角：你指定的，或所有适用性与条件匹配的已启用视角 -3. announce 执行计划 —— 将运行哪些视角，以及哪些视角在其他视角的发现之上运行 -4. 独立视角先运行 —— 平台支持时通过子代理并行 —— 随后运行依赖它们的视角 -5. 汇总为一个 findings 列表；视角间重叠是信号而非重复 - -**输入：** `content`（必填），`lenses`（可选，默认运行所有适配内容的视角），`also_consider`（可选），`style_guide` / `reader_type`（可选，供编辑视角使用） -**输出：** JSON findings 数组和/或按视角分组的 markdown 报告。可通过 skill 的 `customize.toml` 增加自定义视角，或调整/停用内置视角 - -## bmad-customize - -**定位：** 无需手写 TOML，即可修改已安装 BMad 智能体或 workflow 的行为。 - -**工作机制：** - -1. 扫描已安装 BMad skills 的可自定义面 -2. 为你的变更选择合适的覆盖范围 -3. 在 `_bmad/custom/` 下写入覆盖文件 -4. 验证合并后的配置 - -**输入：** 用自然语言描述想要的自定义 -**输出：** `_bmad/custom/` 下的 TOML 覆盖文件。详见[如何自定义 BMad](../how-to/customize-bmad.md) - -## 思考类 skills - -以下三个 skills 是核心模块的组成部分 —— 任何阶段、任何模块都可以借助的通用思考工具。 - -### bmad-brainstorming - -**定位：** 用结构化创意技法快速扩展想法池。 - -**适用场景：** - -- 启动新主题，想先打开问题空间 -- 团队卡在同一思路，需要外部技法打破惯性 -- 需要把“模糊方向”变成可讨论候选方案 - -**工作机制：** - -1. 建立主题会话 -2. 从方法库选择创意技法 -3. 逐轮引导产出并记录想法 -4. 每 10 个想法切换创意领域，防止聚集偏差 - -**输入：** 主题或问题陈述（可附上下文文件） -**输出：** 自包含的 `brainstorm.html` 会话纪念页、可选的 `brainstorm-intent.md`（供下游 skills 使用）与 `.memlog.md` 会话记录 - -### bmad-forge-idea - -**定位：** 压力测试一个想法，直到它站得住、被证实或低成本地淘汰。 - -**工作机制：** - -1. 先确立目标，并据此调整提问方向 -2. 按依赖顺序一次一个问题，先摆出推荐答案供你反驳 -3. 每个分支引入两个角色声音 —— 一个来自已安装的角色阵容，一个由话题临时召唤 -4. 挑战模糊措辞，并用现有项目材料检验论断 -5. 以 Hardened（站住了）、Killed（淘汰）或 Clearer（更清晰）收尾，附可留存的报告 - -**输入：** 任何领域的想法 —— 功能、商业模式、研究假设、人生决定 -**输出：** 想法站住时的 `forged-idea.md` 提炼稿（可选），加上每次运行的 `forge-report.html` - -### bmad-party-mode - -**定位：** 让多个智能体围绕同一议题协作讨论。 - -**适用场景：** - -- 决策涉及产品、架构、实现、质量等多视角 -- 希望不同角色显式冲突并暴露假设差异 -- 需要在短时间内收集多方案观点 - -**工作机制：** - -1. 读取已安装智能体清单 -2. 选取最相关的 2-3 个角色先发言 -3. 轮换角色、持续交叉讨论 -4. 使用 `goodbye` / `end party` / `quit` 结束 - -**输入：** 讨论主题（可指定希望参与的角色） -**输出：** 多智能体实时对话过程 - -## 相关参考 - -- [技能（Skills）参考](./commands.md) -- [智能体参考](./agents.md) -- [工作流地图](./workflow-map.md) diff --git a/docs/zh-cn/reference/modules.md b/docs/zh-cn/reference/modules.md deleted file mode 100644 index 7ff5f73816..0000000000 --- a/docs/zh-cn/reference/modules.md +++ /dev/null @@ -1,94 +0,0 @@ ---- -title: "官方模块" -description: BMad 可选模块参考：能力边界、适用场景与外部资源 -sidebar: - order: 5 ---- - -BMad 通过可选模块扩展能力。你可以在安装时按需选择模块，为当前项目增加特定领域的 `agent`、`workflow` 与 `skill`。 - -:::tip[安装模块] -运行 `npx bmad-method install`，在交互步骤中勾选所需模块。安装器会自动生成对应 skills 并写入当前 IDE 的 skills 目录。 -::: - -## 先看总览 - -| 模块 | 代码 | 最适合 | 核心能力 | -| --- | --- | --- | --- | -| BMad Builder | `bmb` | 扩展 BMad 本身 | 构建自定义 agent / workflow / module | -| Creative Intelligence Suite | `cis` | 前期创意与问题探索 | 头脑风暴、设计思维、创新策略 | -| Game Dev Studio | `gds` | 游戏方向研发 | 游戏设计文档、原型推进、叙事支持 | -| Test Architect（TEA） | `tea` | 企业级测试治理 | 测试策略、可追溯性、质量门控 | - -## BMad Builder（`bmb`） - -用于“构建 BMad”的元模块，重点是把你的方法沉淀成可复用能力。 - -**你会得到：** -- Agent Builder：创建具备特定专业能力的 agent -- Workflow Builder：设计有步骤与决策点的 workflow -- Module Builder：将 agent/workflow 打包为可发布模块 -- 交互式配置与发布支持（YAML + npm） - -**外部资源（英文）：** -- npm: [`bmad-builder`](https://www.npmjs.com/package/bmad-builder) -- GitHub: [bmad-code-org/bmad-builder](https://github.com/bmad-code-org/bmad-builder) - -## Creative Intelligence Suite（`cis`） - -用于前期探索与创意发散，帮助团队在进入规划前澄清问题与方向。 - -**你会得到：** -- 多个创意向 agent（如创新策略、设计思维、头脑风暴） -- 问题重构与系统化思考支持 -- 常见构思框架（含 SCAMPER、逆向头脑风暴等） - -**外部资源（英文）：** -- npm: [`bmad-creative-intelligence-suite`](https://www.npmjs.com/package/bmad-creative-intelligence-suite) -- GitHub: [bmad-code-org/bmad-module-creative-intelligence-suite](https://github.com/bmad-code-org/bmad-module-creative-intelligence-suite) - -## Game Dev Studio（`gds`） - -面向游戏开发场景，覆盖从概念到实现的结构化 workflow。 - -**你会得到：** -- 游戏设计文档（GDD）生成流程 -- 面向快速迭代的 Build 模式 -- 叙事设计支持（角色、对话、世界观） -- 多引擎适配建议（Unity/Unreal/Godot 等） - -**外部资源（英文）：** -- npm: [`bmad-game-dev-studio`](https://www.npmjs.com/package/bmad-game-dev-studio) -- GitHub: [bmad-code-org/bmad-module-game-dev-studio](https://github.com/bmad-code-org/bmad-module-game-dev-studio) - -## Test Architect（TEA，`tea`） - -面向高要求测试场景的独立模块。与内置 QA 相比，TEA 更强调策略、追溯与发布门控。 - -**你会得到：** -- Murat 测试架构师 agent -- 覆盖测试设计、ATDD、自动化、审查、追溯的 workflow -- NFR 评估、CI 集成与测试框架脚手架 -- P0-P3 风险优先级策略与可选工具集成 - -**外部资源（英文）：** -- 文档: [TEA Module Docs](https://bmad-code-org.github.io/bmad-method-test-architecture-enterprise/) -- npm: [`bmad-method-test-architecture-enterprise`](https://www.npmjs.com/package/bmad-method-test-architecture-enterprise) -- GitHub: [bmad-code-org/bmad-method-test-architecture-enterprise](https://github.com/bmad-code-org/bmad-method-test-architecture-enterprise) - -## 如何选择模块 - -- 你要“扩展框架能力”而不是只用框架：优先 `bmb` -- 你还在探索方向、需要结构化创意过程：优先 `cis` -- 你是游戏项目：优先 `gds` -- 你需要测试治理、质量门控或审计追溯：优先 `tea` - -:::note[模块可以组合安装] -模块之间不是互斥关系。你可以按项目阶段增量安装，并在后续重新运行安装器同步 skills。 -::: - -## 相关参考 - -- [测试选项](./testing.md) -- [技能（Skills）参考](./commands.md) -- [工作流地图](./workflow-map.md) diff --git a/docs/zh-cn/reference/testing.md b/docs/zh-cn/reference/testing.md deleted file mode 100644 index dc3baa552a..0000000000 --- a/docs/zh-cn/reference/testing.md +++ /dev/null @@ -1,105 +0,0 @@ ---- -title: "测试选项" -description: 内置 QA workflow 与 TEA 模块对比：何时用哪个、各自边界是什么 -sidebar: - order: 6 ---- - -BMad 有两条测试路径： -- **内置 QA workflow**：快速生成可运行测试 -- **TEA（可选模块）**：企业级测试策略与治理能力 - -## 该选内置 QA 还是 TEA？ - -| 维度 | 内置 QA | TEA 模块 | -| --- | --- | --- | -| 最适合 | 中小项目、快速补覆盖 | 大型项目、受监管或复杂业务 | -| 安装成本 | 无需额外安装（BMM 内置） | 需通过安装器单独选择 | -| 方法 | 先生成测试，再迭代 | 先定义策略，再执行并追溯 | -| 测试类型 | API + E2E | API、E2E、ATDD、NFR 等 | -| 风险策略 | 快乐路径 + 关键边界 | P0-P3 风险优先级 | -| workflow 数量 | 1（Automate） | 9（设计/自动化/审查/追溯等） | - -:::tip[默认建议] -大多数项目先用内置 QA workflow。只有当你需要质量门控、合规追溯或系统化测试治理时，再引入 TEA。 -::: - -## 内置 QA Workflow - -内置 QA workflow（`bmad-qa-generate-e2e-tests`）是 BMM 模块的一部分，通过 Developer 智能体调用。目标是用你现有测试栈快速落地测试，不要求额外配置。 - -**触发方式：** -- 菜单触发器：`QA`（通过 Developer 智能体） -- skill：`bmad-qa-generate-e2e-tests` - -### QA Workflow 会做什么 - -QA Automate 流程通常包含 5 步： -1. 检测现有测试框架（如 Jest、Vitest、Playwright、Cypress） -2. 确认待测功能（手动指定或自动发现） -3. 生成 API 测试（状态码、结构、主路径与错误分支） -4. 生成 E2E 测试（语义定位器 + 可见结果断言） -5. 执行并修复基础失败项 - -**默认风格：** -- 仅使用标准框架 API -- UI 测试优先语义定位器（角色、标签、文本） -- 测试互相独立，不依赖顺序 -- 避免硬编码等待/休眠 - -:::note[范围边界] -QA workflow 只负责”生成测试”。如需实现质量评审与故事验收，请配合代码审查 workflow（`CR` / `bmad-code-review`）。 -::: - -### 何时用内置 QA - -- 要快速补齐某个功能的测试覆盖 -- 团队希望先获得可运行基线，再逐步增强 -- 项目暂不需要完整测试治理体系 - -## TEA（Test Architect）模块 - -TEA 提供专家测试 agent（Murat）与 9 个结构化 workflow，覆盖策略、执行、审查、追溯和发布门控。 - -**外部资源（英文）：** -- 文档: [TEA Module Docs](https://bmad-code-org.github.io/bmad-method-test-architecture-enterprise/) -- npm: [`bmad-method-test-architecture-enterprise`](https://www.npmjs.com/package/bmad-method-test-architecture-enterprise) - -**安装：** `npx bmad-method install` 后选择 TEA 模块。 - -### TEA 的 9 个 workflow - -| Workflow | 用途 | -| --- | --- | -| Test Design | 按需求建立测试策略 | -| ATDD | 基于验收标准驱动测试设计 | -| Automate | 使用高级模式生成自动化测试 | -| Test Review | 评估测试质量与覆盖完整性 | -| Traceability | 建立“需求—测试”追溯链路 | -| NFR Assessment | 评估性能/安全等非功能需求 | -| CI Setup | 配置 CI 中的测试执行 | -| Framework Scaffolding | 搭建测试工程基础结构 | -| Release Gate | 基于数据做发布/不发布决策 | - -### 何时用 TEA - -- 需要合规、审计或强追溯能力 -- 需要跨功能做风险优先级管理 -- 发布前存在明确质量门控流程 -- 业务复杂，必须先建策略再写测试 - -## 测试放在流程的哪个位置 - -按 BMad workflow-map，测试位于阶段 4（实施）： - -1. epic 内逐个 story：使用 Build（`BD` / `bmad-build`）实施，并按需追加代码审查（`CR` / `bmad-code-review`） -2. epic 完成后：用 `QA`（通过 Developer 智能体）或 TEA 的 Automate 统一生成/补齐测试 -3. 最后执行复盘（`bmad-retrospective`） - -内置 QA workflow 主要依据代码直接生成测试；TEA 可结合上游规划产物（如 PRD、architecture）实现更强追溯。 - -## 相关参考 - -- [官方模块](./modules.md) -- [工作流地图](./workflow-map.md) -- [智能体参考](./agents.md) diff --git a/docs/zh-cn/reference/workflow-map.md b/docs/zh-cn/reference/workflow-map.md deleted file mode 100644 index c07fb42f97..0000000000 --- a/docs/zh-cn/reference/workflow-map.md +++ /dev/null @@ -1,80 +0,0 @@ ---- -title: "工作流地图" -description: BMad Method 各阶段 workflow 与产出速查 -sidebar: - order: 1 ---- - -BMad Method（BMM）通过分阶段 workflow 逐步构建上下文，让智能体始终知道“做什么、为什么做、如何做”。这张地图用于快速查阅阶段目标、关键 workflow 和对应产出。 - -如果你不确定下一步，优先运行 `bmad-help`。它会基于你当前项目状态和已安装模块给出实时建议。 - - - -

- 在新标签页打开图表 ↗ -

- -## 阶段 1：分析（可选） - -在正式规划前，先验证问题空间与关键假设。 - -| Workflow | 目的 | 产出 | -| --- | --- | --- | -| `bmad-brainstorming` | 通过引导式创意方法扩展方案空间 | `brainstorming-report.md` | -| `bmad-deep-recon` | 验证假设或在候选方案间做选择——可为你的深度研究工具起草提示词、加工其报告，或直接在此研究；覆盖市场、领域、技术、竞争、用户之声与学术研究；经核实、有引用、可刷新 | 研究报告或摘要 + 可选 HTML 简报 | -| `bmad-create-product-brief` | 沉淀产品方向与战略愿景 | `product-brief.md` | - -## 阶段 2：规划 - -定义“为谁做、做什么”。 - -| Workflow | 目的 | 产出 | -| --- | --- | --- | -| `bmad-prd` | 明确 FR/NFR 与范围边界 | `PRD.md` | -| `bmad-ux` | 在 UX 复杂场景下补齐交互与体验方案 | `DESIGN.md`, `EXPERIENCE.md` | -| `bmad-spec` | 将任意意图输入（brief、PRD、转录、想法笔记）提炼为精炼的 `SPEC.md` 契约及配套文件 —— 先锁定“做什么”，再谈“怎么做” | `SPEC.md` 及配套文件，位于 `{output_folder}/specs/spec-{slug}/` | - -## 阶段 3：解决方案设计（Solutioning） - -定义“如何实现”并拆分可交付工作单元。 - -| Workflow | 目的 | 产出 | -| --- | --- | --- | -| `bmad-architecture` | 显式记录技术决策与架构边界 | `architecture.md`（含 ADR） | -| `bmad-create-epics-and-stories` | 将需求拆分为可实施的 epics/stories | epics 文件与 story 条目 | -| `bmad-sprint-planning` | 实施前就绪 gate 检查，随后生成 story 追踪与冲刺状态摘要 | PASS / CONCERNS / FAIL + `sprint-status.yaml` | - -## 阶段 4：实施 - -所有实施入口都汇入 `bmad-build`。它可以接收直接意图、issue、规格或已规划 story，并自行选择所需的澄清、规划、实现和审查深度。 - -| Workflow | 目的 | 产出 | -| --- | --- | --- | -| `bmad-build` | 将直接意图或已规划 story 转化为完成实现并经过审查的代码 | `spec-*.md` + 代码变更 | -| `bmad-code-review` | 验证实现质量 | 通过或变更请求 | -| `bmad-correct-course` | 处理中途重大方向调整 | 更新后的计划或重路由 | -| `bmad-retrospective` | epic 完成后复盘 | 经验与改进项 | - -### 直接入口与规划入口 - -目标清晰的工作可以直接进入 `bmad-build`。更大的项目可以先准备 PRD、UX、架构、epics、stories、就绪检查和 sprint 计划。上游产物只会增加实施上下文，不会选择另一条实施工作流。 - -## 上下文管理 - -每个阶段产出都会成为下一阶段输入：PRD 约束架构，架构约束开发，story 约束实现。没有这条链路，智能体更容易在跨 story 时出现不一致决策。 - -:::tip[Project Context 建议] -创建 `project-context.md`，把项目特有约定（技术栈、命名、组织、测试策略）写成共享规则，能显著降低实现偏差。 -::: - -**创建方式：** -- **手动创建**：在 `_bmad-output/project-context.md` 记录项目规则 -- **自动生成**：运行 `bmad-generate-project-context` 从架构或代码库提取 - -## 相关参考 - -- [命令与技能参考](./commands.md) -- [智能体参考](./agents.md) -- [核心工具参考](./core-tools.md) -- [项目上下文说明](../explanation/project-context.md) diff --git a/docs/zh-cn/tutorials/getting-started.md b/docs/zh-cn/tutorials/getting-started.md deleted file mode 100644 index c230354d07..0000000000 --- a/docs/zh-cn/tutorials/getting-started.md +++ /dev/null @@ -1,275 +0,0 @@ ---- -title: "快速入门" -description: 安装 BMad 并构建你的第一个项目 ---- - -使用 AI 驱动的工作流更快地构建软件，通过专门的智能体引导你完成规划、架构设计和实现。 - -## 你将学到 - -- 为新项目安装并初始化 BMad Method -- 使用 **BMad-Help** —— 你的智能向导，它知道下一步该做什么 -- 为当前工作选择合适的规划深度 -- 从需求到可用代码，逐步推进各个阶段 -- 有效使用智能体和工作流 - -:::note[前置条件] -- **Node.js 20.12+** — 安装程序必需 -- **Git** — 推荐用于版本控制 -- **AI 驱动的 IDE** — Claude Code、Cursor 或类似工具 -- **一个项目想法** — 即使是简单的想法也可以用于学习 -::: - -:::tip[最简单的路径] -**安装** → `npx bmad-method install` -**询问** → `bmad-help 我应该先做什么？` -**构建** → 让 BMad-Help 逐个工作流地引导你 -::: - -## 认识 BMad-Help：你的智能向导 - -**BMad-Help 是开始使用 BMad 的最快方式。** 你不需要记住工作流或阶段 —— 只需询问，BMad-Help 就会： - -- **检查你的项目**，看看已经完成了什么 -- **根据你安装的模块显示你的选项** -- **推荐下一步** —— 包括第一个必需任务 -- **回答问题**，比如"我有一个 SaaS 想法，应该从哪里开始？" - -### 如何使用 BMad-Help - -在你的 AI IDE 中直接调用技能名： - -``` -bmad-help -``` - -也可以带着问题一起调用，获得更贴合上下文的建议： - -``` -bmad-help 我有一个 SaaS 产品的想法，我已经知道我想要的所有功能。我应该从哪里开始？ -``` - -BMad-Help 将回应： -- 针对你的情况推荐什么 -- 第一个必需任务是什么 -- 其余流程是什么样的 - -### 它也驱动工作流 - -BMad-Help 不仅回答问题 —— **它会在每个工作流结束时自动运行**，告诉你确切地下一步该做什么。无需猜测，无需搜索文档 —— 只需对下一个必需工作流的清晰指导。 - -:::tip[从这里开始] -安装 BMad 后，立即运行 `bmad-help`。它将检测你安装了哪些模块，并引导你找到项目的正确起点。 -::: - -## 了解 BMad - -BMad 通过带有专门 AI 智能体的引导工作流帮助你构建软件。该过程遵循四个阶段： - -| 阶段 | 名称 | 发生什么 | -| ---- | -------------- | -------------------------------------------------- | -| 1 | 分析 | 头脑风暴、研究、产品简报 *（可选）* | -| 2 | 规划 | 创建需求（PRD 或技术规范） | -| 3 | 解决方案设计 | 按需要设计架构 | -| 4 | 实现 | 实施每项变更或已规划的 story，可选择使用自动化编排 | - -**[打开工作流地图](../reference/workflow-map.md)** 以探索阶段、工作流和上下文管理。 - -规划深度可以灵活调整： - -| 规划深度 | 最适合 | 实施前可用上下文 | -| --- | --- | --- | -| **直接** | 清晰的修复、功能、issue 或现有规格 | 意图、issue 或规格 | -| **产品规划** | 产品、平台和复杂功能 | PRD 与可选 UX 设计 | -| **完整方案设计** | 跨系统、高风险或协同项目 | PRD、UX、架构、epics、stories 与 sprint 计划 | - -:::note -这些不是独立的实施路径。所有入口都汇入 `bmad-build`；规划只会改变实施前已有的上下文量。 -::: - -## 安装 - -在项目目录中打开终端并运行： - -```bash -npx bmad-method install -``` - -如果你想使用最新预发布版本（而不是默认发布通道），可以改用 `npx bmad-method@next install`。 - -当提示选择模块时，选择 **BMad Method**。 - -安装程序会创建两个文件夹： -- `_bmad/` — 智能体、工作流、任务和配置 -- `_bmad-output/` — 目前为空，但这是你的工件将被保存的地方 - -:::tip[你的下一步] -在项目文件夹中打开你的 AI IDE 并运行： - -``` -bmad-help -``` - -BMad-Help 将检测你已完成的内容，并准确推荐下一步该做什么。你也可以问它诸如"我的选项是什么？"或"我有一个 SaaS 想法，我应该从哪里开始？"之类的问题。 -::: - -:::note[如何加载智能体和运行工作流] -每个工作流都可以通过技能名直接调用（例如 `bmad-prd`）。你的 AI IDE 会识别 `bmad-*` 技能并执行，无需额外单独加载智能体。你也可以直接调用智能体技能进行通用对话（例如 PM 智能体用 `bmad-agent-pm`）。 -::: - -:::caution[新对话] -始终为每个工作流开始一个新的对话。这可以防止上下文限制导致问题。 -::: - -## 步骤 1：选择规划深度 - -根据工作需要选用阶段 1-3。对于清晰且边界明确的工作，可以直接进入[步骤 2](#步骤-2构建你的项目)。**为每个工作流使用新对话。** - -:::tip[项目上下文（可选）] -在开始之前，考虑创建 `project-context.md` 来记录你的技术偏好和实现规则。这确保所有 AI 智能体在整个项目中遵循你的约定。 - -在 `_bmad-output/project-context.md` 手动创建它，或在架构之后使用 `bmad-generate-project-context` 生成它。[了解更多](../explanation/project-context.md)。 -::: - -### 阶段 1：分析（可选） - -此阶段中的所有工作流都是可选的： -- **头脑风暴**（`bmad-brainstorming`） — 引导式构思 -- **研究**（`bmad-deep-recon`） — 为你自己的深度研究工具起草提示词、将完成的研究报告加工为可供下游使用的精炼摘要，或直接在此执行研究——覆盖市场、领域、技术、竞争、用户之声与学术类型，带论断核实与刷新生命周期 -- **创建产品简报**（`bmad-create-product-brief`） — 推荐的基础文档 - -### 阶段 2：规划（按需） - -对于需要产品规划的工作： -1. 在新对话中调用 **PM 智能体**（`bmad-agent-pm`） -2. 运行 `bmad-prd` 工作流（`bmad-prd`） -3. 输出：`PRD.md` - -:::note[UX 设计（可选）] -如果你的项目有用户界面，在创建 PRD 后调用 **UX-Designer 智能体**（`bmad-agent-ux-designer`），然后运行 UX 设计工作流（`bmad-ux`）。 -::: - -### 阶段 3：解决方案设计（按需） - -**创建架构** -1. 在新对话中调用 **Architect 智能体**（`bmad-agent-architect`） -2. 运行 `bmad-architecture`（`bmad-architecture`） -3. 输出：包含技术决策的架构文档 - -**创建史诗和故事** - -:::tip[V6 改进] -史诗和故事现在在架构*之后*创建。这会产生更高质量的故事，因为架构决策（数据库、API 模式、技术栈）直接影响工作应该如何分解。 -::: - -1. 在新对话中调用 **PM 智能体**（`bmad-agent-pm`） -2. 运行 `bmad-create-epics-and-stories`（`bmad-create-epics-and-stories`） -3. 工作流使用 PRD 和架构来创建技术信息丰富的故事 - -**实现就绪检查** *（强烈推荐）* -1. 在新对话中调用 **Architect 智能体**（`bmad-agent-architect`） -2. 运行 `bmad-sprint-planning`（`bmad-sprint-planning`）— 以就绪 gate 检查开始 -3. 验证所有规划文档之间的一致性 - -## 步骤 2：构建你的项目 - -携带现有上下文进入实现阶段：直接请求、issue、规格或完整规划的 story。**每个工作流应该在新对话中运行。** - -对于已规划工作，运行 `bmad-build` 并指出选定的 story 或 sprint 项，例如：`实现 _bmad-output/planning-artifacts/epics.md 中的 story 2.3`。 - -### 初始化冲刺规划（用于规划工作） - -调用 **Developer 智能体**（`bmad-agent-dev`）并运行 `bmad-sprint-planning`（`bmad-sprint-planning`）。这会创建 `sprint-status.yaml` 来跟踪所有史诗和故事。 - -当 Build 在该文件中解析出选定 story 时，它会在实施期间把状态改为 `in-progress`，并在实施完成后改为 `review`。 - -### 构建周期 - -对于每个直接变更或已规划 story，使用新对话重复此周期： - -| 步骤 | 智能体 | 工作流 | 命令 | 目的 | -| ---- | ------ | ------------ | ----------------------- | ------------------------------- | -| 1 | DEV | `bmad-build` | `bmad-build` | 按需澄清、规划、实现、审查与呈现 | -| 2 | DEV | `bmad-code-review` | `bmad-code-review` | 额外质量验证 *（推荐）* | - -Build 的审查是每次运行的一部分。`bmad-code-review` 是在全新上下文中执行的可选独立验证层。 - -完成史诗中的所有故事后，调用 **Developer 智能体**（`bmad-agent-dev`）并运行 `bmad-retrospective`（`bmad-retrospective`）。 - -## 你已完成的工作 - -你已经学习了使用 BMad 构建的基础： - -- 安装了 BMad 并为你的 IDE 进行了配置 -- 为当前工作选择了合适的规划深度 -- 创建了规划文档（PRD、架构、史诗和故事） -- 了解了实现的构建周期 - -你的项目现在拥有： - -```text -your-project/ -├── _bmad/ # BMad 配置 -├── _bmad-output/ -│ ├── planning-artifacts/ -│ │ ├── PRD.md # 你的需求文档 -│ │ ├── architecture.md # 技术决策 -│ │ └── epics/ # 史诗和故事文件 -│ ├── implementation-artifacts/ -│ │ └── sprint-status.yaml # 冲刺跟踪 -│ └── project-context.md # 实现规则（可选） -└── ... -``` - -## 快速参考 - -| 工作流 | 命令 | 智能体 | 目的 | -| ----------------------------------- | --------------------------------------- | -------- | -------------------------------------------- | -| **`bmad-help`** ⭐ | `bmad-help` | 任意 | **你的智能向导 —— 随时询问任何问题！** | -| `bmad-prd` | `bmad-prd` | PM | 创建产品需求文档 | -| `bmad-architecture` | `bmad-architecture` | Architect | 创建架构文档 | -| `bmad-generate-project-context` | `bmad-generate-project-context` | Analyst | 创建项目上下文文件 | -| `bmad-create-epics-and-stories` | `bmad-create-epics-and-stories` | PM | 将 PRD 分解为史诗 | -| `bmad-sprint-planning` | `bmad-sprint-planning` | DEV | 就绪 gate 检查 + 初始化冲刺跟踪 + 冲刺状态摘要 | -| `bmad-build` | `bmad-build` | DEV | 实施意图、issue、功能、修复或已规划 story | -| `bmad-code-review` | `bmad-code-review` | DEV | 审查已实现的代码 | - -## 常见问题 - -**我总是需要架构吗？** -不需要。只有当技术决策或跨系统约束需要显式记录时才使用架构。清晰工作可以直接进入 `bmad-build`；大型项目则把规划产物带入同一个 workflow。 - -**我可以稍后更改我的计划吗？** -可以。`bmad-correct-course` 工作流用于处理实现过程中的范围变化。 - -**如果我想先进行头脑风暴怎么办？** -在开始 PRD 之前，调用 Analyst 智能体（`bmad-agent-analyst`）并运行 `bmad-brainstorming`（`bmad-brainstorming`）。 - -**我需要遵循严格的顺序吗？** -不一定。一旦你了解了流程，你可以使用上面的快速参考直接运行工作流。 - -## 获取帮助 - -:::tip[第一站：BMad-Help] -**随时运行 `bmad-help`** —— 这是摆脱困境的最快方式。问它任何问题： -- "安装后我应该做什么？" -- "我在工作流 X 上卡住了" -- "我在 Y 方面有什么选项？" -- "向我展示到目前为止已完成的工作" - -BMad-Help 检查你的项目，检测你已完成的内容，并确切地告诉你下一步该做什么。 -::: - -- **在工作流期间** — 智能体通过问题和解释引导你 -- **社区** — [Discord](https://discord.gg/gk8jAdXWmj) (#bmad-method-help, #report-bugs-and-issues) - -## 关键要点 - -:::tip[记住这些] -- **从 `bmad-help` 开始** — 你的智能向导，了解你的项目和选项 -- **始终使用新对话** — 为每个工作流开始新对话 -- **规划深度可变** — 直接意图和完整规划的 story 都进入 `bmad-build` -- **BMad-Help 自动运行** — 每个工作流结束时都会提供下一步的指导 -::: - -准备好开始了吗？安装 BMad，运行 `bmad-help`，让你的智能向导为你引路。 From 0d4378459479e844af3162a0bbc80a964e04a196 Mon Sep 17 00:00:00 2001 From: Alex Verkhovsky Date: Tue, 6 Oct 2026 03:58:18 -0700 Subject: [PATCH 2/3] docs: strip diagram translation The site no longer swaps diagram labels, so the SVG text is the only copy. --- docs-site/package.json | 2 +- docs-site/scripts/export-readme-diagrams.mjs | 31 +--- docs-site/src/components/Diagram.astro | 19 --- .../diagrams/bmad-delivery-loop.labels.json | 26 --- docs-site/src/diagrams/bmad-delivery-loop.svg | 20 +-- docs-site/src/diagrams/build-run.labels.json | 98 ----------- docs-site/src/diagrams/build-run.svg | 60 +++---- .../diagrams/development-paths.labels.json | 68 -------- docs-site/src/diagrams/development-paths.svg | 62 +++---- .../src/diagrams/planning-skills.labels.json | 39 ----- docs-site/src/diagrams/planning-skills.svg | 70 ++++---- .../src/diagrams/walkthrough-run.labels.json | 74 -------- docs-site/src/diagrams/walkthrough-run.svg | 44 ++--- docs-site/src/integrations/diagrams.js | 4 +- docs-site/src/rehype-inline-diagrams.js | 42 +---- docs-site/test/test-english-only-site.mjs | 5 +- .../test/test-export-readme-diagrams.mjs | 27 +++ docs-site/test/test-rehype-plugins.mjs | 51 ++---- docs/_STYLE_GUIDE.md | 5 - docs/images/bmad-delivery-loop-ko.svg | 158 ------------------ docs/images/bmad-delivery-loop.svg | 20 +-- 21 files changed, 191 insertions(+), 734 deletions(-) delete mode 100644 docs-site/src/diagrams/bmad-delivery-loop.labels.json delete mode 100644 docs-site/src/diagrams/build-run.labels.json delete mode 100644 docs-site/src/diagrams/development-paths.labels.json delete mode 100644 docs-site/src/diagrams/planning-skills.labels.json delete mode 100644 docs-site/src/diagrams/walkthrough-run.labels.json create mode 100644 docs-site/test/test-export-readme-diagrams.mjs delete mode 100644 docs/images/bmad-delivery-loop-ko.svg diff --git a/docs-site/package.json b/docs-site/package.json index efac5a70a3..de81234eb8 100644 --- a/docs-site/package.json +++ b/docs-site/package.json @@ -14,7 +14,7 @@ "lint": "eslint scripts test --max-warnings=0", "lint:fix": "eslint scripts test --fix", "preview": "astro preview", - "test": "node test/test-site-url.mjs && node test/test-rehype-plugins.mjs && node test/test-validate-redirects.mjs && node test/test-english-only-site.mjs", + "test": "node test/test-site-url.mjs && node test/test-rehype-plugins.mjs && node test/test-validate-redirects.mjs && node test/test-english-only-site.mjs && node test/test-export-readme-diagrams.mjs", "test:implementation-model": "node test/test-validate-published-implementation-model.mjs", "validate-links": "node scripts/validate-doc-links.js", "validate-sidebar": "node scripts/validate-sidebar-order.js" diff --git a/docs-site/scripts/export-readme-diagrams.mjs b/docs-site/scripts/export-readme-diagrams.mjs index 2b832072e2..37da575be6 100644 --- a/docs-site/scripts/export-readme-diagrams.mjs +++ b/docs-site/scripts/export-readme-diagrams.mjs @@ -26,11 +26,8 @@ import { fileURLToPath } from 'node:url'; const SITE_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..'); const REPO_ROOT = join(SITE_ROOT, '..'); -/** Which diagram lands where, and in which language. */ -const EXPORTS = [ - { diagram: 'bmad-delivery-loop', out: 'docs/images/bmad-delivery-loop.svg' }, - { diagram: 'bmad-delivery-loop', out: 'docs/images/bmad-delivery-loop-ko.svg', lang: 'ko-KR' }, -]; +/** Which diagram lands where. */ +const EXPORTS = [{ diagram: 'bmad-delivery-loop', out: 'docs/images/bmad-delivery-loop.svg' }]; /** * The dark ramp, resolved. These are the values `custom.css` gives the @@ -98,21 +95,6 @@ const STYLE = ` } `; -/** Escape a translated label for use as SVG text content. */ -function escapeXml(value) { - return value.replaceAll('&', '&').replaceAll('<', '<').replaceAll('>', '>'); -} - -/** - * Swap each `data-i18n` label for its translation, keeping the authored - * English wherever one is missing — the same rule the docs site applies. - */ -function translate(svg, strings) { - return svg.replaceAll(/(]*\bdata-i18n="([\w-]+)"[^>]*>)([^<]*)(<\/text>)/g, (whole, open, key, text, close) => - strings[key] ? `${open}${escapeXml(strings[key])}${close}` : whole, - ); -} - /** Substitute every `var(--dg-*)` in the geometry for its literal colour. */ function resolveTokens(svg) { return svg.replaceAll(/var\(--dg-([\w-]+)\)/g, (whole, token) => { @@ -138,13 +120,10 @@ function standalone(svg) { return resolveTokens(svg).replace(/(]*>)/, `$1\n \n ${ground}`); } -for (const { diagram, out, lang } of EXPORTS) { +for (const { diagram, out } of EXPORTS) { const source = join(SITE_ROOT, 'src', 'diagrams', `${diagram}.svg`); - const labelsPath = join(SITE_ROOT, 'src', 'diagrams', `${diagram}.labels.json`); - const labels = JSON.parse(readFileSync(labelsPath, 'utf8')); - - const svg = standalone(translate(readFileSync(source, 'utf8'), (lang && labels[lang]) || {})); + const svg = standalone(readFileSync(source, 'utf8')); const target = join(REPO_ROOT, out); writeFileSync(target, svg); - console.log(`wrote ${out}${lang ? ` (${lang})` : ''}`); + console.log(`wrote ${out}`); } diff --git a/docs-site/src/components/Diagram.astro b/docs-site/src/components/Diagram.astro index 63d3f0d91f..4223102d57 100644 --- a/docs-site/src/components/Diagram.astro +++ b/docs-site/src/components/Diagram.astro @@ -8,8 +8,6 @@ * SVG. This component is the same behaviour for anywhere that *can* take a * component: an `.mdx` page, or a Starlight component override. * - * Both paths share the label file, so a diagram reads the same either way. - * * */ import { readFileSync } from 'node:fs'; @@ -23,27 +21,10 @@ interface Props { } const { name, label } = Astro.props; -const lang = Astro.locals.starlightRoute?.entryMeta?.lang; const dir = new URL('../diagrams/', import.meta.url); let svg = readFileSync(fileURLToPath(new URL(`${name}.svg`, dir)), 'utf8'); -let strings: Record = {}; -try { - const labels = JSON.parse(readFileSync(fileURLToPath(new URL(`${name}.labels.json`, dir)), 'utf8')); - strings = (lang && labels[lang]) || {}; -} catch { - // A diagram without a label file is English-only, which is fine. -} - -for (const [key, value] of Object.entries(strings)) { - // Global, and the key escaped: a diagram may use one key more than once, and - // a key is free to contain regex metacharacters. The rehype plugin walks the - // tree and has neither problem; this path has to be told. - const pattern = new RegExp(`(data-i18n="${key.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}"[^>]*>)[^<]*`, 'g'); - svg = svg.replace(pattern, (_match, open) => `${open}${value}`); -} - if (label) { svg = svg.replace(' - START ANYWHERE + START ANYWHERE - RIGHT-SIZED FOR THE WORK IN FRONT OF YOU + RIGHT-SIZED FOR THE WORK IN FRONT OF YOU - ANALYSIS - optional: explore and validate + ANALYSIS + optional: explore and validate - bmad-brainstorming - brainstorm-<slug>.md, brainstorm.html + bmad-brainstorming + brainstorm-<slug>.md, brainstorm.html - bmad-forge-idea - forge-<slug>.md, forge-report.html + bmad-forge-idea + forge-<slug>.md, forge-report.html - bmad-deep-recon - research-<slug>.md, optional HTML briefing + bmad-deep-recon + research-<slug>.md, optional HTML briefing - bmad-product-brief - brief-<slug>.md, addendum.md + bmad-product-brief + brief-<slug>.md, addendum.md - bmad-prfaq - prfaq-<slug>/ + bmad-prfaq + prfaq-<slug>/ - PLANNING - define what to build + PLANNING + define what to build - bmad-prd - prd-<slug>.md, addendum.md, .memlog.md - validate: HTML + .md report + bmad-prd + prd-<slug>.md, addendum.md, .memlog.md + validate: HTML + .md report - bmad-ux - ux-<slug>.md, DESIGN.md, EXPERIENCE.md + bmad-ux + ux-<slug>.md, DESIGN.md, EXPERIENCE.md - bmad-spec - spec-<slug>.md + companions - bmad-ticket handoff + bmad-spec + spec-<slug>.md + companions + bmad-ticket handoff - Use a spec when needed. - One session of work goes - straight from the spec to Build. + Use a spec when needed. + One session of work goes + straight from the spec to Build. - SOLUTIONING - decide how, divide the work + SOLUTIONING + decide how, divide the work - bmad-architecture - architecture-<slug>.md + bmad-architecture + architecture-<slug>.md - bmad-ticket - ordered tickets.toml entries + bmad-ticket + ordered tickets.toml entries @@ -100,8 +100,8 @@ - bmad-build - one session per unit · built → user marks done · keep plans + bmad-build + one session per unit · built → user marks done · keep plans diff --git a/docs-site/src/diagrams/walkthrough-run.labels.json b/docs-site/src/diagrams/walkthrough-run.labels.json deleted file mode 100644 index 6235619e97..0000000000 --- a/docs-site/src/diagrams/walkthrough-run.labels.json +++ /dev/null @@ -1,74 +0,0 @@ -{ - "en": { - "title": "The bmad-walkthrough run: it reads the build plan or a pull request, then moves through orientation, the walkthrough itself, a detail pass and testing before wrapping up, where you approve, ask for rework, or open a discussion.", - "input-build": "bmad-build", - "input-plan": "plan file", - "input-pr": "PR / commit", - "input-pr-2": "branch", - "orientation": "Orientation", - "orientation-note": "Intent summary", - "orientation-note-2": "Surface area stats", - "walkthrough": "Walkthrough", - "walkthrough-note": "Organized by concern", - "walkthrough-note-2": "Clickable path:line stops", - "detail-pass": "Detail Pass", - "detail-pass-note": "Highest blast radius first", - "detail-pass-note-2": "\"dig into [area]\" for a deep dive", - "testing": "Testing", - "testing-note": "Manual observations", - "testing-note-2": "See it working", - "wrap-up": "Wrap-Up", - "early-exit": "early exit", - "approve": "Approve", - "rework": "Rework", - "discuss": "Discuss" - }, - "ko-KR": { - "title": "bmad-build 계획 파일, PR, 커밋 또는 브랜치에서 시작해 방향 잡기, 둘러보기, 상세 검토, 테스트, 마무리를 차례로 진행한 뒤 승인, 재작업 또는 논의를 선택합니다.", - "input-build": "bmad-build", - "input-plan": "계획 파일", - "input-pr": "PR / 커밋", - "input-pr-2": "브랜치", - "orientation": "방향 잡기", - "orientation-note": "의도 요약", - "orientation-note-2": "영향 범위 통계", - "walkthrough": "둘러보기", - "walkthrough-note": "관심사별 구성", - "walkthrough-note-2": "클릭 가능한 path:line 지점", - "detail-pass": "상세 검토", - "detail-pass-note": "영향이 큰 위험부터 확인", - "detail-pass-note-2": "\"[영역]을 더 파고들어 줘\" 라고 말해 상세 확인", - "testing": "테스트", - "testing-note": "수동 확인", - "testing-note-2": "작동하는 모습 확인", - "wrap-up": "마무리", - "early-exit": "조기 종료", - "approve": "승인", - "rework": "재작업", - "discuss": "논의" - }, - "fr-FR": { - "title": "Le déroulé de bmad-walkthrough : il lit le plan de build ou une pull request, puis passe par l'orientation, la visite guidée, une passe de détail et les tests avant la conclusion, où vous approuvez, demandez une reprise ou ouvrez une discussion.", - "input-build": "bmad-build", - "input-plan": "fichier de plan", - "input-pr": "PR / commit", - "input-pr-2": "branche", - "orientation": "Orientation", - "orientation-note": "Résumé de l'intention", - "orientation-note-2": "Statistiques de portée", - "walkthrough": "Visite guidée", - "walkthrough-note": "Organisée par sujet", - "walkthrough-note-2": "Points path:line cliquables", - "detail-pass": "Passe de détail", - "detail-pass-note": "Le plus à risque d'abord", - "detail-pass-note-2": "« creuse [zone] » pour approfondir", - "testing": "Tests", - "testing-note": "Observations manuelles", - "testing-note-2": "Le voir fonctionner", - "wrap-up": "Conclusion", - "early-exit": "sortie anticipée", - "approve": "Approuver", - "rework": "Reprise", - "discuss": "Discuter" - } -} diff --git a/docs-site/src/diagrams/walkthrough-run.svg b/docs-site/src/diagrams/walkthrough-run.svg index 0180f8436d..aef726b9d7 100644 --- a/docs-site/src/diagrams/walkthrough-run.svg +++ b/docs-site/src/diagrams/walkthrough-run.svg @@ -1,48 +1,48 @@ -The bmad-walkthrough run: it reads the build plan or a pull request, then moves through orientation, the walkthrough itself, a detail pass and testing before wrapping up, where you approve, ask for rework, or open a discussion. +The bmad-walkthrough run: it reads the build plan or a pull request, then moves through orientation, the walkthrough itself, a detail pass and testing before wrapping up, where you approve, ask for rework, or open a discussion. -bmad-build -plan file +bmad-build +plan file -PR / commit -branch +PR / commit +branch -Orientation -Intent summary -Surface area stats +Orientation +Intent summary +Surface area stats -Walkthrough -Organized by concern -Clickable path:line stops +Walkthrough +Organized by concern +Clickable path:line stops -Detail Pass -Highest blast radius first -"dig into [area]" for a deep dive +Detail Pass +Highest blast radius first +"dig into [area]" for a deep dive -Testing -Manual observations -See it working +Testing +Manual observations +See it working -Wrap-Up +Wrap-Up -early exit +early exit -Approve +Approve -Rework +Rework -Discuss +Discuss \ No newline at end of file diff --git a/docs-site/src/integrations/diagrams.js b/docs-site/src/integrations/diagrams.js index fad7e32fd0..c8796348f7 100644 --- a/docs-site/src/integrations/diagrams.js +++ b/docs-site/src/integrations/diagrams.js @@ -29,12 +29,12 @@ import { fileURLToPath } from 'node:url'; const DIAGRAM_DIR = 'src/diagrams'; const STAMP = 'bmad-diagrams'; -/** Absolute paths of every diagram and label file, sorted for a stable hash. */ +/** Absolute paths of every diagram file, sorted for a stable hash. */ function diagramFiles(root) { const dir = fileURLToPath(new URL(`${DIAGRAM_DIR}/`, root)); if (!existsSync(dir)) return []; return readdirSync(dir) - .filter((name) => name.endsWith('.svg') || name.endsWith('.labels.json')) + .filter((name) => name.endsWith('.svg')) .sort() .map((name) => dir + name); } diff --git a/docs-site/src/rehype-inline-diagrams.js b/docs-site/src/rehype-inline-diagrams.js index 0ff398cdc1..65f0719171 100644 --- a/docs-site/src/rehype-inline-diagrams.js +++ b/docs-site/src/rehype-inline-diagrams.js @@ -10,18 +10,12 @@ * `.gate`, `.k`) that `custom.css` styles once for every diagram, in both * themes. * - * Labels are translated, not redrawn. Each `` carries a `data-i18n` key; - * this plugin swaps in the string for the page's locale from the diagram's - * sibling `.labels.json`, falling back to the English already in the file. - * One geometry file serves every language, so a translation can never drift out - * of shape with the original. - * * Diagrams that are not hand-authored (raster files, the workflow-map iframe) * are left alone. */ import { existsSync, readFileSync, statSync } from 'node:fs'; -import { dirname, join } from 'node:path'; +import { join } from 'node:path'; import { fromHtml } from 'hast-util-from-html'; import { visit } from 'unist-util-visit'; @@ -29,28 +23,19 @@ import { visit } from 'unist-util-visit'; /** Where the authored diagrams live, relative to the Astro site root. */ const DIAGRAM_DIR = 'src/diagrams'; -/** `docs/fr/build/x.md` → `fr`. Returns undefined for the root locale. */ -function localeFromPath(filePath, docsDirName = 'docs') { - if (!filePath) return undefined; - const parts = filePath.split('/'); - const i = parts.lastIndexOf(docsDirName); - return i === -1 ? undefined : parts[i + 1]; -} - /** * Create a rehype plugin that replaces diagram images with inline SVG. * * @param {object} options * @param {string} options.root - Absolute path to the Astro site root. - * @param {Record} options.locales - Starlight locale config. * @returns {function} A HAST tree transformer. */ export default function rehypeInlineDiagrams(options = {}) { - const { root, locales = {} } = options; + const { root } = options; const cache = new Map(); /** - * Read a diagram and its labels, keyed on the file's modification time. + * Read a diagram, keyed on the file's modification time. * * The dev server is one long-lived process, so a cache keyed on the name * alone would hand back the first drawing it ever read and keep serving it @@ -60,10 +45,7 @@ export default function rehypeInlineDiagrams(options = {}) { const svgPath = join(root, DIAGRAM_DIR, `${name}.svg`); if (!existsSync(svgPath)) return undefined; - const labelsPath = join(dirname(svgPath), `${name}.labels.json`); - const stamp = [svgPath, labelsPath] - .map((file) => (existsSync(file) ? statSync(file).mtimeMs : 0)) - .join(':'); + const stamp = String(statSync(svgPath).mtimeMs); const cached = cache.get(name); if (cached?.stamp === stamp) return cached; @@ -71,16 +53,12 @@ export default function rehypeInlineDiagrams(options = {}) { const entry = { stamp, svg: readFileSync(svgPath, 'utf8'), - labels: existsSync(labelsPath) ? JSON.parse(readFileSync(labelsPath, 'utf8')) : {}, }; cache.set(name, entry); return entry; } - return (tree, file) => { - const localeKey = localeFromPath(file?.path); - const lang = locales[localeKey]?.lang; - + return (tree) => { visit(tree, 'element', (node, index, parent) => { if (node.tagName !== 'img' || !parent || index === undefined) return; @@ -93,18 +71,8 @@ export default function rehypeInlineDiagrams(options = {}) { const diagram = load(match[1]); if (!diagram) return; - const strings = (lang && diagram.labels[lang]) || {}; const fragment = fromHtml(diagram.svg, { fragment: true, space: 'svg' }); - // Swap each keyed label for its translation, keeping the authored English - // wherever a translation is missing. - visit(fragment, 'element', (el) => { - const key = el.properties?.dataI18n; - if (typeof key === 'string' && strings[key]) { - el.children = [{ type: 'text', value: strings[key] }]; - } - }); - // Carry the markdown alt text through as the accessible name, but only // when the diagram does not name itself. hast camel-cases ARIA // attributes, so these are `ariaLabelledBy` / `ariaLabel`; reading the diff --git a/docs-site/test/test-english-only-site.mjs b/docs-site/test/test-english-only-site.mjs index ef75272ca0..a83e612afc 100644 --- a/docs-site/test/test-english-only-site.mjs +++ b/docs-site/test/test-english-only-site.mjs @@ -29,10 +29,7 @@ test('a diagram keeps its English text when locales are omitted', () => { const root = mkdtempSync(join(tmpdir(), 'bmad-en-diagram-')); try { mkdirSync(join(root, 'src', 'diagrams'), { recursive: true }); - writeFileSync( - join(root, 'src', 'diagrams', 'flow.svg'), - 'Start', - ); + writeFileSync(join(root, 'src', 'diagrams', 'flow.svg'), 'Start'); const tree = { type: 'root', children: [ diff --git a/docs-site/test/test-export-readme-diagrams.mjs b/docs-site/test/test-export-readme-diagrams.mjs new file mode 100644 index 0000000000..254f111b32 --- /dev/null +++ b/docs-site/test/test-export-readme-diagrams.mjs @@ -0,0 +1,27 @@ +/** + * README diagram export stays English-only. + * + * Usage: node docs-site/test/test-export-readme-diagrams.mjs + */ + +import assert from 'node:assert/strict'; +import { execFileSync } from 'node:child_process'; +import { existsSync, readFileSync } from 'node:fs'; +import { dirname, join } from 'node:path'; +import { fileURLToPath } from 'node:url'; + +const siteRoot = join(dirname(fileURLToPath(import.meta.url)), '..'); +const repoRoot = join(siteRoot, '..'); +const marker = ['data', 'i18n'].join('-'); +const koreanExport = ['bmad-delivery-loop', 'ko.svg'].join('-'); +const englishExport = join(repoRoot, 'docs/images/bmad-delivery-loop.svg'); + +const before = readFileSync(englishExport, 'utf8'); +execFileSync('node', ['scripts/export-readme-diagrams.mjs'], { cwd: siteRoot, stdio: 'pipe' }); +const after = readFileSync(englishExport, 'utf8'); + +assert.equal(after, before, 'Running the export again does not change the English diagram'); +assert.equal(after.includes(marker), false, 'The English export has no translation attribute'); +assert.equal(existsSync(join(repoRoot, 'docs/images', koreanExport)), false, 'The Korean export is not rewritten'); + +console.log('README diagram export checks passed.'); diff --git a/docs-site/test/test-rehype-plugins.mjs b/docs-site/test/test-rehype-plugins.mjs index 15ae5a27a8..49f51aab45 100644 --- a/docs-site/test/test-rehype-plugins.mjs +++ b/docs-site/test/test-rehype-plugins.mjs @@ -13,7 +13,7 @@ * - Element rewriting * - Raw HTML rewriting * - Integration (both plugins together) - * - Diagram inlining, label translation and cache invalidation + * - Diagram inlining and cache invalidation * * Usage: node docs-site/test/test-rehype-plugins.mjs */ @@ -118,21 +118,11 @@ function getRawValue(tree) { // --- rehype-inline-diagrams ------------------------------------------------ -const DIAGRAM_LOCALES = { root: { lang: 'en' }, fr: { lang: 'fr-FR' }, 'ko-kr': { lang: 'ko-KR' } }; - -/** A site root holding one diagram and its labels, thrown away after the run. */ +/** A site root holding one diagram, thrown away after the run. */ function makeDiagramFixture() { const root = mkdtempSync(join(tmpdir(), 'bmad-diagrams-')); mkdirSync(join(root, 'src', 'diagrams'), { recursive: true }); - writeDiagram( - root, - 'flow', - 'StartEnd', - ); - writeFileSync( - join(root, 'src', 'diagrams', 'flow.labels.json'), - JSON.stringify({ en: { start: 'Start', end: 'End' }, 'fr-FR': { start: 'Départ' } }), - ); + writeDiagram(root, 'flow', 'StartEnd'); return root; } @@ -148,20 +138,20 @@ function makeImgTree(src, alt = 'a diagram') { } function inlineDiagrams(tree, filePath, root) { - const plugin = rehypeInlineDiagrams({ root, locales: DIAGRAM_LOCALES }); + const plugin = rehypeInlineDiagrams({ root }); plugin(tree, { path: filePath }); return tree; } -/** Text of the keyed label in the first inlined SVG, or undefined. */ -function labelText(tree, key) { +/** Text values in the inlined SVG. */ +function textValues(tree) { const found = []; const walk = (node) => { - if (node.properties?.dataI18n === key) found.push(node.children?.[0]?.value); + if (node.type === 'text') found.push(node.value); for (const child of node.children || []) walk(child); }; for (const child of tree.children) walk(child); - return found[0]; + return found; } function firstTag(tree) { @@ -1084,11 +1074,10 @@ function runTests() { // ============================================================ // rehype-inline-diagrams // ============================================================ - console.log(`${colors.yellow}rehype-inline-diagrams (12 tests)${colors.reset}\n`); + console.log(`${colors.yellow}rehype-inline-diagrams (9 tests)${colors.reset}\n`); const dRoot = makeDiagramFixture(); const EN_PAGE = '/project/docs/build/a-change.md'; - const FR_PAGE = '/project/docs/fr/build/a-change.md'; try { const inlined = inlineDiagrams(makeImgTree('/diagrams/flow.svg'), EN_PAGE, dRoot); @@ -1106,23 +1095,7 @@ function runTests() { assert(firstTag(missing) === 'img', 'Leaves the img alone when the diagram is missing', `Expected img, got ${firstTag(missing)}`); const english = inlineDiagrams(makeImgTree('/diagrams/flow.svg'), EN_PAGE, dRoot); - assert(labelText(english, 'start') === 'Start', 'Root locale keeps the authored English', `Got ${labelText(english, 'start')}`); - - const french = inlineDiagrams(makeImgTree('/diagrams/flow.svg'), FR_PAGE, dRoot); - assert(labelText(french, 'start') === 'Départ', 'Substitutes the label for the page locale', `Got ${labelText(french, 'start')}`); - - assert( - labelText(french, 'end') === 'End', - 'Falls back to the authored English for a missing translation', - `Got ${labelText(french, 'end')}`, - ); - - const korean = inlineDiagrams(makeImgTree('/diagrams/flow.svg'), '/project/docs/ko-kr/build/a-change.md', dRoot); - assert( - labelText(korean, 'start') === 'Start', - 'Falls back when the locale has no label file entry', - `Got ${labelText(korean, 'start')}`, - ); + assert(textValues(english).includes('Start'), 'Inlines the authored text', `Got ${textValues(english).join('|')}`); const labelled = inlineDiagrams(makeImgTree('/diagrams/flow.svg', 'the build run'), EN_PAGE, dRoot); assert( @@ -1140,11 +1113,11 @@ function runTests() { ); // the dev server is one long-lived process: an edited diagram must be re-read - writeDiagram(dRoot, 'flow', 'Redrawn'); + writeDiagram(dRoot, 'flow', 'Redrawn'); const future = Date.now() / 1000 + 10; utimesSync(join(dRoot, 'src', 'diagrams', 'flow.svg'), future, future); const reread = inlineDiagrams(makeImgTree('/diagrams/flow.svg'), EN_PAGE, dRoot); - assert(labelText(reread, 'start') === 'Redrawn', 'Re-reads a diagram after it changes on disk', `Got ${labelText(reread, 'start')}`); + assert(textValues(reread).includes('Redrawn'), 'Re-reads a diagram after it changes on disk', `Got ${textValues(reread).join('|')}`); } finally { rmSync(dRoot, { recursive: true, force: true }); } diff --git a/docs/_STYLE_GUIDE.md b/docs/_STYLE_GUIDE.md index 1375f48930..9b069ef477 100644 --- a/docs/_STYLE_GUIDE.md +++ b/docs/_STYLE_GUIDE.md @@ -243,11 +243,6 @@ themes every diagram in both light and dark. That means a diagram file carries (`node`, `edge`, `gate`, `panel`, `glyph`, and the `n` / `sub` / `k` text classes) and a new diagram will match the others without any styling work. -Labels are translated, not redrawn. Give each `` a `data-i18n` key and add -the strings to the diagram's `.labels.json`; every language then shares one -drawing, and a translation cannot drift out of shape with the original. Anything -missing falls back to the English in the SVG. - A README is not a docs page — it loads an SVG as an ``, where no stylesheet can reach it — so the ones the READMEs use are exports, in `docs/images/`. After changing a source diagram that a README shows, regenerate them: diff --git a/docs/images/bmad-delivery-loop-ko.svg b/docs/images/bmad-delivery-loop-ko.svg deleted file mode 100644 index f0b5d1c626..0000000000 --- a/docs/images/bmad-delivery-loop-ko.svg +++ /dev/null @@ -1,158 +0,0 @@ - - - - The BMad delivery loop - Three kinds of input enter the delivery loop at different points: a vague notion enters at Clarify, a big clear idea enters at Plan, and a small change goes straight to Build and verify. The loop continues through Learn and adjust, which feeds back into planning as the work evolves. - - - - - - - - - - - - 어디서든 시작 - - - 눈앞의 작업에 꼭 맞는 절차 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - ? - 막연한 생각 - 크고 명확한 아이디어 - 작은 변경 - - - - 구체화 - - - - 계획 - - - - 구현 및 검증 - - - - 학습 및 조정 - - - - diff --git a/docs/images/bmad-delivery-loop.svg b/docs/images/bmad-delivery-loop.svg index 731b82a754..0f54b29d44 100644 --- a/docs/images/bmad-delivery-loop.svg +++ b/docs/images/bmad-delivery-loop.svg @@ -71,10 +71,10 @@ the gate's CONCERNS heading, a flagged row - so it said "this is a problem" about the diagram's own conclusion. --> - START ANYWHERE + START ANYWHERE - RIGHT-SIZED FOR THE WORK IN FRONT OF YOU + RIGHT-SIZED FOR THE WORK IN FRONT OF YOU