Spec-Kit 规范驱动开发完全教程

从零开始，掌握 GitHub 官方开源的规范驱动开发（SDD）工具包

1. 什么是 Spec-Kit？
2. 核心理念：规范驱动开发（SDD）
3. 环境准备与安装
4. 项目初始化
5. 核心工作流：五大步骤
6. 辅助质量命令
7. 完整实战案例：任务管理应用
8. 项目目录结构详解
9. 支持的 AI 编程助手
10. 最佳实践与经验总结
11. 常见问题与解决方案
12. 适用场景评估
13. 总结

1. 什么是 Spec-Kit？

Spec-Kit 是 GitHub 官方开源的规范驱动开发（Spec-Driven Development，SDD）工具包，项目地址为 github.com/github/spec-kit。

它的核心目标是：把 AI 从"代码生成工具"升级为"软件开发伙伴"。

传统方式 vs Spec-Kit 方式

	传统方式	Spec-Kit 方式
起点	直接写提示词让 AI 生成代码	先写规范，再让 AI 按规范生成代码
需求管理	靠口头描述或散乱的文档	结构化的规格文档，可追溯、可验证
代码质量	AI "自由发挥"，容易偏离需求	受宪法约束，代码与规范保持一致
迭代方式	改代码	改规范 → 自动同步到代码
团队协作	沟通成本高	标准化文档降低沟通成本

简单来说，Spec-Kit 让你先想清楚"做什么"和"为什么做"，再让 AI 帮你决定"怎么做"。

2. 核心理念：规范驱动开发（SDD）

规范驱动开发（Spec-Driven Development）的核心思想是：规范先行，代码后行。

整个开发流程形成一条完整的链条：

需求定义 → 规格说明 → 技术方案 → 任务分解 → 代码实现
(What & Why)   (Spec)     (Plan)     (Tasks)    (Code)

SDD 的三个关键原则

意图驱动：规格定义的是"做什么"和"为什么做"，而不是"怎么做"
多步精炼：不是一次性从提示词生成代码，而是通过多个步骤逐步精炼
规范约束：所有 AI 产出必须遵循项目"宪法"，避免自由发挥

为什么需要 SDD？

在没有规范约束的情况下，AI 生成代码存在以下问题：

需求偏离：AI 可能自作主张添加不需要的功能，或遗漏关键需求
风格不一致：不同时间生成的代码风格、架构可能不一致
难以迭代：需求变更时，需要人工逐个修改代码文件
无法追溯：代码与需求之间的对应关系不清晰

SDD 通过结构化的规范文档和约束机制，有效解决了这些问题。

3. 环境准备与安装

3.1 系统要求

要求	说明
操作系统	Linux、macOS，或 Windows（通过 WSL2）
Python	>= 3.11
包管理器	uv（Python 包管理工具）
版本控制	Git
AI 编程助手	Claude Code、GitHub Copilot、Cursor、Gemini CLI 等（至少一个）

3.2 安装 uv

如果还没有安装 uv，可以使用以下命令安装：

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

安装完成后，验证：

uv --version

3.3 安装 Spec-Kit CLI

使用 uv 全局安装 Spec-Kit 命令行工具：

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

如果网络较慢，可以使用国内镜像：

uv tool install specify-cli --from git+https://github.com/github/spec-kit.git \
  -i http://mirrors.aliyun.com/pypi/simple --trusted-host mirrors.aliyun.com

安装完成后，验证：

specify --version
# 预期输出: specify-cli @ git+https://github.com/github/spec-kit.git

注意：如果出现 command not found 错误，请参考常见问题部分。

3.4 配置 GitHub Token

Spec-Kit 需要访问 GitHub API 下载模板，因此需要配置 GitHub Token：

前往 GitHub Settings > Developer settings > Personal access tokens
创建一个新的 Token（只需要 public_repo 权限即可）
设置环境变量：

# 临时设置（当前终端会话）
export GITHUB_TOKEN=your_github_token_here

# 永久设置（添加到 shell 配置文件）
echo 'export GITHUB_TOKEN=your_github_token_here' >> ~/.zshrc
source ~/.zshrc

3.5 检查环境

