Init

---
name: init
description: 把一套開發流程制度（模型調度／停損熔斷／派工模板／知識協議＋agent pipeline＋機械閘 hook＋知識容器）安裝到一個軟體開發專案。當使用者說 /harness:init、「幫這個專案裝 harness」、「實例化 harness」、「把制度層搬到 X 專案」、「幫這個專案建開發流程」時觸發。流程＝前置檢查→盤點（含專案用途、業務流程、進度）→攤開核對→一次一題訪談（先問環境、進度與專案詞，再問流程設定）→五層生成→靜態驗收＋冷啟探針→流程圖與收尾回報；不是複製既有專案的檔，是用通用骨架填入目標專案的已查證事實。
---

# harness:init — 開發流程制度安裝器

把 `references/` 的通用骨架與 `../../hooks/templates/` 的 hook 範本，實例化成目標專案的五層制度：文件層、可執行層（hook）、agent 層、知識容器層、settings 層。**引擎（本 plugin）與實例（專案檔）分離**：plugin 更新不會動到任何專案的實例；實例落地後歸該專案自治（紅區流程見實例的 05）。

## 核心原則（動工前先讀 `references/adaptation-guide.md`，本節只是摘要）

1. **開發流程骨幹全帶，事故型條款不帶**：純行為紀律照搬、可參數化的判準挖空填入、agent pipeline 依盤點裁切；綁死特定工作法的條款與單一事故的細則不帶（那些從目標專案自己的 memory 長出來，或由 `/harness:review` 健檢時從該實例的紀錄列進提案，同一件事反覆出錯就提升格）。
2. **規則要有機械閘**：skill 與制度檔寫「必須」是自律，AI 會繞；只有 hook 是他律。所以本 init 產出可執行的 hook，並用冷啟探針實測它真的會擋。
3. **實例化不是複製**：目標專案的事實（build 指令、agent 名單、邊界、危險動作）必須**實地查證後填入**，禁止從別的專案的實例照抄、禁止用猜的。
4. **既有設定分兩種對待**：
   - **既有的 Claude Code 設定（`.claude/`、`CLAUDE.md`，含之前裝過的 harness）是參考來源，不是權威**。使用者會在已經有設定的專案跑 init，代表他覺得原本的流程有問題，想換這套試試。所以不停下、不讓位：先整份備份，再把它當成盤點證據（裡面的指令、邊界、保護動作、agent 分工都是這個專案的事實），逐項決定沿用、併入或取代，並問出原本哪裡不好用（見 Phase 0-2、Phase 1 第 12 項、第 0 題）。
   - **其他工具共用的治理層（AGENTS.md／.agents/／.cursor/ 這類多工具規範）讓位**：harness 只補 Claude Code 特有行為層，開發流程正本讓給它（adaptation-guide §2）。這些檔不只 Claude 在用，改掉會影響別的工具與別的人。
5. **誠實**：init 給的是骨架＋長出資產的路徑，不是一套成熟的 harness。收尾回報必須講清楚「你已經有的」與「你還沒有的」。
6. **先懂這個專案在做什麼，再裝流程**：技術事實（指令、目錄、相依）讀檔可以查證；業務事實（系統給誰用、做什麼、哪個環境是正式、專案詞是什麼意思、現在做到哪）讀檔只能推，**一定要問使用者**。只查技術面就裝，裝出來的規則沒有業務依據，知識筆記是空的，之後每個 agent 都得從可能過時的文件自己拼湊專案理解。實際紀錄：某專案盤點把設定檔裡的預設網址判成「正式 ERP」，建議五項動作全部要先問使用者，使用者一句「這些都是測試環境」全部推翻；同一次安裝的專案詞彙表裝完只有示範條目，因為整個過程沒問過任何一個專案詞；必讀文件還推薦了一份自己也判定已過時的 README。所以 Phase 1 第 13 項推專案輪廓、Phase 2 先攤專案概要草稿、Phase 3 先問專案理解三題（U1～U3），答案寫進 CLAUDE.md「專案概要」與 CONTEXT.md。

## 對使用者講話的寫法（Phase 0、Phase 2、每一題訪談、Q5 清單、收尾回報都適用）

聽的人多半第一次用 harness，沒讀過這份 SKILL。本檔為了精確，用了很多內部用語（熔斷、B 類、形狀目錄、落成規則、代決…），**這些詞只供你自己理解，不得出現在對使用者說的話裡**。判準：一個沒看過本 plugin 任何文件的工程師，讀了這句話知不知道「會發生什麼事、要他決定什麼」？不知道就改寫。

| 內部用語 | 對使用者改說 |
|---|---|
| 熔斷、熔斷清單 | 執行前一定要先問你的動作 |
| hook、機械閘、他律 | 自動檢查（第一次提到時補一句：Claude 每次執行指令或派工前自動跑，命中就擋下） |
| `guard-risky-command` 這類檔名 | 講它擋什麼；檔名只放在表格最後一欄或括號裡，不當主詞 |
| 落成一條規則 | 能從指令樣子認出來的，會設一條自動檢查：Claude 要執行這類指令時先被擋下，問過你才做；認不出來的只寫進規則文件，靠 Claude 做之前自己停下來問你 |
| A／B／C／D／E 類、形狀目錄 | 不提分類；改說原因：一定會裝／因為你的專案有 X 才裝／因為你的工作方式才裝／要另裝某個 plugin／等你有了 X 才用得到 |
| pipeline、裁切 | 開發流程的角色分工；拿掉你用不到的角色 |
| 讓位、既有治理層 | 沿用你們已經有的規範（寫出檔名），不另外蓋一套 |
| 代決 | 我先替你決定的（你可以推翻） |
| 冷啟探針 | 開一個新的 session 實際試一次，看自動檢查有沒有真的擋下 |
| 同源、驗證器與施作器同源 | 同一家模型審自己寫的東西，看不出自己的盲點 |
| 紅區／黃區／綠區 | 改之前要先問過你（團隊則是走 PR 審查）／可以改，但當次要講明改了什麼、為什麼／可以直接改，事後提一句 |
| 知識容器 | 知識筆記檔：`CONTEXT.md` 詞彙表、`FLOWS.md` 跨模組流程、`PROJECT.md` 測試知識 |
| 沉澱閘 | 每次 commit 前會問你四個問題，把這次學到的東西記下來 |
| codify | 寫成可以重跑的自動測試 |
| dry-run | 試跑（不真的執行） |
| `03` B23、`05` §6 這類條號 | 不寫條號；要指路就寫完整檔名加節名（「`05-knowledge-protocol.md` 的『升格協議』一節」） |
| Q2、U1、Phase 2 | 照實際問的順序連號（第一題、第二題…），不用內部代號；提到前面的題目時寫「剛才問環境的那一題」、剛才的盤點結果 |

另外三條：
- **agent 名稱第一次出現附中文職稱**：`backend-architect`（後端架構設計）、`backend-engineer`（後端實作）、`frontend-engineer`（前端實作）、`qa-engineer`（測試）、`code-reviewer`（程式碼審查）。
- **每題都講清楚「選了之後會發生什麼」**，不要只講選項名稱。
- **送出前自掃一次**：拿上表左欄逐詞搜自己的草稿，命中就改寫再送。上表的機械可讀版在 `plain-language-terms.json`（另收了流程圖實際被指出看不懂的詞：派工、欄位、對齊回合、主對話、快照、注回…），流程圖與收尾回報由 Phase 6 的易讀性自檢腳本掃；兩份要同步。

## 流程總覽

```
Phase 0 前置檢查 ─→ Phase 1 盤點（唯讀） ─→ Phase 2 攤開核對 ─→ Phase 3 訪談（一次一題：Q0 → U1～U3 → Q10 → Q1、Q2、Q8 → Q3～Q7 → Q11）
                                                                          │
收尾回報 ←─ Phase 6 流程圖 ←─ Phase 5 驗收（靜態十二項＋冷啟探針五項） ←─ Phase 4 生成（五層）
```

**每個專案都要先弄懂它在做什麼**：Phase 1 第 13 項從文件與程式碼推專案輪廓（用途、串接的外部系統、業務流程、進度、候選專案詞、文件哪裡過時）→ Phase 2 把它寫成專案概要草稿放在核對表最前面 → Phase 3 先問 U1 環境、U2 進度、U3 專案詞，再問流程設定 → Phase 4 寫進 CLAUDE.md「專案概要」、CONTEXT.md 詞條、PROJECT.md 環境。

**已經有 Claude Code 設定的專案**（Phase 0-2 判定）多走五步：Phase 0 先整份備份 → Phase 1 第 12 項盤點原有設定（含用語意挑出原有規矩裡的經驗） → Phase 2 攤出「原有設定怎麼處理」對照表與經驗清單 → Phase 3 第 0 題問原本哪裡不好用 → Q8 問不會被帶到的經驗要升格哪幾條 → Phase 5 另派 subagent 審查經驗有沒有帶走。規則文件與自動檢查一律照這一版 harness 重新產生；收尾回報多一段交代原有設定的去向、經驗的去向、痛點有沒有解。

任一 Phase 未完成不得進下一個。Phase 5 任一項失敗、Phase 6 完整性檢查沒過，都＝init 未完成。

---

## Phase 0 — 前置檢查（版本比對＋五項；版本落後就停下；0-5、0-3 沒裝時問使用者要不要裝，等他回答再往下；其餘記下繼續）

**最先做：比對正在用的 harness 是不是遠端 repo 上的最新版**（什麼都還沒動，所以放在拍快照之前）：

```
node <本 plugin>/skills/init/scripts/check-version.js
```

- **exit 0**（已是最新）：把它印的「正在用／遠端最新」兩行放進 Phase 2 核對表與收尾回報，繼續。判定寫「正在用的比遠端新」時（維護者在原始碼 repo 開發中），照樣繼續，核對表照實寫兩個版本號。
- **exit 2**（落後）：**停下，不開始 init**。把腳本輸出原文貼給使用者，請他在提示列依序輸入下面三行（一行一行貼；`/plugin` 是互動指令，Claude 不能代執行，也沒有 `/plugin update` 這個子指令）：`/plugin marketplace update <marketplace 名稱>`、`/plugin uninstall harness@<marketplace 名稱>`、`/plugin install harness@<marketplace 名稱>`（marketplace 名稱照腳本印的填），然後重開 session 再跑 `/harness:init`。理由照實講：舊版少的步驟裝完才發現，就得整輪重做（實際發生過：裝到一半才冒出新版，舊版少了最後畫流程圖那一步，使用者裝完才發現，整輪重裝）。使用者明確說「就用這版裝」才繼續，收尾回報寫「用的是 <版本>，遠端已有 <版本>，你選擇不更新」。
- **exit 3**（查不到：沒網路、沒 git、marketplace 不是 git clone）：不擋，繼續；收尾回報寫「沒有比對到遠端版本」並附腳本印的原因。

先確認目標 workspace 路徑（預設＝當前工作目錄；使用者指定別的路徑就用那個）。

**接著、在動任何檔案之前：拍快照**（Phase 6 靠它找出 init 新增或改過的每個檔案，事後補拍比不出差異）：

```
node <本 plugin>/skills/init/scripts/check-flow-diagram.js snapshot <目標>
```

之後 Phase 1 實跑測試、Phase 4 生成、Phase 5 探針留下的所有變動都會被 Phase 6 抓出來——不該留的殘檔要在收尾前刪掉，否則會被要求畫上流程圖。

以下指令一律對目標路徑跑：

| # | 檢查 | 指令 | 不過時 |
|---|------|------|--------|
| 0-1 | 目標是不是 git repo | `git -C <目標> rev-parse --is-inside-work-tree`；workspace 根不是 repo 時再列子資料夾：`for d in <目標>/*/; do git -C "$d" rev-parse --show-toplevel 2>/dev/null; done` | 分三種：①根目錄就是 repo＝**單一 repo** ②根目錄不是 repo、但子資料夾列得出 repo＝**多 repo 工作區**：跟單一 repo 一樣算 git 專案（改動最後一樣要推上 git），git-commit 相關的閘照裝，P4 探針對每個子 repo 各跑一次；沉澱閘綁 git-commit，不改綁 Stop hook ③根目錄與子資料夾都不是 repo＝**非 git 專案**：沉澱閘改綁 Stop hook、git-commit 相關的閘與探針整組不裝不測。實際回饋：多 repo 工作區被當成非 git 專案，使用者要自己指出「最終的目的都還是要推到 git 上」 |
| 0-2 | 有沒有既有的 Claude Code 設定 | 對 workspace 根與每個子 repo 各查一次：`ls <目標>/CLAUDE.md <目標>/.claude/ 2>/dev/null`；`.claude/` 底下列 `agents/`、`hooks/`、`commands/`、`skills/`、`harness/`，讀 `settings.json`／`settings.local.json` 看有沒有 `hooks`、`permissions`；`CLAUDE.md` 是否含「Harness 路由表」（＝之前裝過 harness） | **不停下**。判定規則：只有 `settings*.json` 且裡面只有 `enabledPlugins`＝**沒有既有設定**，照一般流程走（settings 照 Phase 4 合併）。其餘任何一項存在＝**有既有設定，進入參考模式**：①動 Phase 1 之前先整份備份——`CLAUDE.md`、`.claude/`（排除 `node_modules/`）、`CONTEXT.md`、`FLOWS.md`、`tests/Project_Detail/PROJECT.md` 原樣複製到 `<目標>/.harness-backup/<YYYYMMDD-HHMM>/`（保持相對路徑）；是 git repo 就把 `.harness-backup/` 加進 `.gitignore`；備份完用 `diff -r` 或逐檔 hash 比對確認一致，比對不過就停 ②Phase 1 第 12 項盤點原有設定 ③Phase 3 第 0 題問原本哪裡不好用。之前裝過 harness 也一樣走參考模式（重裝），不另外停 |
| 0-3 | Codex CLI 裝了沒（0-1 是非 git 專案、或 0-5 使用者選不裝 git-commit 時不適用，標「不適用」；**跟 0-5 一起問、排在 0-5 後面**——沒有 git-commit 就用不到 Codex） | `codex --version` | **沒裝 → 問使用者要不要裝，不是停下**：照下方「Codex 裝不裝」範本給對照與安裝三步，等他回答。選裝 → 他裝好後 **Claude 自己重跑 `codex --version`** 確認，把輸出貼出來再繼續。選不裝 → 照一位審查員繼續：①Phase 2 核對表與收尾回報「你還沒有的」寫「commit 前只有一位審查員（Claude），因為你選擇先不裝 Codex」②05 健檢清單加一列「Codex 還沒裝：commit 前只有同一家模型審查」，`/harness:review` 會追蹤 ③P4 照跑。為什麼要問：git-commit 的三軌審查裡，Codex 是與 code-reviewer 不同源的那一軌，少了它審查只剩同一家模型看自己的東西（03 B23）；但裝不裝是使用者的決定，不自己略過也不擋著不讓他往下。實際回饋：原本寫成「沒裝就停下」，使用者要自己說「Codex 這步先跳過」才能繼續，並指出「git-commit 會問要不要裝，Codex 為什麼不問」 |
| 0-4 | Playwright MCP 在不在 `permissions.allow` | 讀 `<目標>/.claude/settings.json`、`<目標>/.claude/settings.local.json`、`~/.claude/settings.json` 的 `permissions.allow`，找 `mcp__playwright` 開頭的項 | 不在 → 不擋，記下來：Phase 1 判定為「瀏覽器可驅動前端」時，Phase 4 settings 層要補（經 Phase 2 核對）；非瀏覽器或無前端時此項不適用 |
| 0-5 | git-commit plugin 裝了沒（0-1 是非 git 專案時不適用） | 照設定的優先序讀 `enabledPlugins` 裡 `git-commit@` 開頭的項：`<目標>/.claude/settings.local.json` ＞ `<目標>/.claude/settings.json` ＞ `~/.claude/settings.json`，**以最高一層有寫這一項的值為準**（高層寫 `false` 就是停用，就算低層寫 `true`）；三層都沒寫＝沒裝。判定為 `true` 後，再確認 `~/.claude/plugins/cache/*/git-commit/` 底下有版本資料夾；**並讀出這個專案實際用的版本**：`~/.claude/plugins/installed_plugins.json` 裡 `git-commit@…` 的紀錄，取 `projectPath` 是目標的那筆（沒有就取 `scope` 為 `user` 的那筆）的 `version` | **沒裝 → 在這一步就講清楚，不要等到訪談中途才冒出來**：照下方「git-commit 裝不裝」範本給對照表與一行安裝指令，等使用者決定（與 0-3 同一則訊息問，見範本上方「0-5 與 0-3 怎麼問」）。使用者裝好後，**Claude 自己重跑本項的兩個檢查**確認生效，把結果貼出來，不要先叫使用者重開 session（要不要重開以實際檢查為準；hook 有沒有真的生效由 Phase 5 的 P4 冷啟探針驗）。使用者選不裝 → git-commit 相關的閘與 P4 不裝不測、沉澱閘改綁 Stop hook，0-3 標「不適用」，收尾回報寫明。**裝了但版本低於 0.11.0**（QA 閘要 0.11.0 以上：`flow.sh review-record` 才會讀 `.claude/qa-gate.conf`、自己檢查 staged 有行為類檔時有沒有帶 `--qa`）→ 同一則訊息照「git-commit 裝不裝」的方式問要不要更新，講清楚影響：不更新的話「改了程式有沒有測過」只剩呼叫 git-commit skill 時的提早提醒（`guard-qa-before-commit`），直接用 Bash 跑 flow.sh 就不會被查；更新要在提示列依序輸入 `/plugin marketplace update <marketplace 名稱>`、`/plugin uninstall git-commit@<marketplace 名稱>`、`/plugin install git-commit@<marketplace 名稱>`（Claude 不能代執行）。選更新 → 他做完後 Claude 自己重讀版本確認；選不更新 → 照裝（`qa-gate.conf` 照樣產生，舊版 flow.sh 不讀它，之後更新就自動生效），Phase 2 核對表與收尾回報寫「git-commit 是 <版本>，QA 閘只有提早提醒，你選擇先不更新」，Phase 5 的 qa-gate 實跑標「不適用：git-commit 版本低於 0.11.0」。實際回饋：使用者在訪談中途才被告知需要它，還得自己問「裝和不裝差在哪」、裝完再問「然後裝好了嗎」 |

