git:20260930.2f8cb6a to git:20260930.d813c04

# DD Pipeline — Claude Code 自動化開發流程

可攜式 Claude Code 設定庫，透過 `install-dd-pipeline.sh` 安裝到 `~/.claude/` 全域。

## 安裝 / 更新

```bash

./install-dd-pipeline.sh # 首次安裝

./install-dd-pipeline.sh --force # 更新：差異檔覆蓋（內容相同不重寫）；全域 CLAUDE.md 跳過詢問直接覆蓋（先備份）

./install-dd-pipeline.sh --check # 只檢查環境

./install-dd-pipeline.sh --uninstall --yes # 免確認解除安裝（自動化；非互動環境的詢問一律採預設值）

```

> 從舊版（全量部署 / 分桶時期）升級、既有專案升級到 8 步迴圈：見 [UPGRADING.md](UPGRADING.md)。

環境檢查（步驟 1 / `--check`）除必要工具外含**可選項 ffmpeg**：tech-diagram-gif 的

GIF 匯出用，缺少時警示並附安裝指令（brew / apt），該 skill 退化交付 SVG。

只偵測提示、不代裝系統套件。

## 部署清單（使用率盤點制）

repo 只保留**有實證使用紀錄**的元件（2026-08-04 盤點留存 9 skills、4 agents、

dd-init、workflow-review；2026-08-10 新增自製 tech-diagram-gif，實證來源為當次

對話的完整管線驗證；2026-09-30 新增只有 hook 的 gate-guard —— 它是 gate 的防護、不是「用過才收」的

元件，是這條規則唯一的例外），全部預設部署；清單定義在 `install-dd-pipeline.sh` 頂部的

`PROMOTED_*` 陣列。

- 歷次盤點刪除（git 歷史可回溯）：deprecated 桶（全歷史 0 次使用的 34 skills /

17 agents / 6 dd 指令 / 13 NS commands）與 misc 桶（SRE 備援性質但零實際調用的

11 skills / 5 NS commands）均於 2026-08-04 刪除；取回方式

`git checkout pre-prune-2026-08-04 -- skills/<名字>` 後加回陣列

## 目錄結構

- `skills/` — 11 個 Skills（全數部署；除了 gate-guard，每個子目錄含 SKILL.md 定義檔；writing-great-skills 為 vendored 自 mattpocock/skills 的 skill 撰寫參考、tech-diagram-gif 的風格規範 vendored 自 fireworks-tech-graph；gate-guard 是只有 hook、沒有 skill 的 plugin，擋 Claude 用 `--no-verify` 繞過 gate，見 `skills/gate-guard/hooks/CLAUDE.md`）

- `agents/` — 4 個 Agents（code-simplifier、code-reviewer 官方備份 + senior-devops、security-auditor）

- `commands/` — 1 個 dd-* 指令（dd-init，.md 平面檔） + 1 個命名空間 command 目錄（workflow-review）

- `templates/global/` — 全域 CLAUDE.md 模板（經互動比對部署到 `~/.claude/CLAUDE.md`）

- `scripts/` — 輔助腳本（部署清單由 `install-dd-pipeline.sh` 頂部的 `DD_SCRIPTS` 陣列決定，部署到 `~/.claude/scripts/`；含 check-claude-md.sh pre-commit gate 與本 repo 自用的 `githooks/`，後者不部署）

- `diagrams/` — 兩份 README 嵌的 6 張 GIF（使用流程、8 步迴圈、大工作怎麼跑 × 中英），另有 tech-diagram-gif

各風格的示範 GIF（2026-09-07 加入）；每張的來源與重出方式見 `diagrams/src/CLAUDE.md`

（改來源再重出，勿手改 GIF）。

三層架構圖於 2026-08-31 移除 — 它畫的是目錄清單而非架構，資訊都在

`DD_PIPELINE_ARCHITECTURE.md` 的文字版裡，還多一份圖要維護

- `tests/` — CI 在 ubuntu 與 macOS（bash 3.2）都跑的測試：gate 情境 `test-gate.sh`、安裝端到端 `test-install.sh`；**不部署**，也不在 `scripts/*.sh` 那個 glob 內

