zeroz-lab Context Save — 保存工作上下文
入口/出口
- 入口: 当前会话中的工作状态
- 出口:
.claude/checkpoints/下的 checkpoint 文件 - 指向: 恢复时 →
maintain-workflow-context-restore；继续工作流 →build-workflow-execute、verify-workflow-review、ship-workflow-ship等 - 前置加载: CANON.md、
maintain-workflow-context-restore（下游消费方） - 输出路径:
.claude/checkpoints/YYYYMMDD-HHMMSS-{title-slug}.md→ 恢复时由maintain-workflow-context-restore消费
与自动 feature state 的边界
docs/features/<feature>/state.json 由 hooks 自动维护，用于阶段级恢复：当前 feature、当前阶段、最后阶段文档、下一步命令。
/save 不负责基础阶段连续性。它负责保存 state.json 无法表达的内容：为什么选 A 不选 B、重要取舍、注意事项、阻塞原因、非显而易见的剩余工作。
何时不使用
- 当前任务尚未形成可恢复的状态或明确 checkpoint 价值
- 用户只是要求提交、发布或验证，不需要保存上下文
- 用户只需要知道当前 feature 阶段和下一步命令；此时先看 SessionStart 的 feature state 提示
- 需要修改代码来“整理状态”时，先回到对应 build/verify 技能
硬门
只读操作。不修改代码，只读 git 状态和写 checkpoint 文件。
违反此 gate = 本技能被滥用为修改代码的借口。
流程
Step 1: 采集 git 状态
收集当前仓库快照：
git branch --show-current
git status --short
git diff --stat
git log --oneline -5
不需要更多。不需要 diff 全文——统计足够理解变更范围。
Step 2: 总结上下文
从当前会话中提取恢复所需的九类信息：
- 正在做什么 — 当前进度、停在哪个步骤
- 当前目标 — 本 checkpoint 要恢复的目标、停点和 feature doc
- git 快照 — branch、status summary、diff stat、最近 commits
- 进度状态 — 各工作区域 done / pending / blocked 的证据
- 已做决策 — 为什么选 A 不选 B、权衡点
- 验证状态 — 已跑命令、结果、未跑项和失败项
- 剩余工作 — 还有哪些步骤未完成
- 阻塞项和下一命令 — 被谁阻塞、下一步应该运行哪个阶段命令
- 交接风险 — 下个 session 最容易误判什么
总结要精炼。checkpoint 不是工作日志——是恢复上下文的最小信息集。
Step 3: 写入 checkpoint 文件
路径：.claude/checkpoints/YYYYMMDD-HHMMSS-{title-slug}.md
若 .claude/checkpoints/ 目录不存在，先创建：mkdir -p .claude/checkpoints
示例文件名：20260424-143052-refactor-auth-module.md
文件格式：
模板起点：templates/maintain/checkpoint.md
---
status: active|paused|blocked
branch: feature/auth-refactor
timestamp: 2026-04-24T14:30:52+08:00
current_objective: migrate auth from session to JWT
next_command: /build
files_modified:
- src/auth/login.ts
- src/auth/session.ts
last_commits:
- a1b2c3d feat: add token signing
---
## Summary
将登录模块从 session-based 重构为 JWT-based。已完成 token 签发，
停在 refresh token 轮换逻辑。
## Current Objective
- Goal: 完成 JWT auth migration
- Stop point: refresh token rotation 未完成
- Feature doc: `docs/features/20260424-auth/03-plan.md`
## Git Snapshot
- Branch: feature/auth-refactor
- Status summary: 2 modified files
- Diff stat: +120/-35 across auth files
- Last commits: `a1b2c3d feat: add token signing`
## Progress State
| Area | Status | Evidence |
|------|--------|----------|
| Token signing | done | unit tests passing |
| Refresh token rotation | in_progress | plan task 2 |
| Session cleanup | pending | plan task 3 |
## Decisions Made
- 选 RS256 不选 HS256 — 多服务场景下公钥分发更安全
- access token 有效期 15min，refresh token 7 天
## Validation State
| Check | Command / Evidence | Result | Notes |
|-------|--------------------|--------|-------|
| Unit tests | `npm test -- auth` | pass | token signing covered |
| Integration tests | `npm test -- auth.integration` | not_run | blocked until rotation exists |
## Remaining Work
- [ ] Refresh token 轮换逻辑
- [ ] 旧 session 清理迁移
- [ ] 集成测试补全
## Blockers
| Blocker | Owner | Needed Decision / Action |
|---------|-------|--------------------------|
| none | | |
## Next Command
- Recommended command: `/build`
- Why: 继续实现 plan 中的 refresh token rotation
- Preconditions: 当前分支保持 feature/auth-refactor
## Handoff Risks
- 不要删除 `src/auth/legacy.ts`；下个迭代才废弃
- production migration 尚未执行
## Notes
- `src/auth/legacy.ts` 不要删，下个迭代才废弃
- DB migration 已在 staging 跑过，production 还没
YAML frontmatter 字段说明：
| 字段 | 类型 | 说明 |
|---|---|---|
status |
枚举 | active（进行中）、paused（暂停）、blocked（阻塞） |
branch |
字符串 | 当前 git 分支 |
timestamp |
ISO-8601 | 保存时刻 |
current_objective |
字符串 | 当前 checkpoint 要恢复的目标 |
next_command |
字符串 | 推荐恢复后的下一阶段命令 |
files_modified |
列表 | 已修改但未提交的文件 |
last_commits |
列表 | 最近相关提交，至少 1 条或写 none |
Markdown body 十一个章节不可省略。内容为空（如 ## Notes 下写 无），但章节标题必须存在——恢复时按标题定位信息。
常见说辞
| 说辞 | 现实 | 后果 |
|---|---|---|
| "我还没做完不用保存" | 的保存时机是进行中，不是结束时。完成后再保存 = 只有结果没有决策过程。 | 只存结果不存过程 → 下次 session 不知道为什么选了 A → 重复讨论已做决策，浪费 15-30 分钟。 |
| "下次我会记得" | 上下文窗口有限。书面记录跨 session。记忆不可靠，文件可靠。 | 依赖记忆 → session 切换后丢失 70%+ 上下文细节 → 从零重建上下文 > 30 分钟 vs 从 checkpoint 恢复 < 5 分钟。 |
| "保存太花时间" | 采集 git 状态 + 写总结 < 2 分钟。重新理解上下文 > 30 分钟。 | 省下的 2 分钟在下次 session 翻倍回还：30 分钟重新理解 + 可能重复已做决策。 |
| "内容太少不值得保存" | 一行决策也比从零开始强。没有"太小不值得保存"的上下文。 | 小决策不保存 → 下次 session 重复讨论同一决策 → 每次重复讨论 5-10 分钟，累积浪费 > 30 分钟。 |
红旗 — STOP
- checkpoint 文件超过 100 行 — 太详细 = 不该在这里。checkpoint 是恢复索引，不是工作日记。
- 修改代码 — 违反 Hard Gate。本技能只读不写（checkpoint 文件除外）。
- 省略 YAML frontmatter — frontmatter 是机器可读的元数据，恢复依赖它。
- 省略核心 Markdown 章节 — 恢复时按标题定位信息，缺失章节 = 恢复不完整。
- 不采集 git 状态直接写总结 — 缺少 git 状态的 checkpoint 无法验证 branch 一致性。
- 不记录验证状态或下一命令 — 下个 session 不知道能否继续、该从哪个阶段继续。
验证清单
- git 状态完整（branch、status、diff --stat、log --oneline -5）
- 十一个 Markdown 章节全部存在（Summary、Current Objective、Git Snapshot、Progress State、Decisions Made、Validation State、Remaining Work、Blockers、Next Command、Handoff Risks、Notes）
- 决策已记录（为什么选 A 不选 B）
- Validation State 已记录已跑/未跑/失败检查
- 剩余工作已列出（可操作的待办，不是模糊描述）
- Next Command 已写清推荐命令、原因和前置条件
- Handoff Risks 已写清下个 session 最容易误判的点
- YAML frontmatter 完整（status、branch、timestamp、current_objective、next_command、files_modified、last_commits）
- 文件名格式正确（YYYYMMDD-HHMMSS-{title-slug}.md）
- 文件总行数 ≤ 100
验证失败处理
| 失败场景 | 处理方式 |
|---|---|
| checkpoint 超 100 行 | 精炼内容：删除重复描述、合并相似条目、只保留恢复所需的最小信息集。不拆分为多个 checkpoint。 |
| 核心章节有遗漏 | 强制补齐。空章节写"无"，但不省略章节标题——恢复时按标题定位信息。 |
| git 状态采集失败（非 git 仓库） | 在 frontmatter 中记录 branch: none，Markdown body 中注明"非 git 仓库环境，无法采集 git 状态"。 |
| frontmatter 字段不完整 | 补齐 status、branch、timestamp、current_objective、next_command、files_modified、last_commits。不省略任何一项。 |
| 决策未记录 | 强制列出至少 1 个决策 + 理由。"没有决策"不成立——做了选择就有决策。 |
| Validation State 缺失 | 补已跑、未跑和失败检查；没有验证就写 not_run 和原因。 |
| Next Command 缺失 | 根据 Remaining Work 选择 /build、/review、/ship 或其它明确下一步。 |
好坏示例
Good — 精炼 checkpoint
---
status: paused
branch: feature/auth-refactor
timestamp: 2026-04-24T14:30:52+08:00
current_objective: migrate auth from session to JWT
next_command: /build
files_modified:
- src/auth/login.ts
- src/auth/session.ts
last_commits:
- a1b2c3d feat: add token signing
---
## Summary
将登录模块从 session-based 重构为 JWT-based。已完成 token 签发，停在 refresh token 轮换逻辑。
## Current Objective
- Goal: 完成 JWT auth migration
- Stop point: refresh token rotation 未完成
- Feature doc: `docs/features/20260424-auth/03-plan.md`
## Git Snapshot
- Branch: feature/auth-refactor
- Status summary: 2 modified files
- Diff stat: +120/-35 across auth files
- Last commits: `a1b2c3d feat: add token signing`
## Progress State
| Area | Status | Evidence |
|------|--------|----------|
| Token signing | done | unit tests passing |
| Refresh token rotation | in_progress | plan task 2 |
## Decisions Made
- 选 RS256 不选 HS256 — 多服务场景下公钥分发更安全
- access token 15min，refresh token 7 天
## Validation State
| Check | Command / Evidence | Result | Notes |
|-------|--------------------|--------|-------|
| Unit tests | `npm test -- auth` | pass | token signing covered |
## Remaining Work
- [ ] Refresh token 轮换逻辑
- [ ] 旧 session 清理迁移
- [ ] 集成测试补全
## Blockers
| Blocker | Owner | Needed Decision / Action |
|---------|-------|--------------------------|
| none | | |
## Next Command
- Recommended command: `/build`
- Why: 继续 plan task 2
- Preconditions: 当前分支保持 feature/auth-refactor
## Handoff Risks
- src/auth/legacy.ts 不要删，下个迭代才废弃
## Notes
- src/auth/legacy.ts 不要删，下个迭代才废弃
→ frontmatter 完整、四章节齐全、决策有理由、行数 < 50
Bad — 过详细工作日记
## Summary
今天早上 9 点开始，先读了 spec，然后讨论了方案 A 和 B，
花了一个小时比较，然后写了第一个文件的 100 行代码...
→ 问题: 超 100 行 → 不该是日记
→ 问题: 无 YAML frontmatter → 恢复时无法机器定位 branch 和 status
→ 问题: 决策理由缺失 → 下次 session 不知道为什么选 A
→ 问题: 工作时间线无恢复价值 → 只需要当前状态和剩余工作
输出模板
---
status: active|paused|blocked
branch: [当前 git 分支]
timestamp: [ISO-8601 保存时刻]
current_objective: [当前目标]
next_command: [/build|/review|/ship|other]
files_modified:
- [已修改未提交文件1]
- [已修改未提交文件2]
last_commits:
- [short-sha message]
---
## Summary
[一句话描述当前进度和停点]
## Current Objective
- Goal:
- Stop point:
- Feature doc:
## Git Snapshot
- Branch:
- Status summary:
- Diff stat:
- Last commits:
## Progress State
| Area | Status | Evidence |
|------|--------|----------|
| | pending / in_progress / done / blocked | |
## Decisions Made
- [决策1] — [理由]
- [决策2] — [理由]
## Validation State
| Check | Command / Evidence | Result | Notes |
|-------|--------------------|--------|-------|
| | | not_run / pass / fail / blocked | |
## Remaining Work
- [ ] [未完成任务1]
- [ ] [未完成任务2]
## Blockers
| Blocker | Owner | Needed Decision / Action |
|---------|-------|--------------------------|
| none | | |
## Next Command
- Recommended command:
- Why:
- Preconditions:
## Handoff Risks
- [下个 session 最容易误判的点]
## Notes
- [注意事项/已知的坑]