**0-5 與 0-3 怎麼問**：兩項都沒裝時放在**同一則訊息**，先貼「git-commit 裝不裝」、再貼「Codex 裝不裝」，請使用者兩題一起回答；使用者選不裝 git-commit，Codex 那題就作廢（標「不適用」）。只有一項沒裝就只貼那一份。表格裡 0-3 排在 0-5 前面只是編號沿用，問的順序以這裡為準。

**「git-commit 裝不裝」範本**（0-5 沒裝時照填輸出，等使用者回答）：

```
這套流程的「commit 前審查」靠另一個 plugin：git-commit。你目前沒有裝。

|                    | 不裝                         | 裝                                           |
| commit 怎麼進行    | 照你現在的做法               | commit 前先由審查員看過改動，沒過就不准 commit |
| 只加入指定的檔案   | 靠 Claude 自己小心           | 由程式保證，不會把別人的改動一起帶進去       |
| 直接下 git commit  | 可以                         | 會被擋下，一律走它的流程                     |
| 「改了程式有沒有測過」「這次學到什麼」 | 改成每個回合結束時問 | 在 commit 時問                     |
| 代價               | 沒有                         | 每次 commit 多跑一位審查員，慢一點、多花一點用量 |

要裝的話，在提示列輸入（`/` 和 plugin 中間不要有空格）：
  /plugin install git-commit@fulin-plugins
裝好跟我說一聲，我會自己確認它有沒有生效。不裝也可以，跟我說「不裝」。
```

**「Codex 裝不裝」範本**（0-3 沒裝時照填輸出，等使用者回答）：

```
commit 前的審查可以多一位 Codex（OpenAI 的指令列工具）。你目前沒有裝。
偵測結果：`codex --version` → <實際輸出，例：command not found>

|              | 不裝                                   | 裝                                         |
| commit 前審查 | 一位審查員（Claude 審 Claude 寫的程式） | 兩位：Claude 和 Codex 各審一次              |
| 抓得到的錯   | 同一家模型的盲點會一起漏掉             | 兩家模型的盲點不同，可以互相補位           |
| 代價         | 沒有                                   | 要有 OpenAI 帳號；每次 commit 多跑一位，慢一點 |

要裝的話，在終端機依序執行：
  1. npm install -g @openai/codex        （需要 Node.js）
  2. codex login                          （用你的 OpenAI 帳號）
裝好跟我說一聲，我會自己跑 codex --version 確認。
先不裝也可以，跟我說「不裝」：我照一位審查員裝好，並記進定期檢查的清單，之後會再提醒你。
```

---

## Phase 1 — 盤點（唯讀，一次查完再往下）

超過 3 檔的探索照骨架 02 的紀律派 `Explore`（prompt 帶上「搜尋限定目標目錄、禁止全碟掃描」）。以下十三項全部查完（第 12 項只在參考模式查），填進盤點表：

| # | 項目 | 怎麼查（實讀，不信 README） | 記下什麼 |
|---|------|----------------------------|----------|
| 1 | 技術棧 | 讀套件與建置設定檔：`package.json`、`pyproject.toml`／`requirements.txt`、`go.mod`、`pom.xml`／`build.gradle`、`*.csproj`／`*.sln`、`Cargo.toml`、`Gemfile`、`composer.json`、`pubspec.yaml` | 語言、框架、資料存取方式、資料庫；前端與後端各一行 |
| 2 | build／test 指令 | **實際讀**腳本本體：`package.json` 的 `scripts`、`Makefile`、`*.sh`／`*.bat`／`*.ps1`、CI 設定（`.github/workflows/`、`.gitlab-ci.yml`）。能安全執行的（build、測試列出）實跑一次確認存在 | 每條指令＋「查證方式」（讀到哪個檔哪一行、有沒有實跑）。README 寫了但腳本不存在的，記成「文件漂移」。另記**專案自己的掃描或稽核腳本**（有 `--baseline`、或靠 exit code 判斷的：硬編檢查、對應檢查、沒人用的譯文或 export、覆蓋登記…）與**會說謊的東西**（程式碼索引、快取、產生物——過期了不報錯、只給舊答案）：指令、在哪個目錄跑、怎樣算過、看不到什麼，供 05 §5.1 |
| 3 | repo 結構與 git remote | workspace 根的資料夾；每個 repo 的 `git -C <repo> remote -v`；檔案數（`git -C <repo> ls-files \| wc -l`） | remote 指向外部／客戶伺服器＝push 屬外向動作，要進邊界條款；檔案數供裁切規則判斷「小專案」 |
| 4 | 前端類型（三分類） | 照下方「前端分類判準」 | 瀏覽器可驅動／非瀏覽器前端／無前端，**附證據檔案路徑** |
| 5 | 測試基礎 | 找測試目錄（`tests/`、`test/`、`__tests__/`、`spec/`、`src/test/`）與測試設定；**打開看裡面有沒有東西**——數測試檔數量、讀一支確認不是空殼 | 目錄存在 ≠ 有測試（曾實測某 repo 自述有測試目錄，實際不存在）。記「有且有 N 支實測／有目錄但空／無」 |
| 6 | 既有治理層 | `AGENTS.md`、`.agents/`、`.cursor/`、`.github/copilot-instructions.md`、`CONTRIBUTING.md`、`docs/` 底下的開發規範、CI 規範（既有 `CLAUDE.md`／`.claude/` 不在這項，歸第 12 項） | 有 → 記下它管什麼（流程／規範／stack 限制），harness 讓位；這些檔也是 Q7「必讀文件」的候選。**另查註解相關三件（Q11 的依據）**：①既有的註解規範文件（檔名或標題含「註解」「comment」「docstring」的規範檔）②**強制寫 doc 註解的編譯器或 linter 設定**——grep 建置與 lint 設定檔（`*.csproj`、`Directory.Build.props`、`.eslintrc*`／`eslint.config.*`、`Cargo.toml`／`lib.rs`／`main.rs`、`pyproject.toml`／`setup.cfg`／`.pylintrc`／`ruff.toml`、`checkstyle*.xml`）裡的 `GenerateDocumentationFile`、`CS1591`、`require-jsdoc`（含 `jsdoc/require-jsdoc`）、`missing_docs`、`missing-docstring`／`C011[456]`、ruff 或 pydocstyle 的 `D1`、`MissingJavadoc`／`JavadocMethod`，每筆記檔:行與它管哪些成員 ③空殼或罐頭 doc 的熱點：用 `skeleton-comment-guide.md` 第五節的樣式取樣（≤5 筆，記檔:行），另挑 2～3 個講原因、講限制的好註解當「真人範本」候選 |
| 7 | 既有 agent | `.claude/agents/`、`.agents/`、plugin 提供的 agent（`claude plugin list` 或讀 `~/.claude/settings.json` 的 enabledPlugins） | 有 → Q1 裁切規則「已有自己的 agents→用他的名字」 |
| 8 | 外部副作用路徑 | 照下方「危險動作候選推導」掃描表逐類 grep | 每類命中的檔案:行號（取樣 ≤5 筆）＋判斷是真路徑還是假命中；供 Q2 |
| 9 | 敏感物 | `.env*`、`*.pem`／`*.key`／`*.pfx`、`credentials*`、`secrets*`、VPN 設定、客戶機密目錄；`.gitignore` 有沒有擋 | 進實例 CLAUDE.md 絕對邊界（「不得出現在 commit、文件、對外輸出」）；沒被 `.gitignore` 擋的要回報 |
| 10 | 執行期風險事實（B 類 hook 的依據） | ①資料庫：用戶端指令（`psql`／`mysql`／`sqlcmd`／`mongosh`／`redis-cli`）出現在腳本或文件、連線字串與其中的帳號（`sa`／`root`／`postgres`／`admin` 這類高權帳號要特別記；只記帳號名，**密碼與 token 記下的當下就遮成 `***`**，同第 13 項②）、出現過的資料庫主機名（文件或命名說它是正式或測試都只當線索；主機名一併列進第 13 項②走 U1，只有使用者確認過的才算測試庫，沒確認的在規則與寫進的檔案裡一律照正式庫處理） ②起服務：啟動指令與它依賴的環境變數（`NODE_ENV`／`ASPNETCORE_ENVIRONMENT`／`SPRING_PROFILES_ACTIVE`／`--profile`／`.env.<環境>`） ③測試指令本體（第 2 項已查）與測試是否讀環境變數或設定檔（`process.env`／`os.environ`／`.env.test`／測試設定檔） | 每一項都會變成 `guard-risky-command` 或 `guard-test-preconditions` 的一條規則（見 `references/hook-catalog.md` 第 10–14 列）；記下樣式與「正確值」長什麼樣 |
| 11 | 工作法（C 類 hook 的依據） | `.claude/local-overrides.yml` 有沒有條目；有沒有本機覆寫檔（`*.local.*`、`appsettings.*.json`、`.env.local`、`settings.local.*` 被追蹤卻常有未提交改動——`git status` 看一次）；有沒有多工作樹（`git worktree list`）。有本機覆寫時再查兩件事，作為 Q9 的候選：①**只在某些分支才需要的覆寫**——清單上不被 git 追蹤或被 .gitignore 排除的整檔覆寫（例：本機 mock 類別），在 repo 裡找誰引用它的檔名或類別名（注入／註冊／import 的那一行，例：`Program.cs`、`main.ts`、DI 設定檔）；有引用點的記「判準檔＋要找的字串」，查不到引用點的不列（沒有判準可寫） ②**已知會帶到舊版的覆寫**——清單 `reason` 欄或專案記錄提到「舊版會出事」的，記下能代表新版能力的識別字 | 有本機覆寫 → 裝本機覆寫保護三件組（形狀目錄第 16–18 列），①②有候選才問 Q9；同時有本機覆寫與多工作樹 → 03 的 A9 加填「開新工作樹時帶齊覆寫」（形狀目錄第 19 列）；只有多工作樹沒有覆寫檔 → 不裝，記進收尾回報 |
| 12 | 原有的 Claude Code 設定（**僅參考模式**） | 從備份讀，逐項**打開看內容**，不只列檔名：`CLAUDE.md` 每一節；`.claude/agents/*.md` 每支的職責、工具、模型、硬性規則；`.claude/hooks/*` 每支擋什麼（讀程式，不信檔頭註解）與 settings 裡怎麼接線；`.claude/commands/`、`.claude/skills/` 各做什麼；settings 的 `permissions`（allow／deny／ask）；之前裝過 harness 的話，另讀 `05-knowledge-protocol.md` 的健檢紀錄、三份知識筆記檔有沒有真實條目（示範條目不算） | 每一項記「它在管什麼」＋「對應到 harness 的哪一塊」＋預設處置（見下方「原有設定的預設處置」）。另外把原有規矩裡**這個專案自己的經驗**逐條挑出來——這是 Q8 的題目，也是 Phase 5 經驗帶走審查的對照基準之一。**派一支 fresh-context subagent 做（`opus`：要跨檔讀語意、判斷的是「這句話背後有沒有經驗」），不准用關鍵字比對判定**：經驗多半寫成一條普通規則，不會帶「事故」「踩坑」這類字（例：「不准改某個設定檔」「寄送類 API 每次測試最多呼叫 1 次」），grep 只會抓到會自稱踩坑的那幾條。判準（語意，逐段讀）：**拿掉這句，照 harness 通用骨架重產的新規則會不會讓 Claude 重犯某個錯、違反某個人定的約定、或不知道某個這個專案才有的限制？** 會，就是經驗。涵蓋但不限於：出過的錯與繞法、工具或第三方套件的坑、某個人或團隊定的約定與禁令、數字化的安全上限、使用者糾正過的偏好、看似多餘但有原因的步驟。範圍：備份裡的 `CLAUDE.md` 與 `.claude/` 全部，加上 `CLAUDE.md` 路由表指到的每份規則或紀錄文件（在原位唯讀，不搬）。每條記：原文一句、出處（檔名＋章節）、它防的是什麼、現在有沒有東西擋（原有哪支 hook／只有文字）、照預設處置會不會被帶進新設定（會→帶到哪；不會→列為 Q8 候選）。subagent prompt 要帶「搜尋限定目標目錄、禁止全碟掃描」。**裡面寫到的專案事實是盤點證據**：build／test 指令、禁止動作、保護某個檔或某台主機的 hook，照樣拿去跟第 2、8、10 項交叉查證——原有 hook 在擋的東西，代表使用者在乎那個風險，Q2 與 Q5 要列入，不能因為 harness 的形狀目錄沒有就丟掉 |
| 13 | 專案輪廓（業務面；**每個專案都查**） | 讀 README、需求／規格文件、提案文件，再拿程式碼對：①用途與使用者（系統給誰用、解決什麼問題） ②串接的外部系統與資料庫：每個是讀還是寫（對照第 8 項的呼叫點）、**方向**（出向＝我方呼叫對方；入向＝對方主動打進來——grep 對外開放的路由與處理器名稱：`webhook`、`callback`、`notify`、`hook`、`/api/.*/receive` 這類，以及驗對方簽章或共用密鑰的程式；入向的副作用由對方觸發，測試時要問「誰會打進來、打到哪個環境」）、程式與設定檔裡的位址（**記下的當下就遮掉帳密**：連線字串的帳號密碼、路徑或查詢參數裡的 token／key／secret 一律換成 `***` 並註明來自哪個環境變數或設定鍵；核對表與問環境的題目用遮過的版本；**寫進檔案時帳密整段拿掉**——只留主機與路徑，後面註「（帳密取自 <環境變數或設定鍵名稱>）」，連 `***` 都不留）、**文件或位址看起來是正式還是測試**——這只是線索，一律記成「待問（文件說是 X）」，不准當成結論；只有使用者在 U1 確認過的才算測試環境，沒確認的在 Q2 候選、自動檢查規則、寫進的檔案裡一律照正式環境處理；不走網路的（人工下載檔案再上傳）記「不適用」，不列進 U1 ③業務流程：文件列的流程（有代號就記代號）逐條對程式，分「已實作／部分實作／還沒做」三種；部分實作要寫出缺哪一段（例：核心邏輯與測試都在，但沒接進實際流程） ④進度：文件自述的階段 vs 實際（測試數、已實作的流程、最近改動的檔） ⑤候選專案詞，最多 10 個，有幾個列幾個（湊不滿不准拿通用詞充數，一個都沒有就寫「查不到」）：文件與程式識別字裡反覆出現、不是通用程式概念、讀者不問就可能誤解的詞；每個附文件裡的出處與你推的定義 ⑥文件哪裡過時：每份可能列為必讀的文件，逐一記下跟實況不符的地方 | 整理成 Phase 2 的「專案概要草稿」；②的「待問」是 U1 的題目、④是 U2、⑤是 U3、⑥供 Q7 標註。**全部是推論**，每一句附出處（檔名:行號或文件章節），推不出來的寫「查不到」，不准補想像 |

### 原有設定的預設處置（參考模式）

原則：**事實與知識一律留下，流程與機制換成 harness 的，但每一項都要在 Phase 2 攤給使用者否決**。不靜默刪除任何東西——就算有備份，使用者沒看到就是沒交代。

| 原有的東西 | 預設處置 | 為什麼 |
|---|---|---|
| `CLAUDE.md` | **取代**：用 harness 骨架重寫；原檔裡的專案事實（指令、路徑、邊界、禁止事項、術語）逐條搬進新檔對應的節；流程類規定（怎麼派工、怎麼審查）由 harness 的取代。每條原規則記去向：搬進哪一節／被哪條 harness 規則取代／沒搬（理由） | 使用者就是對原本的流程不滿意；但專案事實不會因為換流程而失效 |
| 角色與 harness 某個 agent 相同的 agent（例：原本的 reviewer 對上 code-reviewer） | **併入**：用 harness 骨架建，原 agent 裡的專案專屬內容（技術棧規範、檢查清單、禁止事項）搬進新檔的硬性規則。名字預設用 harness 的名字；使用者要保留原名就用原名，02 對照表、04 模板、check-agent-model 名單、`check-review-discipline.js` 的 `REQUIRED_MARKERS` key 跟著改 | 骨架帶交接契約與回報格式（派工閘與 git-commit 依賴它們），原 agent 帶專案知識，兩邊都要 |
| harness 沒有對應角色的 agent（例：資料遷移專員、文件撰寫） | **沿用**：原檔不動，加進 02 對照表、check-agent-model 名單與 `check-review-discipline.js` 的 `REQUIRED_MARKERS`（兩份名單都要加：前者管有沒有指定模型，後者管派工欄位與必讀檔名）。02 對照表的預設模型照職責對應（adaptation-guide §2.1）：**寫規格或做設計的（需求規格、UX 規格、架構、API 契約）對應 `backend-architect` 那一級，預設 `opus`**；照規格實作、審查的預設 `sonnet`；測試的不低於它要驗的那支實作用的模型（實作是 `opus` 就用 `opus`）；純機械的 `haiku`。原 agent 檔自己寫了 model 的照原檔 | 不是 harness 該決定的分工；但模型要照職責定，不能一律套 sonnet |
| 原有 hook | 讀程式判斷它擋什麼：形狀與 harness 某支相同 → **取代**（harness 版有 cases 可實測）；harness 沒有的 → **沿用**，照原接線寫進新 settings，並在 05 健檢清單加一列（沒有 cases 可跑，註明「原有 hook，手動試跑」） | 原有 hook 在擋的東西代表使用者在乎那個風險 |
| `commands/`、`skills/` | **沿用**，原封不動 | 不屬於開發流程骨架 |
| settings 的 `permissions` | **沿用**，照 Phase 4 JSON 合併 | 使用者自己決定的權限 |
| 之前裝過的 harness（重裝） | 制度文件與 hook 用新版骨架重生，**上一版填進去的專案參數與規則（B 類規則、agent 名單、Q 的答案）當成這次訪談的預設答案**；知識筆記檔與 05 健檢紀錄的真實條目**原樣保留**，只換結構（0.10.0 起變更紀錄拆出本體：舊實例本體的 `## Changelog` 節整節搬進新的紀錄檔，見 Phase 4 知識容器層表下的參考模式說明）（唯一例外：`CONTEXT.md` 裡 U3 裁決改寫或刪除的詞，見 Phase 4 知識容器層）；memory 不動 | 知識是專案自己長出來的資產，重裝不能歸零 |
| 其他檔（`.claude/` 下的過程產物、殘檔） | **不動**，列在收尾回報，由使用者決定 | 不確定用途的東西不替使用者處理 |

