# events 範例：說明

這是作者「城市活動蒐集器」專案的文件（去個資版）。專案本身是公開 GitHub repo，所以內容原本就是公開的；這裡拿掉的是：GitHub 帳號與 repo 網址、主機名、絕對路徑裡的使用者名稱、VPN 網址與 IP、通知 topic 名、本機 LLM 的具體型號、其他專案的名字。網站來源的細節段落（十幾個抓取來源各自的解析細節）有節錄，標 `（節錄）`。

檔案：

- `README.md` — 維護手冊，**兼作本專案的 DESIGN**（公開 repo 需要 README，測試與自動修復腳本都讀它）。
- `DESIGN.md` — 只指路（宣告 README 兼 DESIGN 這個例外）。
- `AGENTS.md` — agent 的操作規則：發佈鐵律、Git 工作流程、抓站門檻、文件維護。
- `STATUS.md` — 現況，照 root DESIGN §4 標準格式。

示範重點：

1. **不變量（INVARIANTS）清單**：把「絕不能做的事」寫成一條條可檢查的句子，agent 做自動修復時照它判斷能不能動。
2. **Runbook**：某來源壞掉時的固定步驟，含「已實測案例」。
3. **發佈鐵律**：改了網頁就要當場發佈到兩邊並驗證——因為「只發了一邊」發生過多次。
4. **文件維護規則**：「這件事如果忘了，會不會重踩一次」——會的就寫，包含失敗的嘗試。
5. **unit 失敗後自動修復**：失敗通知 → flock → 重複失敗守門 → 跑一次無人 `claude -p` → 一定再發第二則通知。
6. **已知陷阱**：一條一個坑，附發現日期與根因。