# 在棕地中工作：完整指南

> **强烈推荐：使用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.  **果断地进行门禁** - 记录质量决策

请记住：**在棕地中，测试架构师不是可选的——它是您防止生产中断的保险单。**