Spec Kit 使用与最佳实践

TraitsW

664人浏览 · 2026-04-21 15:08:29

TraitsW · 2026-04-21 15:08:29 发布

Spec Kit 使用与最佳实践

1. Spec Kit 是什么

Spec Kit 是 GitHub 开源的一个 Spec-Driven Development（规格驱动开发，SDD） 工具包。它的核心思想不是“先写代码，再补文档”，而是把：

需求规格（spec）
技术实现计划（plan）
任务拆解（tasks）

当作开发主线，让 AI 代理根据这些结构化文档去实现代码，而不是直接靠一段模糊 prompt“即兴生成”。

官方文档对它的定位可以概括为：

先定义 What / Why
再补充 How
再生成 Tasks
最后才进入 Implement

这套流程的目标是降低 AI 开发中的漂移、返工和不可追踪性。

2. 什么时候适合用

Spec Kit 特别适合以下场景：

需求较复杂，不能靠一句 prompt 说清楚
团队协作，希望需求、计划、任务都有留痕
想在编码前让 AI 先暴露歧义和风险
需要在同一需求上尝试不同实现方案
存量项目持续迭代，希望新功能开发更可控

不太适合的场景：

一次性原型、演示性质的小玩具
改 1 到 2 个很小的点，建 spec 的成本高于收益
团队完全不维护文档产物，只想“一次生成就结束”

一个简单判断标准：

功能越大、影响越广、协作越多，越适合上 Spec Kit
功能越小、生命周期越短，越不值得走全流程

3. 核心理念

Spec Kit 背后的 SDD 可以总结成 5 条：

规格是主资产，代码是规格的实现结果
规格不是“辅助材料”，而是开发源头。
先写意图，再写实现
specify 阶段只讲用户需要什么、为什么需要，不提前陷入框架、接口、类设计。
持续澄清，而不是一次写完
clarify、checklist、analyze 都是用来反复压缩歧义、补洞和对齐的。
模板约束 AI，减少自由发挥失控
Spec Kit 的价值不只是生成文件，而是用结构化模板限制 AI 的输出质量。
迭代是常态
对复杂需求，不应期待一轮 specify -> plan -> tasks -> implement 就永久正确，而要允许多轮 refinement。

4. 安装与初始化

4.1 前置要求

官方安装文档列出的关键依赖：

uv
Python 3.11+
git
一个受支持的 AI Coding Agent

受支持的代理较多，包括但不限于：

Claude Code
GitHub Copilot
Codex CLI
Cursor
Gemini CLI
Windsurf

如果你在 Cursor 中使用，官方集成 key 是：

cursor-agent

4.2 官方推荐安装方式

优先使用 GitHub 仓库来源安装，不要依赖同名的非官方 PyPI 包。

推荐固定版本：

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

一次性运行也可以：

uvx --from git+https://github.com/github/spec-kit.git@vX.Y.Z specify init <PROJECT_NAME>

在已有项目中初始化：

uvx --from git+https://github.com/github/spec-kit.git@vX.Y.Z specify init --here --ai cursor-agent

或：

specify init --here --ai cursor-agent

4.3 脚本类型

Spec Kit 同时支持：

Bash：.sh
PowerShell：.ps1

Linux / macOS 默认通常会选 sh，Windows 默认通常会选 ps。如果你想显式指定：

specify init --here --ai cursor-agent --script sh

4.4 初始化后会生成什么

常见会看到这些内容：

代理命令/技能文件目录
.specify/scripts/
.specify/templates/
.specify/memory/constitution.md
specs/<feature>/...

其中：

.specify/ 更偏“框架层”和模板层
specs/ 是每个功能的真实规格资产

5. 推荐工作流

官方主流程可以记成：

constitution -> specify -> clarify(可选) -> checklist(可选) -> plan -> tasks -> analyze(可选) -> implement

下面按阶段解释。

5.1 `/speckit.constitution`

