模組 3：真實架構 4 / 6
進階 S16 Session Resume Automation

Session 管理

透過公開介面恢復、命名、分支、匯出並自動化 Claude Code sessions。

2026年3月20日 14 分鐘閱讀
已校驗 課程最近校驗: 2026年7月20日
Claude Code ≥ 2.1.196 官方來源 1 官方來源 2

你將學到什麼

Claude Code session 是與 project directory 關聯的已儲存對話。穩定的操作方式是使用文件化的 commands、flags、session IDs、exports 與 SDK messages，而不是 reverse-engineer transcript records。

本課只介紹延續、尋找、分支與自動化對話的公開契約。

恢復正確的對話

介面行為
claude --continue 或 claude -c恢復目前目錄最近一次對話
claude --resume開啟互動式 session picker
claude --resume <name-or-id>恢復特定命名 session 或 session ID
/resume從 Claude Code 內部切換對話
claude --continue
claude --resume auth-refactor
claude --resume 550e8400-e29b-41d4-a716-446655440000

Session lookup 會考慮 project。ID lookup 僅搜尋目前 project directory 與其 Git worktrees，因此請從 session 原本開始的 project 執行指令。

在需要前先為 Sessions 命名

啟動時指定描述性名稱：

claude --name auth-refactor
# 短寫
claude -n auth-refactor

或重新命名目前 session：

/rename auth-refactor

對人類而言，名稱比把 UUID 複製到 runbook 更好。每個 session 只處理一條 workstream，例如 auth-refactor、release-audit 或 incident-142。

Resume 會恢復什麼

文件化的恢復行為包括：

  • conversation history，包含 tool calls 與 results；
  • 先前 model，但前提是仍可用且沒有被 override；
  • 先前 permission mode，但有重要例外；
  • 在支援範圍內的 active goal 與尚未過期的 scheduled tasks。

plan 與 bypassPermissions 不會自動恢復。標準 settings files 會在啟動時重新讀取。額外 settings、plugin directories、MCP config、fallback models、added directories 等 launch-only inputs，恢復時可能需要再次傳入。

Resume 恢復的是對話狀態，不會回復或重建現實。檔案可能已改變、processes 可能已停止、credentials 可能過期、remote systems 也可能已有新狀態。恢復任務時，先檢查目前 repository 與外部狀態。

使用 Branch，避免覆蓋原路徑

Branching 會把目前對話複製到新 session，原 session 保持不變：

/branch try-streaming-approach

CLI 寫法：

claude --continue --fork-session
claude --resume auth-refactor --fork-session

新 branch 會取得新的 session ID，session-scoped permission approvals 不會繼承。不要在兩個終端恢復同一個未 fork 的 session，否則兩邊的 messages 可能寫進同一段對話。

比較不同思路時使用 session branching；隔離檔案修改時使用 Git branch 或 worktree。兩者解決的是不同問題。

在 Session 內管理 Context

/context
/compact focus on decisions, changed files, and remaining risks
/clear
  • /context 顯示目前 context window 的使用狀況。
  • /compact 以 summary 取代較舊的 context。
  • /clear 開始空白新對話，舊對話仍保留，可用 /resume 恢復。

Compaction 是有損摘要，不是 durable project memory。長期 instructions 應放進 CLAUDE.md，決策應寫進 repository artifacts。

透過受支援介面匯出或自動化

人類可讀紀錄使用 /export，也可直接提供 filename。軟體整合則選擇 structured public interface：

claude -p --output-format json "Summarize this repository"
claude -p --output-format stream-json --verbose "Run the verification"
claude -p --resume <session-id> --output-format json "Summarize what changed"

其他受支援選擇包括 Agent SDK messages，以及 hooks 收到的 transcript_path。預設 transcript 可能以 JSONL 儲存在本機，但其 entry format 明確屬於 internal implementation，可能在任何 release 改變。不要依賴未公開的關聯或 record types 建立 parser。

若一次性 non-interactive run 不應寫入 session transcript，請搭配 -p 使用文件化的 --no-session-persistence flag。

可持續的交接模式

離開長時間任務前：

  1. 命名 session；
  2. 把決策與未解風險寫進 repository；
  3. 記錄目前 branch、worktree、test result 與 external status；
  4. commit 或安全保存檔案變更；
  5. resume 後先驗證以上事實，再繼續工作。

Session 保存對話連續性；repository 與 live systems 才是 source of truth。

官方來源

下一課

下一課將把 CLAUDE.md 設計成能跨多個獨立 sessions 持續使用的 project context。