maintain-workflow-context-restore

name	maintain-workflow-context-restore
description	恢复保存的工作上下文。当新 session 需要继续之前的工作，或提到"恢复""restore""继续上次"
argument-hint	[--latest | checkpoint-title]

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 字段比对：

情况	处理
完全匹配	正常继续
不匹配	发出警告：⚠️ 当前分支 {current} 与 checkpoint 分支 {saved} 不匹配。确认是否切换分支？
checkpoint 无 branch 字段	提示：checkpoint 缺少 branch 信息，请手动确认分支是否正确

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

同时检查 current_objective、next_command、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 存在？ → 高亮风险
  │
  └── 呈现摘要 → 用户确认 → 开始工作

反模式修复表

反模式	修复
恢复后不检查分支	必须比对 checkpoint 分支和当前分支，不匹配则警告
跳过用户确认直接继续	呈现摘要后必须等待人类伙伴确认
恢复损坏格式的 checkpoint	先检查 markdown 结构完整性，缺失字段则跳过并报告
恢复后忽略 Remaining Work	Remaining Work 是工作起点，必须逐项确认
忽略 Next Command	Next Command 是阶段入口，必须作为推荐恢复路径呈现
忽略 Validation State	必须说明哪些检查已跑、哪些没跑，避免虚假完成
忽略 Handoff Risks	必须高亮下个 session 最容易误判的点
同时恢复多个 checkpoint	只恢复一个。多个则让用户选择最相关的
恢复后忘记原工作目标	Summary 是你的北极星，每次操作前回顾
只看代码变更不看决策	Decisions Made 防止重复讨论已排除的方案
恢复后不检查相关文件是否仍存在	验证 spec/plan 等引用路径，缺失则标记为 stale

常见说辞

说辞	现实	后果
"从零开始更快"	重新理解代码库比恢复上下文慢 10 倍。保存的决策和注意事项是花钱买到的经验。	从零重建上下文 > 30 分钟 vs 从 checkpoint 恢复 < 5 分钟，且可能重复已排除的方案。
"文件太多了"	只显示最近 20 个，更早的按需加载。不需要翻全部历史。	不恢复 → 丢弃决策上下文 → 下次重复讨论同一方案，浪费 15-30 分钟。
"之前的上下文已经过时了"	过时的不是整个上下文——决策记录和注意事项通常仍然有效。先看再判断。	假设全过时直接丢弃 → 有效的决策也被丢弃 → 可能重新选择已排除的方案。
"我记得之前在做什么"	记忆在 session 边界消失。你有 100% 信心记得每一个决策和注意事项？	依赖记忆 → session 切换后丢失 70%+ 细节 → 遗漏关键注意事项导致返工 4-8 小时。
"只需要看代码就行"	代码告诉你做了什么，不告诉你为什么这么做、还差什么、要注意什么。	只看代码 → 不知道为什么选了 A → 可能重选已排除的 B → 方向性返工成本 10x。
"我直接重新开始不用恢复"	上下文恢复节省重复工作。至少看一眼之前的决策。	重新开始 = 重复之前的探索、讨论和决策过程，总耗时 > checkpoint 恢复的 5-10x。

红旗 — STOP

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

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

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

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

验证失败处理

失败场景	处理方式
Checkpoint 文件损坏或格式错误	跳过该 checkpoint，报告错误，尝试次新的 checkpoint
Checkpoint 分支已被 force-push	警告用户分支历史已被重写，确认是否继续
Checkpoint 引用的文件已不存在	标记为 stale，提示用户可能需要重新开始
Checkpoint 状态为 blocked	先调查阻塞原因，解决阻塞后再恢复工作
同一任务有多个 checkpoint	选最新的。如果最新的是 blocked 状态，选最新的非 blocked
Checkpoint 的 Remaining Work 全部已完成	报告该任务可能已完工，确认是否需要清理 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 继续 / 用户指定方向]