dd-init

DD 初始化 — 8 步開發迴圈

初始化專案的開發慣例：蓋章「8 步開發迴圈」到專案 CLAUDE.md、建立截圖目錄、 確認巢狀 CLAUDE.md 維護依賴。支援新專案（空目錄）和現有專案（已有程式碼）。

2026-07 重整：原多階段 DD Pipeline（dd-start/arch/approve/dev/test）已封存、 2026-08-04 刪除（見 git 歷史）。本指令改為部署經實際專案實戰驗證的輕量開發迴圈。

---

執行步驟

Phase 0: 專案偵測

1. 掃描目錄內容，用 Glob 檢查專案類型指標：

   • package.json → Node.js、go.mod → Go、pyproject.toml/requirements.txt → Python
   • Cargo.toml → Rust、pom.xml/build.gradle → Java、composer.json → PHP、Gemfile → Ruby
   • 前端框架：偵測 next.config.*、vite.config.*、src/App.* 等

2. 判斷驗證方式（填入迴圈步驟 5 的具體指令）：

   • 有 HTTP API（後端/全端）→ 驗證含 curl 打真實 API
   • 有前端 UI → 驗證含 playwright 開真實瀏覽器（截圖存 .screenshots/）
   • 純 CLI / 函式庫 → 驗證退化為「跑真實指令 / 消費端範例」

3. 檢查 CLAUDE.md 是否存在：

   • 存在 → 補充模式（在末尾加區塊）
   • 不存在 → 建立模式（現有專案先派 Task（subagent_type: Explore）分析技術棧與目錄結構，新專案用 AskUserQuestion 問專案類型/技術棧/名稱）

Phase 1: 蓋章開發迴圈到專案 CLAUDE.md

• 建立模式：用 Write 寫入下方區塊
• 補充模式（CLAUDE.md 已存在）：
  • 無 ## 開發流程 區塊 → 用 Edit 在末尾加入
  • 已含區塊 → 版本檢查：
    • 含 dd-loop-version: 8step 且含 dd-loop-rev: 9 → 已是現行版，跳過並告知
    • 含 6step / 7step 標記、有 8step 但 rev 比 9 舊（沒有 rev 標記，或 rev 是更早的號碼），或無標記、或缺 code-review 步驟 → 舊版/手寫版： 列出與現行版的差異（6step 缺步驟 7、8；7step 缺步驟 8；8step 沒有 rev 缺「段落起點」， 步驟 3、4、8 只看最後一個 commit；rev 1–2 的步驟 8 算範圍用 status --porcelain 加 awk '{print $NF}'， 含空白的目錄名會被切斷、少列一份卻照樣 exit 0，而且「忘了記起點只會多審」那句沒有但書； rev 3 缺「有進度表時起點以表上為準」的例外、缺步驟 4 的「語意無從判定就交回使用者」， 且把「逐層堆疊更新」說成由 gate 把關；rev 4 缺步驟 4 的兩條：prompt 要附已跑過的驗證輸出、 沒有人工寫的程式碼就不派 agent；rev 5 缺步驟 4 的「派兩個 reviewer 取聯集」與「兩份報告不一致時讀程式碼判定」；rev 6 缺步驟 4 的「界定探索預算」那條，並仍把並行 wall 寫成未實測的推論；rev 8 缺步驟 4 的「派工 prompt 交事實、不交『我判斷元凶是 X』」）， AskUserQuestion 詢問是否升級。同意 → 升級為現行版但保留在地內容 （專案特有註記、具體驗證指令、額外規則行），補上版本標記；拒絕 → 保留原樣

依 Phase 0 偵測結果填入具體驗證指令，不留模板變數：

## 開發流程（每個功能段落依序走）
<!-- dd-loop-version: 8step；dd-loop-rev: 9；供 /dd-init 判斷是否提議升級，勿刪 -->

段落開始前先記起點：`~/.claude/scripts/check-claude-md.sh --start-segment`，印出「段落起點：…」才算記好。
⚠️ **這個指令有兩個擋點**：①起點以來有 `SKIP_DOC_CHECK=1` 欠下、還沒補的 CLAUDE.md
②**專案有 `docs/reviews/` 目錄時**（= 採用了 review 留痕慣例），上一段的 commit 範圍內
沒有新增 `docs/reviews/S*.md`。兩者都會 `exit 1` 並印出該怎麼做 —— 照它印的做，不要繞過。
剛採用第二個慣例時第一次一定會被擋（上一段本來就沒報告），補一份 `S<N>-SKIP.md` 即可。
沒印出這行就是沒記好；若是舊版 gate（grep 不到 `--start-segment`），它會照常檢查 staged，印出「commit 已擋下」也不要照著補檔或 commit，
先到 claude-dd repo 跑 `git pull && ./install-dd-pipeline.sh --force`。
一段常有好幾個 commit，步驟 3、4、8 都看「起點到現在」的整段；`<起點>` = `~/.claude/scripts/check-claude-md.sh --segment-base` 的輸出
（exit 非 0 或輸出是空的 = 範圍沒算出來，不是範圍為空）。忘了記下一段的起點時，範圍會連上一段一起算——只會多審，不會漏；
但這只在起點檔已經存在時成立：從沒跑過 `--start-segment` 的專案要等第一個 `SKIP_DOC_CHECK=1` commit 才會自動補記，
起點就落在段落中間，它前面的 commit 步驟 3、4、8 全看不到，而 gate 印「記下段落起點 …」、`--segment-base` 也正常 exit 0，兩個訊號都看不出範圍縮水。
**有進度表時 `--segment-base` 不是最終答案**：專案有 `task-planner` 產的進度表（根目錄 CLAUDE.md 開頭的指路句會寫明檔名，通常在 `docs/designs/`）時，
`<起點>` 以**表上這段 commits 欄的起點**為準。回頭做 `BLOCKED` 過的段落時兩者會不一樣 —— 中間插做別段會把 `--segment-base` 往後推，
用它就漏掉這段先前已經寫好的部分；表上那個較舊、較寬，只會多審。

