get-shit-done spec-phase 工作流实战用 Socratic 访谈与量化歧义评分锁定可证伪的需求【免费下载链接】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的规格驱动开发体系中spec-phase是位于spec-phase → discuss-phase → plan-phase → execute-phase → verify链条最前端的“锁喉”环节它通过最多 6 轮的苏格拉底式Socratic访谈与四个加权维度的量化歧义评分把“这个阶段到底交付什么、为什么”钉死成一份可证伪的SPEC.md让下游的规划器不会在模糊需求上默默做出错误假设。读完本文你将掌握歧义评分模型的完整公式与门槛、五类访谈视角的轮换策略、--auto/--text等模式的行为差异以及如何从仓库源码与测试中验证这一工作流的设计意图。spec-phase 在 GSD 工作流中的定位分工spec-phase 管 WHATdiscuss-phase 管 HOWget-shit-done/workflows/spec-phase.md的purpose段落开宗明义Clarify WHAT a phase delivers through a Socratic interview loop with quantitative ambiguity scoring. Produces a SPEC.md with falsifiable requirements that discuss-phase treats as locked decisions. This workflow handles what and why — discuss-phase handles how.也就是说spec-phase只负责回答“这个阶段交付什么what”和“为什么要做why”绝不询问如何实现how——那是discuss-phase的地盘。这一点在命令文件 commands/gsd/spec-phase.md 的objective中同样被强调输出是{phase_dir}/{padded_phase}-SPEC.md用可证伪的需求锁定“what/why”然后discuss-phase接手处理“how”。工作流定位规格锁定的“单向门”从 get-shit-done/workflows/discuss-phase.md 的step namecheck_spec可以看到下游消费逻辑运行discuss-phase时会执行ls ${phase_dir}/*-SPEC.md 2/dev/null | grep -v AI-SPEC | head -1 || true检测阶段目录下是否已存在 SPEC.md若找到会读取该文件并显示Found SPEC.md — {N} requirements locked. Focusing on implementation decisions.随后把spec_loaded置为 true访谈将不再生成关于 WHAT/WHY 的灰度区问题只讨论 HOW 的实现决策并在输出 CONTEXT.md 时注入条件性的spec_lock段tests/workflow-size-budget.test.cjs 中有对 CONTEXT.md 模板必须保留spec_lock条件的回归测试断言。SPEC.md 是一扇“单向门”模板 get-shit-done/templates/spec.md 明确警告——discuss-phase会把其中的需求、边界与验收标准视为锁定决策一旦需求需要变更用户应先更新 SPEC.md再重新运行discuss-phase。量化歧义评分模型四个加权维度与通过门槛spec-phase的核心创新是把“需求是否清晰”这个主观判断量化为可计算的分数。get-shit-done/workflows/spec-phase.md的ambiguity_model定义了完整的评分体系。维度、权重与最低分维度权重最低分衡量内容Goal Clarity目标清晰度35%0.75成果是否具体且可度量Boundary Clarity边界清晰度25%0.70范围之内 vs 范围之外Constraint Clarity约束清晰度20%0.65性能、兼容性、数据要求Acceptance Criteria验收标准20%0.70如何判定“完成”每个维度按 0.0完全不清晰到 1.0完全清晰打分。歧义分数公式与门槛Ambiguity 1.0 − (0.35×goal 0.25×boundary 0.20×constraint 0.20×acceptance)门槛Gate当且仅当歧义分数 ≤ 0.20且所有维度均不低于各自最低分时才算“够清晰”可以进入 SPEC.md 写作。文档对此做了直观解释0.20 的歧义分数意味着 80% 的加权清晰度——这个精度足以让规划器不再擅自做出错误假设。从公式可推导出一些实用边界目标维度被赋予最高权重35%说明“成果可度量”是整份规格的第一优先级即使其他三个维度满分只要目标清晰度低于约 0.71加权后歧义分数仍可能超过 0.20 而被拦在门槛外。反过来说任一维度跌破其最低分如验收标准只有 0.55即使总分通过门槛同样不通过——最低分机制保证了“木桶短板”不会被高分长板掩盖。苏格拉底访谈循环六轮、五个视角spec-phase的访谈不是漫无目的的聊天而是按interview_perspectives定义的五种视角轮换每种视角天然暴露不同类型的盲区。每轮访谈最多 23 个问题且必须先侦察代码库再提问见critical_rules“Scout the codebase BEFORE the first question — grounded questions only”。视角轮换计划轮次视角核心追问Round 1Researcher研究员代码库今天已有什么现状与目标态的差距什么触发了这项工作什么坏了/缺了Round 2Researcher Simplifier简化者解决核心问题的最简版本是什么砍掉 50% 后不可再削减的内核是什么Round 3Boundary Keeper边界守护者本阶段明确不做什么哪些相邻问题很诱人但不应在本阶段解决“完成”长什么样Round 4Failure Analyst失败分析师需求搞错了最糟会怎样一个坏掉的版本长什么样什么会导致 verifier 拒绝产出Round 5–6Seed Closer收尾者我们现在有 [维度][分数]——什么能让它完全清晰剩余歧义集中在 [区域]——能否现在拍板每轮之后的评分与门槛检查每轮结束后都要1根据用户回答更新四个维度分数2重算歧义分数3) 展示本轮评分面板After round [N]: Goal Clarity: [score] (min 0.75) [✓ or ↑ needed] Boundary Clarity: [score] (min 0.70) [✓ or ↑ needed] Constraint Clarity: [score] (min 0.65) [✓ or ↑ needed] Acceptance Criteria:[score] (min 0.70) [✓ or ↑ needed] Ambiguity: [score] (gate: ≤ 0.20)门槛通过后交互模式下会弹出 AskUserQuestionYes — write SPEC.md/One more round/Done talking — write it。若 6 轮耗尽仍未过门槛则进入“最大轮次”分支可选“仍然写 SPEC.md 并标记缺口”“继续聊此后不限轮数”“放弃Abandon绝不写入”。完整八步执行流程Step 1初始化阶段上下文通过gsd-tools.cjs的init phase-op子命令见 get-shit-done/bin/gsd-tools.cjs 的帮助注释获取阶段操作上下文INIT$(node $HOME/.claude/get-shit-done/bin/gsd-tools.cjs init phase-op ${PHASE}) if [[ $INIT file:* ]]; then INIT$(cat ${INIT#file:}); fi返回的 JSON 需要解析出这些字段phase_found、phase_dir、phase_number、phase_name、phase_slug、padded_phase、state_path、requirements_path、roadmap_path、planning_path、response_language、commit_docs。其中response_language若被设置工作流内所有面向用户的话术必须切换为该语言技术术语、代码与文件路径保持英文commit_docs控制最终是否自动提交 SPEC.md。若phase_found为 false输出Phase [X] not found in roadmap.并提示用/gsd:progress查看可用阶段后退出。接下来检测是否已存在 SPEC.md排除 AI-SPECls ${phase_dir}/*-SPEC.md 2/dev/null | grep -v AI-SPEC | head -1 || true已存在时--auto模式自动选择 “Update it” 并记录日志[auto] SPEC.md exists — updating.否则用 AskUserQuestion 提供 “Update it / View it / Skip” 三个选项Skip 则提示Run /gsd:discuss-phase [X] to continue.。Step 2侦察代码库提问前的强制步骤在抛出任何问题之前必须先读取三份输入{requirements_path}项目需求、{state_path}已做决策、当前阶段、阻塞项、ROADMAP.md 中本阶段的条目阶段描述、目标、canonical refs。随后 grep 代码库寻找类似功能的既有实现、新代码将要接入的集成点、与阶段相关的测试覆盖缺口、以及前期阶段的产物SUMMARY.md、VERIFICATION.md。这一轮侦察的产出是“当前状态综合”——即访谈的立足基线但不要先展示给用户而是用于提出有根据的精准问题“Confirm your current state synthesis internally”。Step 3首次歧义评估在提问之前仅依据 ROADMAP.md 与 REQUIREMENTS.md 的内容给四个维度打初分。若--auto且初始歧义已 ≤ 0.20 且全部达到最低分则直接跳过访谈从 roadmap requirements 直接推导 SPEC.md日志记录[auto] Phase requirements are already sufficiently clear — generating SPEC.md from existing context.跳到 Step 6。Step 4Socratic 访谈循环按前文视角表进行最多 6 轮访谈每轮结束更新分数并检查门槛。两个重要模式说明--auto贯穿全程所有 AskUserQuestion 调用替换为 Claude 推荐选择决策内联记录日志逻辑与 discuss-phase 的--auto一致若最大轮次仍不过门槛仍会写 SPEC.md 但标记未达标维度日志提示[auto] Max rounds reached. Writing SPEC.md with [N] dimensions below minimum. Planner will need to treat these as assumptions.文本模式workflow.text_mode: true或--text标志用纯文本编号列表替代 AskUserQuestion 的 TUI 菜单这也是/rc远程会话的必需模式见 commands/gsd/spec-phase.md 的--text说明。Step 6生成 SPEC.md核心产出使用 get-shit-done/templates/spec.md 模板写入{phase_dir}/{padded_phase}-SPEC.md。每条需求必须同时具备三要素Current现状今天已存在或不存在什么Target目标态本阶段后应变成什么——不是 “improve X”而是 “X becomes Y”Acceptance验收标准可证伪的检查——verifier 如何确认达成。模板的good_examples给出了两个完整示范其中“Post Feed信息流”示例对三条需求逐条填写了 Current/Target/Acceptance并在 Constraints 里写明“必须用 cursor 分页而非 offset因为数据库有 50 万帖子offset 分页在第 3 页后不可接受地慢”——这就是约束维度高分的写法。模糊需求会被明确拒绝✗ “The system should be fast”✗ “Improve user experience”✓ “API endpoint responds in 200ms at p95 under 100 concurrent requests”✓ “CLI command exits with code 1 and prints to stderr on invalid input”同时满足边界必须是显式列表In scope / Out of scope后者附简短理由且不可为空验收标准必须是 pass/fail 复选框禁止 “should feel good”“looks reasonable”存在未达标维度时在 Ambiguity Report 中用⚠ Below minimum — planner must treat as assumption标记需求条数会被 discuss-phase 展示为Found SPEC.md — {N} requirements locked.。Step 7原子提交git add ${phase_dir}/${padded_phase}-SPEC.md git commit -m spec(phase-${phase_number}): add SPEC.md for ${phase_name} — ${requirement_count} requirements (#2213)若commit_docs为 false 则跳过提交但需注明 SPEC.md 已写入未提交。Step 8收尾与下一步引导展示最终结果面板并明确引导用户进入discuss-phaseSPEC.md written — {N} requirements locked. Phase {X}: {name} Ambiguity: {final_score} (gate: ≤ 0.20) Next: /gsd:discuss-phase {X} discuss-phase will detect SPEC.md and focus on implementation decisions only.命令入口与模式标志命令 commands/gsd/spec-phase.md 定义了完整的调用契约名称gsd:spec-phase参数提示phase [--auto] [--text]允许工具Read、Write、Bash、Glob、Grep、AskUserQuestionCopilot 环境使用等价的vscode_askquestions前置依赖discuss-phase、execute-phase、phase、plan-phase标志行为--auto跳过交互式提问由 Claude 选择推荐默认值并直接写 SPEC.md同时满足“初始已清晰”与“访谈中达标”两种快路径--text用纯文本编号列表替代 TUI 菜单适配/rc远程会话。--auto场景下 Step 2 的代码库侦察依然执行只是访谈步骤被压缩保证“接地气的提问”原则不被绕过。设计要点与成功标准critical_rules汇总了不可违反的约束每条需求必须有 Current/Target/Acceptance 三要素Boundaries 段强制存在且不可为空In scope / Out of scope 必须是显式列表而非散文验收标准必须 pass/fail用户选择 Abandon 时绝不写 SPEC.md不询问 HOW那是 discuss-phase 的领域提问前必须先侦察代码库每轮最多 23 个问题禁止一次性抛完全部问题。success_criteria则定义了完成的判定提问前已侦察代码库并理解现状每轮后四个维度全部重新计分门槛通过或用户明确选择带缺口继续SPEC.md 只含可证伪需求边界显式含理由验收标准为 pass/fail 复选框commit_docs为 true 时 SPEC.md 被原子提交用户被正确引导到/gsd:discuss-phase。与相邻工作的关系spec-phase vs discuss-phase前者产出 SPEC.md 锁定“what/why”后者读取它并只谈“how”生成的 CONTEXT.md 与 SPEC.md 分工明确——SPEC.md 记录“交付什么”CONTEXT.md 记录“怎么实现”决策、模式、取舍。模板 get-shit-done/templates/spec.md 的guidelines特别强调二者不可互相替代。spec-phase vs ai-integration-phaseAI 集成阶段生成的AI-SPEC.md用途不同spec-phase 与 discuss-phase 的检测命令都通过grep -v AI-SPEC显式排除它。下游消费者discuss-phase读取并以锁定需求处理gsd-planner读取锁定需求以约束计划范围gsd-verifier把验收标准当作显式 pass/fail 检查。模板 get-shit-done/templates/spec.md 开头对这三个下游消费者逐一列出说明一份高质量的 SPEC.md 能同时约束“怎么谈”讨论、“怎么规划”计划与“怎么验收”验证三个环节。一句话总结这套机制的价值把“需求看起来差不多清楚了”这种主观感受替换成“四个维度加权后歧义 ≤ 0.20 且无一短板”的可量化证据再用可证伪的 Current/Target/Acceptance 三元组把结论固化进版本库——这正是规格驱动开发在 GSD 中的落地点。【免费下载链接】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），仅供参考