Spec Kit Agentic SDD 命令参考：九个 /speckit.* 命令驱动的智能体规格驱动开发全流程

2026-09-06 18:12:55作者：侯霆垣

本文围绕 Spec Kit 的 Agentic SDD（Spec-Driven Development）核心命令体系展开：逐条讲解 /speckit.constitution 到 /speckit.converge 九个斜杠命令的职责、调用方式、产物与交互规则，并结合 templates/commands/ 下的命令模板、scripts/ 下的辅助脚本与 workflows/speckit/workflow.yml 自动化编排，说明每个命令在智能体会话中的真实执行机制，帮助你把"从自然语言需求到可验收代码"的完整流程落地到自己的编码智能体中。

整体流程：一条命令流水线，两个执行档位

Agentic SDD 指的是由编码智能体（Claude、Copilot、Gemini、Codex 等）逐步执行的一套智能体流程（agentic process），全部通过 /speckit.* 斜杠命令驱动。完整流水线为：

/speckit.constitution -> /speckit.specify -> /speckit.clarify -> /speckit.plan -> /speckit.checklist -> /speckit.tasks -> /speckit.analyze -> /speckit.implement -> /speckit.converge

顺序上有两条关键规则：

命令设计上按顺序运行，但严格的前置依赖只有一条：/speckit.plan 之前必须先运行 /speckit.specify。
/speckit.clarify、/speckit.checklist、/speckit.analyze 是质量门禁：对任何存在实质性模糊性的功能都应加入；小功能可以跳过，生产级功能建议全开。

对应地，docs/quickstart.md 中给出了两档常用路径：

短路径（小型功能）：

/speckit.specify
/speckit.plan
/speckit.tasks
/speckit.implement
/speckit.converge

全路径（生产功能）：在上面基础上追加 /speckit.constitution（开头）以及 /speckit.clarify、/speckit.checklist、/speckit.analyze 三个质量门禁，共九步。

调用形式的适配说明（原文档 NOTE 原文含义）：本文统一写作 /speckit.* 形式，但具体调用形式取决于你的智能体——部分 skills 型智能体使用 $speckit-*（如 Codex、ZCode）或 /skill:speckit-*（如 Kimi）。请替换为你所用智能体实际暴露的形式，步骤本身完全一致。

前置条件：先用 uv tool install specify-cli 安装 CLI，再执行 specify init <项目名> 完成初始化（安装方式详见 docs/installation.md）。所有命令都在初始化后的项目内运行，产物集中在 specs/<feature>/ 与 .specify/ 目录下。

`/speckit.constitution`：确立项目宪法

创建或更新项目宪法（constitution）——后续每个阶段都要对照评估的指导性原则，并同步保持依赖模板一致。建议项目开始之前运行一次，此后每当原则变化时再更新，原则作为命令参数传入：

/speckit.constitution This project follows a "Library-First" approach. All features must be implemented as standalone libraries first. We use TDD strictly. We prefer functional programming patterns.

从 templates/commands/constitution.md 的模板实现可以看到三条更深入的机制：

写入位置：宪法位于 .specify/memory/constitution.md。模板通过 scripts/bash/resolve-template.sh constitution-template --json 之类的解析脚本，从预设/扩展/核心模板三层解析栈中解析出当前生效的 constitution-template（对应仓库根目录的 templates/constitution-template.md）；若已有宪法则加载旧值合并，保留仍然适用的条款。
语义化版本：CONSTITUTION_VERSION 按语义化版本规则递增，RATIFICATION_DATE 为原始采纳日期，LAST_AMENDED_DATE 在有变更时更新为当天。
Scope Guard（范围护栏）：该命令的工作范围严格限定为更新宪法本身。若用户输入中夹带了"顺便实现某功能"之类的请求，模板明确要求必须拒绝执行、将其记为 deferred intent 并在 Next Actions 中建议对应的后续命令——这从源头避免了智能体越权修改应用代码。

