LLM 知識庫

Appearance

Harness Code Review SOP ​

以 Harness 在 Claude Code 中建立六視角平行 Code Review 團隊，並支援修正後複查（Re-review）的完整 SOP。

概述 ​

Harness（revfactory/harness）是 Claude Code 的 meta-skill，核心設計是「設計師」而非「執行者」——它根據專案技術棧自動生成一組專門化的 agent 定義（.claude/agents/）和對應的 skill（.claude/skills/），建立針對該專案量身訂做的 code review 團隊。

與單視角 code review 不同，Harness 採用 Fan-out/Fan-in 架構：多個 reviewer agent 平行獨立執行，各自聚焦不同面向（架構、安全、效能、程式風格、測試覆蓋、前後端邊界整合），互不污染各自的 findings，最後由 orchestrator lead agent 合併成一份嚴重度排序報告。這種架構特別擅長發現跨邊界的 integration bug（前端期待的資料格式 vs. 後端實際回傳的 shape），是單視角 review 的盲點。

Harness 適用於高風險、大型、架構級變更；每次執行會消耗 50K–200K token。例行小 PR 應使用輕量的單視角 skill，Harness 的效益隨任務複雜度放大。

核心內容 ​

產物結構 ​

Harness 執行後在專案目錄生成：

your-project/
├── .claude/
│   ├── agents/
│   │   ├── review-orchestrator.md      # 隊長：組隊、派工、merge 報告
│   │   ├── architecture-reviewer.md
│   │   ├── security-reviewer.md
│   │   ├── performance-reviewer.md
│   │   ├── style-reviewer.md
│   │   ├── test-coverage-reviewer.md
│   │   └── integration-qa.md           # 必須是 general-purpose 型
│   └── skills/
│       ├── code-review-orchestrate/SKILL.md
│       └── （各視角 review skill）
└── CLAUDE.md  （新增 harness 指標 + 變更歷史表）

Orchestrator 以 TeamCreate 組隊、TaskCreate 派工；各 reviewer 平行執行，中間產物寫入 _workspace/；最後 lead agent 收斂為單一報告。

六大 Review 視角 ​

Agent審查重點
architecture-reviewer架構設計、模組邊界、關注點分離
security-reviewerSQL injection、XSS、認證邏輯缺陷等安全漏洞
performance-reviewerN+1 查詢、不必要計算、記憶體洩漏
style-reviewer程式碼風格、可維護性、命名一致性
test-coverage-reviewer測試覆蓋缺口、邊界條件、測試品質
integration-qa前後端 API Shape 交叉比對（後端回傳 vs. 前端期待）

Re-review 複查機制 ​

修正後不需重新執行全量 review，Harness 支援迴圈複查：

  1. 開發者修正 Critical/High findings
  2. Re-review prompt 觸發 orchestrator 進入「部分再執行」模式
  3. 舊的 _workspace/ 移至 _workspace_prev/（保留完整歷史）
  4. 僅重跑受影響的 reviewer
  5. 輸出 Resolved / Still Open / Newly Introduced 三類結果

這個迴圈可反覆執行，直到 Still Open 清空。_workspace_prev/ 保留完整修正軌跡。

Finding 修復路徑分流 ​

Review 報告產出後，不要一律丟回 Claude「照建議修一修」——Critical findings 的 fix recommendation 通常只指明方向，缺乏 plan 約束時 Claude 容易跳著修、改一半、引入新問題，導致 Re-review 大量出現 Newly Introduced。應按 finding 屬性分流到三條路徑：

路徑做法適用條件
路徑 1 直接修將 finding 與 fix recommendation 直接交給 Claude 執行Severity ≤ Medium、單檔局部、≤ 20 行、無行為語意變更（風格、命名、typo、null check）
路徑 2 OpenSpec proposal開 change proposal 重新對齊 spec，再走實作流程finding 揭露 spec 設計層問題（API contract 雙方理解不一致、模組邊界劃錯、概念在 spec 中不存在）
路徑 3 writing-plan + TDD用 Superpowers writing-plans 寫 plan，再以 TDD 或 subagent-driven-development 執行Critical/High、跨檔案、安全/效能類、會碰到外部 contract（DB schema、API response）