- `install-dd-pipeline.sh` — 安裝腳本（部署到 ~/.claude/；唯一安裝路線，分享亦同）

## 新增 Skill 步驟

1. 在 `skills/<skill-name>/` 建立 `SKILL.md`

2. 在 `install-dd-pipeline.sh` 的 `PROMOTED_SKILLS` 陣列加入名稱，並**同批**同步：兩份 README 的

Promoted Skills 表格與標題數字、README 安裝步驟裡的「N 個 promoted Skills」、本檔「目錄結構」

那行的總數。CI 的「數字宣稱一致性」會擋，漏改要等 push 才發現

3. 部署前先乾跑（新增或改寫都要）：派 subagent 照 repo 裡這份 `SKILL.md` 做一遍，逐條引用原文回報哪一句讓它卡住、

只能用猜的、或兩句互相矛盾。skill 有分支就每條各跑一次（例如有沒有設計文件）；只讀的步驟拿實際在用的專案跑、

不准寫檔；會寫檔或 commit 的步驟改在 scratchpad 的拋棄式 repo 真的跑，跨 session 的流程再派一個只讀專案文件的

agent 接手做完，結果用指令核對，不看 agent 自述。2026-09-11 改寫 task-planner：只讀乾跑抓到二十多處；沙盒實跑

又抓到只讀看不出來的，例如 gate 在目錄同時有 staged 變更與 SKIP 欠帳時只印 staged 的理由，照訊息補會漏

4. 執行 `./install-dd-pipeline.sh --force` 部署

5. 動到 description 或觸發條件時，裝好後測「會不會自己叫」—— 同一個 session 裡推論不算數，要開全新的：

在拋棄式專案裡跑 `claude -p "<需求>" --output-format stream-json --verbose --max-budget-usd 3 --no-session-persistence

--permission-mode dontAsk --allowedTools "Skill Read Glob Grep" --disallowedTools "Edit Write NotebookEdit Bash Agent"

< /dev/null > out.jsonl`，正反各一個（該叫的大需求、不該叫的小改動），解析 jsonl 看有沒有 `Launching skill:`，

並確認 `permission_denials` 是空的 —— dontAsk 沒加 `--allowedTools Skill` 會把 Skill 擋掉，只證明它「想叫」。

prompt 存成 `<名字>.prompt.txt` 放在 jsonl 旁邊，不然事後核對不了「不含關鍵字」這種說法；每次約 US$0.4–1.6。

這種 session 沒有寫檔工具也沒有 AskUserQuestion，只測得到「叫不叫、出不出得了草稿」，批准之後的步驟要另外在沙盒實跑。

2026-09-11 task-planner：三個功能的需求叫起了，一行字的改動沒叫，已有進度表、說「照設計文件繼續做」也沒叫

6. 只有 hook、沒有 skill 的元件也放 `skills/<名字>/`（`.claude-plugin/plugin.json` + `hooks/hooks.json`，不放 SKILL.md），

會以 `<名字>@skills-dir` 載入（gate-guard，2026-09-30 用 `claude -p` 實測）。測 PreToolUse 擋不擋時，`--allowedTools` 要放行

被管的工具（例如 `Bash`），被 hook 擋下的呼叫才會在 tool_result 以「PreToolUse:Bash hook error: <理由>」出現、並列進 `permission_denials`

### Skill hook 路徑規範（強制）

skill 若含 `hooks/hooks.json`，其中 `command` **必須**用可在任意 cwd 解析的路徑：

- ✅ `$HOME/.claude/skills/<skill-name>/hooks/xxx.sh`

- ❌ `./hooks/xxx.sh`（hook 以「當前工作目錄」為基準執行，換到別的專案就找不到腳本）

安裝腳本的 `validate_skill_hooks()` 會在部署前掃描所有 `hooks.json`，發現相對路徑即**中止部署**。

引入第三方 skill（vendor）時尤其注意：上游常用相對路徑，併入前先改寫（完整收編流程見下方「第三方 Skill / Agent 收編檢查清單」）。

## 新增 Agent 步驟

1. 在 `agents/` 建立 `<agent-name>.md`（frontmatter 含 `name`、`description`、`model` —

