19 - 上下文管理执行手册
1. 定位
本文档是 13-上下文管理策略 的执行层：
- doc-13 = 策略认知层 — 为什么要管理上下文、退化信号、反模式
- doc-19 = 执行 SOP 层 — 怎么做检查点、怎么写 handoff、怎么恢复
三条铁律
- 暂停即保存 — 离开前必须创建检查点（WIP commit + handoff）
- 恢复即验证 — 新会话开始时必须读取 handoff 并运行验证命令
- 上下文是资产 — 当前工作状态、决策历史、已知风险都必须被记录
2. 标准流程 SOP
五阶段工作流
| 阶段 | 动作 | 产物 | 触发条件 |
|---|---|---|---|
| Start | 读取 handoff / 审查近期 commit / 运行验证 | 上下文已恢复 | 新会话开始、隔天继续 |
| Build | 编码、测试、迭代 | 代码变更 | 正常工作中 |
| Checkpoint | 暂存 + WIP commit + 更新 handoff | WIP commit + handoff 文件 | 上下文 > 60%、切换任务、暂停 |
| Resume | 读取 handoff + 审查 commit + 验证 | 确认工作可继续 | 新会话 / 中断后恢复 |
| Close | 正式 commit + 清理 WIP + 关闭 handoff | 干净的 git 历史 | 功能完成 |
流程图
Start ──→ Build ──→ Checkpoint ──→ Resume ──→ Build ──→ ...
│ │
└── 暂停/切换 ──────────────────┘
│
Close（完成时）3. WIP Commit 模板
暂停工作时创建 WIP commit，记录当前进度：
wip(scope): 简要描述当前状态
## Done
- [x] 已完成的工作项 1
- [x] 已完成的工作项 2
## Next
- [ ] 下一步要做的事 1
- [ ] 下一步要做的事 2
## Risk
- 已知风险或阻塞项
## Verify
- 恢复后需要运行的验证命令规则：
Done只列本次会话实际完成的内容Next是下一个会话的行动清单，越具体越好Risk列出已知但未解决的问题Verify列出恢复后必须运行的验证命令
WIP commit 的详细格式和示例见 18-Git 工作流 §6
4. Handoff 模板
HANDOFF.md 是会话间的"交接文档"，由 /checkpoint 覆写，由 /handoff 读取。
4.1 文件位置与生命周期
- 位置：项目根目录
HANDOFF.md（不放 docs/ 子目录） - 语义：覆写制。每次 /checkpoint 完全替换内容，只保留当前状态。历史在
git log -p HANDOFF.md中回溯 - 行数：≤ 50 行。超过说明写重了
4.2 Handoff 结构
markdown
# 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 | 可选 | 引用 docs/plans/ 中的活跃方案及其进度。无正式 plan 时省略 |
| Session Tasks | 必填 | 复选框清单。有正式 plan 时从 plan 任务中提取当前批次；无正式 plan 时记录临时任务 |
| Key Files | 必填 | 涉及的关键文件路径，方便新会话快速定位 |
| Decisions Needed | 可选 | 需要人判断的悬而未决项 |
4.3 Handoff 原则
- 覆写而非追加 — 每次 /checkpoint 完全覆写，历史在 git 中
- 下一步必须可执行 — Session Tasks 中的待完成项含具体文件路径或命令，不写"继续完善 XX"
- 进度来自 plan — HANDOFF 只是快照，整体进度追踪在
docs/plans/中
5. 会话切换 Checklist
5.1 Outgoing（离开当前会话）
□ 1. 确认所有有意义的改动已暂存
□ 2. 运行验证命令确认当前状态
□ 3. 创建 WIP commit（如有未提交的改动）
□ 4. 更新或创建 handoff 文件
□ 5. 确认 handoff 中的 Next Actions 足够具体快捷方式：使用 /checkpoint Skill 自动完成以上步骤。
5.2 Incoming（进入新会话）
□ 1. 读取最新 handoff 文件
□ 2. 审查近期 git commit（git log --oneline -10）
□ 3. 运行 handoff 中列出的验证命令
□ 4. 确认工作环境与 handoff 描述一致
□ 5. 开始 Next Actions 中的第一项快捷方式：使用 /handoff Skill 自动完成以上步骤。
6. CLAUDE.md 上下文规则模板
建议将以下规则写入项目的 CLAUDE.md：
markdown
## 上下文管理
### 检查点纪律
- 上下文使用率 > 60% 时主动执行 /checkpoint
- 切换任务前必须执行 /checkpoint
- 每天结束工作前必须执行 /checkpoint
### 恢复纪律
- 新会话开始时执行 /handoff
- 隔天继续时执行 /handoff
- 不确定上次进度时执行 /handoff
### WIP Commit
- WIP commit 使用 `wip(scope): description` 格式
- WIP commit 不允许进入 main 分支的最终历史
- 功能完成后用正式 commit 覆盖 WIP commit
### Handoff
- HANDOFF.md 存放在项目根目录
- /checkpoint 每次完全覆写，历史在 git 中
- 包含 Active Plan 引用和 Session Tasks 清单7. 常见场景决策树
7.1 暂停工作
要暂停了
├── 有未提交的改动？
│ ├── 是 → /checkpoint（WIP commit + handoff）
│ └── 否 → 更新 HANDOFF.md 的 Session Tasks → 完成
└── 改动是否有意义？
├── 是 → 暂存 + WIP commit
└── 否 → git checkout . 丢弃 → 在 handoff 记录"方案不可行"7.2 开始新会话
新会话
├── 有 HANDOFF.md？
│ ├── 是 → /handoff → 从 Session Tasks 继续
│ └── 否 → 有最近的 WIP commit？
│ ├── 是 → 读取 WIP commit message → 继续工作
│ └── 否 → claude --continue（恢复上次会话）
└── 验证通过？
├── 是 → 开始工作
└── 否 → 先修复验证问题7.3 上下文接近上限
上下文 > 70%
├── 当前任务快完成了？
│ ├── 是 → /compact 压缩 → 完成任务 → 正式 commit
│ └── 否 → /checkpoint → /clear → 新会话 /handoff
└── 已经严重退化（幻觉、重复错误）？
├── 是 → 立即 /checkpoint → /clear → 新会话
└── 否 → /compact 带保留指令 → 继续7.4 跨天继续
隔天继续同一任务
→ /handoff → 读取 handoff → 审查 git log
→ 验证环境 → 从 Next Actions 开始
→ 第一轮交互后评估：是否需要 /compact8. 与其他子系统的关系
doc-13 上下文管理策略 ──→ 策略认知层（为什么），本文档是执行层（怎么做）
doc-18 Git 工作流 ──→ WIP commit 格式、原子提交原则
/checkpoint Skill ──→ 本文档 §2-§4 的自动化执行
/handoff Skill ──→ 本文档 §2、§5.2 的自动化执行
CLAUDE.md ──→ 写入 §6 的上下文管理规则