Review

---
name: review
description: 制度健檢——檢查 /harness:init 在專案裝的那套開發流程，實際使用後有沒有起作用。三軌：軌一從逐字紀錄、subagent 紀錄、知識筆記、hook 試跑抽證據，並逐項跑 05 健檢清單（含專案自己長出的稽核工具、會說謊的索引與快取、清單描述本身有沒有過時）；軌二 /doctor 看工具鏈；軌三 /insights 看使用行為，並把它的建議逐條對照現有規則。寫出「有起作用／沒起作用／沒機會驗證」的報告，要使用者親自看的項目放最前面；可逆的修正列成一批，使用者一次核可後當場修並逐項驗證，不可逆的與規則改動仍逐項提案。當使用者說 /harness:review、「看 harness 有沒有起作用」、「檢查這套流程」、「harness 健檢」、「review 這個專案的 harness」時觸發；05 定期健檢到期時也用它執行。
---

# harness:review — 裝好的流程有沒有起作用

**為什麼有這個 skill**：init 裝完只證明「hook 在、規則寫了」。有沒有起作用，要看實際用起來的紀錄：派工有沒有照範本、該讀的檔有沒有讀、該擋的有沒有擋、擋的對不對、知識有沒有長出來、使用者有沒有一直在糾正同一件事。這些都留在逐字紀錄裡，只是沒有人去看。

**四條鐵則**：
1. **數字由腳本抽，模型只判讀**。不准憑讀逐字紀錄的印象寫數字；每個數字都要有出處（逐字紀錄檔名:行號）。
2. **收集只讀；修正先列清單、一次核可、當場修完再逐項驗**。第 1 到 2.5 步（收集、清單逐項、判讀、交叉比對）不改專案裡任何東西（1.5 的 dry-run 只寫臨時目錄）。修正分兩種：**可逆的**（改之前把原檔存一份到系統暫存目錄、或本來就能重建，報告寫得出怎麼還原）列成一批，使用者一次核可後當場修，修完每一項都要有驗證輸出；**不可逆的、或改變規則本身的**（刪使用者資料、commit／push、改權限設定、對外動作、改判斷規則或熔斷清單的內容）仍逐項提案，照 05 §1 分級流程走。使用者沒核可的一項都不動。
3. **沒機會驗證的照實寫**。例如專案不是 git repo，commit 前的審查就沒被觸發過——寫「沒機會驗證」，不是「通過」。
4. **指揮官不下場**。清單逐項檢查交給 subagent 跑（照 02 派工），主對話只判讀與彙整——健檢清單二三十項全由主對話自己跑，context 會被檢查輸出塞滿，判讀品質跟著掉。

對使用者講話照 init 的「對使用者講話的寫法」（`../init/SKILL.md` 同名一節）：不用內部代號、題號照實際順序連號。

## 流程總覽

```
0 找範圍、請使用者輸入 /doctor 與 /insights
→ 1 收集（腳本）＋ 1.5 健檢清單逐項（subagent）
→ 2 判讀（回原文核對）＋ 2.5 三軌交叉比對
→ 3 問使用者兩題 → 4 報告（使用者親自看的放最前）＋修正清單
→ 5 一次核可後當場修、逐項驗證 → 6 留紀錄
```

**三軌各看一層，單軌都有盲區**：軌一（本 skill 的第 1、1.5、2 步）看制度有沒有腐化、有沒有被照做；軌二 `/doctor` 看工具鏈（安裝、版本、沒在用的連接器與 skill、慢 hook、常駐 context）；軌三 `/insights` 看跨 session 的使用行為與卡關點。軌一抓得到「工具給錯答案卻不報錯」，軌三抓得到「規則寫了卻沒人照做」，互相補位。

## 0. 找範圍

