get-shit-done 项目生命周期指挥中心：`gsd-project` 命名空间路由器与里程碑全流程实战指南

2026-09-07 13:30:06作者：邬祺芯Juliet

本指南围绕 get-shit-done（GSD）中承担“项目生命周期入口”角色的命名空间路由器 gsd-project（源文件 commands/gsd/ns-project.md）展开，讲解它如何把“新项目 / 新里程碑 / 审计 / 完成 / 汇总”五类用户意图路由到正确的子技能，并逐层拆解其背后由 gsd-new-project、gsd-new-milestone、gsd-audit-milestone、gsd-complete-milestone、gsd-milestone-summary 构成的里程碑闭环工作流。读完本文，你将掌握如何在 Claude Code 中通过一条 /gsd-project 入口驾驭完整 spec-driven 交付周期，并理解路由器与底层工作流、模板及 .planning/ 规划工件的协作方式。

gsd-project 是什么：把五类意图路由到正确的子技能

ns-project.md 属于 get-shit-done 的命令文件（位于仓库 commands/gsd/ 下，仓库另一侧还有同名运行时工作流目录 get-shit-done/workflows/）。它的文件名叫 ns-project.md，但 frontmatter 中声明的命令名是 gsd-project，description 明确点出职责范围：project lifecycle | milestones audits summary。

与普通命令不同，它是一个“零参数”的命名空间路由器（namespace router / meta-skill）：

---
name: gsd-project
description: "project lifecycle | milestones audits summary"
argument-hint: ""
allowed-tools:
  - Read
  - Skill
---

注意两点设计细节：

allowed-tools 只开放 Read 与 Skill：路由器自身不做业务操作，不写文件、不跑 git、不调 Agent，只负责“读懂意图 → 读入匹配的 Skill 定义 → 用 Skill 工具直接唤起目标技能”。真正的重型执行全部下沉到各子技能及其引用的 workflow。
加性设计：正如 docs/COMMANDS.md 所强调，命名空间技能是“additive”的——即使存在 /gsd-project 路由器，/gsd-plan-phase、/gsd-code-review --fix 等所有既有具体命令仍然可以直接调用，两条路径并行不悖。

路由器的全部逻辑就是下面这张意图映射表（原文见 commands/gsd/ns-project.md）：

用户想做什么	触发子技能
开启一个新项目（Start a new project）	gsd-new-project
创建新里程碑（Create a new milestone）	gsd-new-milestone
完成当前里程碑（Complete the current milestone）	gsd-complete-milestone
审计里程碑问题（Audit a milestone for issues）	gsd-audit-milestone
汇总里程碑状态（Summarize milestone status）	gsd-milestone-summary

该表还记录了一条重要的命令演进历史：gsd-plan-milestone-gaps 已因 #2790 被删除，里程碑的 gap 规划不再作为独立命令存在，而是内联成为 gsd-audit-milestone 输出的一部分。

为什么需要命名空间路由器：token 成本与命令面收敛

在 get-shit-done 的命令架构中，类似 gsd-project 的路由器共有六个：ns-context（代码库情报）、ns-ideate（探索与捕获）、ns-manage（工程管理）、ns-project（项目生命周期）、ns-review（质量门禁）、ns-workflow（阶段管线）。

从源码看，这六个路由器被登记在 get-shit-done/bin/lib/clusters.cjs 的 ns_meta 集群中：

ns_meta: Object.freeze([
  'ns-context',
  'ns-ideate',
  'ns-manage',
  'ns-project',
  'ns-review',
  'ns-workflow',
]),

引入这套分层机制的核心收益是降低上下文窗口中的技能清单 token 成本。docs/COMMANDS.md 给出的量化依据是：6 个路由器首屏平铺仅约 120 token，而把所有 86 个技能扁平列出需要约 2,150 token。模型先凭低开销选中命名空间，再在需要时展开具体子技能，实现了“命令面完整可及 + 首屏开销可控”的平衡。

命令拼写随运行时而异

同一命令在不同 AI 客户端中有不同的拼写形式（见 docs/COMMANDS.md）：

Claude Code / Copilot / OpenCode / Kilo：连字符形式 /gsd-project、/gsd-new-project
Gemini CLI：冒号形式 /gsd:project、/gsd:new-project（命令文件 frontmatter 里的 name: gsd-project 即冒号风格的规范化写法）
Codex：$gsd-project、$gsd-new-project

安装器会根据实际运行时把正确形式写入对应命令目录，用户无需记忆差异。这些形式本质上都是同一个命令的不同拼法。

