GSD 的 /gsd:pause-work 命令详解为 Claude Code 设计上下文交接文件与会话恢复机制【免费下载链接】get-shit-doneA light-weight and powerful meta-prompting, context engineering and spec-driven development system for Claude Code by TÂCHES.项目地址: https://gitcode.com/GitHub_Trending/getshi/get-shit-doneGSDget-shit-done是面向 Claude Code 的元提示与规格驱动开发系统当会话需要在阶段中途暂停时/gsd:pause-work命令会自动把当前阶段位置、已完成工作、决策与阻塞项固化成机器可读 人类可读双工件HANDOFF.json与.continue-here.md并提交为 WIP 提交。本文完整拆解该命令的上下文检测、状态收集、双工件写入、提交确认全链路并对照其消费方/gsd:resume-work帮助你在自己的 AI 编码代理流程中建立可中断、可恢复的工程化会话交接机制。命令契约/gsd:pause-work 是什么命令定义位于 commands/gsd/pause-work.md其 frontmatter 完整声明了命令契约--- name: gsd:pause-work description: Create context handoff when pausing work mid-phase argument-hint: [--report] allowed-tools: - Read - Write - Bash requires: [phase, progress] ---契约要点目的objective创建.continue-here.md交接文件把完整工作状态跨会话保留下来。工具白名单只开放Read、Write、Bash。这是一个纯记录状态的动作没有改写代码的权限保证暂停工作本身不会副作用式地修改项目。依赖声明requires: [phase, progress]表明命令依赖当前阶段状态与进度信息。命令的context部分特别说明这些状态不在命令层预读而是在 workflow 内部以定向读取targeted reads方式收集避免无谓的上下文膨胀。执行路由execution_context指向~/.claude/get-shit-done/workflows/pause-work.md即仓库中的 get-shit-done/workflows/pause-work.md。这是 GSD 的通用模式——薄命令 厚工作流命令文件只声明路由与入口参数业务逻辑放在可独立复用的 workflow 文件里。--report分支若$ARGUMENTS含--report命令不执行暂停逻辑而是端到端读取并执行 get-shit-done/workflows/session-report.md 生成会话报告否则遵循 pause-work 工作流。工作流承接的完整逻辑包括五步1阶段目录检测2带用户澄清的状态收集3带时间戳的交接文件写入4Git 提交5输出确认与恢复指引。上下文检测交接文件该写到哪里pause-work 工作流的第一步detect是判断正在暂停的是什么类型的工作并据此决定交接文件写入路径。从源码结构看检测依赖一组 shell 探测# Check for active phase phase$(( ls -lt .planning/phases/*/PLAN.md 2/dev/null || true ) | head -1 | grep -oP phases/\K[^/] || true) # Check for active spike spike$(( ls -lt .planning/spikes/*/SPIKE.md .planning/spikes/*/DESIGN.md .planning/spikes/*/README.md 2/dev/null || true ) | head -1 | grep -oP spikes/\K[^/] || true) # Check for active sketch sketch$(( ls -lt .planning/sketches/*/README.md .planning/sketches/*/index.html 2/dev/null || true ) | head -1 | grep -oP sketches/\K[^/] || true) # Check for active deliberation deliberation$(ls .planning/deliberations/*.md 2/dev/null | head -1 || true)检测结果按优先级映射到六类目标路径工作类型探测依据交接写入路径Phase 工作存在活跃的 phase 目录最近修改的PLAN.md.planning/phases/XX-name/.continue-here.mdSpike 工作spike 目录含 SPIKE.md / DESIGN.md / README.md无活跃 phase.planning/spikes/SPIKE-NNN/.continue-here.md目录不存在则创建Sketch 工作sketch 目录含 README.md / index.html无 phase/spike.planning/sketches/.continue-here.mdDeliberation 工作存在活跃的 deliberation 文件.planning/deliberations/.continue-here.mdResearch 工作有研究笔记但无 phase/spike/sketch/deliberation.planning/.continue-here.md默认无法探测到任何上下文.planning/.continue-here.md并在current_state中注明歧义两个实现细节值得注意一是活跃的判定用ls -lt | head -1按修改时间取最新文件是从文件系统时间戳推断活动状态的轻量启发式二是每条探测命令都带|| true容错保证目录缺失时不中断整个流程——resume 侧的工作流注释也证实了这种防御式写法与 zsh 默认NOMATCH选项macOS 默认 shell的兼容性考虑直接相关。对应的回归断言在 tests/pause-work-improvements.test.cjs 中关联 issue #1489要求工作流覆盖 spike / deliberation / research 等非 phase 上下文并写入正确的非 phase 路径。状态收集九维交接模型第二步gather定义了完整状态收集清单这是交接文件的信息核心当前位置哪个 phase、哪个 plan、哪个 task已完成工作本会话完成了什么剩余工作当前 plan/phase 还剩什么已做决策关键决策及其理由阻塞项卡住的事情待人工操作需要人工介入的事项MCP 配置、API key、审批、手动测试后台进程属于该工作流的运行中 server/watcher已修改文件已变更但未提交的内容阻塞性约束Blocking constraints本会话实际遭遇的反模式或方法学失败恢复代理在继续前必须知晓。明确要求只收录通过真实失败发现的条目不收录警告或猜测。每项带severityblocking— 恢复代理必须先通过理解检查understanding check才能继续discuss-phase 与 execute-phase 工作流会强制执行advisory— 重要上下文但不构成恢复门槛。两个配套机制对话式澄清对无法从文件确定的信息通过直接提问向用户澄清而不是臆测填充虚假完成巡检扫描既有摘要文件中的占位内容防止声称完成、实为空壳的 SUMMARY 污染交接# Check for placeholder content in existing summaries grep -l To be filled\|placeholder\|TBD .planning/phases/*/*.md 2/dev/null || true机器可读状态HANDOFF.json第三步write_structured将结构化交接写入.planning/HANDOFF.json这是/gsd:resume-work优先解析的数据源schema 如下{ version: 1.0, timestamp: {timestamp}, phase: {phase_number}, phase_name: {phase_name}, phase_dir: {phase_dir}, plan: {current_plan_number}, task: {current_task_number}, total_tasks: {total_task_count}, status: paused, completed_tasks: [ {id: 1, name: {task_name}, status: done, commit: {short_hash}}, {id: 3, name: {task_name}, status: in_progress, progress: {what_done}} ], remaining_tasks: [ {id: 4, name: {task_name}, status: not_started} ], blockers: [ {description: {blocker}, type: technical|human_action|external, workaround: {if any}} ], human_actions_pending: [ {action: {what needs to be done}, context: {why}, blocking: true} ], decisions: [ {decision: {what}, rationale: {why}, phase: {phase_number}} ], uncommitted_files: [], next_action: {specific first action when resuming}, context_notes: {mental state, approach, what you were thinking} }字段设计上有几个值得借鉴的点completed_tasks 携带 commit 短哈希把任务完成与 git 证据绑定恢复时可校验真正落盘了什么blockers 三分类technical | human_action | external恢复时能立刻把需要人类动手的事项上浮避免代理空等next_action必须是具体动作context_notes则保留暂停瞬间的思路与策略——目标是让一个全新的代理实例冷启动即可接手时间戳获取统一走gsd-sdk query current-timestamp full --raw而不是各自拼日期保证格式一致。按 get-shit-done/references/artifact-types.md 的记载HANDOFF.json/.continue-here.md这一工件类型的生命周期是暂停时创建 → 恢复时消费 → 下次暂停替换属于一次性one-shot工件不是永久存储。人类可读交接.continue-here.md第四步write把 markdown 交接文件写到检测步骤确定的路径。frontmatter 声明元数据--- context: [phase|spike|sketch|deliberation|research|default] phase: XX-name task: 3 total_tasks: 7 status: in_progress last_updated: [timestamp from current-timestamp] ---正文按固定段落组织完整模板见 get-shit-done/templates/continue-here.md核心段落包括# BLOCKING CONSTRAINTS — Read Before Anything Else置顶的强制确认清单每条约束写作- [ ] CONSTRAINT: [name] — [what it is] — [structural mitigation required]并声明 Do not proceed until all boxes are checked无约束时整段删除。Critical Anti-Patterns 表格| Pattern | Description | Severity | Prevention Mechanism |。Prevention Mechanism 一栏要求写防止复发的结构性步骤——而不是口头确认这是与普通 TODO 的本质区别每个反模式都必须附可执行的预防机制。表格会被 discuss-phase 与 execute-phase 工作流解析对blocking行强制理解检查。current_state/completed_work/remaining_work/decisions_made/blockers五段式状态描述用 XML 标签包裹以便下游提示词切分。Required Reading按顺序恢复代理动手前必须读的文档清单若.planning/METHODOLOGY.md存在则列入使恢复代理继承项目的分析视角artifact-types.md 中 METHODOLOGY.md 条目明确记录了 pause-work 这一消费关系。Infrastructure State运行中的服务、外部状态、环境细节。Pre-Execution Critique Required仅在暂停点位于设计与执行之间如 spike 设计完成但尚未运行时填写记录设计工件路径与评审应探询的关键问题并声明 Do NOT begin execution until critique is complete and design is revised——这是一道设计→执行的门禁对应测试中的 issue #1487。context/next_action心智状态与恢复后第一件事写作标准是specific enough for a fresh Claude to understand immediately具体到新实例能立刻理解。模板指南get-shit-done/templates/continue-here.md还强调三条决策要写 WHY 而不只是 WHAT避免下个会话重新辩论next_action必须在不读任何其他文件的前提下可执行该文件在恢复完成后会被删除。提交与确认让交接具备持久性第五步commit把两个工件一次性入库gsd-sdk query commit wip: [context-name] paused at [X]/[Y] --files [handoff-path] .planning/HANDOFF.json提交信息格式wip: [context] paused at X/Y自带上下文类型与进度位置使git log本身就能检索到每次暂停的检查点。提交统一走gsd-sdk query commit接口而非裸git commit这是 GSD 文件操作引擎的统一入口相关设计见 docs/adr/0010-file-operation-engine-module.md。最后一步confirm向用户输出结构化确认✓ Handoff created: - .planning/HANDOFF.json (structured, machine-readable) - [handoff-path] (human-readable) Current state: - Context: [phase|spike|deliberation|research] - Location: [XX-name or SPIKE-NNN] - Task: [X] of [Y] - Status: [in_progress/blocked] - Blockers: [count] ({human_actions_pending count} need human action) - Committed as WIP To resume: /gsd:resume-work工作流的验收清单success criteria明确了完成边界上下文已检测、交接文件写入正确路径、Required Reading / Anti-Patterns / Infrastructure State 段落已填写、适用时Pre-Execution Critique 段落已填写、已 WIP 提交、用户知道文件位置与恢复方式。--report 分支把暂停点变成会话报告当用户带上--reportdocs/USER-GUIDE.md 的新项目全周期示例中即出现/gsd-pause-work --report命令改为端到端执行 session-report 工作流gather_session_data从 STATE.md当前阶段、阻塞、决策、git log近 24 小时提交git diff --stat统计变更、plan/summary 文件、ROADMAP.md里程碑上下文四个来源采集数据并检查.planning/reports/下的历史报告estimate_usage明确说明精确 token 计数需要 hook 拿不到的 API 级插桩因此用可观测信号做启发式估算每个 commit ≈ 一个 plan 周期、每个 plan 文件 ≈ 2,000–5,000 tokens、每个 summary ≈ 1,000–2,000 tokens、子代理按类型 ×1.5并在报告中注明这是估算generate_report写入.planning/reports/SESSION_REPORT.md若已有历史报告则改用YYYYMMDD-session-report.md日期化命名防覆盖。报告包含 Session Summary、Work Performed受影响阶段、关键产出、决策、Files Changed、Blockers Open Items 与 Estimated Resource Usage 表。这使结束一次会话承担双重职责不带--report的暂停产出面向下一会话的恢复工件带--report则产出面向人类的汇报工件——同一命令、两种受众。恢复侧/gsd:resume-work 如何消费交接交接的价值在消费端兑现。pause-work 产物的消费方是 commands/gsd/resume-work.md 路由的 get-shit-done/workflows/resume-project.md。其check_incomplete_work步骤定义了完整的恢复源探测# Check for structured handoff (preferred — machine-readable) cat .planning/HANDOFF.json 2/dev/null || true # Check for continue-here files (phase non-phase legacy fallback) find .planning -maxdepth 3 -name .continue-here*.md -print 2/dev/null || true find . -maxdepth 1 -name .continue-here*.md -print 2/dev/null || true四类恢复源按优先级从高到低HANDOFF.json首选解析status、phase、plan、task、total_tasks、next_action立即上浮blockers与human_actions_pending优先处理completed_tasks中的in_progress项把uncommitted_files与git status对账并标记偏差用context_notes恢复心智模型恢复成功后删除 HANDOFF.json一次性工件.continue-here 文件计划中途的恢复点标记 Found mid-plan checkpoint。这里特意用find而非链式ls通配——工作流注释解释了原因zsh 默认 NOMATCH 选项下单个 glob 不匹配会中止整条命令静默丢弃其后所有模式而find不参与 shell glob 展开在 bash 与 zsh 下都容错有 PLAN 无 SUMMARY执行开始但未完成标记 Found incomplete plan execution被中断的代理子代理已派生但会话在结束前未跑完从agent-history.json读取任务详情通过 Task 工具的 resume 参数恢复。determine_next_action步骤给出明确路由规则HANDOFF.json 存在时主操作是从结构化交接恢复最高优先级备选项为丢弃交接、从文件重新评估仅有 .continue-here 时主操作是从检查点恢复。最后update_session步骤更新 STATE.md 的 Session Continuity 段落Last session / Stopped at / Resume file保证即使本次恢复会话再次意外中断下一次恢复仍知道断点。设计要点小结与实操路径回看 pause-work 的完整链路有五个可迁移的工程化设计双载体交接JSON 面向机器稳定 schema、可校验、可逐字段解析Markdown 面向人承载心智状态与 WHY同一次暂停写两份分别服务恢复代理与人类读者。失败经验一等公民Blocking Constraints 与 Anti-Patterns 只收录真实失败发现的条目且预防机制必须是结构性的tests/pause-work-improvements.test.cjs 把 Required Reading、Anti-Patterns、Infrastructure State 等模板段落固化为回归断言对应 issue #1490防止模板演进中丢失关键段落。git 作为持久层WIP 提交让交接文件与代码一样进入版本控制——暂停不是写张便签而是在版本库打检查点。一次性生命周期HANDOFF.json 与 .continue-here.md 都在恢复后删除永久记忆属于 STATE.md / SUMMARY.md交接文件只是会话之间的临时桥。门禁强制力blocking级别约束由下游 discuss-phase / execute-phase 工作流以强制理解检查执行使交接约束有执行效力而非仅靠自觉。实操使用路径GSD 命令在 Claude Code 中以/gsd-*或/gsd:*形式调用docs/USER-GUIDE.md 使用前者# 阶段中途需要结束会话时暂停 /gsd-pause-work # 产出 HANDOFF.json .continue-here.mdWIP 提交 # 暂停并顺出生成会话报告 /gsd-pause-work --report # 产出 .planning/reports/SESSION_REPORT.md # 下一次会话一键恢复 /gsd-resume-work # 优先解析 HANDOFF.json呈现项目状态与恢复选项一个容易混淆的边界GSD 另有更轻量的/gsd-thread命令用于不属于任何 phase 的轻量跨会话知识Goal / Context / References / Next Steps 四段存于.planning/threads/{slug}.md它不携带 phase 状态与 plan 上下文且可成熟后升级为 phase 或 backlog 项。区分标准很简单暂停的是某个进行中的阶段工作用/gsd:pause-work记录的是跨阶段的研究线索用 thread。【免费下载链接】get-shit-doneA light-weight and powerful meta-prompting, context engineering and spec-driven development system for Claude Code by TÂCHES.项目地址: https://gitcode.com/GitHub_Trending/getshi/get-shit-done创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考