Spec Kit specify CLI 完全参考指南：核心命令、集成、扩展、预设、工作流与 /speckit.* 智能体命令

Spec Kit 的 Specify CLI（specify）负责管理 Spec-Driven Development（SDD）的完整生命周期——从项目初始化、AI 编码智能体集成，到可扩展的命令体系与多步工作流自动化。本文以官方参考文档为骨架，逐层拆解 specify 的六大能力域（Core Commands、Integrations、Extensions、Presets、Workflows、Bundles）以及构建在其上的 /speckit.* 智能体命令，并给出对应的源码位置，帮助你在实际项目中完成初始化、多智能体切换、扩展定制与自动化流水线搭建。

一、CLI 总览：一条命令管理 SDD 全生命周期

Spec Kit 的 pyproject.toml 声明了项目入口：specify = "specify_cli:main"，包名 specify-cli，要求 Python 3.11+，核心依赖包括 typer、rich、pyyaml、pathspec 等。CLI 实现位于 src/specify_cli/ 目录，其中：

• src/specify_cli/integrations/ —— 各 AI 编码智能体的适配实现（claude、copilot、gemini、codex、generic 等 40+ 个子包）；
• src/specify_cli/bundler/ —— 包管理器核心，含 installer、resolver、conflict、validator 等分层服务；
• src/specify_cli/workflows/ —— 工作流引擎与步骤（command、shell、gate、if_then、fan_out/fan_in、while_loop 等）；
• templates/commands/ —— 内置的 /speckit.* 命令模板（specify、plan、tasks、implement 等）。

整个参考文档的组织方式如下表所示，这也是本文的章节脉络：

能力域	解决的问题	参考文档
Core Commands	项目初始化、系统检查、版本信息	docs/reference/core.md
Integrations	连接 Spec Kit 与 AI 编码智能体	docs/reference/integrations.md
Extensions	添加领域命令、外部工具集成、质量门禁	docs/reference/extensions.md
Presets	覆盖模板/命令/脚本来定制工作流	docs/reference/presets.md
Workflows	多步流程自动化：条件、循环、暂停恢复	docs/reference/workflows.md
Bundles	将扩展/预设/工作流组合成可安装单元	docs/reference/bundles.md
Agentic Commands	编码智能体执行的 /speckit.* 命令	docs/reference/agentic-sdd.md

二、Core Commands：初始化、检查与版本

specify init：创建 Spec Kit 项目

specify init [<project_name>]

选项	说明
--integration <key>	选择 AI 编码智能体集成（如 copilot、claude、gemini）
--integration-options	集成的附加选项（如 --integration-options="--commands-dir .myagent/cmds"）
--script sh|ps|py	脚本类型：sh（bash/zsh）、ps（PowerShell）、py（Python）
--here	在当前目录初始化，而不是新建目录
--force	在已有文件的目录中强制合并/覆盖
--ignore-agent-tools	跳过对 AI 编码智能体 CLI 工具的检查
--preset <id>	初始化时同时安装一个预设

该命令创建完整的目录结构、模板、脚本和智能体集成文件。需要注意：Git 仓库初始化和分支管理由 git 扩展负责（默认不安装），需另行执行 specify extension add git。省略 --integration 时，交互式终端会弹出选择提示；CI 等非交互场景默认回落到 GitHub Copilot，可通过环境变量 SPECKIT_INTEGRATION_DEFAULT 修改，显式传参始终优先。

常见用法示例：

# 新建项目并指定集成
specify init my-project --integration copilot

# 在当前目录初始化
specify init --here --integration copilot

# 强制合并到非空目录
specify init --here --force --integration copilot

# 使用 PowerShell 脚本（Windows/跨平台）
specify init my-project --integration copilot --script ps

# 初始化时安装预设
specify init my-project --integration copilot --preset compliance

关键环境变量（两个解析轴）

变量	作用
SPECKIT_INTEGRATION_DEFAULT	覆盖 init 的集成回退值；无法识别的值会警告并使用内置默认值 copilot
SPECIFY_INIT_DIR	在 monorepo 等场景下从项目外指向成员项目根（必须包含 .specify/，否则报错且不回退）；被核心特性脚本与 git 扩展的分支创建逻辑继承
SPECIFY_FEATURE_DIRECTORY	覆盖项目内当前激活的特性目录（优先于 .specify/feature.json），可与 SPECIFY_INIT_DIR 组合实现"先选项目、再选特性"
SPECIFY_FEATURE	在非 Git 仓库中手动指定特性目录名（如 001-photo-albums）

