🌱 Spec Kit 与 Specify CLI 速查表
版本unknown 更新日志2025-11-21 GitHubgithub/spec-kit
340px

🌱 Spec Kit 概览与核心理念 >>

  • Spec Kit：围绕“规范驱动开发”（Spec-Driven Development，SDD）的开源工具集。
  • 核心目标：让规范（spec）成为一等公民，通过可执行规范驱动代码生成。
  • Specify CLI：命令行入口，负责初始化项目、检测依赖等。
  • /speckit.* 命令：在 AI 编码助手中暴露一组结构化的工作流指令。

规范驱动开发的关键思想

- 规范是「真相来源」，代码是规范的表达形式
- 通过可执行的规格、实现计划和任务清单连接「文字 → 代码」
- 调整功能 = 演进规格和实现计划，而不是直接改动散落的代码
- AI 负责从规范到代码的自动化过渡，人负责定义和审阅规范
先写规范，再写实现，Spec Kit 把「规格 → 计划 → 任务 → 代码」变成一条自动化流水线。

⚡ 安装 Specify CLI 与快速开始 >>

  • 推荐方式：使用 uv tool 持久安装。
  • 一次性使用：使用 uvx 直接运行而不安装。
  • 核心命令：specify init 初始化项目；specify check 检查依赖。

安装 & 升级示例（Bash）

# 持久安装 Specify CLI（推荐）
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git

# 快速升级到最新版本
uv tool install specify-cli --force --from git+https://github.com/github/spec-kit.git

# 一次性使用（不安装到 PATH）
uvx --from git+https://github.com/github/spec-kit.git specify init <PROJECT_NAME>

初始化与系统检查

# 初始化一个新项目
specify init my-project

# 检查依赖（git、AI agent 工具、编辑器集成等）
specify check
使用 uv 统一管理 Specify CLI，结合 specify init 与 specify check 完成基础环境准备。

🔧 specify init 常用参数速查 >>

  • <project-name>：项目目录名称，可用 . 或 --here 指向当前目录。
  • --ai：指定 AI 助手，例如 claude、gemini、copilot、cursor-agent 等。
  • --script：脚本类型，sh（Bash/Zsh）或 ps（PowerShell）。
  • --no-git：跳过 Git 仓库初始化。
  • --here / --force：在当前目录初始化，并在非空目录中强制覆盖。
  • --ignore-agent-tools：跳过对本地 AI 工具（如 Claude Code）的检测。
  • --github-token：用于 API 请求的 GitHub Token。

典型用法示例

# 默认初始化到新目录
specify init my-project

# 指定 AI 助手为 Claude
specify init my-project --ai claude

# 支持 Cursor / Windsurf 等编辑器集成
specify init my-project --ai cursor-agent
specify init my-project --ai windsurf

# 在当前目录初始化（可能已有代码）
specify init . --ai copilot
specify init --here --ai copilot

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

# 跳过 Git 初始化
specify init my-project --ai gemini --no-git
specify init 既负责创建项目骨架，也负责为常见 AI 助手预配置命令和脚本。

🤖 支持的 AI Agents 与集成 >>

  • 主流助手：Claude、Gemini、Copilot、Cursor、Windsurf、Qwen 等。
  • 通用模式：通过 --ai <agent> 选择具体助手。
  • 脚本自动选择：根据 OS 自动选择 Bash / PowerShell，或通过 --script 手动指定。
  • Agent 特殊集成：为不同助手预配置快捷命令和工作流。

选择 AI 助手的实践建议

- 团队已有主力 AI 助手时，在初始化时显式传入 `--ai`
- 在多人协作项目中保持 `--ai` 选项一致，避免脚本差异
- 如需跨平台脚本（Windows + Linux），优先保证两种脚本都可用
- 在企业环境中结合 `--github-token` 以避免 API 速率或鉴权问题
Spec Kit 将「项目骨架」和「AI 助手工作流」打包在一起，让不同助手共享同一套规范驱动流程。

📚 Spec-Driven 开发 6 步流程 >>

  • 1. constitution：定义项目宪章与原则。
  • 2. specify：描述要构建的产品与场景。
  • 3. plan：将需求转化为技术实现计划。
  • 4. tasks：生成可执行的任务列表。
  • 5. implement：按任务驱动实现与重构。
  • 6. iterate：通过更新规范推动后续演进。

典型工作流（概览）

/speckit.constitution   # 建立项目原则与质量红线
/speckit.specify        # 聚焦「要做什么」与「为什么」
/speckit.plan           # 选择技术栈与架构，形成实现计划
/speckit.tasks          # 从计划中拆分出任务列表
/speckit.implement      # 根据任务执行实现与验证
把「写需求 → 画架构 → 列任务 → 实现」结构化为一条由 /speckit.* 命令串联的流水线。

📜 /speckit.constitution：项目宪章与原则 >>

  • 定位：定义项目层面的原则、质量标准与约束。
  • 产物：生成或更新宪章文档，作为后续规格与计划的「上位规则」。
  • 作用：统一团队对测试、性能、UX、一致性等维度的期望。

