在棕地專案中工作：完整指南Working in the Brownfield: A Complete Guide

Critical Tip  重要提示

Regardless of what you plan for your existing project you want to start agentic coding with, producing contextual artifacts for agents is of the highest importance.
無論你打算以何種方式在現有專案中開始自主代理式編碼，為代理產出具情境性的產物（contextual artifacts）都是最重要的。

If using Claude Code - it is recommended to use the document-project task with the architect to systematically produce important key artifacts for your codebase.
如果使用 Claude Code，建議與 architect 一起使用 document-project 任務，系統性地為你的程式碼庫產出重要的關鍵產物。

Optionally you can product context information and understanding for your repo utilizing web agents like Gemini. If its already in github, you can provide the project URL in gemini and use the agents to help analyze or document the project with the team fullstack or the architect specific gem.
你可以選擇使用像 Gemini 這類的網路代理為你的倉庫產生上下文資訊與理解。如果專案已經在 GitHub 上，你可以在 Gemini 提供專案 URL，並使用這些代理協助與團隊（fullstack）或特定架構師（architect）套件一起分析或為專案撰寫文件。

If your project is too large, you can also flatten your codebase - which can make it easier to upload or use with some tools. You can read more about the optional tool in the Flattener Guide
若你的專案過大，也可以將程式碼庫展平（flatten）——這會讓上傳或與某些工具一起使用時更為容易。你可以在 Flattener Guide 中閱讀更多關於該選用工具的資訊。

What is Brownfield Development?
什麼是棕地（Brownfield）開發？

Brownfield development refers to adding features, fixing bugs, or modernizing existing software projects. Unlike greenfield (new) projects, brownfield work requires understanding existing code, respecting constraints, and ensuring new changes integrate seamlessly without breaking existing functionality.
棕地開發指的是在既有軟體專案上新增功能、修正錯誤或現代化改造。與綠地（新建）專案不同，棕地工作需要理解現有程式碼、尊重既有限制，並確保新變更能無縫整合而不破壞現有功能。

When to Use BMad for Brownfield
何時在既有場域使用 BMad

• Add significant new features to existing applications
  為現有應用加入重大新功能
• Modernize legacy codebases
  現代化舊有程式碼庫
• Integrate new technologies or services
  整合新技術或服務
• Refactor complex systems
  重構複雜系統
• Fix bugs that require architectural understanding
  修復需要架構層面理解的錯誤
• Document undocumented systems
  為未被記錄的系統撰寫文件

When NOT to use a Brownfield Flow
何時不該使用褐地流程

If you have just completed an MVP with BMad, and you want to continue with post-MVP, its easier to just talk to the PM and ask it to work with you to create a new epic to add into the PRD, shard out the epic, update any architecture documents with the architect, and just go from there.
如果你剛和 BMad 完成了一個 MVP，並且想要繼續進行後續的 post-MVP，最簡單的方式是直接跟產品經理（PM）談，請他與你合作在 PRD 中新增一個 epic，將該 epic 切分（shard）出來，與架構師一起更新任何架構文件，然後就從那裡開始進行。

The Complete Brownfield Workflow
完整的 Brownfield 工作流程

Starting in the Web Option (potentially save some cost but a potentially more frustrating experience):
從 Web 選項開始（可能節省一些成本，但體驗可能較令人沮喪）：

1. Follow the User Guide - Installation steps to setup your agent in the web.
   請依照使用者指南 - 安裝步驟，在 Web 上設定你的代理（agent）。
2. Generate a 'flattened' single file of your entire codebase run: npx bmad-method flatten
   產生一個「扁平化」的單一檔案，包含你整個程式碼庫的執行： npx bmad-method flatten

Starting in an IDE with large context and good models (Its important to use quality models for this process for the best results)
從具備大量上下文和優質模型的 IDE 開始（在此流程中使用高品質模型以取得最佳結果非常重要）

1. In Claude Code or a similar IDE, select the architect agent and then use the *document-project task. You will want to ensure you are validating and directing the agent to produce the best possible documents for LLMs to understand your code base, and not include any misleading or unnecessary info.
   在 Claude Code 或類似的 IDE 中，選擇 architect agent，然後使用 *document-project 任務。你需要確保驗證並指導該 agent，讓它產出最利於 LLM 理解你的程式碼庫的文件，且不包含任何誤導或不必要的資訊。