自製 agent 用 `inherit`；官方備份（code-reviewer / code-simplifier）維持上游的 `opus`，不要改齊）

2. 在 `install-dd-pipeline.sh` 的 `PROMOTED_AGENTS` 陣列加入名稱，並**同批**同步兩份 README 的

promoted Agents 數字與本檔「目錄結構」那行的總數（CI 的「數字宣稱一致性」會擋）

3. 執行 `./install-dd-pipeline.sh --force` 部署

4. 若 agent 被某個 wrapper skill 調用，確認該 skill 的 Task `subagent_type` 先試 `<name>:<name>`（plugin 命名空間）再 fallback `<name>`（本地）

## 新增 Command 步驟

- 平面指令：在 `commands/` 建立 `<name>.md`，並更新 `install-dd-pipeline.sh` 頂層的 `DD_COMMANDS` 陣列

- 命名空間指令：在 `commands/<namespace>/` 建立 `.md` 檔案，並更新 `install-dd-pipeline.sh` 頂層的 `NS_COMMANDS` 陣列

- 平面指令的檔名**必須 `dd-` 開頭**：CI 的陣列一致性用 `ls commands/dd-*.md` 掃，非此前綴的檔案掃不到，

本機安裝正常、push 才紅燈，而訊息只說「陣列與實際目錄不一致」，很難聯想到是檔名前綴

- 兩種都要**同批**同步本檔「目錄結構」那行的數字（`N 個 dd-* 指令`、`N 個命名空間 command 目錄`）——

CI 的「數字宣稱一致性」逐項比對這兩個數字（`ci.yml:120-125`），漏改要等 push 才紅燈

## 新增 Script 步驟

1. 在 `scripts/` 建立 `<name>.sh`（必須通過 `shellcheck -S warning`，且可在 macOS bash 3.2 執行）

2. 加入 `install-dd-pipeline.sh` 頂層的 `DD_SCRIPTS` 陣列 —— 漏加的話 `create_scripts()` 不會部署它，

使用者機器上 `~/.claude/scripts/` 根本沒這支腳本（gate 就住在這一層）。CI 的

「陣列與目錄一致性」有第五組 `DD_SCRIPTS ↔ scripts/*.sh` 會擋

3. 加進 `.github/workflows/ci.yml` 的 ShellCheck 檔案清單 —— **那份清單是逐檔寫死的**，沒加等於完全不檢查。

同批更新 `DD_PIPELINE_ARCHITECTURE.md` CI 防線表裡寫死的「shellcheck（warning 級，N 支腳本）」

4. 執行 `./install-dd-pipeline.sh --force` 部署

> `scripts/githooks/` 是本 repo 自用、不部署，也不在 `scripts/*.sh` 這個 glob 內。

> 撰寫腳本本身的規矩（bash 3.2 相容、變數緊貼全形字要寫 `${var}`、改了 gate 要故意改壞一行驗證）

> 見 `scripts/CLAUDE.md`「此層慣例」，那份是腳本內容的單一維護來源；這一節只管「怎麼讓它被部署與被檢查」。

## 核心工作法：8 步開發迴圈

骨幹是經實際專案實戰驗證的功能段落迴圈

（定義於 `templates/global/CLAUDE.md` §3.9，專案具體版由 `/dd-init` 蓋章）：

```

實作+測試 → commit → code-simplifier → code-review → 再測(curl/playwright) → commit

→ 沉澱本輪所學 → 評分&修正

```

第 7、8 步的細則（範圍怎麼算、發現怎麼分類、何時可跳過）見全域模板 §3.9。

本 repo 是這兩步的 dogfood 來源：2026-08-31 先在這裡實跑 4 次，抓到 2 個真錯誤

（`diagrams/src/CLAUDE.md` 漏寫 `gen_usage.py` 不產 html、第 8 步條文自己用了

在該時機為空的 `git diff --cached`），驗證可行後才推進全域模板與 `/dd-init`。

要跨好幾段的工作由 `task-planner` 拆成段落與小任務：小任務只走步驟 1、2，全部 commit 完，整段才跑 3–8，