- 落點＝有 `.claude/harness/README.md` 的專案根目錄（預設目前工作目錄）；找不到就告訴使用者這個專案沒裝 harness，建議先跑 `/harness:init`，停止。
- 安裝日期：CLAUDE.md 變更紀錄裡「建立」那一筆的日期（0.10.0 起紀錄在 `CLAUDE.changelog.md`；舊實例在 CLAUDE.md 本體的 Changelog 節。收集腳本兩處都找，結果在輸出的 `installDate`）。上次 review 或健檢的日期：`.claude/harness/CHANGELOG.md` 的 `## 05-knowledge-protocol.md` 節裡帶【健檢執行】標記、**日期最大**的一筆（不是檔案裡最後一筆——新的寫在上面或下面都有可能；舊實例在 `05-knowledge-protocol.md` 本體的 Changelog；收集腳本兩處都讀，結果在 `E.lastHealthCheck`，沒有帶標記的紀錄時是 null）。預設看「上次 review 之後」，沒有就看「安裝之後」；使用者指定範圍就照他的。
- **開跑的第一則訊息就請使用者輸入 `/doctor` 和 `/insights`**（軌二、軌三是 Claude Code 內建指令，模型叫不動）。講清楚：「這兩個要你在提示列打，打完輸出會留在對話裡，我接著做軌一，不用等它們」。使用者說不跑，報告寫明「軌二／軌三沒跑：使用者選擇不跑」，不准靜默略過；無人值守時寫「沒跑：無人值守，內建指令無法代跑」。

## 1. 收集（腳本，不准手抽）

```
node <本 plugin>/skills/review/scripts/review-collect.js <落點> --since <日期> --out <系統暫存目錄>/harness-review-<今天>.json
```

- **收集結果不放進專案**：它含出處、檔名、主機名這類線索，放在專案裡可能跟著 commit；專案裡只留第 4 步的報告。
- `notes` 要先看：略過了哪些 session、哪些行解析失敗、範圍內有沒有 session——範圍內沒有 session 時數字全是 0，代表沒資料，不代表流程沒起作用。
- 腳本預設只讀：它用文字解析讀實例的派工檢查表，不執行專案裡的任何程式；輸出不抄指令、使用者發言、擋下訊息的原文（原文可能帶金鑰，遮值規則追不完所有寫法），只記出處（`檔名:行號`）與抽出來的線索：指令名、命中的關鍵詞、擋下的標籤、已知的名稱（角色、模型、hook 檔）；主機只列專案文件裡寫過的，其他只計數——值不在已知清單裡就不輸出，換成固定字樣或計數；要看內容就照出處回原文。輸出前另有一道遮值總清掃當保險。只收 cwd 是這個專案的列（session 中途切到別的專案，那幾列不算）。它會自己略過跑 `/harness:init` 的 session 與安裝時的冷啟探針 session（探針會故意觸發擋下，算進來會失真）；略過了哪些列在 `notes`。
- **要實際執行專案裡的程式，先問使用者一次，他同意才做**——涵蓋這裡的 `--probe`，也涵蓋第 1.5 步清單裡的 hook dry-run、專案稽核工具、清單描述自驗的實跑；他不同意時這些項目一律標「沒機會驗證：使用者沒同意執行專案程式」，不准由 subagent 自己決定跑。`--probe` 的細節：它會在實例的 `.claude/hooks/` 跑 `probe-hooks.js`（語法樹與正則兩條路徑），也就是執行專案裡的程式——那些 hook 本來每次執行指令都在跑，但收集階段只讀，不可自己決定加。問法：「要不要順便實際試跑一次自動檢查？會執行專案 .claude/hooks 裡的程式（建議：要，確認它們還擋得住）」。無人值守、或他不同意時不加，報告寫明「自動檢查沒有實際試跑」。
- 逐字紀錄目錄預設是 `~/.claude/projects/<落點換算的名稱>`（英數字以外的字元換成 `-`）；找不到時腳本會在 `notes` 說明，這時問使用者目錄在哪，用 `--transcripts` 指定。

輸出分九個面向，對應下一步的判讀：

