Jason Yan

Appearance

规范驱动开发：使用 Spec Kit 系统化提升 AI 辅助编程质量

🕒 Published at:

前言 ​

在 AI 辅助编程的实践中，你是否遇到过这些问题：

  • 频繁地 @文件、@片段，然后绞尽脑汁的结合需求去编写 Prompt，耗时 15 分钟，反复修改后，AI 生成的代码仍然与预期不符
  • 完成需求后，想要回顾之前的设计原则和改动点，却找不到任何记录
  • 开发完成后希望 AI 补充文档，却发现上下文过长导致关键信息被压缩
  • 编辑器配置和规则散落各处，缺乏统一的项目原则和规范
  • 陷入 AI 编程的"自证陷阱"，无法实现标准化、流程化的开发

Spec Kit 的出现为这些问题提供了一种全新的解决方案。它倡导"规格即代码"的理念，改变了以往编写简单 Prompt 就让 AI 编码、反复修改却没有专业系统记录的开发模式。

什么是 Spec Kit ​

Spec Kit 是一种"规格即代码"的开发方案，由 GitHub 团队于 2025 年 10 月推出。

它引入了一种名为 "规范驱动开发"（Specification-Driven Development） 的软件开发模式，旨在利用 AI 提升代码质量和开发效率。其核心思想是将需求规格置于开发流程的中心，让开发者首先精确地定义"做什么"（What）和"为什么"（Why），然后由 AI 根据这些清晰的规范生成代码。

核心工作流遵循"文档即代码"（Documentation as Code）的理念，在编码前明确定义功能规格和技术方案，确保开发过程的可追溯性和一致性。

如何使用 ​

支持的 AI 助手 ​

目前 Spec Kit 支持多种 AI 助手，包括：

  • Claude
  • Gemini
  • Copilot

如果没有 Claude 账号，也可以将 Claude Code 的模型配置为 Qwen、DeepSeek 等替代方案。

本文以 Claude Code 作为演示。

前置条件 ​

  • Python >= v3.11
  • Git（无版本要求）

安装步骤 ​

打开终端（如 PowerShell、Terminal），执行以下命令安装 specify-cli：

shell
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git

或者在项目内直接初始化：

shell
uvx --from git+https://github.com/github/spec-kit.git specify init <PROJECT_NAME>

项目初始化 ​

进入已有项目目录，执行初始化命令（这里的 claude 可以替换为其他 AI 助手，详见官方文档）：

shell
specify init . --ai claude

初始化完成后的界面如下：

初始化完成

初始化完成后，项目目录中会新增一个 .specify 目录，包含以下内容：

  • memory：存放项目的最高原则和指导方针
  • scripts/bash：Spec Kit 的调用脚本
  • template：每次执行 /speckit 命令时使用的模板文件

目录结构

Spec Kit 常用命令 ​

在正式使用之前，需要了解 Spec Kit 提供的核心命令。所有命令均以 /speckit. 开头：

命令描述
/speckit.constitution制定或更新项目管理原则和开发指南
/speckit.specify明确构建目标（需求和用户故事）
/speckit.plan基于选定的技术栈创建技术实施计划
/speckit.tasks生成可执行的任务清单
/speckit.implement按照计划执行所有任务以构建功能
/speckit.clarify澄清模糊不清的需求（建议在 /speckit.plan 之前执行）
/speckit.analyze进行跨工件一致性和覆盖率分析（建议在 /speckit.tasks 之后、/speckit.implement 之前执行）
/speckit.checklist生成自定义质量检查清单，验证需求完整性

常用命令说明：

  • 核心命令：specify、plan、tasks、implement 构成了主要工作流
  • constitution：用于项目初始化或追加项目规范时定义最高原则
  • clarify：用于补充说明或解决文档中的歧义（例如，明确"在 A 页面、B 页面都要增加此功能"）
  • checklist：生成自检清单，类似于文本化的单元测试

工作流程图 ​

Spec Kit 的使用流程可以分为完整流程和主要流程两种：

完整流程主要流程
完整工作流程主要工作流程

实战示例 ​

启动 Claude Code ​

通过终端或编辑器插件启动 Claude Code。为了提高效率，这里使用 YOLO 模式（跳过权限确认，最后统一进行 Review）：

shell
claude --dangerously-skip-permissions

步骤 1：建立项目原则 ​

在对话中输入以下命令，创建项目的开发原则。你可以根据项目背景、公司规范等进行自定义：

shell
/speckit.constitution 创建专注于代码质量、测试标准、用户体验一致性和性能要求的原则。

创建项目原则

执行后，Spec Kit 会生成项目的核心原则文档：

