Spec Kit 入门：先写规格，再让 AI 干活

引入

这两年 AI 编码工具最常见的翻车点，不是“不会写”，而是“越写越偏”。你在对话里补了边界条件、验收标准和架构约束，模型当下也许记得住，但一旦任务变长、上下文被压缩，代码就很容易回到“先写点看起来像对的东西”。

GitHub 开源的 Spec Kit，就是冲着这个问题来的。它不想再把 prompt 当一次性口头说明，而是要求你先把规格、计划、任务落成一组 Markdown 工件，再让 Claude Code、Codex、Copilot、Gemini CLI、Cursor、Cline 这类 AI coding agent 去执行。

这篇文章不打算重复发布新闻里的内容。我更想回答四个实际问题：Spec Kit 到底是什么、现在怎么装、实际工作流长什么样、以及它什么时候值得用，什么时候反而会显得重。

一、Spec Kit 在解决什么问题

1.1 它针对的不是“不会写代码”，而是“AI 容易失焦”

GitHub 在官方博客里把问题说得很直白：很多所谓的 “vibe coding” 能很快产出一版代码，但实现会逐渐偏离最初的业务意图。Spec Kit 的思路不是继续叠 prompt 技巧，而是把 spec 重新拉回工程中心，让它成为人和 agent 共享的真相源。

换句话说，Spec Kit 的第一性原理不是“让模型更聪明”，而是“让约束更难丢”。

1.2 它的核心产物不是代码，而是三件套

如果只看官方主流程，Spec Kit 的骨架其实很清楚：

spec.md：定义要做什么
plan.md：定义打算怎么做
tasks.md：把实现拆成可执行任务

随后才进入 implement 阶段，让 agent 去写代码。你可以把它理解成：先让需求、设计和执行边界成形，再让 AI 开始动手。如果把 constitution 算进项目级约束层，完整链路会更像“宪法 + 三件套”。

1.3 它不是绑定单一代理，而是流程层

Spec Kit 官方首页和集成文档都反复强调一件事：它想兼容“任意 AI coding agent”，而不是做一个新的 IDE。集成文档已经列出数十个 agent 集成，并保留了 generic integration 作为兜底路径。

这点很关键。Spec Kit 的价值不在模型本身，而在把实现流程从单轮对话，升级成多阶段工件链。

二、Spec Kit 到底包含什么

2.1 它其实是“CLI + 模板 + 脚本 + Agent 集成”

很多人第一次看到 Spec Kit，会误以为它只是几个 slash command。其实它更像一个小型基础设施层：

组成	作用
`specify` CLI	初始化项目、安装集成、管理 preset / extension / workflow
`.specify/templates/`	提供 spec、plan、tasks、constitution 等模板
`.specify/scripts/`	提供 Bash / PowerShell 辅助脚本
Agent 集成目录	为不同 coding agent 安装对应命令或 skills
`specs/<feature>/`	持续沉淀每个特性的规格、计划、任务和补充工件

它的设计目标很明确：别让每次写需求都从空白 prompt 开始。

2.2 “Constitution” 是它最容易被低估的一步

官方推荐工作流的第一步不是写功能 spec，而是先跑 constitution。这一步会要求你明确项目原则，比如测试要求、架构边界、命名约束、质量门槛和治理规则。

这一步看起来像“文档工作”，但它的价值很实在：以后每次新特性开始时，agent 都能先读到项目宪法，而不是靠你在聊天里临时补一句“顺便保持可测试”。

2.3 官方完整工作流长什么样

Quick Start 给出的推荐顺序是：

/speckit.constitution
/speckit.specify
/speckit.clarify
/speckit.plan
/speckit.checklist
/speckit.tasks
/speckit.analyze
/speckit.implement
/speckit.converge

其中 clarify、checklist、analyze 是典型的质量闸门。你可以轻量跳过，但对于需求含糊、牵涉多人协作、或者准备上生产的功能，这三步其实非常值得保留。

Spec Kit 主流程图

三、怎么上手：安装、初始化和目录结构

3.1 推荐安装方式：优先固定 `release tag`

官方安装文档明确提醒：唯一官方维护的来源是 github/spec-kit 仓库，PyPI 上的同名包不属于官方渠道。

如果你准备长期使用，最稳的方式是固定 release tag 安装：

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

如果你只是想临时试一下，也可以直接一次性运行：

uvx --from git+https://github.com/github/spec-kit.git specify init demo-spec-kit

这里顺便提醒一个实操细节：我在 2026-07-13 用 Windows + PowerShell 直接跑主线仓库时，specify self check 显示的是 0.12.12.dev0，而 GitHub Releases 上最新稳定版仍是 2026-07-10 发布的 v0.12.11。所以真正要落团队环境时，建议钉 release tag，不要裸跟 main。

3.2 Windows + Codex CLI 实测：当前参数用 `--integration`

我在 2026-07-13 用 PowerShell 做了一个最小化 smoke test。当前可用的初始化命令是：

uvx --from git+https://github.com/github/spec-kit.git specify init --here --integration codex --script ps --force

这里有个很容易踩的坑：如果你看到旧示例里写的是 --ai，以当前 specify init --help 为准。现在 CLI 使用的是 --integration 参数。

3.3 初始化后会生成什么

Codex 集成初始化完成后，我本地生成的核心目录大致是这样：

.agents/skills/
  speckit-constitution/
  speckit-specify/
  speckit-plan/
  speckit-tasks/
  speckit-implement/
  speckit-converge/
  speckit-clarify/
  speckit-checklist/
  speckit-analyze/

