尧图网站设计 尧图网站设计YAOTU DESIGN
ARTICLE DETAIL

资讯详情

深耕网站设计与一线实操的经验洞察。

get-shit-done Backlog 治理指南:用 /gsd:review-backlog 将 999.x 积压项晋级为里程碑阶段

get-shit-done Backlog 治理指南:用 /gsd:review-backlog 将 999.x 积压项晋级为里程碑阶段 get-shit-done Backlog 治理指南用 /gsd:review-backlog 将 999.x 积压项晋级为里程碑阶段【免费下载链接】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项目中的 commands/gsd/review-backlog.md 命令规范完整讲解其999.x积压Backlog评审与晋级机制。你将掌握Backlog 项为何使用 999.x 编号、如何列出并逐个评审积压项、如何将它们安全地Promote晋级进活跃里程碑序列、如何清理过期条目以及底层 gsd-sdk 查询如何保证编号不冲突与 ROADMAP.md 一致性。Backlog 的由来为什么要用 999.x 停放未就绪想法GSD 的规划空间.planning/默认把“尚未准备好进入主动规划”的想法统一停放在 ROADMAP.md 的## Backlog区块并把它们排除在活跃阶段序列之外。编号上约定使用999.x而非普通递增编号是为了让这些条目不会占用01-99的正式里程碑阶段号。在 docs/FEATURES.md 中这一机制被明确为产品需求REQ-BACKLOG-01/02/03/04Backlog 项必须使用 999.x 编号以保持在活跃阶段序列之外Backlog 的阶段目录必须立即创建使得/gsd:discuss-phase与/gsd:plan-phase可以直接对其工作/gsd:review-backlog必须支持对每个条目的 promote / keep / remove 三种动作被晋级的条目必须被重新编号进入活跃里程碑序列。与“Review”命令配套的是写入侧的 get-shit-done/workflows/add-backlog.md它由/gsd:capture --backlog触发先读取.planning/ROADMAP.md用gsd-sdk query phase.next-decimal 999 --raw计算下一个积压编号尚无任何 999.x 时返回999.1稀疏编号是允许的例如 999.1、999.3再先写 ROADMAP 条目、后建目录、最后提交。这意味着 Backlog 目录与 ROADMAP 条目是成对存在的而/gsd:review-backlog正是这一流程的反向治理环节。从源码侧也可以确认 999.x 的“隔离”是贯穿全程的约定get-shit-done/bin/lib/init.cjs 中明确“跳过 999.x Backlog 阶段——它们是停放的想法不是活跃工作”/^999(?:\.|$)/并在完成度统计时排除 Backlog 阶段issue #2129。get-shit-done/bin/lib/phase.cjs 在多个编号计算/整理逻辑中if (num 999) continue;将 999.x 视为活跃编号之外的“孤儿”。get-shit-done/bin/lib/milestone.cjs 收集阶段目录时同样过滤掉/^999(?:\.|$)/的目录。也就是说Backlog 项的目录与条目虽然存在于 ROADMAP 与.planning/phases/下但绝不会被当作下一个正式阶段来计算——直到通过评审被主动晋级为止。命令契约触发条件与可用工具review-backlog在仓库中以 slash-command 形式注册其契约见 commands/gsd/review-backlog.md 的 frontmatter字段值说明namegsd:review-backlog命令全名调用时写作/gsd:review-backlogdescriptionReview and promote backlog items to active milestone审查并把积压项提升为活跃里程碑allowed-toolsRead,Write,Bash,AskUserQuestion评审过程需要读文件、改文件、跑命令并通过交互提问征询用户决策requires[phase, review]依赖 phase阶段与 review评审相关上下文就绪该命令的客观目标是审查全部 999.x Backlog 项选择性地将其晋级promote到活跃里程碑序列或删除remove过期条目。它并不负责“新建积压项”——那是/gsd:capture --backlog的职责两者一写一审构成 Backlog 的完整闭环。完整工作流从列目录到输出评审报告/gsd:review-backlog的执行被组织为 7 个步骤命令规范中给出了可直接执行的示例命令。第 1 步列出 Backlog 项Backlog 阶段目录统一存放在.planning/phases/下且以999开头。通过一条防御性 shell 命令即可列出全部积压目录ls -d .planning/phases/999* 2/dev/null || echo No backlog items found2/dev/null抑制“目录不存在”的错误||分支保证即使没有任何积压项也不会让命令失败而是输出可读提示。注意目录名遵循与普通阶段一致的约定例如999.1-idea-slug如果项目在.planning/config.json配置了project_code如CK目录还会带上前缀如CK-999.1-idea-slug这与所有阶段创建路径保持一致见 add-backlog 工作流对generate-slug、config-get project_code的使用。第 2 步读取 ROADMAP 并整理每项上下文随后读取.planning/ROADMAP.md从其中提取全部 999.x 条目cat .planning/ROADMAP.md这一步需要为每一个积压项汇总编号与描述、阶段目录内累积的上下文制品如*-CONTEXT.md的用户决策、*-RESEARCH.md的调研结论参见 get-shit-done/workflows/review.md 中“读取 init.phase-op 拿到 phase_dir / phase_number再读取 CONTEXT.md / RESEARCH.md”的同一套制品发现方式以及创建时间。由于 Backlog 项“累积上下文”的特性正是这些制品构成了评审是否应该晋级的依据。第 3 步通过 AskUserQuestion 呈现决策命令不能自作主张晋级或删除任何 Backlog 项——它必须把候选列表呈现给用户并为每一项提供三选一决策这正是 frontmatter 中声明AskUserQuestion工具的原因Promote晋级移入活跃里程碑序列Keep保留留在 Backlog 中继续停放Remove删除从 Backlog 与磁盘中清除。向用户展示的内容应至少包含阶段编号999.x、描述、已累积的制品清单。这是一个人工决策关口human-in-the-loop避免 AI 自动把未就绪的想法带入正式规划。第 4 步Promote 晋级操作对于被选为Promote的条目核心问题是“如何在不破坏活跃序列连续性的前提下把它变为正式阶段”。命令规范给出的策略分四件事在活跃里程碑中找到下一个顺序阶段号。这一步的关键是调用底层查询句柄让系统自行计算下一个编号而不是人工猜测。规范中给出的命令是NEW_NUM$(gsd-sdk query phase.add ${DESCRIPTION} --raw)这一调用命中的正是 sdk/src/query/phase-lifecycle.ts 中的phaseAdd句柄注册于 sdk/src/query/command-family-handlers.tsphase.add: phaseAdd。从源码实现phase-lifecycle.ts#L88-L233可以确认其行为多个位置参数以单个空格拼接为 description多词描述如phase add User Dashboard不会丢失--raw会被剥离而不会混入描述未知--flag一律以校验错误拒绝description 为必填空描述抛出GSDError(description required for phase add)通过读取当前活跃里程碑内容与.planning/phases/目录名集合调用computeNextSequentialPhaseId计算出下一个顺序阶段号目录命名受.planning/config.json的phase_namingsequential或自定义模式与project_code前缀影响slug 由 description 生成真实写入路径会持有 ROADMAP 写锁readModifyWriteRoadmapMd在“读→计算→写”全程加锁避免两个并发的phase.add观察到同一 maxPhase 而产生重复编号新阶段目录创建.gitkeep以保证空目录被 git 跟踪并把新条目插入到 ROADMAP 中最后一个\n---分隔符之前或文件末尾。把目录从999.x-slug重命名为{new_num}-slug。晋级后目录名必须与新的正式编号保持一致使后续/gsd:discuss-phase、/gsd:plan-phase、完成度统计等逻辑能正确识别它——这些逻辑统一依赖目录前缀作为阶段的“身份”而 999 前缀的排除规则见 init.cjs / phase.cjs / milestone.cjs只有在目录不再以 999 开头后才会将其纳入活跃核算。把已累积的制品移动到新阶段目录。Backlog 期间通过 discuss / plan 累积的*-CONTEXT.md、*-RESEARCH.md等制品必须随目录一起迁移保证“晋级”不会丢失既有调研与用户决策。同步更新 ROADMAP.md把该条目从## Backlog区块移动到活跃阶段列表移除(BACKLOG)标记并补充合适的**Depends on:**字段。之所以要补依赖字段是因为正式阶段是有序、有依赖的参见 get-shit-done/templates/roadmap.md 中**Depends on**: Nothing (first phase)/**Depends on**: Phase 1的骨架写法而 Backlog 项“本质上是无序的、没有 Depends on 字段”add-backlog 工作流的 notes 中明确这一点。第 5 步Remove 删除操作对于被选为Remove的条目需要做两件事保证磁盘与文档保持一致删除阶段目录.planning/phases/999.x-slug从 ROADMAP.md 的## Backlog区块移除对应条目。第 6 步提交变更所有变更无论晋级还是删除都需要统一落入一次文档提交中以保持规划空间的可追溯性gsd-sdk query commit docs: review backlog — promoted N, removed M --files .planning/ROADMAP.mdgsd-sdk query commit是 GSD SDK 的提交查询配合--files只提交规划文档变更避免把工作区其它无关改动一起卷入。第 7 步汇报评审结果命令最后向用户输出结构化汇总## Backlog Review Complete Promoted: {list of promoted items with new phase numbers} Kept: {list of items remaining in backlog} Removed: {list of deleted items}三份清单分别对应 Promote / Keep / Remove 的最终落盘结果晋级项需要列出新阶段号保留项仍在999.x区间删除项则彻底消失。晋级语义的底层验证phase.add 的返回值与落盘细节gsd-sdk query phase.add --raw之所以能充当“寻找下一个顺序阶段号”的权威手段是因为其返回值直接来自对 ROADMAP 与目录的实时计算。phaseAdd在非 dry-run 模式下返回结构phase-lifecycle.ts#L218-L232包括字段含义phase_number新阶段编号数字转字符串后padded左补零的编号如05用于目录与文件命名name阶段的描述文本slug由描述生成的目录 slug 片段directory相对项目根的新阶段目录路径naming_modeconfig.phase_naming的实际取值默认sequential在 dry-run--dry-run模式下还会额外返回dry_run: true与roadmap_entry即将写入的 ROADMAP 条目方便在真正写入前预览编号与条目内容。并发安全方面readModifyWriteRoadmapMd的路由级写锁保证两个并发phase.add不会看到同一个最大阶段号——这正是把“自动分配下一个编号”委托给 SDK 而不是由 Agent 手工数编号的根本原因。与相邻命令的分工capture、discuss、plan 与 review要把 review-backlog 放在整个 GSD 工作流里理解可以参考 get-shit-done/workflows/help/modes/full.md 等文档对命令族的组织。Backlog 相关的生命周期大致是捕获/gsd:capture --backlog 描述把想法写入## Backlog调用 add-backlog 工作流产生999.x条目与目录孕育/gsd:discuss-phase 999.x与/gsd:plan-phase 999.x在积压目录内累积*-CONTEXT.md、*-RESEARCH.md等制品评审/gsd:review-backlog定期清理这一“停车区”parking lot把成熟的想法晋级为正式阶段、删除过期的想法。该流程的正确性在测试中有覆盖例如 tests/bug-3135-capture-backlog-workflow.test.cjs 验证了 capture backlog 工作流与后续 review-backlog 提示的衔接tests/roadmap.test.cjs 则覆盖 ROADMAP 结构解析与 Backlog 相关条目的处理。总结与最佳实践永远不要手工猜测下一个 999.x 或正式阶段号加 Backlog 用phase.next-decimal 999晋级用phase.add两者都由 SDK 基于当前 ROADMAP 与目录实时计算并加锁写入天然避免编号冲突尤其稀疏编号如 999.1、999.3 时。磁盘与 ROADMAP 必须成对变更无论是 capture 的“先写条目后建目录”还是 review-backlog 的“改名目录 移动制品 移动条目 去掉 (BACKLOG) 补 Depends on”都要求在文件系统与文档之间保持一致任何一边的滞后都会破坏后续统计与钩子检测。晋级是人工决策review-backlog 通过 AskUserQuestion 逐项征询 Promote / Keep / Remove绝不自动删除用户想法也绝不让未就绪想法悄悄进入正式序列。提交保持原子用gsd-sdk query commit --files .planning/ROADMAP.md单独提交规划变更保持仓库历史清晰。至此你已经可以完整地理解并执行一次 Backlog 治理列出 999.x 积压项 → 读取 ROADMAP 与累积制品 → 逐项三选一 → 晋级者重编号并迁移、删除者清理 → 原子提交 → 输出三清单报告。【免费下载链接】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),仅供参考
返回列表