作用：定义项目级规则，也就是你的“开发宪法”。

通常应该在项目早期完成，内容包括：

架构原则
测试策略
依赖/基础设施约束
安全、性能、可维护性要求
团队约定

最佳实践：

写 不可妥协的原则，不要写空泛口号
用可验证语言，尽量少写“尽量”“适当”“最好”
把会影响后续 plan / tasks / implement 的约束写进去
没有长期约束的内容不要放 constitution，避免它膨胀成杂物箱

好的例子：

必须先写 contract tests 再写实现
所有外部依赖必须可替换并有超时控制
所有配置必须环境化，不允许硬编码

不好的例子：

代码要优雅
尽量高性能
尽量少 bug

5.2 `/speckit.specify`

作用：把一个功能想法转成结构化规格。

这一阶段最重要的原则是：

只讲 What / Why
不要提前讲 How

推荐写法：

用户是谁
他们要完成什么任务
为什么要做
成功标准是什么
明确范围边界和不做什么

不推荐一上来就写：

用 React / Next.js / Spring Boot / Redis
新增某某表结构
加某个 SDK
暴露几个 API

因为这些属于 plan 阶段。

示例：

/speckit.specify 为团队内部知识库增加“文档失效提醒”能力。
当文档超过维护周期后，系统应提醒责任人更新。提醒需要支持按团队和知识域过滤。
产品目标是减少过期知识继续被引用的问题。

5.3 `/speckit.clarify`

作用：让 AI 主动找出规格中的歧义、边界条件和未决策项。

这是 Spec Kit 非常关键的一步。公开讨论里，很多用户都把 clarify 视为真正拉开质量差距的阶段。

最佳实践：

在 plan 之前跑一次
对复杂需求，可以跑多次
如果 AI 提出的问题很关键，不要急着进入 plan
回答时给出明确取舍，不要继续模糊

适合澄清的问题类型：

权限边界
数据保留策略
分页、排序、过滤规则
失败时的行为
兼容性要求
性能或 SLA 目标

如果第一次 clarify 后你仍感觉 spec 不够清晰，可以继续补充要求后再次运行。这一点在官方 discussion 中也被明确认为是合理做法，没有“必须只跑一次”的硬规则。

5.4 `/speckit.checklist`

作用：检查“需求写得好不好”，而不是检查“代码写得对不对”。

官方模板把 checklist 形容为：

requirements writing 的“unit tests”

也就是它重点验证：

完整性
清晰性
一致性
可测性
场景覆盖
边界条件覆盖
非功能需求是否明确

最佳实践：

把它当“需求质量审计”而不是流程装饰
在关键功能上强烈建议使用
如果 checklist 暴露出大面积模糊项，先修 spec，不要硬进入 plan

5.5 `/speckit.plan`

作用：把业务规格翻译成技术实现计划。

这一阶段才开始引入：

技术栈
架构
数据模型
API / contract
测试策略
quickstart / 验证场景

最佳实践：

明确列出关键技术选择和原因
如果存在多个可行方案，写清楚取舍依据
让 plan 回应 spec 中每条关键需求，而不是单纯写一个“实现构想”
复杂项目建议在 plan 中按阶段拆开，不要一次性铺满所有未来需求

高质量 plan 的特征：

每个技术决策都能追溯回 spec 中的某个需求
关键风险、约束、依赖是显式的
能自然导出后续 tasks

5.6 `/speckit.tasks`

作用：把 plan 变成可执行任务清单。

Spec Kit 会结合：

plan.md
可选的 research.md
data-model.md
contracts/

来生成 tasks.md。

最佳实践：

任务要能映射回用户故事或阶段目标
对可并行工作要明确标记
避免生成“超大任务块”，否则 implement 阶段很容易失控
对复杂功能，优先分阶段任务，而不是一次生成几十个混杂任务

如果任务明显不合理，优先回到 plan 或 spec 修正，而不是直接在错误的任务树上实现。