宪法在后续流程中的作用：templates/commands/analyze.md 明确宪法冲突自动升级为 CRITICAL 级发现，且"不可通过稀释、重新解释或静默忽略原则来解决"；templates/commands/converge.md 同样把违反 MUST 原则的代码视为最高严重度发现并生成修复任务。

`/speckit.specify`：用自然语言写规格说明

从自然语言描述创建或更新功能规格说明（specification），聚焦做什么（what）与为什么（why）——用户可见的行为与目标——而不涉及技术栈（技术栈属于 /speckit.plan）：

/speckit.specify Build an application that helps me organize photos into albums grouped by date, re-orderable by drag-and-drop on the main page, with a tile preview inside each album.

模板（templates/commands/specify.md）揭示了它背后相当重的自动化细节：

功能目录命名：先从描述中提取 2–4 词的短名（如 user-auth、oauth2-api-integration），再按 specs/<prefix>-<short-name> 创建目录。前缀的编号策略读自 .specify/init-options.json 的 feature_numbering："sequential" 取扫描现有目录后的下一个三位序号（003-user-auth），"timestamp" 用 YYYYMMDD-HHMMSS（20260319-143022-user-auth）。旧字段 branch_numbering 已弃用，仅作迁移读取。
状态持久化：解析出的目录路径写入 .specify/feature.json（内容为 {"feature_directory": "specs/003-user-auth"} 这样的实际路径值），供 plan/tasks/implement 等下游命令定位功能目录——不依赖 git 分支名约定。这与 scripts/bash/common.sh 中 read_feature_json_feature_directory 的实现相互印证：该函数按 jq → python3 → grep/sed 三级解析器依次尝试读取 feature.json，任何一级失败都静默落到下一级，保证在 Windows 等环境下 feature.json 依然可读。
规格质量自检：写完后立即在 SPECIFY_FEATURE_DIRECTORY/checklists/requirements.md 生成一份内置规格质量检查清单，包含 Content Quality / Requirement Completeness / Feature Readiness 三组勾选项（例如"不含实现细节""所有必需章节已完成""无遗留 [NEEDS CLARIFICATION] 标记"）。随后按清单逐项验证，失败则回改规格并重跑（最多 3 轮）。
澄清标记上限：不确定的点只允许标记最多 3 个 [NEEDS CLARIFICATION: 具体问题]，按影响面排序（scope > security/privacy > UX > 技术细节），其余用"有依据的猜测"填充并写入 Assumptions 章节。

`/speckit.clarify`：在规格上提问并回写答案

对当前规格中欠规范的部分提出至多 5 个针对性问题，并把你的答案编码回 spec.md。在规划之前可以运行任意多次，每次聚焦不同领域；可选地传入聚焦领域作为参数：

/speckit.clarify Focus on the task card behavior: status changes, comment limits, and who can be assigned.

先澄清再规划，能避免"在模糊性之上做设计"。若之后 /speckit.analyze 又暴露出需求缺口，应回到这里（或 /speckit.specify）重跑。

templates/commands/clarify.md 定义了它的内部工作方式，信息量很大：

结构化模糊度扫描：按十个类目对规格打分（Clear / Partial / Missing）——功能范围与行为、领域与数据模型、交互与 UX 流、非功能质量属性、集成与外部依赖、边界与失败处理、约束与取舍、术语一致性、完成信号、占位符。只有 Partial/Missing 且答案会实质影响架构/数据建模/任务分解/测试设计的类目才进入候选问题队列。
提问纪律：整个会话最多问 5 题，每题必须能"二选一~五选的选择题（2–5 个互斥选项）或 ≤5 个词的短答"回答；一次只呈现一题，先给出带理由的 **Recommended:** 选项，用户可用选项字母、"yes/recommended" 或直接作答；重试不计数为新问题。
增量回写：每接受一个答案，立即在 ## Clarifications 下的 ### Session YYYY-MM-DD 追加一条 - Q: ... → A: ...，并同步更新到规格的最合适章节（功能需求、用户故事、数据模型、成功标准、边界情况、术语规范化），替换掉被推翻的旧表述，然后逐次原子保存文件以防上下文丢失。
重新校验内置清单：若 checklists/requirements.md 存在，/speckit.clarify 会对更新后的规格重新评估其勾选项，仅翻转状态真正变化的 [ ]/[x] 标记，并在完成报告中给出前后通过数（如 "12/16 → 15/16"）。注意原文档的例外边界：该行为只适用于内置的 requirements 清单，不适用于 /speckit.checklist 生成的自定义清单。