分流決策樹：

讀完報告 → 按 severity 分桶
├─ Medium / Low → 路徑 1 一次清掉
└─ Critical / High
    ├─ 設計層問題（spec 本身錯） → 路徑 2
    └─ 實作層問題                  → 路徑 3

默認升級規則：報告含 任一 Critical 或 ≥3 個 High → 強制升級到路徑 3，不要走路徑 1。多個 Critical 集中在同一邏輯區塊時更需先 plan 再動手——表示問題比表面深，協調順序比快速 patch 重要。

OpenSpec 的時序關係：OpenSpec proposal 與 Harness 的關係是前序而非後續——理想情境是 spec → 實作 → Harness review；review 後才開 proposal，只在 spec 本身被打臉時合理。

修復節奏：每修完一批 Critical/High 就跑一次 Re-review，不要等全部修完才驗證，避免「以為修好」的累積誤差。

前置條件確認 ​

項目要求確認指令
Claude Code 版本v2.x 以上claude --version
Harness 插件harness@harness 為 activeclaude plugin list
實驗旗標CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1echo $CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS

安裝 Harness：

bash
claude plugin marketplace add revfactory/harness
claude plugin install harness@harness-marketplace

⚠️ export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 僅在當前 shell 有效。建議寫入 ~/.zshrc 或 ~/.bashrc，避免開新 terminal 後忘記重設（症狀：只有一個 agent 回應，team 沒成形）。

生成的 Harness 架構驗證清單 ​

Harness 生成後應檢查（不符合時直接告訴 Claude 修正即可）：

  • [ ] 每個 reviewer 有獨立的 .md 定義檔
  • [ ] integration-qa.md 是 general-purpose 型（Explore 唯讀，無法執行驗證腳本）
  • [ ] orchestrator skill 的 description 含「re-review / 後續更新」相關關鍵詞（否則複查不觸發）
  • [ ] .claude/commands/ 應為空（Harness 不產生 command）
  • [ ] CLAUDE.md 只留「觸發規則 + 變更歷史」，未將 agent/skill 清單塞進去

關鍵要點 ​

  • Harness 最佳落點：高風險變更的最終審查，可在 Superpowers subagent-driven-development 完成後、合併前執行
  • _workspace/ 是稽核資產，Re-review 和歷史追蹤都依賴它——不要刪除
  • 所有 agent 應使用 model: "opus"，review 品質直接綁在推理能力上
  • 半成品專案應縮範圍至「已完成的變更」，避免 stub/TODO 被報成缺陷
  • 一次只跑一個 harness 任務，不要用 && 串多個呼叫
  • 可將 OpenSpec 的 change proposal 作為 spec-of-record 餵進 review prompt，讓 reviewer 同時檢查「實作 vs. spec 偏離」
  • Finding 修復不要一律走「直接請 Claude 修」——按 severity 分流：Medium/Low 直接修、Critical/High 走 writing-plan + TDD、spec 設計錯則開 OpenSpec proposal；報告含任一 Critical 或 ≥3 個 High 時強制走 plan 路徑

實際應用 ​

適合使用的場景 ​

  • 大型功能合併前的全面審查
  • 架構重構後的系統性驗證
  • 安全敏感改動（認證、授權、資料處理）
  • 前後端 API contract 一致性驗證

不適合使用的場景 ​

  • TDD red-green-refactor 內迴圈（本質序列，fan-out 只增加成本）
  • OpenSpec spec 撰寫（需要單一連貫聲音）
  • 例行小 PR（改幾行 config 或 bugfix）

部署設定參考 ​

以下為各步驟可直接複製的 prompt 與操作指令。

環境設定 ​

bash
cd /path/to/your-project
export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

Step 2：建立 Review Harness（建議用英文觸發） ​

Build a harness for comprehensive code review of this project.
I want parallel reviewer agents, each with an independent lens:
(1) architecture & design, (2) security vulnerabilities,
(3) performance bottlenecks, (4) code style & maintainability,
(5) test coverage gaps, and (6) cross-boundary integration QA
that reads both API response shapes and frontend hook expectations
and compares them.

