ADR 0007: 反規格文件驅動 (Anti-Spec-Driven Development) 與以碼為首¶

Context (背景脈絡)¶

在初版開發期間（特別是 docs/time_compass 這個充滿大量文件的時代），專案曾嘗試導入 Spec-Driven Development (SDD)。理念是要求開發者與 AI 先把模組中每一個細節、每一個函數的預期輸入輸出（包含詳細的屬性欄位）以 Markdown 文件定義得清清楚楚，然後再開始寫 Code。但很快我們發現，由於這是一個高度實驗性質的新架構（需要與 Google API 和複雜的 Moodle 爬蟲打交道），我們幾乎每天都在重構 API 回傳的結構與欄位。這導致先寫好的 SDD 文件在幾天內就徹底 Out-of-date（過期），甚至開始誤導後續接手的開發者。

Decision (技術決策)¶

摒棄細微節點的文件驅動開發 (Anti-SDD)，確立「程式碼才是唯一絕對的事實來源 (Single Source of Truth)」，輔以高階架構圖與 ADR。

具體規則： 1. 不寫微觀 Spec 文件：不再於外部 Markdown 檔案中定義某個特定函數的入參出參。這些內容必須直接寫在 Python 的 Type Hints (型別提示) 以及 Pydantic Models 裏頭。 2. 註解寫「為什麼」而非「做什麼」：程式碼的 JSDoc/TSDoc 或 Python Docstring 必須專注於解釋這段邏輯的意圖（Why），而非重複描述實作步驟（What）。 3. 高階索引與資料流圖：我們唯獨保留且重視的是系統架構層次的文件（例如 docs/architecture/data-flow.md 中的 Mermaid 圖表），用以說明模組之間是如何傳遞資料的，但不定義內部細節。

Consequences (決策結果)¶

Positive (優點)¶

永遠不會過期的文件：藉由依賴 Code 作為規格，並搭配靜態型別檢查工具（如 mypy/pyright），這份「規格」是會被編譯器保證正確的。
開發速度提升：開發者 (含 AI) 不必再陷入「改動一行 Code 需要同步更新三份 Spec Markdown 文件」的文書泥淖。
避免 AI 產生幻覺：當 AI 開發者直接讀取原始碼，而非閱讀一份已經過期兩週的文件時，產出的程式碼準確率大幅提升。

Negative (缺點)¶

新人初期理解門檻較高：缺少了一份「步步拆解」的冗長規格書，新開發者需要具備循著 models.py 閱讀型別定義，以及 tracing data flow 的能力。然而這也是我們透過強制制定 systematic-debugging 技能建立 Data-flow Routing & Inspection Protocol (DRIP) 的原因。