`/speckit.plan`：把技术决策落进设计产物

执行规划流程，从规格生成设计产物。实现细节属于这一步——技术栈、架构、技术约束都以参数形式给出：

/speckit.plan Use .NET Aspire with Postgres. The frontend is Blazor Server with drag-and-drop boards and real-time updates. Expose REST APIs for projects, tasks, and notifications.

templates/commands/plan.md 显示该命令先运行 scripts/bash/setup-plan.sh --json（PowerShell/Python 变体 scripts/powershell/setup-plan.ps1、scripts/python/setup_plan.py 等价）拿到 FEATURE_SPEC、IMPL_PLAN、SPECS_DIR、BRANCH 等路径，然后按两个阶段产出：

Phase 0（大纲与研究）：把 Technical Context 中每个 NEEDS CLARIFICATION、每个依赖、每个集成点转成研究任务，汇总进 research.md，每条记录采用 Decision / Rationale / Alternatives considered 三段格式——所有待澄清项必须在此清零。
Phase 1（设计与契约）：
- 从规格抽取实体 → data-model.md（字段、关系、来自需求的校验规则、状态迁移）；
- 有对外接口的项目 → contracts/ 目录（库的公开 API、CLI 的命令 schema、Web 服务的端点、解析器文法、应用 UI 契约等；纯内部工具可跳过）；
- quickstart.md：可运行的端到端验证场景（前置条件、安装/测试命令、预期结果），只写"验证指南"，不写实现代码。

命令还要求在设计与设计后各做一次 Constitution Check，违规且无正当理由直接 ERROR。

`/speckit.checklist`："给需求写的单元测试"

为功能生成质量清单——原文档的比喻是**"需求的单元测试（unit tests for your requirements）"。它不测试代码，而是检查规格本身是否完整、清晰、无歧义、一致**，例如"拖拽规则是否为每一列都定义了？""被指派人被删除后行为是否有定义？"

不带参数做宽泛检查，或传聚焦领域做定向检查：

/speckit.checklist

/speckit.checklist Focus on the Kanban board interactions and comment permissions.

勾选语义（原文档强调的所有权规则）：本命令生成的自定义清单是评审人所有（reviewer-owned）的需求质量评审产物。智能体只有在被明确要求时才可协助评估；实现过程不得静默自我批准。[x] 表示评审人认定该需求质量准则已满足，不表示实现工作已完成。

templates/commands/checklist.md 给出了完整的生成规范：

文件与编号：写入 FEATURE_DIR/checklists/<domain>.md（如 ux.md、api.md、security.md）；文件不存在则从 CHK001 开始新建，已存在则只追加并从上一个 CHK 号续编，永不删除或替换既有内容；新生成项一律 [ ] 未勾选。
条目写法禁令：严禁出现 "Verify/Test/Confirm/Check + 实现行为" 的条目（如"验证落地页显示 3 张卡片"❌）；必须是问句且针对需求本身，如"是否量化了 'fast loading' 的时长阈值？[Clarity, Spec §NFR-2]"✅，并标注质量维度（Completeness/Clarity/Consistency/Coverage/Measurability 等）与可追溯引用（[Spec §X.Y]、[Gap]、[Ambiguity]、[Conflict]），至少 80% 条目须带追溯引用。
场景分类覆盖：检查 Primary / Alternate / Exception / Recovery / Non-Functional 五类场景的需求是否齐备；涉及状态变更时追问回滚需求。
处置闭环：审查生成的清单，若暴露缺口，回到 /speckit.clarify 或 /speckit.specify 收紧规格后再做任务分解；确认准则满足后才逐项打 [x]。

`/speckit.tasks`：生成带依赖序的任务清单

