情境背景

你剛完成一個 feature branch feat/export-csv，準備開 PR 進 main。改動範圍包含新增 OrderExporter 類別、修改 OrderRepository 加查詢方法、以及一個新的 API endpoint。你想在上傳前先確認兩件事：第一，程式碼有沒有遵循 repo 的編碼標準；第二，這份 diff 有沒有忠實實作原始 issue 的需求。

/code-review 是設計來回答這兩個問題的工具。它對自固定點（commit、branch、tag 或 merge-base）至今的變更進行雙軸審查，並用平行子代理執行，避免兩軸互相污染。

第 1 步：固定比較點

目標：告訴 /code-review 從哪個點開始比對

AI 對話：

• You:

  /code-review
  請從 main 到目前 branch 的 diff 進行雙軸審查。

• AI:

  我會從 main...HEAD 的 diff 進行雙軸審查。

  找到 originating issue：#142 - 訂單 CSV 匯出。我啟動兩個平行子代理：

  • Standards 子代理：檢查是否符合 repo 標準與 Fowler smell 基線。
  • Spec 子代理：逐項對照 issue #142 的需求與 diff。

  完成後並列報告。

固定點可以用 commit SHA、branch 名稱、tag 或 merge-base。/code-review 會先確認 ref 可解析、diff 非空。

第 2 步：找 spec 來源

目標：讓 Spec 軸知道要對照什麼

/code-review 的搜尋順序是固定的：

1. 先看 commit message 有沒有 issue reference（例如 Fixes #142）。
2. 再看使用者有沒有提供 spec 路徑。
3. 再看 docs/、specs/、.scratch/ 下有沒有對應檔案。
4. 找不到時明確標記「沒有 spec」，Spec 軸會以這個前提執行。

如果這次 diff 的 commit message 沒有寫 issue 號，你要手動提供路徑：

• You:

  spec 在 docs/specs/2026-08-order-export.md，請用它當 Spec 軸來源。

第 3 步：雙軸平行執行

目標：理解為什麼兩軸要分開跑

兩軸用平行子代理的原因是避免互相污染。一個 smells 清單如果知道「但它符合 spec」，可能會被洗白。Standards 軸只看程式碼本身是否乾淨，Spec 軸只看 diff 是否覆蓋 issue 需求，兩者各自獨立判斷。

Standards 軸會檢查什麼

• repo 內文件化的編碼標準（CONTEXT.md、ADR、CONTRIBUTING.md）
• 疊加一個 always-on 的 Fowler smell 基線：Mysterious Name、Duplicated Code、Feature Envy、Data Clumps、Primitive Obsession、Repeated Switches、Shotgun Surgery、Divergent Change、Speculative Generality、Message Chains、Middle Man、Refused Bequest

repo 自己的標準覆寫基線，每個 smell 都是判斷呼叫，不是硬性違規。

Spec 軸會檢查什麼

逐項對照 issue 或 spec 的需求清單，確認 diff 是否覆蓋每條需求，標出漏掉的邊界。

第 4 步：並列報告

目標：解讀兩份輸出

AI 對話（完成後）:

• AI:

  Standards 軸

  • Duplicated Code：CSV 欄位排序邏輯在 OrderExporter 與 OrderRepository.toCsvRow 各出現一次。建議抽出共用函式。
  • Primitive Obsession：到處用 string orderId，但 OrderId 是值物件候選。
  • 其餘符合標準。

  Spec 軸

  • 已實作：合法訂單可匯出
  • 已實作：包含訂單時間、金額、狀態欄位
  • 缺漏：issue #142 要求「過濾作廢訂單」，diff 找不到對應處理
  • 已實作：權限檢查

  兩軸 finding 分開統計，沒有合併排序。

注意輸出是並列而非合併。你可以同時看到「程式碼有重複」與「spec 有缺漏」這兩件獨立的事。

第 5 步：依 finding 排序後續動作

目標：把審查結果轉成行動

收到報告後，建議的處理順序是：

1. Spec 軸缺漏優先：spec 沒覆蓋到等於功能沒做完，比 smell 重要。補上「過濾作廢訂單」的邏輯，可以再走一次 /tdd 加測試。
2. Standards 軸的 Duplicated Code：用 /code-review 的 refactor 階段抽出共用函式。這正是 refactor 屬於 /code-review 不屬於 /tdd 的理由。
3. Standards 軸的 Primitive Obsession：這是判斷呼叫，不是硬性違規。值物件重構可以記成 ADR 之後再做，不阻塞這次 PR。

何時不應該用 /code-review

還在實作中、頻繁變動

diff 一直在變，審查結果一下就過時。等 branch 穩定下來再跑。

純探索性原型

原型是用 /prototype 的，原型不上 review。審查一個會被丟掉的 HTML 沒意義。

想找人類 opinions

/code-review 是結構性審查，主觀取捨用 /grilling 來逼問。

工具使用摘要

結果

• 確認 diff 有重複邏輯與值物件候選，但都不是硬性違規
• 確認 issue #142 的「過濾作廢訂單」需求被漏掉
• 學會把審查結果排序：spec 缺漏 > duplicated code > primitive obsession

關鍵學習點

• /code-review 用平行子代理跑兩軸，避免 Standards 知道 Spec 結果後被洗白。
• repo 自己的編碼標準覆寫 Fowler smell 基線，每個 smell 都是判斷呼叫而非硬性違規。
• Spec 軸缺漏比 Standards smell 優先處理，功能沒做完比程式碼不漂亮更要緊。
• refactor 屬於 /code-review 不屬於 /tdd，拿到 smell 報告後在這裡收尾。