| 代號 | 面向 | 腳本給什麼 |
|---|---|---|
| A | 自動檢查還活著 | session 開頭有沒有 `[harness]` 提醒、settings 每條接線指到的檔在不在、probe 兩條路徑的結果（加 `--probe` 才有；parserMode 標出規則引擎實際走語法樹還是正則——解析器沒裝好時兩次都走正則、數字照樣全綠） |
| B | 流程有照走 | 每個 session 的派工順序、第一次派工前有沒有對齊（問過使用者，或寫明無分岔；被擋下的提問不算）、commit 指令（0 筆＝commit 前審查沒被觸發過） |
| C | 派工品質 | 每次真的派出去的派工：model、有沒有【開工前必讀】、寫到哪些必讀檔；被擋下沒派出去的嘗試另列；每次被擋的出處與標籤 |
| D | 必讀真的有讀 | 每個 subagent 實際讀成功了哪些必讀檔（Read 失敗的不算，另記 failedReads；CLAUDE.md 會被自動載入，標「自動載入」）、回報有沒有已讀清單 |
| E | 知識有長出來 | 主對話有改檔的回合（turnsWithEdits）、沉澱提醒次數與回答、三份知識筆記安裝後的異動、剩多少示範條目 |
| F | 危險動作 | 危險指令檢查擋下的次數、所有看起來有風險的指令（連線、部署、資料庫；只記出處與指令名。主機只列專案文件——CLAUDE.md、CONTEXT.md、FLOWS.md、PROJECT.md、.claude/harness——寫過的，沒寫過的只計 unknownHosts）、指令裡直接寫了金鑰／密碼／權杖的出處（只記出處與種類，不抄值） |
| G | 使用者介入 | 使用者發言數、打斷次數、帶糾正語氣的發言（出處與命中的詞） |
| H | 專案概要 | CLAUDE.md 有沒有專案概要、進度日期距今幾天、是否還標「未經使用者確認」 |
| I | 版本差距 | 目前 plugin 版本有、這個實例還沒有的功能；hook 引擎與目前範本不同的檔 |

上面九個面向替 `05-knowledge-protocol.md` §5 清單的幾項附了證據（H 的專案概要日期、A 的 hook 接線與試跑、C 的派工欄位、E 的知識筆記異動）；清單其餘項目在 1.5 跑。

## 1.5 健檢清單逐項（派 subagent，不在主對話跑）

`05-knowledge-protocol.md` §5 的清單（含 §5.1 本專案稽核工具表）**全部**要跑，派一支 subagent（`sonnet`；照 02 派工三件套，prompt 帶「搜尋限定專案目錄、禁止全碟掃描」與「不准修改任何檔案、不准 commit」）。交給它：清單全文、落點路徑、收集結果裡跟清單重疊的那幾項（不必重查）。要它回：

- 每一項一列：`項目｜OK／異常／沒機會驗證｜證據（實際指令與輸出、或檔名:行號）`，不准只寫 OK。
- **清單描述自驗**：清單裡寫了預期結果的項目（「應 exit 0」「應擋下」「應放行」「應 >N」），照描述實際跑一次，把實際結果跟描述並列。對不上的另標「清單與實際不符」，**不准直接判成哪一邊錯**——可能是清單過時（實際發生過：hook 加了一道要填的欄位，清單還寫「四格齊全應放行」，照抄跑出被擋，一度被誤判成 hook 壞了），也可能是 hook 真的壞了；兩種處理相反，判錯一種就會把故障改寫成「預期行為」蓋掉。
- **會說謊的工具**：索引、快取、產生物、提醒 hook 這類「錯了也不會報錯」的東西，要比對它給的答案跟實況（例：程式碼索引的時間 vs repo HEAD 的時間；健檢到期提醒算出的基準日 vs changelog 裡日期最大的那筆健檢）。
- 會執行專案裡程式的檢查（hook dry-run、稽核工具、清單描述自驗的實跑），只在使用者已經在第 1 步同意執行專案程式時才跑；沒同意就標「沒機會驗證：使用者沒同意執行專案程式」。派工 prompt 要寫明使用者同意了沒有。
- 有執行副作用的檢查（會重新產生檔案、會寫入 temp 的 dry-run）先講會動到什麼；會改到專案追蹤中的檔案的，不跑，標「沒機會驗證：會改動追蹤中的檔」。
- 標了【使用者親自看】的項目：只彙整資料，不下結論。