从设计产物生成可执行、按依赖排序的 tasks.md：

/speckit.tasks

阶段组织方式（原文档与 templates/commands/tasks.md 一致）：

Setup：项目初始化；
Foundational：阻塞性前置任务，必须在所有用户故事之前完成；
每个用户故事一个阶段，按 spec.md 中的优先级（P1、P2…）排序；测试任务在被要求时生成在该故事阶段内部，而不是单独一个阶段；
最后是 Polish 阶段处理横切关注点；
可能并行的任务标注 [P] 并行标记。

每条任务必须严格遵循清单格式 - [ ] [TaskID] [P?] [Story?] Description with file path，例如：

- [ ] 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

其中 Task ID（T001 起按执行序编号）与文件路径为必填，[US1] 类故事标签仅出现在用户故事阶段。模板还要求 tasks.md "立即可执行"——每条任务都要具体到 LLM 无需额外上下文即可完成，并附依赖图、每个故事内的并行执行示例与 MVP 范围建议（通常就是 User Story 1）。该命令通过 scripts/bash/setup-tasks.sh --json（见 scripts/bash/setup-tasks.sh）拿到 FEATURE_DIR 与任务模板内容。

`/speckit.analyze`：只读的跨产物一致性分析

对 spec.md、plan.md、tasks.md 做只读（read-only）的跨产物一致性与质量分析，报告冲突、缺口与歧义——例如"某个任务没有对应需求"或"某个 plan 决策与规格矛盾"。它从不编辑任何文件，只产出报告，并可应要求给出修复建议供你批准后手动执行：

/speckit.analyze

templates/commands/analyze.md 定义了它的六类检测通道与严重度分级：

通道	检测内容
A 重复	近似重复的需求，标记低质量表述以便合并
B 歧义	缺可测标准的模糊形容词（fast、scalable、robust…）、未解决的占位符（TODO、TKTK）
C 欠规范	有动词但缺对象/可测结果的需求、缺失验收标准对齐、任务引用了规格/计划中不存在的文件
D 宪法对齐	与 MUST 原则冲突的需求或计划项（自动 CRITICAL）
E 覆盖缺口	零任务的需求、无对应需求/故事的任务、需要构建工作但无任务承接的成功标准
F 不一致	术语漂移、数据实体跨文件缺失、任务顺序矛盾、互相冲突的需求

严重度分为 CRITICAL / HIGH / MEDIUM / LOW 四级，发现条目上限 50 条（超出者聚合为溢出摘要）；报告含逐条发现表、需求覆盖表、指标（总需求数、总任务数、覆盖率、歧义数、重复数、CRITICAL 数）与 Next Actions。

原文档给出的使用策略值得强调：在实现之前运行它——此时产物调整成本最低。发现问题后回到拥有该问题的上游步骤修复：需求问题回 /speckit.specify 或 /speckit.clarify，设计问题回 /speckit.plan，任务问题重跑 /speckit.tasks，然后重跑 /speckit.analyze 直到干净。实现完成之后也可以再跑一次作为额外审查。

`/speckit.implement`：按依赖序执行，清单做门禁

执行 tasks.md 中的任务，按依赖序逐阶段推进并尊重 [P] 并行标记。

/speckit.implement

清单门禁机制（原文档重点，模板 Step 2 详述）：执行前先扫描 FEATURE_DIR/checklists/ 下所有清单文件的复选框状态，统计每项的 Total / Checked / Unchecked 并输出状态表；只要有任何未勾选项就停下来询问"是否仍要继续？"，等待用户明确 yes/no。清单标记对本命令是只读的：只计数、不改写；自定义清单上的 [x] 语义是评审人对需求质量的批准，不是实现完成的证明。

规模策略（原文档两种用法都保留）：

小功能：一次跑完全部构建。
大功能：分阶段执行以避免撑爆智能体上下文——每次用参数圈定范围，验证结果后再继续：

/speckit.implement Implement only the Setup and Foundational phases: project scaffolding and the project/task data model with basic CRUD. Stop before the user-story features.

/speckit.implement Now implement the Kanban board user story: drag-and-drop between columns.

