Spec-Kit 配置与使用指南（Spec-Driven Development）
在项目实训使用 AI 辅助完成代码的过程中，了解到Spec Coding（规范驱动开发）以及 GitHub 开源工具spec-kit。本文记录其在 Windows + Cursor 环境下的配置、标准工作流与在「阅见」项目中的实践要点，便于后续功能开发时复用。
一、Spec Coding 介绍
1.1 什么是 Spec-Driven Development（SDD）
Spec Coding（规范驱动开发，Spec-Driven Development，简称SDD）是一种AI 辅助开发方法论：在编写代码之前，先建立清晰、结构化的规范文档（Spec），再让 Coding Agent 基于规范分阶段生成与实现代码。
与传统开发的区别在于：规范不再只是「写完就丢的脚手架」，而是贯穿原则 → 需求 → 计划 → 任务 → 实现全链路的可执行输入。
1.2 与 Prompt 开发、Vibe Coding 的对比
| 方式 | 特点 | 适用场景 | 常见问题（复杂需求） |
|---|---|---|---|
| 单次 Prompt | 一句话让 AI 写功能 | 改 bug、小函数 | 上下文丢失、边界遗漏 |
| Vibe Coding | 对话式即兴改代码 | 原型、UI 微调 | 前后矛盾、缺乏约束、难以复盘 |
| Spec Coding | 分阶段产出文档再实现 | 多模块、有业务规则的功能 | 前期多写文档，但可追溯、可评审 |
阅见项目中阅读商城（书币与称号）等功能，即采用/speckit.specify → plan → tasks → implement流水线完成：需求里明确表约束、接口字段、打卡规则常量，实现阶段 AI 按tasks.md逐项落地，减少「写到一半改架构」的情况。
1.3 Spec-Kit 在流程中的角色
spec-kit 是 GitHub 开源的SDD 工具包，提供：
- Specify CLI：安装、初始化项目、检查环境；
- Slash Commands（如
/speckit.specify）：写入 Agent 可识别的提示模板； .specify/目录：宪法、规格、计划、任务等制品的模板与输出约定。
支持30+AI 编程 Agent（含Cursor、Claude Code、Copilot、Codex CLI 等），详见官方 Integrations 文档。
二、标准工作流总览
推荐顺序（官方）：
constitution→ 2.specify→ （可选clarify）→ 3.plan→ 4.tasks→ （可选analyze）→ 5.implement→ （可选checklist）
在 Agent 对话中，在 prompt开头使用/speckit.xxx，并说明项目上下文；各命令会将产物写入约定目录（通常在.specify/或项目内specs/、tasks.md等，以初始化时模板为准）。
三、环境配置
3.1 前置条件
| 依赖 | 说明 |
|---|---|
| Python 3.11+ | Specify CLI 运行环境 |
| Git | 从 GitHub 安装 specify-cli |
| uv（推荐）或 pipx | Python 工具隔离安装 |
| AI Agent | 如 Cursor、Claude Code 等 |
| 操作系统 | Windows / macOS / Linux 均可 |
3.2 配置 uv（Windows）
安装（PowerShell，建议管理员权限）：
powershell-c"irm https://astral.sh/uv/install.ps1 | iex"uv--version配置国内镜像（可选，提升 pip 下载速度）：
配置文件路径：%USERPROFILE%\.config\uv\config.toml
（例如C:\Users\你的用户名\.config\uv\config.toml）
notepad%USERPROFILE%\.config\uv\config.toml推荐写入阿里云镜像：
# 阿里云 PyPI 镜像 [registries.pypi] index = "https://mirrors.aliyun.com/pypi/simple/" # 可选：清华镜像 # [registries.tuna] # index = "https://pypi.tuna.tsinghua.edu.cn/simple/"保存后可用uv pip install或uv tool install验证下载是否走镜像。
3.3 安装 Specify CLI
# 安装最新稳定版（将 vX.Y.Z 替换为 Releases 页具体标签）uv tool install specify-cli--fromgit+https://github.com/github/spec-kit.git@vX.Y.Z# 或直接安装 main 分支（开发/尝鲜）uv tool install specify-cli--fromgit+https://github.com/github/spec-kit.git版本与升级：
specify self check# 检查是否有新版本specify self upgrade--dry-run# 预览升级命令specify self upgrade# 升级到最新稳定版四、项目初始化（Specify CLI）
4.1 新建项目
specify init<PROJECT_NAME># 示例specify init my-app--integrationcursor-agent4.2 在已有仓库中初始化（阅见等 Brownfield 项目）
# 在当前目录初始化specify init.# 或specify init--here# 指定 AI 集成（Cursor 示例）specify init.--aicursor-agent# 等价写法（新版 CLI 更推荐 --integration）specify init.--integrationcursor-agent# 目录非空时强制合并specify init.--force--integrationcursor-agent交互选项说明：
- 终端会提示选择AI 集成（Cursor、Copilot、Claude Code、Codex 等）；
- Windows 用户：若询问 Shell 类型，建议选择PowerShell（ps），与日常开发环境一致；
- 若未安装对应 Agent CLI，可加
--ignore-agent-tools仅拉取模板：
specify init.--force--integrationcursor-agent --ignore-agent-tools初始化成功后，项目中会出现.specify/及 Agent 侧命令目录（如 Cursor 的.cursor/下 slash command 或 skills 配置，取决于集成选项）。
4.3 验证安装
specify check出现Specify CLI is ready to use!即表示 CLI 可用。
其他常用命令：
specify integration list# 查看本版本支持的 AI 集成specify extension search# 搜索社区扩展specify preset search# 搜索预设模板五、Slash Commands 详解
5.1 核心命令（必读）
| 命令 | 作用 | 输入侧重 | 典型产出 |
|---|---|---|---|
/speckit.constitution | 项目宪法 / 开发原则 | 质量、测试、UX、性能准则 | 治理原则文档 |
/speckit.specify | 功能需求规格 | 做什么、为什么（少写技术栈） | Spec：用户故事、边界、验收 |
/speckit.plan | 技术实施计划 | 技术栈、分层、架构 | Plan：模块、接口、数据设计 |
/speckit.tasks | 任务拆解 | 基于 plan 自动生成或可补充约束 | tasks.md可执行任务列表 |
/speckit.implement | 按计划实现 | 强调最小改动、复用现有风格 | 代码变更 + 联调说明 |
5.2 可选命令（提升质量）
| 命令 | 建议时机 | 作用 |
|---|---|---|
/speckit.clarify | specify之后、plan之前 | 澄清规格中模糊点（原/quizme） |
/speckit.analyze | tasks之后、implement之前 | 检查 spec / plan / tasks 一致性 |
/speckit.checklist | 实现前后 | 生成需求完整性检查清单 |
/speckit.taskstoissues | tasks之后 | 将任务列表转为 GitHub Issues |
5.3 在 Cursor 中的使用方式
- 打开已
specify init的项目仓库； - 在Agent / Chat输入框开头输入命令，例如：
/speckit.specify 请为「阅读商城」编写需求：用户阅读满 10 分钟可打卡领书币，用书币购买称号……- 按工作流依次执行后续命令；
- 实现阶段在
implement中写明约束（如「不改动全局配置」「关键逻辑先确认」）。
部分 Agent 使用Skills 模式（如 Codex CLI
--skills），命令形如$speckit-specify而非/speckit.specify，以specify init时选项为准。
六、分步使用示例
6.1 确立项目原则
/speckit.constitution Create principles focused on code quality, testing standards, user experience consistency, and performance requirements. 本项目为 Spring Boot + Vue3 全栈，AI 能力通过 Python ai-service 桥接，需保持前后端接口契约稳定。6.2 创建规格（注意：命令为 specify，非 specite）
/speckit.specify 请根据阅见项目架构，生成「阅读商城（书币与称号商城）」功能需求说明。 用户阅读达到条件后打卡领书币，用书币购买称号。 输出：Spec + 接口字段说明 + 关键业务规则 + 边界条件。写法要点：
- 写清用户角色、业务规则、异常分支（余额不足、重复购买、重复打卡）；
- 可引用已有表名、模块路径（如
vr_reading_daily_stat）； - 此阶段不宜堆砌具体类名实现细节，留给
plan。
6.3 制定技术计划
/speckit.plan 技术栈：Spring Boot 3.x + Java 17 + MyBatis-Plus + JWT + Vue3 + Vite + Element Plus。 为「阅读商城」给出 Controller/Service/DTO/Entity 分层方案与数据库表设计， 并与现有阅读日历模块（zoneId、vr_reading_daily_stat）对齐。6.4 拆解任务
/speckit.tasks 请把「阅读商城」拆成可执行任务并生成 tasks.md。 覆盖：schema 表与唯一约束、CoinController/ShopTitleController、 CoinCheckInService 打卡规则、BookCoinShopView.vue 前端并行加载与刷新策略。6.5 执行实现
/speckit.implement 按 tasks.md 实现阅读商城。要求： 1）最小修改，复用现有架构； 2）奖励计算、幂等、余额扣减、阅读秒数口径变更前先确认； 3）SQL 仅限本功能表，不破坏既有契约。七、初始化后的项目结构（概念说明）
specify init后典型目录（以官方模板为准，版本可能略有差异）：
| 路径 | 含义 |
|---|---|
.specify/ | Spec-Kit 核心模板、扩展与预设根目录 |
.specify/templates/ | constitution / spec / plan / tasks 等模板 |
.specify/memory/或specs/ | 各功能分支的规格与计划制品 |
.cursor/（Cursor 集成） | Slash commands 或 Agent 规则入口 |
tasks.md | 当前特性任务清单（由tasks命令产出） |
扩展与预设（进阶）：
specify extensionadd<name># 新增工作流能力（如 Jira、代码评审）specify presetadd<name># 覆盖模板格式（如合规、中文术语）项目级覆盖可放在.specify/templates/overrides/。
八、实践建议与常见问题
8.1 在阅见项目中的实践经验
- Brownfield 先对齐现状：
specify中要求 AI「阅读现有schema.sql/ 路由 / 风格」，避免重复造表。 - 业务常量写进 Spec：如
MIN_READ_SECONDS=600、里程碑奖励，减少 implement 阶段争议。 - implement 加护栏：明确「不随意改全局配置」「大逻辑先 human confirm」。
- 与实训博客联动：每个功能完成后，用 Spec 产物反查代码，撰写「工作记录」博客（见
doc/项目实训个人工作记录（七）-阅读商城书币与称号.md）。 - 可选 analyze：多模块联调前跑一遍，检查接口是否在 plan 与 tasks 中齐全。
8.2 常见问题
| 问题 | 处理 |
|---|---|
uv tool install慢或失败 | 配置config.toml镜像；或检查 Git / 网络 |
specify check失败 | 确认 Python 3.11+、specify在 PATH（uv tool安装后重启终端） |
Cursor 无/speckit命令 | 重新specify init . --integration cursor-agent --force；检查.cursor是否生成 |
| AI 跳过 tasks 直接写代码 | 明确要求「只输出 tasks.md，不写代码」；分两次对话 |
| 生成代码与项目风格不符 | constitution 中写明栈与目录约定；implement 强调「复用现有 Controller/Service 风格」 |
| Windows 路径问题 | init 时选ps；避免在 cmd 与 ps 混用导致脚本异常 |
8.3 与「内嵌智能体 / AI 封面」的关系
- 适合 Spec-Kit：有清晰业务规则的功能（阅读商城、打卡幂等、称号购买校验）。
- 可 Spec 但需拆分：大功能（剧情推演）建议分「持久化 / 前端 / 编排器」多个
specify周期。 - 不宜只靠 Spec 一次写完：强依赖本地环境的能力（ComfyUI 部署）——Spec 写需求与接口，人工完成环境配置与联调。
九、命令速查表
# 环境 uv tool install specify-cli --from git+https://github.com/github/spec-kit.git specify init . --integration cursor-agent --force specify check # SDD 主流程（在 AI Agent 中） /speckit.constitution … /speckit.specify … /speckit.clarify … # 可选 /speckit.plan … /speckit.tasks /speckit.analyze … # 可选 /speckit.implement /speckit.checklist … # 可选十、参考资料
- spec-kit 官方仓库
- Spec-Kit 文档站
- Supported AI Integrations
- 腾讯云：Spec-Kit 介绍
- 知乎：Spec 驱动开发实践
- 腾讯云：SDD 方法论
- 博客园：spec-kit 使用笔记
十一、总结
Spec-Kit 将 AI 辅助开发从「即兴对话」升级为可评审、可回溯的分阶段流水线：先用/speckit.constitution与/speckit.specify锁定原则与需求，再用/speckit.plan与/speckit.tasks把实现路径结构化，最后由/speckit.implement在约束下改代码。在阅见实训中，阅读商城等模块已验证该流程对中等复杂度、规则明确的需求显著降低返工；配合本文的配置步骤与命令速查，可在新功能开发时快速复用。