主對話收到後，「異常」與「清單與實際不符」逐項回原文或重跑一次確認。「清單與實際不符」要查證是哪一邊：找得到「行為是刻意改的」證據（該 hook 或工具的 changelog、commit 訊息、檔頭說明寫了新行為，且日期晚於清單那一項的寫法）才判「清單描述過時」；找不到就判「異常：實際行為不符預期」，當故障處理、不准改描述去遷就。兩種都附查證的出處。其餘確認（subagent 的結論是線索，同鐵則 1；重跑要執行專案程式的，同樣只在使用者第 1 步同意時才跑，沒同意就只回原文核對）。**用關鍵字比對得出的「找不到」「漏收」「沒有引用」，換一種寫法再搜一次才算數**（版號加點與不加點、全名與簡稱、中英文名）——實際發生過：搜「2453」判定某條知識漏收，原文寫的是「2.45.3」，其實早就收了。

## 2. 判讀（每個結論都回原文核對）

腳本的數字是線索，不是結論。逐項這樣判：

- **每一次被擋**（C 的 denials）：開逐字紀錄那一行前後看——擋得對不對（真的缺了東西，還是規則太嚴）、擋下後 Claude 有沒有補對再派、有沒有改派別的 agent 繞過。擋錯的要列進提案。
- **派工順序**（B）：行為類需求要看到 實作 → 測試 → 審查；只有審查沒有測試的，回原文找有沒有寫「分流例外」和理由。第一次派工前沒有對齊的，回原文確認是真的沒對齊，還是腳本沒認出來（例如用一般文字問使用者）。
- **必讀**（D）：少讀的檔逐一回 subagent 紀錄確認；再看派工 prompt 有沒有列那個檔（C 的 mentions）——沒列是派工的問題，列了沒讀是 subagent 的問題，兩種提案不同。
- **知識**（E）：有改檔的回合數 vs 沉澱回答數；回答「無」的回合抽看幾個，確認真的沒有新詞、新坑。示範條目還在只是線索、不是結論：專案可能已經加了真實條目、只是沒刪示範——先看安裝後的變更紀錄異動（changelogSince；腳本讀三個位置——本體的 `## Changelog` 節（舊實例）、同目錄的 `<檔名>.changelog.md`、同目錄 `CHANGELOG.md` 裡 `## <檔名>` 那一節——實際讀到哪幾個列在 changelogSources）與正文有沒有真實條目，兩者都沒有才寫「那份筆記沒被用過」。changelogSources 是空的、正文卻有真實條目＝紀錄寫在腳本不認得的位置，回原檔看，不准判成「沒有異動」。
- **危險指令**（F）：逐條看 riskyLookingCommands——unknownHosts 大於 0 的每一條都要照出處回原文，看連到哪裡（沒有點的主機名與 ssh 設定檔別名一律只計數，不會列在 hosts；含底線但有點的主機名跟一般主機一樣，文件寫過才列出）；再對照 CLAUDE.md 專案概要的環境表與 `03-judgment-matrix.md` 的熔斷清單：連到沒確認的主機卻沒被擋的，是最嚴重的一類發現。secretsInCommands 每一處都回原文確認是真的金鑰（不是路徑裡的編號）；確認後報告只寫次數與出處、不寫值，提案通常是「改用環境變數或設定檔載入」加一條自動檢查。
- **使用者介入**（G）：糾正與打斷逐條看原文——同一件事被糾正兩次以上，代表 harness 該防沒防住，一定要進提案。
- **版本差距**（I）：列出來，提案走 `/harness:init` 參考模式升級，不建議手補。
- **當初略過的安裝項**：`05-knowledge-protocol.md` 健檢清單有「Codex 還沒裝」那一列（init 時使用者選了不裝）時，跑一次 `codex --version`：還是沒裝 → 報告的「沒起作用」寫「commit 前只有一位審查員（同一家模型），因為 Codex 還沒裝」，提案附安裝三步（`npm install -g @openai/codex`、`codex login`、`codex --version`）；已經裝了 → 提案刪掉那一列，並提醒 commit 審查現在會多一位 Codex 審查員。