运行环境检查命令，确认所有依赖都已就绪：

specify check

该命令会检查 git、已安装的 AI 编程助手等工具是否可用。

4. 项目初始化

4.1 创建新项目

specify init <项目名称>

例如，创建一个名为 my-task-app 的项目：

specify init my-task-app

执行后会提示你选择：

AI 编程助手：如 claude、copilot、cursor-agent 等
脚本类型：sh（Bash/Zsh）或 ps（PowerShell）

也可以通过参数直接指定：

specify init my-task-app --ai claude

初始化完成后，会创建以下核心目录结构：

my-task-app/
├── .specify/
│   ├── memory/          # 项目宪法等记忆文件
│   ├── scripts/         # 辅助脚本
│   ├── specs/           # 规格文档目录
│   └── templates/       # 模板文件
├── CLAUDE.md            # AI 助手上下文文件（如果选择 claude）
└── .git/                # Git 仓库

4.2 在已有项目中初始化

如果你已经有一个项目目录，想在其中使用 Spec-Kit：

specify init . --ai <AI助手>

或使用 --here 参数：

specify init --here --ai <AI助手>

建议：在已有项目中初始化前，请确保已提交或备份当前代码，以防文件被覆盖。

4.3 常用初始化参数

参数	说明
`<project-name>`	项目目录名称
`--ai <agent>`	指定 AI 编程助手
`--script <type>`	脚本类型：`sh` 或 `ps`
`--here`	在当前目录初始化
`--force`	强制合并/覆盖（跳过确认）
`--no-git`	跳过 Git 仓库初始化
`--debug`	启用调试输出

5. 核心工作流：五大步骤

Spec-Kit 的核心工作流遵循严格的顺序：

宪法(Constitution) → 规格(Specify) → 方案(Plan) → 任务(Tasks) → 实现(Implement)

下面逐步详解每个环节。

5.1 制定项目宪法 — `/speckit.constitution`

这一步做什么？

制定项目的最高级别规则和约束——就像国家的宪法一样，所有后续的 AI 产出都必须遵守这些规则。

为什么需要宪法？

没有约束的 AI 就像一个没有规则约束的开发者——它可能会：

随意引入不需要的第三方库
使用与项目不一致的编码风格
忽略性能和安全要求
添加你从未要求的功能

宪法为 AI 设定了清晰的边界，确保所有产出都符合你的期望。

怎么做？

在你的 AI 编程助手（如 VS Code 中的 Copilot Chat）中输入：

/speckit.constitution

然后描述项目的核心原则，例如：

"1. 优先使用原生 Web API，避免不必要的第三方库
2. 所有代码必须遵循 TDD，测试覆盖率 >= 90%
3. UI 响应时间 < 100ms
4. 安全优先：所有用户输入必须经过验证和转义
5. 渐进式价值交付：核心功能优先，增强功能其次"

输出结果

AI 会根据你的描述生成 .specify/memory/constitution.md 文件，内容包含：

技术栈约束：允许/禁止使用的技术
代码质量标准：测试覆盖率、代码风格等
性能要求：响应时间、资源限制等
安全规则：输入验证、权限控制等
交付策略：优先级排序、迭代策略等

宪法示例

# Taskify 项目宪法

## 技术原则
- 优先使用原生 Web API（Fetch、IndexedDB、Custom Elements）
- 仅允许引入 lit-html 作为模板引擎
- 使用 ES Modules 模块化开发
- 不使用任何框架（React、Vue 等）

## 代码质量
- 遵循 TDD，测试覆盖率 >= 85%
- 所有公共函数必须有 JSDoc 注释
- 使用 ESLint + Prettier 统一代码风格
- 提交信息遵循 Conventional Commits 规范

## 性能要求
- 首屏加载时间 < 1.5s
- UI 交互响应时间 < 100ms
- 列表渲染支持 1000+ 条数据不卡顿

## 安全规则
- 所有用户输入必须经过 HTML 转义
- 不在客户端存储敏感信息
- API 调用必须包含错误处理

5.2 编写功能规格 — `/speckit.specify`

这一步做什么？

将模糊的用户需求转化为可测试、无歧义的功能规格。

规格包含什么？