1. **實作功能 + 首輪測試通過**（相關既有測試跑綠 + 基本手動驗證，不可帶紅燈進 commit）
2. **commit**（第一次 — 保留簡化前還原點）
3. 跑 **code-simplifier**（對該段新增/修改的程式碼：`git diff <起點>`，官方 agent）
4. 跑 **code-review**（該段 diff；每段全量跑，例外見下；修掉 Critical/Important 才續行）
   - 範圍要明講給 reviewer：依序跑時 `git diff <起點>` 加上 `git ls-files --others --exclude-standard`（步驟 3 新增、還沒 commit 的檔案 `git diff` 看不到）
   - prompt 要附上步驟 1（重跑時加步驟 5）已跑過的驗證輸出，明寫「已確認，不要重跑」，否則它會把測試、build、渲染指令整組再跑一遍
   - 這段沒有「人工寫的程式碼」（diff 全是資料／設定／註解／文件，或改動已被專案的機械檢查完全覆蓋）就不派 agent，
     改成自己逐條核對、在回報附證據，理由寫進設計文件「段落與小任務」該段底下（沒有設計文件就寫在回報裡）。
     判準是**「這段有沒有正確性還沒被機械檢查證明的人工判斷」，不是 diff 多長**
   - ⚠️⚠️ **派工的 prompt 交事實（行號、數字、實測輸出），不要交「我判斷元凶是 X」** ——
     自己的錯誤診斷寫進去，reviewer 會跟著錯（實證：兩個都接受了錯的框架，只有第三方去查才發現）。
     要寫就標明是推測。
   - **派兩個 reviewer 跑同一份 prompt，報告取聯集**：單發只挖到一部分（實測同一段 diff 五發，每發都只命中 3 個已知錯誤中的 2 個、子集還不同；兩發聯集平均 2.3/3 對單發 1.8/3）。成本 ×2；並行派時 wall 約等於較慢那一發（實測：同一則訊息派兩個，781s 與 1007s，整體 ~1007s）
   - **想讓它快就界定探索預算，不是改派送方式**：實測派送管線只佔 ~25s，時間由它跑幾次工具決定（3–5 次 = 2–4 分、21/26 次 = 13–17 分）。prompt 寫明「最多做一次重現實驗」，或「需要外部查證的列出來交回、不要自己去抓」
   - **兩份報告講不一樣時用讀程式碼判定，不要表決**：被某一發判成「既有問題、不是這次引入的」而丟進 Not reported 的項目，自己回去看那幾行（實測踩過：那個錯誤寫法正是這次 diff 複製進新路徑的）
   - 與步驟 3 並行時用 `git diff <起點> HEAD`，並要求 reviewer 一律用 `git show HEAD:<路徑>` 取檔案、不讀工作目錄（simplifier 正在改，讀到一半會被換掉）
   - 發現若是「行為變了，但**無從判定哪個才是預期**」（程式碼、測試、文件都沒寫明語意），**用 AskUserQuestion 把選擇交回使用者**，
     不要自己選一邊也不要讓 reviewer 選。金額、權限、資料保留期這類決定選錯了不會報錯，只會靜靜地錯下去
   - ⚠️ **兩份報告落地成 committed 檔(`docs/reviews/S<段落>-{a,b}.md`,三節:派工/發現/處置),
     跳過時 commit 訊息加 trailer `SKIP-REVIEW: <段落> <理由>`**。步驟 4 是 8 步裡最容易**靜默**
     掉的一步:①不留痕(跑完什麼都不產生,進度表標 `DONE` 是同一個 agent 自己填的,等於自證)
     ②最貴(13–17 分鐘 ×2)③跳過條款就寫在上面。**而它一跳,步驟 7 就沒東西可寫 ——
     那是迴圈唯一固化教訓的格子,剪斷這條回授線不會報錯。**
     ⚠️ 證據**不可以放 `.git/`**(`dd-segment-base` 走 `git rev-parse --git-path`、不進版控)。
     ⚠️ 目的是**拿掉「靜默省略」這個選項**,不是讓說謊變不可能;`.md` 不在 gate 的 `CODE_EXT` 裡,
     gate 不會強制它存在 —— 不要把它寫成閉環。
   - ⚠️ **「程式碼只有一行 / 定義域全被測試覆蓋」不是合法的跳過理由**:review 真正抓的是
     **註解與文件裡的宣稱**,不是運算式。實測某段只跑 simplifier 就抓到一句「作者自稱查證過
     卻仍然錯」的宣稱;下一段同等規模的改動,兩個 reviewer 抓出 2 個 Critical。
     **hotfix 段落通常正是人工判斷最密的地方。**
     ⚠️ 判準用「**有沒有引別處**」而不是「程式碼幾行」:diff 裡只要有引別處行號 / 函式 /
     UI 字串 / commit 範圍的敘述,就不是「只有一個運算式」—— 補審在那段的「修正版」裡
     又抓到一個新的錯宣稱,而 playwright 攔 request body 看不到這一類東西。
   - ⚠️ **半號段落(`S2.5`)有自己的 commit 且改了人工邏輯 → 算新段落,要走步驟 3–8**;
     只是補檔進同一個 commit、或純文件/資料改動,才算前一段的小任務。
     `task-planner` 的規則區塊沒寫明這條,而那份規則是照抄進設計文件、不跟著 skill 更新的。