進度表連同規則區塊照抄進專案的設計文件。照抄進去的那份不會跟著 skill 更新 ——

改了 `skills/task-planner/SKILL.md` 的規則區塊，已經在用的專案手上仍是舊版。

搭配巢狀 CLAUDE.md 堆疊維護（依賴 `claude-md-management` plugin，安裝腳本管理），

並由 **pre-commit gate 強制**（block 版）：`scripts/check-claude-md.sh` 部署到

`~/.claude/scripts/`，`/dd-init` 掛進專案 `.git/hooks/pre-commit`（專案設有

`core.hooksPath` 時改掛該目錄，見下方「開發本 repo」）— 改碼目錄缺

CLAUDE.md 或未同批更新即擋 commit；檢查點 commit 逃生口 `SKIP_DOC_CHECK=1`。

SKIP 不是豁免：段落起點以來跳過、還沒補 CLAUDE.md 的目錄，之後的正常 commit

（就算沒改程式碼）一樣擋；細節見 `scripts/CLAUDE.md`。

> **舊 DD Pipeline（已刪除）**：`/dd-start → /dd-arch → /dd-approve → /dd-dev → /dd-test`

> 多階段流程於 2026-07-23 依使用率盤點（全歷史 0 次使用）封存、2026-08-04 刪除，

> 檔案與舊版 dd-init 見 git 歷史（如 `git show pre-prune-2026-08-04:commands/dd-dev.md`）。

## 開發本 repo

- clone 後啟用 CLAUDE.md gate（dogfood，本 repo 吃自己的 pre-commit）：

```bash

git config core.hooksPath scripts/githooks

```

（`core.hooksPath` 設定後 `.git/hooks/` 會被 git 忽略；`/dd-init` Phase 3

會偵測此設定並改掛到 hooksPath 目錄，兩者不衝突）

- gate 規則與逃生口（`SKIP_DOC_CHECK=1`）同各專案：改 `.sh` 等程式碼檔時，

該目錄的 CLAUDE.md 必須同批更新

- 記段落起點、取範圍都用 repo 這份：`scripts/check-claude-md.sh --start-segment` /

`--segment-base`（全域模板寫的是 `~/.claude/scripts/` 那份）。本 repo 的 hook 跑 repo 這份，

其他專案的 hook 跑部署那份；安裝腳本不帶 `--force` 也會覆蓋部署那份，gate 還沒驗證完

別跑安裝，驗證完 commit 後再重跑，其他專案才會用到新版

- 要在 Claude 的 Bash 工具裡取用安裝腳本的函式或陣列，一律 `bash -c 'source ./install-dd-pipeline.sh && validate_skill_hooks'`：

Bash 工具是 zsh，沒有 `BASH_SOURCE`，腳本尾端的 source guard 會失效，整支安裝直接在真實 `~/.claude` 上跑起來（2026-09-30 踩過）

- 架構總覽（分層、部署清單、安裝行為保證、CI 防線）見 `DD_PIPELINE_ARCHITECTURE.md`

## 注意事項

- 所有回應和註解使用繁體中文

- Commit message 使用繁體中文

- 此專案是 source of truth，全域 ~/.claude/ 的內容由安裝腳本從此專案部署

- 修改 skills / agents / commands / **scripts** 後務必同步更新 install-dd-pipeline.sh 的部署陣列

（`PROMOTED_SKILLS`、`PROMOTED_AGENTS`、`DD_COMMANDS`、`NS_COMMANDS`、`DD_SCRIPTS`；五組 CI 都會擋不一致）

- skill / command frontmatter 的 `allowed-tools` 是**該輪的免確認預授權**，不是工具白名單。

官方文件：「It does not restrict which tools are available: every tool remains callable」，

要真的拿掉工具得用 `disallowed-tools`，而且預授權在使用者下一則訊息後就失效。

所以漏列**不會**讓步驟執行不出來，只會多一次權限詢問；只有當該 skill 內文寫著

「不詢問，直接執行」時才構成矛盾，嚴重度是 minor。2026-09-12 稽核時 4 個 agent 同時誤判過

- README 有英文（`README.md`，GitHub 預設顯示）與繁中（`README.zh-TW.md`）兩份，**內容須同批更新**。

