/checkpoint

会话进度存档 + 知识沉淀。当前任务告一段落、需要切换会话或即将达到上下文限制时使用。

Checkpoint — 知识路由 + 会话存档

对话是知识产生的地方，/checkpoint 是知识持久化的统一收口点。

触发时机

• 用户主动输入 /checkpoint
• 一个阶段性任务完成，准备切换到下一个
• 会话即将达到上下文限制
• 用户准备结束当前会话

步骤

Step 1: 知识提取

回顾本次对话，识别值得持久化的内容。按以下类型逐项检查：

对话中发生了什么	归档到哪	格式参考
讨论并确定了技术选型/架构决策	docs/adr/{NNN}-{slug}.md	doc-06 §4.1 ADR 模板
做了技术调研、方案对比	docs/research/{date}-{slug}.md	doc-06 §4.4 Research 模板
排查并解决了 bug	docs/troubleshooting/{date}-{slug}.md	doc-06 §4.2 Troubleshooting 模板
讨论并确认了实施方案	docs/plans/{slug}.md	doc-06 §4.3 Plans 模板
功能完成/状态变更	docs/features.md	更新对应行
新增了依赖	docs/approved-deps.md	追加条目
更新了项目规则/架构	CLAUDE.md	更新对应章节
需求有变更	docs/spec.md	更新对应部分

输出归档清单，等待用户确认。不是每次都有所有类型——没有就跳过。

如果某类知识已在对话中通过专门 Skill（如 /tech-research、/debug）归档过，不重复归档。

Step 2: 进度更新

扫描 docs/plans/ 中 Status 为 active 的方案文件：

1. 勾选已完成任务 — 对照本次对话实际完成的工作，将 - [ ] 改为 - [x]
2. 更新 Progress 行 — 统计 - [x] 数量，更新 Progress: n/m
3. 完成判定 — 如果所有任务已完成：
   • 将 Status 改为 done
   • 如有 Feature 字段，提示更新 docs/features.md 对应功能状态

如果没有活跃 plan，跳过此步骤。

Step 3: 知识归档

用户确认后，批量写入各归档文件。每个文件遵循 doc-06 §4 的格式契约。

累积型目录（plans/、adr/、research/、troubleshooting/）的文件写入后，同步更新对应的 README.md 索引表。

Step 4: 会话状态覆写

完全覆写 HANDOFF.md（如不存在则创建），仅保留当前状态：

# HANDOFF
<!-- /checkpoint at {YYYY-MM-DD} -->

## Active Plan
{方案名} — `docs/plans/{slug}.md`（n/m, xx%）

## Session Tasks
- [x] {本次完成的任务}
- [ ] {待完成的任务}

## Key Files
- `{file}` — {一句话说明}

## Decisions Needed
- {待决策项，没有则省略此节}

• Active Plan — 引用活跃 plan 及其进度。无正式 plan 时省略此段
• Session Tasks — 本次会话的任务清单（复选框格式）。有正式 plan 时从 plan 任务清单中提取当前批次；无正式 plan 时记录对话中产生的临时任务
• 如果 Session Tasks 中未完成项 > 5 且预计跨会话，建议升级为正式 plan

覆写制：每次完全替换，历史在 git 中（git log -p HANDOFF.md）。

Step 5: Git Commit

git add -A  # 包含所有归档文件 + plan 更新 + HANDOFF.md
git commit -m "checkpoint: {本轮简要描述}"

Step 6: 输出摘要

向用户输出：

• 归档了哪些知识（一句话列表）
• 下次恢复命令：/handoff

IMPORTANT

• 覆写而非追加 — HANDOFF.md 每次完全覆写，只保留当前状态，≤ 50 行
• 下一步必须可执行 — 含具体文件路径或命令，不写"继续完善 XX"这种模糊指令
• 知识归档需确认 — Step 1 列出清单后等用户确认，不自动写入
• 不重复归档 — 已通过 /tech-research、/debug 等 Skill 归档的内容不再重复