Choose Your Approach  選擇你的方法

Approach A: PRD-First (Recommended if adding very large and complex new features, single or multiple epics or massive changes)
方法 A：以 PRD 為先（若要新增非常大且複雜的新功能、單一或多個 epic 或大規模變更時建議採用）

Best for: Large codebases, monorepos, or when you know exactly what you want to build
最適用於：大型程式碼庫、單一倉庫(monorepo)，或當你已經非常清楚要構建的內容時

1. Create PRD First to define requirements
   先建立 PRD 以定義需求
2. Document only relevant areas based on PRD needs
   僅根據 PRD 的需求記錄相關區域
3. More efficient - avoids documenting unused code
   更有效率 — 避免紀錄未使用的程式碼

Approach B: Document-First (Good for Smaller Projects)
方法 B：先文件化（適用於較小的專案）

Best for: Smaller codebases, unknown systems, or exploratory changes
適用於：較小的程式碼庫、未知系統或探索性變更

1. Document entire system first
   先將整個系統文件化
2. Create PRD with full context
   建立具有完整背景的產品需求文件（PRD）
3. More thorough - captures everything
   更完整—涵蓋所有細節

Approach A: PRD-First Workflow (Recommended)
方法 A：以 PRD 為先的工作流程（建議）

Phase 1: Define Requirements First
階段 1：先定義需求

In Gemini Web (with your flattened-codebase.xml uploaded):
在 Gemini Web（已上傳 flattened-codebase.xml 時）：

@pm
*create-brownfield-prd

The PM will:  專案經理將會：

• Ask about your enhancement requirements
  詢問您的增強需求
• Explore the codebase to understand current state
  探索程式碼庫以了解目前狀態
• Identify affected areas that need documentation
  識別需要文件化的受影響區域
• Create focused PRD with clear scope
  撰寫具明確範圍的專注式需求規格（PRD）

Key Advantage: The PRD identifies which parts of your monorepo/large codebase actually need documentation!
主要優勢：PRD 能識別出您在 monorepo/大型程式碼庫中實際需要文件化的部分！

Phase 2: Focused Documentation
階段 2：聚焦文件化

Still in Gemini Web, now with PRD context:
仍在 Gemini Web 中，現在有 PRD 的上下文：

@architect
*document-project

The architect will:  架構師將會：

• Ask about your focus if no PRD was provided
  若未提供產品需求文件（PRD），請詢問其重點
• Offer options: Create PRD, provide requirements, or describe the enhancement
  提供選項：建立 PRD、提供需求，或描述此改進
• Reference the PRD/description to understand scope
  參考 PRD/描述以了解範圍
• Focus on relevant modules identified in PRD or your description
  聚焦於 PRD 或您描述中所指出的相關模組
• Skip unrelated areas to keep docs lean
  略過不相關的領域以保持文件精簡
• Generate ONE architecture document for all environments
  為所有環境產生一份單一的架構文件

The architect creates:  架構師建立：

• One comprehensive architecture document following fullstack-architecture template
  一份遵循 fullstack-architecture 範本的完整架構文件
• Covers all system aspects in a single file
  涵蓋所有系統面向於單一檔案中
• Easy to copy and save as docs/architecture.md
  可輕鬆複製並另存為 docs/architecture.md
• Can be sharded later in IDE if desired
  如有需要，日後可在 IDE 中分割成多個檔案

For example, if you say "Add payment processing to user service":
例如，如果你說「新增付款處理到使用者服務」：

• Documents only: user service, API endpoints, database schemas, payment integrations
  僅文件：使用者服務、API 端點、資料庫結構、支付整合
• Creates focused source tree showing only payment-related code paths
  建立精簡的原始碼樹，僅顯示與支付相關的程式碼路徑
• Skips: admin panels, reporting modules, unrelated microservices
  跳過：管理面板、報表模組、不相關的微服務

Approach B: Document-First Workflow
方法 B：以文件為先的工作流程

Phase 1: Document the Existing System
階段一：紀錄現有系統

Best Approach - Gemini Web with 1M+ Context:
最佳做法 — 使用具 1M+ 上下文的 Gemini Web：

1. Go to Gemini Web (gemini.google.com)
   前往 Gemini Web（gemini.google.com）
2. Upload your project:   上傳你的專案：
   • Option A: Paste your GitHub repository URL directly
     選項 A：直接貼上您的 GitHub 倉庫 URL
