用途:speckit-plan 用于执行实施规划工作流,依据规划模板将功能规格转化为设计产物,属于 Spec-Kit 流程中的规划环节。
主要能力:
- 前置检查:若项目根目录存在 .specify/extensions.yml,读取 hooks.before_plan 下的钩子;跳过 enabled 为 false 的条目,无 enabled 字段视为启用;不解释 condition 表达式,非空 condition 的钩子跳过。命令名中的点替换为连字符,如 speckit.git.commit 对应 /speckit-git-commit。可选钩子仅提示执行方式,强制钩子需等待结果后再继续。
- 环境准备:在仓库根目录运行 .specify/scripts/powershell/setup-plan.ps1 -Json,解析 FEATURE_SPEC、IMPL_PLAN、SPECS_DIR、BRANCH。
- 载入上下文:读取 FEATURE_SPEC 与 .specify/memory/constitution.md,加载已复制的 IMPL_PLAN 模板。
- 按模板执行规划:填写技术上下文(未知项标记 NEEDS CLARIFICATION)、填写宪章检查、评估门禁(违规且无正当理由报错)。
- 阶段 0:从技术上下文中提取未知项,为每个待澄清项生成研究任务,为每个依赖生成最佳实践任务,为每个集成生成模式任务,汇总到 research.md,格式为 Decision、Rationale、Alternatives considered。
- 阶段 1:从功能规格提取实体生成 data-model.md(实体名、字段、关系、校验规则、状态转换);在项目有外部接口时于 /contracts/ 定义接口契约(库的公开 API、CLI 的命令模式、Web 服务端点、解析器文法、应用 UI 契约等),纯内部项目可跳过;生成 quickstart.md 验证指南,包含前置条件、设置命令、测试/运行命令与预期结果,引用契约与数据模型而非重复内容,不包含完整实现代码或测试套件;更新 CLAUDE.md 中 <!-- SPECKIT START --> 与 <!-- SPECKIT END --> 之间的规划引用,指向新建的规划文件。
- 后置钩子:读取 hooks.after_plan,规则同前;强制钩子须输出 EXECUTE_COMMAND。
- 完成报告:命令在阶段 2 规划后结束,报告分支、IMPL_PLAN 路径与生成的产物。
使用方式:通过斜杠命令触发,可附带用户输入参数($ARGUMENTS),参数中含单引号时使用转义语法。文件系统操作使用绝对路径,文档与智能体上下文引用使用项目相对路径。
适用场景:在编码实现前,将功能规格系统性转化为研究结论、数据模型、接口契约与快速验证指南,并同步更新智能体上下文,适用于采用 Spec-Kit 约定目录结构(.specify/)的项目。
限制:依赖项目内特定脚本与目录结构;门禁失败或澄清未解决时报错终止;YAML 无法解析时静默跳过钩子检查;不评估钩子 condition 表达式,交由 HookExecutor 处理。