CI 對兩份都驗數字宣稱與 Promoted Skills 表格，正規式為語言無關（`.github/workflows/ci.yml`）。

CHANGELOG.md 與 UPGRADING.md 維持純繁中，英文 README 連向它們時須標註 *(Traditional Chinese)*。

README 變英文不改變本專案的註解語言 — 專案 CLAUDE.md（衝突順序第 3 位）優先於

全域模板 §1.1 程式碼註解列的「跟隨 README 語言」（第 5 位）；回應語言在 §1.1

本就固定繁中，與 README 語言無關

- 查 `~/.claude.json`（MCP）與 `~/.claude/settings.json`（plugin 啟用狀態）務必

真正解析 JSON，**不可用字串 grep** — 前者同時存放所有專案的 scoped 設定，純比對會把

別的專案的設定誤判為已安裝；後者的 `enabledPlugins` 是 `{key: bool}`，**停用是

「鍵在、值為 false」**，grep 只看得到鍵在（實測 `ralph-wiggum` 值為 `false` 卻被舊版

回報「已啟用」）。兩者各有專屬 helper：`mcp_scope()` 與 `plugin_enabled_state()`，

同為 jq → python3 → 退化標示無法判定

- 檢查類輸出的鐵則：**不確定就說不確定，不可退化成有把握的斷言**。`mcp_scope()`

區分 `none`（確定沒有）／`unparseable`（檔案損毀，無從判定）／`unknown`（缺 jq

與 python3，只有字串證據）；jq 與 python3 兩條路徑須逐項等價（型別護欄要對齊），

否則同一台機器裝不裝 jq 會得到不同結論

- `OFFICIAL_PLUGINS` 新增項目前先確認該 plugin 的 `.claude-plugin/plugin.json`

**有沒有 `version` 欄位** — 官方 `skill-creator` 就沒有（marketplace 與 cache 兩份都沒有）。

缺 version 時 `install_plugins()` 改讀 `installed_plugins.json` 裡 Claude Code 自己記的值

（它填內容雜湊，如 `85cce0381e78`）；**不可自行編版本號**，`installPath` 是用它組出

cache 路徑，編錯會指向不存在的目錄。兩處讀取都要**型別護欄（只接受 JSON 字串）** —

少了它 `"version": null` 會讓 jq 印 `null`、python3 印 `None`，後者繞過守衛，

正是本檔上一條「兩路徑須逐項等價」的典型破口。代價是這類 plugin 必須先手動

`claude plugin install <name>@claude-plugins-official` 過一次，安裝腳本才登記得起來 —

README 兩份的「必要條件」段落須註明此限制

- `~/.claude.json` 只涵蓋官方 `user` 與 `local` 兩種 scope；`project` scope

（專案根目錄 `.mcp.json`）不在其中，任何以此檔為據的檢查都會低報，文件須註明

- 增刪 `REQUIRED_MCP` / `OPTIONAL_MCP` 時要**手動**同步**兩份** README 的 MCP 表格 —

CI 驗的陣列一致性只涵蓋 skills / agents / commands / scripts（`DD_SCRIPTS ↔ scripts/*.sh`

於 2026-09-12 補上），數字宣稱只驗 skills / agents / commands；MCP 表格會靜靜過期。

**CI 不驗、只能手動同步的區塊**（不寫總數 — 沒窮舉過，寫個數字只會變成下一個過期宣稱）：

兩份 README 的安裝步驟清單、指令一覽、官方 Plugins、第三方 Plugin 推薦、MCP 必要表、

MCP 可選表、前置需求段落、MCP 退化狀態表、**CLAUDE.md 維護規則那幾條**（含 `--no-verify` 與 gate-guard 那條）、**「為什麼要巢狀」

底下的 gate 對策段落**、**散文裡的「8 步／8-step」字樣**（四方只數圍欄內的編號項、

第五方只認箭頭行與安裝腳本輸出，標題與內文的步數字樣五道防線一道都碰不到；要改步數時自己

`grep -c '8 步' README.zh-TW.md` 與 `grep -c '8-step' README.md` 數一遍，**不要在這裡寫死數量** —