Use a Fan-out/Fan-in + Producer-Reviewer hybrid: the reviewers run in
parallel and must NOT contaminate each other's findings, then a lead
agent merges everything into a single severity-ranked report.

The orchestrator must support re-review: when I fix issues and ask again,
it should read the previous findings, check only what I changed, and report
which issues are resolved, still-open, or newly introduced.

Step 4：啟動 Code Review ​

針對 branch diff（半成品專案建議此方式）：

Run the code review team on the changes in this branch against main.
Skip unfinished stubs and TODO placeholders — focus on completed logic.
Pay special attention to the API/frontend boundary in src/api/ and src/hooks/.
Output: a single severity-ranked report plus per-lens detail.

針對特定模組（已完成專案）：

Run the code review team on everything under src/orders/.
Output a severity-ranked report with file:line references and a concrete
fix recommendation for each finding.

Step 5：Finding Triage 與修復啟動 ​

收到 Review 報告後，先 triage 再動手修。

Triage 檢核清單（按順序判斷）：

  • [ ] 報告是否含 任一 Critical 或 ≥3 個 High？→ 是：直接升級路徑 3
  • [ ] 高嚴重度 finding 措辭是否出現 spec 層訊號？（"API contract mismatch" / "前後端對 X 欄位理解不一致" / "module boundary violation" / "this concept doesn't exist in the spec"）→ 是：路徑 2
  • [ ] 其餘 Critical/High 視為實作層問題 → 路徑 3
  • [ ] 剩下的 Medium/Low → 路徑 1 一次清

路徑 1 安全邊界（同時滿足才直接修）：

  • severity ≤ Medium
  • 修改範圍 ≤ 1 檔案、≤ 20 行
  • 無行為語意變更
  • 沒有其他 reviewer 在相同位置標出問題

路徑 1 啟動 prompt：

Read the Harness review report at _workspace/<latest>/final-report.md.
Apply only the Medium and Low findings that touch a single file and
introduce no behavioral change (style, naming, typo, null check).
Skip anything Critical/High — those go through a planned path.

路徑 2 啟動 prompt（OpenSpec proposal）：

The Harness review surfaced spec-level issues (see _workspace/<latest>/
final-report.md, findings: <ids>). Open an OpenSpec change proposal to
realign the spec for these concerns, then we will re-implement against
the updated spec rather than patching the current code.

路徑 3 啟動 prompt（writing-plan + TDD）：

Read the Harness review report at _workspace/<latest>/final-report.md.
Pick the Critical and High findings only (skip spec-design ones —
those are handled via OpenSpec).
Use the writing-plans skill to draft an implementation plan that fixes
those findings, then execute with TDD. If findings span multiple
independent files, use subagent-driven-development to parallelise.
After execution, trigger the Harness re-review to verify
Resolved / Still Open / Newly Introduced.

修復節奏控制：每批 Critical/High 修完即跑 Re-review，不要積壓到全部修完才驗證。

Step 7：Re-review 複查 ​

I've fixed the Critical and High findings from the last review.
Re-review only what I changed: read the previous findings in _workspace/,
verify each fixed issue is actually resolved, flag any that are still open,
and report any NEW issues my changes introduced.

Step 8：演進 Harness（新增 Reviewer） ​

Add a new reviewer agent for <concern>, wire it into the orchestrator's
fan-out, and record the change in CLAUDE.md's change history.

疑難排解 ​

症狀原因處置
只有一個 agent 回應，team 沒成形當前 shell 未設旗標export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 後重跑
觸發語沒反應，沒生成檔案plugin 未啟用或非英文觸發誤路由claude plugin list 確認 active；用英文重下建立語
報告把 stub/TODO 報成缺陷範圍框太寬縮範圍到 branch diff 或指定目錄，prompt 標明排除 WIP
複查沒讀到前次結果_workspace/ 被刪 / orchestrator 缺 re-review 觸發詞保留 _workspace/；請 Claude 補 orchestrator description 關鍵詞
Token 成本過高多 agent 扇出一次一任務、縮範圍、保留給高風險變更

相關概念 ​

來源 ​