规格驱动开发
向 AI 编程智能体下指令之前,先写一份规格
GitHub 的 Spec Kit 是 GitHub 自己的开源项目。本指南为独立内容,与 GitHub 无关联,也未获其背书。
使用 AI 编程智能体时,大多数挫败感都来自同一个原因:请求含糊,结果就含糊,而你只有在读完与预期不符的代码之后,才发现自己真正想要什么。规格能把这个顺序理顺。在发出第一条提示之前,你先用平实的语言写下三件简短的事:它应该做什么、给谁用,以及用哪些具体检查来判断它已经完成。这些都不需要懂编程。GitHub 的 Spec Kit 是一个在 GitHub 自己的仓库中维护的开源工具包,它围绕的正是这个习惯,为编程智能体建立了一套结构化、可重复的流程,配有自己的命令行工具,以及一组从项目指导原则一直走到可运行成品的命名步骤。本指南介绍你五分钟就能手写出来的三部分规格,Spec Kit 的工作流如何把同一个思路拆成各自独立的命令,以及什么时候值得安装完整工具包,什么时候自己写规格就够了。
规格是你在请编程智能体构建任何东西之前写下的一份简短、平实的说明:它做什么、给谁用,以及证明它已完成的验收标准。GitHub 的 Spec Kit 是在 GitHub 自己的仓库中构建的开源工具包,它把这个习惯变成一套可重复的工作流,提供各自的命令,用于设定原则、撰写规格、制定计划、把计划拆成任务、实施以及收敛,其文档列出了它所连接的智能体,包括 Anthropic 的 Claude Code 和 GitHub Copilot。要获得这份好处,并不需要这个工具包:把同样的三部分说明作为第一条消息输入,在你已经在用的任何编程智能体里都行得通。
发布于
免费课时 · 无需注册账号认识 Claude为什么是 Claude？6分钟开始免费课时要点总结
- 规格是在第一条提示之前写下的三件事:智能体要构建什么、给谁用,以及证明它已完成的验收标准。
- GitHub 的 Spec Kit 是免费的开源工具包,据其自身仓库说明采用 MIT 许可证,它把这个习惯变成六个命名命令:章程、规格、计划、任务清单、实施,最后是收敛。
- 不用 Spec Kit 也能从规格中受益。把同样的三部分说明作为第一条消息输入,在 Claude Code、OpenAI 的 Codex、Copilot、Anysphere 的 Cursor 或任何其他编程智能体中都有效。
- Spec Kit 自己的安装文档用集成标识列出了它所连接的编程智能体,包括 Claude Code 和 GitHub Copilot,同时也提供了添加其他智能体的途径。
- 跳过验收标准,是规格悄悄失效的最常见原因:没有它们,你和智能体都无法判断任务是否真的完成了。
复制即用
今天就能用的提示词
用来开启第一次对话的三部分规格
下面是我想让你构建的东西的规格。它做什么:一个脚本,把我下载文件夹里的文件按文件类型整理到带日期的子文件夹中。给谁用:只有我自己,在终端里手动运行,没有其他用户。完成标准:在一个包含20个示例文件的测试文件夹上运行后,每个文件都被整理到正确的子文件夹,该文件夹之外的内容一概不动,而且我可以用一条命令撤销整次运行。开始构建之前,有任何需要了解的请先问我。
把它作为你的第一条消息粘贴进去,先不要来回讨论该怎么实现。
请智能体把模糊的想法变成规格
我想做点东西,但想法还很模糊。我大致设想的是:在这里用一两句话描述你的初步想法。在写任何代码之前,请不断向我提问,直到你能分三个简短部分向我复述:它做什么、给谁用,以及我们怎样才能都知道它已经完成。在我明确确认这三个部分之前,不要开始构建。
适用于你知道问题的大致轮廓,但还没把细节敲定的时候。
在批准构建之前先核对验收标准
在你开始实施之前,请列出你会用来证明这件事已完成的具体检查:你会测试什么,每一项的预期结果是什么,以及什么情况算失败。如果某项检查需要你在本次会话内部无法自行验证的条件,请现在就告诉我,不要假设以后会没问题。
一个好的智能体应该能在写下第一行代码之前,详细回答这个问题。
核心习惯
为什么规格要放在提示之前
直接把请求敲进编程智能体,感觉比先写点什么要快,对于真正琐碎的任务,通常也确实如此。麻烦出在那些有不止一种合理理解的任务上:智能体选定一种,朝着它去构建,而你直到读到成品代码时才发现它选错了。从那以后每来回一轮,花的时间都比写一份规格所需的几分钟更多。
规格改变的是做事的顺序。在任何代码写出来之前,你先用平实的语言写下三件事:它应该做什么、给谁用,以及证明它能正常工作的验收标准。这不是技术文档。它更像是你留给一位能干、但从没见过你的助手的便条:细节足够多,让对方不必去猜那些关键的部分。
它之所以管用,原因很简单。智能体不再用自己的假设去填补你请求里的空白,因为剩下的空白已经不多了。而你也不必再事后通过读智能体的输出来发现自己真正想要什么,因为在提出任何要求之前,你已经把它写下来了。
这一切并不局限于某一个工具。Claude Code、Codex、Copilot、Cursor 以及其他所有编程智能体,基本工作方式都一样:输入平实语言的指令,输出代码和命令。规格改变的是输入的内容,也就改变了返回的内容,不管你面对的是哪一个。
三部分规格
五分钟就能写好的规格包含什么
四个简短的部分,用平实的语言写成。这里没有任何一项需要懂编程。
它做什么
用一两句话描述行为,而不是实现方式。写「把文件按类型整理到带日期的文件夹」,而不是去描述该用哪些函数或库。
给谁用
只是你自己手动运行?还是一位从没见过这个项目的同事?这个答案会改变你真正需要构建的东西,往往比功能描述的影响还大。
验收标准
证明构建已完成的、具体且可测试的条件。这是大多数人跳过的部分,也是出问题时最关键的部分。
护栏
可选,但在风险真实存在时值得加上:智能体绝对不能做什么,比如改动某个文件夹之外的文件,或自动发送任何内容。
一套开源的结构
GitHub 的 Spec Kit 如何把规格变成工作流
GitHub 的 Spec Kit 是一个开源工具包,在 GitHub 自己的仓库中以 MIT 许可证维护,目的是给 AI 编程智能体提供结构化的流程、可复用的模板和有记录的成果,而不是一次性的对话。它通过自己的命令行工具安装,其 README 把它描述为一个用于上手规格驱动开发,或你希望智能体遵循的任何其他结构化流程的工具包。
据该项目自己的文档,核心的规格驱动工作流依次经过六个命名命令:一个设定项目的指导原则,一个撰写规格本身,一个把规格转成技术计划,一个把计划拆成有序的任务清单,一个执行任务并写出实际代码,最后一个检查结果与规格的收敛程度。项目自己的建议是一次运行一个命令,每一步的结果都先审阅再继续,并重复实施和收敛这两步,直到收敛检查报告工作已经收敛,而不是把整件事一次性交给智能体。
这个工具包还提供可以叠加在核心工作流之上的独立扩展,同样据其自身文档:一组命令围绕评估并修复某个具体的缺陷,另一组命令围绕把一个粗略的想法先经过调研和界定,再决定是否要构建。
至于它连接哪些智能体,Spec Kit 自己的安装文档用安装时传入的集成标识列出了其中几个,包括 Claude Code 和 GitHub Copilot,并指向其另外的文档,说明如何连接它直接列出的那些之外的更多智能体。请把任何具体的智能体列表,包括这一份,都当作一张快照:在假定某个工具如今是否受支持之前,请先查看 Spec Kit 的最新文档。
逐条命令看工作流
Spec Kit 的六个核心命令
据项目自己的 README,规格驱动工作流按顺序经过这六个步骤,并重复最后两步,直到结果收敛。
设定章程
一个记录项目范围原则的命令,智能体在之后的所有工作中都应遵守这些原则,只写一次,在后续工作中反复使用。
撰写规格
一个生成实际规格文档的命令,内容就是上文介绍的那份平实的说明,只是现在保存成了可复用的文件,而不是一条一次性的消息。
规划方案
一个把规格转成技术计划的命令,在任何代码写出之前先选定方案,这样设计决策就不会被埋在实现里。
拆分成任务
一个把计划拆成具体、有序任务清单的命令,每个任务都小到可以单独检查。
实施
一个执行任务清单并编写代码的命令,以前面各步骤的全部成果为指引,而不是从头开始。
收敛
一个检查结果与规格吻合程度的命令。据项目自己的建议,你要把实施和收敛放在一起重复,直到收敛检查报告工作已经收敛。
什么都不用安装
手写规格,无需工具包
对于只想做一件小东西的非开发者来说,运行完整的 Spec Kit 工作流,可能比任务本身需要的仪式感还多。单独一份三部分规格,作为你发给现有智能体的第一条消息,本身就能完成大部分实际工作,而且不用安装任何东西。
先粘贴规格,然后让智能体在动手写任何东西之前先向你提澄清问题。有能力的智能体在遇到不清楚的地方时会发问,而规格给了它具体可问的内容,而不是悄悄猜测,然后信心十足地做出错误的东西。
这种朴素的做法可以通用。无论你面对的是 Claude Code、Codex、Copilot、Cursor 还是其他任何编程智能体,同样的三部分说明都有效,因为它不依赖某一个工具独有的功能。这是一个你在养成的习惯,而不是一个你在安装的插件。
容易出错的地方
会让规格失效的几种错误
一旦出现下面这些情况,写规格带来的帮助就会打折扣。
没有验收标准
没有验证完成与否的方法,规格只是把猜测从提示阶段挪到了审阅阶段,而那里更难发现问题。
混入实现细节
在还没确定这个功能到底要不要之前,就指定编程语言或具体算法,会让规格变成过早的设计。
事后补写
为了与已有代码吻合而起草的规格,只是记录了已经构建出来的东西。它无法发现一个本来就是为了与之保持一致而写的问题。
一份规格,多个任务
一份规格如果涵盖了不止一个真正的任务,就会把真正重要的那个埋掉。让每份规格只对应一项单一、可检查的工作。
何时该用工具包
朴素规格还是完整 Spec Kit:怎么选
对于单个小型构建,直接在对话里输入一份朴素的三部分规格就够了,而且比安装任何东西都快。本指南里的大部分示例,写的正是这种情况。
当你在同一个项目上反复这样做,希望它的原则自动作用于每一个新功能,或者希望直接用缺陷修复或想法评估扩展自带的结构,而不是每次都自己发明一套类似的做法时,Spec Kit 的安装成本才开始值回票价。
无论哪种方式,真正的技能都是一样的:在写下任何一行代码之前,先说明它做什么、给谁用,以及你怎样知道它已经完成。工具包只是把这个记录过程自动化、保持一致,前提是这个习惯你用得足够频繁,值得为它自动化。
在构建之前练习写规格
写出清晰的规格,并为 AI 编程智能体提供长期有效的项目指令,是一项可以迁移到本指南中每个工具上的技能。Nightschool AI 关于项目指令文件的免费课程,以 Claude Code 为例,正好讲解了这些内容。
常见问题
在这里,规格到底是什么?
它是你在请编程智能体构建东西之前写下的一份简短、平实的说明。至少包含这个东西应该做什么、给谁用,以及证明它已完成的验收标准。它不是技术文档,也不需要懂编程。
写规格需要会编程吗?
不需要。规格用平实的语言描述行为和结果,而不是实现方式。描述一个工具应该做什么、你怎样知道它能正常工作,并不需要编程知识,尽管构建它的智能体会写出真正的代码。
GitHub 的 Spec Kit 是什么?
一个开源工具包,采用 MIT 许可证,在 GitHub 自己的仓库中维护。它围绕规格驱动开发,为 AI 编程智能体提供结构化、可重复的流程,配有自己的命令行工具,以及一组从项目指导原则一直到实施和收敛的六个命名命令。
Spec Kit 能配合哪些编程智能体使用?
据其自身的安装文档,你在安装时用一个集成标识来连接智能体;文档以这种方式列出了几个智能体,包括 Claude Code 和 GitHub Copilot,并链接到其自己的文档,说明如何连接其他智能体。在假定某个具体工具是否受支持之前,请查看 Spec Kit 的最新文档,获取完整且最新的列表。
本指南与 GitHub 有关联吗?
没有。这是一份独立的教育性指南,并非由 GitHub 发布或背书。Spec Kit 和 GitHub 是 GitHub 自己的项目和商标,此处提及只是为了准确地描述它们。
规格和一条更长的提示有什么区别?
更长的提示仍然只是一条描述任务的消息。规格是一份结构化的说明,包含三个具体部分:它做什么、给谁用、验收标准,目的是被阅读、被确认、被复用,而不是只输入一次就被遗忘。
「验收标准」具体指什么?
证明构建已完成的可测试条件:你要检查什么,每项检查的预期结果是什么,以及什么情况算失败。没有它们,就没有一个公认的办法来判断智能体是真的完成了任务,还是只是停下来了。
要获得这个习惯的好处,必须安装 Spec Kit 吗?
不必。把同样的三部分规格作为第一条消息输入给任何编程智能体,无论是 Claude Code、Codex、Copilot、Cursor 还是其他,不用安装任何东西就能获得大部分好处。Spec Kit 是为经常这样做而设的可重复结构,而不是做这件事的前提条件。
Spec Kit 可以免费使用吗?
可以。据其自身仓库说明,它是以 MIT 许可证发布的开源项目,并通过它自己的免费命令行工具安装。
Spec Kit 的撰写规格命令实际会生成什么?
据项目自己的文档,它生成规格文档本身,也就是本指南通篇所描述的那份平实的说明,并作为可复用的文件保存在你的项目中,而不是每次都重新输入到对话里。