SpecKit 规范驱动开发

SpecKit是GitHub推出的一个开源工具包，它采用规格驱动开发(Spec-Driven Development，SDD)的方法。

https://github.com/github/spec-kit

简单来说，它是一种将AI深度融合到开发流程中的方法，倡导先明确“做什么”和“为什么”，再考虑“如何做” ，通过一系列结构化的命令，将你的自然语言需求逐步转化为详细的技术规范、计划、任务乃至最终的代码。

Speckit 是什么？

Speckit的核心在于改变传统的开发范式。它不是一个单一的代码补全工具，而是一个开发框架和流程。其核心理念是“规范先行”，即在编写任何代码之前，先使用自然语言和结构化文档来精确地定义需求、技术方案和任务。

它的主要设计目标是与各种AI编码助手（如Claude Code、GitHub Copilot、Cursor等） 协同工作，通过一套标准化的命令，引导AI助手帮助你完成从需求分析到代码实现的整个流程。

如何使用 Speckit ?

安装前提:

• 确保你的系统已安装 uv （https://github.com/astral-sh/uv）
• git (https://git-scm.com/)
• Python 3.11+ (https://www.python.org/)

在终端中执行以下命令进行安装:

# 安装 Specify CLI
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git# 后续升级
uv tool install specify-cli --force --from git+https://github.com/github/spec-kit.git# 进入你的项目目录（或在新建目录中），运行初始化命令
specify init <PROJECT_NAME>
# 在这个过程中，你需要选择你想要使用的AI助手（例如Claude Code、GitHub Copilot等）。
# 初始化命令会为你的项目创建必要的目录结构和模板文件
specify check

初始化完成后，你就可以在AI助手（如Claude Code）的对话中，使用一系列 /speckit 命令来驱动开发了。

使用Speckit进行开发，标准流程可以概括为以下几个关键阶段:

flowchart TDA[1. 项目初始化<br>specify init] --> B[2. 确立项目原则<br>/speckit.constitution]B --> C[3. 编写功能规范<br>/speckit.specify]C --> D[4. 制定技术方案<br>/speckit.plan]D --> E[5. 生成任务清单<br>/speckit.tasks]E --> F[6. 执行开发<br>/speckit.implement]F -.->|可选: 需求澄清| CF -.->|可选: 一致性分析| G{增强命令}subgraph G [可选增强步骤]direction LRH[/speckit.clarify/]I[/speckit.analyze/]J[/speckit.checklist/]end

示例:分布式实时代码质量分析平台

项目概述

一个能够实时分析多仓库代码质量、检测技术债务、并提供智能重构建议的分布式系统。

区别于现有工具，它能够跨项目关联分析，提供团队级代码健康度洞察。

项目构建

specify init cr1
# 上面命令会创建 cr1 这个目录

这一步我选择 gemini

项目宪法确立 (/speckit.constitution)

为项目制定“宪法”，定义所有开发工作必须遵守的核心原则。

/speckit.constitution 建立以性能、可扩展性、数据一致性和开发者体验为核心的技术原则，遵循第一性原理，消除一切不必要的复杂性

产出：在 .specify/memory/ 目录下生成 constitution.md 文件，其中包含了项目的基本开发原则。

下图是 constitution.md 的部分内容：

编写功能规范 (/speckit.specify)

用自然语言描述你想要构建的功能。

/speckit.specify 构建一个分布式代码质量分析平台，核心功能包括：1. 多仓库实时代码质量扫描
2. 技术债务量化与趋势分析  
3. 智能重构建议生成
4. 团队级代码健康度仪表盘
5. 与GitHub/GitLab深度集成要求：支持Java、Python、TypeScript主流语言，能够处理10万行以上的大型单体仓库

产出：在 specs/ 目录下生成结构化的 spec.md 文件，其中包含用户故事、功能需求、成功标准和边界案例等。

下图是 spec.md 文件部分截图

制定技术方案 (/speckit.plan)

基于上一步的规范，制定具体的技术实施方案。你需要指定技术栈、架构等。

/speckit.plan 技术栈选择：使用Go编写后端，TypeScript+React编写前端。存储使用TimescaleDB存储时间序列指标，ScyllaDB存储代码结构数据。消息队列使用NATS JetStream保证消息持久化。使用OpenTelemetry实现全链路追踪。

产出：在功能目录下生成 plan.md、research.md、data-model.md 等技术方案文档，详细说明了技术选型、项目结构和API设计等

生成任务清单 (/speckit.tasks)

AI助手会自动将技术方案分解成具体、可执行的任务列表

/speckit.tasks 按照架构层次拆分实施阶段，明确各阶段的交付物和验收标准

产出：生成 tasks.md 文件，任务按用户故事分组并标明了依赖关系，为开发提供了清晰的路线图

执行开发 (/speckit.implement)

AI助手会根据任务清单开始编写代码、配置文件和测试用例。

/speckit.implement 开始实施Phase 1和Phase 2的核心任务，首先生成go分析引擎的基础框架和消息总线集成

产出：项目的实际源代码文件。

澄清需求 /speckit.clarify

在制定计划前，对模糊的需求进行结构化提问，降低风险。

比如有这个需求：我想做一个工具，能自动整理我收藏的网页和文档，并且能智能打标签。

在AI助手对话中，你输入：

/speckit.clarify 我想做一个工具，能自动整理我收藏的网页和文档，并且能智能打标签。

AI助手可能会识别到需求中的模糊点，并生成一系列结构化的澄清问题，例如：

• 核心功能范围：您提到的"整理"具体包括哪些操作？例如，是仅提取标题和关键信息，还是需要生成摘要？是否需要支持对PDF等二进制文档的全文内容识别？

• 数据来源与类型："网页和文档"具体指哪些格式？网页是仅保存链接，还是离线存档（如HTML文件）？文档是否支持.pdf, .docx, .md等格式？

• 标签系统："智能打标签"您希望基于什么逻辑？是基于内容的关键词提取，还是自动归类到预定义的分类中？是否需要支持用户自定义标签规则？

• 技术偏好与集成：这个工具是一个独立的桌面应用，还是希望作为Web服务？是否需要与现有的笔记软件（如Notion、Obsidian）集成？

• 用户交互方式：您希望通过什么方式"收藏"内容？例如，是浏览器插件一键添加，还是手动拖拽文件？

通过回答上述问题，你的需求会变得更加明确和具体，可能演变成：

我需要一个桌面端应用，核心功能是：
通过浏览器插件一键保存网页（完整内容离线存档）。
支持手动导入PDF和Markdown文档，并解析其全文文本。

利用自然语言处理技术，自动从内容中提取关键词作为标签，并允许我预定义分类规则。

能将整理好的条目同步至我的Obsidian知识库中。

这个经过澄清的、清晰具体的需求描述，再交给 /speckit.specify 命令，就能生成出结构完整、细节丰富且可直接指导开发的功能规范文档。

/speckit.analyze

在开始实施前，进行跨产物（规范、计划、任务）的一致性分析，生成报告。

/speckit.analyze 检查技术方案与项目宪法的一致性，特别关注性能要求和分布式一致性保证

总结

SpecKit的使用遵循一个清晰的、阶段化的流程，确保从想法到代码的每一步都坚实可靠。其核心工作流可以通过下图完整展示：

flowchart TDA[模糊需求/想法] --> B{流程选择}B -->|需求清晰| C[直接制定规范<br>/speckit.specify]B -->|需求模糊| D[先澄清需求<br>/speckit.clarify]D --> CC --> E[确立项目原则<br>/speckit.constitution]E --> F[制定技术方案<br>/speckit.plan]F --> G[分解任务清单<br>/speckit.tasks]subgraph H[一致性保障]I[分析一致性<br>/speckit.analyze]J[生成检查清单<br>/speckit.checklist]endG --> HH --> K[最终执行<br>/speckit.implement]K --> L[可工作的代码]

SpecKit 的五大关键要点

1. 核心理念：规范先行 (Spec-Driven)

• 根本性转变：从“急着写代码”转变为“先想清楚再动手”

• 核心价值：用结构化的规范文档取代模糊的口头需求

• 实际效果：减少返工，提高代码质量和团队协作效率

2. 宪法治理：原则高于一切

• constitution.md 是项目的最高法律

• 在项目开始时就确立技术标准、质量门禁、架构原则

• 所有后续决策都必须符合宪法精神

示例：树莓派小车的“性能第一”、代码分析平台的“30秒分析时限”

3. 结构化演进：从抽象到具体

SpecKit强制遵循一个层层细化的思考过程：

想法 → 宪法原则 → 功能规范 → 技术方案 → 任务分解 → 代码实现

每个阶段都有对应的命令和产出物，确保思考的完整性和一致性。

4. AI增强而非AI替代

• SpecKit不是让AI替你思考，而是帮你更好地思考

• AI负责繁琐的结构化文档生成，你负责核心的技术决策

• 示例：你决定用Rust做分析核心，AI帮你生成具体的模块设计和API规范

5. 一致性保证：闭环验证

• 使用 /speckit.analyze 检查各阶段产出的一致性

• 通过 /speckit.checklist 确保关键步骤不被遗漏

• 建立从原则到代码的可追溯性

给技术人员的实战建议

什么时候使用SpecKit最有效？

• 复杂项目：涉及多个模块和技术栈的系统

• 团队协作：需要明确分工和接口定义的项目

• 技术探索：尝试新技术栈时的学习路径规划

• 简单脚本：几十行的工具脚本可能过度设计

如何避免“分析瘫痪”？

• 时间盒限制：为每个阶段设置时间限制（如宪法制定不超过1小时）

• 迭代细化：先定核心原则，细节在后续阶段逐步完善

• 聚焦MVP：明确最小可行产品的范围，避免过度设计

成功的关键心态

• 严谨但不死板：宪法是指导原则，不是束缚创新的枷锁

• 拥抱澄清：模糊处就是风险点，主动使用clarify命令

• 代码即产出：所有文档的最终目标都是生成可工作的代码

记住，SpecKit的本质是将优秀工程师的思考过程系统化、模板化。它不能替代你的技术判断，但能确保你的技术判断被完整、一致地执行。

开始你的第一个SpecKit项目时，建议从中等复杂度的个人项目练手，熟悉整个工作流后再在团队中推广。