一份完整的功能规格通常包含：

用户故事（User Stories）：从用户视角描述功能需求
功能需求（Functional Requirements, FR）：系统必须实现的具体功能
成功标准（Success Criteria, SC）：验证功能是否正确实现的判断条件

怎么做？

/speckit.specify

然后描述你想要构建的功能，例如：

"我要做一个任务管理应用。用户可以创建、编辑、删除任务。每个任务有名称、优先级（高/中/低）和截止日期。任务列表支持按优先级和日期筛选。用户可以标记任务为已完成。"

关键要点：专注于"做什么"和"为什么做"，不要在规格阶段指定技术实现。

输出结果

AI 会在 specs/001-<功能名称>/spec.md 中生成功能规格：

# 任务管理功能规格

## 用户故事

### US-001: 创建任务
作为用户，我希望能够创建带有名称、优先级和截止日期的任务，
以便跟踪我的待办事项。

### US-002: 管理任务
作为用户，我希望能够编辑和删除已有任务，
以便及时更新我的任务信息。

### US-003: 筛选任务
作为用户，我希望能够按优先级和日期筛选任务，
以便快速找到我关注的任务。

### US-004: 完成任务
作为用户，我希望能够标记任务为已完成，
以便区分已处理和未处理的任务。

## 功能需求

- FR-001: 系统必须支持任务的创建，包含名称（必填）、优先级（高/中/低）、截止日期（可选）
- FR-002: 系统必须支持任务的编辑和删除
- FR-003: 任务列表必须支持按优先级筛选（支持多选）
- FR-004: 任务列表必须支持按截止日期排序
- FR-005: 用户可以将任务标记为"已完成"
- FR-006: 已完成的任务应显示删除线样式，但仍可见

## 成功标准

- SC-001: 创建任务操作响应时间 < 100ms
- SC-002: 任务列表正确显示优先级标签（高=红色、中=黄色、低=绿色）
- SC-003: 筛选操作即时生效，无明显延迟
- SC-004: 删除任务前需弹出确认对话框

5.3 生成技术方案 — `/speckit.plan`

这一步做什么？

基于功能规格，AI 自动生成详细的技术实现方案。

怎么做？

/speckit.plan

然后指定技术栈和架构偏好，例如：

"使用 Vite 构建工具，纯 HTML/CSS/JavaScript 开发，尽量不使用第三方库。图片不上传到服务器，元数据存储在本地 IndexedDB 中。"

输出结果

AI 会在 specs/001-<功能名称>/ 目录下生成多个文件：

文件	内容
`plan.md`	架构决策、技术选型说明
`data-model.md`	数据库/表结构设计
`quickstart.md`	本地环境搭建指南
`contracts/`	API 接口契约（如有）

plan.md 示例

# 技术实现方案

## 架构决策

### AD-001: 使用 Web Components 组件化开发
**决策**: 使用原生 Web Components（Custom Elements + Shadow DOM）
**原因**: 符合宪法中"优先使用原生 Web API"的原则
**替代方案**: React/Vue 组件 — 被否决，因为违反宪法

### AD-002: 使用 IndexedDB 存储任务数据
**决策**: 使用 IndexedDB 作为本地持久化存储
**原因**: 需要支持复杂查询（按优先级筛选、按日期排序）
**替代方案**: localStorage — 被否决，因为不支持索引查询

### AD-003: 使用 Vite 作为构建工具
**决策**: 使用 Vite 进行开发和构建
**原因**: 快速的 HMR，原生 ES Module 支持

## 技术栈
- 构建: Vite 5.x
- 语言: JavaScript (ES2022+)
- 存储: IndexedDB (via idb 库)
- 测试: Vitest + Testing Library
- 代码风格: ESLint + Prettier

data-model.md 示例

# 数据模型

## tasks 表

| 字段 | 类型 | 约束 | 说明 |
|---|---|---|---|
| id | string | PRIMARY KEY | UUID 格式 |
| name | string | NOT NULL | 任务名称，最大 200 字符 |
| priority | string | NOT NULL | 枚举值: "high", "medium", "low" |
| dueDate | string | NULLABLE | ISO 8601 日期格式 |
| completed | boolean | DEFAULT false | 是否已完成 |
| createdAt | string | NOT NULL | ISO 8601 创建时间 |
| updatedAt | string | NOT NULL | ISO 8601 更新时间 |