分三類寫結論：**有起作用**（附證據）／**沒起作用**（附證據與失敗情境）／**沒機會驗證**（附為什麼沒被觸發）。

## 2.5 三軌交叉比對（使用者貼回 /doctor、/insights 輸出之後）

- **軌二 `/doctor`**：它建議關掉或移除的連接器、skill、plugin，對照 05 清單「系統提示的工具來源」那一項與 CLAUDE.md 路由表——路由表或制度檔有點名的不關（點名了卻零使用，反而是「規則寫了沒人照做」的線索，記到軌一）。它的修改屬於可逆類（關掉可再開），列進第 5 步的修正清單。
- **軌三 `/insights`**：它給的每一條建議（常見是「CLAUDE.md 加一條…」）逐條對照現有規則（全域與專案 CLAUDE.md、02～05、hook），分三類：
  1. **已經有規則，只是沒被照做** → 不加文字（再加一條一樣會被忽略），提案改成自動檢查；能從指令樣子認出來的往 `guard-risky-command`／`guard-test-preconditions` 加規則。
  2. **真的沒有規則** → 提案補規則，寫明補在哪一份檔。
  3. **不屬於這個專案**（例子出自別的專案、或該由某個 plugin 管）→ 指出應該補在哪裡，不寫進這個專案。
  每一條都要附「對照了哪幾份檔、哪一行」。
- **三軌都看到的同一件事**，在報告結論裡講，那通常是最該先處理的。

## 3. 問使用者兩題（一次一題，附建議）

逐字紀錄看不到使用者的感受。報告前問：
1. 「這段時間用起來，哪裡最卡或最煩？」（建議從判讀結果挑一個最可能的當選項）
2. 「有沒有哪次 Claude 做錯了，卻沒有被擋下或被發現？」（建議：列出判讀時找到的可疑時點讓他確認）

無人值守時跳過，報告寫明「沒問使用者」。

## 4. 報告＋提案

寫成 `<落點>/.claude/harness/reviews/<今天>.md`，照這個結構：

1. **請你親自看**（清單標了【使用者親自看】的項目；沒有就省略這段）：只放資料與它在哪裡，不替使用者下結論
2. **結論**（三到五句）：整體有沒有起作用、三軌都看到的問題、最大的一個問題、建議先做哪一件
3. **三軌結果**：每軌一行——看什麼、結果；沒跑的軌寫原因
4. **有起作用的**：逐項附證據出處
5. **沒起作用的**：逐項附證據出處與失敗情境（含「清單描述過時」〔附刻意改動的證據〕、「實際行為不符預期」、「工具給錯答案」）
6. **沒機會驗證的**：逐項附原因
7. **可以當場修的**（可逆類）：每項一列——要改什麼、對應哪個發現、改之前原檔存在哪、怎麼還原、修完怎麼驗
8. **要逐項決定的提案**（不可逆或改規則的）：每項一列——要改什麼、為什麼、屬於哪一類（改規則文件／補自動檢查／放寬擋錯的規則／升級範本／移除沒用的東西）、風險區（紅區要先問、黃區當次講明、綠區可直接改）、預估影響；軌三的「已經有規則只是沒被照做」「不屬於這個專案」也列在這裡
9. **版本差距**：目前 plugin 有、這個實例沒有的功能，與升級方式
10. **附錄**：這次看了哪些 session、略過了哪些、用的範圍（--since）；收集結果在系統暫存目錄，不隨報告保存

