記錄決策
概述
決策是持久的基礎設施；記憶與聊天記錄則不是。記錄的成本只需支付一次，而遺失決策的成本則在每次有人從程式碼逆向推斷意圖時重複支付。
記錄格式
每個非瑣碎的決策都會產生一個結構固定的記錄，讓任何閱讀者都知道去哪裡找資訊：
| 區段 | 內容 |
|---|---|
| 架構 | 解決方案的形狀與關鍵檔案 |
| 資料模型 | 實體、欄位、關係 |
| 決策（附帶理由） | 每個選擇及其背後的理由 — 理由是強制性的 |
| 介面 | 其他程式碼如何使用此功能 |
| 約束 | 必須保持不變的條件 |
| 陷阱 | 對下一個開發者而言不明顯的潛在問題 |
| 被拒絕的替代方案 | 哪些方案被考慮過但被捨棄，以及原因 — 避免重新爭論已解決的問題 |
三個配套文件
- 所有決策的索引，帶有明確的依賴追蹤（哪個決策建立在哪個之上）和被取代區段。將一堆記錄轉變為可導覽的圖表。
- 「未來考量」文件 — 暫緩的想法與已知問題，在開始新工作時查閱，確保沒有任何事項被默默遺忘。事件行動項目與附帶觸發條件的暫緩決策放在這裡。
- 歸檔 — 被取代的記錄移至此處而非刪除。歷史被保留，而非覆寫。
快速參考
- 記錄放置慣例：
docs/superpowers/decisions/YYYY-MM-DD-<主題>.md，並附帶 YAML 前置資料（title、date、component、status、supersedes、dependencies）。 - 未來考量文件位於
docs/superpowers/future-considerations.md。每項條目都帶有狀態（open/triggered/done/dropped）以及適用的觸發條件（觸發重新啟動的條件）。在開始新工作時查閱它。 - 前置資料會餵給自動生成的索引 — 請保持準確。
- 理由與被拒絕的替代方案是價值最高的兩個區段。缺少它們的記錄就像是地雷。
- 在管線的記錄階段（參見
designing-before-building），執行階段之後撰寫記錄。
內建工具
此技能附帶自己的腳本與範本，因此能在任何安裝該技能的儲存庫中運作。它們位於 SKILL.md 旁：
recording-decisions/
scripts/doc-archive.sh 找出缺少決策記錄的規格/計劃
scripts/index-rebuild.sh 從記錄的前置資料重新生成索引
templates/decision-record.md
找到它們 — 技能可能按專案或全域安裝：
for base in .claude/skills ~/.claude/skills; do
d="$base/recording-decisions/scripts"
[ -d "$d" ] && echo "$d" && break
done
doc-archive.sh [specs_dir] [plans_dir] [decisions_dir] [archive_dir]
列出沒有對應決策記錄的規格，並輸出由範本建立的轉換提示。預設值為 docs/superpowers/{specs,plans,decisions,archive}。
index-rebuild.sh [decisions_dir] [output_file]
從每個記錄的前置資料重新寫入 docs/superpowers/index.md — 一個作用中表格（元件、標題、日期、依賴關係）和一個被取代表格（元件、標題、被誰取代）。由於是完全重新生成，因此切勿手動編輯。
兩者都是無依賴的 Bash 腳本：使用此技能的專案不需要 yq、jq 或任務執行器。如果腳本遺失，上述程序是自足的 — 直接手動完成工作。
為何這對上下文很重要
規格與計劃刻意詳細；它們是為跟隨推理過程的人類編寫的。每次 Claude 開啟一份規格或計劃時，都會為其繁瑣的內容付出上下文成本。決策記錄只保留前進所需的資訊 — 決策、理由、介面、約束、陷阱、被拒絕的替代方案 — 大約 30-50 行，而原始規格則移至 archive/，在那裡它對人類保持可讀性，且不會消耗上下文，直到被刻意開啟。
何時不使用
瑣碎、不言自明的變更不需要記錄。測試標準：將來是否會有人問「為什麼要用這種方式做？」 如果是，就記錄。
完整理由：章程第二條，置於 engineering-constitution/references/engineering-constitution.md。