此外，specify init 会生成受管理的 .specify/.gitignore，将机器本地状态（feature.json、各扩展的 local-config.yml）排除在版本控制之外，同时保留宪法、模板、脚本等团队共享内容。

specify check 与 specify version

specify check          # 检查 CLI 型 AI 编码智能体是否可用（离线命令，IDE 型智能体被跳过）
specify version        # 显示 CLI 版本、Python 版本、平台与架构
specify version --features            # 离线查看本地 CLI 能力
specify version --features --json     # JSON 形式，供脚本/智能体按能力选择工作流
specify --version / specify -V        # 快速版本检查

若命令行为像旧版本或某 CLI 特性缺失，可运行 specify self check 判断本地 CLI 是否落后于最新发行版。

三、Integrations：把 Spec Kit 接入你的 AI 编码智能体

集成（Integration）为特定智能体生成对应的命令文件与目录结构。核心规则：每个项目同时只有一个默认集成处于激活状态，但允许受控地共存多个集成，可随时切换。

支持的智能体

docs/reference/integrations.md 列出了 40 余个内置集成，包括 Claude Code（claude）、GitHub Copilot（copilot）、Gemini CLI（gemini）、Codex CLI（codex）、Cursor（cursor-agent）、Goose、Kimi Code、Qwen Code、Zed 等，以及用于自定义智能体的 generic（配合 --integration-options="--commands-dir <path>"）。其中相当一部分是 skills-based 集成——将 speckit-<command>/SKILL.md 安装到智能体专属目录（如 .claude/skills），并以 /speckit-<command>、$speckit-<command> 等形式调用；src/specify_cli/integrations/ 下每个子包对应一个智能体的落地实现，并配套 tests/integrations/ 中的同名测试文件（如 test_integration_claude.py、test_integration_gemini.py）保障行为一致性。

生命周期管理命令族

命令	用途与关键选项
specify integration list	列出内置集成、当前已装集成、是否需要 CLI 工具；--catalog 可浏览社区目录
specify integration install <key>	安装指定集成；目标未安装时等价于"卸载+安装"一步完成，失败自动回滚
specify integration uninstall [<key>]	卸载集成；未修改的文件（按 SHA-256 校验）自动删除，手动修改过的文件被保留，--force 可强制删除
specify integration switch <key>	更换默认集成；目标已安装时行为等价于 use
specify integration use <key>	仅切换默认集成并重新脚手架化已装的扩展与预设（--force 可覆盖共享模板）
specify integration upgrade [<key>]	升级 Spec Kit 后刷新管理文件；检测到本地修改会阻断升级除非 --force
specify integration status [--json]	只读状态报告：默认集成、已装集成、缺失/修改的管理文件、共享基础设施健康度；状态为 ok/warning 时退出码为 0，仅 error 时退出码 1

多安装安全性（multi-install safe）

多个集成可以共存，但仅在两者都被声明为"多安装安全"时自动放行；其他组合需显式 --force 确认。多安装安全要求：静态唯一的智能体根目录与命令目录、稳定的调用配置、且管理文件不与其他安全集成重叠。.specify/integration.json 中记录 default_integration、installed_integrations、integration_settings 及用于未来迁移的 integration_state_schema。

集成目录（Catalog）

目录按优先级解析（首个命中生效）：

1. 环境变量 SPECKIT_INTEGRATION_CATALOG_URL（覆盖一切）
2. 项目配置 .specify/integration-catalogs.yml
3. 用户配置 ~/.specify/integration-catalogs.yml
4. 内置默认（官方 + 社区目录）

通过 specify integration catalog add <url> / remove <index> 管理项目级目录源（URL 必须为 HTTPS，本地测试除外）。此外，specify integration scaffold <key> 可在 Spec Kit 仓库根目录生成新的内置集成包骨架与测试骨架，模板类型可选 markdown（默认）、skills、toml、yaml。

四、Extensions：为 Spec Kit 添加新能力

扩展引入新的命令与模板——领域特定命令、外部工具集成、质量门禁等。与集成不同，多个扩展可以共存于同一项目，各自独立安装、更新、启用、禁用或移除。仓库自带四个内置扩展：extensions/git（Git 工作流）、extensions/agent-context（上下文文件同步）、extensions/assess（评估流程）、extensions/bug（缺陷分诊）。

命令族