5. **再測一次** — 確認步驟 3、4 沒破壞行為，不可只跑單元測試：
   - 重跑步驟 1 的相關測試
   - <依偵測結果填入：curl 打真實 API 驗證後端邏輯（登入/CRUD/權限…）>
   - <依偵測結果填入：playwright 真的開瀏覽器登入、操作 UI、截圖驗證前端可用>
     - 截圖一律存 `.screenshots/`（已 gitignore）；勿丟專案根目錄
     - ⚠️ **React 專案**：`browser_click` / `browser_fill_form` 常常不觸發 onClick 與
       受控輸入（工具回報成功但畫面 state 沒變，照著它的回報就會宣稱「測過了」其實沒點到）。
       改用 `browser_evaluate` 直接操作 DOM；填欄位要用 native value setter 再 dispatch
       `input`，否則 React 讀不到值：
       ```js
       const set = Object.getOwnPropertyDescriptor(HTMLInputElement.prototype, 'value').set;
       set.call(el, v); el.dispatchEvent(new Event('input', { bubbles: true }));
       ```
       表單送不出去時（後端零請求）改用 `form.requestSubmit()`。
       **判斷有沒有真的送出，看後端有沒有收到請求，不是看畫面。** 拿不到後端 log 時，
       在瀏覽器裡數請求數也算數（驗「前端擋下來、根本沒送出」特別好用）：
       `performance.getEntriesByType('resource').filter(r => r.name.includes('/api/x')).length`
6. **再 commit**（最終版本）
7. **沉澱本輪所學**（有才做）— 本輪若留下踩雷、指令或慣例，用
   claude-md-management plugin 的 /revise-claude-md 寫進 CLAUDE.md；
   它會先列出建議、等你同意才寫檔。沒有值得留的就跳過
8. **評分 & 修正本輪動過的 CLAUDE.md** — 第一個動作是算範圍，不是開始審。
   下面這行是**沒有進度表**時的寫法；有進度表時 `base` 改填表上這段 commits 欄的起點
   （步驟 3、4 寫 `<起點>` 會自動套用上面那條例外，只有這裡把指令寫死）：
   `base=$(~/.claude/scripts/check-claude-md.sh --segment-base) && [ -n "$base" ] && { git -c core.quotePath=false diff --name-only "$base" HEAD; git -c core.quotePath=false diff --name-only HEAD; git -c core.quotePath=false ls-files --others --exclude-standard; } | grep 'CLAUDE\.md$' | sort -u`
   算出幾份就只審那幾份（用 claude-md-improver）。該 skill 預設會 find 全部，
   不先算範圍會全 repo 掃。範圍是空的才跳過（指令 exit 非 0 是範圍沒算出來，不算空）。
   後兩條抓「還沒 commit 的」；**不要改用 `status --porcelain -uall | awk '{print $NF}'`** —— 含空白的路徑
   git 會加引號，`$NF` 切開後比對不到，少列一份卻照樣 exit 0 不報錯

驗證不過 → 修完重跑步驟 5，不可帶著紅燈進步驟 6。

## CLAUDE.md 維護

- 每個有程式碼的資料夾都要有 CLAUDE.md（說明該層職責與慣例）
- 功能落地後，受影響目錄的 CLAUDE.md 逐層堆疊更新（程式碼改了 → 文件跟著改）。
  **gate 只擋改碼的那一層**（缺 CLAUDE.md 或沒同批更新）；往上逐層堆疊是這裡的工作流規則，
  gate 不檢查，上層過期不會有任何訊號
- 步驟 7 處理的是「本輪學到什麼」，與上一條的「程式碼改了所以文件要同步」是兩件事
- **步驟 7 跳過不代表步驟 8 跳過**：步驟 2、6 被 gate 逼著更新的 CLAUDE.md
  也要進步驟 8 的範圍 — gate 只確認「有寫」、不確認「寫得對」