# Maintain Workflow Context Restore

> 恢复保存的工作上下文。当新 session 需要继续之前的工作，或提到"恢复""restore""继续上次"

- Skill: `zeroz-lab/maintain-workflow-context-restore` (Agent Skill)
- Install (CLI): `npx skillmds@latest add zeroz-lab/maintain-workflow-context-restore`
- Raw SKILL.md: https://api.skillmd.com/api/skills/zeroz-lab/maintain-workflow-context-restore/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: zeroz-lab (https://skillmd.com/u/zeroz-lab)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/zeroz-lab/maintain-workflow-context-restore

---


# 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` 前缀开头，天然保证时间排序。按文件名字母序排列即为时间序。

```bash
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 长这样：

```markdown
# .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（必须先确认再行动）
```

## 输出模板

```markdown
### 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 继续 / 用户指定方向]
```