• Option B: Upload your flattened-codebase.xml file
  選項 B：上傳您的 flattened-codebase.xml 檔案
3. Load the architect agent: Upload dist/agents/architect.txt
   載入架構代理：上傳 dist/agents/architect.txt
4. Run documentation: Type *document-project
   執行文件生成：輸入 *document-project

The architect will generate comprehensive documentation of everything.
建築師會產出所有事物的完整文件。

Phase 2: Plan Your Enhancement
第 2 階段：規劃您的增強

Option A: Full Brownfield Workflow (Recommended for Major Changes)
選項 A：完整棕地工作流程（建議用於重大變更）

1. Create Brownfield PRD:
1. 建立棕地 PRD：

@pm
*create-brownfield-prd

The PM agent will:
專案經理代理人將會：

• Analyze existing documentation from Phase 1
  分析第一階段的現有文件
• Request specific enhancement details from you
  向您請求具體的增強細節
• Assess complexity and recommend approach
  評估複雜度並建議處理方法
• Create epic/story structure for the enhancement
  為此功能改進建立 epic/故事 結構
• Identify risks and integration points
  識別風險與整合接點

How PM Agent Gets Project Context:
PM 代理如何取得專案上下文：

• In Gemini Web: Already has full project context from Phase 1 documentation
  在 Gemini Web：已從第 1 階段文件取得完整的專案上下文
• In IDE: Will ask "Please provide the path to your existing project documentation"
  在 IDE：會要求「請提供您現有專案文件的路徑」

Key Prompts You'll Encounter:
您會遇到的關鍵提示：

• "What specific enhancement or feature do you want to add?"
  「您想新增哪一項具體的強化功能或特性？」
• "Are there any existing systems or APIs this needs to integrate with?"
  「是否有任何現有系統或 API 需要整合？」
• "What are the critical constraints we must respect?"
  「有哪些我們必須遵守的關鍵限制條件？」
• "What is your timeline and team size?"
  「您的時程與團隊規模為何？」

2. Create Brownfield Architecture:
2. 建立褐地（Brownfield）架構：

@architect
*create-brownfield-architecture

The architect will:  架構師將會：

• Review the brownfield PRD
  審查棕地產品需求文件（PRD）
• Design integration strategy
  設計整合策略
• Plan migration approach if needed
  如有需要，規劃遷移方法
• Identify technical risks  識別技術風險
• Define compatibility requirements
  定義相容性需求

Option B: Quick Enhancement (For Focused Changes)
選項 B：快速增強（針對重點變更）

For Single Epic Without Full PRD:
針對單一史詩且無完整產品需求文件：

@pm
*create-brownfield-epic

Use when:  使用時機：

• Enhancement is well-defined and isolated
  增強功能已定義明確且獨立
• Existing documentation is comprehensive
  現有文件已相當完整
• Changes don't impact multiple systems
  變更不會影響多個系統
• You need quick turnaround
  你需要快速回應

For Single Story:  針對單一敘述（Single Story）：

@pm
*create-brownfield-story

Use when:  適用情況：

• Bug fix or tiny feature
  修復錯誤或極小的功能改動
• Very isolated change  非常孤立的變更
• No architectural impact  無架構影響
• Clear implementation path
  清晰的實作路徑

Phase 3: Validate Planning Artifacts
階段 3：驗證規劃產物

@po
*execute-checklist-po

The PO ensures:  產品負責人（PO）確保：

• Compatibility with existing system
  與現有系統相容
• No breaking changes planned
  無計畫進行破壞性變更
• Risk mitigation strategies in place
  已制定風險緩解策略
• Clear integration approach
  明確的整合方式

Phase 4: Save and Shard Documents
階段 4：儲存並分片文件

1. Save your PRD and Architecture as: docs/prd.md docs/architecture.md (Note: You can optionally prefix with 'brownfield-' if managing multiple versions)
   將你的 PRD 和架構文件儲存為：docs/prd.md docs/architecture.md（注意：如果要管理多個版本，也可以選擇在檔名前加上 'brownfield-' 前綴）

Shard your docs: In your IDE
將你的文件分片：在你的 IDE 中

@po
shard docs/prd.md

@po
shard docs/architecture.md

Phase 5: Transition to Development
階段 5：轉入開發

Follow the Enhanced IDE Development Workflow
遵循增強型 IDE 開發工作流程

