一篇文章带你掌握SpecKit

SpecKit

是什么？SpecKit是一个规格驱动开发（Specification-Driven Development）的工作流框架

安装SpecKit的CLI

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

验证

specify --version
specify --help

报错找不到相关命令

永久加到用户环境变量(推荐)

setx PATH "C:\Users\e-Jiaxin.Yang1.local\bin;%PATH%"

关闭当前窗口，新开一个测试即可

初始化项目

在干什么？

• 在项目里装 SpecKit 的技能和模板

为了啥？

• 让 Claude Code 有这套 slash command 可用

specify init . --integration claude

弹出了一个交互式选择菜单 ，让你选「脚本类型」：选择ps(powershell) 回车即可

然后会生产一堆文件及目录 如下图

• 如果没看到这个命令 可以关掉Claude Code，重开即可。或者新开个新的

实战

第1步: /speckit-constitution (项目宪法)

在干什么？

• 定项目宪法:核心原则、技术约束、质量要求

为了啥？

• 整个项目的"规矩",后续每一步都不能违反它。相当于给AI定下"家规"

-- 通用引导
/speckit-constitution
-- 精准定制
/speckit-constitution 创建项目开发原则：
- 代码框架使用Vue3
- 组件库用shadcn
- 遵循函数式编程规范
- 功能必须完整实现
​
所有产出的需求、规格、API文件与说明文件，一律使用简体中文撰写

• 执行成功：宪法已经生成在 .specify/memory/constitution.md 里了

第 2 步: /speckit-specify(写清楚功能需求，只讲要什么 不讲怎么做)

在干什么？

• 写一个具体功能的需求:用户故事、验收标准、成功指标

为了啥？

• 把"我想做个学生管理的功能"变成结构化的、可测试的需求文档

/speckit-specify 开发一个学生管理系统 纯前端实现
- 支持注册、登录、获取个人信息
- 支持学生管理列表的增删改查

结果：把我们要的功能变成了完整需求规格文档，新生成了三个文件。

• 规格文件：specs\001-student-management-mvp\spec.md
• 质量校验清单：specs\001-student-management-mvp\checklists\requirements.md
• feature.json：.specify/feature.json

第3步：可选，先用 /speckit-clarify 做结构化澄清，补足歧义（个人感觉可以这步还是不错，可以加上，把一些模糊的点给确认了）

在干什么？

• 审查上一步生成的规格文档，主动挖掘模糊点、矛盾点和边界缺失
• 通过多轮问答，把工程落地细节（如数据方案、鉴权、交互模式、编程规范）逐一钉死

为了啥？

• 把"AI 猜测出来的初版规格"变成无歧义、可直接用于编码且符合 Constitution 约束的精确蓝图
• 避免在写代码阶段才发现需求漏洞，防止因理解偏差导致的大面积返工

/speckit-clarify 
基于已生成的《学生管理系统》初版规格，请进行全面歧义审查。
​
以下是我当前最关注的几个方向（仅供参考，不限于此）：
- 纯前端数据持久化与鉴权方案
- 学生实体字段与校验规则
- shadcn-vue CRUD 交互模式选型
- Vue3 函数式编程规范的具体落地方式
​
请在覆盖以上方向的同时，主动扫描规格文档中我可能遗漏的其他模糊点、矛盾点或边界条件缺失。
以问答形式分批向我确认，每轮不超过3个问题，待我全部回复后再更新规格文档。

• 接着AI会询问你一些不确定的方案 让你选择， 按需选择即可

• 规格已更新，接着它会 同步更新质量校验清单，重新核验。

  • spec.md 及 requirements.md 将会更新

第4步：/speckit-plan 把需求翻译成技术方案

在干什么？

• 出技术方案:选技术栈、定架构、模块划分

为了啥？

• 把"要做什么"翻译成"怎么做"------用 React 还是 Vue?存文件还是数据库?怎么组织代码?

-- 使用了/speckit.clarify
/speckit-plan
基于已澄清的 spec.md，制定学生管理系统的技术实现方案。
请重点承接 clarify 阶段刻意 defer 的决策：
1. Vue3 函数式编程规范的具体落地方式（纯函数隔离、不可变数据流、Composables 设计）
2. shadcn-vue 组件精确选型与配置（Dialog/AlertDialog/Table/Form）
3. 存储介质最终选型（localStorage vs IndexedDB）及密码哈希算法实现
4. 路由结构与状态管理方案（Pinia store 划分原则）
5. 跨标签页会话同步的技术实现细节
​
输出 plan.md，需包含模块拆分、依赖关系、关键技术决策依据及风险点。
​
​
-- 没使用/speckit-clarify
/speckit-plan
基于当前初版 spec.md（未经过 clarify 阶段），制定学生管理系统的技术实现方案。
​
⚠️ 注意：规格文档中存在未澄清的工程歧义，请在规划阶段主动完成以下关键技术决策，并明确写入 plan.md 的「技术决策」章节：
1. 纯前端数据持久化方案选型（localStorage / IndexedDB / Mock API）及选择依据
2. 无后端场景下的登录鉴权与会话管理机制（含跨标签页同步策略）
3. Vue3 函数式编程规范的具体落地方式（纯函数隔离、不可变数据流、Composables 设计原则）
4. shadcn-vue CRUD 交互模式与组件精确选型（Dialog / Drawer / Table / Form 等）
5. 学生实体核心字段定义、校验规则及密码哈希算法实现
6. 路由结构与状态管理方案（Pinia store 划分原则）
​
输出 plan.md，需包含：
- 模块拆分与依赖关系
- 上述 6 项技术决策的最终结论与理由
- 因跳过 clarify 可能引入的风险点及缓解措施
- 对 spec.md 中模糊需求的合理化假设声明