specify extension search [query]        # 搜索（--tag / --author / --verified）
specify extension add <name>            # 安装（--dev 本地目录 / --from <url> / --force / --priority <N>）
specify extension remove <name>         # 移除（--keep-config 保留配置 / --force 跳过确认）
specify extension list                 # 列出已装（--available / --all）
specify extension info <name>          # 查看详情
specify extension update [<name>]      # 更新单个或全部
specify extension enable <name>        # 启用
specify extension disable <name>       # 禁用（不卸载，命令不可用）
specify extension set-priority <name> <priority>   # 同名命令冲突时，数值小者优先

扩展安装后会自动向当前激活的智能体集成注册其命令；若命令未在智能体中出现，先确认安装与启用状态，再重启智能体。

目录信任模型：发现源与安装源的分野

这是扩展体系中最值得注意的安全设计。目录分两类，且这个区别是安全边界而非限制：

• 安装源（install_allowed: true）：内置的 default（官方）目录，以及你自己编写并审核过的目录；
• 仅发现源（install_allowed: false）：内置的 community 目录开箱即可搜索但不可直接安装——因为它是开放的、未经审核的清单，把其中所有内容变成一条命令可装等于无审查地拉取任意第三方代码。

正确安装社区扩展的两条路径：

1. 单个审核安装：specify extension info <name> 会打印"候选归档"URL，人工审核该发布归档后执行 specify extension add <name> --from <archive-url>；
2. 自建受管目录：维护自己审核过的目录并标记 install_allowed: true。

配置分层与 Hook

扩展安装目录下有三层配置文件：

.specify/extensions/<ext>/
├── <ext>-config.yml           # 项目配置（纳入版本控制）
├── <ext>-config.local.yml     # 本地覆盖（gitignored）
└── <ext>-config.template.yml  # 模板参考

合并顺序（优先级依次升高）：扩展默认值（extension.yml）→ 项目配置 → 本地覆盖 → 环境变量（SPECKIT_<EXT>_*）。初始化配置只需复制模板：

cp .specify/extensions/<ext>/<ext>-config.template.yml \
   .specify/extensions/<ext>/<ext>-config.yml

项目级注册与 Hook 配置存放在 .specify/extensions.yml，hooks 按事件分组（如 before_implement、after_implement），每个条目支持 extension、command、enabled、optional、priority、prompt、description、condition 字段。optional: true 的 Hook 会带 prompt 询问用户；optional: false 则作为自动 Hook 输出（包含 EXECUTE_COMMAND 标记）。从源码结构看，Hook 的分发由 HookExecutor.get_hooks_for_event() 负责，对缺失/非法的 priority 统一回落到 10（布尔值与非数值拒绝、小于 1 归一为 10），但当前命令模板按 YAML 配置顺序而非优先级排序来呈现 Hook。

五、Presets：不改工具链，只改工作流

预设通过覆盖命令文件、模板文件与脚本文件来定制 Spec Kit 的行为——用于强制组织规范、适配自身方法论或本地化整个体验。多个预设可按优先级叠加。仓库内置了 presets/lean（精简版核心命令）与 presets/constitution-sync。

命令族

specify preset search [query]      # 搜索（--tag / --author）
specify preset add [<preset_id>]   # 安装（--dev <path> / --from <url> / --priority <N>）
specify preset remove <preset_id>  # 移除并清理已注册命令
specify preset list                # 按解析/优先级顺序列出（同优先级按 id 字母序）
specify preset info <preset_id>    # 查看模板、元数据、标签
specify preset resolve <name>      # 追踪某文件的完整解析栈——调试多个预设提供同名文件时的利器
specify preset enable/disable <preset_id>  # 禁用后从文件解析中跳过，但已注册命令保留
specify preset set-priority <preset_id> <priority>  # 数值小者优先

文件解析栈与组合策略

每个文件按名称独立在优先级栈上解析，不同文件可以来自不同层。默认策略为 replace（栈中首个命中整体胜出）；模板与命令还支持组合策略：prepend（置于低优先级内容之前）、append（置于之后）、wrap（用低优先级内容替换 {CORE_TEMPLATE} 占位符）；脚本支持 replace 与 wrap，占位符为 $CORE_SCRIPT。

解析栈从高到低依次为：

1. 项目本地覆盖 — .specify/templates/overrides/
2. 已安装预设 — 按优先级排序（数值小者先查）
3. 已安装扩展 — 按优先级排序
4. Spec Kit 核心 — .specify/templates/