Brownfield Best Practices
棕地最佳實務

1. Always Document First  1. 始終先進行文件記錄

Even if you think you know the codebase:
即使你自認熟悉程式碼庫：

• Run document-project to capture current state
  執行 document-project 以擷取當前狀態
• AI agents need this context
  AI 代理需要這些上下文
• Discovers undocumented patterns
  發現未記載的模式

2. Respect Existing Patterns
2. 尊重既有模式

The brownfield templates specifically look for:
這些棕地範本特別會尋找：

• Current coding conventions
  目前的程式編碼慣例
• Existing architectural patterns
  既有的架構模式
• Technology constraints  技術限制
• Team preferences  團隊偏好

3. Plan for Gradual Rollout
3. 漸進式推出計畫

Brownfield changes should:
既有系統（棕地）變更應該：

• Support feature flags  支援功能旗標
• Plan rollback strategies
  規劃回滾策略
• Include migration scripts
  包含遷移腳本
• Maintain backwards compatibility
  維持向後相容性

4. Test Integration Thoroughly
4. 徹底測試整合

Why the Test Architect is Critical for Brownfield
為何測試架構師對棕地專案至關重要

In brownfield projects, the Test Architect (Quinn) becomes your safety net against breaking existing functionality. Unlike greenfield where you're building fresh, brownfield requires careful validation that new changes don't destabilize what already works.
在棕地專案中，測試架構師（Quinn）成為防止破壞既有功能的安全網。與從頭開始的綠地專案不同，棕地專案需要謹慎驗證新變更不會讓已運作的部分失去穩定性。

Brownfield-Specific Testing Challenges
棕地專屬的測試挑戰

The Test Architect addresses unique brownfield complexities:
測試架構師處理特有的棕地複雜性：

Complete Test Architect Workflow for Brownfield
完整的棕地測試架構工作流程

Stage 1: Before Development (Risk & Strategy)
階段一：開發前（風險與策略）

CRITICAL FOR BROWNFIELD - Run These First:
棕地關鍵——請先執行下列項目：

# 1. RISK ASSESSMENT (Run IMMEDIATELY after story creation)
@qa *risk {brownfield-story}
# Identifies: Legacy dependencies, breaking changes, integration points
# Output: docs/qa/assessments/{epic}.{story}-risk-{YYYYMMDD}.md
# Brownfield Focus:
#   - Regression probability scoring
#   - Affected downstream systems
#   - Data migration risks
#   - Rollback complexity

# 2. TEST DESIGN (After risk assessment)
@qa *design {brownfield-story}
# Creates: Regression test strategy + new feature tests
# Output: docs/qa/assessments/{epic}.{story}-test-design-{YYYYMMDD}.md
# Brownfield Focus:
#   - Existing functionality that needs regression tests
#   - Integration test requirements
#   - Performance benchmarks to maintain
#   - Feature flag test scenarios

Stage 2: During Development (Continuous Validation)
階段 2：開發期間（持續驗證）

Monitor Integration Health While Coding:
在編碼時監控整合健康狀況：

# 3. REQUIREMENTS TRACING (Mid-development checkpoint)
@qa *trace {brownfield-story}
# Maps: New requirements + existing functionality preservation
# Output: docs/qa/assessments/{epic}.{story}-trace-{YYYYMMDD}.md
# Brownfield Focus:
#   - Existing features that must still work
#   - New/old feature interactions
#   - API contract preservation
#   - Missing regression test coverage

# 4. NFR VALIDATION (Before considering "done")
@qa *nfr {brownfield-story}
# Validates: Performance, security, reliability unchanged
# Output: docs/qa/assessments/{epic}.{story}-nfr-{YYYYMMDD}.md
# Brownfield Focus:
#   - Performance regression detection
#   - Security implications of integrations
#   - Backward compatibility validation
#   - Load/stress on legacy components

Stage 3: Code Review (Deep Integration Analysis)
階段 3：程式碼審查（深入整合分析）

Comprehensive Brownfield Review:
完整的棕地審查：

# 5. FULL REVIEW (When development complete)
@qa *review {brownfield-story}
# Performs: Deep analysis + active refactoring
# Outputs:
#   - QA Results in story file
#   - Gate file: docs/qa/gates/{epic}.{story}-{slug}.yml

The review specifically analyzes:
審查特別分析：

• API Breaking Changes: Validates all existing contracts maintained
  API 不相容變更：驗證所有既有維護中的合約
