get-shit-doneGSD/gsd-cleanup 使用指南将已完成里程碑的 Phase 目录归档至.planning/milestones/v{X.Y}-phases/【免费下载链接】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导读本指南围绕 get-shit-doneGSD的/gsd-cleanup命令展开讲解它如何把长期积压在.planning/phases/下的、属于**已完成里程碑completed milestone**的阶段目录安全归档到.planning/milestones/v{X.Y}-phases/从而保持规划工作区整洁、可控。读完本文你将掌握GSD 规划目录为什么会“越用越乱”、cleanup 六步执行流水线的每一步细节、干跑dry-run确认机制、跨运行时文本模式回退以及它在complete-milestone生命周期中的定位与调用方式。一、命令本体与文档定位/gsd-cleanup是一个以“阶段目录归档”为核心的实用工具命令其命令声明位于 commands/gsd/cleanup.md对应的完整执行工作流位于 get-shit-done/workflows/cleanup.md。从命令 frontmatter元信息头部可以读出 GSD 对命令合约的严格约定字段值含义namegsd:cleanup全局命名空间下的命令名避免与其他 AI 助手的工具冲突descriptionArchive accumulated phase directories from completed milestones面向 LLM/Agent 的能力摘要决定何时被调度allowed-toolsRead、Write、Bash、AskUserQuestion该命令允许调用的工具白名单还有部分命令会使用Grep、Globrequires[phase]该命令依赖 phase 上下文存在即应在执行过 phase 相关流程的项目中使用命令的 objective 一句话说明了它的全部用途Archive phase directories from completed milestones into.planning/milestones/v{X.Y}-phases/. Use when.planning/phases/has accumulated directories from past milestones.也就是说当.planning/phases/中残留了大量过去里程碑的阶段目录时就是运行/gsd-cleanup的时机。命令的 process 只有三行端到端执行、识别已完成里程碑、展示 dry-run 摘要并在确认后归档。在实际使用中命令通过斜杠形式触发。官方命令文档 docs/COMMANDS.md 中给出的调用方式为/gsd-cleanup无需额外参数真正的判定逻辑全部交给工作流去完成。二、为什么需要归档.planning/目录的工作机制理解/gsd-cleanup之前要先理解 GSD 规划工作区的目录约定。从 get-shit-done/templates/README.md 的目录清单可以还原出如下布局.planning/ ├── MILESTONES.md # 里程碑清单与状态已完成 / 进行中 ├── ROADMAP.md # 顶层路线图 ├── PROJECT.md ├── phases/ # 阶段目录随规划不断增长 │ ├── 01-foundation/ │ ├── 02-auth/ │ └── 03-core-features/ └── milestones/ # 里程碑归档目录 ├── v1.0-ROADMAP.md # 里程碑关闭时的 ROADMAP 快照 ├── v1.0-REQUIREMENTS.md # 里程碑关闭时的 REQUIREMENTS 快照 └── v1.0-phases/ # 由 /gsd-cleanup 归档出来的阶段目录其中每个 phase 目录.planning/phases/NN-name/内部会承载大量阶段产物例如NN-MM-PLAN.md由/gsd:plan-phase产生的可执行实施计划NN-MM-SUMMARY.md由/gsd:execute-phase产生的执行摘要与经验沉淀NN-CONTEXT.md由/gsd:discuss-phase写入的讨论决策NN-RESEARCH.md、NN-VALIDATION.md、NN-UAT.md、NN-PATTERNS.md、NN-UI-SPEC.md、NN-SECURITY.md、NN-AI-SPEC.md等具体文件与产出命令的对照表可查阅 get-shit-done/templates/README.md。这些目录承载了每个阶段的完整上下文而 GSD 的价值主张正是“上下文工程”因此它们不会在阶段结束后被随意删除而是需要归档保留供后续里程碑复用上下文——这也解释了为何需要/gsd-cleanup这样非破坏性的迁移工具而不是简单rm -rf。按 get-shit-done/templates/README.md 的说明.planning/milestones/下出现的归档文件通常由/gsd:complete-milestone产生包括vX.Y-ROADMAP.md、vX.Y-REQUIREMENTS.md、vX.Y-MILESTONE-AUDIT.md以及可选的vX.Y-phases/阶段目录归档当 complete-milestone 使用了--archive-phases时。cleanup 填补的正是这一步当完整里程碑流程没有顺手做阶段归档、导致 phase 目录持续堆积在.planning/phases/时由它事后补归档。三、执行前必须读取的资料required_readingget-shit-done/workflows/cleanup.md 明确指出在动手之前必须依次读取三份材料.planning/MILESTONES.md—— 里程碑清单用于判断哪些里程碑已完成、版本号是什么.planning/milestones/目录清单 —— 判断哪些里程碑已经存在归档目录避免重复归档.planning/phases/目录清单 —— 找出当前仍残留的阶段目录确定实际可迁移对象。这三份材料分别回答“归档谁”“是否已归档”“还有哪些可归档”三个问题构成了后续每一步判定的数据基础。四、六步执行流水线详解工作流把整个 cleanup 拆成 6 个带名字的步骤从识别到提交、再到汇报全部可复现、可审计第 1 步识别已完成里程碑identify_completed_milestones首先读取里程碑清单并提取所有已完成里程碑的版本号cat .planning/MILESTONES.md从中解析出版本如v1.0、v1.1、v2.0。然后检查这些版本在归档目录中是否已有对应空间ls -d .planning/milestones/v*-phases 2/dev/null || true|| true的作用是当没有任何匹配ls返回非零时不让命令失败、进而让工作流误判。随后筛选出尚未创建-phases归档目录的里程碑作为本次清理的候选集。边界情况如果所有已完成里程碑都已有阶段归档工作流会输出下面这条消息并直接终止All completed milestones already have phase directories archived. Nothing to clean up.这是一种幂等性的体现——重复运行/gsd-cleanup不会造成破坏。第 2 步确定阶段归属determine_phase_membership对于每个“尚未归档”的已完成里程碑读取里程碑关闭时快照下来的 ROADMAP 归档文件以确定哪些阶段属于它cat .planning/milestones/v{X.Y}-ROADMAP.md从归档 ROADMAP 中提取阶段编号与名称例如Phase 1: Foundation、Phase 2: Auth。随后核对.planning/phases/中实际仍存在的目录ls -d .planning/phases/*/ 2/dev/null || true只把“仍然存在于.planning/phases/中”的目录纳入归档清单。这一设计保证了已被手工删除、或已被早期流程移走的目录不会被当作目标再次操作避免mv落空导致命令失败。为什么以 ROADMAP 归档文件为归属判据因为 ROADMAP 是阶段划分的“权威快照”。关于归档时快照的生成逻辑可参考 get-shit-done/templates/milestone-archive.md其中明确归档文件由 complete-milestone 工作流在里程碑所有阶段完成后创建保存到.planning/milestones/v{VERSION}-{NAME}.md例如.planning/milestones/v1.0-mvp.mdROADMAP.md 归档同理.planning/milestones/vX.Y-ROADMAP.md。因此阶段编号 → 里程碑归属的映射是可靠、可追溯的。第 3 步干跑摘要与用户确认show_dry_run这一步是/gsd-cleanup最重要的安全闸门。工作流先按里程碑分组输出类似下面的干跑摘要在真正移动任何目录之前让用户看到完整的迁移计划## Cleanup Summary ### v{X.Y} — {Milestone Name} These phase directories will be archived: - 01-foundation/ - 02-auth/ - 03-core-features/ Destination: .planning/milestones/v{X.Y}-phases/ ### v{X.Z} — {Milestone Name} These phase directories will be archived: - 04-security/ - 05-hardening/ Destination: .planning/milestones/v{X.Z}-phases/若筛选后发现没有任何阶段目录可归档例如全部已移动或已被删除则输出No phase directories found to archive. Phases may have been removed or archived previously.并停止执行。随后进入确认环节工作流通过AskUserQuestion询问 “Proceed with archiving?”选项为 “Yes — archive listed phases” 与 “Cancel”。选择 Cancel 则立即终止不产生任何文件操作。值得说明的是文本模式Text mode回退机制。这是一条贯穿 GSD 全部工作流的约定cleanup 文档同样遵守当配置中workflow.text_mode: true或命令调用带--text参数时Agent 不得调用AskUserQuestion该交互能力在 OpenAI Codex、Gemini CLI 等非 Claude 运行时中不可用而应改用纯文本编号列表让用户键入选项数字完成确认Proceed with archiving? 1. Yes — archive listed phases 2. Cancel如果你在非 Claude 运行时中使用 GSD请务必通过--text或text_mode配置开启文本模式否则工作流可能因找不到AskUserQuestion而中断。第 4 步真正归档archive_phases用户确认后工作流逐里程碑执行目录迁移。首先为目标里程碑创建归档空间mkdir -p .planning/milestones/v{X.Y}-phases然后逐个移动属于该里程碑的阶段目录mv .planning/phases/{dir} .planning/milestones/v{X.Y}-phases/对清理集合中的每个里程碑重复上述两步。整个过程是纯mv同文件系统内移动不复制、不删除因此具备天然的事务性特征——即便中途失败也不会丢失数据只是留下部分已迁移的中间状态重新运行即可续迁。第 5 步提交变更commit归档完成后工作流调用 SDK 的提交查询完成 Git 提交gsd-sdk query commit chore: archive phase directories from completed milestones --files .planning/milestones/ .planning/phases/这里有两个值得注意的实现细节使用gsd-sdk query commit而非裸git commit说明 GSD 的提交链路统一收口在 SDK 层便于维护提交规范、hook 校验等横切逻辑--files显式圈定受影响目录.planning/milestones/与.planning/phases/避免把无关工作区变更卷入本次“chore”提交符合 docs/CONFIGURATION.md 等文档所强调的原子提交与最小变更原则。第 6 步汇报结果report最后工作流按固定格式向用户汇报本次归档结果Archived: {For each milestone} - v{X.Y}: {N} phase directories → .planning/milestones/v{X.Y}-phases/ .planning/phases/ cleaned up.五、成功判据Success Criteriaget-shit-done/workflows/cleanup.md 用一份 checklist 定义了/gsd-cleanup完整执行的标准可作为人工验收依据所有已完成里程碑中未建立阶段归档的均已被识别阶段归属依据归档 ROADMAP 快照确定干跑摘要已展示且用户已确认阶段目录已移动至.planning/milestones/v{X.Y}-phases/变更已提交。六、在里程碑生命周期中的位置与运维建议与 complete-milestone 的关系/gsd-cleanup不是孤立工具。GSD 中里程碑关闭的主流程是/gsd:complete-milestone它会将版本化产物如vX.Y-MILESTONE-AUDIT.md、快照文件归档到.planning/milestones/并按需通过--archive-phases顺带归档阶段目录。而当该步骤被跳过、或项目经历了长周期演进导致.planning/phases/出现跨里程碑堆积时/gsd-cleanup就是兜底的“事后归档器”。因此一个健康的归档链路是完成里程碑内全部阶段/gsd:complete-milestone归档快照类文档ROADMAP / REQUIREMENTS / AUDIT并标记里程碑完成当 phase 目录开始拖慢上下文扫描、或准备开启下一里程碑前运行/gsd-cleanup一次性清空.planning/phases/残留。运维建议与边界何时运行.planning/phases/中出现了多个已完成里程碑的阶段目录、且尚未创建对应vX.Y-phases归档时。参考 get-shit-done/templates/README.md 的提示若本应在.planning/milestones/的版本化产物出现在.planning/根目录通常也意味着归档步骤被跳过是执行 cleanup 的信号。安全边界工作流全程使用mkdir -p与mv不涉及任何删除命令识别与归属判定都依据.planning/MILESTONES.md与归档 ROADMAP 快照而非 Agent 主观猜测。这与仓库中 docs/adr/0010-file-operation-engine-module.md 倡导的“可审计、低破坏性文件操作”理念一致。幂等性所有已完成里程碑均已归档时输出 “Nothing to clean up” 并提前终止无阶段目录可归档时输出 “No phase directories found to archive” 并终止——无论重复运行多少次都不会产生副作用。非 Claude 运行时在 Codex、Gemini CLI 等环境请使用--text或workflow.text_mode: true确认环节将退化为纯文本编号选择。七、小结/gsd-cleanup用一套“识别 → 归属 → 干跑 → 确认 → 移动 → 提交 → 汇报”的可审计流水线解决了 spec-driven 开发模式下.planning/phases/目录无限累积的运维痛点。它以 ROADMAP 归档快照为唯一权威依据、以mv为唯一文件操作原语、以 dry-run 显式确认作为安全闸门既保证了阶段上下文的完整保留这是 GSD 上下文工程的根基又让规划工作区始终可扫描、可导航。相关命令定义见 commands/gsd/cleanup.md完整工作流见 get-shit-done/workflows/cleanup.md目录与模板约定见 get-shit-done/templates/README.md官方斜杠命令速查见 docs/COMMANDS.md。【免费下载链接】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），仅供参考
 用法解析：如何判断 JSON 值是否为 null)