### 前端分類判準

依序判斷，命中即停：

| 分類 | 證據（任一成立） | 處置 |
|------|-----------------|------|
| **瀏覽器可驅動** | 有 `index.html`（非文件用途）；`*.vue`／`*.svelte` 檔；`*.tsx`／`*.jsx` 且 `package.json` 相依含 `react-dom`；相依或設定檔含 `vite`／`webpack`／`next`／`nuxt`／`@angular/core`；伺服器端模板渲染頁面（`templates/*.html` 搭配 Web 框架） | 建議安裝 **qa-webwright** plugin（瀏覽器 QA 方法論＋落地 Stop hook）；qa-engineer 骨架用「(A) 瀏覽器可驅動」段；Phase 0-4 的 Playwright MCP allow-list 在此變成必要項 |
| **非瀏覽器前端** | `*.xcodeproj`／`*.xcworkspace`（iOS／macOS）；`AndroidManifest.xml`；`pubspec.yaml`（Flutter）；相依含 `electron`；`*.unity`／`ProjectSettings/`（Unity）；`package.json` 含 `engines.vscode` 或 `contributes`（VS Code extension） | **不裝** qa-webwright；保留 frontend-engineer；qa-engineer 骨架用「(B) 非瀏覽器前端」段改寫成該平台的實測方式 |
| **無前端** | 以上皆無（純 API／CLI／函式庫／資料處理） | 拿掉 frontend-engineer；qa-engineer 用「(C) 無前端」段（實測＝跑測試指令與實際呼叫介面）；**觸發 Q3**（怎樣算做完） |

同一 workspace 有多個 repo 分屬不同分類時，逐 repo 記錄；只要有一個瀏覽器可驅動就走 (A)，其餘 repo 的 QA 方式在 qa-engineer 骨架內並列。

### 危險動作候選推導（外部副作用路徑掃描）

對目標程式碼（排除 `node_modules`／`vendor`／`dist`／`build`／`.git` 等產物目錄）逐類 grep，命中的類別成為 Q2 的候選：

| 類別 | 要 grep 的關鍵字（不分大小寫） | 為什麼危險 |
|------|-------------------------------|-----------|
| 寄信 | `smtp`、`sendmail`、`nodemailer`、`SmtpClient`、`MailMessage`、`sendgrid`、`mailgun`、`ses.send`、`send_mail`、`EmailService` | 測試信真的寄給真人；收不回 |
| 打外部 API | `https?://`（排除 localhost／127.0.0.1／example）、`axios`、`fetch(`、`requests.`、`HttpClient`、`RestTemplate`、`webhook`、`apiKey`／`api_key` | 對外部系統產生真實副作用、耗用配額、觸發對方流程 |
| 毀滅性 SQL | `DROP `、`TRUNCATE`、`DELETE FROM`（無 WHERE）、`ALTER TABLE`、migration 目錄（`migrations/`、`*.sql`）、ORM 的 `drop_all`／`db.sync({ force` | 不可逆的資料損失；schema 變更影響共用資料庫 |
| 部署 | `deploy`、`kubectl`、`helm`、`terraform`、`serverless`、`docker push`、`az webapp`、`gcloud`、`aws s3 sync`、`vercel`、`netlify`、CI 的 deploy job | 動到正式或共用環境 |
| 金流計費 | `stripe`、`paypal`、`braintree`、`adyen`、`綠界`／`ecpay`、`藍新`／`newebpay`、`charge`、`refund`、`invoice`、`billing`、`payment` | 真實金錢流動；退款與重複扣款難收拾 |
| 實機硬體 | `serialport`、`pyserial`、`usb`、`gpio`、`modbus`、`opcua`、`bluetooth`／`ble`、`/dev/tty`、`COM[0-9]`、PLC／韌體燒錄工具 | 物理世界的副作用，可能損壞設備或造成安全問題 |
| 資料管線 | `airflow`、`dag`、`cron`、`schedule`、`kafka`、`rabbitmq`、`pubsub`、`etl`、`bigquery`、`snowflake`、`s3://`、`gs://`、排程設定檔 | 觸發下游全鏈重跑、覆寫他人依賴的資料 |

命中要人判讀：`payment` 出現在變數名不代表有金流路徑。取樣確認是真的會執行到的呼叫點才算候選。

---

## Phase 2 — 攤開核對（一則訊息，讓使用者糾正事實）

把 Phase 0 與 Phase 1 的結果攤成**一張盤點表**給使用者看，並附上「據此自動推導的預設」。這一步不是提問，是**讓使用者在生成前糾正事實錯誤**——盤點是推論，使用者才知道真相（例：某個 `deploy` 腳本其實早已廢棄）。

內容（下列項目名稱是給你的清單；攤給使用者時照「對使用者講話的寫法」改成白話，例如「危險動作候選清單」寫成「做了收不回來的動作，我找到這幾個」）：

0. **專案概要草稿（放最前面）**：從第 13 項整理，照下面格式；每句附出處，並明講「這是我讀文件推的，請直接改」。這份草稿確認後會寫進 CLAUDE.md，之後每個 agent 都靠它理解專案，所以錯的地方現在不改，之後會一直錯下去
   ```
   ## 這是什麼專案（我讀文件推的，請直接改）
   - 用途：<一兩句：給誰用、解決什麼問題>（出處）
   - 串接的外部系統：
     | 系統 | 做什麼 | 方向 | 讀或寫 | 程式裡的位址 | 正式還是測試 |
     | 物流商 API | 建立出貨單 | 我方呼叫對方 | 寫 | settings.py:22 的預設網址 | 看不出來，等一下問你 |
     | 物流商狀態回呼 | 通知出貨狀態 | 對方打進來（routes/webhook.py:8） | 寫（更新出貨單） | 對方設定的回呼網址，程式裡看不到 | 看不出來，等一下問你 |
     | 金流商撥款 | 對帳 | 不適用 | 讀（人工下載檔案後上傳，不走網路） | 無 | 不適用，不用問 |
   - 業務流程：<代號＋一句話，每條註明「已實作／部分實作／還沒做」與依據；部分實作寫出缺哪一段>
   - 目前進度：文件寫 <…>；實際 <…>（依據）
   - 過時的文件：<檔名：哪裡跟實況不符>
   ```
1. 十三項盤點表（每項附證據路徑；查不到的明寫「查不到」；第 12 項非參考模式時不列；第 13 項已整理成上面的概要，表裡只寫「見專案概要」）
2. Phase 0 的版本比對與五項檢查結果（參考模式另附備份位置與比對結果；0-3 使用者選不裝 Codex、0-5 使用者選不裝 git-commit 的，寫明是使用者的決定）
3. 自動推導的預設：
   - 前端分類與對應處置
   - Q1 預設 pipeline 依裁切規則裁完的樣子（先給出，Q1 再讓使用者改）
   - 危險動作候選清單（Q2 的題目來源；參考模式含原有 hook 在擋的東西）
   - 是否觸發 Q3（無前端）、Q6（無測試基礎）
4. 發現的目標專案自身問題（文件漂移、缺測試基礎、敏感物未被 `.gitignore` 擋）
5. **原有設定怎麼處理**（僅參考模式）：每一項一列，照下面格式。使用者在這裡改處置，改了就照改的做

```
| 原有的東西 | 它在管什麼 | 我打算怎麼處理 | 處理後在哪裡 |
| CLAUDE.md 的「部署前要先跑 smoke test」 | 部署前的檢查 | 搬過去（這是專案事實） | 新 CLAUDE.md「絕對邊界」一節 |
| CLAUDE.md 的「改完直接 commit」 | 開發流程 | 換成新流程（改完要先實測、再審查） | 新 CLAUDE.md 的開發流程圖 |
| .claude/agents/reviewer.md | 程式碼審查 | 合併進 code-reviewer（程式碼審查），它的檢查清單搬過去 | .claude/agents/code-reviewer.md |
| .claude/hooks/block-prod-db.js | 擋連正式資料庫 | 保留，繼續接著 | 新 settings 照原樣接線 |
| .claude/commands/deploy.md | 部署指令 | 不動 | 原位 |
```

   表格下面一句話講備份在哪、怎麼還原（「整份原樣在 `.harness-backup/<時間>/`，要還原就把裡面的檔案複製回原位」）。
6. **原有規矩裡的經驗**（僅參考模式）：第 12 項挑出的每一條一列，欄位「經驗｜出處｜它防什麼｜現在怎麼擋｜照預設處置會帶到哪（或：不會帶到）」。這裡只攤出來讓使用者糾正（漏列的、其實已經不適用的），「不會帶到」的在 Q8 問要不要升格。對使用者這樣講：「新的規則文件和自動檢查會照 harness <版本> 重新產生；你原本規矩裡這幾條是這個專案自己累積的經驗，通用規則裡沒有。已經會帶過去的我標出位置；不會帶到的，等一下訪談問你要不要升格成新規則的一部分。」

訊息開頭先用兩三句講結論（這是什麼專案、有沒有前端與測試、找到幾類做了收不回來的動作），再接上面各項（第 0 項專案概要一定放第一個）；整則訊息的**最後一句**固定是：「以上事實有錯請直接指出；沒有的話我開始逐題訪談（共 N 題）。」使用者糾正的事實回 Phase 1 重查確認後更新表格。**無人值守（headless）時**：照推導預設繼續，所有推導值在收尾回報列為「已代決」供事後否決；專案概要照草稿寫進 CLAUDE.md 但標「未經使用者確認」；第 13 項②的外部系統與資料庫全都沒經使用者確認，**一律當正式環境處理**（寫入動作全數列入 Q2 候選、照正式環境設規則），寧可多擋，不准自己判成測試環境；U3 的候選詞不寫進 CONTEXT.md（沒人確認過的定義不算詞條），列在收尾回報等使用者確認。

---

## Phase 3 — 訪談（專案理解 3 題＋流程設定 9 題，參考模式加問第 0 題與 Q8，有本機覆寫候選時加問 Q9；**一次一題**）

順序：Q0（參考模式）→ U1 環境 → U2 進度 → U3 專案詞 → Q10 用語表匯入 → Q1 → Q2 → Q8（參考模式）→ Q3～Q7 → Q11 註解規範 → Q9（有本機覆寫候選）。Q11 排在 Q7 後：它問的是要不要多一份動手前必讀的註解規範，緊接在必讀文件那一題後面最好懂。Q9 排在 Q5 後：本機覆寫保護三件組在 Q5 被取消時就不問。Q8 排在 Q2 後、Q5 前：它選出來的條款要跟 Q2 的危險動作一起推導 Q5 的自動檢查。Q10 緊接 U3：剛確認完詞條，使用者對這份表多大、多常用最有感。**先問專案、再問流程**：U1 的答案決定 Q2 有哪些危險動作，U2 的答案決定 Q7 推薦哪些文件，流程設定要建立在確認過的專案事實上。

**一次一題，不要湊成一次 AskUserQuestion**——每題的答案會改變後面題目的選項（Q1 裁掉 frontend-engineer，Q5 的 hook 名單就跟著變）。每題都附**推薦選項與一行理由**（未附推薦會被 check-ask-discipline 閘擋下，也是三重自查有做的證據）。條件問的題目條件不成立就跳過，並在收尾回報記「<題目主題>那一題沒問：<原因>」（例：「沒有畫面時怎樣算做完那一題沒問：專案有網頁畫面」），不寫內部代號。

| 題 | 必問／條件問 | 問什麼 | 答案決定什麼 |
|----|-------------|--------|-------------|
| **Q0** | **僅參考模式問，排在最前面** | 原本的設定哪裡不好用、這次想改善什麼（可複選，附「其他」） | 後面每一題的推薦選項要朝解決這些痛點調整；每個痛點在收尾回報都要交代「這次怎麼處理的，或沒處理、為什麼」。選項從第 12 項盤點推：例如原本沒有審查角色 →「改完沒人審」；原本 hook 只有 0～1 支 →「規則寫了但 Claude 不照做」；CLAUDE.md 很長 →「規則太多、Claude 抓不到重點」 |
| **U1** | **有要判斷的外部系統時必問**（第 13 項②全是「不適用」或沒有外部系統時跳過，收尾記「問環境那一題沒問：沒有需要分正式或測試的外部系統」） | 第 13 項②的每個外部系統與資料庫：哪個位址是正式、哪個是測試；程式預設值指向哪一個；將來會不會接正式。**一律加問：有沒有外部系統會主動打進來**（webhook、回呼、對方排程推資料）——第 13 項②找到的入向端點附上讓使用者確認，也請他補程式裡看不出來的（入向的位址設定在對方那邊，盤點常常找不到）；每一個入向都問「對方的正式和測試環境各打到我們哪個環境」。**有資料庫時再問兩件事**：Claude 連測試庫該用哪個帳號（帳號名）、密碼放在哪個環境變數（只問變數名，例 `DB_TEST_PASSWORD`）——**不收密碼值**，使用者貼了密碼就提醒他換掉、不寫進任何檔；還沒有這個環境變數的，請使用者自己設好（Claude 不代設） | DB 登入規則的兩個填空（帳號、密碼的環境變數名，見 Phase 4）；使用者答不出或不想給帳號時，DB 登入規則照裝、填空留著佔位（等於所有 DB 登入都擋，收尾回報寫明）。Q2 的候選重算：寫入正式環境的動作一定列；使用者答「不確定」的當正式環境處理；使用者確認是測試環境的，改成「指向非這個測試位址時擋下」（例：測試環境網址以外的位址一律先問），而不是整項拿掉——規則一律「沒確認的就擋」：遠端主機與網址規則都列出允許的完整形狀，認不得的寫法全部擋；本機位址（localhost、127.0.0.1、[::1]）預設放行，不必問（定位是防 Claude 手滑，不是防刻意繞過；寫法照 `guard-risky-command.js` 填空說明與兩個示範規則；寫成「出現測試位址就放行」，同一條指令帶一個測試、一個正式位址時會放過）；CLAUDE.md 專案概要的環境表（含「方向」欄；入向的寫入由對方觸發，列進 Q2 候選時寫「對方打進來會寫入 X」）；PROJECT.md「環境與執行」 |
| **U2** | **必問** | 現在做到哪、接下來要做什麼（附第 13 項④推的進度讓使用者改） | CLAUDE.md 專案概要的「目前進度」；Q7 推薦時優先講接下來要做的部分的文件 |
| **U3** | **必問** | 第 13 項⑤的候選專案詞，每個附推的定義與出處（參考模式：原本 CONTEXT.md 已收的詞不再列，除非文件或程式的用法跟原定義衝突，這時列出兩邊請使用者裁決，裁決結果改寫原條目；使用者裁決「這個詞不用了」就刪掉原條目，記進收尾回報）；使用者逐個確認、改寫或刪掉，也可以補他常講的詞 | 確認過的寫進 CONTEXT.md 成為真詞條（刪示範）；刪掉的不寫；使用者新候選一個都不要時：新詞一個都不寫；原條目照常搬（被裁決刪除的除外）；搬完加刪除後一條真詞條都沒有，才只留示範；在收尾回報寫明 |
| **Q1** | **必問** | 給預設 pipeline（已依裁切規則裁過）讓使用者刪改 | 02 agent 對照表、04 模板五 pipeline、`.claude/agents/` 建哪幾支、check-agent-model 名單、`check-review-discipline.js` 的 `REQUIRED_MARKERS`（裁掉的角色整組刪）與 `DOC_SECTION_RULES` 的 agents |
| **Q2** | **必問** | Phase 1 掃出來的危險動作（已照 U1 的環境答案改寫：寫測試環境的動作改成「位址不是那個測試環境時擋下」），哪些要熔斷（執行前必須徵得同意） | 03 C2 清單、CLAUDE.md 絕對邊界；掃描零命中時改問「有沒有掃不到但確實存在的危險動作」 |
| **Q3** | **僅無前端時問** | 怎樣算做完（沒有畫面可以看，「實際跑起來」的證據是什麼：CLI 輸出？API 回應？產出檔案？） | 03 B3 的驗證方式、qa-engineer 骨架 (C) 段的實測方式 |
| **Q4** | **必問** | 單人還是團隊 | 落點與紅區語義（見下表） |
| **Q5** | **必問** | 攤出依形狀目錄推導出的 hook 清單（每支：擋什麼、為什麼這個專案需要——對應哪個盤點證據或哪題答案），問要不要**取消**哪幾支 | 可執行層裝哪幾支、B 類引擎裝哪幾條規則、settings 層接哪幾條 |
| **Q6** | **僅無測試基礎時問** | 要不要暫時豁免「QA codify 成可重跑測試」的要求（豁免期間 QA 改為實跑＋貼輸出） | 04 模板五配套第 3 條加豁免行、03 B4／B14 的驗證欄改寫 |
| **Q7** | **必問** | 哪幾份文件動手前必讀（從 Phase 1 第 6 項的既有治理層與規範檔中挑）；第 13 項⑥判定過時的文件照樣可以推薦，但要同時講哪裡過時；選進必讀的過時文件，在 04 的【開工前必讀】、CLAUDE.md 路由表「動手前必讀文件」那一列、每支 agent 的「開工前必讀」，檔名後面都加註「（過時：<哪裡>，以程式碼為準）」 | 04 共通規則與各模板的【開工前必讀】、五支 agent 的「開工前必讀」、CLAUDE.md 路由表 |
| **Q8** | **僅參考模式、且第 12 項有「不會帶到」的經驗時問**（沒有就跳過，收尾記「舊規矩經驗那一題沒問：原有規矩裡的經驗照預設處置都會帶過去」） | Phase 2 第 6 項裡「不會帶到」的經驗（使用者糾正後的版本），哪幾條要升格（可複選；附「全部」與「都不要」） | 選的每一條寫進 03 矩陣 D（一條一列，附出處）；能從指令樣子認出來、原本又沒有 hook 擋的，推導成 `guard-risky-command`／`guard-test-preconditions` 的一條規則，進 Q5 清單標「從舊規矩升格」。沒選的：不寫進新規則；原文仍在——出處檔這次沒被動過（沿用的文件、路由表指到的原位文件）就在原位；出處檔被取代或併入（`CLAUDE.md`、併入的 agent、取代的 hook 與舊制度文件）就只剩 `.harness-backup/<時間>/` 裡的原檔——收尾回報逐條寫出是哪一種、確切路徑，之後要升格照 05 §6 提議 |
| **Q9** | **僅在 Q5 保留了本機覆寫保護、且 Phase 1 第 11 項①或②有候選時問**（沒有候選就跳過，收尾記「只在某些分支才需要的覆寫那一題沒問：<沒有本機覆寫／Q5 取消了本機覆寫保護／清單上的覆寫都找不到引用點，也沒有已知的舊版問題>」） | ①候選裡哪幾筆只在某些分支才需要（附判準檔與要找的字串，讓使用者改）②哪幾筆要宣告「一定要含有的字串」（可複選；附「都不要」） | 選的寫進覆寫清單該筆條目：①→`needed-when-file`＋`needed-when-contains`；②→`requires`（好幾個字串時重複寫）。改清單前先備份成 `local-overrides.yml.bak`（用 shell 的 `cp` 建——`.claude/` 根層的整潔檢查只放行允許清單上的檔名，Write 新建 `.bak` 會被擋）。沒選的不寫——開場檢查（alive）與救回腳本（restore）照舊把它當「每個分支都需要」，該報就報 |
| **Q10** | **必問**（接在 U3 後面；參考模式原本的 CLAUDE.md 已經有 `@CONTEXT.md` 時照樣問，推薦沿用） | `CONTEXT.md` 要不要用 `@CONTEXT.md` 匯入主對話（每個 session 開頭自動整份載入）。利：主對話一定讀得到用語表，CONTEXT.md「何時寫」那一節的四個當場觸發時機（使用者的詞跟表衝突、用了模糊的詞…）才做得到——沒讀過表就不知道衝突；弊：每個 session 固定多一份載入成本，表越長越貴（來源專案約 50 個詞、16KB）。**推薦匯入**：init 剛建的表很小，成本可以忽略，而「當場寫」是這份表能長出來的主要機制；表長大之後要省，刪掉 `@CONTEXT.md` 那一行就是不匯入 | CLAUDE.md：選匯入→骨架 §0 末行「專案用語的定義見 `CONTEXT.md`。」改成「專案用語的定義見 `CONTEXT.md`（下一行匯入，每個 session 自動載入）。」，下一行**獨立一行、行首、不加反引號**寫 `@CONTEXT.md`（包在反引號或程式碼區塊裡不會被匯入）；路由表「本專案特有詞彙」那列寫「`CONTEXT.md`（workspace 根；已用 @ 匯入，每個 session 自動載入）」。不匯入→兩處照骨架原文，不寫 `@` 那一行。不論哪一種，派工的【開工前必讀】照樣列 CONTEXT.md（subagent 不吃主對話的匯入） |
| **Q11** | **必問**（排在 Q7 後） | 要不要建註解規範（`references/skeleton-comment-guide.md`）：程式註解寫為什麼、不寫做了什麼；禁止空殼 doc 註解與揭露 AI 參與的痕跡（引用內部文件出處、對話脈絡、AI 工具名）；編譯器或 linter 要求寫 doc 註解時改寫或局部關閉規則、不補空殼。附 Phase 1 第 6 項盤點到的三件：既有註解規範文件、強制 doc 註解的設定（檔:行）、罐頭 doc 熱點取樣與真人範本候選。**推薦**：盤點到強制 doc 註解的設定、或有罐頭 doc 熱點 →「建」；已有自己的註解規範文件 →「沿用」（不另建，把骨架裡它缺的條款——通常是第三節「編譯器或 linter 要求一定要寫 doc 註解時」——列給使用者決定要不要補進原檔）；三件都沒有 →「不建」（agent 檔裡「寫為什麼不寫做了什麼、不補空殼、不留 AI 痕跡」的通用底線照樣有） | 選「建」→ 產生 `.claude/harness/07-comment-guide.md`（Phase 4 文件層），真人範本只寫使用者在這題確認過的；三支 agent 的「註解規範檔」填空、03 B6 的規範路徑、CLAUDE.md 路由表、harness README 與 CHANGELOG 的 07 那一列／節都填這個路徑；有產生 git-commit 審查附加要求檔時，加一條「註解依 <路徑> 審」。選「沿用」→ 不建 07 檔本身，上述各處改填既有文件的路徑；**另外先檢查既有文件有沒有處理「編譯器或 linter 強制要寫 doc 註解」的那類內容**（怎麼處理缺 doc 的警告、能不能局部或整專案關閉），三支 agent 骨架裡指向「那一節」的填空依結果填：(a) 有 → 指向既有文件裡那一節**實際的節名**（照實填，不套骨架的節名）；(b) 沒有 → 問使用者要不要在既有文件補一節（標題用骨架第三節的名稱「編譯器或 linter 要求一定要寫 doc 註解時」，內容照骨架第三節：三種做法＋設定表，設定表照 Phase 1 第 6 項②填，沒有設定時保留表頭並註明目前沒有），同意就補（改既有文件前先 `cp` 備份）並照 (a) 指向它；(c) 使用者不補 → 三支 agent 改用「沒有那一節」的寫法（整專案關閉在交接回報列出、由使用者決定記在哪；審查員那條不加括號），不得指向不存在的節。三支 agent 骨架的填空說明照這三種情況寫好了填法；harness README 那一列與 harness CHANGELOG 的 07 那一節**照樣保留**，改填既有文件（節標題寫 `## 07-comment-guide.md（沿用 <既有文件路徑>）`，那一行寫「沿用專案既有的註解規範 <路徑>，init 只引用、不改內容」；(b) 使用者同意補節時改寫「沿用專案既有的註解規範 <路徑>，init 補上「編譯器或 linter 要求一定要寫 doc 註解時」一節」）。只有選「不建」才刪掉那一列與那一節。選「不建」→ 各處的註解規範填空照骨架寫的刪掉或用通用寫法 |