• Data Migration Safety: Checks transformation logic and rollback procedures
  資料遷移安全性：檢查轉換邏輯與回滾程序
• Performance Regression: Compares against baseline metrics
  效能回歸：與基準指標比較
• Integration Points: Validates all touchpoints with legacy code
  整合接點：驗證與舊有程式碼的所有接觸點
• Feature Flag Logic: Ensures proper toggle behavior
  功能旗標邏輯：確保切換行為正確
• Dependency Impacts: Maps affected downstream systems
  相依性影響：對應受影響的下游系統

Stage 4: Post-Review (Gate Updates)
階段 4：審查後（閘門更新）

# 6. GATE STATUS UPDATE (After addressing issues)
@qa *gate {brownfield-story}
# Updates: Quality gate decision after fixes
# Output: docs/qa/gates/{epic}.{story}-{slug}.yml
# Brownfield Considerations:
#   - May WAIVE certain legacy code issues
#   - Documents technical debt acceptance
#   - Tracks migration progress

Brownfield-Specific Risk Scoring
棕地專屬風險評分

The Test Architect uses enhanced risk scoring for brownfield:
測試架構師對棕地採用強化風險評分：

Brownfield Testing Standards
棕地測試標準

Quinn enforces additional standards for brownfield:
Quinn 對棕地實作加強了額外標準：

• Regression Test Coverage: Every touched legacy module needs tests
  回歸測試覆蓋率：每個被觸及的舊有模組都需有測試
• Performance Baselines: Must maintain or improve current metrics
  效能基準：必須維持或改善現有指標
• Rollback Procedures: Every change needs a rollback plan
  回滾程序：每項變更都需要有回滾計畫
• Feature Flags: All risky changes behind toggles
  功能旗標：所有有風險的變更均置於開關後方
• Integration Tests: Cover all legacy touchpoints
  整合測試：涵蓋所有舊系統接觸點
• Contract Tests: Validate API compatibility
  契約測試：驗證 API 相容性
• Data Validation: Migration correctness checks
  資料驗證：遷移正確性檢查

Quick Reference: Brownfield Test Commands
快速參考：棕地測試指令

Integration with Brownfield Scenarios
與褐地場景的整合

Scenario-Specific Guidance:
情境專屬指引：

1. Legacy Code Modernization
   舊有程式碼現代化
   • Start with *risk to map all dependencies
     從 *risk 開始以對所有相依性進行繪製
• Use *design to plan strangler fig approach
  使用 *design 來規劃逐步替換（strangler fig）策略
• Run *trace frequently to ensure nothing breaks
  經常執行 *trace 以確保一切未被破壞
• *review with focus on gradual migration
  以漸進式遷移為重點的 *review
2. Adding Features to Monolith
   向單體應用新增功能
   • *risk identifies integration complexity
     *risk 識別整合的複雜性
• *design plans isolation strategies
  *design 規劃隔離策略
• *nfr monitors performance impact
  *nfr 監控效能影響
• *review validates no monolith degradation
  *review 驗證單體應用未劣化
3. Microservice Extraction  微服務抽取
   • *risk maps service boundaries
     *risk 對映服務邊界
• *trace ensures functionality preservation
  *trace 確保功能得以保留
• *nfr validates network overhead acceptable
  *nfr 驗證網路額外負擔可接受
• *gate documents accepted trade-offs
  *gate 記錄已接受的取捨
4. Database Schema Changes  資料庫結構變更
   • *risk assesses migration complexity
     *risk 評估遷移的複雜度
• *design plans backward-compatible approach
  *design 規劃向後相容的做法
• *trace maps all affected queries
  *trace 對所有受影響的查詢進行對應
• *review validates migration safety
  *review 驗證遷移安全性

5. Communicate Changes  5. 溝通變更

Document:  文件：

• What changed and why
  變更了什麼以及為什麼
• Migration instructions  遷移說明
• New patterns introduced  新增範式
• Deprecation notices  棄用通知

Common Brownfield Scenarios
常見的棕地情境

Scenario 1: Adding a New Feature
情境 1：新增功能

1. Document existing system
   紀錄現有系統
2. Create brownfield PRD focusing on integration
   建立以整合為重點的棕地 PRD
3. Test Architect Early Involvement:
   讓測試架構師及早參與：
   • Run @qa *risk on draft stories to identify integration risks
     在草稿故事上執行 @qa *risk 以識別整合風險
