企业官网建设流程全解析

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-done

GSD（get-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）带时间戳的交接文件写入；4）Git 提交；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)

检测结果按优先级映射到六类目标路径：

两个实现细节值得注意：一是"活跃"的判定用ls -lt | head -1（按修改时间取最新文件），是从文件系统时间戳推断活动状态的轻量启发式；二是每条探测命令都带|| true容错，保证目录缺失时不中断整个流程——resume 侧的工作流注释也证实了这种防御式写法与 zsh 默认NOMATCH选项（macOS 默认 shell）的兼容性考虑直接相关。对应的回归断言在 tests/pause-work-improvements.test.cjs 中（关联 issue #1489），要求工作流覆盖 spike / deliberation / research 等非 phase 上下文并写入正确的非 phase 路径。

状态收集：九维交接模型

第二步（gather）定义了完整状态收集清单，这是交接文件的信息核心：

1. 当前位置：哪个 phase、哪个 plan、哪个 task；
2. 已完成工作：本会话完成了什么；
3. 剩余工作：当前 plan/phase 还剩什么；
4. 已做决策：关键决策及其理由；
5. 阻塞项：卡住的事情；
6. 待人工操作：需要人工介入的事项（MCP 配置、API key、审批、手动测试）；
7. 后台进程：属于该工作流的运行中 server/watcher；
8. 已修改文件：已变更但未提交的内容；
9. 阻塞性约束（Blocking constraints）：本会话实际遭遇的反模式或方法学失败，恢复代理在继续前必须知晓。明确要求只收录"通过真实失败发现"的条目，不收录警告或猜测。每项带severity：
   • blocking— 恢复代理必须先通过理解检查（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），核心段落包括：

1. # BLOCKING CONSTRAINTS — Read Before Anything Else：置顶的强制确认清单，每条约束写作- [ ] CONSTRAINT: [name] — [what it is] — [structural mitigation required]，并声明 "Do not proceed until all boxes are checked"；无约束时整段删除。
2. Critical Anti-Patterns 表格：| Pattern | Description | Severity | Prevention Mechanism |。Prevention Mechanism 一栏要求写"防止复发的结构性步骤——而不是口头确认"，这是与普通 TODO 的本质区别：每个反模式都必须附可执行的预防机制。表格会被 discuss-phase 与 execute-phase 工作流解析，对blocking行强制理解检查。
3. <current_state>/<completed_work>/<remaining_work>/<decisions_made>/<blockers>：五段式状态描述，用 XML 标签包裹以便下游提示词切分。
4. Required Reading（按顺序）：恢复代理动手前必须读的文档清单；若.planning/METHODOLOGY.md存在则列入，使恢复代理继承项目的分析视角（artifact-types.md 中 METHODOLOGY.md 条目明确记录了 pause-work 这一消费关系）。
5. Infrastructure State：运行中的服务、外部状态、环境细节。
6. Pre-Execution Critique Required：仅在暂停点位于"设计与执行之间"（如 spike 设计完成但尚未运行）时填写，记录设计工件路径与评审应探询的关键问题，并声明 "Do NOT begin execution until critique is complete and design is revised"——这是一道设计→执行的门禁，对应测试中的 issue #1487。
7. <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 分支：把暂停点变成会话报告

当用户带上--report（docs/USER-GUIDE.md 的新项目全周期示例中即出现/gsd-pause-work --report），命令改为端到端执行 session-report 工作流：

1. gather_session_data：从 STATE.md（当前阶段、阻塞、决策）、git log（近 24 小时提交，git diff --stat统计变更）、plan/summary 文件、ROADMAP.md（里程碑上下文）四个来源采集数据，并检查.planning/reports/下的历史报告；
2. estimate_usage：明确说明精确 token 计数"需要 hook 拿不到的 API 级插桩"，因此用可观测信号做启发式估算（每个 commit ≈ 一个 plan 周期、每个 plan 文件 ≈ 2,000–5,000 tokens、每个 summary ≈ 1,000–2,000 tokens、子代理按类型 ×1.5），并在报告中注明这是估算；
3. 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

四类恢复源按优先级从高到低：

1. 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（一次性工件）；
2. .continue-here 文件：计划中途的恢复点，标记 "Found mid-plan checkpoint"。这里特意用find而非链式ls通配——工作流注释解释了原因：zsh 默认 NOMATCH 选项下单个 glob 不匹配会中止整条命令，静默丢弃其后所有模式，而find不参与 shell glob 展开，在 bash 与 zsh 下都容错；
3. 有 PLAN 无 SUMMARY：执行开始但未完成，标记 "Found incomplete plan execution"；
4. 被中断的代理：子代理已派生但会话在结束前未跑完，从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 的完整链路，有五个可迁移的工程化设计：

1. 双载体交接：JSON 面向机器（稳定 schema、可校验、可逐字段解析），Markdown 面向人（承载心智状态与 WHY）；同一次暂停写两份，分别服务恢复代理与人类读者。
2. 失败经验一等公民：Blocking Constraints 与 Anti-Patterns 只收录"真实失败发现"的条目，且预防机制必须是结构性的；tests/pause-work-improvements.test.cjs 把 Required Reading、Anti-Patterns、Infrastructure State 等模板段落固化为回归断言（对应 issue #1490），防止模板演进中丢失关键段落。
3. git 作为持久层：WIP 提交让交接文件与代码一样进入版本控制——暂停不是"写张便签"，而是"在版本库打检查点"。
4. 一次性生命周期：HANDOFF.json 与 .continue-here.md 都在恢复后删除，永久记忆属于 STATE.md / SUMMARY.md，交接文件只是会话之间的临时桥。
5. 门禁强制力：blocking级别约束由下游 discuss-phase / execute-phase 工作流以"强制理解检查"执行，使交接约束有执行效力而非仅靠自觉。

实操使用路径（GSD 命令在 Claude Code 中以/gsd-*或/gsd:*形式调用，docs/USER-GUIDE.md 使用前者）：

# 阶段中途需要结束会话时暂停 /gsd-pause-work # 产出 HANDOFF.json + .continue-here.md，WIP 提交 # 暂停并顺出生成会话报告 /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