企业官网建设流程全解析

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-4）；Total 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：阶段目标，取自 ROADMAP；
• Depends 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}}

总结区是归档的灵魂，四类信息各司其职：

关键决策的留存尤其重要：工作流在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 为初始 MVP，v1.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)

归档后的三条收尾动作在整个系统中意义重大：

1. ROADMAP.md 折叠：已完成里程碑放入<details>折叠块，只保留一行摘要与链接，保持路线图体积恒定（模板示例见 complete-milestone 工作流）；
2. PROJECT.md 演进：增加 "Current State" 与 "Next Milestone Goals" 小节，历史内容归档进<details>（对应工作流的evolve_project_full_review步骤）；
3. 阶段编号永不重置：下一里程碑从{{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 tag（git 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