Elsa Core 中的 speckit-clarify 技能解析：为功能规格消除歧义并回写澄清记录

后端工作流自动化流程编排低代码【免费下载链接】elsa-coreThe Workflow Engine for .NET项目地址https://gitcode.com/gh_mirrors/el/elsa-core点击查看免费下载导读speckit-clarify是 Elsa Core 仓库中 spec-kitSpec-Driven Development规格驱动开发技能体系的一员其职责是在进入规划阶段之前通过最多 5 个高度聚焦的澄清问题定位当前功能规格feature spec中未被明确定义的决策点并把每一条确认后的答案以结构化格式直接回写到 spec 文件中。本文将以仓库中真实的技能定义.agents/skills/speckit-clarify/SKILL.md为骨架结合仓库内.specify/的实际配置与脚本、specs/目录下的真实规格样例完整讲解该工作流的执行步骤、提问约束、歧义分类法、增量写回机制与校验规则帮助你掌握一套先澄清、再规划的高质量规格编写方法。一、技能定位澄清发生在规划之前speckit-clarify是一个命令型技能Skill其 Frontmatter 中声明的职责是Identify underspecified areas in the current feature spec by asking up to 5 highly targeted clarification questions and encoding answers back into the spec.即识别当前特性规格中未充分定义的领域提出至多 5 个高度针对性的澄清问题并将答案编码回规格文件。其兼容性要求是项目具备 spec-kit 目录结构即根目录存在.specify/目录——本仓库根目录下确实存在.specify/内含extensions.yml、templates/、scripts/、workflows/等结构。从技能定义可知该澄清工作流必须在调用/speckit-plan之前完成。如果用户明确表示跳过澄清例如做探索性 spike技能允许继续但必须警告下游返工rework风险会上升。这一先后顺序也体现在.specify/extensions.yml的钩子注册中——before_clarify与before_plan是两个独立的钩子时点详见下文。在 Elsa Core 仓库中与之配套的技能还有speckit-specify、speckit-plan、speckit-tasks、speckit-implement、speckit-checklist、speckit-analyze、speckit-taskstoissues以及多个 git 相关技能见 .agents/skills/ 目录共同构成一条完整的规格驱动开发流水线。specs/目录下每个特性目录如 specs/011-persistence-vnext/通常包含spec.md、plan.md、tasks.md、research.md、data-model.md、contracts/、checklists/等文件正是本技能要读取、澄清和写回的目标工件。二、整体执行流程概览技能定义将工作流划分为 8 个可执行步骤外加前置与后置的扩展钩子检查阶段内容Pre-Execution Checks检查.specify/extensions.yml中hooks.before_clarify注册的钩子并按规则输出/执行第 1 步运行check-prerequisites.sh --json --paths-only解析特性路径第 2 步加载当前 spec按歧义分类法做结构化覆盖扫描Clear / Partial / Missing第 3 步内部生成优先级排序的候选澄清问题队列≤5第 4 步顺序交互提问循环一次只呈现一个问题第 5 步每次接受答案后增量更新 spec 并立即写盘第 6 步每次写入后执行校验并做最终校验第 7 步将更新后的 spec 写回FEATURE_SPEC第 8 步输出完成报告问题数、路径、触及章节、覆盖总结、下一步建议Post-Execution Checks检查hooks.after_clarify注册的钩子下文逐阶段展开。三、前置执行检查扩展钩子机制在执行澄清逻辑之前技能要求先检查项目根目录的.specify/extensions.yml若文件存在读取hooks.before_clarify键下的钩子条目若 YAML 无法解析或无效则静默跳过钩子检查并继续过滤掉enabled: false的钩子没有enabled字段的钩子默认视为启用不要尝试解释或求值钩子的condition表达式——无condition字段或为 null/空的钩子视为可执行定义了非空condition的钩子直接跳过把条件求值留给 HookExecutor 实现对每个可执行钩子根据其optional标志输出不同格式可选钩子optional: true## Extension Hooks **Optional Pre-Hook**: {extension} Command: /{command} Description: {description} Prompt: {prompt} To execute: /{command}强制钩子optional: false## Extension Hooks **Automatic Pre-Hook**: {extension} Executing: /{command} EXECUTE_COMMAND: {command} Wait for the result of the hook command before proceeding to the Outline.如果没有注册任何钩子或extensions.yml不存在则静默跳过。在本仓库的 .specify/extensions.yml 中hooks.before_clarify实际注册了一个可选钩子before_clarify: - extension: git command: speckit.git.commit enabled: true optional: true prompt: Commit outstanding changes before clarification? description: Auto-commit before spec clarification condition: null也就是说在 Elsa Core 中运行澄清前Agent 会提示用户是否先执行speckit.git.commit提交未提交的变更auto_execute_hooks: true同时作用于全局设置。钩子采用optional: true因此按文档规则输出Optional Pre-Hook提示块并等待用户决定而不是自动执行。after_clarify钩子同样注册了speckit.git.commit描述为 Auto-commit after spec clarification用于在澄清写回后提交改动。四、第 1 步前置条件检查与路径解析技能要求从仓库根目录只运行一次.specify/scripts/bash/check-prerequisites.sh --json --paths-only这是--json与--paths-only的组合模式脚本参数也支持-Json/-PathsOnly的 PowerShell 风格其含义是仅输出路径变量、不做校验。仓库中的 .specify/scripts/bash/check-prerequisites.sh 源码与技能定义完全对应在--paths-only模式下脚本跳过plan.md、tasks.md等文件存在性校验直接输出最小 JSON 负载{REPO_ROOT:...,BRANCH:...,FEATURE_DIR:...,FEATURE_SPEC:...,IMPL_PLAN:...,TASKS:...}技能要求至少解析以下字段FEATURE_DIR特性目录路径FEATURE_SPEC特性规格文件路径可选IMPL_PLAN、TASKS供后续链式流程plan / tasks使用。若 JSON 解析失败应中止流程并提示用户重新运行/speckit-specify或检查特性分支环境。另外注意参数中的单引号转义问题当参数包含单引号例如 Im Groot时需使用I\m Groot这类转义写法或尽量改用双引号包裹Im Groot。从脚本源码看check-prerequisites.sh还会在非--paths-only模式下校验FEATURE_DIR存在、plan.md存在--require-tasks时还要求tasks.md并汇总research.md、data-model.md、contracts/、quickstart.md等可用文档清单——这些文件正是在specs/各特性目录中常见的内容。五、第 2 步结构化歧义与覆盖扫描加载当前 spec 文件后技能要求按一套固定分类法做结构化扫描对每个类别标记状态Clear已明确/Partial部分明确/Missing缺失并在内部生成覆盖地图用于优先级排序除非没有任何问题要问否则不输出原始地图。完整分类法如下功能范围与行为Functional Scope Behavior核心用户目标与成功标准Core user goals success criteria显式的范围外声明Explicit out-of-scope declarations用户角色 / 人群区分User roles / personas differentiation领域与数据模型Domain Data Model实体、属性、关系Entities, attributes, relationships标识与唯一性规则Identity uniqueness rules生命周期 / 状态流转Lifecycle/state transitions数据量 / 规模假设Data volume / scale assumptions交互与 UX 流程Interaction UX Flow关键用户旅程 / 时序Critical user journeys / sequences错误 / 空 / 加载状态Error/empty/loading states可访问性或本地化说明Accessibility or localization notes非功能质量属性Non-Functional Quality Attributes性能延迟、吞吐目标可扩展性水平/垂直、上限可靠性与可用性正常运行时间、恢复预期可观测性日志、指标、追踪信号安全与隐私认证/授权、数据保护、威胁假设合规 / 监管约束如有集成与外部依赖Integration External Dependencies外部服务/API 及其失败模式数据导入/导出格式协议 / 版本化假设边界情况与失败处理Edge Cases Failure Handling负面场景Negative scenarios限流 / 节流Rate limiting / throttling冲突解决如并发编辑约束与权衡Constraints Tradeoffs技术约束语言、存储、托管显式权衡或被否决的备选方案术语与一致性Terminology Consistency规范术语表Canonical glossary terms应避免的同义词 / 弃用术语完成信号Completion Signals验收标准可测试性可度量的 Definition of Done 风格指标杂项 / 占位符Misc / PlaceholdersTODO 标记 / 未决决策缺乏量化的模糊形容词如 robust、intuitive对于每个状态为 Partial 或 Missing 的类别应加入候选问题机会除非满足以下任一条件澄清不会实质性改变实现或验证策略或信息更适合推迟到规划阶段此时在内部备注。需要说明的是spec 模板本身就会预留待澄清占位符。在 .specify/templates/spec-template.md 中可以看到这类标记的范例例如需求条目的[NEEDS CLARIFICATION: auth method not specified - email/password, SSO, OAuth?]或[NEEDS CLARIFICATION: retention period not specified]——这正是扫描阶段重点捕获的模糊点。六、第 3 步澄清问题生成约束最多 5 个技能要求在内部生成优先级排序的候选问题队列最多 5 个且不要一次性输出全部问题。生成时需遵守以下约束数量上限整个会话最多 5 个问题答案形态每个问题必须能用以下两种形式之一回答简短多选题2–5 个互斥选项或一个单词 / 短语明确约束Answer in 5 words影响面过滤只纳入答案会实质性影响架构、数据建模、任务拆解、测试设计、UX 行为、运维就绪度或合规验证的问题类别覆盖平衡优先覆盖影响最大且尚未解决的类别避免在单一高影响领域如安全姿态尚未解决时去问两个低影响问题排除项排除已回答的问题、琐碎风格偏好、规划层面的执行细节除非阻塞正确性倾向优先选择能降低下游返工风险、或防止验收测试错位的问题优先级启发式若未解决类别超过 5 个按Impact × Uncertainty影响 × 不确定性启发式选取前 5。七、第 4 步顺序交互提问循环提问采用严格的一次一问交互模式一次只呈现一个问题多选题格式先分析所有选项依据项目类型最佳实践、类似实现中的常见模式、风险降低安全/性能/可维护性以及与 spec 中可见目标的对齐程度选出最合适的选项将推荐选项置顶并给出 1–2 句理由格式为**Recommended:** Option [X] - reasoning然后用 Markdown 表格呈现所有选项OptionDescriptionABC(add D/E as needed up to 5)ShortProvide a different short answer (5 words) (Include only if free-form alternative is appropriate)表格之后追加一行引导You can reply with the option letter (e.g., A), accept the recommendation by saying yes or recommended, or provide your own short answer.短答格式没有有意义的离散选项时基于最佳实践与上下文给出建议答案**Suggested:** your proposed answer - brief reasoning然后输出Format: Short answer (5 words). You can accept the suggestion by saying yes or suggested, or provide your own answer.用户回答后的处理若用户回复 yes / recommended / suggested采用先前给出的推荐/建议作为答案否则验证答案是否映射到某个选项或满足 ≤5 词约束若答案有歧义请求快速澄清仍计入同一问题不推进问题计数确认后存入工作记忆暂不写盘进入下一个排队问题。停止提问的条件满足其一即可关键歧义已提前全部解决剩余排队问题变得不必要用户发出完成信号done、good、no more已问满 5 个问题。同时要遵守两条纪律绝不提前透露未来排队的问题如果一开始就不存在有效问题立即报告没有关键歧义对应行为规则中的输出No critical ambiguities detected worth formal clarification.。八、第 5 步每次回答后的增量写回技能采用增量更新策略在内存中维护 spec 的表示开始时加载一次及原始文件内容每接受一个答案就立即更新并写盘以最小化上下文丢失风险。具体写入规则本会话第一个被集成的答案处理确保 spec 中存在## Clarifications节若缺失按 spec 模板在最高层级的上下文/总览节之后创建在其下创建若不存在### Session YYYY-MM-DD子标题YYYY-MM-DD 为当天日期在答案被接受后立即追加一行子弹记录- Q: question → A: final answer随后把澄清立即应用到最合适的章节澄清类型落点功能歧义在 Functional Requirements 中新增或修改一条用户交互 / 角色区分更新 User Stories 或 Actors 小节补充角色、约束或场景数据形态 / 实体更新 Data Model新增字段、类型、关系保持原有顺序简明标注新增约束非功能约束在 Success Criteria Measurable Outcomes 中新增/修改可度量标准把模糊形容词转换为指标或明确目标边界情况 / 负面流程在 Edge Cases / Error Handling 下新增一条或按模板占位符新建该小节术语冲突在 spec 全篇归一化术语仅在必要时保留原词并标注(formerly referred to as X)若澄清使之前的模糊陈述失效应替换而非复制不留任何过时的矛盾文本每次集成后立即保存 spec 文件原子覆盖写保持格式不重排无关章节保持标题层级完整每次插入的澄清保持最小化、可测试避免叙述漂移。落点章节的名称与 .specify/templates/spec-template.md 中的模板章节一致Functional Requirements、User Scenarios Testing含 User Story N 与 Acceptance Scenarios、Edge Cases、Success Criteria Measurable Outcomes、Assumptions等。真实样例 specs/011-persistence-vnext/spec.md 展示了这些章节的落地形态——用户故事按 P1/P2 优先级排序、每条含 Why this priority 与 Given/When/Then 格式的 Acceptance Scenarios这正是澄清结果会被编码进去的载体。九、第 6 步校验每次写入后 最终通过每次写入后以及最终收尾时都要执行以下校验## Clarifications会话节中每个被接受的答案恰好对应一条子弹记录无重复总提问被接受数 ≤ 5被更新的章节中不存在本应被新答案消除的模糊占位符残留不存在自相矛盾的旧陈述扫描已失效的备选选择并移除Markdown 结构有效只允许新增标题## Clarifications、### Session YYYY-MM-DD术语一致性所有被更新章节使用同一规范术语。十、第 7–8 步写回与完成报告第 7 步把更新后的 spec 写回FEATURE_SPEC即第 1 步解析出的规格文件路径。第 8 步在提问循环结束或提前终止后输出完成报告包含提问并回答的问题数量更新后的 spec 路径被触及的章节名列表覆盖总结表对每个分类法类别给出状态——Resolved原为 Partial/Missing 且已解决、Deferred超出问题配额或更适合规划阶段、Clear本就充分、Outstanding仍为 Partial/Missing 但影响低若存在 Outstanding 或 Deferred给出建议是继续进入/speckit-plan还是在规划之后再运行一次/speckit-clarify建议的下一命令。十一、行为规则红线汇总技能定义末尾的行为规则是整个工作流不可违反的约束若未发现有意义歧义或所有潜在问题均为低影响输出No critical ambiguities detected worth formal clarification. 并建议继续若 spec 文件缺失指导用户先运行/speckit-specify本技能不负责新建 spec总提问数永不超 5同一问题的澄清重试不计为新问题避免投机性技术栈问题除非其缺失阻碍了功能清晰度尊重用户提前终止信号stop、done、proceed若因全覆盖而未提问输出紧凑覆盖总结所有类别 Clear然后建议推进若配额用尽仍有未解决的高影响类别在 Deferred 下显式标记并给出理由。十二、后置执行检查after 钩子澄清流程结束后同样要检查.specify/extensions.yml中的hooks.after_clarify键规则与前置检查一致无效 YAML 静默跳过、过滤enabled: false、不解释condition表达式。可执行钩子按optional标志输出可选钩子optional: true## Extension Hooks **Optional Hook**: {extension} Command: /{command} Description: {description} Prompt: {prompt} To execute: /{command}强制钩子optional: false## Extension Hooks **Automatic Hook**: {extension} Executing: /{command} EXECUTE_COMMAND: {command}回到本仓库的 .specify/extensions.ymlhooks.after_clarify注册的同样是speckit.git.commitoptional: true用于在澄清写回后提示提交变更从而把澄清 → 写回 → 提交串成一个原子工作单元。从源码结构看.specify/extensions.yml中对before_specify、before_plan、before_tasks、before_implement、before_checklist、before_analyze、before_taskstoissues以及对应的after_*钩子都注册了同类 git 钩子印证了该钩子机制是覆盖整个 spec-kit 流水线的通用横切能力。十三、结合仓库的落地小结在本仓库中speckit-clarify技能的运行环境是真实存在的证据链完整技能本体.agents/skills/speckit-clarify/SKILL.md即本文骨架来源约 250 行的完整工作流定义扩展钩子配置.specify/extensions.ymlhooks.before_clarify/hooks.after_clarify均注册了speckit.git.commit前置检查脚本.specify/scripts/bash/check-prerequisites.sh支持--json --paths-only输出FEATURE_DIR、FEATURE_SPEC、IMPL_PLAN、TASKS等字段配套脚本.specify/scripts/bash/common.sh 等路径解析与分支校验spec 模板.specify/templates/spec-template.md澄清写入的章节结构依据真实规格样例specs/011-persistence-vnext/spec.mdP1/P2 用户故事、Given/When/Then 验收场景的落地形态完整的技能生态.agents/skills/specify → clarify → plan → tasks → implement → checklist → analyze 的流水线。对于在 Elsa Core 上参与特性开发的 Agent 或开发者而言这套工作流的意义在于在投入规划与实现之前把 spec 中的模糊形容词、未决选项、缺失边界条件转化为明确的、可测试的、可度量的需求条目并以## Clarifications会话记录的形式保留审计轨迹从而显著降低下游返工风险也为后续/speckit-plan提供一份确定性的输入。赞分享后端工作流自动化流程编排低代码【免费下载链接】elsa-coreThe Workflow Engine for .NET项目地址https://gitcode.com/gh_mirrors/el/elsa-core点击查看免费下载相关推荐Rerun 点云性能优化完整指南3 步搞定海量点云实时渲染Rerun 点云性能优化完整指南3 步搞定海量点云实时渲染 Rerun 是一个用来可视化和流式传输 3D、点云等机器人数据的开源工具。做自动驾驶或三维重建时后端工作流自动化流程编排低代码Spec-Kit 实现执行工作流详解用 speckit-implement 技能将任务清单落地为 Elsa Workflow Runtime 功能Spec Kit 实现执行工作流详解用 speckit implement 技能将任务清单落地为 Elsa Workflow Runtime 功能 在基于 s后端工作流自动化流程编排低代码Corsair DeepSeek 插件实战指南四大端点、API Key 鉴权与错误重试策略Corsair DeepSeek 插件实战指南四大端点、API Key 鉴权与错误重试策略 本篇技术指南以 packages/deepseek/README.后端工作流自动化流程编排低代码上一篇如何使用Metroidvania-System保存游戏进度完整教程下一篇Vue数据可视化的终极指南5分钟掌握ECharts集成创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考