# finance 範例：說明

這是作者「個人財務資料管線」專案的文件（去個資版）。專案把多家金融機構的原始檔（Gmail 附件、手動下載的 CSV／PDF）整合成可追溯、可重建、可驗證的 SQLite，再產生報表。

拿掉的：所有機構與券商名稱（改成「銀行A」「券商B」等代號）、帳號、金額、餘額、持股、貸款條件、家族公司名、房產地點、雲端資料夾名、路徑中的使用者名稱。`DESIGN.md` 的 schema 與規則完整保留；篇幅太長的段落（機構清單、目錄樹、CLI）有節錄並標明。`STATUS.md` 與 `DESIGN-CHANGELOG.md` 只取開頭與有代表性的幾條，**是節錄**。

檔案：

- `AGENTS.md` — agent 入口：讀哪些文件、最容易誤觸的鐵則、「你改了什麼就跑什麼測試」的表、Git 工作方式。
- `DESIGN.md` — 「憲法」：目的與成功判準、持久性等級與鐵則、parser 開發迴圈（五個 stage）、權威來源原則、資料模型、對帳檢查、分析層規矩、agent 工作守則。
- `DESIGN-CHANGELOG.md` — 憲法的修訂紀錄（節錄）：每列「日期／修訂／動機」，動機幾乎都是踩坑。
- `STATUS.md` — 節錄：頂部的說明、最後更新、最近做完的事（兩條）、一句話現況、未完成（一段）。

示範重點：

1. **成功判準有優先順序**：「進出資料正確 > 事件語意完整」，取捨時永遠保住底線。
2. **判斷結果不寫 DB，寫 config**：所以 DB 永遠敢砍掉重建；違反的後果寫在旁邊（「你會不敢 rebuild，pipeline 隨即腐爛」）。
3. **兩道獨立檢查**：agent 目視抄的 ground truth 要先被「機構印的餘額」驗過，才能拿來驗 parser；不符時只准改 parser，不准改 expected。
4. **無法自動化的部分必須明確回報**，且限制代碼要先登記才能用。
5. **DESIGN 與實作不得長期不一致**，修任一邊都要留紀錄——CHANGELOG 就是這條規則的產物。
6. **STATUS 很長怎麼辦**：拆 ARCHIVE、只讀開頭、「最近做完的事」只留 5 條——root DESIGN §4 的規則就是從這裡整理出去的。
7. **AGENTS 裡的「什麼時候跑什麼」表**：省下的是每次 session 的固定成本，但「懷疑的時候跑全套」。