结果：生成了部分文件

都在 specs\001-student-management-mvp 下面:

文件	干什么的
specs\001-student-management-mvp\plan.md	技术上下文、宪法校验（四原则全通过）、项目结构（分层架构）、决策依据与风险
specs\001-student-management-mvp\research.md	承接 5 项 defer 决策：函数式分层、shadcn-vue 选型、存储+哈希、路由+Pinia、跨标签页同步
specs\001-student-management-mvp\data-model.md	serAccount/Student/Session 实体、字段校验、存储结构、派生纯函数清单
specs\001-student-management-mvp\contracts\auth-composables.md	useAuth 接口（register/login/logout/fetchProfile）
specs\001-student-management-mvp\contracts\student-composables.md	useStudents 接口（CRUD+检索，不可变更新）
specs\001-student-management-mvp\contracts\storage-contract.md	storage/仓储层 IO 契约 + 存储键常量
specs\001-student-management-mvp\quickstart.md	4 场景端到端验证（对照 US1--US4 + SC-001~008）

第5步：/speckit-tasks

在干什么？

• 把计划拆成一个个小任务,带依赖关系和优先级

为了啥？

• 让 AI 能一个任务一个任务地执行,不会一口气写太多搞乱

/speckit-tasks
基于已确认的 plan.md 与 clarify 阶段产出的需求澄清记录，生成学生管理系统的原子任务清单 tasks.md。
​
📋 输出格式要求：
使用 Markdown 复选框列表 + 分组标题，按以下结构组织：
- 按模块分组（如：存储层 / 鉴权层 / UI 组件 / 业务逻辑），每组使用 ### 标题
- 每个任务为一个 `- [ ]` 条目，格式如下：
  - [ ] **T-{模块缩写}-{序号}** | {任务描述} | 依赖: {依赖ID或无} | 优先级: {P0-P3} | 预估Token: {数值} | 风险: {⚠️标记或无}
    - 验收标准: Given {...} When {...} Then {...}
- 禁止使用表格，必须使用可勾选的 Markdown 复选框语法
​
🎯 任务拆分硬性约束：
1. 原子性：单个任务代码产出 ≤ 150 行，或仅涉及 1 个文件/1 个函数；超出则必须继续拆分
2. 独立性：每个任务可独立运行测试，不依赖未完成的任务（允许 mock）
3. 函数式约束：涉及 Composables / 工具函数的任务，验收标准中必须包含纯函数断言（无副作用、输入输出确定性）
4. 高风险标记：跨标签页同步、存储介质操作、密码哈希相关任务，必须在风险字段注明 ⚠️ 并在验收标准后追加「降级方案: ...」
5. 验收标准：统一使用 Given/When/Then 格式，禁止模糊表述（如"功能正常""无明显bug"）
​
🔍 自检要求：
生成完成后，自动检查并将结果附在 tasks.md 末尾（不使用复选框，仅作校验记录）：
- 是否存在循环依赖
- P0 任务是否全部无前置依赖
- 所有 plan.md 中的技术决策是否都有对应落地任务
- clarify 阶段确认的需求细节是否均已映射到具体任务
- 高风险任务是否均已标记

结果：生成了一个任务清单文件

• 人工审查 ，必做！！！

  • 看下粒度是否达标，检查。

第6步：/speckit.analyze 建议加上

• 我当时忘了哈哈 问题不大

第7步：/speckit-implement

在干什么？

• 按任务列表真正写代码

为了啥？

• 把 spec + plan + tasks 变成能跑的程序

