Context Restore — 恢复工作上下文

入口/出口

• 入口: .claude/checkpoints/ 下的 checkpoint 文件
• 出口: 上下文摘要呈现给用户
• 指向: 认后 → 继续原工作流（build / verify / ship 等）
• 前置加载: CANON.md、maintain-workflow-context-save（上游生产方，了解 checkpoint 格式契约）
• 输出路径: 读取 .claude/checkpoints/YYYYMMDD-HHMMSS-{title-slug}.md → 恢复后继续对应阶段技能

与自动 feature state 的边界

新 session 会通过 docs/features/<feature>/state.json 获得阶段级恢复提示：当前 feature、当前阶段、最后阶段文档、下一步命令。这个提示不等于 /restore，也不会自动开始写代码。

/restore 用于恢复 decision-rich checkpoint：当前目标、git 快照、进度状态、已做决策、验证状态、阻塞、剩余工作、下一命令和交接风险。只需要知道"做到哪一步"时，优先使用 SessionStart 的 feature state 提示。

何时不使用

• 当前会话上下文完整，不需要从 checkpoint 恢复
• 用户只是询问历史信息，不准备继续之前的工作
• SessionStart 已提供足够的 feature state，且不需要恢复决策上下文
• checkpoint 内容来源不明或与当前 repo 明显不匹配

硬门

只读操作。不修改代码。

恢复上下文后直接动手写代码 = 跳过确认。必须先呈现、再确认、再行动。

流程

Step 1: 查找 checkpoint 文件

扫描 .claude/checkpoints/ 下所有 .md 文件。

文件名以 YYYYMMDD 前缀开头，天然保证时间排序。按文件名字母序排列即为时间序。