## 索引

| 索引名 | 字段 | 类型 |
|---|---|---|
| idx_priority | priority | 非唯一 |
| idx_due_date | dueDate | 非唯一 |
| idx_completed | completed | 非唯一 |

5.4 拆分任务清单 — `/speckit.tasks`

这一步做什么？

AI 将技术方案自动拆解为可执行的任务单元，包含前置条件、步骤和依赖关系。

怎么做？

/speckit.tasks

输出结果

AI 会在 specs/001-<功能名称>/tasks.md 中生成任务清单：

# 任务清单

## Phase 1: 项目基础搭建

- [ ] T-001: 创建项目目录结构
  - 创建 `src/`, `src/components/`, `src/db/`, `src/utils/` 目录
  - 初始化 `package.json` 和 Vite 配置
  - 依赖: 无

- [ ] T-002: 初始化 IndexedDB 数据库
  - 创建 `src/db/database.js`
  - 定义 `tasks` 表结构和索引
  - 依赖: T-001

- [ ] T-003: 配置测试环境
  - 安装 Vitest 和 Testing Library
  - 创建 `vitest.config.js`
  - 依赖: T-001

## Phase 2: 核心 CRUD 功能

- [ ] T-004: 实现任务创建 API
  - 编写 `src/db/task-repository.js`
  - 实现 `createTask()`, `getTask()`, `updateTask()`, `deleteTask()`
  - 编写对应单元测试
  - 依赖: T-002, T-003

- [ ] T-005: 创建任务表单组件
  - 创建 `src/components/task-form.js`
  - 实现表单验证（名称必填、优先级枚举）
  - 依赖: T-001, T-004

- [ ] T-006: 创建任务列表组件
  - 创建 `src/components/task-list.js`
  - 实现任务列表渲染和删除确认
  - 依赖: T-004

## Phase 3: 筛选与完成功能

- [ ] T-007: 实现任务筛选功能
  - 创建 `src/components/task-filter.js`
  - 支持按优先级多选筛选
  - 支持按截止日期排序
  - 依赖: T-006

- [ ] T-008: 实现任务完成标记
  - 已完成任务显示删除线
  - 点击复选框切换完成状态
  - 依赖: T-006

## Phase 4: 集成测试与优化

- [ ] T-009: 集成测试
  - 端到端测试：创建 → 编辑 → 筛选 → 完成 → 删除
  - 依赖: T-007, T-008

- [ ] T-010: 性能优化
  - 虚拟滚动支持 1000+ 条数据
  - 防抖搜索输入
  - 依赖: T-009

任务清单的关键特点：

按用户故事分阶段：每个用户故事对应一个独立的实现阶段
依赖管理：任务按依赖关系排序（模型 → 服务 → 界面）
并行标记：可并行执行的任务标注 [P]
TDD 结构：测试任务排在实现任务之前
检查点验证：每个阶段包含独立的验证检查点

5.5 执行开发实现 — `/speckit.implement`

这一步做什么？

AI 按照任务清单逐个执行任务——写代码、创建文件、运行测试，并实时报告进度。

怎么做？

/speckit.implement

执行过程

验证前提条件：检查宪法、规格、方案、任务是否都已就绪
解析任务清单：从 tasks.md 读取任务分解
按序执行：按正确的顺序执行任务，尊重依赖关系
TDD 流程：先写测试，再写实现
进度更新：每完成一个任务，在 tasks.md 中标记勾选

开发者的角色

在使用 /speckit.implement 时，开发者只需要：

审查代码：检查生成的代码是否符合规格
提供反馈：如果代码不满足需求，更新规格后重新执行
最终验收：确认所有成功标准都满足

YOLO 模式

在 /speckit.implement 执行过程中，你可以选择 "YOLO 模式"（全自动模式）：

AI 自动执行所有任务，无需逐步确认
开发者只需在最后做整体审查
适合对规格有信心、希望快速推进的场景

6. 辅助质量命令

