CLAUDE.md git:20260911.ad94c89A

Immutable. This exact content is served forever at /api/v1/blob/532a2b65bed50a10.

# 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，實證來源為當次
對話的完整管線驗證），全部預設部署；清單定義在 `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/` — 10 個 Skills（每個子目錄含 SKILL.md 定義檔，全數部署；writing-great-skills 為 vendored 自 mattpocock/skills 的 skill 撰寫參考、tech-diagram-gif 的風格規範 vendored 自 fireworks-tech-graph）
- `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/` — 輔助腳本（部署到 `~/.claude/scripts/`；含 check-claude-md.sh pre-commit gate 與本 repo 自用的 `githooks/`，後者不部署）
- `diagrams/` — 兩份 README 嵌的 4 張 GIF（使用流程、8 步迴圈 × 中英），另有 tech-diagram-gif
  各風格的示範 GIF（2026-09-07 加入）；每張的來源與重出方式見 `diagrams/src/CLAUDE.md`
  （改來源再重出，勿手改 GIF）。
  三層架構圖於 2026-08-31 移除 — 它畫的是目錄清單而非架構，資訊都在
  `DD_PIPELINE_ARCHITECTURE.md` 的文字版裡，還多一份圖要維護
- `install-dd-pipeline.sh` — 安裝腳本（部署到 ~/.claude/；唯一安裝路線，分享亦同）

## 新增 Skill 步驟

1. 在 `skills/<skill-name>/` 建立 `SKILL.md`
2. 在 `install-dd-pipeline.sh` 的 `PROMOTED_SKILLS` 陣列加入名稱
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` 部署

### 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` 陣列加入名稱
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` 陣列

## 核心工作法：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 後再重跑，其他專案才會用到新版
- 架構總覽（分層、部署清單、安裝行為保證、CI 防線）見 `DD_PIPELINE_ARCHITECTURE.md`

## 注意事項

- 所有回應和註解使用繁體中文
- Commit message 使用繁體中文
- 此專案是 source of truth，全域 ~/.claude/ 的內容由安裝腳本從此專案部署
- 修改 skills/agents/commands 後務必同步更新 install-dd-pipeline.sh 的部署陣列（CI 會擋不一致）
- 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 的陣列與數字，MCP 表格會靜靜過期。
  CI 不驗的手動同步區塊共 6 類（安裝步驟清單、指令一覽、官方 Plugins、
  第三方 Plugin 推薦、MCP 必要表、MCP 可選表），雙語化後 × 兩份 README = 12 處
- **安裝選項**已有 CI 防線：flag 三方對照驗「腳本 case 分支 ↔ `--help` 輸出 ↔
  兩份 README 指令範例」名稱完全一致，新增/刪除 flag 忘了同步文件會被擋。
  只驗 flag **名稱**，各 flag 的**語意描述**仍是手動維護
- **迴圈步數**已有 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` 那處是人工逐檔翻完仍漏掉、靠檢查腳本才抓到的
- `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 / pkg 事實驗證** | 任何 `npm install` / CLI args / 套件名，先 `npm view <pkg>` 或讀官方 README 證實，**不靠名稱推論** | 無法證實 → 不收 |
| 4 | **runtime 依賴** | 讀 SKILL.md / scripts，確認是否需 Python / Node / 全域 binary | 需額外 runtime → 違反「不塞二進制」，不收或改純設定 |
| 5 | **跨平台冪等** | 無硬編碼絕對路徑、無單一 OS 假設，重跑安裝結果一致；設定與狀態分離 | 不冪等 → 改寫 |
| 6 | **撞名 / 重疊** | 與既有 skill 比 `description`，功能不重複、命名不衝突（避免污染如下節「殘留清理」所述） | 重疊 → 評估取代或不收 |
| 7 | **納管** | 全過後：加進 `install-dd-pipeline.sh` 的 `PROMOTED_*` 部署陣列 → 跑 `--force` → 納入 source of truth | — |

> **典型踩雷**（實際評估）：某第三方 UI/UX skill 號稱 9 萬星但建立僅半年、forks 為整數 → 採用度存疑；且需 `npm -g` binary + Python runtime → 第 3、4 項直接擋下。

> **只借概念、不抄檔案時**（本表第 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` 清掉。