ls .claude/checkpoints/*.md | sort

Step 2: 选择 checkpoint

默认行为： 加载最新的（排序后最后一个）。

按片段搜索： 支持按标题关键词筛选。

/restore              → 加载最新 checkpoint
/restore auth         → 搜索文件名包含 "auth" 的最新 checkpoint
/restore list         → 列出最近 20 个 checkpoint（标题 + 时间 + 状态）

按编号选择： list 输出带编号，用编号指定。

Step 3: 呈现摘要

读取 checkpoint 文件，提取并呈现关键信息：

📋 Checkpoint: refactor-auth-module
  分支: feature/auth-refactor
  时间: 2026-04-24 14:30
  状态: active
  目标: migrate auth from session to JWT
  下一命令: /build

  Summary: 将登录模块从 session-based 重构为 JWT-based。
           已完成 token 签发，停在 refresh token 轮换逻辑。

  Validation: unit tests pass; integration tests not_run
  Remaining Work:
    - Refresh token 轮换逻辑
    - 旧 session 清理迁移
    - 集成测试补全

  Handoff Risks:
    - 不要删除 src/auth/legacy.ts

不展开全部内容。只呈现恢复决策所需的最小信息。完整内容在用户要求时才展示。

Step 4: Branch 匹配检查

获取当前 git branch，与 checkpoint 的 branch 字段比对：

branch 不匹配不阻止恢复——但必须警告。用户可能有意在另一个分支继续。

同时检查 currentobjective、nextcommand、Validation State、Blockers 和 Handoff Risks。缺失时必须标记为 legacy checkpoint，不得假装恢复信息完整。

Step 5: 提示下一步

呈现摘要后，等待用户选择：

1. 继续工作 — 按 checkpoint 的 Next Command 和 Remaining Work 继续
2. 查看完整文件 — 输出 checkpoint 全文
3. 忽略 — 不恢复，从当前状态继续

不做任何假设。不自动开始写代码。

Checkpoint 文件示例

一个完整、格式良好的 checkpoint 长这样：

# .claude/checkpoints/20260425-143000-task-auth.md

---
status: paused
branch: feature/auth-jwt
timestamp: 2026-04-25T14:30:00+08:00
current_objective: implement JWT auth
next_command: /build
files_modified:
  - src/auth/token.ts
last_commits:
  - a1b2c3d feat: add auth middleware
---

## Summary
实现用户认证功能：JWT token 签发 + 验证中间件

## Current Objective
- Goal: 完成 JWT auth
- Stop point: refresh token endpoint 未完成
- Feature doc: `docs/features/20260425-auth/03-plan.md`

## Git Snapshot
- Branch: feature/auth-jwt
- Status summary: 1 modified file
- Diff stat: +80/-10 in auth
- Last commits: `a1b2c3d feat: add auth middleware`

## Progress State
| Area | Status | Evidence |
|------|--------|----------|
| Middleware | done | unit tests pass |
| Refresh token | pending | plan task 3 |

## Decisions Made
- 选择 JWT 而非 session（理由：无状态、横向扩展友好）
- access token 15min + refresh token 7d
- 密码用 bcrypt cost=12

## Validation State
| Check | Command / Evidence | Result | Notes |
|-------|--------------------|--------|-------|
| Unit tests | `npm test -- auth` | pass | middleware covered |

## Remaining Work
- [ ] 刷新 token 端点
- [ ] 密码重置流程
- [ ] 集成测试

## Blockers
| Blocker | Owner | Needed Decision / Action |
|---------|-------|--------------------------|
| none | | |

## Next Command
- Recommended command: `/build`
- Why: 继续 refresh token 端点
- Preconditions: branch matches checkpoint

## Handoff Risks
- 不要把 refresh token 存明文

## Notes
- spec 在 docs/features/20260425-auth/01-spec.md
- plan 在 docs/features/20260425-auth/03-plan.md

Checkpoint 选择流程图

查找 checkpoints/
  │
  ├── 找到多个？
  │   ├── YES → 按时间戳排序 → 选最新的
  │   └── NO → 只有一个 → 使用它
  │
  ├── 分支匹配？
  │   ├── YES → 继续
  │   └── NO → 警告用户 → 确认是否继续
  │
  ├── 状态检查
  │   ├── blocked → 先调查阻塞原因
  │   └── active / paused → 呈现恢复摘要
  │
  ├── 恢复合同检查
  │   ├── next_command 存在？ → 用它建议下一步
  │   ├── validation state 存在？ → 告知已验证/未验证
  │   └── handoff risks 存在？ → 高亮风险
  │
  └── 呈现摘要 → 用户确认 → 开始工作

反模式修复表

常见说辞

红旗 — STOP

• 恢复后直接开始写代码 — 违反 Hard Gate。必须先确认上下文仍准确。
• 忽略 branch 不匹配警告 — 不同分支的代码状态可能完全不同，强行继续 = 覆盖错误基础。
• 加载过时的 blocked checkpoint 不问原因 — blocked 有原因。不搞清楚为什么被阻塞就继续，会重蹈覆辙。
• 呈现摘要时省略 Remaining Work / Next Command / Validation State — 用户无法判断"接下来做什么、是否可继续"，恢复就失去意义。
• 不检查 checkpoint 文件格式完整性 — 格式破损的 checkpoint 可能误导恢复。

注意来自人类伙伴的信号：

• "之前做到哪了？" — 你没读 checkpoint 就开始工作了
• "这是新的还是继续之前的？" — 你没确认恢复状态
• "上次为什么不用方案 A？" — 你没读 Decisions Made
• "还要多久？" — 你没读 Remaining Work 了解剩余任务
• "这个之前不是讨论过吗？" — 你没恢复之前的决策上下文

全部意味着：STOP。回去读 checkpoint。

验证失败处理

验证清单

• checkpoint 文件存在于 .claude/checkpoints/
• YAML frontmatter 完整（status、branch、timestamp、files_modified）
• 核心 Markdown 章节全部存在（Summary、Current Objective、Git Snapshot、Progress State、Decisions Made、Validation State、Remaining Work、Blockers、Next Command、Handoff Risks、Notes）
• branch 匹配或已发出警告
• next_command 已呈现或标记为 legacy 缺失
• Validation State 已呈现，未跑检查明确标记
• Blockers 和 Handoff Risks 已高亮
• 用户确认继续（未自动开始操作）
• 呈现了摘要而非全文（用户未要求时）

好坏示例

Good — 结构化恢复

/restore

Step 1: 扫描 checkpoints/ → 找到 3 个文件
Step 2: 选择最新的: 20260424-143052-refactor-auth-module.md
Step 3: 呈现摘要:
  📋 Checkpoint: refactor-auth-module
    分支: feature/auth-refactor
    时间: 2026-04-24 14:30
    状态: paused
    目标: migrate auth from session to JWT
    下一命令: /build
    Validation: unit tests pass; integration tests not_run
    Remaining: refresh token 轮换 + session 清理 + 集成测试
    Risks: 不要删除 src/auth/legacy.ts
Step 4: branch 匹配 ✅ (当前也在 feature/auth-refactor)
Step 5: 等待用户确认

→ 用户确认后按 Remaining Work 继续执行

Bad — 不确认直接写代码

/restore

（读了 checkpoint，发现停在 refresh token 逻辑）

（直接开始写 refresh token 代码）

→ 问题: 没有呈现摘要 → 用户不知道恢复了什么
→ 问题: 没有检查 branch → 可能在新分支上写旧分支的代码
→ 问题: 没有等用户确认 → 违反 Hard Gate（必须先确认再行动）

输出模板

### Context Restore 恢复记录

**Checkpoint**: [文件名]
**分支**: [checkpoint 分支 / 当前分支 / 不匹配警告]
**时间**: [保存时间]
**状态**: [active / paused / blocked]
**目标**: [current_objective]
**下一命令**: [next_command / legacy missing]

**摘要**: [一句话描述当前进度]
**Validation State**: [已跑/未跑/失败检查摘要]
**Blockers**: [阻塞项摘要]
**Remaining Work**: [未完成任务列表]
**关键决策**: [已做决策摘要]
**Handoff Risks**: [下个 session 风险摘要]

**Branch 匹配**: ✓ 匹配 / ⚠ 不匹配 — [当前分支] vs [checkpoint 分支]
**用户确认**: [已确认继续 / 已查看完整文件 / 已忽略]
**下一步**: [按 Remaining Work 继续 / 用户指定方向]