ADR — 架構決策紀錄（Architecture Decision Records）

這個資料夾收錄 Cortex 每一個值得記住「為什麼這樣做」的決策。

為什麼需要 ADR

大型 spec（ARCHITECTURE.md、CORE_SPEC.md 等）描述「系統現在長怎樣」，但它們不保留：

• 當初為什麼選 A 不選 B
• 當時有哪些限制、踩過哪些坑
• 哪些 trade-off 是刻意接受的

開發時這些脈絡都寫在 .claude/active-plan-<branch>.md，但那份檔案 merge 後就刪除 —— 等於每做完一個功能，最值錢的「為什麼」就蒸發了。ADR 就是把它沉澱下來的地方。

一個 ADR = 一個決策

ADR 是逐功能 / 逐決策的小文件，不是大 spec。它只回答四件事：Context（為什麼）、 Decision（做了什麼）、Consequences（影響與 trade-off）、以及指回實作的 PR / commit。

什麼時候寫

把寫 ADR 綁進既有的 PR 流程，不靠意志力：

1. 開發時照常寫 .claude/active-plan-<branch>.md。
2. PR merge 前，把那份 plan 濃縮成一篇 ADR 收進這個資料夾。
3. 在 PR 的「📋 計畫完成對照表」註明「本次新增 ADR-XXXX」或「更新了哪份 *_SPEC.md」。

並非每個 PR 都需要 ADR —— 純 bug 修正、格式調整不用。有架構/資料模型/取捨選擇的才寫。

怎麼寫

1. 複製 0000-template.md。
2. 取下一個流水號（四位數，遞增；被取代的不回收號碼）。
3. 檔名：NNNN-<kebab-case-簡短標題>.md，例如 0001-twse-margin-maintenance-ratio.md。
4. 填四個段落，Status 起手設 Accepted。
5. 被後續決策推翻時，不刪舊 ADR，把舊的 Status 改成 Superseded by ADR-YYYY，保留歷史。

索引

ADR	標題	Status
0001	上市融資維持率（每日盤後指標，live 計算）	Accepted