docs: rewrite quick-fixes how-to around Quick Dev workflow
Remove DEV agent references and simplify to Quick Dev as the single entry point. Show free-form intent examples, add deferred work section, clarify that Quick Dev commits for you. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
Alex Verkhovsky
parent
3bb953f18b
commit
3fad46849f
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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**：约定式提交。遵循标准格式的提交消息。
|
||||
|
|
|
|||
Loading…
Reference in New Issue