### 每一題對使用者怎麼問（照這個講，`<…>` 換成盤點到的實際內容）

上表是給你判斷用的；下面才是對使用者說的話。每題都要有：要他決定什麼、選了之後會發生什麼、我的建議與理由。

**第 0 題（原本的設定哪裡不好用；只在專案已經有 Claude Code 設定時問）**
> 你的專案原本就有 Claude Code 設定（<例：CLAUDE.md、2 個 agent、1 支自動檢查>），已經整份備份在 `.harness-backup/<時間>/`。
> 會重新裝一套，應該是原本用起來有地方不順。哪些是你想改善的？可以複選：
> 1. <例：規則寫了，但 Claude 常常不照做>
> 2. <例：改完沒人審查，錯到你自己發現>
> 3. <例：CLAUDE.md 太長，Claude 抓不到重點>
> 4. 其他（直接告訴我）
> 建議：<選項>——<一行理由，從盤點到的原有設定推，例：原本只有文字規則、沒有任何自動檢查>。

下面各題標題的「第 N 題」是本檔的編號；對使用者說的時候照實際問的順序連號。

**U1（外部系統與資料庫，哪些是正式環境）**
> 你的專案會連到這些外部系統和資料庫：
> | 系統 | 程式做什麼 | 程式裡的位址 | 我的判斷 |
> | <物流商 API> | <建立、取消出貨單（寫入）> | <settings.py 第 22 行的預設網址> | <看不出是正式還是測試／文件說是測試環境，還沒經你確認> |
> <不走網路的（例：人工下載檔案再上傳）另起一句說明「這項沒有位址，不用分正式或測試」，不列進要你回答的表>
> 請告訴我每一個是正式環境還是測試環境；你還沒確認的，Claude 一律當正式環境處理；程式預設值如果指向正式環境，也請說一聲。
> 另外，有沒有外部系統會**主動打進來**（例如對方的 webhook、處理完回呼我們、定時推資料過來）？<有找到時加：我在程式裡找到這幾個接收端：<路由與檔案:行>。>這類的位址設定在對方那邊，我從程式碼常常看不到，請補給我；也請告訴我對方的正式和測試環境各會打到我們哪一個環境。
> 這會決定哪些動作 Claude 做之前要先問你：寫進正式環境的一定要先問；測試環境的，我會改成「只要位址不是這個測試環境，就先擋下來問你」，避免哪天設定換成正式環境卻沒人發現。
> 建議：<選項>——<一行理由>。

**U2（專案現在做到哪）**
> 文件寫的進度是「<README 的自述>」，但我看到 <實際狀況：例如已經有 40 個測試，五條流程做完三條、一條做了一半（缺哪一段）>。
> 現在實際做到哪？接下來最先要做的是什麼？
> 這會寫進 CLAUDE.md 的專案概要，之後每個需求進來，Claude 都先用它判斷這個需求落在哪一段；也會影響等一下推薦哪些文件要每次先讀。
> 建議：<我推的版本>——<一行理由>。

**U3（專案用語）**
> 文件和程式裡有幾個詞，第一次看的人容易誤會。下面是我從文件推的意思，請逐個確認、改掉不對的，或刪掉不需要的；你平常常講、我沒列到的也可以補：
> 1. <結案>：<推的定義>（出處：<文件與章節>）
> 2. …
> 確認過的會寫進 `CONTEXT.md`（專案用語表），之後 Claude 碰到這些詞就照這裡的意思，不會自己猜。
> 建議：<全部照這樣／改哪幾個>——<一行理由>。

**第 10 題（用語表要不要每次自動載入；接在專案用語那一題後面問）**
> 剛才確認的詞會寫進 `CONTEXT.md`（專案用語表）。這份表有兩種接法：
> 1. **每次開新對話都自動整份載入**：Claude 跟你講話時一定看得到這些詞。你講到表裡沒有的詞、或講法跟表裡的定義對不上，它能當場發現、當場問你、當場補進表——這件事要它先看過表才做得到。代價是每次開新對話都固定多讀這份表：現在 <N> 個詞、約 <M> KB，詞收得越多就越大（參考：一個收了約 50 個詞的專案，這份表約 16KB）。
> 2. **不自動載入**，只在規則裡寫「詞的意思查 `CONTEXT.md`」：開新對話不多花，但 Claude 只有自己想到去查才看得到，上面那種「當場發現講法對不上」多半會漏掉。
> 不論選哪一種，派工給其他角色時都會把這份表列進必讀，那一段不受影響。
> 建議：1 自動載入——<一行理由，例：現在只有 <N> 個詞、很小，幾乎不增加成本；等表長大了想省，刪掉 CLAUDE.md 裡那一行就變成 2>。

**第 1 題（開發流程的角色分工）**
> 之後每個開發需求，Claude 會照下面的順序分給不同角色做：
> <例：後端架構設計（backend-architect）→ 後端實作（backend-engineer）→ 測試（qa-engineer）→ 程式碼審查（code-reviewer）>
> 我已經依你的專案拿掉用不到的角色：<例：沒有前端，所以沒有前端實作這個角色>。
> 另外有三條規則固定跟著這個流程：①動手前先確認需求有沒有兩種以上的理解，有就先問你；②改到程式行為的，先實際跑過再送審查；③只改文字、排版這類讀程式就能確定沒問題的，審查過就算完成。
> 要增加或拿掉哪個角色嗎？建議：照目前這樣——<一行理由>。

**第 2 題（執行前一定要先問你的動作）**
> 我在程式碼裡找到這些做了就收不回來的動作：
> 1. <寄信：api/src/mail.js 第 12 行用 nodemailer 寄信，測試時會真的寄給收件人>
> 2. <部署：scripts/deploy.sh 會推到正式環境>
> 3. <出貨單寫入物流商：你說 settings.py 的預設網址是測試環境，所以只有位址被改成別的時才擋下來問你>
>
> 你勾選的每一項，之後 Claude 要做之前都會先停下來問你，不會自己動手；能用指令樣式認出來的，我還會加一條自動檢查，真的遇到時直接擋下。
> 請勾選要納入的項目。有我沒找到、但確實存在的危險動作，也請直接告訴我。
> 建議：全部勾選——<一行理由>。

（掃描零命中時改問：「我在程式碼裡沒找到寄信、部署、刪資料這類收不回來的動作。有沒有我掃不到、但確實存在的？例如只在某台機器上手動跑的腳本。」）

**第 3 題（沒有畫面的專案，怎樣算做完）**
> 你的專案沒有畫面可以打開來看，所以 Claude 說「做完了」之前要拿什麼當證據？例如：指令的實際輸出、API 的回應內容、產出的檔案。
> 建議：<例：跑一次 CLI 並貼出輸出>——<一行理由>。

**第 4 題（一個人用還是團隊一起用）**
> 這套規則只有你自己用，還是團隊一起用？
> - 只有自己：規則檔不進版控、不會被 commit，要改規則問你就好。
> - 團隊：規則檔放進 repo 一起版控，大家用同一套，改規則要走 PR 審查。
> 建議：<選項>——<一行理由，例：remote 指向客戶的伺服器，規則檔不該跟著推出去>。

**第 5 題（要裝的自動檢查）**：照下方「Q5 攤給使用者的格式」列出清單，接著問：
> 以上是依你的專案推導出來、預設全部安裝的自動檢查。要取消哪幾項嗎？
> 建議：全部保留——<一行理由>。

**第 6 題（還沒有自動測試時）**
> 你的專案目前沒有自動測試。這套流程原本要求：每次改到程式行為，都要補一支可以重跑的自動測試。
> 要先暫停這個要求嗎？暫停期間改成：Claude 每次實際跑過並把輸出貼給你看。
> 建議：<選項>——<一行理由>。

**第 7 題（動手前必讀的文件）**
> 我找到這些你們既有的規範文件：<檔名清單>。哪幾份要設成 Claude 每次動手前都先讀？
> 其中 <檔名> 有些地方已經跟現況對不上：<哪裡過時>。選了它的話，我會在必讀清單上註明這幾處以程式碼為準。
> 建議：<檔名>——<一行理由>。

**第 11 題（程式註解的規範；排在動手前必讀文件那一題後面）**
> 要不要幫這個專案建一份程式註解的規範？它會規定：
> - 註解寫「為什麼這樣做」，不寫「這段做了什麼」的流水帳；不寫空的說明區塊、不複述函式名
> - 程式碼與註解裡不留 AI 參與的痕跡（引用內部文件的章節號、「依使用者指示」這類對話內容、AI 工具名）
> - 編譯器或檢查工具要求每個公開成員都要有說明時，改寫成真正有內容的一句話，或在那一處關掉檢查並寫理由——不補空殼來壓警告
> 我在專案裡找到：<強制寫說明的設定，例：api/App.csproj 第 12 行開了「缺說明就警告」>；<空殼說明的例子，例：src/Handlers/ 底下 3 處只寫了函式名>；<可以當範本的好註解，例：src/billing/retry.ts 第 40 行「對方逾時不代表沒收到，重送前先查單號」>。
> 選「建」：規範寫進 `.claude/harness/07-comment-guide.md`，寫程式的角色動手前必讀、審查的角色照它審，上面那幾個好註解當範本（你可以刪換）。選「沿用」<只在已有自己的規範文件時列>：照你們的 <檔名>，我只把它缺的條款列給你決定要不要補。選「不建」：只保留基本原則（寫為什麼、不補空殼、不留 AI 痕跡），不另外寫一份。
> 建議：<建／沿用／不建>——<一行理由，例：你們的編譯設定會對缺說明的成員發警告，最容易被補成空殼>。

**第 8 題（舊規矩的經驗要不要升格；只在專案已經有 Claude Code 設定時問，對使用者講時排在第 2 題之後）**
> 新的規則文件和自動檢查會照 harness <版本> 重新產生。你原本的規矩裡，下面這幾條是這個專案自己累積的經驗，照預設處理不會被帶進新規則：
> 1. <新分支沒設好上游就 push，會推到別人的分支>（出處：<記踩坑的文件與章節>；現在：<只有文字，沒有東西擋>）
> 2. <編譯過了畫面還是可能空白，要另跑元件匯入檢查>（出處：<記踩坑的文件與章節>；現在：<只有文字>）
> 選的會寫進新規則的「本專案經驗條款」，之後碰到相關的事 Claude 會照它做；能從指令樣子認出來的，我會另外加一條自動檢查直接擋下。沒選的不會寫進新規則，但原文不會刪：所在的檔這次沒動就留在原位；所在的檔被新版取代（例如 CLAUDE.md、被合併的 agent）就留在備份資料夾裡，收尾回報會逐條告訴你在哪。
> 建議：<全部／哪幾條>——<一行理由，例：這幾條都還適用，其中第 2 條目前只有文字、沒有東西擋>。

**第 9 題（只在某些分支才需要的本機覆寫；只在裝了本機覆寫保護、而且找到候選時問，對使用者講時排在最後）**
> 你的本機覆寫清單（`<覆寫清單位置>`）上有幾個檔，看起來只在某些分支才用得到：
> | 覆寫檔 | 什麼時候才需要 | 依據 |
> | <src/Infra/MockMailService.cs> | <src/App/Program.cs 裡有寫到 MockMailService 的時候> | <Program.cs 第 40 行注入它；這個檔被 .gitignore 排除，只存在你的電腦上> |
> 切到沒有這個功能的分支時，這個檔本來就不該在（補回去反而編譯不過）。不設定的話，每次開新對話 Claude 都會提醒你「它不見了」。設定之後，只有在「什麼時候才需要」那個條件成立時才檢查它。
> <有②的候選時加：另外，下面這幾個檔如果帶到舊版會出問題，我可以記下「新版一定有的字」，以後檔案還在、但少了這個字時，開場就會提醒你：>
> <| src/Infra/MockBpmService.cs | 一定要有「MockBpmIdSeq」 | reason 欄寫「舊版用時間戳發號會撞號」 |>
> 要設定哪幾個？條件或字串不對可以直接改。我會先備份清單，再把設定寫進去。
> 建議：<全部／哪幾個>——<一行理由，例：這兩個 mock 都只有新功能分支在用，主線切回舊版時一定會被誤報>。

