用 Spec Kit 让 AI 更懂我的项目：最小实践记录

Posted on In , Views: Word count in article: 3k Reading time ≈ 3 mins.
Spec Kit 是 GitHub 推出的一个开源工具包，旨在推广"规范驱动开发"(Spec-Driven Development， SDD)。它的核心思想是：先明确"要做什么"，再让 AI 去实现"怎么做"。

AI 辅助编程存在的问题

  • LLMs 不懂工程的上下文，每次都要给它介绍背景、规范、约束等
  • LLMs 经常出现幻觉，前后不一，需要人每次去提醒、重复输入如何做
  • 不同需求、工程，我经常需要输入重复的、常用的一些 prompt
  • 如果不使用 agent，那么 LLMs 根据我的需求描述、已有代码片段生成的结果，往往需要我手动修改很多
  • 和 LLMs 的交互记录越来越多，需要记录过程（需求、任务分解、是否已实现）

主要的问题在于AI 不了解我的项目。它不知道我的技术栈、编码规范、项目结构，就像个新来的实习生，按照自己的想法开始写代码。

刷到很多帖子，在讨论 Spec Kit，觉得不错，小小地尝试了一下，给 AI 写一份”项目说明书”，让它按照我想法做事。

简单看了下 Spec Kit，觉得内容太多了，一下子不适合新手上手，很多人看了不知所云、如何上手，所以我想的是：现在已有的工程中实践一下，先只要把握最核心的部分就行，用一个最小实践打通整个流程、理解其理念。

Spec Kit 是什么

简单说，核心思想就是：先说清楚要做什么，再让 AI 去做。

通过几个 Markdown 文件，把项目的”规矩”记录下来：

  • 用什么技术栈
  • 代码放在哪些目录
  • 有什么编码规范
  • 哪些代码不能动

这样 AI 写代码时，就能”照章办事”了。我摸索了一套最小可用实践，三个文件就搞定。

我的操作流程

初始化（只保留核心）

在项目里运行（这里用的是 uv，所以 uv 好啊，uv 得学）：

1
2
3
4
5
6
# 安装工具
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git

# 在项目目录初始化
cd my-project
specify init . --ai cursor  # 我用的 cursor

初始化后会生成一堆文件，但我不需要那么多。直接删减到只剩这三个：

1
2
3
4
5
.specify/
  └── memory/
      ├── constitution.md  ← 项目规则(必需)
      ├── spec.md         ← 功能规范(按需)
      └── plan.md         ← 技术计划(按需)

scripts/ 和 templates/ 目录直接删了，不影响。核心就这三个文件。

写 constitution.md 最重要

这是唯一必需的文件，告诉 AI：”这是我项目的基本规则”。

我的做法：让 AI 帮我生成初稿。

  1. 在 Cursor 里打开项目
  2. 跟 AI 说：”帮我分析这个项目，生成一份 constitution.md，包括技术栈、目录结构、编码规范”
  3. AI 扫描代码，生成大致框架
  4. 我再根据实际情况修改补充

比如我的一个项目，生成的内容：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
# Project Constitution

## Tech Stack
- Python 3.11
- pytest + pytest-html + allure
- requests + jsonschema (接口测试)
- selenium + pytest-selenium (UI 自动化)
- faker (测试数据生成)

## Project Structure
tests/
  ├── api/           # 接口测试用例
  ├── ui/            # UI 自动化用例
  ├── fixtures/      # pytest fixtures
  ├── utils/         # 工具类(请求封装、断言等)
  └── data/          # 测试数据

## Coding Standards
- 所有用例用 pytest,不用 unittest
- 用例文件以 test_ 开头
- fixture 统一放在 conftest.py
- 接口请求统一用 utils/api_client.py
- 断言失败必须有清晰的错误信息

## Constraints
- legacy_tests/ 目录的老用例别动
- 新用例必须有 allure 报告标注
- 接口测试必须做 schema 校验

写完这个，基本就可以用了。AI 之后生成的代码会自动遵循这些规则。

需要加功能时，写 spec.md

只有要开发新功能或重构时，才需要创建 spec.md。

我一般也让 AI 帮忙：

“分析一下这个项目，有哪些可以优化的?哪些功能可以加?写到 spec.md 里”

AI 给的建议：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
# Feature Specification

## 需要优化的问题

### 1. 测试覆盖问题
- 支付接口缺少异常场景测试
- UI 自动化用例没有覆盖移动端

### 2. 测试效率
- 没有参数化,重复用例太多
- 缺少测试数据管理,每次都手动造数据

## 下个迭代要做的功能

### 支付接口测试补充
- 补充超时、重复支付、金额异常等场景
- 添加并发测试(100 个用户同时支付)
- 校验响应 JSON schema

### 测试数据管理
- 用 faker 生成随机测试数据
- 建立测试数据工厂类
- 支持从 YAML 加载测试数据集

有了这个，AI 就知道我接下来要做什么了。

功能复杂时，写 plan.md

如果功能比较复杂，涉及多个模块，可以让 AI 生成技术实现计划：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
# Technical Plan: 支付接口测试

## 实现步骤

### 1. 测试用例设计
- 新建 `tests/api/test_payment.py`
- 用 pytest.mark.parametrize 参数化测试
- 场景:正常支付、超时、重复、金额异常

### 2. 测试数据生成
- 新建 `tests/factories/payment_factory.py`
- 用 faker 生成订单号、金额、用户信息
- 支持生成边界值数据

### 3. Schema 校验
- 新建 `tests/schemas/payment_schema.json`
- 用 jsonschema 库校验响应格式
- 断言必需字段和数据类型

### 4. 并发测试
- 用 pytest-xdist 插件并发执行
- 100 个并发请求,验证幂等性
- 检查数据库一致性

## 技术决策
- 不用 locust,直接用 pytest-xdist(场景简单)
- 测试数据统一用工厂类生成,不写死

实际使用体验

设置完这三个文件后，开发流程变成：

以前：

1
2
3
我： "写个支付接口的测试用例"
AI： 生成一堆 unittest 代码,还用了我不用的 mock 库
我： 算了还是自己写

现在：

1
2
3
我： "写个支付接口的测试用例"
AI： 自动读取 constitution.md 和 spec.md,生成符合我规范的 pytest 用例
我： 改几个断言细节,直接能用

效率至少提升 3 倍，代码质量也稳定多了。

核心理解

说白了，.specify/ 目录就是给 AI 的项目手册：

  • constitution.md = 项目宪法(基本规则)
  • spec.md = 需求文档(要做什么)
  • plan.md = 设计文档(怎么做)

AI 读了这些，就知道该按什么标准写代码。

最妙的是：最少一个文件就能用。我只想让 AI 遵守项目规范，只保留 constitution.md 就够了。要做复杂功能时，再按需添加另外两个。

适合的场景

我觉得这几种情况特别适合：

  1. 已有项目，想让 AI 帮忙加功能但又怕它乱写
  2. 要重构老代码，先写清楚目标再让 AI 动手
  3. 想统一自己用 AI 的方式，形成固定流程

小结

Spec Kit 的核心理念我很认同：代码是最终产物，意图才是核心。

以前我直接让 AI 写代码，就像让实习生直接干活，当然容易出问题。现在先告诉 AI”我的项目是什么样”、”要做什么功能”、”怎么做最好”，它才能真正帮上忙。

三个 Markdown 文件，不到半小时设置好，之后的开发效率能提升好几倍。