598 lines
18 KiB
Markdown
598 lines
18 KiB
Markdown
# 在棕地中工作：完整指南
|
||
|
||
> **强烈推荐：使用Gemini Web或Gemini CLI进行棕地文档生成！**
|
||
>
|
||
> Gemini Web的1M+令牌上下文窗口或Gemini CLI（当它工作时）可以一次性分析您的整个代码库或其关键部分（当然是在合理范围内）：
|
||
>
|
||
> - 通过GitHub URL上传或在项目文件夹中使用gemini cli
|
||
> - 如果在Web中工作：使用`npx bmad-method flatten`将您的项目展平为单个文件，然后将该文件上传到您的Web代理。
|
||
|
||
## 什么是棕地开发？
|
||
|
||
棕地开发是指为现有软件项目添加功能、修复错误或进行现代化改造。与绿地（新）项目不同，棕地工作需要理解现有代码、尊重约束，并确保新更改无缝集成而不会破坏现有功能。
|
||
|
||
## 何时为棕地使用BMad
|
||
|
||
- 向现有应用程序添加重要的新功能
|
||
- 现代化遗留代码库
|
||
- 集成新技术或服务
|
||
- 重构复杂系统
|
||
- 修复需要架构理解的错误
|
||
- 记录未记录的系统
|
||
|
||
## 何时不使用棕地流程
|
||
|
||
如果您刚刚用BMad完成了MVP，并且想继续进行MVP后的工作，那么与PM交谈并要求他与您合作创建一个新的史诗以添加到PRD中，分片史诗，与架构师一起更新任何架构文档，然后从那里开始会更容易。
|
||
|
||
## 完整的棕地工作流
|
||
|
||
1. **遵循[<ins>用户指南-安装</ins>](user-guide.md#installation)步骤在Web中设置您的代理。**
|
||
2. **生成整个代码库的“扁平化”单个文件** 运行：`npx bmad-method flatten`
|
||
|
||
### 选择您的方法
|
||
|
||
#### 方法A：PRD优先（推荐用于添加非常大和复杂的新功能、单个或多个史诗或大规模更改）
|
||
|
||
**最适合**：大型代码库、monorepos，或者当您确切知道要构建什么时
|
||
|
||
1. **首先创建PRD**来定义需求
|
||
2. **仅根据PRD需求记录相关区域**
|
||
3. **更高效** - 避免记录未使用的代码
|
||
|
||
#### 方法B：文档优先（适用于较小项目）
|
||
|
||
**最适合**：较小的代码库、未知的系统或探索性更改
|
||
|
||
1. **首先记录整个系统**
|
||
2. **用完整的上下文创建PRD**
|
||
3. **更彻底** - 捕获所有内容
|
||
|
||
### 方法A：PRD优先工作流（推荐）
|
||
|
||
#### 阶段1：首先定义需求
|
||
|
||
**在Gemini Web中（上传了您的flattened-codebase.xml）：**
|
||
|
||
```bash
|
||
@pm
|
||
*create-brownfield-prd
|
||
```
|
||
|
||
PM将：
|
||
|
||
- **询问您的增强**需求
|
||
- **探索代码库**以了解当前状态
|
||
- **识别需要文档的受影响区域**
|
||
- **创建具有明确范围的专注PRD**
|
||
|
||
**主要优势**：PRD确定了您的monorepo/大型代码库的哪些部分实际上需要文档！
|
||
|
||
#### 阶段2：专注文档
|
||
|
||
**仍在Gemini Web中，现在有了PRD上下文：**
|
||
|
||
```bash
|
||
@architect
|
||
*document-project
|
||
```
|
||
|
||
架构师将：
|
||
|
||
- **如果未提供PRD，则询问您的重点**
|
||
- **提供选项**：创建PRD、提供需求或描述增强功能
|
||
- **引用PRD/描述**以了解范围
|
||
- **专注于PRD或您的描述中识别的相关模块**
|
||
- **跳过不相关的区域**以保持文档精简
|
||
- **为所有环境生成一个架构文档**
|
||
|
||
架构师创建：
|
||
|
||
- **一个遵循fullstack-architecture模板的综合架构文档**
|
||
- **在一个文件中涵盖所有系统方面**
|
||
- **易于复制并另存为**`docs/architecture.md`
|
||
- **如果需要，以后可以在IDE中分片**
|
||
|
||
例如，如果您说“向用户服务添加支付处理”：
|
||
|
||
- 仅记录：用户服务、API端点、数据库模式、支付集成
|
||
- 创建仅显示与支付相关的代码路径的专注源树
|
||
- 跳过：管理面板、报告模块、不相关的微服务
|
||
|
||
### 方法B：文档优先工作流
|
||
|
||
#### 阶段1：记录现有系统
|
||
|
||
**最佳方法 - 具有1M+上下文的Gemini Web**：
|
||
|
||
1. **转到Gemini Web** (gemini.google.com)
|
||
2. **上传您的项目**：
|
||
- **选项A**：直接粘贴您的GitHub存储库URL
|
||
- **选项B**：上传您的flattened-codebase.xml文件
|
||
3. **加载架构师代理**：上传`dist/agents/architect.txt`
|
||
4. **运行文档**：输入`*document-project`
|
||
|
||
架构师将生成所有内容的综合文档。
|
||
|
||
#### 阶段2：规划您的增强功能
|
||
|
||
##### 选项A：完整的棕地工作流（推荐用于重大更改）
|
||
|
||
**1. 创建棕地PRD**：
|
||
|
||
```bash
|
||
@pm
|
||
*create-brownfield-prd
|
||
```
|
||
|
||
PM代理将：
|
||
|
||
- **分析来自阶段1的现有文档**
|
||
- **向您请求具体的增强细节**
|
||
- **评估复杂性**并推荐方法
|
||
- **为增强功能创建史诗/故事结构**
|
||
- **识别风险和集成点**
|
||
|
||
**PM代理如何获取项目上下文**：
|
||
|
||
- 在Gemini Web中：已经从阶段1的文档中获得了完整的项目上下文
|
||
- 在IDE中：会问“请提供您现有项目文档的路径”
|
||
|
||
**您会遇到的关键提示**：
|
||
|
||
- “您想添加什么具体的增强或功能？”
|
||
- “这是否需要与任何现有系统或API集成？”
|
||
- “我们必须遵守哪些关键约束？”
|
||
- “您的时间表和团队规模是多少？”
|
||
|
||
**2. 创建棕地架构**：
|
||
|
||
```bash
|
||
@architect
|
||
*create-brownfield-architecture
|
||
```
|
||
|
||
架构师将：
|
||
|
||
- **审查棕地PRD**
|
||
- **设计集成策略**
|
||
- **如果需要，规划迁移方法**
|
||
- **识别技术风险**
|
||
- **定义兼容性要求**
|
||
|
||
##### 选项B：快速增强（用于专注的更改）
|
||
|
||
**对于没有完整PRD的单个史诗**：
|
||
|
||
```bash
|
||
@pm
|
||
*create-brownfield-epic
|
||
```
|
||
|
||
在以下情况下使用：
|
||
|
||
- 增强功能定义明确且孤立
|
||
- 现有文档全面
|
||
- 更改不影响多个系统
|
||
- 您需要快速周转
|
||
|
||
**对于单个故事**：
|
||
|
||
```bash
|
||
@pm
|
||
*create-brownfield-story
|
||
```
|
||
|
||
在以下情况下使用：
|
||
|
||
- 错误修复或微小功能
|
||
- 非常孤立的更改
|
||
- 没有架构影响
|
||
- 清晰的实施路径
|
||
|
||
### 阶段3：验证规划工件
|
||
|
||
```bash
|
||
@po
|
||
*execute-checklist-po
|
||
```
|
||
|
||
PO确保：
|
||
|
||
- 与现有系统兼容
|
||
- 没有计划中的重大更改
|
||
- 风险缓解策略到位
|
||
- 清晰的集成方法
|
||
|
||
### 阶段4：保存和分片文档
|
||
|
||
1. 将您的PRD和架构另存为：
|
||
docs/prd.md
|
||
docs/architecture.md
|
||
（注意：如果管理多个版本，您可以选择性地以“brownfield-”为前缀）
|
||
2. 分片您的文档：
|
||
在您的IDE中
|
||
|
||
```bash
|
||
@po
|
||
shard docs/prd.md
|
||
```
|
||
|
||
```bash
|
||
@po
|
||
shard docs/architecture.md
|
||
```
|
||
|
||
### 阶段5：过渡到开发
|
||
|
||
**遵循[<ins>增强的IDE开发工作流</ins>](enhanced-ide-development-workflow.md)**
|
||
|
||
## 棕地最佳实践
|
||
|
||
### 1. 始终先记录
|
||
|
||
即使您认为自己了解代码库：
|
||
|
||
- 运行`document-project`以捕获当前状态
|
||
- AI代理需要这个上下文
|
||
- 发现未记录的模式
|
||
|
||
### 2. 尊重现有模式
|
||
|
||
棕地模板专门寻找：
|
||
|
||
- 当前的编码约定
|
||
- 现有的架构模式
|
||
- 技术约束
|
||
- 团队偏好
|
||
|
||
### 3. 规划逐步推出
|
||
|
||
棕地更改应：
|
||
|
||
- 支持功能标志
|
||
- 规划回滚策略
|
||
- 包括迁移脚本
|
||
- 保持向后兼容性
|
||
|
||
### 4. 彻底测试集成
|
||
|
||
#### 为什么测试架构师对棕地至关重要
|
||
|
||
在棕地项目中，测试架构师（Quinn）成为您防止破坏现有功能的安全网。与您从头开始构建的绿地不同，棕地需要仔细验证新更改不会破坏已经正常工作的内容。
|
||
|
||
#### 棕地特定的测试挑战
|
||
|
||
测试架构师解决了独特的棕地复杂性：
|
||
|
||
| **挑战** | **测试架构师如何帮助** | **命令** |
|
||
| --- | --- | --- |
|
||
| **回归风险** | 识别哪些现有功能可能会中断 | `*risk` |
|
||
| **遗留依赖** | 映射集成点和隐藏的依赖关系 | `*trace` |
|
||
| **性能下降** | 验证现有流程没有减速 | `*nfr` |
|
||
| **覆盖差距** | 查找新更改触及的未经测试的遗留代码 | `*design` |
|
||
| **重大更改** | 检测API/合同违规 | `*review` |
|
||
| **迁移安全** | 验证数据转换和回滚计划 | `*risk` + `*review` |
|
||
|
||
#### 棕地的完整测试架构师工作流
|
||
|
||
##### 阶段1：开发前（风险与策略）
|
||
|
||
**对棕地至关重要 - 首先运行这些：**
|
||
|
||
```bash
|
||
# 1. 风险评估（故事创建后立即运行）
|
||
@qa *risk {brownfield-story}
|
||
# 识别：遗留依赖、重大更改、集成点
|
||
# 输出：docs/qa/assessments/{epic}.{story}-risk-{YYYYMMDD}.md
|
||
# 棕地重点：
|
||
# - 回归概率评分
|
||
# - 受影响的下游系统
|
||
# - 数据迁移风险
|
||
# - 回滚复杂性
|
||
|
||
# 2. 测试设计（风险评估后）
|
||
@qa *design {brownfield-story}
|
||
# 创建：回归测试策略+新功能测试
|
||
# 输出：docs/qa/assessments/{epic}.{story}-test-design-{YYYYMMDD}.md
|
||
# 棕地重点：
|
||
# - 需要回归测试的现有功能
|
||
# - 集成测试要求
|
||
# - 要维持的性能基准
|
||
# - 功能标志测试场景
|
||
```
|
||
|
||
##### 阶段2：开发期间（持续验证）
|
||
|
||
**在编码时监控集成健康状况：**
|
||
|
||
```bash
|
||
# 3. 需求跟踪（开发中期检查点）
|
||
@qa *trace {brownfield-story}
|
||
# 映射：新需求+现有功能保留
|
||
# 输出：docs/qa/assessments/{epic}.{story}-trace-{YYYYMMDD}.md
|
||
# 棕地重点：
|
||
# - 必须仍然工作的现有功能
|
||
# - 新/旧功能交互
|
||
# - API合同保留
|
||
# - 缺失的回归测试覆盖
|
||
|
||
# 4. NFR验证（考虑“完成”之前）
|
||
@qa *nfr {brownfield-story}
|
||
# 验证：性能、安全性、可靠性不变
|
||
# 输出：docs/qa/assessments/{epic}.{story}-nfr-{YYYYMMDD}.md
|
||
# 棕地重点：
|
||
# - 性能回归检测
|
||
# - 集成的安全影响
|
||
# - 向后兼容性验证
|
||
# - 对遗留组件的负载/压力
|
||
```
|
||
|
||
##### 阶段3：代码审查（深度集成分析）
|
||
|
||
**全面的棕地审查：**
|
||
|
||
```bash
|
||
# 5. 全面审查（开发完成时）
|
||
@qa *review {brownfield-story}
|
||
# 执行：深度分析+主动重构
|
||
# 输出：
|
||
# - 故事文件中的QA结果
|
||
# - 门禁文件：docs/qa/gates/{epic}.{story}-{slug}.yml
|
||
```
|
||
|
||
审查特别分析：
|
||
|
||
- **API重大更改**：验证所有现有合同是否得到维护
|
||
- **数据迁移安全**：检查转换逻辑和回滚程序
|
||
- **性能回归**：与基准指标进行比较
|
||
- **集成点**：验证与遗留代码的所有接触点
|
||
- **功能标志逻辑**：确保正确的切换行为
|
||
- **依赖影响**：映射受影响的下游系统
|
||
|
||
##### 阶段4：审查后（门禁更新）
|
||
|
||
```bash
|
||
# 6. 门禁状态更新（解决问题后）
|
||
@qa *gate {brownfield-story}
|
||
# 更新：修复后的质量门禁决策
|
||
# 输出：docs/qa/gates/{epic}.{story}-{slug}.yml
|
||
# 棕地考虑：
|
||
# - 可能会豁免某些遗留代码问题
|
||
# - 记录技术债务接受情况
|
||
# - 跟踪迁移进度
|
||
```
|
||
|
||
#### 棕地特定的风险评分
|
||
|
||
测试架构师对棕地使用增强的风险评分：
|
||
|
||
| **风险类别** | **棕地因素** | **对门禁的影响** |
|
||
| --- | --- | --- |
|
||
| **回归风险** | 集成点数量×代码年龄 | 评分≥9 = FAIL |
|
||
| **数据风险** | 迁移复杂性×数据量 | 评分≥6 = CONCERNS |
|
||
| **性能风险** | 当前负载×增加的复杂性 | 评分≥6 = CONCERNS |
|
||
| **兼容性风险** | API消费者×合同更改 | 评分≥9 = FAIL |
|
||
|
||
#### 棕地测试标准
|
||
|
||
Quinn对棕地强制执行额外的标准：
|
||
|
||
- **回归测试覆盖率**：每个接触到的遗留模块都需要测试
|
||
- **性能基准**：必须维持或改进当前的指标
|
||
- **回滚程序**：每个更改都需要一个回滚计划
|
||
- **功能标志**：所有有风险的更改都在切换开关后面
|
||
- **集成测试**：覆盖所有遗留接触点
|
||
- **合同测试**：验证API兼容性
|
||
- **数据验证**：迁移正确性检查
|
||
|
||
#### 快速参考：棕地测试命令
|
||
|
||
| **场景** | **要运行的命令** | **顺序** | **为何关键** |
|
||
| --- | --- | --- | --- |
|
||
| **向遗留代码添加功能** | `*risk` → `*design` → `*trace` → `*review` | 顺序 | 首先映射所有依赖 |
|
||
| **API修改** | `*risk` → `*design` → `*nfr` → `*review` | 顺序 | 防止破坏消费者 |
|
||
| **性能关键的更改** | `*nfr`早期并经常→ `*review` | 持续 | 立即发现性能下降 |
|
||
| **数据迁移** | `*risk` → `*design` → `*trace` → `*review` → `*gate` | 完整周期 | 确保数据完整性 |
|
||
| **复杂系统中的错误修复** | `*risk` → `*trace` → `*review` | 专注 | 防止副作用 |
|
||
|
||
#### 与棕地场景的集成
|
||
|
||
**特定场景指南：**
|
||
|
||
1. **遗留代码现代化**
|
||
- 从`*risk`开始以映射所有依赖关系
|
||
- 使用`*design`规划绞杀者无花果方法
|
||
- 经常运行`*trace`以确保没有任何东西损坏
|
||
- `*review`时专注于逐步迁移
|
||
|
||
2. **向单体添加功能**
|
||
- `*risk`识别集成复杂性
|
||
- `*design`规划隔离策略
|
||
- `*nfr`监控性能影响
|
||
- `*review`验证没有单体性能下降
|
||
|
||
3. **微服务提取**
|
||
- `*risk`映射服务边界
|
||
- `*trace`确保功能保留
|
||
- `*nfr`验证网络开销可接受
|
||
- `*gate`记录接受的权衡
|
||
|
||
4. **数据库模式更改**
|
||
- `*risk`评估迁移复杂性
|
||
- `*design`规划向后兼容的方法
|
||
- `*trace`映射所有受影响的查询
|
||
- `*review`验证迁移安全性
|
||
|
||
### 5. 沟通更改
|
||
|
||
记录：
|
||
|
||
- 更改了什么以及为什么
|
||
- 迁移说明
|
||
- 引入的新模式
|
||
- 弃用通知
|
||
|
||
## 常见棕地场景
|
||
|
||
### 场景1：添加新功能
|
||
|
||
1. 记录现有系统
|
||
2. 创建专注于集成的棕地PRD
|
||
3. **测试架构师早期参与**：
|
||
- 在草稿故事上运行`@qa *risk`以识别集成风险
|
||
- 使用`@qa *design`规划回归测试策略
|
||
4. 架构强调兼容性
|
||
5. 故事包括带有测试要求的集成任务
|
||
6. **开发期间**：
|
||
- 开发人员运行`@qa *trace`以验证覆盖率
|
||
- 使用`@qa *nfr`监控性能影响
|
||
7. **审查阶段**：`@qa *review`验证集成安全性
|
||
|
||
### 场景2：现代化遗留代码
|
||
|
||
1. 广泛的文档阶段
|
||
2. PRD包括迁移策略
|
||
3. **测试架构师策略规划**：
|
||
- `@qa *risk`评估现代化复杂性
|
||
- `@qa *design`规划并行测试方法
|
||
4. 架构规划逐步过渡（绞杀者无花果模式）
|
||
5. 故事遵循增量现代化，并带有：
|
||
- 未触及的遗留代码的回归测试
|
||
- 新/旧边界的集成测试
|
||
- 每个阶段的性能基准
|
||
6. **持续验证**：每个增量后运行`@qa *trace`
|
||
7. **门禁管理**：使用`@qa *gate`跟踪技术债务接受情况
|
||
|
||
### 场景3：复杂系统中的错误修复
|
||
|
||
1. 记录相关子系统
|
||
2. 使用`create-brownfield-story`进行专注修复
|
||
3. **测试架构师风险评估**：运行`@qa *risk`以识别副作用的可能性
|
||
4. 包括来自`@qa *design`输出的回归测试要求
|
||
5. **修复期间**：使用`@qa *trace`映射受影响的功能
|
||
6. **提交前**：运行`@qa *review`进行全面验证
|
||
7. 测试架构师使用以下方法验证无副作用：
|
||
- 用于副作用分析的风险分析（概率×影响评分）
|
||
- 跟踪矩阵以确保修复不会破坏相关功能
|
||
- NFR评估以验证性能/安全性不变
|
||
- 门禁决策记录修复安全性
|
||
|
||
### 场景4：API集成
|
||
|
||
1. 记录现有的API模式
|
||
2. PRD定义集成要求
|
||
3. **测试架构师合同分析**：
|
||
- `@qa *risk`识别重大更改的可能性
|
||
- `@qa *design`创建合同测试策略
|
||
4. 架构确保一致的模式
|
||
5. **API测试重点**：
|
||
- 用于向后兼容性的合同测试
|
||
- 新端点的集成测试
|
||
- 增加负载的性能测试
|
||
6. 故事包括API文档更新
|
||
7. **验证检查点**：
|
||
- `@qa *trace`映射所有API消费者
|
||
- `@qa *nfr`验证响应时间
|
||
- `@qa *review`确保没有重大更改
|
||
8. **门禁决策**：记录任何接受的重大更改以及迁移路径
|
||
|
||
## 故障排除
|
||
|
||
### “AI不理解我的代码库”
|
||
|
||
**解决方案**：用更具体的关键文件路径重新运行`document-project`
|
||
|
||
### “生成的计划不符合我们的模式”
|
||
|
||
**解决方案**：在规划阶段之前，用您的特定约定更新生成的文档
|
||
|
||
### “小更改的样板太多”
|
||
|
||
**解决方案**：使用`create-brownfield-story`代替完整的工作流
|
||
|
||
### “集成点不清楚”
|
||
|
||
**解决方案**：在PRD创建期间提供更多上下文，特别强调集成系统
|
||
|
||
## 快速参考
|
||
|
||
### 棕地特定命令
|
||
|
||
```bash
|
||
# 记录现有项目
|
||
@architect *document-project
|
||
|
||
# 创建增强PRD
|
||
@pm *create-brownfield-prd
|
||
|
||
# 创建具有集成重点的架构
|
||
@architect *create-brownfield-architecture
|
||
|
||
# 快速创建史诗
|
||
@pm *create-brownfield-epic
|
||
|
||
# 创建单个故事
|
||
@pm *create-brownfield-story
|
||
```
|
||
|
||
### 用于棕地的测试架构师命令
|
||
|
||
注意：下面显示的是简写形式。完整命令：`*risk-profile`、`*test-design`、`*nfr-assess`、`*trace-requirements`
|
||
|
||
```bash
|
||
# 开发前（规划）
|
||
@qa *risk {story} # 评估回归和集成风险
|
||
@qa *design {story} # 规划回归+新功能测试
|
||
|
||
# 开发期间（验证）
|
||
@qa *trace {story} # 验证新旧覆盖率
|
||
@qa *nfr {story} # 检查性能下降
|
||
|
||
# 开发后（审查）
|
||
@qa *review {story} # 深度集成分析
|
||
@qa *gate {story} # 更新质量决策
|
||
```
|
||
|
||
### 决策树
|
||
|
||
```text
|
||
您有大型代码库或monorepo吗？
|
||
├─ 是 → PRD优先方法
|
||
│ └─ 创建PRD → 仅记录受影响的区域
|
||
└─ 否 → 您是否熟悉代码库？
|
||
├─ 是 → PRD优先方法
|
||
└─ 否 → 文档优先方法
|
||
|
||
这是一个影响多个系统的重大增强吗？
|
||
├─ 是 → 完整的棕地工作流
|
||
│ └─ 始终首先运行测试架构师*risk + *design
|
||
└─ 否 → 这是否比简单的错误修复更复杂？
|
||
├─ 是 → *create-brownfield-epic
|
||
│ └─ 为集成点运行测试架构师*risk
|
||
└─ 否 → *create-brownfield-story
|
||
└─ 如果触及关键路径，仍运行*risk
|
||
|
||
更改是否触及遗留代码？
|
||
├─ 是 → 测试架构师是强制性的
|
||
│ ├─ *risk → 识别回归可能性
|
||
│ ├─ *design → 规划测试覆盖率
|
||
│ └─ *review → 验证无中断
|
||
└─ 否 → 推荐测试架构师
|
||
└─ *review → 确保质量标准
|
||
```
|
||
|
||
## 结论
|
||
|
||
在修改现有系统时，使用BMad方法的棕地开发提供了结构和安全性。测试架构师成为您防止破坏现有功能的关键安全网，使用风险评估、回归测试和持续验证来确保新更改不会破坏现有功能。
|
||
|
||
**棕地成功公式：**
|
||
|
||
1. **首先记录** - 了解存在什么
|
||
2. **尽早评估风险** - 在编码前使用测试架构师`*risk`
|
||
3. **规划测试策略** - 设计回归+新功能测试
|
||
4. **持续验证** - 在开发期间检查集成健康状况
|
||
5. **全面审查** - 在提交前进行深度分析
|
||
6. **果断地进行门禁** - 记录质量决策
|
||
|
||
请记住：**在棕地中，测试架构师不是可选的——它是您防止生产中断的保险单。**
|