项目原则结果

步骤 2：使用 specify 定义需求 ​

接下来，使用 Spec Kit 开发一个二维码生成工具库作为示例：

shell
/speckit.specify 需要做一个类似 qrcode 的二维码生成工具库，支持 color、size、logo 等基本配置，且需要有使用示例，需要满足大部分使用场景。

执行后，Spec Kit 会自动生成 spec.md 和 requirements.md 文档。这一步完成了需求拆解和验收标准的明确，相当于完成了产品经理和测试工程师的工作：

需求规格生成结果

步骤 3：使用 clarify 澄清需求（可选） ​

如果生成的需求存在方向偏差或边界模糊的问题，可以使用 clarify 命令进行澄清。这一步并非必须，也可以在后续迭代中优化，或手动修改文档。

例如，如果前面没有明确运行环境，可以使用以下命令：

shell
/speckit.clarify 不需要考虑 Node.js 使用，这里只是 Web 端使用

执行后，Spec Kit 会记录你的问题，并提出其他需要明确的问题，给出推荐方案并等待确认。这个过程可以反复进行：

澄清需求问题

例如，它可能会提出以下边界模糊的问题：

问题 1: Logo 图像输入方式

基于用户明确只针对 Web 端使用，Logo 的输入方式需要明确。

推荐方案：选项 C（File 对象/Blob + URL 字符串）- 这是最灵活的 Web 端方案，既支持用户上传文件，也支持远程图片 URL 和 Base64。

问题 2: 颜色对比度过低时的处理策略

当用户设置的前景色和背景色对比度过低时，系统应该如何处理？

推荐方案：选项 B（警告但允许生成）- 这种方式既尊重开发者的设计自由度，又通过警告提醒潜在问题。

通过多轮澄清，所有问题都会被记录在需求文档中：

澄清结果

步骤 4：使用 plan 生成技术方案 ​

执行 plan 命令时，Spec Kit 会索引 spec.md、requirements.md 以及全局的 constitution.md，制定一个完整的开发计划：

shell
/speckit.plan

生成技术方案

随后，Spec Kit 会深度调研市面上与需求相匹配的技术方案，生成调研报告，并基于调研结果和上下文生成数据模型：

技术调研报告

步骤 5：使用 tasks 进行任务拆解 ​

执行 tasks 命令，让 Spec Kit 基于所有设计文档进行任务拆分：

shell
/speckit.tasks

可以看到，Spec Kit 拆分了 7 个 Story，每个 Story 中的 Tasks 都非常详细：

任务拆解结果

步骤 6：使用 implement 执行任务 ​

执行 implement 命令，基于 tasks.md 执行所有任务：

shell
/speckit.implement

执行过程如下：

正在执行 Phase 1: Setup… (esc to interrupt · ctrl+t to hide todos · 2m 15s · ↑ 1.2k tokens)
  ⎿  ☒ 验证并创建项目 ignore 文件
     ☐ Phase 1: Setup (7个任务)
     ☐ Phase 2: Foundational (7个任务)
     ☐ Phase 3: User Story 1 - MVP (7个任务)
     ☐ Phase 4: User Story 2 (5个任务)
     ☐ Phase 5: User Story 5 (5个任务)
     ☐ Phase 6: User Story 3 (7个任务)
     ☐ Phase 7: User Story 4 (4个任务)
     ☐ Phase 8: Polish (8个任务)

注意：如果执行过程中因任务过多而中断，可以使用以下命令继续执行：

shell
/speckit.implement 继续执行

执行进度

执行结果 ​

这是一个从 0 到 1 的完整需求实现，整体耗时约 1 小时（包括网络延迟和等待指令的时间）。实践结果表明，Spec Kit 能够显著提升需求实现的准确性和代码质量，为 AI 辅助开发提供了可重复、可追溯的标准化工作流程。

以下是最终生成的代码和文档：

执行结果 1

执行结果 2

执行结果 3

总结 ​

相比于传统的 AI 编程方式（反复沟通、多次修改），使用 Spec Kit 就像在与一个集产品经理、测试工程师、架构师、开发工程师于一体的专业团队协作。它以专业且标准化的方式将"一句话需求"转化为高质量的实现，并保留了完整的决策过程和技术文档。

在本次实践中，整个需求一次性完成，达到了预期目标的 90%。唯一的遗憾是文档和示例部分希望使用 VitePress，虽然在初始需求中未明确说明，但在澄清需求阶段也未被询问到。这也提醒我们，在使用 Spec Kit 时，应尽可能在 specify 和 clarify 阶段明确所有细节。

参考资源 ​