get-shit-done 里程碑归档模板用 Milestone Archive 固化版本历史、决策与技术债【免费下载链接】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本篇技术指南以 milestone-archive.md 为核心讲解 get-shit-done 中里程碑归档Milestone Archive的完整模板结构与填充规范从归档文件头、逐阶段详情、小数阶段INSERTED标记到里程碑总结中的决策、已解决/延后问题与技术债清单。读完本文你将掌握如何为每个已发布版本在.planning/milestones/下生成标准化的历史档案并理解归档背后由complete-milestone工作流与milestone.cjs驱动的落地机制以及归档布局如何被校验工具链validate consistency、find-phase识别。一、为什么要做里程碑归档在 get-shit-done 的规划体系中.planning/ROADMAP.md承载着跨版本的长期路线图.planning/REQUIREMENTS.md则按里程碑界定需求范围。若二者无限增长上下文成本会持续抬升。归档机制的核心目的见 complete-milestone 工作流 中的archival_behavior一节是让 ROADMAP.md 保持恒定大小已完成的里程碑折叠进details标签并压缩为一行摘要未来阶段仍保持可见让 REQUIREMENTS.md 里程碑化每个里程碑归档后删除原文件下一里程碑通过/gsd:new-milestone重新生成建立可回溯的历史记录版本号、阶段范围、计划数、关键决策、已解决问题与技术债全部固化到.planning/milestones/下供后续版本参考。归档动作由/gsd:complete-milestone命令触发其定义见 commands/gsd/complete-milestone.md。归档产物包括.planning/milestones/v{X.Y}-ROADMAP.md—— 使用本文讲解的milestone-archive模板生成.planning/milestones/v{X.Y}-REQUIREMENTS.md—— 需求归档全部勾选 结果标注.planning/milestones/v{X.Y}-MILESTONE-AUDIT.md—— 审计文件若存在.planning/MILESTONES.md条目、更新后的.planning/STATE.md。二、归档文件命名与存放位置模板的 Usage Guidelines 明确规定了归档位置原文档原文Save to .planning/milestones/v{VERSION}-{NAME}.md Example: .planning/milestones/v1.0-mvp.md在实际的 SDK 实现中归档目录与命名由 milestone.cjs 统一处理milestone complete/phases.archive查询处理器归档根目录固定为.planning/milestones/不存在时自动创建platformEnsureDir路线图归档写入${version}-ROADMAP.md需求归档写入${version}-REQUIREMENTS.md带归档头archiveHeader审计文件若存在则移动为${version}-MILESTONE-AUDIT.md阶段目录可选归档到${version}-phases/。需要注意的是模板中的v{VERSION}-{NAME}.md是通用约定而命令行实际产出的文件名以v{X.Y}-ROADMAP.md与v{X.Y}-REQUIREMENTS.md为准见 complete-milestone 命令 的步骤 4、5。两种命名同属.planning/milestones/归档族可互相印证。三、模板结构逐段解析模板以# Milestone v{{VERSION}}: {{MILESTONE_NAME}}作为归档文件标题完整结构如下。3.1 归档文件头# Milestone v{{VERSION}}: {{MILESTONE_NAME}} **Status:** ✅ SHIPPED {{DATE}} **Phases:** {{PHASE_START}}-{{PHASE_END}} **Total Plans:** {{TOTAL_PLANS}}文件头用三行元信息锁定一个已发布版本的事实基线Status恒为✅ SHIPPED归档只针对真正交付的版本Phases记录阶段编号区间如1-4Total Plans记录该里程碑的全部计划数。这与工作流中verify_readiness步骤的检查口径一致——只有disk_status complete、progress_percent 100%的阶段才允许进入归档见 complete-milestone 工作流。3.2 Overview 概述## Overview {{MILESTONE_DESCRIPTION}}用一段话概括本版本交付了什么。在工作流中这一步对应extract_accomplishments阶段从各阶段SUMMARY.md提取 4~6 条关键成果one-liner经用户确认后写入见 complete-milestone 工作流。模板中的MILESTONE_DESCRIPTION即为这些成果的凝练版。3.3 Phases 逐阶段详情## Phases ### Phase {{PHASE_NUM}}: {{PHASE_NAME}} **Goal**: {{PHASE_GOAL}} **Depends on**: {{DEPENDS_ON}} **Plans**: {{PLAN_COUNT}} plans Plans: - [x] {{PHASE}}-01: {{PLAN_DESCRIPTION}} - [x] {{PHASE}}-02: {{PLAN_DESCRIPTION}} [... all plans ...] **Details:** {{PHASE_DETAILS_FROM_ROADMAP}}模板明确要求为里程碑中的每个阶段包含以下信息原文档[For each phase in this milestone, include:]。每个阶段小节必须完整承载Goal阶段目标取自 ROADMAPDepends on前置依赖阶段体现阶段间依赖关系工作流中的wave/依赖语义与此呼应Plans计划总数且所有计划以- [x]勾选状态逐条列出归档只接受已完成计划Details来自 ROADMAP.md 的完整阶段细节。这里值得注意的是计划编号与阶段编号的对应关系{{PHASE}}-01意味着计划号由阶段号派生如阶段 4 的计划为04-01这与测试中对65-01-PLAN.md、65-03-PLAN.md这类文件名的校验完全吻合见 milestone-archive.test.cjs。3.4 小数阶段INSERTED 标记模板为里程碑中途插入的紧急工作专门给出了格式规范原文档原文### Phase 2.1: Critical Security Patch (INSERTED) **Goal**: Fix authentication bypass vulnerability **Depends on**: Phase 2 **Plans**: 1 plan Plans: - [x] 02.1-01: Patch auth vulnerability小数阶段Decimal Phase用于在既有编号序列中插入紧急修复如安全补丁、生产事故热修复语义上插在某个整数阶段之后。其约定要点标题必须带(INSERTED)标记便于归档与检索时一眼识别计划编号采用02.1-01这种小数阶段号 序号格式Depends on指向其插入位置的父阶段。这一设计对应命令文档中的/gsd:phase --insert N用法见 complete-milestone 命令而测试 bug-2787 相关用例 验证了extractCurrentMilestone能正确解析含小数阶段/折叠块的 ROADMAP。归档阶段所有小数阶段会统一汇总到 Milestone Summary 的Decimal Phases列表中。3.5 Milestone Summary 里程碑总结## Milestone Summary **Decimal Phases:** - Phase 2.1: Critical Security Patch (inserted after Phase 2 for urgent fix) **Key Decisions:** {{DECISIONS_FROM_PROJECT_STATE}} **Issues Resolved:** {{ISSUES_RESOLVED_DURING_MILESTONE}} **Issues Deferred:** {{ISSUES_DEFERRED_TO_LATER}} **Technical Debt Incurred:** {{SHORTCUTS_NEEDING_FUTURE_WORK}}总结区是归档的灵魂四类信息各司其职区块内容来源示例模板原文Decimal Phases本里程碑插入的全部小数阶段及插入原因Phase 5.1: Performance Hotfix (inserted after Phase 5 for production issue)Key DecisionsPROJECT-STATE.md / SUMMARY 文件中的决策记录含理由Use ROADMAP.md split (Rationale: Constant context cost)Issues Resolved里程碑期间解决的问题Fixed context overflow at 100 phasesIssues Deferred明确延后到后续版本的问题PROJECT-STATE.md tiering (deferred until decisions 300)Technical Debt Incurred为赶进度接受的捷径标注修复时机Some workflows still have hardcoded paths (fix in Phase 5)关键决策的留存尤其重要工作流在evolve_project_full_review步骤中会把各阶段 SUMMARY.md 中的决策抽取到 PROJECT.md 的 Key Decisions 表并标注结局✓ Good/⚠️ Revisit/— Pending见 complete-milestone 工作流归档总结区则负责把最重要的决策固化为长期历史。而延后问题与技术债记录在工作流的pre_close_artifact_audit步骤中也有对应机制若gsd-sdk query audit-open发现未闭合项且用户选择 Acknowledge会写入 STATE.md 的## Deferred Items表格并在 MILESTONES.md 条目中记录计数见 complete-milestone 工作流。3.6 归档收尾引用_For current project status, see .planning/ROADMAP.md_模板在总结后给出当前状态的指引指向项目根目录下的.planning/ROADMAP.md归档完成时该文件已被折叠整理作为活文档继续服务下一里程碑。四、Usage Guidelines何时归档与如何填充模板末尾的guidelines区块以清单形式给出了归档的操作规范逐条展开如下。4.1 何时创建里程碑归档- After completing all phases in a milestone (v1.0, v1.1, v2.0, etc.) - Triggered by complete-milestone workflow - Before planning next milestone work归档只在所有阶段完成、真正交付后发生。工作流的what_qualifies一节给出判据Is this deployed/usable/shipped? If yes → milestone.并明确不要为单个阶段完成、进行中的工作、内部迭代创建里程碑见 complete-milestone 工作流。版本号遵循milestone_naming约定v1.0 为初始 MVPv1.1/v1.2 为增量更新v2.0/v3.0 为重大重写见 complete-milestone 工作流。4.2 如何填充模板- Replace {{PLACEHOLDERS}} with actual values - Extract phase details from ROADMAP.md - Document decimal phases with (INSERTED) marker - Include key decisions from PROJECT-STATE.md or SUMMARY files - List issues resolved vs deferred - Capture technical debt for future reference六条填充规则与原模板逐字段一一对应其中从 ROADMAP.md 提取阶段详情和从 PROJECT-STATE.md / SUMMARY 文件收集决策是实际归档流程中的两个关键数据源。测试 bug #2684 用例 验证了milestone.complete v1.0能自动完成归档目录创建、版本号透传与可选的--archive-phases阶段归档模板填充主要依赖 AI 对 ROADMAP/SUMMARY/PROJECT-STATE 的内容理解与重组。4.3 归档位置与归档后的收尾Archive location: - Save to .planning/milestones/v{VERSION}-{NAME}.md - Example: .planning/milestones/v1.0-mvp.md After archiving: - Update ROADMAP.md to collapse completed milestone in details tag - Update PROJECT.md to brownfield format with Current State section - Continue phase numbering in next milestone (never restart at 01)归档后的三条收尾动作在整个系统中意义重大ROADMAP.md 折叠已完成里程碑放入details折叠块只保留一行摘要与链接保持路线图体积恒定模板示例见 complete-milestone 工作流PROJECT.md 演进增加 Current State 与 Next Milestone Goals 小节历史内容归档进details对应工作流的evolve_project_full_review步骤阶段编号永不重置下一里程碑从{{PHASE_END}}1继续编号保证版本跨度内阶段号全局唯一——这是路线图历史可审计性的基石。4.4 归档布局与校验工具链的集成归档布局不只是把文件挪走它还深度影响了验证工具的行为。从源码看validate.ts 会枚举.planning/milestones/下的归档目录并按语义排序当项目采用 milestone-archive 布局.planning/phases/不存在阶段目录位于.planning/milestones/v*-phases/下时validate consistency、validate health与find-phase都会扫描归档目录避免对已归档阶段误报 W006 Phase N in ROADMAP.md but no directory on disk 警告相关行为由 milestone-archive.test.cjs 全面覆盖归档布局不产生虚假 W006、旧里程碑阶段不被当作活动阶段、find-phase按确定性排序检索归档目录。五、从归档到下一个里程碑归档完成后complete-milestone工作流还会依次完成PROJECT.md 全量演进审查、MILESTONES.md 条目创建、RETROSPECTIVE.md 复盘追加、STATE.md 更新、分支合并与 git taggit tag -a v{X.Y}受git.create_tag配置控制见 complete-milestone 工作流。最终呈现给用户的收尾信息形如见 complete-milestone 工作流✅ Milestone v[X.Y] [Name] complete Archived: - milestones/v[X.Y]-ROADMAP.md - milestones/v[X.Y]-REQUIREMENTS.md Summary: .planning/MILESTONES.md Tag: v[X.Y]随后系统会提示通过/gsd:new-milestone开启下一周期提问 → 研究 → 需求 → 路线图见 complete-milestone 命令。至此定义 → 构建 → 发布 → 归档 → 再定义的里程碑闭环完成milestone-archive模板既是历史的封存格式也是下一版本规划的起点让每个发布版本都能被精确回溯、被校验工具识别、并为后续决策提供事实依据。【免费下载链接】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），仅供参考