除了核心的五大步骤，Spec-Kit 还提供了三个辅助命令，帮助提升开发质量。

6.1 需求澄清 — `/speckit.clarify`

什么时候用？

在 /speckit.plan 之前使用，用于消除规格中的歧义。

为什么需要？

人类写需求时常常会有模糊的地方，例如：

"任务筛选"是单条件还是多条件组合？
"排序"是升序还是降序？是否支持切换？
"编辑"是弹窗编辑还是内联编辑？

如果不在早期澄清，后期返工成本很高。

怎么做？

/speckit.clarify

AI 会主动识别规格中的模糊点，并通过多选题的形式向你提问：

Q1: 任务筛选是否支持多条件组合？
  A) 仅支持单条件筛选（如：只按优先级）
  B) 支持多条件组合（如：高优先级 + 本周到期）

Q2: 任务的"编辑"方式是？
  A) 弹窗编辑
  B) 内联编辑（点击即可编辑）
  C) 跳转到编辑页面

Q3: 已完成的任务如何处理？
  A) 显示在列表底部，带删除线
  B) 默认隐藏，可通过开关显示
  C) 移到单独的"已完成"标签页

你的回答会自动更新到规格文档中。

6.2 一致性分析 — `/speckit.analyze`

什么时候用？

在 /speckit.tasks 之后、/speckit.implement 之前使用。

为什么需要？

在多步骤的工作流中，规格、方案和任务之间可能存在不一致。例如：

规格要求"显示任务创建时间"，但数据模型中缺少 created_at 字段
任务清单中遗漏了某个功能需求对应的任务
技术方案中选用的技术违反了项目宪法

怎么做？

/speckit.analyze

AI 会生成一份一致性报告，标出发现的问题：

一致性分析报告
================

[ERROR] 规格与数据模型不一致
  - 规格 FR-006 要求"已完成的任务应显示删除线样式"
  - 数据模型中没有 completedAt 字段来记录完成时间
  - 建议: 在 tasks 表中添加 completedAt 字段

[WARNING] 任务覆盖不完整
  - 规格 FR-004 要求"按截止日期排序"
  - 任务清单中没有单独的排序实现任务
  - 建议: 在 T-007 中增加排序功能说明

[OK] 宪法合规性
  - 所有技术选型符合项目宪法
  - 未发现违反宪法的方案

6.3 质量检查表 — `/speckit.checklist`

什么时候用？

任何时候都可以使用，通常在 /speckit.plan 之后。

为什么需要？

质量检查表就像"英文的单元测试"——在写代码之前就验证需求本身的完整性、清晰性和一致性。

怎么做？

/speckit.checklist

AI 会基于规格生成一份检查表：

# 需求满足度检查表

## 功能需求覆盖
- [ ] FR-001: 任务创建是否已实现？
- [ ] FR-002: 任务编辑和删除是否已实现？
- [ ] FR-003: 优先级筛选是否已实现？
- [ ] FR-004: 日期排序是否已实现？
- [ ] FR-005: 任务完成标记是否已实现？
- [ ] FR-006: 完成任务的视觉样式是否正确？

## 成功标准验证
- [ ] SC-001: 创建任务响应时间 < 100ms？
- [ ] SC-002: 优先级标签颜色是否正确？
- [ ] SC-003: 筛选操作是否即时生效？
- [ ] SC-004: 删除前是否有确认对话框？

## 宪法合规性
- [ ] 是否使用原生 Web API？
- [ ] 测试覆盖率是否 >= 85%？
- [ ] 是否有输入验证和转义？

7. 完整实战案例：任务管理应用

让我们通过一个完整的实战案例，演示 Spec-Kit 从零到一的完整流程。

7.1 第一步：初始化项目

# 创建项目
specify init taskify --ai claude

# 进入项目目录
cd taskify

7.2 第二步：制定宪法

在 AI 编程助手中输入 /speckit.constitution，然后描述：

"这是一个任务管理 Web 应用。
技术原则：使用原生 Web Components 开发，不使用任何前端框架。
数据存储在浏览器本地（IndexedDB）。
代码质量：TDD 开发，测试覆盖率 >= 85%。
性能：UI 响应 < 100ms，支持 1000+ 任务不卡顿。
安全：所有用户输入必须转义，防止 XSS。"