5.7 `/speckit.analyze`

作用：在实现前做一致性和风险分析。

它通常会检查：

constitution 与 plan 是否冲突
tasks 是否覆盖 spec
plan 是否存在逻辑缺口
某些设计是否无法落地

最佳实践：

在 implement 前几乎都建议跑一次
对 analyze 提出的高优先级问题优先处理
可以多轮 analyze，直到关键问题收敛

公开讨论中，维护者明确表示：
对于修改已有 spec / plan / tasks，没有唯一正确姿势。你可以：

继续使用 core commands
使用 clarify / checklist / analyze
让 AI 直接编辑文件
手动编辑

重点不是“只能跑一次”，而是保证最终产物一致、可执行。

5.8 `/speckit.implement`

作用：按任务清单进入实现。

最佳实践：

不要在 spec 和 tasks 明显未收敛时就 implement
大功能按 phase 实施，避免一次吃掉整个 tasks.md
每完成一个阶段都回头验证
对实现后出现的偏差，要及时回补 spec / plan / tasks，避免产物漂移

6. 最推荐的一套落地方式

如果你是第一次在真实项目中引入 Spec Kit，建议用下面这套节奏：

方案 A：标准团队流程

初始化项目并固定版本
写 constitution
为单个功能运行 specify
跑 clarify
跑 checklist
写 / 生成 plan
生成 tasks
跑 analyze
按阶段 implement
实现后如果有偏差，再修正 spec 资产

方案 B：较轻量的个人流程

constitution
specify
clarify
plan
tasks
analyze
implement

如果功能特别小，可以省掉 checklist，但不建议省掉 clarify 和 analyze。

7. 编写高质量输入的实践

7.1 写 spec 时

建议包含：

目标用户
核心场景
成功标准
约束条件
边界 / 非目标

避免：

提前指定实现细节
把多个完全不同功能揉成一个 spec
用“做个类似 X 的东西”代替明确需求

7.2 写 plan 时

建议包含：

技术栈和版本边界
数据流 / 控制流
接口契约
依赖与风险
测试和验证策略

避免：

plan 仍然停留在业务描述，没有技术落地
没有说明为什么选某方案
直接跳进代码细节，反而破坏 plan 的可读性

7.3 写 constitution 时

建议放进去的内容：

不可违背的工程原则
团队统一技术约束
测试优先级
安全 / 合规 / 可观测性要求

不建议放进去的内容：

某次 feature 的临时决定
很快会过时的业务细节
没有办法检查是否满足的“价值观口号”

8. 存量项目（Brownfield）使用建议

Spec Kit 不只适合新项目，也适合已有代码库，但 Brownfield 项目更容易出现两个问题：

规格和现有实现不一致
升级或反复初始化时覆盖自定义配置

推荐做法：

先写清楚 constitution，明确哪些既有架构必须继承
新功能单独建 spec，不要试图一次把整个旧系统完整“补 spec”
每个 feature 都走小步闭环：specify -> clarify -> plan -> tasks -> analyze -> implement
发现现实代码与 spec 偏离时，优先决定“改代码”还是“改 spec”，不要让两边长期漂移

官方 issue 也说明了：Brownfield 的持续演进流程仍在不断完善，当前比较稳妥的做法是把 spec 当作增量资产维护，而不是频繁重新初始化整个项目。

9. 升级、切换集成与版本管理

这是 Spec Kit 实战里最容易踩坑的地方。

9.1 升级 CLI

uv tool install specify-cli --force --from git+https://github.com/github/spec-kit.git@vX.Y.Z

然后执行：

specify check

9.2 刷新项目内模板/命令

specify init --here --force --ai cursor-agent

9.3 官方已知风险

根据官方升级文档，下面这些通常是安全的：

specs/ 目录下的规格、计划、任务
源代码
git 历史

但下面这些可能被覆盖：

.specify/memory/constitution.md
.specify/templates/
集成生成的命令/技能文件