深入五个子技能：从新项目到归档的完整闭环

下面依次展开路由器映射的五个目标技能。它们的命令定义位于 commands/gsd/ 下的同名文件，完整执行逻辑则委托给 get-shit-done/workflows/ 下的对应 workflow。

1. gsd-new-project：从提问到路线图的一次性初始化

定义文件：commands/gsd/new-project.md。description：以深度上下文收集和 PROJECT.md 初始化一个新项目。参数提示 [--auto]。

它驱动的是一条统一流程：questioning（提问） → research（研究，可选） → requirements（需求） → roadmap（路线图）。作为初始化命令，它要求前置条件“不存在既有 .planning/PROJECT.md”（对应 docs/COMMANDS.md 的 Prerequisites 说明），并在结束时生成一组规划工件：

.planning/PROJECT.md —— 项目上下文
.planning/config.json —— 工作流偏好
.planning/research/ —— 领域研究（可选）
.planning/REQUIREMENTS.md —— 收敛后的需求范围
.planning/ROADMAP.md —— 阶段（phase）结构
.planning/STATE.md —— 项目记忆

命令行参数（来自命令文件 <context> 区块）：

参数	含义
`--auto`	自动模式。配置提问结束后，无需人工交互直接依次运行 research → requirements → roadmap；此时期望通过 `@` 引用一份想法文档（idea document）作为输入

典型用法（交互模式与自动模式）：

/gsd-new-project                    # 交互模式
/gsd-new-project --auto @prd.md     # 从 PRD 自动抽取，跳过交互提问

注意点：

命令执行时加载的上下文文件包括 get-shit-done/workflows/new-project.md、get-shit-done/references/questioning.md、get-shit-done/references/ui-brand.md 以及 get-shit-done/templates/project.md、get-shit-done/templates/requirements.md 等模板。
命令结束后并不直接开写代码，而是提示用户运行 /gsd:plan-phase 1 进入阶段 1 的规划（对应 After this command: Run /gsd:plan-phase 1 to start execution.）。
若运行在 VS Code Copilot 环境，workflow 中所有调用 AskUserQuestion 之处应等价替换为 vscode_askquestions（见命令文件的 <runtime_note>）。
frontmatter 的 requires: [config, phase, plan-phase] 声明了对配置、阶段操作与阶段规划命令的依赖。

2. gsd-new-milestone：存量项目开启下一轮迭代

定义文件：commands/gsd/new-milestone.md。参数提示形如 [milestone name, e.g., 'v1.1 Notifications']，即里程碑名可不传、随后交互询问。

它被定义为 new-project 的 Brownfield 等价物（改造型项目入口）：项目已存在、PROJECT.md 已有历史，因此不再重复全量初始化，而是“收集 What's next → 更新 PROJECT.md → 走 requirements → roadmap 循环”。关键差异：

.planning/PROJECT.md —— 追加新里程碑目标（更新而非重建）
.planning/research/ —— 仅当引入新功能时可选做领域研究
.planning/REQUIREMENTS.md —— 为当前里程碑收敛需求（全新生成）
.planning/ROADMAP.md —— 追加阶段结构，继续沿用既有编号序列
.planning/STATE.md —— 为新里程碑重置

依赖链 requires: [new-project, phase, plan-phase] 说明它假定已存在可承接的 new-project 成果，之后同样以 /gsd:plan-phase [N] 开启执行。它复用 get-shit-done/workflows/new-milestone.md 及与 new-project 相同的 references/templates，在子代理介入时通过 <files_to_read> 区块解析项目与里程碑上下文文件后做委派。

3. gsd-audit-milestone：归档前的“完成定义”校验

定义文件：commands/gsd/audit-milestone.md。参数 [version] 可选，缺省时以当前里程碑为准。职责：在里程碑归档之前，验证它是否达成自己的 Definition of Done——具体检查三项：需求覆盖度（requirements coverage）、跨阶段集成（cross-phase integration）、端到端流程（end-to-end flows）。

命令自身的 <objective> 强调它是编排者（orchestrator）而非执行者：

读取各阶段在 execute-phase 期间已生成的 VERIFICATION.md（校验工作其实在阶段内已由 verify 完成）；
聚合技术债与延后的缺口（tech debt and deferred gaps）；
为跨阶段接线（cross-phase wiring）派生 integration checker（集成检查）进一步核查。

它通过 glob 读取已完成工作产物：

Glob: .planning/phases/*/*-SUMMARY.md
Glob: .planning/phases/*/*-VERIFICATION.md

