claude-code-checkpoint-systemlisted

# Claude Code 跨對話斷點系統(claude-code-checkpoint-system) ## 什麼時候用 - 每開一個新 Claude Code 對話,都要手動交代「上次做到哪、為什麼這樣決定、有沒有留半成品」 - 長專案跨很多個對話接力,交接靠人腦記,講久了會漏 - 手上多個專案進度不一,「現在哪個最該處理」沒有任何地方能一眼回答 - 想要一層「狀態記在硬碟上、開場自動讀回來」的基礎建設,而不是更聰明的 AI ## 原理:為什麼會失憶、斷點系統補什麼 Claude Code 每個對話是獨立的,沒有跨對話記憶——新對話開場就是一張白紙。斷點系統補的不是模型能力,是基礎建設:把狀態寫在硬碟上,開場自動讀回來。 整套分四層: | 層 | 元件 | 做什麼 | |---|---|---| | 狀態層 | 每個專案一個 `.project/` 資料夾 | 存斷點:精簡斷點 + 長脈絡 + 決策日誌 | | 載入層 | SessionStart hook | 開場自動把斷點塞進 context | | 時間層 | UserPromptSubmit hook | 每則訊息注入當下精確時間 | | 視覺層 | 掃描全部專案的儀表板 | 回答「現在哪個專案最該處理」 | 最關鍵的設計判斷是**「讀強制、寫柔性」**: - **讀(載入斷點)走 hook 強制執行**——零成本、又絕對不能漏,用機器保證。 - **寫(更新斷點)只用柔性提醒**——如果用 hook 強制擋著不讓你隨手問一句,會非常煩。寫的那端留��人自由。 另外兩個設計判斷: - **決策日誌 append-only**:決策會演變,用新條目標 `supersedes` 舊的、永不覆寫,才能回溯整條演化線。 - **半成品保護**:精簡斷點裡放一個 `safe_to_continue` 旗標,任務開始設 `false`、乾淨結束才設回 `true`。開場載入看到 `false`,先警告上次有未完成的工作、問要繼續還是回滾,而不是悶頭往下做。 補充:hooks 是 Claude Code 在特定事件觸發時自動執行的 shell command。SessionStart hook 在每次開新對話時跑;UserPromptSubmit hook 在每次使用者送訊息前跑。設定在 `~/.claude/settings.json`。 ## 照步驟做 先確認使用者的作業系統跟專案結構,再一層一層建,每建一層停下來跟使用者確認再繼續。 ### 第 1 步:狀態層 —— `.project/` 三個檔 在專案根目錄建 `.project/` 資料夾,放三個檔: 1. **`current.yaml`** — 精簡斷點,控制在 30 行內(每次開場都要載入,太長會吃 context)。欄位: - `phase`:現在做到什麼階段 - `last_updated`:上次更新時間 - `safe_to_continue`:半成品旗標(任務開始設 false、乾淨結束設回 true) - `needs_human`:有沒有卡在需要人決定的事 - `next_task` / `next_input`:下一步做什麼、需要什麼輸入 - `open_issues`:未解問題清單 2. **`current.full.md`** — 長脈絡(架構、踩過的雷、外部依賴),按需才讀,不進開場載入��� 3. **`decisions.yaml`**