上一版就在這個括號裡寫了「各 9 處」，跟本條自己的「不寫總數」直接打架）、

**「核心工作法」的迴圈說明段與 task-planner 段**、**授權段的 vendored 清單**；

以及 `DD_PIPELINE_ARCHITECTURE.md` 的 **CI 防線表**與**授權清單**。

（該檔的**數字**已於 2026-09-12 納入 CI：元件數、安裝編號步驟數、shellcheck 腳本數

四項都在「數字宣稱一致性」裡比對，不再屬於手動區塊。）

**觸發時機**：動到部署陣列、MCP、plugin、CI step、**gate 行為**、**迴圈步數或 §3.9 文案**、

**收編新的 vendored 元件**時，逐項巡一遍

- **安裝選項**已有 CI 防線：flag 三方對照驗「腳本 case 分支 ↔ `--help` 輸出 ↔

兩份 README 指令範例」名稱完全一致，新增/刪除 flag 忘了同步文件會被擋。

只驗 flag **名稱**，各 flag 的**語意描述**仍是手動維護

- 腳本開頭是 `set -e`，所以**回非 0 是正常結果**的指令單獨成行會中止整個安裝，

而且中止點之後的步驟全部不執行、使用者只看到安裝突然結束。最常見的三個是

`diff`（內容不同回 1）、`grep`（無匹配回 1）、`cmp`；一律補 `|| true` 或放進管線

（管線取的是**最後一個**指令的結束狀態 — 但這只在腳本**沒有** `set -o pipefail` 時成立，

目前 repo 的腳本都沒開；哪天有人補上，管線這條逃生口就失效，屆時只剩 `|| true`）。2026-09-12 踩過：全域 CLAUDE.md 互動選單的

`s) 顯示完整 diff` 分支裡 `diff` 單獨成行，選 s 就中止，講好的第二次詢問永遠問不到；

同一函式上面的 `diff "$target" "$source" | head -30` 反而沒事，正是因為在管線裡。

`bash -n` 與 `shellcheck -S warning` 都驗不出這種錯，要靠隔離重現（帶 `set -e` 跑一次）。

**最危險的變體是 `n=$(grep -c ...)`**：零命中時 `grep` 回 1，指令替換把這個 1 帶給賦值，

`set -e` 當場中止，而且**連一個字都不印** — 沒有錯誤訊息、沒有半截輸出，

看起來就跟「這段檢查跑完了、沒事」一模一樣。所以「先確認抓到東西非空、再計數」

這個順序有承重，不可為了整理而對調（`ci.yml` §7.2 那兩道護欄即此形狀，註解已標明）

- **迴圈步數**已有 CI 兩道防線。**四方一致**（全域模板 §3.9 ↔ `/dd-init` 蓋章版 ↔

兩份 README 清單 ↔ `dd-loop-version` 標記）只數**編號清單**；**第五方**（2026-09-04 補）

管它看不到的兩類使用者可見文案 — ①安裝腳本印出的「N 步開發迴圈」（排除註解行，

那裡是有日期的歷史敘述）②一行式箭頭摘要（合併續行後，箭頭 ≥3 且同時含 commit

與 review 才認定；CHANGELOG／UPGRADING 為歷史敘述故排除）。兩次踩雷都是靜默失效

不報錯：2026-08-31 迴圈 6→7→8 時標記停在 `6step`（舊專案跑 `/dd-init` 會被誤判為

最新）、README 清單漏補一項；2026-09-04 在第五方範圍內抓到 9 處殘留，其中

`DD_PIPELINE_ARCHITECTURE.md` 那處是人工逐檔翻完仍漏掉、靠檢查腳本才抓到的

- **動到 `commands/dd-init.md` 的蓋章區塊（三個反引號圍起來、開頭是 `## 開發流程` 的那一整塊）

就必須同步跳 `dd-loop-rev`** — 兩處，用 `grep -n 'dd-loop-rev' commands/dd-init.md` 找

（Phase 1 的判定式與蓋章標記；**不要在這裡寫行號**，2026-09-12 才因為同一份檔案加了兩行，

讓原本寫的 `:51` 指到 code fence 起始行），外加 `UPGRADING.md` 寫死的 rev 值與 CHANGELOG 未發布區塊。