示例：specify preset add compliance --priority 5 与 specify preset add team-workflow --priority 10 同时提供 plan-template.md 时，compliance（5 < 10）胜出；只有一个提供的文件直接用那个；都没有则回落核心默认。目录管理与扩展相同，配置文件为 .specify/preset-catalogs.yml，环境变量 SPECKIT_PRESET_CATALOG_URL 具有最高覆盖权。

六、Workflows：可暂停、可恢复的多步流程自动化

工作流把命令、提示、Shell 步骤与人工检查点串成可重复执行的序列，支持条件逻辑、循环、fan-out/fan-in，并能在中断点精确暂停与恢复。仓库内置了 workflows/speckit/workflow.yml，引擎实现见 src/specify_cli/workflows/engine.py，步骤类型以子目录组织（command/、shell/、gate/、if_then/、fan_out/、fan_in/、while_loop/、do_while/、switch/ 等），并有 tests/workflows/ 覆盖解析器、overlay 合并与安全测试。

核心命令

specify workflow run <source>

选项	说明
-i / --input	以 key=value 传入输入（可重复）
--json	输出单一 JSON 对象（进度信息改走 stderr，stdout 保证可解析）

<source> 可以是目录 ID、URL 或本地文件路径。示例：

specify workflow run speckit \
  -i spec="Build a kanban board with drag-and-drop task management" \
  -i scope=full

--json 的输出形如：

{
  "run_id": "662bf791",
  "workflow_id": "build-and-review",
  "status": "paused",
  "current_step_id": "review",
  "current_step_index": 0
}

failed/aborted 运行会附带 error 字段；该错误会持久化到运行的 state.json，事后可通过 specify workflow status <run_id> --json 查看。workflow_id 取自 YAML 中声明的 workflow.id，而非文件名。

specify workflow resume <run_id>   # 从停止的精确步骤恢复；--input 值合并进已存输入并重新校验
specify workflow status [<run_id>]  # 查看状态或列出所有运行
specify workflow list               # 列出项目已安装的工作流
specify workflow add <source>       # 安装（--dev 本地 / --from <url>；支持 YAML、目录、zip/tar 归档）

运行状态机为：created → running → completed / paused / failed / aborted。大多数工作流命令要求项目已 specify init，唯一例外是运行本地 YAML 文件——可以脱离项目执行，此时运行状态存放在当前目录的 .specify/workflows/runs/<run_id>/ 下。此外，工作流 overlay 机制允许项目在不修改已安装 workflow.yml 的前提下扩展或覆盖工作流，使本地定制在 specify workflow add 升级后依然安全。

七、Bundles：把组件栈打包成一个版本化单元

Bundle 把已有的扩展、预设、工作流与步骤组合成单一、版本化、可安装的单元。它不引入新的运行时行为，而是在已有原语之上的分发与组合层。Bundle 由 bundle.yml 清单描述，通过与其他组件相同的目录栈发现；安装时对声明组件做版本解析与钉选，检查唯一的跨 bundle 冲突点（激活的集成），并通过完整的溯源记录实现干净的移除与刷新。实现集中在 src/specify_cli/bundler/（installer、resolver、conflict、validator、packager），仓库同时提供了四个角色示例：examples/bundles/developer、product-manager、business-analyst、security-researcher。

命令族

命令	说明
specify bundle search [query]	搜索全部目录，附 verified/community 信任指示器；--offline / --json
specify bundle info <bundle_id>	展示完全展开的组件集（每个扩展/预设/步骤/工作流及其钉选版本）——与 install 实际执行的计划一致，可先预览再安装
specify bundle install <bundle_id | path>	通过各原语自身机制安装整套组件；当前目录非 Spec Kit 项目时会先自动初始化；不覆盖已初始化项目的激活集成，集成不匹配时整体中止
specify bundle update [<bundle_id>]	重新解析并刷新组件到钉选版本；--all 更新全部；保留原语级覆盖（如预设优先级）
specify bundle remove <bundle_id>	仅移除该 bundle 贡献的组件，不产生连带删除
specify bundle list	列出已装 bundle 及版本、组件数、安装时间
specify bundle init [<bundle_id>]	幂等地确保当前目录是项目，再可选安装 bundle——新 checkout 的一步式引导
specify bundle validate	校验 bundle.yml 形式与组件引用可达性；离线或目录不可达的引用降级为警告而非失败
specify bundle build	构建 bundle 发布产物（--path / --output）

两点重要的行为细节：

