Spec Kit 的 tasks-template.md 详解:生成可执行、可并行 tasks.md 的模板设计与源码机制

在 Spec Kit 的规范驱动开发(SDD)流程中,/speckit.tasks 命令负责把 spec.md、plan.md 等设计文档拆解为一份依赖有序、可直接被 Agent 执行的任务清单 tasks.md,而这份清单的骨架正是 tasks-template.md。本文逐节解析该模板的任务格式、阶段划分、依赖关系与三种实施策略,并结合 setup_tasks.py 与 common.py 的源码,说明模板如何被前置检查、优先级解析与覆盖机制驱动,帮助读者既能读懂 tasks.md 的生成逻辑,也能自定义自己的任务模板。

一、tasks-template.md 在 SDD 工作流中的位置

quickstart.md 描述的完整工作流是:/speckit.specify → /speckit.clarify → /speckit.plan → /speckit.tasks → /speckit.analyze → /speckit.implement → /speckit.converge。其中:

• /speckit.tasks "从设计产物生成一份可执行、依赖有序的 tasks.md",即本文主题所在的环节;
• /speckit.implement 按依赖顺序执行 tasks.md 中的任务;
• /speckit.analyze 对 spec.md、plan.md、tasks.md 做只读一致性分析;
• /speckit.converge 若发现代码与规格有差距,会把缺失项以追加方式写回 tasks.md(见 agentic-sdd.md)。

模板文件位于仓库的 templates/tasks-template.md。它会被 specify init 安装到项目的 .specify/templates/tasks-template.md(可从 setup_tasks.py 的错误提示与 test_integration_base_markdown.py 中多处对 .specify/templates/tasks-template.md 的断言确认),并在打包时映射进 wheel(pyproject.toml 的资产声明)。

二、模板结构全解

2.1 Front Matter 与头部元信息

模板开头的 YAML front matter 只有一行 description: "Task list template for feature implementation",声明其用途。紧随其后的头部信息块定义了生成 tasks.md 时的基本约束(见 tasks-template.md):