7.3 第三步：编写规格

输入 /speckit.specify，描述：

"我要做一个任务管理应用。用户可以创建任务（名称、优先级、截止日期），编辑和删除任务，按优先级筛选任务，标记任务为已完成。任务列表要清晰美观，优先级用颜色区分。"

7.4 第四步：澄清需求

输入 /speckit.clarify，回答 AI 的问题：

Q: 筛选支持多条件组合吗？
A: 支持，可以同时按优先级和日期范围筛选

Q: 编辑方式是？
A: 内联编辑，点击任务名称即可编辑

Q: 已完成任务如何显示？
A: 显示在列表底部，带删除线，可通过开关隐藏

7.5 第五步：生成技术方案

输入 /speckit.plan，指定技术栈：

"使用 Vite 构建，原生 Web Components + lit-html 模板，
IndexedDB 存储（使用 idb 库），Vitest 测试。"

7.6 第六步：生成任务清单

输入 /speckit.tasks，AI 自动生成任务分解。

7.7 第七步（可选）：一致性分析

输入 /speckit.analyze，检查规格、方案、任务之间的一致性。

7.8 第八步：执行实现

输入 /speckit.implement，AI 开始按任务清单执行开发。

可以选择 YOLO 模式让 AI 全自动执行，也可以逐步确认。

7.9 第九步：测试与迭代

实现完成后，运行应用进行测试。如果发现问题：

代码不符合预期：不要直接改代码！回到规格文档，更新需求，然后重新执行 /speckit.plan → /speckit.tasks → /speckit.implement
需要新功能：创建新的规格（/speckit.specify），走完整工作流
运行时错误：将错误信息粘贴给 AI 助手，让它修复

8. 项目目录结构详解

完成规格和方案阶段后，项目目录结构如下：

taskify/
├── CLAUDE.md                           # AI 助手上下文文件
├── .specify/
│   ├── memory/
│   │   └── constitution.md             # 项目宪法
│   ├── scripts/
│   │   ├── check-prerequisites.sh      # 环境检查脚本
│   │   ├── common.sh                   # 公共工具函数
│   │   ├── create-new-feature.sh       # 创建新功能脚本
│   │   ├── setup-plan.sh              # 方案设置脚本
│   │   └── update-agent-context.sh     # 更新 AI 上下文
│   ├── specs/
│   │   └── 001-task-management/        # 第一个功能规格
│   │       ├── contracts/
│   │       │   └── api-spec.json       # API 接口契约
│   │       ├── data-model.md           # 数据模型设计
│   │       ├── plan.md                 # 技术实现方案
│   │       ├── quickstart.md           # 快速上手指南
│   │       ├── research.md             # 技术调研（如有）
│   │       ├── spec.md                 # 功能规格
│   │       └── tasks.md                # 任务清单
│   └── templates/
│       ├── CLAUDE-template.md          # AI 助手模板
│       ├── plan-template.md            # 方案模板
│       ├── spec-template.md            # 规格模板
│       └── tasks-template.md           # 任务模板
├── src/                                # 源代码（实现阶段生成）
│   ├── components/
│   ├── db/
│   └── utils/
├── tests/                              # 测试文件（实现阶段生成）
└── package.json                        # 项目配置

关键目录说明

目录/文件	说明
`.specify/memory/`	存储项目宪法等持久化记忆
`.specify/specs/`	按功能编号组织所有规格文档
`.specify/scripts/`	Spec-Kit 提供的辅助脚本
`.specify/templates/`	文档模板，确保格式统一
`CLAUDE.md`	AI 助手的项目上下文文件

9. 支持的 AI 编程助手

AI 助手	支持状态	说明
Claude Code	完全支持	Anthropic 的 Claude 编程助手
GitHub Copilot	完全支持	GitHub Copilot IDE 集成
Cursor	完全支持	Cursor AI 编辑器
Gemini CLI	完全支持	Google Gemini 命令行助手
Qwen Code	完全支持	阿里云通义千问编程助手
Windsurf	完全支持	Windsurf AI 编辑器
CodeBuddy	完全支持	CodeBuddy AI 助手
Codex CLI	完全支持	OpenAI Codex 命令行助手
Roo Code	完全支持	Roo Code AI 助手
Kilo Code	完全支持	Kilo Code AI 助手
Amazon Q	部分支持	不支持斜杠命令的自定义参数