交付前照 init 的易讀性自檢跑一次（沒裝 deliver-report 就跳過並提示安裝）：

```
node <本 plugin>/skills/init/scripts/readability-check.js <落點> <落點>/.claude/harness/reviews/<今天>.md
```

把報告的第 1、2、7、8 段貼給使用者，附檔案路徑，問兩件事：第 7 段要不要整批修（可以挑掉幾項），第 8 段要套用哪幾項。

## 5. 修正

**第 7 段（可逆類）——使用者一次核可後當場修**：
- 典型項目：重建過期的索引或快取、`retire_when` 條件已成立的 memory 退場、更新已查證為過時的清單描述（要附「行為是刻意改的」證據；只是跟實跑不符、查不到刻意改動證據的，當故障處理，不改描述）、修明顯的 hook bug（例：提醒 hook 取錯日期）、關掉 /doctor 判定零使用且沒被制度點名的連接器或 skill、刪沒被任何程式引用的死碼譯文。
- 每一項改之前把原檔存一份到系統暫存目錄（能重建的不必存，例如索引）；改 hook 一律補 cases（要能證明舊版會 FAIL、新版 PASS）並跑 probe-hooks 兩條路徑。
- 修完每一項附驗證輸出：重跑當初發現問題的那個檢查，從異常變成 OK 才算修好。只改了檔、沒重跑檢查的，報告寫「已落檔，未驗證」。
- 修正本身或驗證要執行專案程式的（用專案的腳本重建索引、跑稽核工具重寫基線、跑 probe-hooks、重跑 hook）：使用者在第 1 步沒同意執行專案程式時，請他核可修正清單的同一則訊息裡，要講明「這幾項修完要執行專案程式才能驗證」，讓他一併決定；他仍不同意：只有驗證要執行程式的，照樣可以修，但報告寫「已落檔，未驗證：使用者沒同意執行專案程式」；修正本身就要執行程式的（例如重建索引），不做，報告寫「沒修：要執行專案程式，使用者沒同意」。
- 使用者挑掉的項目不做。

**第 8 段（不可逆或改規則）——逐項照 05 §1 分級**：
- 紅區（CLAUDE.md、02～05 的規則內容、熔斷清單、agents、settings 的權限）：先說明原因、位置、建議內容，確認後才改；改 hook 同上要補 cases。
- 升級範本：建議使用者跑 `/harness:init`（參考模式會把現有設定當參考、知識條目原樣搬）。
- 使用者沒選的不做。

## 6. 留紀錄

第 4 步問核可時一併問「要不要把這次健檢記進健檢紀錄（健檢提醒會從今天重新算 30 天）」，預設建議要。同意時在 `.claude/harness/CHANGELOG.md` 的 `## 05-knowledge-protocol.md` 節補一行（新的寫在上面或下面照該節原本的慣例；舊實例還沒有這個檔、或檔裡沒有這一節時，寫在 `05-knowledge-protocol.md` 本體的 Changelog——提醒在那種情況下讀的是本體，並在報告的提案裡建議升級時把 changelog 搬出去）：`- <今天> 【健檢執行】/harness:review：<一句話結論>；報告 .claude/harness/reviews/<今天>.md`。**【健檢執行】這個標記要緊接在日期後面**——`health-check-reminder.js` 只認這個標記，不從文字猜（「健檢執行：結論…」跟「健檢執行：改為每月一次」字面分不出來）；改制度的紀錄不准用這個標記。補完後確認提醒認得這行：使用者在第 1 步**同意執行專案程式**時，跑一次 `node .claude/hooks/health-check-reminder.js`，要沒有輸出（有輸出代表提醒沒認得這行：把它列進修正清單，經使用者核可後照第 5 步修 hook）；**沒同意時不跑**，只確認這行是 `- <今天> 【健檢執行】` 開頭，回覆寫明「提醒有沒有認得這行沒有實跑確認」。不同意補紀錄就不寫、在回覆裡講明。