底层工作流见 get-shit-done/workflows/audit-milestone.md。需要特别留意 #2790 之后的约定：审计输出中会逐一枚举未满足的需求、跨阶段问题与断裂流程；若审计发现缺口，不必再找已被删除的 gsd-plan-milestone-gaps 命令，而是直接依据审计枚举的缺口，用 /gsd:phase --insert <N> 插入收尾阶段，再跑标准的 discuss/plan/execute 链，或将缺口显式记为技术债接受。

4. gsd-complete-milestone：归档、打 tag、准备下一版

定义文件：commands/gsd/complete-milestone.md。参数 <version> 必填（如 1.0、1.1、2.0），作用是把 {{version}} 标记为完成、归档到 milestones/、并同步更新 ROADMAP.md 与 REQUIREMENTS.md。

第 0 步是强制性的审计前置检查。命令会查找 .planning/v{{version}}-MILESTONE-AUDIT.md，并按三种状态分流（命令内置了可直接呈现的 Markdown 检查块）：

审计文件状态	动作
缺失或过期	⚠ 提示先跑 `/gsd:audit-milestone` 验证需求覆盖、跨阶段集成与 E2E 流程
`gaps_found`	⚠ 按审计枚举的缺口用 `/gsd:phase --insert <N>` 插入收尾阶段并走 discuss→plan→execute 链；或显式接受缺口作为技术债继续推进
`passed`	✓ 放行进入归档流程

归档流程八步（命令 <process> 的完整骨架）：

校验就绪度：确认里程碑内所有阶段都已生成规划（存在 SUMMARY.md），展示范围与统计并等待用户确认；
收集统计：统计阶段/规划/任务数，计算 git 变更区间、文件改动量、LOC，从 git log 抽取时间线，展示后确认；
提炼成果：读取里程碑范围内全部阶段 SUMMARY.md，提炼 4–6 条关键成就，交付用户审批；
归档里程碑：创建 .planning/milestones/v{{version}}-ROADMAP.md，从 ROADMAP.md 抽取完整阶段细节并按 get-shit-done/templates/milestone-archive.md 填充，然后把 ROADMAP.md 压成一行摘要加链接；
归档需求：创建 .planning/milestones/v{{version}}-REQUIREMENTS.md，把该版本全部需求勾选完成，标注每个需求的结局（validated / adjusted / dropped），随后删除 .planning/REQUIREMENTS.md（为下一里程碑让路）；
更新 PROJECT.md：新增 “Current State” 段（已发布版本）与 “Next Milestone Goals” 段，v1.1 起的历史内容折叠进 <details>；
提交并打 tag：stage MILESTONES.md / PROJECT.md / ROADMAP.md / STATE.md 及归档文件，提交信息 chore: archive v{{version}} milestone，执行 git tag -a v{{version}} -m "[milestone summary]"（是否推送 tag 需询问用户，且仅在 git.create_tag 启用时创建），最后提交；
提供下一步：引导 /gsd:new-milestone 开启下一里程碑。

成功标准与关键规则（<success_criteria> / <critical_rules>）摘要：里程碑与需求必须归档到 milestones/；REQUIREMENTS.md 需删除以便下版全新编写；ROADMAP.md 压缩为单行条目；PROJECT.md 记录当前状态；git tag 建立；所有阶段必须已有 SUMMARY.md 才能归档；先归档再删除（Always create archive files before updating/deleting originals）。

值得单独指出的是 context efficiency 设计动机：通过归档，ROADMAP.md 与 REQUIREMENTS.md 在每个里程碑内都能保持近似恒定大小，避免规划文档随版本无限膨胀挤占上下文。完整工作流在 get-shit-done/workflows/complete-milestone.md。

5. gsd-milestone-summary：让新成员“读一份文档就能接手”

定义文件：commands/gsd/milestone-summary.md。参数 [version] 可选（缺省解析当前/最新里程碑）。目标是为团队 onboarding 与项目评审生成结构化里程碑总结：读取已完成里程碑的全部工件（ROADMAP、REQUIREMENTS、CONTEXT、SUMMARY、VERIFICATION 等），产出“做了什么、怎么做、为什么”的人性化概述，使新成员通过阅读单份文档加追问即可理解整个项目。

其读取的输入工件完整清单包括：

.planning/ROADMAP.md、.planning/PROJECT.md、.planning/STATE.md、.planning/RETROSPECTIVE.md
.planning/milestones/v{version}-ROADMAP.md 与 v{version}-REQUIREMENTS.md（若已归档）
.planning/phases/*-*/ 下的 SUMMARY.md、VERIFICATION.md、CONTEXT.md、RESEARCH.md