/speckit-implement
读取 tasks.md，按优先级与依赖关系逐个执行原子任务。
​
🔁 单任务执行循环（每个任务必须严格遵循）：
1. 编码实现当前任务，确保符合验收标准中的 Given/When/Then 断言
2. 运行语法检查与项目构建（如 tsc --noEmit / npm run build / cargo check 等，根据项目技术栈自动选择）
3. 若构建失败：立即修复，不得进入下一步；修复后重新执行步骤 2
4. 若构建通过：执行 git add . && git commit -m "feat({模块}): {任务ID} {任务简述}"
5. 将 tasks.md 中对应任务的 [ ] 更新为 [x]
6. 禁止执行 git push，所有提交仅保留在本地仓库
​
⚠️ 阻塞处理：
- 构建连续失败 3 次仍无法修复 → 暂停并报告具体错误日志
- 测试断言与任务描述冲突 → 暂停并请求确认，不得自行修改任务定义
- 发现前置任务缺失 → 暂停并列出缺失项，不得跳过当前任务

结果：源代码都在src目录下

项目效果图

• 由图可见 简单雏形已经有了，个人感觉还是不错的 shadcn就是优雅， 包括不同账号看到的学生也有隔离。

第8步：/speckit-converge

在干什么？ 下·

• 对照规格文档逐条检查代码实现到位没有，把没做到位的补成新任务追加到任务清单末尾,让 implement 接着补完

为了啥？

• 确保实现没偏离需求,该做的都做了

/speckit-converge
基于 plan.md、constitution.md、tasks.md 与当前代码库，执行全量收敛检查。
​
【人工走查反馈】：
核心用户故事与主流程已人工验证通过，无明显运行时异常。
​
请重点检查：
1. 代码实现是否完全覆盖 tasks.md 中所有标记为完成的任务
2. 实际代码结构是否符合 constitution.md 中的架构约束
3. 是否存在 spec.md 中定义但代码未体现的功能点
4. 实施过程中产生的临时方案或变更是否已同步回文档
​
若全部对齐，请明确输出"✅ 收敛完成"并确认可进入交付阶段。

结果：如果代码和任务不匹配的话 会继续追加任务，接着执行

speckit-implement

它会接着跑 xxxx--xxxx,补完这几个小任务。跑完再跑一次:

/speckit-converge

这次应该会显示 converged(零发现) ,整个流程就彻底闭环了

怎么选

场景	推荐链路	说明
探索性 Demo、内部一次性小工具	specify → plan → tasks → implement	跳过 clarify 和质量门禁，图快
生产级功能、多人协作	constitution → specify → clarify → plan → checklist → tasks → analyze → implement → converge	全量九步，质量门禁全开
需求已 100% 明确	直接写代码	spec-kit 价值发挥不出来

方法论速查表

方法论要点	一句话说明	对应命令
宪法先行	技术栈、禁止项写死，不留 AI 自由发挥空间	/speckit.constitution
只讲意图	spec 阶段不碰技术选型，只讲用户故事和验收标准	/speckit.specify
澄清优先	哪怕需求只有三句话，也要跑一遍边界条件确认	/speckit.clarify
技术落地	目录结构、表结构、接口契约在这一步定稿	/speckit.plan
需求质检	用清单挑出「以为讲清楚了」和「AI 真读懂了」之间的落差	/speckit.checklist
任务拆解	每个任务小而明确，自带验收标准	/speckit.tasks
一致性把关	implement 之前做一次跨文档核对，别带病上线	/speckit.analyze
代码落地	AI 按任务清单交付，任务完成自动跑测试	/speckit.implement
持续对齐	需求变了先改 spec，再让代码追上来，而不是反过来	/speckit.converge

全命令清单与定位

命令	类型	作用	时机
/speckit.constitution	核心	建立项目原则、技术栈约束、治理规则	项目首次，或原则需更新时
/speckit.specify	核心	写功能规格（用户故事 + 功能需求）	每个功能开始
/speckit.clarify	增强（建议必做）	系统性澄清 spec 的模糊点	specify 之后、plan 之前
/speckit.plan	核心	技术实现方案（受宪法约束）	specify/clarify 之后
/speckit.tasks	核心	拆解有序原子任务	plan 之后
/speckit.analyze	增强（建议必做）	跨制品一致性 + 覆盖度分析	tasks 之后、implement 之前
/speckit.implement	核心	逐任务实现	tasks 之后
/speckit.converge	增强（按需）	代码 vs 规格对齐性收敛，补缺失任务	implement 之后
/speckit.checklist	增强（灵活）	生成"需求的单元测试"清单	specify/plan/tasks 之后均可
/speckit.taskstoissues	增强（可选）	把任务转成 GitHub Issues	tasks 之后，需团队跟踪时

什么场景适合用SDD

非常适合的：

• 从零开始的新项目，特别是需要严格架构规范的企业级应用
• 多团队协作项目，需要统一的开发标准和文档体系
• 外包项目，清晰的规范能大幅减少沟通成本
• 技术选型对比，同一个规范可以生成多种实现方案

需要谨慎的：

• 每日多次部署的超高速迭代项目，可以用简化版流程
• 目标不明确的纯研究项目，等结果稳定后再应用

不太适合的：

• 紧急修复，生产问题需要立即解决
• 一次性的数据处理脚本
• 100行以内的简单工具