导航

SpecKit 规范驱动开发

Posted on 2025-11-27 16:52  蝈蝈俊  阅读(0)  评论(0)    收藏  举报

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

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

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

Speckit 是什么？

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

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

如何使用 Speckit ?

安装前提:

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

# 安装 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 TD A[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 -.->|可选: 需求澄清| C F -.->|可选: 一致性分析| G{增强命令} subgraph G [可选增强步骤] direction LR H[/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 TD A[模糊需求/想法] --> B{流程选择} B -->|需求清晰| C[直接制定规范<br>/speckit.specify] B -->|需求模糊| D[先澄清需求<br>/speckit.clarify] D --> C C --> E[确立项目原则<br>/speckit.constitution] E --> F[制定技术方案<br>/speckit.plan] F --> G[分解任务清单<br>/speckit.tasks] subgraph H[一致性保障] I[分析一致性<br>/speckit.analyze] J[生成检查清单<br>/speckit.checklist] end G --> H H --> 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项目时，建议从中等复杂度的个人项目练手，熟悉整个工作流后再在团队中推广。