SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场maintain-workflow-context-save

maintain-workflow-context-save

办公与效率

查看项目

更新于 10-16 10:19

技能介绍

用途

maintain-workflow-context-save 用于保存工作上下文。当需要保存当前工作状态供后续 session 恢复，或用户提到"保存""save""checkpoint""挂起"时触发。其入口为当前会话中的工作状态，出口为 .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: 总结上下文

从当前会话中提取恢复所需的九类信息：正在做什么、当前目标、git 快照、进度状态、已做决策、验证状态、剩余工作、阻塞项和下一命令、交接风险。总结要精炼，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。

文件格式

YAML frontmatter 字段包括 status（枚举 active/paused/blocked）、branch、timestamp（ISO-8601）、current_objective、next_command、files_modified（列表）、last_commits（列表，至少 1 条或写 none）。

Markdown body 包含十一个章节：Summary、Current Objective、Git Snapshot、Progress State、Decisions Made、Validation State、Remaining Work、Blockers、Next Command、Handoff Risks、Notes。章节不可省略，内容为空（如 Notes 下写无）但章节标题必须存在，恢复时按标题定位信息。

常见说辞与现实

  • "我还没做完不用保存"：保存时机是进行中，不是结束时。完成后再保存 = 只有结果没有决策过程。
  • "下次我会记得"：上下文窗口有限，记忆不可靠，文件可靠。
  • "保存太花时间"：采集 git 状态 + 写总结 < 2 分钟，重新理解上下文 > 30 分钟。
  • "内容太少不值得保存"：一行决策也比从零开始强。

红旗（STOP）

  • checkpoint 文件超过 100 行 — 太详细，checkpoint 是恢复索引，不是工作日记
  • 修改代码 — 违反 Hard Gate，本技能只读不写（checkpoint 文件除外）
  • 省略 YAML frontmatter — frontmatter 是机器可读元数据，恢复依赖它
  • 省略核心 Markdown 章节 — 恢复时按标题定位信息，缺失章节 = 恢复不完整
  • 不采集 git 状态直接写总结 — 缺少 git 状态的 checkpoint 无法验证 branch 一致性
  • 不记录验证状态或下一命令 — 下个 session 不知道能否继续、该从哪个阶段继续

验证清单

包括 git 状态完整、十一个 Markdown 章节全部存在、决策已记录、Validation State 已记录已跑/未跑/失败检查、剩余工作已列出、Next Command 已写清推荐命令原因和前置条件、Handoff Risks 已写清、YAML frontmatter 完整、文件名格式正确、文件总行数 ≤ 100。

验证失败处理

  • checkpoint 超 100 行：精炼内容，删除重复描述、合并相似条目，不拆分为多个 checkpoint
  • 核心章节有遗漏：强制补齐，空章节写"无"但不省略标题
  • git 状态采集失败（非 git 仓库）：frontmatter 中记录 branch: none，body 中注明环境无法采集
  • frontmatter 字段不完整：补齐所有字段，不省略任何一项
  • 决策未记录：强制列出至少 1 个决策 + 理由
  • Validation State 缺失：补已跑、未跑和失败检查，没有验证就写 not_run 和原因
  • Next Command 缺失：根据 Remaining Work 选择 /build、/review、/ship 或其它明确下一步

适用场景

在软件开发工作流中，当一次会话即将结束而任务尚未完成时，用于保存可恢复的上下文，便于下个 session 快速接续，避免重复讨论已做决策和重新理解上下文。