• 版本钉选只在安装时生效。幂等检查基于 id 而非版本：已存在的组件在 install 时会被跳过而不比对磁盘版本，需运行 specify bundle update 才重新应用钉选版本；
• 安装失败不留痕。失败的安装不写溯源记录，并已装组件会做尽力清除（清除错误被吞掉，可能残留部分磁盘状态）。

八、Agentic Commands：/speckit.* 智能体命令

前述章节都是 specify CLI 管理的基础原语；/speckit.* 则是编码智能体在编辑器内逐步骤执行的智能体流程。命令形态因智能体而异——skills 型智能体可能用 $speckit-*（Codex、ZCode）或 /skill:speckit-*（Kimi），需以你的智能体实际暴露的形式为准。

Agentic SDD：九步核心流程

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

按顺序执行，仅 /speckit.specify 是 /speckit.plan 的硬性前置；clarify / checklist / analyze 是面向有实质模糊性的特性的质量门禁，按需加入。

命令	职责
/speckit.constitution	创建/更新项目宪法——后续所有阶段对照的指导原则，并把依赖模板保持同步；将原则作为参数传入
/speckit.specify	从自然语言描述生成特性规格，聚焦"做什么、为什么"（用户可见行为与目标），不写技术栈；可维护内置的 checklists/requirements.md
/speckit.clarify	针对当前规格中欠明确处提出至多 5 个针对性问题，并把答案写回 spec.md；可反复运行、每次聚焦不同区域
/speckit.plan	从规格生成设计产物，技术栈、架构、约束在此给出
/speckit.checklist	为特性生成"需求的单元测试"式质量清单，检查规格本身是否完整、清晰、无歧义、一致；[x] 表示评审者确认该需求质量标准已满足
/speckit.tasks	从设计产物生成按依赖排序的 tasks.md：Setup → Foundational → 每个用户故事一个阶段（按优先级）→ 收尾的 Polish 阶段；测试按需生成在故事阶段内，可并行任务带标记
/speckit.analyze	只读地跨 spec.md/plan.md/tasks.md 做一致性与质量分析，报告冲突、缺口与歧义但不编辑文件；发现问题应回到负责的命令修复后再复跑直至干净
/speckit.implement	按 tasks.md 的依赖顺序执行任务、尊重并行标记；执行前读取清单勾选状态作为门禁，有未勾选项会先询问，且不修改清单标记；大特性可分阶段运行
/speckit.converge	收尾阶段的收敛处理

Agentic Bug Fix：bug 扩展的三步分诊

bug 扩展为缺陷处理提供 assess → fix → test 三步流程，每个 bug 独立存放于 .specify/bugs/<slug>/ 目录。它是可选安装的内置扩展，使用前先执行：

specify extension add bug

/speckit.bug.assess -> /speckit.bug.fix -> /speckit.bug.test

三个命令共享同一句柄——slug（以 slug=<name> 传入，归一化为小写 kebab-case）：

• /speckit.bug.assess：只读分诊 bug 报告（粘贴的堆栈或 issue URL），判断是否真实 bug、定位疑似代码路径并给出修复建议；仅写 assessment.md；
• /speckit.bug.fix：唯一修改源码的命令，按评估中的建议实施并记录改动明细，超出评估范围的情况记入"Deviations from Assessment"；产出 fix.md；
• /speckit.bug.test：重跑复现与新增测试来验证修复，结论为 verified / partial / failed 三选一且不夸口——评估中列出的复现若未实际执行，结果降级为 partial；对源码只读，产出 test.md。

对应命令模板位于 extensions/bug/commands/（speckit.bug.assess.md、speckit.bug.fix.md、speckit.bug.test.md）。

九、落地建议与延伸阅读

• 新项目起步：specify init <name> --integration <key> 选定智能体，随后在编辑器内按 /speckit.constitution → /speckit.specify 开始；需要 Git 特性分支时再 specify extension add git。
• 团队规范化：用 preset 覆盖模板与术语、用 extension 增加门禁命令、需要分角色交付时用 bundle 一步到位（specify bundle info 可先预览组件集）。
• 自动化：把重复流程写成 workflow 并用 --json 输出接入 CI；specify version --features --json 与 specify integration status --json 都是为脚本与智能体设计的稳定机器可读输出。

进一步的官方参考入口：Core Commands、Integrations、Extensions、Presets、Workflows、Bundles、Agentic SDD、Agentic Bug Fix；扩展开发可参考 extensions/EXTENSION-DEVELOPMENT-GUIDE.md 与 extensions/RFC-EXTENSION-SYSTEM.md。