**界線**：蓋章區塊 = 三個反引號 `markdown` 圍起來的那一整塊，用

``grep -n '^```' commands/dd-init.md | head -2`` 取得起訖行；Phase 0–6 的執行指示在區塊外，

改它們不必跳 rev。注意上面那個 `dd-loop-rev` 的 grep **不能**拿來夾範圍 ——

它的第一個命中（Phase 1 判定式）本身就在區塊外。Phase 1 的判定是「rev 等於現行值 → 已是現行版，跳過」，

不跳號的話已蓋章的專案永遠拿不到這次修正，跑 `/dd-init` 還會被告知「已是最新」。

CI 只驗 dd-init.md 檔內 rev 前後一致（種類數 == 2），**不驗「內容改了 rev 有沒有跳」**，

UPGRADING.md 那份 CI 根本不看。2026-09-12 踩過：同一輪前面已有一個 commit 動過蓋章區塊沒跳號，

靠 code-review 才抓到

- **新增 `.github/workflows/ci.yml` 的檢查 step 必做負面測試**：故意把被檢查的來源改壞一行，

確認該 step 真的紅燈，再還原確認回綠。`scripts/CLAUDE.md` 只對 gate 訂了這條規矩、

ci.yml 其他 step 沒有 — 而 2026-09-12 新增的兩道護欄，修的正是「抓 0 筆卻印綠燈」。

- **subagent 回報的行號可能整組對不上，要拿它引的原文 grep 定位後才動手**：2026-09-12

code-simplifier 對一份只有 263 行的 `README.md` 報 `README.md:323`，而它描述的內容

逐條屬實。行號錯得離譜反而好認，錯個三五行才危險 — 一律以原文比對為準，不信行號。

**它回報的「數字」同理**：要寫進文件的量測值（字級、案例數、幾處誤報）一律自己重跑一次再寫。

同日踩過：reviewer 說產生器的 `.ttl` 是 40，照抄進 `diagrams/src/CLAUDE.md`，

實測三支產生器**根本沒有 `.ttl`**；同一段我另外抄的三組溢出數字倒是全對 —— 所以不能靠感覺挑

- **在規則文件裡加「例外條款」時，要掃同一份檔案裡所有把該規則寫死成指令的地方**：

用 `<佔位符>` 描述的段落會自動套用新例外，**把指令逐字寫死的那一段不會**。

2026-09-12 踩過：全域模板 §3.9 前言加了「有進度表時 `<起點>` 改用表上那個起點」，

步驟 3、4 因為寫 `<起點>` 所以自動生效，只有步驟 8 把 `base=$(… --segment-base)` 寫死，

照抄就拿到被往後推的窄範圍 —— 同一節自己打架，而且沒有任何檢查抓得到。

判準：改完拿該規則涉及的**指令字串**去 grep（本例是 `--segment-base`），逐處確認要不要跟著改

- `OPTIONAL_MCP` 只收 **MCP server**（會註冊進 `~/.claude.json` `mcpServers` 的東西）；

plugin 形式的工具（如 claude-mem，`npx claude-mem install` 走 hooks + plugin 系統）

列進去檢查會**永遠回報未安裝**，應改列 README 的「推薦第三方 Plugin」段落

- 可選 MCP 推薦名單比照使用率盤點制：上游 deprecated／改名（如 cipher → byterover-cli，

2026-08-11 移除）或本機實際使用紀錄已斷即移除；後繼品未經實證使用不自動遞補

## 第三方 Skill / Agent 收編檢查清單（vendor intake）

> 引入任何**非自製來源**（GitHub repo、Claude marketplace、舊版安裝包）的 skill/agent 前，逐項過。**任一項不過 → 先改寫或不收**，不得直接併入部署陣列。

| # | 檢查項 | 怎麼驗 | 不過的處置 |

|---|---|---|---|

| 1 | **授權相容** | LICENSE 存在且相容（MIT/Apache 可；GPL/未標需評估）。frontmatter 若寫 `license: … LICENSE.txt`，該檔**必須同目錄存在** | 補齊 LICENSE 或移除懸空 frontmatter |

