用户输入
$ARGUMENTS
在继续之前,必须考虑用户输入(如果非空)。
执行前检查
检查扩展钩子(任务生成前):
- 检查项目根目录是否存在
.specify/extensions.yml。 - 如果存在,读取它并查找
hooks.before_tasks键下的条目。 - 如果 YAML 无法解析或无效,不要静默跳过:告知用户
.specify/extensions.yml无法读取(包含解析错误),并且没有检查任何钩子(包括注册在那里的任何强制性(optional: false)钩子),然后正常继续。 - 过滤掉
enabled明确为false的钩子。将没有enabled字段的钩子视为默认启用。 - 对于每个剩余的钩子,不要尝试解释或评估钩子的
condition表达式:- 如果钩子没有
condition字段,或者该字段为空/无效,将该钩子视为可执行。 - 如果钩子定义了一个非空的
condition,跳过该钩子,将条件评估留给 HookExecutor 实现。
- 如果钩子没有
- 当从钩子命令名称构造命令调用时,将点号(
.)替换为连字符(-)。例如,speckit.git.commit→/speckit-git-commit。 - 对于每个可执行的钩子,根据其
optional标志输出以下内容:- 可选钩子(
optional: true):## 扩展钩子 **可选预钩子**:{extension} 命令:`/{command}` 描述:{description} 提示:{prompt} 要执行:`/{command}` - 强制性钩子(
optional: false):
发出上述块之后,你必须实际调用钩子并等待其完成,然后再继续。以你在此代理/会话中运行命令的相同方式运行它(调用方式可能不同于上面显示的文本## 扩展钩子 **自动预钩子**:{extension} 正在执行:`/{command}` EXECUTE_COMMAND:{command} 在继续到大纲之前,等待钩子命令的结果。{command}id,例如,技能模式代理将其作为/skill:speckit-...或$speckit-...运行)。仅发出块并不能运行钩子。
- 可选钩子(
- 如果没有注册钩子或
.specify/extensions.yml不存在,则静默跳过。
大纲
-
设置:从仓库根目录运行
.specify/scripts/bash/setup-tasks.sh --json并解析 FEATURE_DIR、TASKS_TEMPLATE_CONTENT、TASKS_TEMPLATE 和 AVAILABLE_DOCS 列表。FEATURE_DIR和TASKS_TEMPLATE在提供时必须是绝对路径。AVAILABLE_DOCS是FEATURE_DIR下可用的文档名称/相对路径列表(例如research.md或contracts/)。对于像 "I'm Groot" 这样的参数中的单引号,使用转义语法:例如 'I'''m Groot'(或尽可能使用双引号:"I'm Groot")。 -
加载设计文档:从 FEATURE_DIR 读取:
- 必需:plan.md(技术栈、库、结构),spec.md(带有优先级的用户故事)
- 可选:data-model.md(实体),contracts/(接口契约),research.md(决策),quickstart.md(测试场景)
- 如果存在:加载
.specify/memory/constitution.md以获取项目原则和治理约束。 - 注意:并非所有项目都有所有文档。根据可用内容生成任务。
-
执行任务生成工作流:
- 加载 plan.md 并提取技术栈、库、项目结构。
- 加载 spec.md 并提取具有优先级(P1、P2、P3 等)的用户故事。
- 如果存在 data-model.md:提取实体并映射到用户故事。
- 如果存在 contracts/:将接口契约映射到用户故事。
- 如果存在 research.md:提取用于设置任务的决策。
- 按用户故事组织生成任务(见下面的任务生成规则)。
- 生成显示用户故事完成顺序的依赖关系图。
- 为每个用户故事创建并行执行示例。
- 验证任务完整性(每个用户故事都有所有需要的任务,可独立测试)。
-
生成 tasks.md:使用 TASKS_TEMPLATE_CONTENT(来自上面的 JSON 输出)作为结构。为了与省略 TASKS_TEMPLATE_CONTENT 的旧设置脚本兼容,读取 TASKS_TEMPLATE 代替。填充:
- 来自 plan.md 的正确功能名称。
- 阶段 1:设置任务(项目初始化)。
- 阶段 2:基础任务(阻塞所有用户故事的先决条件)。
- 阶段 3+:每个用户故事一个阶段(按 spec.md 中的优先级顺序)。
- 每个阶段包括:故事目标、独立测试标准、测试(如果要求)、实现任务。
- 最后阶段:润色与横切关注点。
- 所有任务必须遵循严格的清单格式(见下面的任务生成规则)。
- 每个任务的清晰文件路径。
- 显示故事完成顺序的依赖关系部分。
- 每个故事的并行执行示例。
- 实现策略部分(MVP 优先,增量交付)。
强制执行的执行后钩子
在向用户报告完成之前,你必须完成此部分。
检查项目根目录是否存在 .specify/extensions.yml。
- 如果不存在,或者
hooks.after_tasks下没有注册钩子,则跳转到完成报告。 - 如果存在,读取它并查找
hooks.after_tasks键下的条目。 - 如果 YAML 无法解析或无效,不要静默跳过:告知用户
.specify/extensions.yml无法读取(包含解析错误),并且没有检查任何钩子(包括注册在那里的任何强制性(optional: false)钩子),然后继续到完成报告。 - 过滤掉
enabled明确为false的钩子。将没有enabled字段的钩子视为默认启用。 - 对于每个剩余的钩子,不要尝试解释或评估钩子的
condition表达式:- 如果钩子没有
condition字段,或者该字段为空/无效,将该钩子视为可执行。 - 如果钩子定义了一个非空的
condition,跳过该钩子,将条件评估留给 HookExecutor 实现。
- 如果钩子没有
- 当从钩子命令名称构造命令调用时,将点号(
.)替换为连字符(-)。例如,speckit.git.commit→/speckit-git-commit。 - 对于每个可执行的钩子,根据其
optional标志输出以下内容:- 强制性钩子(
optional: false)——对于每个强制性钩子,你必须发出EXECUTE_COMMAND::
发出上述块之后,你必须实际调用钩子并等待其完成,然后再继续。以你在此代理/会话中运行命令的相同方式运行它(调用方式可能不同于上面显示的文本## 扩展钩子 **自动钩子**:{extension} 正在执行:`/{command}` EXECUTE_COMMAND:{command}{command}id,例如,技能模式代理将其作为/skill:speckit-...或$speckit-...运行)。仅发出块并不能运行钩子。 - 可选钩子(
optional: true):## 扩展钩子 **可选钩子**:{extension} 命令:`/{command}` 描述:{description} 提示:{prompt} 要执行:`/{command}`
- 强制性钩子(
完成报告
输出生成的 tasks.md 路径和摘要:
- 总任务数
- 每个用户故事的任务数
- 确定的并行机会
- 每个故事的独立测试标准
- 建议的 MVP 范围(通常只是用户故事 1)
- 格式验证:确认所有任务都遵循清单格式(复选框、ID、标签、文件路径)
任务生成的上下文:$ARGUMENTS
tasks.md 应立即可执行——每个任务必须足够具体,以便 LLM 无需额外上下文即可完成。
任务生成规则
关键:任务必须按用户故事组织,以实现独立实现和测试。
测试是可选的:仅在功能规范中明确要求或用户要求 TDD 方法时才生成测试任务。
清单格式(必需)
每个任务必须严格遵循此格式:
- [ ] [TaskID] [P?] [Story?] 描述及文件路径
格式组件:
- 复选框:始终以
- [ ]开头(Markdown 复选框)。 - 任务 ID:按执行顺序的连续编号(T001、T002、T003...)。
- [P] 标记:仅当任务可并行化(不同的文件,不依赖未完成的任务)时才包含。
- [Story] 标签:仅对用户故事阶段任务必需。
- 格式:[US1]、[US2]、[US3] 等(映射到 spec.md 中的用户故事)。
- 设置阶段:无故事标签。
- 基础阶段:无故事标签。
- 用户故事阶段:必须有故事标签。
- 润色阶段:无故事标签。
- 描述:带有确切文件路径的清晰操作。
示例:
- ✅ 正确:
- [ ] T001 根据实施计划创建项目结构 - ✅ 正确:
- [ ] T005 [P] 在 src/middleware/auth.py 中实现认证中间件 - ✅ 正确:
- [ ] T012 [P] [US1] 在 src/models/user.py 中创建用户模型 - ✅ 正确:
- [ ] T014 [US1] 在 src/services/user_service.py 中实现 UserService - ❌ 错误:
- [ ] 创建用户模型(缺少 ID 和故事标签) - ❌ 错误:
T001 [US1] 创建模型(缺少复选框) - ❌ 错误:
- [ ] [US1] 创建用户模型(缺少任务 ID) - ❌ 错误:
- [ ] T001 [US1] 创建模型(缺少文件路径)
任务组织
-
从用户故事(spec.md)——主要组织方式:
- 每个用户故事(P1、P2、P3...)都有自己的阶段。
- 将所有相关组件映射到其故事:
- 故事所需的模型。
- 故事所需的服务。
- 故事所需的接口/UI。
- 如果要求测试:该故事特定的测试。
- 标记故事依赖关系(大多数故事应独立)。
-
从契约:
- 将每个接口契约映射到它服务的用户故事。
- 如果要求测试:每个接口契约 → 在该故事阶段实现之前的 [P] 契约测试任务。
-
从数据模型:
- 将每个实体映射到需要它的用户故事。
- 如果实体服务于多个故事:将其放在最早的故事或设置阶段。
- 关系 → 在适当故事阶段的服务层任务。
- 对于 data-model.md 中具有约束的每个字段(最大长度、可为空/必需、枚举值、验证规则),在任务描述中逐字引用该约束,以便不在实现时自行决定。
-
从设置/基础设施:
- 共享基础设施 → 设置阶段(阶段 1)。
- 基础/阻塞任务 → 基础阶段(阶段 2)。
- 故事特定的设置 → 在该故事的阶段内。
阶段结构
- 阶段 1:设置(项目初始化)。
- 阶段 2:基础(阻塞的先决条件——必须在用户故事之前完成)。
- 阶段 3+:按优先级顺序(P1、P2、P3...)的用户故事。
- 在每个故事内:测试(如果要求)→ 模型 → 服务 → 端点 → 集成。
- 每个阶段应是一个完整的、可独立测试的增量。
- 最后阶段:润色与横切关注点。
完成条件
- 已生成 tasks.md,包含所有阶段、任务 ID 和文件路径。
- 已根据上面“强制执行的执行后钩子”中的规则调度或跳过了扩展钩子。
- 已向用户报告完成情况,包括任务数、故事细分和 MVP 范围。