• Use @qa *design to plan regression test strategy
  使用 @qa *design 來規劃迴歸測試策略
4. Architecture emphasizes compatibility
   架構強調相容性
5. Stories include integration tasks with test requirements
   故事包含帶有測試需求的整合任務
6. During Development:   開發期間：
   • Developer runs @qa *trace to verify coverage
     開發人員執行 @qa *trace 以驗證涵蓋範圍
• Use @qa *nfr to monitor performance impact
  使用 @qa *nfr 來監控效能影響
7. Review Stage: @qa *review validates integration safety
   審查階段： @qa *review 驗證整合安全性

Scenario 2: Modernizing Legacy Code
情境二：現代化舊有程式碼

1. Extensive documentation phase
   大量文件撰寫階段
2. PRD includes migration strategy
   產品需求文件（PRD）包含遷移策略
3. Test Architect Strategy Planning:
   測試架構策略規劃：
   • @qa *risk assesses modernization complexity
     @qa *risk 評估現代化的複雜度
• @qa *design plans parallel testing approach
  @qa *design 規劃平行測試方式
4. Architecture plans gradual transition (strangler fig pattern)
   架構規劃漸進式轉換（絞殺無花果模式）
5. Stories follow incremental modernization with:
   故事遵循漸進現代化，包含：
   • Regression tests for untouched legacy code
     對未改動的遺留程式碼進行回歸測試
• Integration tests for new/old boundaries
  針對新舊邊界進行整合測試
• Performance benchmarks at each stage
  在每個階段進行效能基準測試
6. Continuous Validation: Run @qa *trace after each increment
   持續驗證：在每次增量後執行 @qa *trace
7. Gate Management: Use @qa *gate to track technical debt acceptance
   閘門管理：使用 @qa *gate 來追蹤技術負債的接受情況

Scenario 3: Bug Fix in Complex System
場景 3：在複雜系統中的錯誤修復

1. Document relevant subsystems
   文件相關子系統
2. Use create-brownfield-story for focused fix
   針對性修正請使用 create-brownfield-story
3. Test Architect Risk Assessment: Run @qa *risk to identify side effect potential
   測試架構風險評估：執行 @qa *risk 以識別副作用可能性
4. Include regression test requirements from @qa *design output
   納入來自 @qa *design 輸出的回歸測試需求
5. During Fix: Use @qa *trace to map affected functionality
   修復期間：使用 @qa *trace 來對受影響的功能進行對應
6. Before Commit: Run @qa *review for comprehensive validation
   提交前：執行 @qa *review 以進行全面驗證
7. Test Architect validates no side effects using:
   測試架構師使用以下方式驗證無副作用：
   • Risk profiling for side effect analysis (probability × impact scoring)
     副作用風險剖析（機率 × 影響 評分）
• Trace matrix to ensure fix doesn't break related features
  追蹤矩陣以確保修正不會破壞相關功能
• NFR assessment to verify performance/security unchanged
  非功能性需求評估以驗證效能/安全性未改變
• Gate decision documents fix safety
  決審文件以確認修正安全

Scenario 4: API Integration
情境 4：API 整合

1. Document existing API patterns
   記錄現有的 API 範式
2. PRD defines integration requirements
   產品需求文件（PRD）定義整合需求
3. Test Architect Contract Analysis:
   測試架構師合約分析：
   • @qa *risk identifies breaking change potential
     @qa *risk 識別潛在的破壞性變更
• @qa *design creates contract test strategy
  @qa *design 建立合約測試策略
4. Architecture ensures consistent patterns
   架構確保一致的模式
5. API Testing Focus:   API 測試重點：
   • Contract tests for backward compatibility
     確保向後相容性的合約測試
• Integration tests for new endpoints
  新端點的整合測試
• Performance tests for added load
  新增負載的效能測試
6. Stories include API documentation updates
   任務（Stories）包含 API 文件更新
7. Validation Checkpoints:   驗證檢查點：
   • @qa *trace maps all API consumers
     @qa *trace 對所有 API 使用者進行映射
• @qa *nfr validates response times
  @qa *nfr 驗證回應時間
• @qa *review ensures no breaking changes
  @qa *review 確保不會有破壞性變更
8. Gate Decision: Document any accepted breaking changes with migration path
   決策關卡：記錄任何被接受的破壞性變更並附上遷移路徑