| 2 | **hook 路徑絕對化** | grep `hooks/hooks.json`，`command` 路徑須以 `/`、`$HOME/`、`~/` 或 `${CLAUDE_PLUGIN_ROOT}` 開頭（validator 會先剝掉 `bash`/`node` 等直譯器前綴再判斷）；相對路徑（`./`）不合格。詳見上方「Skill hook 路徑規範」 | 併入前改寫（`validate_skill_hooks()` 也會擋） |

| 3 | **事實驗證（不只 CLI）** | 任何靠名稱推論不出來的東西都要實跑證實：`npm install` / CLI args / 套件名（`npm view <pkg>` 或官方 README），以及**路徑算式、編碼規則、目錄命名**（實際跑一次拿真實輸出對照）。2026-09-12 踩過：self-improving-agent 五處 `%2F` 編碼算出的記憶體目錄從來不存在，收編時沒人跑過一次 | 無法證實 → 不收 |

| 4 | **runtime 依賴** | 讀 SKILL.md / scripts，確認是否需 Python / Node / 全域 binary | 需額外 runtime → 違反「不塞二進制」，不收或改純設定 |

| 5 | **跨平台冪等** | 無硬編碼絕對路徑、無單一 OS 假設，重跑安裝結果一致；設定與狀態分離 | 不冪等 → 改寫 |

| 6 | **撞名 / 重疊** | 與既有 skill 比 `description`，功能不重複、命名不衝突（避免污染如下節「殘留清理」所述） | 重疊 → 評估取代或不收 |

| 7 | **納管** | 全過後：加進 `install-dd-pipeline.sh` 的 `PROMOTED_*` 部署陣列 → **同批**同步兩份 README 的 Promoted Skills 表格與數字、本檔「目錄結構」的總數、`DD_PIPELINE_ARCHITECTURE.md` 的元件數字、以及三處授權段的 vendored 清單 → 跑 `--force` → 納入 source of truth | — |

> **典型踩雷**（實際評估）：某第三方 UI/UX skill 需要 `npm -g` 安裝的 binary 外加 Python runtime，

> 第 3、4 項直接擋下。**不收的理由只寫「它不符合本 repo 的哪一項約束」就夠了** —— 這是公開 repo，

> 不要在這裡評論別人專案的人氣、品質或維護者。那些是讀者無從查證、對本清單也毫無作用的話。

> **只借概念、不抄檔案時**（本表第 2、4、5 項不適用，授權仍要處理）：歸屬範圍**精確到段落／項目**，

> 不可整節掛名。2026-09-07 `tech-diagram-gif` 借鏡 diagram-design（MIT）時，LICENSE.txt 把整節

> 「產出前檢查清單」掛到對方名下 — 實際只有四項 remove-test 是借的，其餘來自本 skill 與

> fireworks-tech-graph，同時構成**過度歸屬**（掛了不是人家的）與**不足歸屬**（漏掉真的借的硬閘門 1）。

> 判準：能逐條指出「哪一段來自誰」才算寫對；寫不出來就是範圍還沒想清楚。commit b28c22c 已修。

## 殘留清理（手動）

`install-dd-pipeline.sh` 只「部署」`BUILTIN_SKILLS`，**不會清掉**外部來源（如 tresor、舊版安裝包）放進 `~/.claude/skills/` 的殘留。已知會污染目錄的型態：

| 類型 | 範例 | 風險 |

|---|---|---|

| 安裝包 zip | `~/.claude/skills/*.zip` | 純垃圾，不會載入但佔空間 |

| 分類子目錄 | `~/.claude/skills/{communication,development,documentation,git,security}/` | 內含同名 skill（如 `code-reviewer`、`security-auditor`），與 DD wrapper 撞名 |

排查指令：

```bash

find ~/.claude/skills -maxdepth 1 -name '*.zip' # 查 zip 殘留（zsh 下 glob 無匹配會直接報錯，故用 find）

ls -d ~/.claude/skills/{communication,development,documentation,git,security} 2>/dev/null # 查分類目錄殘留

```

確認非 DD pipeline 內容後手動 `rm` / `rm -rf` 清掉。