10. 最佳实践与经验总结

规格编写

先定宪法，再写规格：宪法是所有后续产出的约束，务必首先确立
聚焦"做什么"和"为什么"：规格阶段不要涉及技术实现细节
不要把第一版当作最终版：利用 /speckit.clarify 澄清模糊点
始终在 /speckit.plan 之前运行 /speckit.clarify：减少下游返工

技术方案

警惕过度工程：AI 可能会"自作主张"添加你不需要的组件，要求它给出理由
确保方案遵循宪法：宪法是基础文档，所有方案必须合规
调研快速变化的技术栈：如果你的技术栈更新快，让 AI 调研特定版本细节
避免模糊调研：引导 AI 解决具体问题，而非泛泛的技术概览

开发实现

确保本地工具已安装：AI 会执行本地命令（如 npm、dotnet），确保它们可用
增量交付：任务清单支持按用户故事增量交付
在任务和实现之间运行 /speckit.analyze：验证跨文档一致性
迭代规格而非代码：如果代码不满足需求，更新规格后重新走流程

通用建议

善用 YOLO 模式：对规格有信心时，使用全自动模式加速开发
遗留项目先用"压缩视图"：让 AI 先为现有代码库生成文档（.specify/specs/000-existing-system/research.md），后续开发参考它防止需求偏离
使用 GitHub CLI 管理 PR：通过功能分支和 Pull Request 跟踪变更

11. 常见问题与解决方案

Q1: `specify` 命令安装后找不到

原因：uv 安装的工具路径没有加入 PATH。

解决方案：

# 查找工具安装路径
uv tool list --verbose

# 将 bin 目录加入 PATH（以 macOS 为例）
echo 'export PATH="/opt/homebrew/Cellar/uv/0.7.6/libexec/tools/specify-cli@0.1.0/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Q2: GitHub API 返回 401 错误

原因：GitHub Token 未正确设置或已过期。

解决方案：

# 检查 Token 是否已设置
echo $GITHUB_TOKEN

# 重新设置
export GITHUB_TOKEN=your_new_token_here

# 确保 Token 有 public_repo 权限

Q3: AI 生成的代码不符合规格

原因：规格描述不够清晰，或 AI 没有充分理解需求。

解决方案：

检查规格文档是否清晰、无歧义
使用 /speckit.clarify 澄清模糊点
在宪法中添加更明确的约束
使用 /speckit.analyze 检查一致性

Q4: 需求变更了怎么办？

解决方案：不要直接改代码！遵循以下流程：

更新规格文档（spec.md）
重新执行 /speckit.plan → /speckit.tasks → /speckit.implement
AI 会根据新的规格生成新的方案和代码

Q5: 如何在已有项目中使用 Spec-Kit？

解决方案：

# 在当前目录初始化
specify init . --ai <AI助手>

# 先让 AI 为现有代码生成"压缩视图"
# 然后在 .specify/specs/000-existing-system/research.md 中参考

Q6: 中文版 Spec-Kit 如何使用？

如果你更习惯使用中文界面，可以使用中文版 Spec-Kit：

# 安装中文版 CLI
uv tool install specify-cn-cli --from git+https://github.com/figoliu/spec.xin.git

# 使用 specify-cn 替代 specify
specify-cn init my-project --ai claude

	原版	中文版
命令	`specify`	`specify-cn`
包名	`specify-cli`	`specify-cn-cli`
文档语言	英文	中文

Q7: 安装速度很慢怎么办？

解决方案：使用国内镜像：

uv tool install specify-cli --from git+https://github.com/github/spec-kit.git \
  -i http://mirrors.aliyun.com/pypi/simple --trusted-host mirrors.aliyun.com

12. 适用场景评估

适合使用 Spec-Kit 的场景