• Input:来自 /specs/[###-feature-name]/ 的设计文档;
• Prerequisites:plan.md(必需)、spec.md(用户故事必需)、research.md、data-model.md、contracts/;
• Tests:测试任务是可选的,只有当功能规格中明确要求测试时才包含;
• Organization:任务按用户故事分组,以便每个故事都能被独立实现和测试。

2.2 任务格式与路径约定

模板规定了每条任务必须遵循的格式 [ID] [P?] [Story] Description(见 tasks-template.md):

• [P]:可并行执行(操作不同文件、无未完成依赖);
• [Story]:该任务属于哪个用户故事(US1、US2、US3……);
• 描述中必须包含精确的文件路径。

同时给出三类项目的路径约定:单项目用根目录 src/、tests/;Web 应用用 backend/src/、frontend/src/;移动项目用 api/src/ 加 ios/src/ 或 android/src/。模板明确提示:示例路径假设单项目结构,实际应按 plan.md 的结构调整。

2.3 阶段划分:Setup → Foundational → User Story → Polish

模板中有一处关键 HTML 注释(tasks-template.md):以下任务是示例任务,供演示格式;__SPECKIT_COMMAND_TASKS__ 命令(即安装后的 /speckit.tasks)必须依据 spec.md 的用户故事(含 P1/P2/P3 优先级)、plan.md 的需求、data-model.md 的实体与 contracts/ 的接口把它们替换为真实任务,且不得把示例任务保留在生成的 tasks.md 中。

Phase 1: Setup(共享基础设施) — 项目初始化与基础结构,示例任务:

- [ ] T001 Create project structure per implementation plan
- [ ] T002 Initialize [language] project with [framework] dependencies
- [ ] T003 [P] Configure linting and formatting tools

Phase 2: Foundational(阻塞性前置) — 所有用户故事开始之前必须完成的核心基础设施,模板用 "CRITICAL: No user story work can begin until this phase is complete" 强调其阻塞性质。示例任务包括数据库 schema 与迁移框架(T004)、认证/授权框架(T005 [P])、API 路由与中间件(T006 [P])、所有故事依赖的基础模型(T007)、错误处理与日志(T008)、环境配置管理(T009)。该阶段以 Checkpoint 收尾:"Foundation ready - user story implementation can now begin in parallel"。

Phase 3 起:每个用户故事一个阶段 — 按 spec.md 中的优先级排序(Phase 3 为 P1 并标注 MVP)。每个故事阶段包含:

• Goal:该故事交付什么;
• Independent Test:如何独立验证该故事可用;
• Tests(可选,仅在要求测试时):且注明 "Write these tests FIRST, ensure they FAIL before implementation"(TDD 红-绿前提),示例为契约测试 tests/contract/test_[name].py 与集成测试 tests/integration/test_[name].py,均标 [P];
• Implementation:按 模型 → 服务 → 端点/功能 → 校验与错误处理 → 日志 的顺序,示例中 T014 显式标注了依赖关系 "depends on T012, T013";
• Checkpoint:如 "User Story 1 should be fully functional and testable independently",故事 2 完成时则要求故事 1 与 2 都能独立工作。

Phase N: Polish & Cross-Cutting Concerns — 影响多个故事的收尾工作,如文档更新、代码清理、跨故事性能优化、补充单元测试(如要求)、安全加固、运行 quickstart.md 验证。

2.4 依赖关系与执行顺序

模板的 "Dependencies & Execution Order" 一节(tasks-template.md)给出三层依赖描述:

1. 阶段依赖:Setup 无依赖可立即开始;Foundational 依赖 Setup 完成并阻塞所有用户故事;各用户故事都依赖 Foundational,之后可并行推进(人力允许时)或按 P1 → P2 → P3 顺序串行;Polish 依赖所有目标故事完成。
2. 故事间依赖:US1 无对其他故事的依赖;US2/US3 可与 US1/US2 集成,但必须保持可独立测试。
3. 故事内部顺序:测试(若包含)必须先写且先失败 → 模型先于服务 → 服务先于端点 → 核心实现先于集成 → 一个故事完成再进入下一优先级。

"Parallel Opportunities" 列出可并行点:所有标 [P] 的 Setup/Foundational 任务、Foundational 完成后各故事整体、同一故事内标 [P] 的测试与模型,以及不同成员分头做不同故事。

2.5 并行执行示例与三种实施策略

模板给出 US1 的并行示例(tasks-template.md):测试任务(契约+集成)一起启动、两个实体模型任务一起启动——这正是 [P] 标记在 /speckit.implement 阶段的消费方式。

"Implementation Strategy" 提供三种策略(tasks-template.md):

1. MVP First(仅 US1):完成 Setup → Foundational → US1,然后 STOP and VALIDATE:独立测试 US1,必要时直接部署/演示;
2. Incremental Delivery:Foundation ready 后逐个叠加故事,每加一个故事就独立测试并部署/演示,"Each story adds value without breaking previous stories";
3. Parallel Team Strategy:团队共同完成 Setup + Foundational,之后开发者 A/B/C 分别负责 US1/US2/US3,故事独立完成后集成。

末尾 Notes 汇总纪律:[P] 任务的定义、[Story] 标签用于追溯性、每个故事应可独立完成和测试、实现前先验证测试失败、每个任务或逻辑组完成后提交、可在任意 Checkpoint 停下来独立验证故事;并列出应避免的反模式——含糊任务、同文件冲突、破坏故事独立性的跨故事依赖。

三、/speckit.tasks 命令如何驱动该模板

生成端定义在 templates/commands/tasks.md。其 front matter 声明了三语言脚本入口(scripts/bash/setup-tasks.sh --json、scripts/powershell/setup-tasks.ps1 -Json、scripts/python/setup_tasks.py --json)以及完成后向 speckit.analyze、speckit.implement 的 handoff。执行要点:

1. Setup:在仓库根运行脚本,解析出 FEATURE_DIR、TASKS_TEMPLATE_CONTENT、TASKS_TEMPLATE、AVAILABLE_DOCS;
2. Load design documents:必需读 plan.md(技术栈/结构)与 spec.md(带优先级的用户故事),可选读 data-model.md、contracts/、research.md、quickstart.md,存在则读 /memory/constitution.md;
3. 生成工作流:从 plan.md 提取技术栈,从 spec.md 提取 P1/P2/P3 故事,实体与契约映射到故事,生成按故事组织的任务、依赖图与并行示例;
4. 套用模板:以脚本输出的 TASKS_TEMPLATE_CONTENT 为结构填充真实任务,并强制所有任务符合清单格式。

其中 "Task Generation Rules" 给出了正误示例,值得对照模板格式逐条理解:

- ✅ CORRECT: - [ ] T001 Create project structure per implementation plan
- ✅ CORRECT: - [ ] T005 [P] Implement authentication middleware in src/middleware/auth.py
- ✅ CORRECT: - [ ] T012 [P] [US1] Create User model in src/models/user.py
- ❌ WRONG: - [ ] Create User model            (缺 ID 与 Story 标签)
- ❌ WRONG: T001 [US1] Create model               (缺 checkbox)
- ❌ WRONG: - [ ] T001 [US1] Create model          (缺文件路径)

Story 标签仅在用户故事阶段的任务上必需;Setup、Foundational、Polish 阶段不带标签。生成结束时还要输出 Completion Report:任务总数、每个故事的任务数、识别出的并行机会、各故事的独立测试标准、建议的 MVP 范围(通常就是 US1),以及"所有任务符合清单格式"的格式校验确认。

四、源码剖析:前置检查与模板解析

4.1 setup_tasks.py:硬性前置检查

setup_tasks.py 是 Python 版前置检查脚本(与 bash/PowerShell 版保持行为一致),核心逻辑:

• 通过 common.py 的 get_feature_paths 定位功能目录(优先 SPECIFY_FEATURE_DIRECTORY 环境变量,否则读 .specify/feature.json);
• plan.md 缺失时报错并提示"先运行 /speckit.plan",spec.md 缺失时提示"先运行 /speckit.specify"(setup_tasks.py),这正是模板头部 Prerequisites 一节的程序化保证;
• _available_docs 探测 research.md、data-model.md、contracts/、quickstart.md 的可用性,写入 AVAILABLE_DOCS(setup_tasks.py);
• 以 --json 输出 FEATURE_DIR、AVAILABLE_DOCS、TASKS_TEMPLATE(路径)与 TASKS_TEMPLATE_CONTENT(完整内容)供 Agent 直接消费(setup_tasks.py)。

4.2 模板优先级解析:overrides → presets → extensions → core

common.py 的 resolve_template 定义了四级优先级栈:

1. .specify/templates/overrides/ 项目级覆盖;
2. .specify/presets/<preset-id>/templates/,按 .registry 中的 priority 排序;
3. .specify/extensions/<ext-id>/templates/;
4. .specify/templates/ 核心模板(即由本仓库 tasks-template.md 安装而来)。

而 resolve_template_content(common.py)进一步支持内容合成:预设 manifest 中的 replace/prepend/append/wrap 四种策略(wrap 要求层内容包含 {CORE_TEMPLATE} 占位符,见 common.py),允许预设在不整体替换模板的前提下插入内容。仓库内 presets/self-test/preset.yml 就示范了声明一个 name: "tasks-template"、replaces: "tasks-template" 的模板条目。

由此得到自定义任务模板的实操路径:在目标项目里新建 .specify/templates/overrides/tasks-template.md 即可整体接管;或用预设按 prepend/append 增量注入(该报错信息与策略集合均可在 setup_tasks.py 与 common.py 中核对)。模板中的 __SPECKIT_COMMAND_TASKS__ 占位符会在安装时由 format_speckit_command(common.py)替换为当前集成环境下的真实命令名。

五、tasks.md 的消费端:/speckit.implement 如何执行它

模板设计的最终读者是 templates/commands/implement.md,其中多条执行规则与模板字段一一对应:

• 清单门禁:实现前扫描 checklists/ 下的勾选状态生成状态表;存在未勾选项时停下询问用户是否继续,且绝不修改清单文件(implement.md);
• 解析结构:从 tasks.md 提取阶段、依赖、ID、文件路径与 [P] 标记(implement.md);
• 分阶段执行:完成一个阶段再进入下一个;[P] 任务可并行,影响同一文件的任务必须串行;每个阶段完成后做验证检查点——对应模板中的 Checkpoint 机制(implement.md);
• 进度与状态:每个任务完成后必须把 tasks.md 中的 [ ] 标记为 [X],这是 /speckit.converge 与迭代续作能识别进度的依据(implement.md);
• 完成校验:验证所有必需任务完成、实现与原规格一致、测试通过且符合技术方案(implement.md)。

这也解释了模板 Notes 中"每个故事应可独立完成和测试"的价值:无论整体 MVP 先行,还是团队并行分故事,执行端都能在任意 Checkpoint 停下独立验证,而不破坏其他故事的交付。

六、适用前提与实操建议

• 前提:/speckit.tasks 依赖 specify init 初始化过的项目(.specify/ 目录与 feature.json),且当前功能目录中已存在 plan.md 与 spec.md,否则脚本会以非零码退出并给出引导;
• 测试任务默认不生成:模板与命令文档一致强调"Tests are OPTIONAL",只有规格明确要求或用户点名 TDD 时才生成测试任务,且测试必须先于实现写、先失败;
• 保持任务独立性与精确路径:这是 [P] 并行、按故事交付、converge 缺口追加三者都能正常运转的基础,模板 Notes 列出的反模式(含糊任务、同文件冲突、破坏独立的跨故事依赖)应作为评审 tasks.md 的检查清单;
• 自定义模板时:优先用 .specify/templates/overrides/tasks-template.md 整体覆盖,或用预设的 prepend/append/wrap 策略增量修改,避免直接改动已安装的 .specify/templates/tasks-template.md 核心文件,以免升级时被覆盖策略的解析顺序意外遮蔽。

综上,tasks-template.md 看似只是一份带示例的 Markdown,实则是 Spec Kit 从"设计文档"落到"可执行实施"的关键契约:它用统一的任务格式约束 Agent 输出,用阶段与 Checkpoint 约束执行节奏,用 [P]/[Story] 标记支撑并行与追溯,再由 setup_tasks 前置检查与模板解析栈保证模板本身可被项目级安全覆盖与扩展。