每个阶段验证通过后再进入下一阶段。templates/commands/implement.md 还规定了执行细节：按阶段推进、顺序任务失败即中止、[P] 并行任务失败则继续成功项并汇报失败项、完成的任务必须在 tasks.md 中标为 [X]，并且实现前先做项目配置校验（按 plan 中技术栈生成/校验 .gitignore、.dockerignore、.eslintignore 等忽略文件，附带 Node/Python/Java/.NET/Go/Rust 等十余种技术栈的通用模式清单）。

`/speckit.converge`：实现完成后的收敛校验

对照功能的 spec、plan 与 tasks 评估代码库，确认没有遗漏。它是**追加式（append-only）**命令：从不编辑或删除代码，唯一可能的写入是向 tasks.md 追加任务。且只有在 /speckit.implement 已对当前 tasks.md 运行之后才可运行：

/speckit.converge

它先打印一份按严重度分级的发现摘要，然后收敛到两种结局之一（原文档的两种结局完整保留）：

Converged（已收敛）——没有发现缺口。tasks.md 逐字节保持不变，你会看到类似 ✅ Converged — the implementation satisfies the spec, plan, and tasks. 的干净结果。流程结束，进入代码评审或提交 PR。
Tasks appended（追加了任务）——发现缺口。Converge 把它们作为新任务追加到 tasks.md 的 Convergence 小节下，并告知追加数量。随后重跑 /speckit.implement 完成这些任务，再跑一次 /speckit.converge；每一轮发现都会更少，重复直至报告 converged。

templates/commands/converge.md 进一步明确了它的约束边界：它不是 diff 工具，不跟踪变更、不做 git 分支比较，只评估"当前代码相对功能产物的状态"；spec.md/plan.md 一律不得修改，既有任务（包括上一轮 Convergence 追加的任务）不得改写、重编号、重排或删除；宪法是最高裁决——违反 MUST 原则的代码是最高严重度发现并生成对应修复任务，而若宪法还是未填充的模板则优雅跳过宪法检查。

底层支撑：功能状态、脚本与自动化编排

把九个命令串起来的还有三块仓库级基础设施，理解它们有助于排查实际问题：

1. 功能状态追踪（不依赖 Git 分支）。Spec Kit 通过 .specify/feature.json 记录当前活跃功能目录（可用环境变量 SPECIFY_FEATURE_DIRECTORY 覆盖）。命令从该状态而非 checkout 的 Git 分支解析功能——不需要 Git 也能跑；可选的 git 扩展提供 001-feature-name 式编号分支用于版本控制组织，但活跃功能始终以 feature.json 指向的目录为准，单纯 git checkout 不会切换它。从源码结构看，scripts/bash/common.sh 中 find_specify_root 向上寻找 .specify/ 目录定位项目根（防止误取父仓库根），SPECIFY_INIT_DIR 环境变量则允许从 monorepo 根目录显式指向某个成员项目而无需 cd。

2. 辅助脚本三语言并行。每个命令模板的 frontmatter 都声明了 sh / ps / py 三套等价脚本（如 scripts/bash/check-prerequisites.sh --json --paths-only、scripts/python/check_prerequisites.py），specify init 时交互式选择其一，非交互运行默认按操作系统选 shell 变体，也可用 --script sh|ps|py 显式指定。这些脚本负责解析功能目录、模板解析（resolve-template）、前置检查（check-prerequisites）与产物落位（setup-plan/setup-tasks）。

3. Workflow 自动化编排。workflows/speckit/workflow.yml 提供了一条 "Full SDD Cycle" 工作流：specify → plan → tasks → implement 四个核心命令按序调度，中间在 spec 与 plan 之后各插一个 gate（审批门）——reviewer 选 approve 才继续，reject 则 abort。它要求 speckit_version >= 0.8.5（该版本起引擎侧支持 integration: "auto" 解析），且 integrations.any 列表只是兼容性提示而非封闭集合——任何提供这四个核心命令的集成都能跑。这为 CI/自动化场景下复现"短路径"提供了现成模板。