Spec-kit配置及使用

Spec-Kit 配置与使用指南Spec-Driven Development在项目实训使用 AI 辅助完成代码的过程中了解到Spec Coding规范驱动开发以及 GitHub 开源工具spec-kit。本文记录其在 Windows Cursor 环境下的配置、标准工作流与在「阅见」项目中的实践要点便于后续功能开发时复用。一、Spec Coding 介绍1.1 什么是 Spec-Driven DevelopmentSDDSpec 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/目录宪法、规格、计划、任务等制品的模板与输出约定。支持30AI 编程 Agent含Cursor、Claude Code、Copilot、Codex CLI 等详见官方 Integrations 文档。二、标准工作流总览/speckit.constitution项目原则/speckit.specify需求规格/speckit.clarify可选澄清/speckit.plan技术计划/speckit.tasks任务拆解/speckit.analyze可选一致性分析/speckit.implement按任务实现/speckit.checklist可选质量检查推荐顺序官方constitution→ 2.specify→ 可选clarify→ 3.plan→ 4.tasks→ 可选analyze→ 5.implement→ 可选checklist在 Agent 对话中在 prompt开头使用/speckit.xxx并说明项目上下文各命令会将产物写入约定目录通常在.specify/或项目内specs/、tasks.md等以初始化时模板为准。三、环境配置3.1 前置条件依赖说明Python 3.11Specify CLI 运行环境Git从 GitHub 安装 specify-cliuv推荐或 pipxPython 工具隔离安装AI Agent如 Cursor、Claude Code 等操作系统Windows / macOS / Linux 均可3.2 配置 uvWindows安装PowerShell建议管理员权限powershell-cirm https://astral.sh/uv/install.ps1 | iexuv--version配置国内镜像可选提升 pip 下载速度配置文件路径%USERPROFILE%\.config\uv\config.toml例如C:\Users\你的用户名\.config\uv\config.tomlnotepad%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--fromgithttps://github.com/github/spec-kit.gitvX.Y.Z# 或直接安装 main 分支开发/尝鲜uv tool install specify-cli--fromgithttps://github.com/github/spec-kit.git版本与升级specify self check# 检查是否有新版本specify self upgrade--dry-run# 预览升级命令specify self upgrade# 升级到最新稳定版四、项目初始化Specify CLI4.1 新建项目specify initPROJECT_NAME# 示例specify init my-app--integrationcursor-agent4.2 在已有仓库中初始化阅见等 Brownfield 项目# 在当前目录初始化specify init.# 或specify init--here# 指定 AI 集成Cursor 示例specify init.--aicursor-agent# 等价写法新版 CLI 更推荐 --integrationspecify init.--integrationcursor-agent# 目录非空时强制合并specify init.--force--integrationcursor-agent交互选项说明终端会提示选择AI 集成Cursor、Copilot、Claude Code、Codex 等Windows 用户若询问 Shell 类型建议选择PowerShellps与日常开发环境一致若未安装对应 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.clarifyspecify之后、plan之前澄清规格中模糊点原/quizme/speckit.analyzetasks之后、implement之前检查 spec / plan / tasks 一致性/speckit.checklist实现前后生成需求完整性检查清单/speckit.taskstoissuestasks之后将任务列表转为 GitHub Issues5.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奖励计算、幂等、余额扣减、阅读秒数口径变更前先确认 3SQL 仅限本功能表不破坏既有契约。七、初始化后的项目结构概念说明specify init后典型目录以官方模板为准版本可能略有差异路径含义.specify/Spec-Kit 核心模板、扩展与预设根目录.specify/templates/constitution / spec / plan / tasks 等模板.specify/memory/或specs/各功能分支的规格与计划制品.cursor/Cursor 集成Slash commands 或 Agent 规则入口tasks.md当前特性任务清单由tasks命令产出扩展与预设进阶specify extensionaddname# 新增工作流能力如 Jira、代码评审specify presetaddname# 覆盖模板格式如合规、中文术语项目级覆盖可放在.specify/templates/overrides/。八、实践建议与常见问题8.1 在阅见项目中的实践经验Brownfield 先对齐现状specify中要求 AI「阅读现有schema.sql/ 路由 / 风格」避免重复造表。业务常量写进 Spec如MIN_READ_SECONDS600、里程碑奖励减少 implement 阶段争议。implement 加护栏明确「不随意改全局配置」「大逻辑先 human confirm」。与实训博客联动每个功能完成后用 Spec 产物反查代码撰写「工作记录」博客见doc/项目实训个人工作记录七-阅读商城书币与称号.md。可选 analyze多模块联调前跑一遍检查接口是否在 plan 与 tasks 中齐全。8.2 常见问题问题处理uv tool install慢或失败配置config.toml镜像或检查 Git / 网络specify check失败确认 Python 3.11、specify在 PATHuv 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 githttps://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在约束下改代码。在阅见实训中阅读商城等模块已验证该流程对中等复杂度、规则明确的需求显著降低返工配合本文的配置步骤与命令速查可在新功能开发时快速复用。