9.4 升级最佳实践

每次升级前建议：

先提交 git 或做好备份
备份 constitution.md
如果改过 .specify/templates/，整目录备份
升级后恢复你的自定义内容
再用一轮 analyze 检查新模板与当前项目是否仍一致

备份示例：

cp .specify/memory/constitution.md /tmp/constitution-backup.md
cp -r .specify/templates /tmp/specify-templates-backup
specify init --here --force --ai cursor-agent
cp /tmp/constitution-backup.md .specify/memory/constitution.md

9.5 集成管理

官方现在支持独立的 integration 管理命令：

specify integration list
specify integration install cursor-agent
specify integration switch claude
specify integration upgrade

如果你需要从一个 AI 代理切换到另一个，优先使用 integration switch，而不是手动删文件。

10. 最佳实践清单

下面这部分可以当成团队内部约定直接采用。

必做

固定 Spec Kit 版本，避免团队成员模板漂移
每个项目先写好 constitution
specify 只写 What / Why，不提前实现化
在 plan 之前至少跑一次 clarify
在 implement 之前至少跑一次 analyze
大功能分阶段实施，避免一次性实现所有 tasks
实现后及时回补文档，防止 spec 漂移

强烈建议

对重要功能使用 checklist
关键技术决策在 plan 中写明理由
每个 feature 单独维护在自己的 specs/<feature>/ 目录
在 Brownfield 项目里做增量 spec，而不是重建整个仓库的规格
升级前先备份 constitution.md 和自定义模板

尽量避免

把 spec 写成技术设计文档
没跑 clarify 就直接 plan
tasks 明显失真还继续 implement
用一次 implement 试图完成超大范围改动
反复 init --here --force 却不保护自定义 constitution

11. 常见误区

误区 1：Spec Kit 会自动替你想清楚需求

不会。它能帮助你暴露问题，但前提是你愿意对问题作出清晰决策。

误区 2：spec 写得越长越好

不对。更重要的是：

清晰
可验证
有边界
无歧义

误区 3：只要有 tasks，就可以放心 implement

不对。tasks 只是执行分解，不能替代 analyze 和人工判断。

误区 4：升级只升级 CLI 就够了

不一定。CLI 和项目内模板/命令可能需要一起升级，但升级项目前一定要保护自定义内容。

误区 5：Spec Kit 只适合新项目

不对。它同样适合 Brownfield，但 Brownfield 更需要增量引入和小步闭环。

12. 一个可直接套用的最小模板

constitution 提示词模板

/speckit.constitution
本项目必须满足以下长期原则：
1. 所有对外接口必须有明确契约和错误语义
2. 所有配置必须环境化，不允许硬编码敏感信息
3. 关键业务流程必须有自动化验证
4. 默认优先简单实现，禁止无明确收益的抽象层
5. 所有新增能力必须具备可观测性（日志/指标/错误定位）

specify 提示词模板

/speckit.specify
为 <系统/产品> 增加 <功能名>。
目标用户是 <谁>。
用户需要完成 <什么任务>。
这样做是为了解决 <什么问题>。
成功标准包括 <可验证结果>。
本次不包含 <非目标范围>。

plan 提示词模板

/speckit.plan
技术栈使用 <框架/语言/运行时>。
需要满足 <性能/安全/兼容性/部署> 约束。
请重点考虑 <数据模型/API/事件流/权限/测试策略>。

13. 建议的仓库治理方式

如果你准备把 Spec Kit 真正纳入团队流程，推荐：

把 constitution.md 纳入版本控制
把 specs/ 下的核心产物纳入版本控制
对 feature 以分支为单位推进，让规格和实现一起评审
把 analyze 结果作为实现前检查项
在 PR 评审时不仅看代码，也看 spec.md / plan.md / tasks.md 是否一致