场景	原因
追求高质量代码的团队	SDD 流程确保代码与需求一致
中大型项目	结构化文档降低协作成本
需要频繁协作的项目	标准化文档减少沟通损耗
想充分利用 AI 的开发者	Spec-Kit 让 AI 的产出更可控
重视需求管理的团队	从需求到代码全链路可追溯

需要谨慎使用的场景

场景	原因
快速原型探索	SDD 流程相对较重，可能影响速度
技术基础较弱的团队	需要理解 SDD 理念和多个配置步骤
对外部服务敏感的环境	依赖 GitHub API 和 AI 服务
需要高度自定义流程的组织	内置工作流较固定，定制空间有限

13. 总结

Spec-Kit 通过"规范→方案→任务→实现"的结构化流程，让 AI 辅助开发变得更加可控和高效：

宪法：为 AI 设定边界，防止"自由发挥"
规格：明确"做什么"和"为什么做"
方案：设计"怎么做"
任务：拆解"按什么顺序做"
实现：执行"做出成果"

三个辅助命令（clarify、analyze、checklist）在关键节点提供质量保障。

核心心法：迭代规格，而非迭代代码。当需求变更时，先更新规格，再让 AI 重新生成方案和代码——这才是 SDD 的正确打开方式。

参考资源

项目仓库: github.com/github/spec-kit

官方文档: github.github.com/spec-kit

中文文档: docs.spec.xin

uv 包管理器: docs.astral.sh/uv

posted @ 2026-05-15 13:43 helloHKTK 阅读(718) 评论(0) 收藏举报

刷新页面返回顶部

helloHKTK

Spec-Kit 规范驱动开发完全教程

目录

1. 什么是 Spec-Kit？

传统方式 vs Spec-Kit 方式

2. 核心理念：规范驱动开发（SDD）

SDD 的三个关键原则

为什么需要 SDD？

3. 环境准备与安装

3.1 系统要求

3.2 安装 uv

3.3 安装 Spec-Kit CLI

3.4 配置 GitHub Token

3.5 检查环境

4. 项目初始化

4.1 创建新项目

4.2 在已有项目中初始化

4.3 常用初始化参数

5. 核心工作流：五大步骤

5.1 制定项目宪法 — /speckit.constitution

这一步做什么？

为什么需要宪法？

怎么做？

输出结果

宪法示例

5.2 编写功能规格 — /speckit.specify

这一步做什么？

规格包含什么？

怎么做？

输出结果

5.3 生成技术方案 — /speckit.plan

这一步做什么？

怎么做？

输出结果

plan.md 示例

data-model.md 示例

5.4 拆分任务清单 — /speckit.tasks

这一步做什么？

怎么做？

输出结果

5.5 执行开发实现 — /speckit.implement

这一步做什么？

怎么做？

执行过程

开发者的角色

YOLO 模式

6. 辅助质量命令

6.1 需求澄清 — /speckit.clarify

什么时候用？

为什么需要？

怎么做？

6.2 一致性分析 — /speckit.analyze

什么时候用？

为什么需要？

怎么做？

6.3 质量检查表 — /speckit.checklist

什么时候用？

为什么需要？

怎么做？

7. 完整实战案例：任务管理应用

7.1 第一步：初始化项目

7.2 第二步：制定宪法

7.3 第三步：编写规格

7.4 第四步：澄清需求

7.5 第五步：生成技术方案

7.6 第六步：生成任务清单

7.7 第七步（可选）：一致性分析

7.8 第八步：执行实现

7.9 第九步：测试与迭代

8. 项目目录结构详解

关键目录说明

9. 支持的 AI 编程助手

10. 最佳实践与经验总结

规格编写

技术方案

开发实现

通用建议

11. 常见问题与解决方案

Q1: specify 命令安装后找不到

Q2: GitHub API 返回 401 错误

5.1 制定项目宪法 — `/speckit.constitution`

5.2 编写功能规格 — `/speckit.specify`

5.3 生成技术方案 — `/speckit.plan`

5.4 拆分任务清单 — `/speckit.tasks`

5.5 执行开发实现 — `/speckit.implement`

6.1 需求澄清 — `/speckit.clarify`

6.2 一致性分析 — `/speckit.analyze`

6.3 质量检查表 — `/speckit.checklist`

Q1: `specify` 命令安装后找不到