diff --git a/docs/how-to/quick-fixes.md b/docs/how-to/quick-fixes.md index 7de4263a8..3b695a52d 100644 --- a/docs/how-to/quick-fixes.md +++ b/docs/how-to/quick-fixes.md @@ -5,119 +5,91 @@ sidebar: order: 5 --- -Use the **DEV agent** directly for bug fixes, refactorings, or small targeted changes that don't require the full BMad Method or Quick Flow. +Use **Quick Dev** for bug fixes, refactorings, or small targeted changes that don't require the full BMad Method. ## When to Use This - Bug fixes with a clear, known cause - Small refactorings (rename, extract, restructure) contained within a few files - Minor feature tweaks or configuration changes -- Exploratory work to understand an unfamiliar codebase +- Dependency updates :::note[Prerequisites] - BMad Method installed (`npx bmad-method install`) - An AI-powered IDE (Claude Code, Cursor, or similar) ::: -## Choose Your Approach - -| Situation | Agent | Why | -| --- | --- | --- | -| Fix a specific bug or make a small, scoped change | **DEV agent** | Jumps straight into implementation without planning overhead | -| Change touches several files or you want a written plan first | **Quick Flow Solo Dev** | Clarifies intent, plans, implements, and reviews in a single workflow so the agent stays aligned to your standards | - -If you are unsure, start with the DEV agent. You can always escalate to Quick Flow if the change grows. - ## Steps -### 1. Invoke the DEV Agent +### 1. Start a Fresh Chat -Start a **fresh chat** in your AI IDE and invoke the DEV agent skill: +Open a **fresh chat session** in your AI IDE. Reusing a session from a previous workflow can cause context conflicts. + +### 2. Give It Your Intent + +Quick Dev accepts free-form intent — before, with, or after the invocation. Examples: ```text -bmad-dev +run quick-dev — Fix the login validation bug that allows empty passwords. ``` -This loads the agent's persona and capabilities into the session. If you decide you need Quick Flow instead, invoke the **Quick Flow Solo Dev** agent skill in a fresh chat: - ```text -bmad-quick-flow-solo-dev +run quick-dev — fix https://github.com/org/repo/issues/42 ``` -Once the Solo Dev agent is loaded, describe your change and tell it to run **quick-dev**. The workflow will clarify your intent, create a plan, implement the change, run a code review, and present results — all in a single run. +```text +run quick-dev — implement the intent in _bmad-output/implementation-artifacts/my-intent.md +``` -:::tip[Fresh Chats] -Always start a new chat session when loading an agent. Reusing a session from a previous workflow can cause context conflicts. -::: +```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 quick-dev +``` -### 2. Describe the Change +```text +run quick-dev +> What would you like to do? +Refactor UserService to use async/await instead of callbacks. +``` -Tell the agent what you need in plain language. Be specific about the problem and, if you know it, where the relevant code lives. +Plain text, file paths, GitHub issue URLs, bug tracker links — anything the LLM can resolve to a concrete intent. -:::note[Example Prompts] -**Bug fix** -- "Fix the login validation bug that allows empty passwords. The validation logic is in `src/auth/validate.ts`." +### 3. Answer Questions and Approve -**Refactoring** -- "Refactor the UserService to use async/await instead of callbacks." +Quick Dev may ask clarifying questions or present a short spec for your approval before implementing. Answer its questions and approve when you're satisfied with the plan. -**Configuration change** -- "Update the CI pipeline to cache node_modules between runs." +### 4. Review and Push -**Dependency update** -- "Upgrade the express dependency to the latest v5 release and fix any breaking changes." -::: +Quick Dev implements the change, reviews its own work, patches issues, and commits locally. When it's done, it opens the affected files in your editor. -You don't need to provide every detail. The agent will read the relevant source files and ask clarifying questions when needed. +- Skim the diff to confirm the change matches your intent +- If something looks off, tell the agent what to fix — it can iterate in the same session -### 3. Let the Agent Work - -The agent will: - -- Read and analyze the relevant source files -- Propose a solution and explain its reasoning -- Implement the change across the affected files -- Run your project's test suite if one exists - -If your project has tests, the agent runs them automatically after making changes and iterates until tests pass. For projects without a test suite, verify the change manually (run the app, hit the endpoint, check the output). - -### 4. Review and Verify - -Before committing, review what changed: - -- Read through the diff to confirm the change matches your intent -- Run the application or tests yourself to double-check -- If something looks wrong, tell the agent what to fix -- it can iterate in the same session - -Once satisfied, commit the changes with a clear message describing the fix. +Once satisfied, push the commit. Quick Dev will offer to push and create a PR for you. :::caution[If Something Breaks] -If a committed change causes unexpected issues, use `git revert HEAD` to undo the last commit cleanly. Then start a fresh chat with the DEV agent to try a different approach. +If a pushed change causes unexpected issues, use `git revert HEAD` to undo the last commit cleanly. Then start a fresh chat and run Quick Dev again to try a different approach. ::: -## Learning Your Codebase - -The DEV agent is also useful for exploring unfamiliar code. Load it in a fresh chat and ask questions: - -:::note[Example Prompts] -"Explain how the authentication system works in this codebase." - -"Show me where error handling happens in the API layer." - -"What does the `ProcessOrder` function do and what calls it?" -::: - -Use the agent to learn about your project, understand how components connect, and explore unfamiliar areas before making changes. - ## What You Get - Modified source files with the fix or refactoring applied - Passing tests (if your project has a test suite) -- A clean commit describing the change +- A ready-to-push commit with a conventional commit message -No planning artifacts are produced -- that's the point of this approach. +## Deferred Work + +Quick Dev keeps each run focused on a single goal. If your request contains multiple independent goals, or if the review surfaces pre-existing issues unrelated to your change, Quick Dev defers them to a file (`deferred-work.md` in your implementation artifacts directory) rather than trying to tackle everything at once. + +Check this file after a run — it's your backlog of things to come back to. Each deferred item can be fed into a fresh Quick Dev run later. ## When to Upgrade to Formal Planning -Consider using [Quick Dev](../explanation/quick-dev.md) or the full BMad Method when: +Consider using the full BMad Method when: - The change affects multiple systems or requires coordinated updates across many files -- You are unsure about the scope and need a spec to think it through -- The fix keeps growing in complexity as you work on it +- You are unsure about the scope and need requirements discovery first - You need documentation or architectural decisions recorded for the team + +See [Quick Dev](../explanation/quick-dev.md) for more on how Quick Dev fits into the BMad Method. diff --git a/docs/zh-cn/how-to/quick-fixes.md b/docs/zh-cn/how-to/quick-fixes.md index 4320adbcc..4451627df 100644 --- a/docs/zh-cn/how-to/quick-fixes.md +++ b/docs/zh-cn/how-to/quick-fixes.md @@ -5,135 +5,103 @@ sidebar: order: 5 --- -直接使用 **DEV 智能体**进行 bug 修复、重构或小型针对性更改，这些操作不需要完整的 BMad Method 或 Quick Flow。 +使用 **Quick Dev** 进行 bug 修复、重构或小型针对性更改，这些操作不需要完整的 BMad Method。 ## 何时使用此方法 - 原因明确且已知的 bug 修复 - 包含在少数文件中的小型重构（重命名、提取、重组） - 次要功能调整或配置更改 -- 探索性工作，以了解不熟悉的代码库 +- 依赖更新 :::note[前置条件] - 已安装 BMad Method（`npx bmad-method install`） - AI 驱动的 IDE（Claude Code、Cursor 或类似工具） ::: -## 选择你的方法 - -| 情况 | 智能体 | 原因 | -| --- | --- | --- | -| 修复特定 bug 或进行小型、范围明确的更改 | **DEV agent** | 直接进入实现，无需规划开销 | -| 更改涉及多个文件，或希望先有书面计划 | **Quick Flow Solo Dev** | 在单个工作流中澄清意图、规划、实现和审查，使智能体与你的标准保持一致 | - -如果不确定，请从 DEV 智能体开始。如果更改范围扩大，你始终可以升级到 Quick Flow。 - ## 步骤 -### 1. 加载 DEV 智能体 +### 1. 启动新的聊天 -在 AI IDE 中启动一个**新的聊天**，并使用斜杠命令加载 DEV 智能体： +在 AI IDE 中打开一个**新的聊天会话**。重用之前工作流的会话可能导致上下文冲突。 + +### 2. 提供你的意图 + +Quick Dev 接受自由形式的意图——可以在调用之前、同时或之后提供。示例： ```text -/bmad-agent-bmm-dev +run quick-dev — 修复允许空密码的登录验证 bug。 ``` -这会将智能体的角色和能力加载到会话中。如果你决定需要 Quick Flow，请在新的聊天中加载 **Quick Flow Solo Dev** 智能体： - ```text -/bmad-agent-bmm-quick-flow-solo-dev +run quick-dev — fix https://github.com/org/repo/issues/42 ``` -加载 Solo Dev 智能体后，描述你的更改并告诉它运行 **quick-dev**。工作流将澄清你的意图、创建计划、实现更改、运行代码审查并呈现结果 — 全部在单次运行中完成。 +```text +run quick-dev — 实现 _bmad-output/implementation-artifacts/my-intent.md 中的意图 +``` -:::tip[新聊天] -加载智能体时始终启动新的聊天会话。重用之前工作流的会话可能导致上下文冲突。 -::: +```text +我觉得问题在 auth 中间件，它没有检查 token 过期。 +让我看看... 是的，src/auth/middleware.ts 第 47 行完全跳过了 +exp 检查。run quick-dev +``` -### 2. 描述更改 +```text +run quick-dev +> 你想做什么？ +重构 UserService 以使用 async/await 而不是回调。 +``` -用通俗语言告诉智能体你需要什么。具体说明问题，如果你知道相关代码的位置，也请说明。 +纯文本、文件路径、GitHub issue URL、bug 跟踪器链接——任何 LLM 能解析为具体意图的内容都可以。 -:::note[示例提示词] -**Bug 修复** -- "修复允许空密码的登录验证 bug。验证逻辑位于 `src/auth/validate.ts`。" +### 3. 回答问题并批准 -**重构** -- "重构 UserService 以使用 async/await 而不是回调。" +Quick Dev 可能会提出澄清问题，或在实现之前呈现简短的规范供你批准。回答它的问题，并在你对计划满意时批准。 -**配置更改** -- "更新 CI 流水线以在运行之间缓存 node_modules。" +### 4. 审查和推送 -**依赖更新** -- "将 express 依赖升级到最新的 v5 版本并修复任何破坏性更改。" -::: +Quick Dev 实现更改、审查自己的工作、修复问题，并在本地提交。完成后，它会在编辑器中打开受影响的文件。 -你不需要提供每个细节。智能体会读取相关的源文件，并在需要时提出澄清问题。 - -### 3. 让智能体工作 - -智能体将： - -- 读取并分析相关的源文件 -- 提出解决方案并解释其推理 -- 在受影响的文件中实现更改 -- 如果存在测试套件，则运行项目的测试套件 - -如果你的项目有测试，智能体会在进行更改后自动运行它们，并迭代直到测试通过。对于没有测试套件的项目，请手动验证更改（运行应用、访问端点、检查输出）。 - -### 4. 审查和验证 - -在提交之前，审查更改内容： - -- 通读 diff 以确认更改符合你的意图 -- 自己运行应用程序或测试以再次检查 +- 浏览 diff 以确认更改符合你的意图 - 如果看起来有问题，告诉智能体需要修复什么——它可以在同一会话中迭代 -满意后，使用描述修复的清晰消息提交更改。 +满意后，推送提交。Quick Dev 会提供推送和创建 PR 的选项。 :::caution[如果出现问题] -如果提交的更改导致意外问题，请使用 `git revert HEAD` 干净地撤销最后一次提交。然后启动与 DEV 智能体的新聊天以尝试不同的方法。 +如果推送的更改导致意外问题，请使用 `git revert HEAD` 干净地撤销最后一次提交。然后启动新聊天并再次运行 Quick Dev 以尝试不同的方法。 ::: -## 学习你的代码库 - -DEV 智能体也适用于探索不熟悉的代码。在新的聊天中加载它并提出问题： - -:::note[示例提示词] -"解释此代码库中的身份验证系统是如何工作的。" - -"向我展示 API 层中的错误处理发生在哪里。" - -"`ProcessOrder` 函数的作用是什么，什么调用了它？" -::: - -使用智能体了解你的项目，理解组件如何连接，并在进行更改之前探索不熟悉的区域。 - ## 你将获得 - 已应用修复或重构的修改后的源文件 - 通过的测试（如果你的项目有测试套件） -- 描述更改的干净提交 +- 带有约定式提交消息的准备推送的提交 -不会生成规划产物——这就是这种方法的意义所在。 +## 延迟工作 + +Quick Dev 保持每次运行聚焦于单一目标。如果你的请求包含多个独立目标，或者审查发现了与你的更改无关的已有问题，Quick Dev 会将它们延迟到一个文件中（实现产物目录中的 `deferred-work.md`），而不是试图一次解决所有问题。 + +运行后检查此文件——它是你的待办事项积压。每个延迟项目都可以稍后输入到新的 Quick Dev 运行中。 ## 何时升级到正式规划 -在以下情况下考虑使用 [Quick Dev](../explanation/quick-dev.md) 或完整的 BMad Method： +在以下情况下考虑使用完整的 BMad Method： - 更改影响多个系统或需要在许多文件中进行协调更新 -- 你不确定范围，需要规范来理清思路 -- 修复在工作过程中变得越来越复杂 +- 你不确定范围，需要先进行需求发现 - 你需要为团队记录文档或架构决策 +参见 [Quick Dev](../explanation/quick-dev.md) 了解 Quick Dev 如何融入 BMad Method。 + --- ## 术语说明 -- **agent**：智能体。在人工智能与编程文档中，指具备自主决策或执行能力的单元。 -- **Quick Flow**：快速流程。BMad Method 中的一种统一工作流程，用于快速澄清意图、规划、实现和审查小型更改。 +- **Quick Dev**：快速开发。BMad Method 中的快速工作流，用于小型更改的完整实现周期。 - **refactoring**：重构。在不改变代码外部行为的情况下改进其内部结构的过程。 - **breaking changes**：破坏性更改。可能导致现有代码或功能不再正常工作的更改。 - **test suite**：测试套件。一组用于验证软件功能的测试用例集合。 - **CI pipeline**：CI 流水线。持续集成流水线，用于自动化构建、测试和部署代码。 -- **async/await**：异步编程语法。JavaScript/TypeScript 中用于处理异步操作的语法糖。 -- **callbacks**：回调函数。作为参数传递给其他函数并在适当时候被调用的函数。 -- **endpoint**：端点。API 中可访问的特定 URL 路径。 - **diff**：差异。文件或代码更改前后的对比。 - **commit**：提交。将更改保存到版本控制系统的操作。 -- **git revert HEAD**：Git 命令，用于撤销最后一次提交。 +- **conventional commit**：约定式提交。遵循标准格式的提交消息。