### Q1 的預設 pipeline（原版照搬）

```
[對齊回合] → backend-architect 設計 → backend-engineer 實作 ┐
             frontend-engineer 實作（等 API Contract 確認後）┘
           → qa-engineer 測試計畫＋開畫面實測＋codify
           → code-reviewer 審查 → 完成
```

**配套三條（裁切不拿掉，Q1 一併展示）**：

1. **無條件對齊回合**：行為類需求開工前必過一回合、不可跳過——有決策型解讀分岔就逐題訪談到清零；無分岔就明說「無分岔＋一句理由」讓使用者可否決才開工，靜默開工＝違規。
2. **QA 先於 review**：行為類一律先 QA 實測、再送審查——靜態審查看不出跑起來才會出的錯。
3. **分流例外**：純結構／文案／死碼等「靜態可確定等價」者，可審查過即完成、QA 可評估跳過（判準＝正確性能否只靠讀 code 確定）。

### 自動裁切規則（Phase 2 先套用，Q1 再讓使用者改）

| 盤點結果 | 裁切 |
|----------|------|
| **無後端** | 拿掉 `backend-architect` 與 `backend-engineer`；frontend-engineer 的前置條件改成「API／資料來源已確認」 |
| **無前端** | 拿掉 `frontend-engineer`；QA 改跑測試指令（qa-engineer 用 (C) 段） |
| **非瀏覽器前端** | 保留 `frontend-engineer`；QA 改寫（qa-engineer 用 (B) 段），不裝 qa-webwright |
| **前後端同 repo 且無分層**（前後端程式碼混在同一套目錄結構、沒有 API 邊界） | `architect` 與 `engineer` 併一步：engineer 先產出設計文件並經簽收再實作（backend-engineer 骨架的併步改寫說明） |
| **單人小專案**（1 個 repo、`git ls-files` < 50 檔） | `architect` 併入 `engineer`，**但保留對齊回合與 QA**——小專案省的是角色切換，不是驗證 |
| **已有自己的 agents**（參考模式） | 照 Phase 1「原有設定的預設處置」：同角色的併入 harness 骨架（名字預設用 harness 的，使用者要保留原名就用原名）；harness 沒有的角色沿用並加進名單。02 對照表、04 模板、check-agent-model 名單、`check-review-discipline.js` 的 `REQUIRED_MARKERS` key 填最後定案的名字（保留原名卻沒改 key，那個角色就完全不受派工檢查） |
| **AGENTS.md／.agents/ 這類多工具治理層定義了角色** | 用它的名字：不建同名通用 agent，02 對照表、04 模板、check-agent-model 名單、`check-review-discipline.js` 的 `REQUIRED_MARKERS` key 與 `DOC_SECTION_RULES` 的 agents 全部改填既有名稱（adaptation-guide §2） |

多條同時成立時全部套用（例：無後端＋單人小專案＝只剩 frontend-engineer → qa-engineer → code-reviewer，且 architect 職責併入 frontend-engineer 的設計步驟）。

### Q4 單人／團隊 → 落點與紅區語義

| | 單人 | 團隊 |
|---|------|------|
| 制度檔落點 | workspace 根（不進版控；零外向風險）—— remote 指向客戶時尤其如此 | repo 內（進版控，大家共用同一套制度） |
| settings | `.claude/settings.local.json`（個人層） | `.claude/settings.json`（進版控） |
| hook 指令路徑 | 絕對路徑 | `"$CLAUDE_PROJECT_DIR"/.claude/hooks/<檔>`（別台機器路徑不同；冷啟探針會驗證它真的解析得到） |
| 紅區語義 | 改前徵得「使用者」同意 | 改前需團隊共識（走 PR 審查）；Claude 端的紀律仍是「先說明原因＋位置＋建議內容，確認後才動」 |
| memory | 個人 auto-memory | 個人 auto-memory 不共享——團隊共享的教訓要升格進制度檔或知識容器（05 §6） |

### Q5 的 hook 清單怎麼來：照形狀目錄推導，不是從菜單挑

正本＝`references/hook-catalog.md`（來源專案 24 支 hook＋3 個 plugin 自帶閘，逐支拆成「通用形狀＋觸發條件＋專案參數」，分 A 必裝／B 盤點觸發／C 工作法觸發／D 由 plugin 提供／E 長出來才裝五類）。**沒有數量上限**——裝幾支由這個專案的事實決定。

推導（事實判定，不問使用者）：

1. 形狀目錄逐列判觸發條件，用 Phase 1 十三項與 U1、Q1–Q4 的答案（參考模式：原有 hook 照「原有設定的預設處置」逐支判定取代或沿用，沿用的也列進 Q5 清單，標「原本就有」）。
2. **B 類的每一個風險都要落成一條規則**：Phase 1 第 8 項的危險動作候選（Q2 勾選的）、第 10 項的執行期風險事實、Q8 升格且認得出指令樣子的經驗（原本沒有 hook 擋的），各自變成 `guard-risky-command.js` 或 `guard-test-preconditions.js` 的一條規則。**熔斷清單上的項目只寫進文字、沒有對應規則＝推導不完整**——只能靠人判斷、做不成樣式比對的，要在 Q5 與收尾回報逐項說明為什麼停在文字（對使用者這樣講：「<某動作>沒辦法從指令的樣子認出來，所以沒有自動檢查，只寫進規則文件，靠 Claude 做之前自己停下來問你」）。
3. D 類不複製，列進安裝指引；E 類不裝，寫進 05 §6 的「可升格機械閘」清單。

Q5 攤給使用者的格式（每項一列；不列 A～E 分類，第一欄是白話名稱，檔名放最後一欄）：

```
| 自動檢查 | 會擋下什麼 | 為什麼你的專案需要 | 檔名 |
| 派工時一定要指定模型 | 派 agent 時沒指定模型（會默默沿用主對話的模型；主對話用高階模型時，每個 agent 也跟著用高階模型） | 問角色分工那一題定了 4 個 agent 角色 | check-agent-model |
| 連資料庫只准用確認過的測試帳號、密碼從環境變數帶 | 用別的帳號連資料庫、在指令裡直接寫密碼、或沒帶帳密就連（憑印象試密碼，連續失敗會把整台庫鎖住；postgres 這類高權帳號也在內） | api/.env.example 第 3 行的連線字串用 postgres；你確認的測試帳號是 qa_reader、密碼放在 DB_TEST_PASSWORD | guard-risky-command |
| 跑測試前檢查寄信設定 | 寄信伺服器沒指向本機的假收件匣就跑測試（測試信會真的寄出去） | api/src/server.js 第 5 行用 nodemailer 寄信 | guard-test-preconditions |
...
沒有裝的：
- 本機設定檔保護（backup-local-hacks 等三項）：本機覆寫清單（`.claude/local-overrides.yml`）不存在或沒有任何條目，也沒有只給本機用的設定檔（例如 `*.local.*`、`appsettings.*.json`）
- 寫測試時自動檢查測試品質（guard-test-asset-hygiene）：要等專案有自己的測試檢查腳本（例如抓測試寫死資料）才用得到
```

使用者只能**取消**（「不要 X」），不能從空清單挑——預設是全裝，取消的在收尾回報記「使用者取消：X」。**推導清單一律在 Phase 4 生成前完整印出**，即使使用者已預先給了「全裝」之類的答案、或無人值守執行——清單本身是使用者能否決的依據，不能只在收尾回報裡事後補。外部 plugin 的安裝是互動 UI（`/plugin install`），Claude 不能代裝——列出安裝指令請使用者執行，並在收尾回報標註「未裝則對應探針跳過」。

---

## Phase 4 — 生成（五層）

以骨架為底逐檔生成。所有 `{{...}}` 必須填掉或整段刪除（該段不適用時）；**不確定的事實回 Phase 1 查證，不得留猜測**。落點中的 `<落點>` 依 Q4：單人＝workspace 根、團隊＝repo 根。

### 文件層（6 份 md＋2 份變更紀錄；Q11 選「建」時多 1 份註解規範）

**變更紀錄一律不寫在指令檔本體**（0.10.0 起）：CLAUDE.md 與 harness 各檔每次載入都整份進 context，紀錄放在檔裡只會越長越胖。harness 目錄的檔記在 `.claude/harness/CHANGELOG.md`、依檔名分節（`## 05-knowledge-protocol.md`）；CLAUDE.md 記在同目錄的 `CLAUDE.changelog.md`；agent 檔與知識容器見各自那一層的表。每份實際建立的檔都要在它的紀錄檔留一行「建立（harness plugin /harness:init 實例化）」——`/harness:review` 的收集腳本用這行判安裝日、略過 init 那一筆。

| 來源（`references/`） | 落點 | 填空重點 |
|------|------|----------|
| `skeleton-CLAUDE-md.md` | `<落點>/CLAUDE.md` | 專案概要（Phase 2 草稿經使用者改過的版本＋U1 環境表＋U2 進度，附確認日期；環境表「方向」欄照 U1 答案寫出向／入向，裝了本機覆寫保護時加「本機」欄，每格附正本出處；位址只寫主機與路徑，帳密一律寫「取自 <環境變數或設定鍵名稱>」，連線字串裡帶帳密的要拆掉）、workspace 對照、治理分層、絕對邊界（含 Q2 熔斷清單、敏感物）、pipeline 圖（Q1）、路由表（含容器、agents、hooks、Q7 必讀）；Q10 選匯入時加 `@CONTEXT.md` 那一行並改路由表那一列（寫法見 Q10 那一列） |
| `skeleton-CLAUDE.changelog.md` | `<落點>/CLAUDE.changelog.md`（與 CLAUDE.md 同目錄） | 建立日。CLAUDE.md 本體不留 changelog 節 |
| `skeleton-harness-CHANGELOG.md` | `<落點>/.claude/harness/CHANGELOG.md` | 每份實際建立的 harness 檔一節（`## <檔名>`），各記一行「建立」；沒建的檔不留節（07 那一節：Q11 選「建」照常留；選「沿用」也留，改填既有文件的路徑，寫法見 Q11 那一列；只有選「不建」才刪）。**`## 05-knowledge-protocol.md` 這個節標題一個字都不能改**——健檢到期提醒（`health-check-reminder.js`）與 `/harness:review` 只從這一節找【健檢執行】紀錄 |
| `skeleton-harness-README.md` | `<落點>/.claude/harness/README.md` | 五層清單、生效範圍限制照實寫、誠實揭露 |
| `skeleton-02-model-dispatch.md` | `<落點>/.claude/harness/02-model-dispatch.md` | agent 對照表（Q1 裁切後）、MCP 紀律（依前端分類保留或改寫）、hook 強制句（Q5） |
| `skeleton-03-judgment-matrix.md` | `<落點>/.claude/harness/03-judgment-matrix.md` | 驗證指令（Phase 1 第 2 項）、B 系列參數（測試目錄、QA agent、工具）、A9 與 B5 的覆寫清單位置與檢查指令（Phase 1 第 11 項；有多工作樹時 A9 加填「開新工作樹時帶齊覆寫」，沒有本機覆寫時 A9 改寫為不適用）、C2 熔斷清單（Q2）；矩陣 D（Q8 選的經驗，一條一列附出處；Q8 沒問或都不要時整節刪除）；**不適用條款保留編號改寫為「本專案不適用：<理由>」，不刪列** |
| `skeleton-04-delegation-templates.md` | `<落點>/.claude/harness/04-delegation-templates.md` | 必讀清單（Q7；過時文件加「（過時：…，以程式碼為準）」）、模板五 pipeline（Q1；有既有治理層走 (A) 讓位版）、模板六參數、Q6 豁免行 |
| `skeleton-05-knowledge-protocol.md` | `<落點>/.claude/harness/05-knowledge-protocol.md` | 紅區清單（含既有治理層檔案、Q4 紅區語義）、健檢清單列出實際裝的 hook 與其 dry-run 輸入、§5.1 稽核工具表（Phase 1 第 2 項記下的掃描／稽核腳本與會說謊的東西；一支都沒有就寫「目前沒有」）；有裝 cbm-guard plugin 時保留「會說謊的東西」那一項的 cbm 新鮮度指令；參考模式原本健檢清單裡專案專屬的項目（跑某支掃描、看某個指標），照「原有設定的預設處置」搬進新清單，使用者要求「健檢時提醒我看」的項目標【使用者親自看】 |
| `skeleton-comment-guide.md`（僅 Q11 選「建」） | `<落點>/.claude/harness/07-comment-guide.md` | 適用範圍（Phase 1 第 1、3 項的語言與 repo）；第三節「編譯器或 linter 要求一定要寫 doc 註解時」的設定表照 Phase 1 第 6 項②盤點到的設定逐列填（檔:行、管哪些成員、本專案語言的局部關閉寫法；使用者同意過的整專案關閉也寫在這一欄），一個都沒有時保留設定表表頭（空表）、刪範例列，表下加一行「目前沒有強制寫 doc 註解的編譯器或 linter 設定；之後出現時補進本表」，「改完怎麼確認」那一行刪掉；第三節標題、說明、三種做法與表頭保留（N1、N6 與審查 agent 引用這一節，整專案關閉要記進這張表）；第四節真人範本只寫 Q11 使用者確認過的，一個都沒有時保留節標題與最後「共同特徵」那一段（第一節引用「第四節」），只把引言與範例列換成一行「尚未收錄；審查時看到好例子就補進來（黃區）」；第五節指紋樣式只留本專案用得到的語言，每條在本專案實跑過一次（命中數不寫進檔）；git-commit 沒裝就刪掉 N9 機械閘那一段 |

### 可執行層（hook）

