GSD 规范化工件注册表get-shit-done 的.planning工件契约与 W019 校验机制全解【免费下载链接】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-done/templates/README.mdGSD Canonical Artifact Registry 的权威索引为核心骨架系统讲解 get-shit-doneGSD一个面向 Claude Code 的轻量级 meta-prompting 与规格驱动开发系统中哪些.planning/文件是官方承认的规范化工件、它们由哪个命令产出、存放于哪个层级这一整套工件契约并下沉到artifacts.cjs、verify.cjs、health工作流与测试用例的源码实现层面。读完你将能(1) 一眼判定某个.planning/根文件是否为官方工件避免gsd-health的 W019 告警(2) 理解阶段子目录工件与里程碑归档的命名与职责分工(3) 掌握为 GSD 新增一个规范化工件时需要同步修改的全部位置。1. 背景为什么 GSD 需要一份工件权威索引GSD 以 spec-driven规格驱动方式把一次软件开发组织为PROJECT.md → ROADMAP.md → 分阶段 PLAN/SUMMARY → 里程碑归档的完整产物链所有产物都集中在项目根目录的.planning/下。产物的命名与存放位置一旦失控例如随手在.planning/根目录放了MY-NOTES.md、scratch.md之类的散记就会污染 Agent 与 Reviewer 对当前规划状态的认知——它们无法判断哪个文件是活的权威工件、哪个只是临时草稿。因此templates/README.md被定位为权威索引authoritative index它列出的文件就是 GSD 工作流官方产出的全部工件。文档原话强调了两条硬约束若某个.planning/根文件不在该表中gsd-health会将其标记为 W019unrecognized artifact未识别工件Agent 在把某个.planning/文件当作权威依据之前必须先查询本文件若文件名未出现在下面它就不是 GSD 的规范化工件。换言之这份 README 既是一张文件清单更是一份运行时会被真实验证、并在测试中被强制保持同步的契约文档——它并非装饰性的说明。2..planning/根工件GSD 项目身份的顶层契约以下文件直接位于.planning/根目录不在任何 phase 子目录内是 W019 唯一的检查范围。表格完整收录自 templates/README.md并补充了各自模板在仓库中的实际路径文件模板产出命令职责PROJECT.mdproject.md/gsd:new-project项目身份、目标、需求摘要ROADMAP.mdroadmap.md/gsd:new-milestone、/gsd:new-project分阶段计划、里程碑与进度跟踪STATE.mdstate.md/gsd:new-project、/gsd:health --repair当前会话状态、活动阶段、最近活动REQUIREMENTS.mdrequirements.md/gsd:new-milestone带可追溯性的功能需求MILESTONES.mdmilestone.md/gsd:complete-milestone已完成里程碑及其成就的日志BACKLOG.md(inline无独立模板)/gsd-add-backlog待办想法与延期工作LEARNINGS.md(inline)/gsd:extract-learnings、/gsd:execute-phase阶段复盘经验供后续计划复用THREADS.md(inline)/gsd:thread持久化讨论线程config.jsonconfig.json/gsd:new-project、/gsd:health --repair项目级 GSD 配置CLAUDE.mdclaude-md.md/gsd-profile自动装配的 Claude Code 上下文文件RETROSPECTIVE.md(inline)/gsd:complete-milestone随每个里程碑关闭持续更新的复盘文档2.1 根工件的角色定位身份、状态、需求三件套从职责划分可以清晰看到根目录工件的分工逻辑PROJECT.md回答做什么。以 project.md 模板为例它要求维护What This Is当前准确描述2–3 句话、Core Value唯一最重要的事作为取舍时的优先级标尺、Requirements细分为 Validated / Active / Out of Scope 三档其中 Validated 一旦锁定改动需要显式讨论、Context、Constraints、Key Decisions并在文档末尾记录Last updated时间与触发原因。它还内嵌了演化规则evolution每次阶段过渡后核对哪些需求失效移入 Out of Scope、哪些已验证移入 Validated、哪些新涌现需求加入 Active每次里程碑结束后做全量复审并核对 Core Value 是否仍是正确优先级。STATE.md回答进行到哪。它引用 PROJECT.md 中的 Core Value 与当前阶段聚焦点例如模板中规定的## Project Reference段See: .planning/PROJECT.md (updated [date])加一行 Core Value 与 Current focus确保 Claude 每次会话都读取到最新 PROJECT.md 上下文。config.json回答如何工作。项目级配置模板见 get-shit-done/templates/config.json覆盖了mode如interactive、granularity如standard、workflow.*research、plan_check、verifier、auto_advance、nyquist_validation、security_enforcement 与 asvs 级别、discuss_mode、plan_bounce、cross_ai_execution 等开关、ship.pr_body_sections、planning.commit_docs与search_gitignored、git.create_tag、parallelizationmax_concurrent_agents、min_plans_for_parallel、gates.*逐环节确认闸门、safety.*破坏性与外部服务确认以及project_code、agent_skills、claude_md_path。当配置文件损坏或缺失时/gsd:health --repair会用默认值重建它。2.2 版本戳工件vX.Y-*.md模式除上述精确命名文件外.planning/根目录还存在一类版本戳工件其文件名遵循vX.Y-*.md模式由匹配检测而非精确匹配识别模式产出命令职责vX.Y-MILESTONE-AUDIT.md/gsd:audit-milestone归档前的里程碑审计报告一个重要的健康规则随之而来这些文件应当由/gsd:complete-milestone归档到.planning/milestones/。若在里程碑完成后它们仍停留在.planning/根目录说明归档步骤被跳过Agent 应当据此提示用户。3. 阶段子目录工件.planning/phases/NN-name/内的执行产物以下文件位于某个阶段目录内如.planning/phases/01-foundation/。它们不受 W019 检查——W019 只检查.planning/根目录。注意阶段目录名遵循NN-name的编号规范不符合会触发健康检查中的 W005。文件模式模板产出命令职责NN-MM-PLAN.mdphase-prompt.md/gsd:plan-phase可执行的实现计划NN-MM-SUMMARY.mdsummary.md/gsd:execute-phase执行后总结含经验学习NN-CONTEXT.mdcontext.md/gsd:discuss-phase面向该阶段的讨论决策NN-RESEARCH.mdresearch.md/gsd:plan-phase、/gsd:plan-phase --research-phase N面向该阶段的技术研究NN-VALIDATION.mdVALIDATION.md/gsd:plan-phaseNyquist验证架构Nyquist 方法NN-UAT.mdUAT.md/gsd:validate-phase用户验收测试结果NN-PATTERNS.md(inline)/gsd:plan-phasepattern mapper面向该阶段的类比文件映射NN-UI-SPEC.mdUI-SPEC.md/gsd:ui-phaseUI 设计契约NN-SECURITY.mdSECURITY.md/gsd:secure-phase安全威胁模型NN-AI-SPEC.mdAI-SPEC.md/gsd:ai-integration-phaseAI 集成规格含评测策略NN-DEBUG.mdDEBUG.md/gsd:debug调试会话日志NN-REVIEWS.md(inline)/gsd:review跨 AI 评审反馈3.1 阶段工件 vs 根工件的边界为何重要把产物分成根 阶段两层的直接后果是命名空间的职责隔离根目录只承载跨阶段的规划真相PROJECT / ROADMAP / STATE / REQUIREMENTS阶段目录承载该阶段内的执行证据PLAN / SUMMARY / VALIDATION / UAT / UI-SPEC / SECURITY / AI-SPEC / DEBUG 等。若把阶段文件01-CONTEXT.md、01-01-PLAN.md误放到根目录它们既不符合规范化命名也会在文件重组后造成引用失效。值得注意的是阶段内模板往往有着严格的契约式结构例如NN-UAT.md对应/gsd:validate-phase、NN-SECURITY.md对应/gsd:secure-phase这正是 GSD 让 Agent 在正确阶段产出规范证据的设计体现。4. 里程碑归档.planning/milestones/由/gsd:complete-milestone归档的文件永远不被 W019 检查它们已退出活跃规划区文件模式来源vX.Y-ROADMAP.md里程碑关闭时ROADMAP.md的快照vX.Y-REQUIREMENTS.md里程碑关闭时REQUIREMENTS.md的快照vX.Y-MILESTONE-AUDIT.md从.planning/根目录移入vX.Y-phases/已归档的阶段目录若使用了--archive-phases归档机制同时保证根目录的版本戳审计文件若未移入该目录会被视为归档步骤跳过健康告警来源之一而归档目录自身由于采用vX.Y-*.md版本戳命名与受控子目录也不会与根目录的精确命名发生冲突。5. 机制落地W019 在源码中是如何被实现的templates/README.md描述的契约并不是纸面约定它由两层源码强制执行。5.1 注册表本体get-shit-done/bin/lib/artifacts.cjs该文件维护了两套规范化集合见第 14–33 行CANONICAL_EXACT一个Set包含 11 个.planning/根的精确文件名——PROJECT.md、ROADMAP.md、STATE.md、REQUIREMENTS.md、MILESTONES.md、BACKLOG.md、LEARNINGS.md、THREADS.md、config.json、CLAUDE.md、RETROSPECTIVE.mdCANONICAL_PATTERNS两条正则用于兜底版本戳文件/^v\d\.\d(?:\.\d)?-MILESTONE-AUDIT\.md$/i如v1.0-MILESTONE-AUDIT.md、v2.3.1-MILESTONE-AUDIT.md/^v\d\.\d(?:\.\d)?-.*\.md$/i其他版本戳规划文档。对外接口是isCanonicalPlanningFile(filename)第 41–47 行它只接收不带路径的 basename先查精确集合再依次跑模式正则任一命中即返回true。注意该函数把NN-CONTEXT.md、NN-MM-PLAN.md等阶段级文件判定为false——它们归属于phases/子目录不属于根目录注册范畴。新增一个根级规范化工件的第一步就是向CANONICAL_EXACT添加条目。5.2 校验触发点get-shit-done/bin/lib/verify.cjs 的 Check 13W019 的实际告警发生在 verify.cjs 的Check 13Unrecognized.planning/root files。其逻辑可概括为读取.planning/目录条目fs.readdirSync(planBase, { withFileTypes: true })仅取.md文件且跳过目录对每个文件调用isCanonicalPlanningFile(entry.name)不命中则addIssue(warning, W019, ...)并给出修复指引文案Move to.planning/milestones/archive subdir or delete if stale. Seetemplates/README.mdfor the canonical artifact list.两个值得注意的实现细节W019 的repairable标记为false——即它无法被/gsd:health --repair自动修复。这是刻意为之文件属于手写散记还是过期产物机器无法安全判断只能人工移入归档或删除见同文件底部 repair_actions 中Not repairabletoo risky策略家族的思路。这与可修复的 E004重建 STATE.md、W018用--backfill从归档快照回填 MILESTONES.md形成对比。外层有try/catch且注释明确 artifact check is advisory — skip on error因此该检查在目录不可读等异常下不会拖垮整个健康检查。5.3 工作流视角get-shit-done/workflows/health.md在 Agent 工作流层面health.md 定义了/gsd:health的执行方式它通过gsd-sdk query validate.health调用底层校验并解析 JSON 输出status/errors[]/warnings[]/info[]/repairable_count/repairs_performed[]随后以━━━分隔的格式化文本呈现Status / Errors / Warnings / Info。在该工作流的错误码表中W019 被正式登记为CodeSeverityDescriptionRepairableW019warningUnrecognized.planning/root file — not a canonical GSD artifactNo同时表内其他代码也印证了工件体系的健康规则如 E004 缺 STATE.md 可修复、W002 状态引用不存在的阶段、W009 有验证架构但没有 VALIDATION.md、W018 归档快照缺少对应 MILESTONES.md 条目等。由于 health 输出默认不含被警告的细节文件名以外的修复动作收到 W019 后应人工裁决文件已过期→删除仍有意保留→移入.planning/milestones/或阶段子目录。5.4 测试对契约的固化tests/enh-2448-artifact-registry.test.cjs该契约被 tests/enh-2448-artifact-registry.test.cjs 用两组用例锁死issue #2448 引入对isCanonicalPlanningFile的单测CANONICAL_EXACT中每个名字都应判定为规范化版本戳文件v1.0-MILESTONE-AUDIT.md、v2.3.1-MILESTONE-AUDIT.md通过模式匹配MY-NOTES.md、scratch.md、random-output.md判定为false阶段级文件01-CONTEXT.md、01-01-PLAN.md在根目录层面判定为false它们只属于phases/。对gsd-healthW019 的集成测试在临时项目里放置.planning/MY-NOTES.md后运行cmdValidateHealth应产出W019、消息中包含该文件名、且repairable false只有规范化文件时无 W019.planning/phases/01-foundation/01-01-PLAN.md不会触发 W019仅检查根目录版本戳v1.0-MILESTONE-AUDIT.md不触发 W019多个未识别文件产生与文件数等量的 W019最后一条用例直接断言templates/README.md存在、且必须同时包含W019、artifacts.cjs、PROJECT.md字样——即本文档与注册表源码、健康检查告警三者被测试强制保持同步任何一边脱节都会让测试失败。6. 为 GSD 新增一个规范化工件标准流程当一个新的工作流开始在.planning/根目录产出文件时README 给出了三步收口动作注册把文件名加入 get-shit-done/bin/lib/artifacts.cjs 的CANONICAL_EXACT若走模式匹配则补一条CANONICAL_PATTERNS正则建档在上文的.planning/Root Artifacts表中增加一行文件、模板、产出命令、职责四列对齐配模板如果该工件存在对应模板把模板文件放入 get-shit-done/templates/ 目录。补记三条实践建议结合源码推得若新增的是阶段级工件如NN-*.md由于 W019 只扫根目录你并不需要改CANONICAL_EXACT但仍建议在Phase Subdirectory Artifacts表中登记让 Agent 知道该阶段文件的模板与产出命令。新增根工件会同步放大验证面tests/enh-2448-artifact-registry.test.cjs会对CANONICAL_EXACT全量断言因此第 1 步注册后应确保该测试通过并同步更新测试中BASE_FILES之类的样本如需要。命名与归属要保持一致可被正则匹配的版本戳文件vX.Y-*只应作为待归档工件短暂出现在根目录确认关闭后请交给/gsd:complete-milestone归档避免与归档步骤被跳过的告警纠缠。7. 把契约当工具对 Agent 与人的使用建议综合上述内容这份注册表文档在日常使用中的价值可以收敛为三条可直接落地的操作准则先查表再当真无论你是 Claude Code 会话、reviewer 还是人在把.planning/下某个文件当作权威依据前先对照 templates/README.md 的三个表格确认它是否为官方工件。表中未出现的根文件要么是待归档的过期版本应移入.planning/milestones/要么是应删除的散记。用健康检查做常态化兜底对每个项目定期运行/gsd:health不带--repair先看诊断让 W019 帮你发现悄悄混入根目录的非规范.md涉及 STATE.md / config.json 缺失等可修复项时再运行/gsd:health --repair。若需要针对某个里程碑补全归档记录--backfill会从.planning/milestones/vX.Y-ROADMAP.md快照合成缺失条目。扩展时三处同步为项目贡献新的规范化工件时牢记注册表artifacts.cjs→ 索引表templates/README.md→ 模板目录templates/三位一体、缺一不可——而 enh-2448 测试 会替你验证这份同步是否真的完成。把.planning/视作项目的规划事实库把templates/README.md视作该事实库的 schema 与数据字典GSD 的 Agent 协作就不会在哪个文件才是权威上产生分歧——这正是这套工件注册表设计最核心的价值所在。【免费下载链接】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），仅供参考