Spec Kit 任务生成命令深度解析:speckit.tasks 如何把设计文档拆成可执行任务清单

Spec Kit 任务生成命令深度解析:speckit.tasks 如何把设计文档拆成可执行任务清单【免费下载链接】spec-kit Toolkit to help you get started with Spec-Driven Development项目地址: https://gitcode.com/GitHub_Trending/sp/spec-kit本篇以 Spec Kit 核心命令模板 tasks.md 为主体,完整拆解speckit.tasks命令从前置检查、扩展钩子到任务生成规则的完整执行逻辑,并结合其配套脚本 setup_tasks.py、模板 tasks-template.md 与共享工具库 common.py 的源码实现,讲清生成结果的每个字段从何而来、每条任务格式规则为何如此设计,帮助读者既会使用该命令,也理解其底层工程机制。一、speckit.tasks 在 Spec-Driven Development 流程中的位置Spec Kit 采用规格驱动开发(Spec-Driven Development, SDD)工作流:先用speckit.specify产出规格spec.md,再用speckit.plan产出实现计划plan.md,随后speckit.tasks把设计工件拆成依赖有序、可直接执行的任务清单tasks.md,最后由speckit.implement按阶段落地。tasks.md命令模板位于 templates/commands/tasks.md,其 YAML frontmatter 声明了命令的交接关系:description: Generate an actionable, dependency-ordered tasks.md for the feature based on available design artifacts. handoffs: - label: Analyze For Consistency agent: speckit.analyze prompt: Run a project analysis for consistency send: true - label: Implement Project agent: speckit.implement prompt: Start the implementation in phases send: true scripts: sh: scripts/bash/setup-tasks.sh --json ps: scripts/powershell/setup-tasks.ps1 -Json py: scripts/python/setup_tasks.py --json这里有两个值得注意的设计:双向衔接:上游 plan.md 的 frontmatter 中以Create Tasks / agent: speckit.tasks声明了向本命令的交接,下游则声明可交接给speckit.analyze(一致性分析)与speckit.implement(分阶段实现)。整个流程因此形成 specify → plan → tasks → implement 的流水线。三平台脚本:frontmatter 的scripts块同时给出 Bash、PowerShell、Python 三个变体。从源码结构看,Agent 注册时会在渲染命令正文前把占位符{SCRIPT}替换为按当前环境选定的脚本命令——见 agents.py 中resolve_skill_placeholders的占位符解析逻辑(读取 frontmatter 的scripts字典、按script变体选择、py变体再构造 Python 调用,最后执行body.replace({SCRIPT}, script_command)与body.replace({ARGS}, $ARGUMENTS))。这意味着正文中出现的{SCRIPT}在用户项目里是已解析的真实命令,而仓库模板中保留的是占位符。二、前置准备:setup-tasks 脚本提供什么命令 Outline 的第 1 步是Setup:在仓库根目录运行{SCRIPT}(即 setup-tasks 脚本)并解析其 JSON 输出。以 Python 变体 setup_tasks.py 为例,--json模式输出单行 JSON,包含四个关键变量:变量含义来源FEATURE_DIR当前功能目录的绝对路径get_feature_paths()解析AVAILABLE_DOCSFEATURE_DIR 下可用的可选设计文档列表(如research.md、data-model.md、contracts/、quickstart.md)_available_docs()按文件/目录是否存在逐一探测TASKS_TEMPLATE解析后的任务模板文件路径(绝对路径)resolve_template(tasks-template, ...)TASKS_TEMPLATE_CONTENT模板经层叠组合后的最终文本内容resolve_template_content(...)命令模板明确要求FEATURE_DIR和TASKS_TEMPLATE在提供时必须是绝对路径,并提示 JSON 中单引号参数的转义方式(如I\m Groot)。前置工件检查:plan.md 与 spec.md 缺一不可setup_tasks.py 在输出前做硬性前置检查(setup_tasks.py):若plan.md不存在,报错并提示先运行speckit.plan创建实现计划;若spec.md不存在,报错并提示先运行speckit.specify创建功能结构。这与命令正文的Load design documents一节相互印证:Required文档是plan.md(技术栈、库、结构)与spec.md(带优先级的用户故事),而data-model.md(实体)、contracts/(接口契约)、research.md(决策记录)、quickstart.md(测试场景)均为Optional;模板同时指出并非所有项目都有全部文档,应基于现有内容生成任务。此外,若/memory/constitution.md存在,应加载项目章程作为治理约束。功能目录的解析链FEATURE_DIR并非写死,而是由 common.py 中get_feature_paths()按以下优先级解析:环境变量SPECIFY_FEATURE_DIRECTORY(相对路径会相对仓库根展开,且会持久化写入.specify/feature.json)→ 已存在的.specify/feature.json中的feature_directory字段 → 否则报错。仓库根本身也通过环境变量SPECIFY_INIT_DIR、向上查找.specify/目录等方式定位,分支名则取自SPECIFY_FEATURE,缺省回退为功能目录名。这解释了为什么命令可以在仓库根目录运行却能精确找到specs/NNN-feature-name/下的设计工件。模板解析:四层覆盖栈TASKS_TEMPLATE_CONTENT的取值体现 Spec Kit 的模板覆盖机制。从源码结构看,common.py 中resolve_template_content()按固定优先级取层:.specify/templates/overrides/(项目级覆盖,命中即直接作为基座);.specify/presets/preset-id/templates/(按.registry中 priority 排序,策略可为replace/prepend/append/wrap);.specify/extensions/ext-id/templates/(扩展模板,命中即替换);.specify/templates/(核心模板,即 templates/tasks-template.md 初始化时安装的位置)。命令正文特意保留了兼容逻辑:对于省略TASKS_TEMPLATE_CONTENT的旧版 setup 脚本,改读TASKS_TEMPLATE文件。而核心模板找不到时,脚本会给出明确修复指引:添加 override 于.specify/templates/overrides/tasks-template.md,或重新specify init恢复核心模板——这类报错文案本身就是一份排障文档。三、执行前置:扩展钩子 before_tasks在生成任务之前,命令必须检查扩展钩子。规则如下(完整继承自命令模板的 Pre-Execution Checks 一节):检查项目根是否存在.specify/extensions.yml,存在则读取hooks.before_tasks键下的条目;YAML 无法解析或非法时,静默跳过钩子检查并正常继续;过滤掉enabled显式为false的钩子;没有enabled字段的钩子默认视为启用;不解释、不评估钩子的condition表达式:无condition或为空的钩子视为可执行;定义了非空condition的钩子则跳过,把条件求值留给 HookExecutor 实现;对每个可执行钩子,按optional标志输出两种不同消息:可选钩子(optional: true):输出## Extension Hooks / Optional Pre-Hook块,含命令、描述、提示语,等待用户决定是否执行;强制钩子(optional: false):输出Automatic Pre-Hook块并带EXECUTE_COMMAND: {command}标记,Agent必须先实际调用并等待该钩子命令完成后才能进入 Outline——模板特别强调仅输出块本身并不会运行钩子,且不同 Agent 的调用形式可能与字面命令 id 不同(如 skills 模式下的/skill:speckit-...或$speckit-...)。这些事件名来自 Spec Kit 扩展系统的标准事件集。从 extensions/EXTENSION-API-REFERENCE.md 看,核心定义了before_specify/after_specify、before_plan/after_plan、before_tasks/after_tasks、before_implement/after_implement等成对事件;钩子在扩展清单中以command、priority(默认 10,越小越先执行)、optional(默认 true)、prompt、description、condition等字段描述,并支持单映射或映射列表两种形态。一个真实用例是 Git 扩展:extensions/git/config-template.yml 中auto_commit配置提供before_tasks/after_tasks开关与自定义提交信息(默认禁用,如message: [Spec Kit] Save progress before task generation),即为speckit.tasks前后自动提交的设计落点。四、任务生成主流程:Outline 四步命令 Outline 定义了生成tasks.md的核心工作流:Setup:运行{SCRIPT}并解析FEATURE_DIR、TASKS_TEMPLATE_CONTENT、TASKS_TEMPLATE与AVAILABLE_DOCS列表(见第二节)。Load design documents:从FEATURE_DIR读取必需与可选文档,条件加载/memory/constitution.md;不存在全部文档时按现有内容生成。Execute task generation workflow,具体提取与映射规则:从plan.md提取技术栈、库、项目结构;从spec.md提取带优先级(P1、P2、P3…)的用户故事;若存在data-model.md:提取实体并映射到用户故事;若存在contracts/:把接口契约映射到用户故事;若存在research.md:提取决策用于生成 Setup 任务;按用户故事组织任务,生成展示用户故事完成顺序的依赖图,为每个故事创建并行执行示例,并校验任务完备性(每个故事任务齐全、可独立测试)。Generate tasks.md:以TASKS_TEMPLATE_CONTENT为结构骨架,填入功能名、各阶段任务、依赖关系、并行示例与实现策略(详见下节)。五、产出物结构:tasks.md 的阶段划分与清单格式核心模板 templates/tasks-template.md 规定了最终tasks.md的完整形态,命令模板要求逐项填充。阶段(Phase)结构Phase 1: Setup(项目初始化:创建项目结构、初始化依赖、配置 lint 等共享基础设施);Phase 2: Foundational(阻塞性前置:数据库迁移框架、认证授权、路由中间件、基础模型、错误处理、环境配置等——模板特别标注本阶段完成前任何用户故事不得开工);Phase 3: 每个用户故事一个阶段,按 spec.md 优先级顺序排列(P1 → P2 → P3…),故事内部顺序为:测试(若请求)→ 模型 → 服务 → 端点 → 集成;每个阶段应是完整、可独立测试的增量,并含Goal与Independent Test两个必填说明及阶段末Checkpoint;Final Phase: Polish Cross-Cutting Concerns(文档更新、重构、跨故事性能优化、安全加固、运行 quickstart.md 验证等)。模板还给出Path Conventions约定:单项目用src/、tests/;Web 应用用backend/src/、frontend/src/;移动端用api/src/加ios/src//android/src/,并提示按 plan.md 的实际结构调整。清单格式(强制规范)命令模板将清单格式列为 REQUIRED,每条任务必须严格符合:- [ ] [TaskID] [P?] [Story?] Description with file path五个格式要素:Checkbox:永远以- [ ](Markdown 复选框)开头;Task ID:按执行顺序编号(T001、T002、T003…);[P] 标记:仅当任务可并行(不同文件、不依赖未完成任务)时包含;[Story] 标签:仅用户故事阶段的任务必填,格式[US1]/[US2]…,与 spec.md 中的用户故事对应;Setup、Foundational、Polish 阶段不加故事标签;Description:动作明确且含精确文件路径。模板给出的正反例值得原样保留,因为它定义了可被 LLM 直接执行的边界:✅- [ ] T001 Create project structure per implementation plan✅- [ ] T005 [P] Implement authentication middleware in src/middleware/auth.py✅- [ ] T012 [P] [US1] Create User model in src/models/user.py✅- [ ] T014 [US1] Implement UserService in src/services/user_service.py❌- [ ] Create User model(缺 Task ID 与 Story 标签)❌T001 [US1] Create model(缺 checkbox)❌- [ ] [US1] Create User model(缺 Task ID)❌- [ ] T001 [US1] Create model(缺文件路径)命令模板末尾那句要求是整个格式的动机:tasks.md 应当立即可执行——每个任务必须具体到 LLM 无需额外上下文即可完成。任务来源映射规则(Task Organization)任务从哪里来,模板给出四条映射规则:来自用户故事(spec.md)——首要组织维度:每个故事(P1/P2/P3…)独占一个阶段,把该故事所需的模型、服务、接口/UI 及(若请求)测试全部归入该阶段,并标注故事间依赖(大多数故事应当相互独立);来自 contracts/:每个接口契约映射到其服务的用户故事;若请求测试,在每个故事的实现任务之前先生成契约测试任务(标 [P]);来自 contenteditable="false">【免费下载链接】spec-kit Toolkit to help you get started with Spec-Driven Development项目地址: https://gitcode.com/GitHub_Trending/sp/spec-kit创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考