Spec Kit 入门指南：让 AI 帮你写更好的代码

iFlow 补给站
,
1

1686×768 261 KB

为什么需要 Spec Kit？

如果你曾经历过以下情况，那么 Spec Kit 正是为你而生：

  • 需求变化无常：客户说要一个"简单的登录功能"，结果做到一半发现需要支持第三方登录、忘记密码、双因子认证…

  • 代码越写越乱：开始时想法很清晰，写着写着就偏离了原始目标，最后自己都不知道在做什么

  • 团队理解不一致：每个人对同一个需求的理解都不同，导致代码风格和实现方式千差万别

  • AI 生成的代码不可控：让 AI 写代码很快，但经常生成的代码不符合预期，需要反复修改

这些问题的根源在于一个核心问题：意图偏移。也就是说，从最初的想法到最终的代码之间，意图在传递过程中逐渐偏离了原始方向。

Spec Kit 是什么？

Spec Kit 引入了一个全新的开发理念：规格驱动开发（Spec-Driven Development, SDD）。

核心理念转变

传统开发模式：想法 → 代码 → 调试 → 修改 → 完成

Spec Kit 模式：想法 → 详细规格 → 基于规格生成代码 → 完成

这个转变的关键在于：

  • 规格是主角，代码是配角：把精力投入到写清楚"要做什么"，而不是急着写"怎么做"

  • 让 AI 按规格工作：给 AI 提供详细、准确的规格说明，它就能生成更符合预期的代码

  • 过程可追溯：从需求到代码的每一步都有记录，便于维护和修改

简单类比

想象你要建房子：

  • 传统方式：拿着锤子就开始敲钉子，边建边想要建成什么样

  • Spec Kit 方式：先画详细的建筑图纸，标明每个房间的用途、尺寸、材料，然后按图施工

Spec Kit 的 7 步工作流程

Spec Kit 将开发过程标准化为 7 个步骤，每一步都有明确的目标和输出物：

1. Constitution（制定原则）

目标：为团队或项目建立开发原则和约定

实际操作：

  • 定义代码风格偏好（比如：使用 TypeScript、遵循函数式编程）

  • 确定技术栈选择（比如：React + Node.js + PostgreSQL）

  • 制定质量标准（比如：所有函数必须有测试、代码覆盖率不低于 80%）

举例：

我们的团队原则：
- 使用 TypeScript 进行类型安全
- 所有 API 接口必须有输入验证
- 优先使用现有的开源库，避免重复造轮子
- 每个功能都要先写测试

2. Specify（明确规格）

目标：将模糊的需求转化为具体的功能规格

实际操作：

  • 详细描述要实现的功能

  • 定义输入输出格式

  • 明确边界条件和异常情况

举例：

功能：用户注册
输入：邮箱、密码、确认密码
验证规则：
- 邮箱格式必须正确
- 密码长度 8-20 位，包含字母和数字
- 两次密码输入必须一致
输出：成功返回用户 ID，失败返回错误信息
异常处理：邮箱已存在时提示用户登录

（可选）3. Clarify（澄清疑问）

目标：识别并解决规格中的模糊点

实际操作：

  • 列出所有不确定的地方

  • 逐一确认或做出假设

  • 记录决策依据

举例：

疑问：密码需要包含特殊字符吗？
决策：暂不要求，但系统要支持后续升级密码策略

疑问：注册后是否自动登录？
决策：是，注册成功后直接跳转到主页

4. Plan（技术方案）

目标：设计具体的技术实现方案

实际操作：

  • 选择技术框架和工具

  • 设计数据库结构

  • 规划 API 接口

  • 确定文件结构

举例：

技术方案：
- 前端：React + TypeScript
- 后端：Express + TypeScript
- 数据库：PostgreSQL
- 认证：JWT Token
- 密码加密：bcrypt

API 设计：
POST /api/auth/register
Body: { email, password, confirmPassword }
Response: { success: boolean, data?: { userId, token }, error?: string }

5. Tasks（任务分解）

目标：将方案拆分为可执行的小任务

实际操作：

  • 按功能模块分解任务

  • 估算每个任务的工作量

  • 确定任务依赖关系

举例：

任务列表：
1. 创建用户数据模型（30分钟）
2. 实现密码加密工具函数（20分钟）
3. 创建注册 API 接口（45分钟）
4. 编写输入验证中间件（30分钟）
5. 创建前端注册表单组件（60分钟）
6. 编写端到端测试（40分钟）

依赖关系：任务 3 依赖任务 1 和 2

（可选）6. Analyze（一致性检查）

目标：检查所有规格和方案是否一致

实际操作：

  • 对比原始需求和最终方案

  • 检查技术方案是否能满足所有规格要求

  • 识别潜在的风险和问题

举例：

检查清单：
✅ API 接口设计覆盖了所有规格要求
✅ 数据验证规则与规格一致
✅ 错误处理符合用户体验要求
⚠️  风险：未考虑高并发情况下的邮箱唯一性检查

7. Implement（实现代码）

目标：基于前面的规格和方案编写代码

实际操作：

  • 按照任务列表逐个实现功能

  • 严格遵循既定的规格和技术方案

  • 持续运行测试确保质量

Spec Kit 的主要优势

1. 多 AI 平台兼容

Spec Kit 不绑定特定的 AI 工具，你可以配合使用：

  • Claude：适合复杂逻辑分析和架构设计

  • Cursor：适合实时代码编写和调试

  • GitHub Copilot：适合代码补全和重构

这意味着你可以根据不同任务选择最合适的 AI 助手。

2. 强制测试驱动开发（TDD）

Spec Kit 内置了 TDD 流程：

  • 先写测试：基于规格编写测试用例

  • 再写代码：让代码通过测试

  • 持续验证：每次修改都要确保测试通过