成功标准要点（见命令 <success_criteria>）：版本从参数/STATE.md/归档扫描解析；产出文档写入 .planning/reports/MILESTONE_SUMMARY-v{version}.md；生成全部 7 个章节——Overview、Architecture、Phases、Decisions、Requirements、Tech Debt、Getting Started；总结内联展示并提供交互式问答；同步更新 STATE.md。底层编排在 get-shit-done/workflows/milestone-summary.md。

串联起来：一条可执行的里程碑生命周期流水线

把路由表映射的五个技能按真实使用顺序拼装，就得到完整闭环。以 .planning/ 规划目录的演化为主线：

[新项目]                                [改造型新迭代]
gsd-new-project                  ┌─── gsd-new-milestone "v1.1 ..."
  └→ PROJECT.md / config.json    │      └→ 更新 PROJECT.md
       REQUIREMENTS.md           │           REQUIREMENTS.md（新）
       ROADMAP.md / STATE.md     │           ROADMAP.md（续编号）
            │                    │           STATE.md（重置）
            ▼                    ▼
    /gsd:plan-phase 1 → /gsd:execute-phase …（每阶段产出 SUMMARY.md / VERIFICATION.md）
            │
            ▼
    gsd-audit-milestone（有缺口 → gsd:phase --insert <N> 补收尾阶段后重审）
            │
            ▼
    gsd-complete-milestone v1.0
      └→ milestones/v1.0-{ROADMAP,REQUIREMENTS}.md 归档；git tag v1.0
            │
            ▼
    gsd-milestone-summary v1.0 → .planning/reports/MILESTONE_SUMMARY-v1.0.md（团队 onboarding）
            │
            ▼
    回到 gsd-new-milestone，进入 v1.1 循环

各阶段工件对应的命令定义与运行时 workflow 汇总如下，便于按需查阅：

子技能	命令定义	运行时工作流	关键产物
新项目	commands/gsd/new-project.md	get-shit-done/workflows/new-project.md	`PROJECT.md`、`REQUIREMENTS.md`、`ROADMAP.md`
新里程碑	commands/gsd/new-milestone.md	get-shit-done/workflows/new-milestone.md	续编号的 `ROADMAP.md`、全新 `REQUIREMENTS.md`
里程碑审计	commands/gsd/audit-milestone.md	get-shit-done/workflows/audit-milestone.md	审计报告 + 内联缺口清单
完成里程碑	commands/gsd/complete-milestone.md	get-shit-done/workflows/complete-milestone.md	`milestones/v{V}-ROADMAP.md` 等归档 + git tag
里程碑汇总	commands/gsd/milestone-summary.md	get-shit-done/workflows/milestone-summary.md	`reports/MILESTONE_SUMMARY-v{V}.md`（7 章节）

配套的上下文模板位于 get-shit-done/references/questioning.md、get-shit-done/references/ui-brand.md，文档模板位于 get-shit-done/templates/project.md、get-shit-done/templates/requirements.md、get-shit-done/templates/milestone-archive.md。

延伸阅读与源码证据

想要验证或深入这套机制的读者，建议按以下路径阅读：

路由器本体与命名空间约定：commands/gsd/ns-project.md 是最简实现样本；对照 commands/gsd/ns-context.md、commands/gsd/ns-manage.md、commands/gsd/ns-workflow.md 可以看到同样式路由器的意图表，以及 #2790 中 gsd-scan/gsd-intel、gsd-config/gsd-workspace 等命令被合并为子技能 flags 的同类演进。
集群登记：get-shit-done/bin/lib/clusters.cjs 的 ns_meta 集群列出全部六个路由器；同文件还可见 milestone 集群（new-milestone、complete-milestone、milestone-summary 等），印证了命令注册与集群的对应关系。
命令参考与特性说明：docs/COMMANDS.md 的 “Namespace Meta-Skills” 章节说明路由器的 token 成本动机与加性设计；docs/FEATURES.md 与 docs/USER-GUIDE.md 提供配套特性与端到端走读。
测试佐证：tests/enh-2792-namespace-skills.test.cjs 覆盖 #2792 引入的命名空间技能契约，可用于确认路由器与子技能间的前置依赖（requires）与调用形式没有被破坏。
运行时制品布局：所有 ns-*.md 命令只允许 Read + Skill，目标技能在执行时才会按需 @ 加载 workflow/reference/template——这种“路由轻、执行重”的分层也是整条里程碑流水线保持上下文可控的关键。