Troubleshooting  疑難排解

"The AI doesn't understand my codebase"
「這個 AI 不理解我的程式碼庫」

Solution: Re-run document-project with more specific paths to critical files
解決方法：以更明確的路徑對關鍵檔案重新執行 document-project

"Generated plans don't fit our patterns"
「產生的計畫不符合我們的模式」

Solution: Update generated documentation with your specific conventions before planning phase
解決方案：在規劃階段之前，先用你的特定慣例更新產生的文件

"Too much boilerplate for small changes"
「對於小變更來說樣板程式碼太多」

Solution: Use create-brownfield-story instead of full workflow
解決方案：使用 create-brownfield-story 取代完整工作流程

"Integration points unclear"
「整合點不清楚」

Solution: Provide more context during PRD creation, specifically highlighting integration systems
解法：在建立產品需求文件（PRD）時提供更多上下文，特別強調整合系統

Quick Reference  快速參考

Brownfield-Specific Commands
棕地專用指令

# Document existing project
@architect *document-project

# Create enhancement PRD
@pm *create-brownfield-prd

# Create architecture with integration focus
@architect *create-brownfield-architecture

# Quick epic creation
@pm *create-brownfield-epic

# Single story creation
@pm *create-brownfield-story

Test Architect Commands for Brownfield
棕地測試架構師指令

Note: Short forms shown below. Full commands: *risk-profile, *test-design, *nfr-assess, *trace-requirements
注意：下方顯示為簡寫。完整指令： *risk-profile 、 *test-design 、 *nfr-assess 、 *trace-requirements

# BEFORE DEVELOPMENT (Planning)
@qa *risk {story}     # Assess regression & integration risks
@qa *design {story}   # Plan regression + new feature tests

# DURING DEVELOPMENT (Validation)
@qa *trace {story}    # Verify coverage of old + new
@qa *nfr {story}      # Check performance degradation

# AFTER DEVELOPMENT (Review)
@qa *review {story}   # Deep integration analysis
@qa *gate {story}     # Update quality decision

Decision Tree  決策樹

Do you have a large codebase or monorepo?
├─ Yes → PRD-First Approach
│   └─ Create PRD → Document only affected areas
└─ No → Is the codebase well-known to you?
    ├─ Yes → PRD-First Approach
    └─ No → Document-First Approach

Is this a major enhancement affecting multiple systems?
├─ Yes → Full Brownfield Workflow
│   └─ ALWAYS run Test Architect *risk + *design first
└─ No → Is this more than a simple bug fix?
    ├─ Yes → *create-brownfield-epic
    │   └─ Run Test Architect *risk for integration points
    └─ No → *create-brownfield-story
        └─ Still run *risk if touching critical paths

Does the change touch legacy code?
├─ Yes → Test Architect is MANDATORY
│   ├─ *risk → Identify regression potential
│   ├─ *design → Plan test coverage
│   └─ *review → Validate no breakage
└─ No → Test Architect is RECOMMENDED
    └─ *review → Ensure quality standards

Conclusion  結論

Brownfield development with BMad Method provides structure and safety when modifying existing systems. The Test Architect becomes your critical safety net, using risk assessment, regression testing, and continuous validation to ensure new changes don't destabilize existing functionality.
使用 BMad 方法進行既有系統開發，在修改現有系統時提供結構與安全保障。測試架構師成為你重要的安全網，透過風險評估、回歸測試與持續驗證，確保新變更不會破壞既有功能。

The Brownfield Success Formula:
棕地成功公式：

1. Document First - Understand what exists
   文件優先 - 了解現有狀況
2. Assess Risk Early - Use Test Architect *risk before coding
   及早評估風險 - 在編碼前使用 Test Architect *risk
3. Plan Test Strategy - Design regression + new feature tests
   規劃測試策略 — 設計回歸測試與新功能測試
4. Validate Continuously - Check integration health during development
   持續驗證 — 在開發過程中檢查整合狀態
5. Review Comprehensively - Deep analysis before committing
   全面審查 — 在提交前進行深入分析
6. Gate Decisively - Document quality decisions
   果斷把關 — 文件化品質決策

Remember: In brownfield, the Test Architect isn't optional - it's your insurance policy against breaking production.
記住：在棕地專案中，測試架構師不是可有可無的——他是你避免破壞生產環境的保險。