这确保了代码质量和需求一致性。

3. 结构化模板指导

Spec Kit 提供标准化模板，包括：

  • 需求规格模板

  • API 设计模板

  • 测试用例模板

  • 代码审查检查单

这些模板帮助团队保持一致的工作方式。

4. 跨项目一致性

通过标准化的工作流程，不同项目之间可以保持：

  • 相同的代码质量标准

  • 一致的文档格式

  • 统一的技术决策过程

5. 风险提前暴露

在编码之前的规格化过程中，能够及早发现：

  • 需求不明确的地方

  • 技术方案的潜在问题

  • 任务估算的偏差

  • 资源依赖的风险

谁适合使用 Spec Kit？

适合的团队和个人：

个人开发者

  • 想要提高代码质量和开发效率

  • 经常需要维护多个项目

  • 希望与 AI 更好地协作

小型团队（2-10人）

  • 需要统一开发流程和代码标准

  • 团队成员技术水平参差不齐

  • 项目复杂度中等，需要清晰的需求管理

中型团队（10-50人）

  • 多个项目并行开发

  • 需要跨团队协作和知识共享

  • 对代码质量和交付效率有较高要求

典型应用场景：

场景 1：新功能开发 比如要为电商网站添加优惠券功能，使用 Spec Kit 可以：

  • 明确优惠券的各种类型和使用规则

  • 设计完整的数据库结构和 API 接口

  • 确保前后端开发人员理解一致

  • 提前识别边界情况（如优惠券叠加使用的逻辑）

场景 2：技术重构 当需要将旧系统迁移到新技术栈时：

  • 详细分析现有功能的规格要求

  • 制定分阶段迁移计划

  • 确保新系统功能与旧系统完全一致

  • 建立完整的回归测试套件

场景 3：团队协作 多人协作开发同一个项目时：

  • 统一团队的技术选择和代码风格

  • 明确每个人的任务边界和接口约定

  • 建立代码审查和质量检查流程

与现有工作流的集成：

Spec Kit 可以很好地融入现有的开发流程：

  • 配合 Git Flow：在每个功能分支开始前完成规格化

  • 结合敏捷开发：将用户故事转化为详细的技术规格

  • 增强 CI/CD：基于规格生成的测试用例可以直接集成到自动化流水线

快速上手指南

系统要求

  • Python 3.11 或更高版本

  • 操作系统：Windows、macOS、Linux 均支持

安装方法

如果是 iflow 用户，直接使用以下命令安装即可。除了 SpecKit 还有其他 workflow 可以尝试： https://platform.iflow.cn/agents?type=workflows&category=all

iflow workflow add "github-spec-OzctqA"

如果使用了其他 AI Coding 工具，可以用下面的方式

方法 1：使用 uv tool（推荐）

# 安装 uv（如果还没安装）
curl -LsSf https://astral.sh/uv/install.sh | sh

# 安装 Spec Kit
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git

方法 2：使用 uvx（临时使用）

# 直接运行，无需安装
uvx --from git+https://github.com/github/spec-kit.git specify init <PROJECT_NAME>

基本使用步骤

# 在项目目录中初始化 Spec Kit
speckit init

# 这会创建必要的配置文件和模板
# 启动你的 AI Agent，比如 iflow 或者 claude

# 开始新功能开发
/speckit.specify "用户登录功能"

# 上一步完成，会在当前目录生成 specs 目录。仔细阅读 spec.md 如果有什么不清楚的
/speckit.clarify "澄清的内容"

# 没问题，我们开始让 AI 出计划。因为是体验，我们就只过一下最核心的步骤
/speckit.plan "用 React 来实现"

# 看生成的文档，没问题就继续。
# 如果有问题，可以通过 /speckit.clarify 回到 spec 也就是第一步
# 也可以直接修改 md 文档
# 都确认了，那么就执行 tasks，拆解为可执行任务
/speckit.tasks

# 最后让其实现
/speckit.implement

1700×784 246 KB

最佳实践建议

  1. 从小功能开始

  • 不要一开始就用 Spec Kit 处理复杂的大功能

  • 选择一个简单的功能（比如"添加删除按钮"）来熟悉流程

  • 逐渐增加复杂度

  1. 规格要具体

  • :cross_mark: 错误：实现用户管理功能

  • :white_check_mark: 正确：实现用户列表页面，包含姓名、邮箱、注册时间字段，支持按姓名搜索和分页显示

  1. 充分利用模板

  • Spec Kit 提供的模板都是经过实践验证的

  • 不要跳过任何步骤，即使某些步骤看起来很简单

  • 根据项目特点适当调整模板内

  1. 与团队共享

  • 将生成的规格文档加入版本控制

  • 定期回顾和更新团队的开发原则（Constitution）

  • 建立规格审查机制

总结：迈向更高效的开发方式

Spec Kit 不仅仅是一个工具，更是一种全新的开发思维方式。它教会我们：

  • 思考先于行动：在写代码前充分思考和规划

  • 沟通重于技巧：与 AI、团队成员的有效沟通比编程技巧更重要

  • 过程即产品：开发过程中产生的规格文档本身就是有价值的资产

在 AI 时代，开发者的价值不再是写代码的速度，而是：

  • 准确理解和表达需求的能力

  • 设计合理系统架构的能力

  • 与 AI 有效协作的能力

  • 保证代码质量和可维护性的能力

2 个赞
2

没用过spec kit。 重点好像是确定规格。 有个具体的规格就能实现具体的目标。 重点在统一规格。 :smiling_face_with_sunglasses:

1 个赞
3

除了 SpecKit，iFlow 还有其他 workflow 可以尝试： https://platform.iflow.cn/agents?type=workflows&category=all

4

+1