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