.specify/
  integrations/
  memory/constitution.md
  scripts/powershell/
  templates/
  workflows/

这说明 Spec Kit 真正安装下来的并不是一个“黑盒命令”，而是一整套本地可见、可改、可扩展的工作流骨架。

四、Spec Kit 真正好用的地方

4.1 它把“先想清楚”变成默认路径

很多 AI 编码流程的一个高频问题，是分析和实现混在一起。Spec Kit 逼你先做 specification、plan 和 tasks，再进入 implement。这个顺序本身就很有价值，因为它天然抬高了“没想清楚就开始写”的门槛。

4.2 它对多代理和跨工具切换很友好

Spec Kit 不绑定某个单一运行时。你可以今天在 Codex CLI 里跑，明天换到 Claude Code 或 Copilot，只要大家都围绕同一套 spec 工件工作，切换成本就不会主要落在“重新解释需求”上。

对于团队来说，这比“大家都写一份自己的提示词”可靠得多。

4.3 它适合有治理要求的团队

官方首页提到它支持离线、可在防火墙后使用，也支持 preset、extension、workflow 和 bundle。这个信号很明确：Spec Kit 不只是面向个人极客，也在试图成为企业和团队的流程组件。

如果你需要这些东西，它会特别有吸引力：

项目原则需要显式化
AI 产出要有中间工件可审查
不同 agent 之间要共享一套约束
要在内网或半离线环境里部署

五、它什么时候会显得过重

5.1 小任务会觉得“文档比代码还多”

如果你只是改两个配置、修一个按钮样式、补一条接口判空，Spec Kit 很可能会让你觉得流程太长。社区里已经有人直说，它有时会制造一种“做了很多事”的感觉。换成工程语言，就是文本工件的增长不一定同步带来代码价值的增长。

这类批评并不离谱。Spec Kit 更像工程治理工具，不是在所有场景下都更快。

5.2 长实现阶段仍会遇到上下文问题

官方在 “Handling Complex Features” 文档里直接承认：复杂特性到了 /speckit.implement 阶段，依旧可能因为上下文窗口耗尽而退化，表现为忽略计划、漏任务、甚至产生幻觉。

它的应对方式不是魔法，而是很工程化：

限制每次 implement 的任务范围
把大特性继续拆小
尽量使用支持 sub-agent 的运行时

这也说明一件事：Spec Kit 不是替你消灭复杂度，而是帮你把复杂度切片。

5.3 多人并行时要准备治理 specs 冲突

GitHub Discussions 里已经有人讨论团队协作下的 merge conflict 和共享契约冲突。原因不难理解：当 spec.md、plan.md、tasks.md 也成为多人共同修改的工件时，冲突不再只发生在代码层，也会发生在“大家如何描述同一个系统”这一层。

所以它不是装上就万事大吉。你仍然需要自己决定：

spec 文件谁负责维护
需求变化后谁来回写工件
共享领域模型怎么避免不同特性各写一套

六、适合谁，现在值不值得试

6.1 适合的场景

我会优先推荐给下面几类人：

场景	为什么适合
从 `0` 到 `1` 的新项目	规格、计划、任务链最容易一次性铺好
需求复杂、容易反复返工的功能	用工件约束 agent，比反复补 prompt 稳
团队里混用多个 AI coding agent	Spec Kit 提供统一流程层
有合规、架构、测试门槛的组织	constitution、checklist、analyze 很好用
Brownfield 增量改造	可以把变更先写成 spec，再决定落代码

6.2 不太适合的场景

下面这些情况，我反而不会优先上 Spec Kit：

只是修小 bug
快速验证创意、一天内就要扔掉
团队暂时没有维护 spec 工件的习惯
你追求的是“先写出来看看”，而不是“先约束清楚再写”

一句话总结：Spec Kit 适合高歧义、高协作、高约束的任务，不适合所有低成本试错。

总结

Spec Kit 的价值，不在于它发明了“写需求”这件事，而在于它把需求、设计和任务重新做成了 AI 能持续读取的工程工件。

如果你已经对“聊天一长就跑偏”的 AI 编码体验感到厌烦，Spec Kit 很值得试，因为它确实把流程从“单轮 prompt”抬到了“多阶段规格驱动”。但也别把它神化。它不是所有项目都更快，也不会自动替你解决复杂实现和多人治理问题。

一句话总结：Spec Kit 不是另一个 AI IDE，而是一层把 AI 编码拉回工程纪律的流程骨架。

参考资料

GitHub Spec Kit 官网 — 官方首页，说明产品定位、主流程和能力边界
Quick Start Guide — 官方推荐工作流与质量闸门
Installation Guide — 官方安装方式、升级和分发来源说明
Supported AI Coding Agent Integrations — 官方集成列表与不同 agent 的安装形态
What is Spec-Driven Development? — 官方对 SDD 的定义和适用范围说明
Handling Complex Features — 官方对长实现阶段上下文退化问题的说明
Upgrade Guide — 官方升级与 constitution.md 覆盖风险提示
GitHub Blog：Spec-driven development with AI — 官方首篇介绍文章
GitHub Blog：Using Markdown as a programming language when building with AI — 官方对方法论延展的说明
GitHub 仓库 README — CLI、模板与工件结构参考
GitHub Releases — 最新稳定版本与发布记录
GitHub Discussion #497 — 团队协作下的冲突与治理讨论
GitHub Discussion #1784 — 对流程开销和“文本幻觉”的批评

引入