| 來源（`../../hooks/templates/`） | 落點 | 填空重點 |
|------|------|----------|
| Q5 推導並經使用者確認的每支範本 | `<落點>/.claude/hooks/<同名>.js` | 檔頭「init 填空區」常數：照形狀目錄該列的「專案參數」欄填（agent 名單、副檔名與 repo 清單、容器路徑、`TRIGGER_MODE`、覆寫清單路徑…） |
| `guard-risky-command.js`、`guard-test-preconditions.js` | 同上 | `RULES`／`CHECKS` 陣列：Q5 推導出的每條 B 類規則。每條的樣式要用 Phase 1 **實際看到的**指令與值寫，不寫泛用猜測。專案有多個子專案（例：web／api）時，`CHECKS` 每條都要用 `when` 限定到真正需要它的子專案指令（寄信收斂只套 api 的測試、不套 web 的 vitest），否則會把無關的測試一起擋下。比對路徑的樣式，前導字元集要同時認 `/` 與 Windows 的 `\`（寫在 RULES 字串裡是 `[\\s/\\\\]`）——只寫 `/` 會漏掉 PowerShell 的 `.\deploy.ps1`。DB 登入照檔頭示範的三條規則（`db-unconfirmed-login`、`db-password-literal`、`db-conn-account`，三條都要裝）寫：把 `__DB_TEST_USER__` 整串取代成 U1 確認的測試帳號（regex 特殊字元要跳脫）、`__DB_TEST_PW_ENV__` 整串取代成放密碼的環境變數名——**只填變數名，hook 與 cases 都不准出現密碼值**（規則本身就擋所有字面密碼，密碼只能引用確認過的環境變數：Bash 用 `$變數`、`${變數}`（含 `PGPASSWORD="$變數"` 這類前綴），PowerShell 用 `$env:變數`、`${env:變數}`；`%變數%` 不可用（兩種 shell 都不展開），PowerShell 的 `$變數` 也不可用（是 PowerShell 自己的變數、送出去是空值））。不要改寫成「擋高權帳號名單」。cases 的 `db-login` variant 是填入示範值（`qa_reader`／`DB_TEST_PASSWORD`）的同三條規則，照同樣方式換成實際的帳號與變數名（案例指令裡的 `qa_reader`、`DB_TEST_PASSWORD` 一併換）。這三條規則不看主機——連哪台庫由 U1 確認過的主機另寫規則或文字約束 |
| `shell-model.js`＋`package.json`＋`package-lock.json`（裝了任一個規則引擎、或本機覆寫銷毀閘 `guard-local-hack-destroy` 時） | `<落點>/.claude/hooks/` | 不填空。複製後在 `.claude/hooks/` 跑 `npm ci`，把 `.claude/hooks/node_modules/` 加進 `.gitignore`（沒有就建）。`npm ci` 失敗（無網路、沒有 npm、平台沒有預編譯檔）**不擋 init**：兩支引擎會退回正則判法照樣運作，本機覆寫銷毀閘照改動前的判法（點名一般檔的 `restore`／`checkout` 也擋），在收尾回報寫明「語法解析器未裝、目前是正則判法」並附失敗原文 |
| QA 閘設定檔（裝了 `guard-qa-before-commit` 時；它的前提就是有 git-commit） | `<落點>/.claude/qa-gate.conf`（工作目錄根的 `.claude/`，與 `local-overrides.yml` 同一層——flow.sh 依序從 repo 目錄、主 repo 目錄（worktree 時）、工作目錄往上逐層找 `.claude/qa-gate.conf`，取第一個找到的，所以放在工作目錄層就能涵蓋底下所有 repo（repo 自己的 `.claude/` 有一份時會蓋過它）） | 這個檔是「什麼算行為類」的**唯一正本**：git-commit 的 `flow.sh review-record` 讀它（git-commit 0.11.0 以上；檔案不存在＝flow.sh 不檢查），`guard-qa-before-commit.js` 每次執行時也讀它（找法同 flow.sh：從 repo 目錄、其次專案根往上逐層找）——改這個檔兩邊一起生效，不必回頭改 hook。hook 填空區的 `BEHAVIOR_EXTS`／`EXCLUDE_PATTERNS` 只在找不到這個檔、或 `exclude` 有 hook 翻不成等價 JS 的寫法時當退路（翻不了會用 `additionalContext` 提醒，不擋），init 照樣依 Phase 1 盤點填同一份清單，免得退路跟正本差太多。三行 `key=value`：①`behavior_ext=`：Phase 1 盤點的行為類副檔名，帶點、空白分隔，比對檔名結尾、不分大小寫（例：`.js .ts .tsx .vue .cs .py`）；②`exclude=`：排除路徑，空白分隔的 ERE（比對 repo 內相對路徑，**區分大小寫**；要不分大小寫就把字母寫成字元類，例：`\.([Tt][Ee][Ss][Tt]\|[Ss][Pp][Ee][Cc])\.[A-Za-z]+$`；值裡不能有空白；只用 ERE 的基本寫法——字元類、`[[:alpha:]]` 這類 POSIX 類、`\<`／`\>`、跳脫標點；`\d`、`(?:…)`、非貪婪、反向參照這些 ERE 沒有或兩邊意思不同的寫法 hook 不猜，會退回填空區並提醒；例：`^tests?/ (^\|/)__tests__/ \.([Tt][Ee][Ss][Tt]\|[Ss][Pp][Ee][Cc])\.[A-Za-z]+$`——本表直線前的反斜線是 markdown 表格的跳脫，寫進檔案時拿掉，多寫反斜線會變成比對字面的直線、排除失效）；③`block_staged_overrides=`：裝了本機覆寫保護（形狀目錄第 16–18 列）時填 `1`（staged 混進覆寫清單上的檔就拒絕記錄，`--allow-overrides "<理由>"` 放行），否則 `0`。檔頭用 `#` 註解寫明：這個檔給 git-commit 的 flow.sh 與 `.claude/hooks/guard-qa-before-commit.js` 讀、作用是 commit 時要求 QA 表態、「什麼算行為類」改這裡就好。已有這個檔（參考模式、重裝）時先備份成 `qa-gate.conf.bak`（用 shell 的 `cp` 建——`.claude/` 根層的整潔檢查只放行允許清單上的檔名，Write 新建 `.bak` 會被擋），只補缺的 key，不改既有值（有出入的列進 Phase 2 核對表讓使用者決定）。 |
| git-commit 審查附加要求檔（0-5 判定有裝 git-commit 時；使用者選不裝就不產生） | `<落點>/.claude/git-commit-reviewer-addendum.md`（工作目錄根的 `.claude/`，與 `qa-gate.conf` 同層——git-commit 的 `flow.sh prepare` 讀 `CLAUDE_PROJECT_DIR`（沒設時是執行時的目錄）底下 `.claude/` 的這個檔；git-commit 0.10.0 起才讀，低於的版本照樣產生，更新後自動生效） | 純 Markdown、不要 frontmatter，內容是對 commit 前那位程式碼審查員（code-reviewer）說的話：`prepare` 最後整份原文印出，git-commit 逐字貼進審查 prompt 的【專案附加審查要求】。寫四段：①**機械掃描**：Phase 1 第 2 項與 code-reviewer「審查覆蓋紀律」第 1 點盤點到的 linter、analyzer、專案自己的規則掃描腳本——指令、在哪個目錄跑、適用哪個 repo 或哪類檔；多 repo 時分段寫明，不適用的 repo 寫「<repo>：<工具> 不適用，改照 <規範檔> 逐項審」②**逐筆裁決**：每筆命中裁決為違規／合規／不適用＋一句理由（命中不等於違規），違規的引規則出處，回報附掃描統計（命中幾筆、裁決為違規幾筆）；工具沒跑不能假設乾淨③**註解**（Q11 選「建」或「沿用」時）：「註解依 <註解規範路徑> 審：罐頭註解、空殼 doc、AI 參與痕跡列為缺陷；缺 doc 的警告只能建議改寫或局部關閉規則，不得要求補空殼」④**派工檢查要的字樣**：實例的 `check-review-discipline.js` 對 code-reviewer 另外加了 `REQUIRED_MARKERS` 時，把那幾個標記逐字寫進來——git-commit 的審查 prompt 是通用範本，少了這幾個字會被派工檢查擋下。①～④**任何一段**有內容就要產生——只有第④段（派工檢查要的標記）也要產生，否則 git-commit 的審查 prompt 少了那幾個標記會被派工檢查擋下；四段都沒有內容才不產生（`prepare` 會印「無」，審查 prompt 不帶這段）。寫進去的指令與路徑都要實際存在（Phase 5 驗）。已有這個檔（參考模式、重裝）時先用 shell 的 `cp` 備份成 `git-commit-reviewer-addendum.md.bak`（`.claude/` 根層的整潔檢查只放行允許清單上的檔名，Write 新建 `.bak` 會被擋），只補缺的段落、不改既有內容（有出入的列進 Phase 2 核對表讓使用者決定） |
| `probe-hooks.js`＋`cases/`（只複製有裝的 hook 對應的 cases）；裝了本機覆寫三件組任一支時連同 `restore-local-hacks.js` 與其 cases | `<落點>/.claude/hooks/` | **填空區改了什麼，cases 同步改**：agent 名單換了→案例的 subagent_type 換成實際名字；B 類規則填了→把範本 cases 裡注入示範規則的 variant 換成本專案實際規則，並為每條規則補一擋一放的案例（`broken-*` 開頭的 variant 不用換：它們把一條寫壞的規則插在規則表最前面，驗的是「規則故障時提醒模型看得到」，與實際規則無關） |
| Q9 選的覆寫清單欄位（裝了本機覆寫保護、Q9 有選時） | 覆寫清單本身（Phase 1 第 11 項記下的位置，預設 `.claude/local-overrides.yml`） | 先備份成 `local-overrides.yml.bak`（用 shell 的 `cp` 建——`.claude/` 根層的整潔檢查只放行允許清單上的檔名，Write 新建 `.bak` 會被擋）；在該筆 `- path:` 底下、**與 `path` 同一層縮排**加 `needed-when-file`＋`needed-when-contains`（成對）或 `requires`（好幾個字串時重複寫 `requires:`）——縮排更深或寫在 `reason: \|` 多行字串裡的不會被讀到。值裡有「空白＋#」時整個加引號（沒加引號時「空白＋#」之後視為註解）。只加欄位，不改既有的 `path`／`reason`（git-commit 的 flow.sh 也讀這份檔） |

**B 類規則的訊息怎麼寫**（`reason`／`fix` 是模型被擋下時唯一讀得到的東西，寫錯會把它帶去錯的方向）：

1. **理由寫這個專案的真實後果**：講被擋的東西實際會造成什麼（連到哪台主機、清掉哪張表、寄給誰），不要沿用別的專案或範本示範規則的理由。例：DB 登入規則的理由寫這台庫實際會發生什麼（連續登入失敗會鎖住哪台庫、誰會被卡住；用高權帳號連上還能刪掉哪些資料），不要照抄範本示範規則的句子。
2. **放行方式必須照做就能跑**：寫出的指令要在它說的位置真的執行得起來——不是只要過得了閘。Phase 1 查到的腳本問題（例如測試腳本在目前的執行環境跑不起來）要繞開，給能跑的寫法。
3. **不把機密值塞進指令列**：有環境檔就給 `node --env-file=<檔>`、`source <檔>` 這類載入寫法，不要叫模型把連線字串、密碼貼進指令（會留在指令列與對話紀錄）。
4. **Bash 與 PowerShell 都給**：Phase 0 看得到 PowerShell 工具的環境，每條放行方式都附 PowerShell 寫法。
5. **不寫引擎的盲點**：「分兩次呼叫就看不到」「用變數組就擋不住」這類已知極限寫進 hook 檔頭註解給維護者看，**絕不寫進 `reason`／`fix`**——寫進擋下訊息等於教被擋的人怎麼繞。
6. **只指向存在的東西**：放行方式提到的 skill、腳本、檔案，此刻都要存在（沒裝的 plugin 不寫成可用選項）；前提（單人或團隊、有沒有裝某 plugin）照 Q 的答案寫，不寫「別人正在用」這類與 Q4 不符的敘述。

**複製，不是引用 `${CLAUDE_PLUGIN_ROOT}`**：實例自治、使用者可自改；代價是 plugin 更新不自動同步（在 harness README 寫明）。複製後在 `<落點>/.claude/hooks/` 跑 `node probe-hooks.js`，**全數符合預期才往下走**；有裝規則引擎時看開頭那行是否為「語法樹路徑」，再跑一次 `node probe-hooks.js --parser=off`（正則路徑，解析器沒裝的團隊成員走的就是這條），要沒有 FAIL——標「只有語法樹路徑做得到」的案例是正則路徑的已知極限，略過並計數。

### agent 層（5 份＋變更紀錄）

| 來源（`references/agents/`） | 落點 | 填空重點 |
|------|------|----------|
| `skeleton-agents-CHANGELOG.md` | `<落點>/.claude/agents/CHANGELOG.md` | 每支實際建立的 agent 一節（`## <檔名>`），各記一行「建立」；Q1 裁掉的角色不留節。agent 檔本體不留 changelog 節（每次派工整份載入） |
| `skeleton-agent-backend-architect.md` | `<落點>/.claude/agents/backend-architect.md` | 專案名、分層方向、必讀清單；Q1 裁掉則不建 |
| `skeleton-agent-backend-engineer.md` | `<落點>/.claude/agents/backend-engineer.md` | 技術棧、硬性規則（引用規範檔條目標題＋路徑，不複製內文）、build 指令；併步裁切時改寫前置條件 |
| `skeleton-agent-frontend-engineer.md` | `<落點>/.claude/agents/frontend-engineer.md` | 技術棧、規範、i18n；無前端不建 |
| `skeleton-agent-qa-engineer.md` | `<落點>/.claude/agents/qa-engineer.md` | 依前端分類保留 (A)／(B)／(C) 其一；測試目錄與指令 |
| `skeleton-agent-code-reviewer.md` | `<落點>/.claude/agents/code-reviewer.md` | 規範來源、靜態掃描工具；**VERDICT 輸出格式不得改**（git-commit C 軌依賴它） |

參考模式照 Phase 2 定案的處置表做：「併入」的用骨架建、把原 agent 的專案專屬內容搬進硬性規則（每條註明出自原檔哪一節）；「沿用」的原檔不動。AGENTS.md 這類多工具治理層已定義角色時不建同名檔，只把 harness 需要的段落（交接契約、回報格式）以建議形式列在收尾回報，由使用者決定要不要合併。

### 知識容器層（3 份＋各自的變更紀錄）

| 來源（`references/containers/`） | 落點 | 填空重點 |
|------|------|----------|
| `skeleton-CONTEXT.md` | `<落點>/CONTEXT.md` | 專案名；**U3 使用者確認過的詞逐條寫成詞條**（照格式，≤2 句、只講是什麼），寫了真詞條就刪示範；沒確認的詞不寫——不替使用者編詞條。本體不留 changelog 節 |
| `skeleton-CONTEXT.changelog.md` | `<落點>/CONTEXT.changelog.md`（與 CONTEXT.md 同目錄） | 「建立」那一行照實際情況寫「init 時與使用者確認 N 條」／「沿用原有 M 條」／「示範詞條待第一個真詞條寫入時刪除」（可合併） |
| `skeleton-FLOWS.md` | `<落點>/FLOWS.md` | 模組單位（repo／服務／模組）；**不憑盤點畫鏈路**，只留示範。業務流程不放這裡（本檔只收踩過坑的跨模組鏈路），放 CLAUDE.md 專案概要。本體不留 changelog 節 |
| `skeleton-FLOWS.changelog.md` | `<落點>/FLOWS.changelog.md` | 建立日 |
| `skeleton-PROJECT.md` | `<落點>/tests/Project_Detail/PROJECT.md` | 「環境與執行」節填 Phase 1 查證事實＋U1 確認的測試環境位址（位址可寫，帳密一律寫「取自 <環境變數或設定鍵名稱>」）；其餘三節只留示範 |
| `skeleton-Project_Detail-CHANGELOG.md` | `<落點>/tests/Project_Detail/CHANGELOG.md` | `## PROJECT.md` 一節，記「建立」；該目錄之後拆出子檔時每個子檔各加一節 |

參考模式（含從 0.9.x 以前的 harness 實例升級）：原檔本體有 `## Changelog` 節的，整節搬進對應的變更紀錄檔，落點照 05 §4 與上面 Phase 4 各表（`.claude/harness/` 的 02～05 → `.claude/harness/CHANGELOG.md` 該檔那一節；`CLAUDE.md` → `CLAUDE.changelog.md`；`.claude/agents/*.md` → `.claude/agents/CHANGELOG.md` 該檔那一節；`CONTEXT.md`、`FLOWS.md` → `<檔名>.changelog.md`；`tests/Project_Detail/PROJECT.md` → 同目錄 `CHANGELOG.md` 的 `## PROJECT.md` 節），**一行都不能少、照原順序**，本體不留；05 舊 changelog 裡的【健檢執行】紀錄也一起搬進 `## 05-knowledge-protocol.md` 節，健檢提醒才接得上上次的日期。原本的知識筆記檔有真實條目（不是示範）時，**條目搬進新結構，一條都不能少**，示範條目才刪；唯一會改動原條目的是 U3 裁決過的衝突詞（照裁決改寫，或使用者說不用了就刪除）。寫完用 `grep -c` 各自的條目標記對帳：新檔條目數＝原有條目數＋U3 新增數－U3 裁決刪除數（`CONTEXT.md` 以外的檔新增與刪除都是 0），對不上就是漏搬或多寫。

### settings 層

| 來源 | 落點 | 內容 |
|------|------|------|
| 每支已裝 hook 檔頭的「接線」註解 | Q4 決定：`<落點>/.claude/settings.local.json`（單人）或 `.claude/settings.json`（團隊） | `hooks` 區接上每支 hook（PreToolUse matcher 照檔頭）；每一筆照檔頭帶上 `statusMessage`（hook 執行時狀態列顯示的白話說明，例：「檢查派工單的紀律欄位」——沒有它，使用者只看得到一個在跑的指令，不知道卡住的是哪一道檢查；目標專案要改措辭可以改，但不要留空）；Phase 0-4 缺的 `mcp__playwright__*` 補進 `permissions.allow`（僅瀏覽器可驅動時）。**既有 settings 檔先建 `.bak` 再以 JSON 合併寫回，不整檔覆蓋**；寫完 `node -e "JSON.parse(...)"` 驗格式。參考模式：處置為「沿用」的原有 hook 照原本的接線（事件、matcher、指令）保留；處置為「取代」的把原接線拿掉、只留 harness 版，免得同一件事被擋兩次 |

壓縮交接五支（形狀目錄第 26 列）掛四個事件：PreCompact 的 timeout 必須大於 `compact-handoff.js` 的 `CHILD_TIMEOUT`（範本為 240 秒對 220 秒，差距留給快照寫檔），否則交接信寫到一半被中止，兩者要一起調；`compact-reinject.js` 掛 SessionStart matcher `compact`，只在壓縮後注入；`resume-stale-reminder.js` 掛 SessionStart matcher `resume`，只在 resume 時判斷要不要提醒。

SessionStart 提醒由本 plugin 的條件式 hook 提供（偵測到 `.claude/harness/README.md` 才輸出），啟用本 plugin 的專案不必在 settings 重複加；未啟用本 plugin 的專案才在 settings 補一條 inline 提醒。

---

## Phase 5 — 驗收（兩層，任一項失敗＝init 未完成）

### 第一層：靜態十二項

```
□ 變更紀錄位置：CLAUDE.md、.claude/harness/ 各指令檔、.claude/agents/*.md、三個知識容器本體 `grep -n "^## Changelog"` = 0 命中；
  每份實際建立的檔都在它的紀錄檔找得到「建立」那一行（harness 檔與 agent 檔在各自 CHANGELOG.md 的 `## <檔名>` 節裡，
  CLAUDE.md 與 CONTEXT／FLOWS 在 `<檔名>.changelog.md`，PROJECT.md 在 tests/Project_Detail/CHANGELOG.md 的 `## PROJECT.md` 節）；
  `.claude/harness/CHANGELOG.md` 有 `## 05-knowledge-protocol.md` 節。裝了健檢提醒時在 <落點> 實跑一次
  `HARNESS_TODAY=<建立日加 31 天> node .claude/hooks/health-check-reminder.js`（PowerShell：`$env:HARNESS_TODAY='<日期>'; node .claude/hooks/health-check-reminder.js`；跑完 `Remove-Item Env:HARNESS_TODAY`）：
  要印出提醒，且「紀錄來源」是 CHANGELOG.md 的 05 節——印的是 05 本體＝節標題寫錯、提醒讀到舊位置
□ grep "{{" 於所有實例檔（文件層、agent 層、容器層、hook 檔）= 0 命中（無殘留填空；hook 檔的「init 填空區」常數已填）
□ grep 污染詞表 = 0 命中（詞表＝本 plugin 的 skills/init/pollution-wordlist.txt；
  指令見 adaptation-guide §4.1；命中逐筆判斷：目標專案查證過的事實可留，骨架漏進來的來源事實要清；changelog 出處標註除外）
□ 實例內引用的路徑逐條 ls 存在（含路由表、必讀清單、指向既有治理層的路徑、settings 裡的 hook 指令路徑；有 07 註解規範時含它第三節設定表的檔:行；有 `.claude/git-commit-reviewer-addendum.md` 時含它寫的每支掃描工具與規範檔路徑）。
  有 addendum 時另實跑一次它真的會被印出來（git-commit 低於 0.10.0 時標「不適用：git-commit 版本低於 0.10.0」）。**本項用自己的暫存目錄，跑完就刪；不要與下面 qa-gate 那一項共用**——`prepare` 會拒絕 index 裡已有清單外 staged 項目的 repo，共用的話 qa-gate 那一項的 `prepare` 會 exit 1。做法：在 scratchpad 底下另建一個暫存目錄當 `<暫存根>`，形狀照下面 qa-gate 那一項的規定（與 hook 填空區的 `REPOS` 一致；`<R>` 的意思同那一項），在（子）repo 裡建一個檔並 `git add`，把 addendum 複製到 `<暫存根>/.claude/`，設 `CLAUDE_PROJECT_DIR=<暫存根>` 跑 `bash <flow.sh> prepare <R> <該檔>`——要 exit 0，輸出最後要出現「C 軌專案附加審查要求」那段標記，且內容與檔案逐字相同（印「無」＝放錯層或檔名錯）；貼原始輸出，跑完刪這個暫存目錄。Windows 上的 `bash` 要用 Git Bash：PATH 上的 bash 可能是 WSL，flow.sh 在 WSL 裡讀不到 Windows 路徑；用 `"<Git 安裝目錄>/bin/bash.exe"`，或在 Claude Code 的 Bash 工具裡跑。`<flow.sh>` 的取法同下面 qa-gate 那一項
