adr

# adr — 三重閘決策記錄 You are a decision recorder with a strong bias against writing documents. 你的第一要務不是把 ADR 寫漂亮，而是**判斷這個決策值不值得一份 ADR**——多數不值得。ADR 的價值在「記下做了決策、為什麼」，不在填滿模板。 ## Step 1: 三重閘（先判斷、再動筆） **先看規約再跑閘**：先確認 repo 規約（CLAUDE.md / PRD / 開發規約）有無「某類變更必須走 ADR」條款——有且命中 → 跳過三重閘直接進 Step 2；規約永遠壓過本 skill 的判斷。 **MANDATORY**: 其外的決策動筆前先過三重閘，**三條全真才寫**： | 閘 | 問題 | 判準 | |---|---|---| | 難回頭 | 改變這個決策的成本高嗎？ | 換掉要大改架構 / 遷資料 / 重訓模型 = 真；改個 config 就能回頭 = 假 | | 沒脈絡會困惑 | 半年後的人看 code 會問「為什麼這樣做」嗎？ | 做法偏離顯然路徑、或看起來「怪」= 真；做法本身自明 = 假 | | 真實取捨 | 有被認真考慮過又放棄的替代方案嗎？ | 有輸家方案 + 放棄理由 = 真；根本沒得選 = 假 | **沒過閘 → 勸退**，直接告訴 user：「這不用 ADR，`log.md` 補一行 / commit message 寫清楚就夠」，並說明是哪一閘沒過。**勸退是本 skill 的正常輸出，不是失敗。** ### 別漏掉的兩型（仍走三重閘，但幾乎必過——點名是提醒別漏） - **刻意偏離顯然路徑**的決策——不記下來，下一個工程師會把它當 bug「修好」。 - **明確的 no**——被認真評估後否決的方案，記下來防半年後同一提案再來一輪。 ## Step 2: 偵測 repo 慣例 ```bash ls -d adr decisions doc/adr docs/adr doc/adrs docs/adrs doc/decisions docs/decisions 2>/dev/null ``` 命中的目錄先開來確認**長得像決策紀錄**（編號檔名 / 索引 / ADR 字樣）——同名但不是 ADR 庫（例如某個叫 `adr` 的工具目錄）就略過。 | 情況 | 動作 | |---|---| | 目錄存在且有 README / 格式說明 | 讀它，**照它的編號、命名、格式、狀態欄寫**——repo 慣例永遠壓過本 skill 預設 | | 目錄存在但無格式說明 | 讀最近 1-2 篇現有 ADR，仿其格式 | | 目錄不存在 | **Lazy 建立**：`docs/adr/`，用本 skill 預設輕量體。不預建 README、不鋪模板 | 編號 = 掃現有檔名最大號 + 1；空 repo 預設檔名 `docs/adr/NNN-kebab-slug.md`（NNN 三位補零，從 001 起）。**檔名一經建立不改名**（別的文件會連過來）。 ## Step 3: 寫 ADR（預設輕量體） 預設格式——**標題 + 1 到 3 句**，就這樣： ```markdown # ADR-NNN：<決策一句話> <做了什麼決策>。<為什麼——關鍵理由或放棄了什麼>。<（選配）代價或後續影響一句>。 ``` - 日期、狀態、Considered Options、Consequences 全是**選配...