使用示例

/speckit.constitution Create principles focused on code quality, testing standards,
user experience consistency, and performance requirements

编写建议

- 明确哪些质量指标是「必须满足」，哪些是「可选加分」
- 写清楚测试策略（单测/集成/端到端）和覆盖率期望
- 统一错误处理、日志、可观测性等横切关注点
- 对「禁止使用」或「慎用」的技术栈提前声明
宪章决定整个项目「怎么做事」，后续的 spec 和 plan 都应与之对齐。

📝 /speckit.specify：编写功能规格 >>

  • 关注点：聚焦「做什么」「为什么」，刻意回避具体技术细节。
  • 产物：生成 feature 分支与 specs/<feature>/spec.md。
  • 内容形态：用户故事、用例场景、验收标准、边界条件等。

调用示例

/speckit.specify Build an application that can help me organize my photos
in separate photo albums...（省略具体描述）

编写高质量规格的技巧

- 多用「用户故事」风格：作为某某角色，我希望……
- 明确成功标准：什么情况下可以认为功能完成？
- 标记不确定点：使用 [NEEDS CLARIFICATION: 问题] 标注模糊需求
- 不提前锁定技术栈，把「怎么实现」留给 `/speckit.plan`
规格阶段只谈「做什么」，不谈「怎么做」，确保需求在技术选型前就足够清晰。

🧩 /speckit.plan：技术实现计划 >>

  • 输入：已有的功能规格 spec.md 与项目宪章。
  • 产物：生成 specs/<feature>/plan.md 等设计文档。
  • 内容：技术栈选择、架构分层、边界划分、数据模型、高层组件划分等。

调用示例

/speckit.plan The application uses Vite with minimal number of libraries.
Use vanilla HTML, CSS, and JavaScript as much as possible...

高质量实现计划的要点

- 对每个关键技术选择写出 rationale（为什么这样选）
- 用模块/组件的方式拆解系统，而不是按文件罗列
- 提前思考数据模型与边界（API、消息、事件）
- 将非功能性需求（性能、安全、监控）融入计划中
实现计划连接「业务规格」与「代码结构」，是后续任务拆解与实现的蓝图。

✅ /speckit.tasks 与 /speckit.implement >>

  • /speckit.tasks：从 plan 及相关文档自动生成任务清单 tasks.md。
  • /speckit.implement：按任务顺序执行，实现代码与测试。
  • 并行标记：[P] 表示可以并行执行的任务。

示例工作流

/speckit.tasks      # 生成 tasks.md
/speckit.implement  # 按 tasks.md 执行实现

结合传统开发流程的类比

- 传统：PRD → 设计文档 → 手工拆任务 → 手工实现
- 使用 Spec Kit：
  - `/speckit.specify` 写 PRD 级规格
  - `/speckit.plan` 生成技术设计
  - `/speckit.tasks` 自动拆解任务
  - `/speckit.implement` 驱动 AI 实现
tasks + implement 让「写文档」直接变成「驱动实现」，减少手工搬运与遗漏。

📂 项目目录结构与 SPECIFY_FEATURE >>

  • feature 目录：通常位于 specs/<feature-branch>/。
  • 核心文件：spec.md、plan.md、tasks.md、quickstart.md、data-model.md 等。
  • 环境变量：SPECIFY_FEATURE 用于在非 Git 场景下指定当前 feature。

典型目录结构示意

specs/
  001-photo-albums/
    spec.md          # 功能规格
    plan.md          # 技术实现计划
    tasks.md         # 任务清单
    quickstart.md    # 快速验证场景
    data-model.md    # 数据模型
    contracts/       # API/事件契约
    research.md      # 研究/调研记录

在无 Git 仓库下切换 feature

# 在当前 shell / Agent 上下文中指定要工作的 feature
export SPECIFY_FEATURE=001-photo-albums   # Bash / Zsh
$env:SPECIFY_FEATURE = \"001-photo-albums\"  # PowerShell
使用 SPECIFY_FEATURE 可以在没有 Git 分支的环境中手动指定当前正在处理的 feature。

🩺 故障排查与实践建议 >>

  • Git / 鉴权问题：在 Linux 上可按 README 中脚本安装 Git Credential Manager。
  • AI Agent 行为异常：回到宪章与规格，检查是否存在模糊或冲突。
  • 规格质量不足：重复运行 clarify / checklist / analyze 等辅助命令。
  • 计划过度设计：通过 plan 审阅阶段减少不必要的复杂度。

提升规格质量的辅助命令

- `/speckit.clarify`   ：补充和澄清模糊需求（推荐在 `/speckit.plan` 之前）
- `/speckit.checklist`：生成自定义检查清单，像「英语单元测试」一样验证规格质量
- `/speckit.analyze`  ：在 plan → tasks 阶段做一致性与覆盖率分析
一旦实现出现偏差，优先检查规格与计划是否准确，而不是直接修改代码。