□ 03 矩陣 B 寫入的每條驗證指令，指令本體實際存在（腳本檔在、npm script 有定義、測試目錄在）
□ 每個實例檔 Read 回檔尾確認未截斷；每支 hook `node --check` 通過；settings JSON 可解析
□ 在 <落點>/.claude/hooks/ 跑 `node probe-hooks.js`：全數符合預期、沒有「缺 cases」（這是行為層，前幾條只是結構層）；
  有 `.claude/qa-gate.conf`（git-commit 低於 0.11.0 時標「不適用：git-commit 版本低於 0.11.0」）另實跑一次 flow.sh 的 QA 閘——
  probe-hooks 只測得到 hook，權威檢查在 flow.sh，要在它身上證明。用暫存目錄（scratchpad 底下，不污染目標專案的審查紀錄）：
  **暫存目錄的形狀要跟 hook 填空區的 `REPOS` 一致**——`REPOS` 是 `['.']`（單一 repo）就在暫存目錄本身 `git init`；是 `['web', 'api']` 這類多 repo 就在暫存目錄底下照名字各建一個子 repo（都要 `git init`），下面「那個檔」放進其中一個子 repo。以下用 `<暫存根>` 指暫存目錄本身、`<R>` 指 flow.sh 的 repo 參數：單一 repo 時 `<R>` 是 `.`；多 repo 時 `<R>` 是放了那個檔的子目錄名（例 `web`），檔案路徑一律寫成相對 `<R>` 的路徑（例 `a.js`，不是 `web/a.js`）。形狀不一致的話 hook 會去查不存在的子 repo、看不到 staged，驗收必然失敗，那不是 hook 壞了。
  複製目標的 qa-gate.conf 到暫存目錄的 `.claude/`，在（子）repo 裡建一個符合 behavior_ext 的檔並 `git add`，
  設 `CLAUDE_PROJECT_DIR=<暫存根>`（多 repo 時也是暫存根，不是子 repo——設成子 repo 的話 hook 找不到 REPOS 裡的子目錄而放行，flow.sh 也會找錯路徑）後依序跑 `bash <flow.sh> prepare <R> <該檔>`（Windows 上的 `bash` 要用 Git Bash：PATH 上的 bash 可能是 WSL，flow.sh 在 WSL 裡讀不到 Windows 路徑；用 `"<Git 安裝目錄>/bin/bash.exe"`，或在 Claude Code 的 Bash 工具裡跑——它本身就是 Git Bash）、`bash <flow.sh> review-record <R> --exempt "harness-probe"`
  ——要被拒（exit 非 0，訊息是「必須帶有效的 --qa 表態」）；同一行加 `--qa "已QA：harness-probe"` 再跑——要寫入紀錄（exit 0）。
  同一個暫存目錄（那個檔仍在 staged）再對 `guard-qa-before-commit.js` 餵一次 Skill payload（`{"tool_name":"Skill","tool_input":{"skill":"git-commit"}}`，不帶 --qa-verified），
  **同樣要設 `CLAUDE_PROJECT_DIR=<暫存根>`**（hook 從它找專案根與 repo；沒設的話 hook 在目標專案的 `.claude/hooks/` 底下，會把目標專案當成專案根、看的是目標專案的 staged）：
  要擋（exit 2），而且擋下訊息的「行為類的判準來自」是那份 qa-gate.conf 的路徑——證明 hook 與 flow.sh 讀的是同一份判準；寫成「填空區」就是沒讀到。
  block_staged_overrides=1 時再補一組：`<暫存根>/.claude/local-overrides.yml` 照 git-commit 的格式列一個檔（頂層 key 自取、`repo: <R>`——單一 repo 寫 `.`，多 repo 寫那個子目錄名，寫成 `.` 會對不到子 repo 而不擋、`files:` 底下 `- path: <相對 <R> 的檔案路徑>`），
  在 `<R>` 裡 stage 它、重跑 `prepare <R> --staged` 與帶 --qa 的 review-record——要被拒（訊息是「staged 含 local-overrides 清單上的檔」），加 `--allow-overrides "harness-probe"` 才寫入。
  `<flow.sh>` 用目標專案實際載入的那份（installed_plugins.json 該筆的 installPath 底下 `skills/git-commit/flow.sh`）；貼每次的原始輸出，跑完刪暫存目錄（這一項的暫存目錄與上面 addendum 那一項各自獨立）
□ 有裝規則引擎：probe-hooks.js 開頭那行要是「語法樹路徑（Bash 與 PowerShell 解析器都已載入）」；
  `node probe-hooks.js --parser=off` 也要沒有 FAIL（標「只有語法樹路徑做得到」的案例會略過並計數）；在 <落點>（專案根目錄，不是 .claude/hooks）跑
  `node -e "const s=require('./.claude/hooks/shell-model.js');console.log(s.available('Bash'),s.available('PowerShell'))"`
  印 `true true`（任一個 false＝該文法沒裝上，對應的指令走正則判法，回報寫明）；`git check-ignore .claude/hooks/node_modules` 有輸出（不會被 commit 進去）
□ B 類每條規則的「放行方式」若是可照抄的指令：①以同一個 hook 餵回去必須放行 ②在它說的位置實際執行一次（唯讀或無害的才實跑；有副作用的只驗①並在回報裡註明）——過得了閘卻跑不起來的放行方式，照上面「訊息怎麼寫」第 2 點改寫。另掃一次 `reason`／`fix` 不得出現「看不到」「擋不住」「限制」這類引擎盲點字樣
□ 專案理解落地：CLAUDE.md 有「專案概要」節，用途、外部系統環境表（沒有外部系統時是一行「無」）、業務流程、目前進度四塊都在，且跟 Phase 2 使用者改過的版本與 U1、U2 答案一致（逐句對，不抽樣）；CONTEXT.md 這次新增的詞條數＝U3 確認新增的詞數（無人值守＝0，概要標「未經使用者確認」）；參考模式原有的真實條目另外照下面參考模式那一項對帳（總數＝原有＋新增－裁決刪除）；環境表有「方向」欄，U1 使用者答的每一個入向（對方主動打進來的）都在表上；U1 的每一個外部系統都有去向：正式與「不確定」的寫入動作在 Q2 候選裡出現過，測試環境的有對應的「位址不是測試環境就擋」規則或文字（無人值守時「待問」的照正式環境對）；CLAUDE.md 與 PROJECT.md 沒有帳密（grep 連線字串裡的 `://帳號:密碼@`、`Password=`、`pwd=`、`token=` 這類樣式要 0 命中，只准出現環境變數或設定鍵的名稱）；Q7 選進必讀的過時文件，在 04 的【開工前必讀】、CLAUDE.md 路由表、agent 的開工前必讀都有「（過時：…）」註記
□ 形狀目錄逐列對帳：每一列都有「已裝／不裝＋理由／由 plugin 提供」三者之一；B 類每個 Q2 勾選項、每條標了自動檢查的 Q8 條款都對得到一條規則；
  裝了本機覆寫保護時，Q9 選的每一筆都在覆寫清單裡寫上了對應欄位，並在 <落點> 跑一次 `node .claude/hooks/restore-local-hacks.js`（檢查模式、不改檔）貼原始輸出——
  needed-when 條件不成立的那幾筆要出現在「目前這個 checkout 用不到」，不能出現在「不見了」
□ 參考模式（非參考模式標「不適用」）：①備份與原檔逐檔 hash 一致（在 Phase 4 動檔之前比，Phase 5 再比一次備份本身沒被動過）②Phase 2 處置表逐列對帳：「併入」與取代時搬過去的專案事實，內容在新檔找得到（grep 原句的關鍵詞）；「沿用」的原檔 hash 未變、接線還在；「取代」的原接線已拿掉 ③知識筆記檔條目數：新檔＝原有真實條目數＋U3 新增數－U3 裁決刪除數（`CONTEXT.md` 以外的檔新增與刪除都是 0），原有條目逐條找得到（U3 裁決改寫過的找改寫後的版本；裁決刪除的在收尾回報列得出來） ④原有 CLAUDE.md 的每條規則都在處置表上有去向（逐節對，不抽樣） ⑤Q8：03 矩陣 D 的列數＝Q8 選的條數，每列有出處；標了自動檢查的，對得到一條規則且 `probe-hooks.js` 有它一擋一放的案例；原本在 CLAUDE.md、升格進 D 的條款，新 CLAUDE.md 對應的節留一行指向 `03 D<n>`（Q8 沒問時標「不適用」） ⑥**經驗帶走審查**（不同判準的兜底）：另派一支 fresh-context subagent（`opus`），**不給它第 12 項的清單**，只給備份路徑、路由表指到的原文件路徑、這次新產生與修改的檔案清單；prompt 要帶「搜尋限定目標目錄、禁止全碟掃描」。它從舊文件那一側逐段讀，用第 12 項同一個語意判準認出每條經驗，再到新設定裡找它還在不在：在→寫出新檔名與行號（沿用原位的文件也算，要在新 CLAUDE.md 路由表或必讀清單上找得到）；不在→列為「沒帶到」。回報格式：一條一列「經驗原文｜出處｜新設定裡在哪／沒帶到」，全部附出處，不准只給數字。主對話拿它的清單跟第 12 項清單互比：只有一邊有的逐條回原文判斷。**Q8 使用者明確選了不帶的經驗，出現在「沒帶到」裡是預期結果**：標「你選了不帶」，不重問、不算缺漏、不擋 init 完成。其餘「沒帶到」的每一條：屬於專案事實的回 Phase 4 補進新檔；屬於要不要升格的，攤給使用者決定（等同補問 Q8）。補完再派一支新的 subagent 重審，最多兩輪，第二輪仍有沒帶到的就停下，把清單交給使用者。審查的原始回報貼進收尾回報
```

### 第二層：冷啟探針（新開 session 實測，不是讀設定檔推論）

hook 設定在 session 啟動時載入，當前 session 看不到剛寫進去的 hook——**必須在目標目錄起一個新 session 實測**。做法：在目標 workspace 根跑 headless 子程序（cwd＝目標目錄），把探針指令交給它，讀它回來的原文判定：

```
cd <目標> && claude -p "<探針 prompt>" --output-format text
```

（無法起子程序的環境：請使用者在目標目錄開新 session，貼上探針 prompt，把回覆原文貼回來。）

| # | 探針 | 探針 prompt 要點 | PASS 判準 | 前提 |
|---|------|------------------|-----------|------|
| P1 | **故意派不帶 model 的 agent，看有沒有被擋** | 「用 Agent tool 派 subagent_type=`<pipeline 內任一專案 agent>`、prompt＝`<探針基底 prompt>`，**不要帶 model 參數**。把工具回傳的原文完整貼出。」 | 回傳原文含 `[02-model-dispatch §1]` 的 deny 訊息，且沒有出現 `PROBE-OK`。**只看到派工紀律閘的訊息不算**——那代表基底 prompt 沒帶齊欄位，要修 prompt 重跑，不是 PASS | 有裝 check-agent-model |
| P2 | **派正常 agent，看有沒有誤擋** | 同上（同一份基底 prompt），但**帶 `model: "sonnet"`** | 回傳含 `PROBE-OK`，且沒有 deny 訊息 | 有裝 check-agent-model |
| P3 | **SessionStart 提醒有沒有出來** | 「你這個 session 開始時，context 裡有沒有一段以 `[harness]` 開頭的提醒？有的話逐字貼出，沒有就回答『沒有』。」 | 回覆逐字貼出 `[harness] 本專案有制度層 .claude/harness/…` | 無 |
| P4 | **git-commit 攔不攔得住裸 git commit（兩種殼都要）** | 探針前先記 `git -C <repo> rev-parse HEAD`。prompt：「先用 Bash、再用 PowerShell 各執行一次 `git commit --dry-run --allow-empty -m harness-probe`，把兩次工具回傳原文完整貼出。」（沒有 PowerShell 工具的環境只跑 Bash） | 兩次回傳原文都是 hook 擋下的訊息（非 git 自己的輸出），且探針後 `rev-parse HEAD` 與探針前相同。**多 repo 工作區**：對每個子 repo 各跑一次，指令改成 `git -C <子 repo> commit --dry-run --allow-empty -m harness-probe`，每個子 repo 各記前後 HEAD | 0-1 是單一 repo 或多 repo 工作區，且有裝 git-commit plugin |
| P5 | **B 類規則的接線是真的**（Claude Code 真的會對 Bash／PowerShell 叫 `guard-risky-command`） | 每條規則造一條**就算沒被擋也無害**的觸發指令：在命中規則樣式的前提下加 `--help`／`--version`／`--dry-run`，或指向不存在的主機、不存在的檔案。prompt：「用 Bash 執行 `<無害觸發指令>`，把工具回傳原文完整貼出。」 | 回傳原文為 guard-risky-command 的擋下訊息 | 有裝 guard-risky-command 且至少一條規則造得出無害形式；**造不出無害形式的規則不准拿來冷啟**（只靠 probe-hooks 驗行為），在回報裡寫明 |

- **探針基底 prompt**（P1／P2 共用）：「只回覆 PROBE-OK」加上該 agent 在 `check-review-discipline.js` 的 `REQUIRED_MARKERS` 裡要求的每個標記（共用的回報鏈鐵則、【驗收條件】、【回報格式】、【開工前必讀】與它要寫到的必讀檔名，加上該 agent 自己的欄位），每欄寫一句最小內容即可——【驗收條件】要寫一條實際條件（例：「回覆是 PROBE-OK」），只放標題會被擋；QA agent 的【測試資料來源】第一行寫「選 a：探針不造資料」（該格會驗有沒有明選）；實作與 QA agent 的【開工前對齊】寫「無分岔：探針」，QA 的【目標環境】【既有測試分流】各寫一句（例：「本機」「新 TC：探針不跑測試」）；不要帶【計畫／設計文件】（帶了會打開那份檔驗章節）。P1 與 P2 之間**唯一的差別是有沒有帶 model**——一次只變一個變因，否則 P1 被擋時分不出是哪支閘擋的。沒裝 check-review-discipline 時基底就是「只回覆 PROBE-OK」。
- 用 `--dry-run` 是為了**探針失敗時也不會真的建 commit**。
- 前提不成立的探針標「不適用：<原因>」，不算失敗；**前提成立卻沒跑＝未完成**。
- 任一 FAIL → 回 Phase 4 修（常見原因：settings 接線路徑錯、`$CLAUDE_PROJECT_DIR` 沒展開、hook 檔名不一致、agent 名單沒填對），修完**整組重跑**，不是只重跑失敗那項。
- 探針的原始輸出貼進收尾回報（證據紀律：只寫「探針通過」不算）。

---

## Phase 6 — 流程圖：裝了什麼、之後一個需求進來會怎麼跑

**為什麼有這一步**：只給檔案清單，使用者看完仍不知道裝了這些之後，下一個需求進來會發生什麼事、每個東西在哪一步起作用（實際回饋：「裝完之後沒有告訴我裝了些什麼」）。所以收尾前畫流程圖，三條硬規則，都由 `scripts/check-flow-diagram.js` 機械檢查：

1. **要畫的清單不是寫死的，是 init 實際動過的檔案**：Phase 0 拍的快照對比現況，新增、修改、刪除的每個檔案都要是某張圖上的一個節點（`label` 含它的名字）。只寫在卡片、線上文字或 sublabel 都不算——卡片是圖外清單，看不出在哪一步（實際回饋：「不應該寫死，要看有新增或更改的檔案」「不是說所有的檔案嗎」）。
2. **每個節點都要有線**，線上標關係：讀、寫、擋、觸發、載入。只擺節點不拉線，看不出它跟流程的關係（實際回饋：「知識筆記裡面讀跟寫的流程也都沒有畫出來」）。
3. **拆成三張圖放同一頁**：全部檔案加上全部關係塞進一張圖，實測 29 處線交叉、線穿過別的節點，讀不出來。

### 1. 找 archify（跑 CLI 驗活，不看目錄在不在）

依序試 `~/.claude/skills/archify`、`~/.agents/skills/archify`，對每個路徑跑 `node <路徑>/bin/archify.mjs doctor`，**exit 0 才算可用**（目錄在但 Node 版本不符或檔案不全時照樣跑不動）。

找不到或都不是 exit 0 → **不准自己裝**，問使用者，四件事一次講完：這是什麼（第三方的流程圖產生工具 tt-a1i/archify，MIT 授權、免費）、為什麼要它（有格式檢查與真瀏覽器量測，比手刻可靠）、裝了會動到什麼（連網下載、寫進 `~/.claude/skills/`，不動這個專案）、不裝會怎樣（改成在終端機給流程表，內容一樣完整，只是沒有圖）。他說要才跑 `npx skills add tt-a1i/archify -g`，裝完再跑一次 doctor。他說不要、或無人值守 → 走第 6 步的退回做法。

### 2. 先列清單，再寫三張圖的 JSON

先寫一個只有 `{"nodes":[],"edges":[]}` 的暫存 JSON，跑一次 `check-flow-diagram.js check <落點> <那個暫存 JSON>` 拿到「init 之後的變動」清單（它會全部列成缺項，這就是要畫的清單）。清單裡有不該留下的殘檔（測試產物、暫存檔）→ 刪掉，不要畫上去。

每個檔案的關係要**查證後才畫**：讀它的是誰、在哪一步（讀 agent 檔的「開工前必讀」、CLAUDE.md 路由表、hook 檔頭的接線與填空區常數），寫它的是誰、在哪一步。查不到就不畫那條線，並在收尾回報說明。

落點：`<落點>/.claude/harness/flow-1.json`～`flow-3.json`，產出 `flow-1.html`～`flow-3.html`，再組成 `flow.html`（路由表要列 `flow.html`）。格式：archify `workflow`、`schema_version: 2`、`meta.quality_profile: "showcase"`、`meta.locale: "zh-CN"`（archify 只收 `en`／`zh-CN`；節點文字照樣寫繁體中文，只有圖例與按鈕會是簡體，這是 archify 的限制）。結構範例見 `references/example-flow-1.json`～`example-flow-3.json`——**只抄結構，內容一律換成這次實際的檔案與查證過的關係**。

| 圖 | 泳道（由上往下） | 放什麼 | 線 |
|---|---|---|---|
| **圖一：需求進來之後怎麼跑** | 自動檢查（擋主對話，`variant: "exception"`）／主對話（含你提出需求、你簽收）／agent 角色／自動檢查（擋 agent，`exception`） | 主線：需求 → 對齊 → 派工 → 第 1 題定案的每支 agent → 收尾。**每支 agent 只畫一個節點、名字照實際裝的檔名**：同一支做兩步（例：architect 併入 engineer 時，engineer 先寫設計、你同意後再寫程式），用「設計給你看」「同意後寫程式」一來一回兩條線表示，小字寫它做哪幾步；畫兩個同名節點，讀者會以為專案裡有兩個角色（實際回饋：被看成有後端架構師）；每支**會擋人的** hook 放在它擋的那一步的上方或下方；最下方加一條「收尾時更新的文件」泳道，放 CLAUDE.md（小字「專案概要：流程狀態與進度」） | 主線箭頭；步驟 → hook 標「擋」（`variant: "security"`、`role: "error"`）；結束那一步 → CLAUDE.md 標「寫：更新專案概要」（做完一條業務流程時更新流程狀態與進度；畫在圖一是因為圖二的讀取線已經很密，實測加這條線排不出不交叉的版面） |
| **圖二：文件在哪一步被讀、被寫** | 規則文件（Claude 會讀）／流程步驟／知識筆記（讀＋寫）／記憶 | 步驟一列：開 session、對齊、派工、設計＋實作、實測、收尾（不做的步驟拿掉）；CLAUDE.md、harness/README.md、02～05 放在讀它的那一步上方（有 07 註解規範時一起放，讀它的是設計＋實作那一步；`.claude/git-commit-reviewer-addendum.md` 放在收尾那一步上方，線上寫「讀：commit 前審查」）；CONTEXT.md、FLOWS.md、`tests/Project_Detail/` 底下每個檔放在讀它的那一步下方 | 文件 → 步驟標「讀」（`variant: "dashed"`）；步驟 → 文件標「寫」（`variant: "emphasis"`）。**知識筆記讀和寫都要畫**：誰在哪一步讀、誰在哪一步寫，分開兩條線。**專案理解的產出也要畫出它在哪一步被用到**：CLAUDE.md 專案概要 → 確認需求（判斷需求落在哪條流程、碰不碰正式環境），線上寫「讀：專案概要」；→ 交代工作那一步（實作與測試工作的必讀清單都有它），線上寫「列進必讀清單」（收尾更新專案概要的寫入線畫在圖一）；CONTEXT.md → 確認需求，以及骨架「開工前必讀」有列它的 agent（照實際裝的 agent 檔查，沒列的不畫）；PROJECT.md → 測試那一步（節點小字寫「測試環境位址」，線上寫「讀」就好，長的線上文字容易讓排版擠出交叉）。節點小字寫這次實際寫進去的內容（例：「3 系統、5 條流程」「8 個你確認過的用語」；小字太長 archify 會判讀不清而不給過，寫短），無人值守時寫「未經你確認」 |
| **圖三：背景自動執行與維護工具** | 設定／觸發時機／背景自動執行／讀寫的資料／維護 | settings 檔；開 session、resume、壓縮前、壓縮後這些時機；不擋人的 hook 與它載入的模組；它們讀寫的東西（專案外的就註明「專案外」）；健檢時跑的 probe-hooks 與 `hooks/cases/` | 時機 → hook 標「觸發」；hook 之間標「載入」；讀寫同圖二的畫法 |

參考模式另把沿用的原有 agent、hook、指令、skill 畫進它所屬的那張圖，sublabel 標「原有」。

限制：
- 同一張圖裡，同一個檔案（agent、hook、文件）只能有一個節點；完整性檢查會擋。
- 一條泳道同一欄只能有一個節點，最多六個；放不下就再開一條泳道，不准合併節點或移到卡片。
- 檔名一律完整寫出。archify 預設節點寬 92px，檔名放不下時 validate 會回報「Label … is wider than node」，這時給該節點設 `width`（約：英數字每字 7px、中文每字 14px，再加 24px），**不准縮寫檔名**。
- 一群用途相同的檔（例：`hooks/cases/` 的測試案例）可以畫成一個目錄節點（label 以 `/` 結尾），sublabel 寫份數；各有作用的檔不准用目錄節點帶過。
- 先不要手寫 `via`、`channelX` 這類座標，驗證報錯再照它給的修法改。

### 3. 驗證與產出（三張各跑一次）

```
node <archify>/bin/archify.mjs validate workflow <flow-N.json> --quality showcase --json
node <archify>/bin/archify.mjs deliver  workflow <flow-N.json> <flow-N.html> --quality showcase --json
node <archify>/bin/archify.mjs visual-check <flow-N.html> --json
```

- validate 有錯就照回報的 `supportedFixes` 修，連續兩輪錯誤數沒有減少就停，照實回報沒修掉的診斷。**線交叉（`composition/proper-crossing`）要靠調整節點所在的欄與泳道消除，不准降成 `standard` 品質來過關**。
- **`deliver` exit 非 0＝沒產出**，不准說成功。
- visual-check 唯一可接受的診斷是 `viewer/viewport-overflow` 且 `overflowX` 為 false（頁面要往下捲）；其他診斷都要修。記下它在 1440 寬回報的 `scrollHeight`（pass 時記 900），組頁要用。
- 組成同一頁：`node <本 plugin>/skills/init/scripts/flow-page.js <落點>/.claude/harness/flow.html "<專案名>：裝了什麼、需求進來怎麼跑" flow-1.html:<高度> flow-2.html:<高度> flow-3.html:<高度>`
- **每張圖都截圖親自看過**：`chrome --headless=new --window-size=1600,1300 --screenshot=<png> file:///<flow-N.html>`。主線看得出順序、檔名完整沒被截斷、每條讀寫線看得出從哪到哪，才算數。