从公开讨论看，关于“哪些中间文件一定要提交”的官方规则仍在演进中。保守做法是：至少提交对团队协作有持续价值的核心规格资产，例如 constitution.md 与 specs/ 下的核心文档；对纯临时、一次性中间产物，则根据团队规范决定是否提交。

14. 总结

Spec Kit 不是“让 AI 更会写代码”的工具，而是“让 AI 在更受控的规格约束下写代码”的工具。

想用好它，关键不是记住多少命令，而是坚持下面 4 件事：

先把需求写清楚，再进入实现
用 clarify / checklist / analyze 主动暴露问题
把 constitution 当成长周期工程约束，而不是装饰文件
在复杂项目里分阶段、小步闭环，而不是一把梭

如果只把它当成“多了几个 slash command”，收益会很有限；如果把它当成 AI 时代的规格治理流程，价值会明显大很多。

15. 参考来源

AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念，把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起，为开发者提供从开发、训练到部署的一站式体验。

更多推荐

[Dify x EdgeOne] 论文猎手——用 Dify + EdgeOne Pages 给科研人造一个每日 arXiv 速读助手

AtomGit开源社区

消息跨端架构演进：基于 C++ 的多端一致性研发框架实践

跨端不是追求 100% 代码复用。核心是在"一致性"与"平台最优体验"之间找到平衡点。对于强交互场景（如键盘区域），保留 Native 实现往往是更好的选择。容器框架的抽象层级要足够精简。过度设计会导致理解成本反增。我们的 BizLogicProtocol 只有 7 个核心方法，足以覆盖所有业务场景。全链路质量监控是成功落地的关键保障。跨端方案最怕的不是技术问题，而是出了问题找不到原因。架构合理性

AtomGit开源社区

[Dify x EdgeOne] 哄睡童话机——用 Dify + EdgeOne Pages 给娃造一个会现挂的 AI 睡前故事神器

AtomGit开源社区

所有评论(0)

查看更多评论

TraitsW

@TraitsW

已为社区贡献1条内容

Spec Kit 使用与最佳实践

TraitsW

Spec Kit 使用与最佳实践

1. Spec Kit 是什么

2. 什么时候适合用

3. 核心理念

4. 安装与初始化

4.1 前置要求

4.2 官方推荐安装方式

4.3 脚本类型

4.4 初始化后会生成什么

5. 推荐工作流

5.1 /speckit.constitution

5.2 /speckit.specify

5.3 /speckit.clarify

5.4 /speckit.checklist

5.5 /speckit.plan

5.6 /speckit.tasks

5.7 /speckit.analyze

5.8 /speckit.implement

6. 最推荐的一套落地方式

方案 A：标准团队流程

方案 B：较轻量的个人流程

7. 编写高质量输入的实践

7.1 写 spec 时

7.2 写 plan 时

7.3 写 constitution 时

8. 存量项目（Brownfield）使用建议

9. 升级、切换集成与版本管理

9.1 升级 CLI

9.2 刷新项目内模板/命令

9.3 官方已知风险

9.4 升级最佳实践

9.5 集成管理

10. 最佳实践清单

必做

强烈建议

尽量避免

11. 常见误区

误区 1：Spec Kit 会自动替你想清楚需求

误区 2：spec 写得越长越好

误区 3：只要有 tasks，就可以放心 implement

误区 4：升级只升级 CLI 就够了

误区 5：Spec Kit 只适合新项目

12. 一个可直接套用的最小模板

constitution 提示词模板

specify 提示词模板

plan 提示词模板

13. 建议的仓库治理方式

14. 总结

15. 参考来源

官方资料

官方讨论 / Issue

公开实践文章

所有评论(0)

温馨提示：您尚未绑定手机号

TraitsW

5.1 `/speckit.constitution`

5.2 `/speckit.specify`

5.3 `/speckit.clarify`

5.4 `/speckit.checklist`

5.5 `/speckit.plan`

5.6 `/speckit.tasks`

5.7 `/speckit.analyze`

5.8 `/speckit.implement`