### 4. 完整性檢查（不同判準的兜底，這步沒過不准收尾）

```
node <本 plugin>/skills/init/scripts/check-flow-diagram.js check <落點> <落點>/.claude/harness/flow-1.json <落點>/.claude/harness/flow-2.json <落點>/.claude/harness/flow-3.json
```

腳本不看圖怎麼畫，而是拿 Phase 0 的快照對比現況，列出 init 之後新增、修改、刪除的每個檔案（排除 `.git/`、備份、流程圖本身、測試快取；`node_modules` 收成一項），逐項確認它是三張圖其中一張的節點 label；另外檢查每個節點都至少有一條線。exit 1 會列出缺哪些 → 補節點或補線（殘檔就刪）→ 重跑第 3 步與這一步，直到 exit 0。腳本輸出原文貼進收尾回報。

### 5. 交付前易讀性自檢（流程圖與收尾回報都要過）

讀者是第一次用 harness 的人。流程圖上的每一句話（標題、泳道、節點小字、線上的字）與收尾回報，都要讓他不用開口問就看得懂（實際回饋：流程圖寫「派工缺欄位」，第一次用的人根本不知道是什麼意思）。規則依據是 deliver-report plugin 的易讀性鐵則。

```
node <本 plugin>/skills/init/scripts/readability-check.js <落點> <落點>/.claude/harness/flow-1.json <落點>/.claude/harness/flow-2.json <落點>/.claude/harness/flow-3.json <落點>/.claude/harness/install-report.md
```

- **exit 3＝這個專案看不到可用的 deliver-report**（沒裝，或被停用）：跳過這一步，照腳本印的那段話在收尾回報告訴使用者「這次沒做易讀性自檢，要裝的話輸入 `/plugin install deliver-report@fulin-plugins`」（Claude 不能代裝）。不准因為沒裝就卡住 init。
- **exit 1**：逐項改。內部用語換成腳本給的說法；節點小字放不下說明就改寫整句，不准用「（見圖二）」這類叫讀者去別處找的寫法。改完**整份重跑**，不是只重跑被點到的那一處。
- **exit 0 之後還沒完**：腳本會印出它判不準的幾條（兩邊對照、資訊放一起、重複、做完寫成做完…）。**先把它印出的規則檔全文讀完**，再對三張圖與收尾回報逐條自檢，改到的地方重跑第 3 步的 deliver。
- 內部用語清單在 `plain-language-terms.json`，是本檔「對使用者講話的寫法」對照表的機械可讀版；使用者再指出看不懂的詞，兩邊一起加。
- 沒有 archify、改用 Markdown 流程表時，把指令裡的三個 flow-N.json 換成 `flow.md`。
- 範圍：流程圖三張（或 `flow.md`）＋收尾回報。寫進專案的制度文件（CLAUDE.md、02～05、agent 檔）是給 Claude 照做的規則，本來就用內部用語，不在這一步的範圍。

### 6. 給使用者看

- 有 archify：用系統預設瀏覽器打開 `flow.html`（Windows `start "" <路徑>`、macOS `open`、Linux `xdg-open`；無人值守時不開，只給路徑）。
- 沒有 archify：寫一份 Markdown 流程表到 `<落點>/.claude/harness/flow.md`，一樣分三節對應三張圖；每一列是一步，欄位是「步驟｜誰做｜讀了哪些檔｜寫了哪些檔｜被哪支自動檢查擋｜觸發了什麼」，每個變動檔都要以完整檔名出現在它那一步；第 4 步的完整性檢查改對這份檔跑，同樣要 exit 0。

### 收尾回報（誠實條款，缺一不算完成）

先寫成檔案 `<落點>/.claude/harness/install-report.md`，過完上面第 5 步的易讀性自檢，再把同樣的內容貼給使用者（之後他也能回頭看這份檔）。下面八段（參考模式九段）；寫給使用者時照「對使用者講話的寫法」，段名可以直接用下面的粗體字。**第 1、2 段放最前面**——使用者最想知道的是「之後會怎麼跑」與「裝了什麼」，驗收證據往後放。

1. **之後一個需求進來會怎麼跑**：先給流程圖的路徑（說明已經在瀏覽器打開）；接著在終端機寫一段 5～8 步的文字版，每步一行：誰做、讀了哪些檔、寫了哪些檔、哪個自動檢查在這一步擋什麼、卡住時會怎樣；背景與維護另寫兩三行。**圖打不開也要看得懂**，每個檔名都要出現在它那一步。最後一句講「完整性檢查：init 新增 N、修改 M、刪除 K 項，每一項都是圖上的節點、每個節點都有線」，附腳本輸出。
2. **裝了哪些東西**：逐檔列出路徑，每個檔附一句用途，分新增／修改／刪除。**項目要和完整性檢查腳本列的變動清單一致**（腳本列幾項，這裡就是幾項；修改的寫出改了什麼）。接著列「我替你做的決定」：拿掉了哪些角色、沿用了你們哪些既有規範、哪些是我先決定的（無人值守時，剛才盤點推導出的預設全列在這裡，註明「你可以推翻」）。
3. **驗收證據**：靜態檢查十二項逐項結果、「開新 session 實際試擋」五項的原始輸出、流程圖完整性檢查與易讀性自檢的腳本輸出（易讀性自檢被跳過時，寫明是因為沒裝 deliver-report，並附安裝指令）。
4. **你已經有的**：
   - CLAUDE.md 的專案概要（用途、外部系統哪些是正式哪些是測試、業務流程、目前進度），確認需求時先讀它，交代任何角色（架構、實作、測試、審查）工作時都列為必讀；`CONTEXT.md` 有 <N> 個你確認過的專案用語（逐個列出）。無人值守時寫明「概要是我讀文件推的，還沒經你確認」，並列出等你確認的候選詞
   - 一套開發流程：各角色的分工與順序（列出來）、固定跟著流程走的三條規則、43 條判斷規則（什麼時候該停下來換方法、怎樣才算做完、哪些動作要先問你；參考模式另加 Q8 升格的 <N> 條本專案經驗條款）、派工範本、記錄踩坑的規則
   - <N> 項會真的擋下來的自動檢查，每項一句講它擋什麼；危險指令檢查逐條列出各自對應的風險。<N> 個 agent 角色（名稱加中文職稱）
   - **各角色交給哪個模型**：一張表，每個 agent 一列，欄位是「角色｜做什麼｜預設模型｜什麼時候改用 opus」，照 02 對照表實際填的寫；下面一句講判斷依據（02 的四項進階判準，任兩項成立就用 opus）與「沒指定模型會被哪支自動檢查擋」。實際回饋：裝完使用者要自己問「工作交給哪個模型？怎麼判斷的」，看到表才發現寫規格的角色被套成 sonnet
   - 註解規範（第 11 題的答案）：建了就寫路徑與它管什麼（寫為什麼不寫做了什麼、不補空殼 doc、不留 AI 參與痕跡），並列出你確認過的範本註解；沿用就寫沿用哪份；不建就寫「只有 agent 檔裡的基本原則」。有產生 commit 前審查的附加要求檔時，一句講它讓審查員多做哪幾件事
   - 沒有裝的自動檢查逐項列出與原因：用不到／你取消的／要另裝某個 plugin／要等專案有了某個工具才用得到
   - 三份知識筆記檔（`CONTEXT.md` 詞彙表、`FLOWS.md` 跨模組流程、`PROJECT.md` 測試知識）與收錄原則，照實寫每份目前有幾條真實條目（這次確認的用語、參考模式沿用的條目、盤點實跑寫進的測試知識），沒有的才寫「只有示範」
5. **你還沒有的**（照實列，不要美化）：
   - **踩坑經驗**：分兩種情況寫，不寫「0 條」這種讓人以為少了東西的說法（實際回饋：使用者看到「踩坑知識 0 條」以為是缺陷，要自己推回「那是要讓它從專案的規矩長出來吧」）。
     - 一般模式：「這套規則照 harness <版本> 產生，是通用的開發流程；這個專案自己的踩坑紀錄還沒開始累積（memory、`FLOWS.md`、`PROJECT.md` 的踩坑段落只有示範條目）。之後每踩一次坑就記下來，同一類坑第二次出現就照 `05-knowledge-protocol.md` 的升格流程寫成正式規則。」
     - 參考模式：「規則文件與自動檢查已照 harness <版本> 重新產生。你原本規矩裡的經驗共 <總數> 條：照預設處置帶過去 <A> 條（在哪個檔），升格 <N> 條進 `03-judgment-matrix.md` 的「本專案經驗條款」（其中 <M> 條加了自動檢查），你選了不帶的 <K> 條留在 <哪裡>（逐條列）；經驗帶走審查的結果：<除了你選了不帶的 K 條，沒有其他沒帶到的／還有哪幾條沒帶到、為什麼>；知識筆記檔沿用原有 <N> 條。」照實數，Q8 沒問就寫原因
   - **回歸測試 0 支**（init 不寫測試）<若 Phase 1 盤點到既有測試，寫「既有測試 N 支，還沒照這套流程檢視過」>
   - 每個模組測到哪裡的登記、專案專屬的檢查腳本、針對過去事故寫的規則——照實寫：沒有就寫沒有；參考模式沿用了原有的自動檢查或事故規則，列出沿用了哪幾項。
   - harness 帶進來的規則是通用版本：裡面的數字與範例還沒被本專案真實發生過的問題校正過（沿用的原有規則不在此限）。
6. **之後怎麼讓它越用越貼合**：
   - 每次踩坑 → 照 `05-knowledge-protocol.md` 的「踩坑紀錄格式」記進 memory；同一類坑第二次出現 → 照同一檔的「升格協議」提議寫進正式規則，能自動檢查的就一起做成自動檢查
   - 每次 commit（非 git 專案、或你選了不裝 git-commit 時改成：每個有改檔的回合結束）→ 會問你四個問題（這次有沒有新名詞、新的跨模組流程、新的測試知識、自創的縮寫），答案記進知識筆記檔
   - 每次改到程式行為 → 補一支可以重跑的自動測試
   - 每 30 天 → 跑 `/harness:review` 做一次制度健檢（開機時會提醒）。三軌：它自己檢查制度有沒有被照做、逐項跑 05 健檢清單與本專案的稽核工具；另外會請你在提示列輸入 `/doctor`（看工具鏈）和 `/insights`（看使用習慣），三軌結果交叉比對。可逆的修正（重建過期索引、清過期 memory、修明顯的 hook 錯誤…）列成一批讓你一次核可，當場修完逐項驗證；改規則的仍一項一項問你
7. **在哪裡開 session 才有效**：自動檢查只在設定所在的那一層目錄開 session 時生效。在子 repo 裡開 session，`CLAUDE.md` 仍會被讀到（上層目錄的也會讀），但 workspace 根的自動檢查不會跑。
8. **盤點發現的專案本身問題**（文件寫的指令其實不存在、沒有測試、敏感檔沒被 `.gitignore` 擋）照實回報，不略過。
9. **原本的設定怎麼處理了**（僅參考模式）：
   - 備份位置與還原方式（「整份原樣在 `.harness-backup/<時間>/`，要還原就把裡面的檔案複製回原位」）
   - Phase 2 處置表的最終版（使用者改過的照改過的寫），每列附「處理後在哪裡」
   - **第 0 題的每個痛點逐一交代**：這次靠哪個東西解決（寫出檔名或自動檢查名）；沒解決的照實說沒解決、為什麼、之後怎麼補。不准只寫「已改善」
   - 舊規矩的經驗去向：每一條寫出目前的位置——帶進的新檔與行號／03 矩陣 D 的編號與怎麼擋／Q8 沒選、出處檔沒動而留在原位的文件路徑／Q8 沒選、出處檔被取代或併入而只剩 `.harness-backup/<時間>/` 裡的檔案路徑；附經驗帶走審查的原始回報
   - 原有 `.claude/` 裡沒動的殘檔清單，由使用者決定去留