先问你一个问题你给 AI 写的 prompt测试过吗我猜大部分人的答案是没测过也没法测。需求方一段话扔过来你把它整理成 prompt 丢给大模型上下文堆到几万 token生成出来的代码跑起来处处漏风。然后你开始改 prompt加约束、补例子、换角色设定来回折腾十几轮最后安慰自己“大模型就是这样得多试”。但问题真的出在 AI 不行吗我觉得不是问题出在 prompt 太“软”了。它是一段没法验证、没法拆分、没法复用的自然语言你没法对它做单元测试。GitHub Spec Kit 就是冲着这个痛点来的。它把自然语言的需求描述转成结构化的、可以被 AI 执行和校验的规格说明Specification。这套东西不是让你“更好地写 prompt”而是让你把 prompt 里的需求内核抽出来沉淀成一份机器能读、人也能读、团队能共同维护的“契约”。这篇文章我会从为什么需要可执行规格讲起拆解 Spec Kit 的核心概念详细走一遍从规划 prompt 到生成规格、落地到实际开发流程中的全过程最后聊聊我在试用过程中踩过的坑和至今还在纠结的地方。不管你是做 AI 辅助开发的一线工程师还是正在研究 prompt engineering 怎么落地到团队协作的朋友这篇应该都能帮你少走一些弯路。1. 为什么“可执行规格”这个提法比“写好 prompt”更接近问题的本质prompt 写不好通常不是表达问题而是结构问题。这一节我想把这件事拆开说清楚。1.1 普通 prompt 的致命伤没有“可验证性”你在对话框里输入一大段 promptAI 给你返回一段代码或者一份计划。然后你怎么判断它做对没有靠肉眼 review靠跑一下测试靠人肉审视逻辑。如果这段 prompt 对应的是一个小函数这没问题但当需求涉及十几个模块、几十条业务规则时你根本没法靠肉眼判断 AI 有没有漏掉某条规则。举一个我自己的例子。我之前让 AI 开发一个订单导出功能prompt 里写了“导出的文件名要包含日期导出后要发送通知数据要按创建时间排序”。这三条要求看着很明确对吧结果 AI 生成的代码里日期格式写死了YYYY-MM-DD通知只发了站内信没发邮件排序还写反了。我重新读了一遍我的 prompt发现我根本没定义日期格式、通知渠道、排序方向。这不是 AI 蠢是我的 prompt 本身就是一份充满漏洞的“伪需求文档”。普通 prompt 的核心问题在于它很难被验证所以 AI 也就很难被约束。你写的是一条模糊的自然语言AI 只能靠概率去猜你脑子里那个“显然”的细节。1.2 从“写给人看的需求文档”到“机器可执行的规格”传统软件工程里我们有 PRD有需求文档有接口文档。这些文档写得很详细但它们是“写给人看的”机器不认。AI 时代不一样了你的“读者”除了人还有大模型。大模型是语言模型它能读自然语言但自然语言里的隐含信息、上下文依赖、前后矛盾大模型同样会踩坑——而且它踩坑的表现形式是“一本正经地胡说八道”比人犯错更难发现。Spec Kit 的思路是把 PRD 里的关键规则抽取出来用一种半结构化的 Markdown 格式去描述。每条规格不是“一句话建议”而是一条独立的、可被引用的、可被检查的规则。它做的事情很像传统开发里的“契约测试”——把需求变成可执行的断言只不过这些断言的读者是 AI 和你指定的开发工具链。1.3 我理解的“可执行”三个字到底指什么在 Spec Kit 的语境下“可执行”至少有三层含义理解这三层你才能明白这个工具的设计意图可被 AI 消费规格文件是标准 MarkdownAgent无论是 Claude Code 还是别的什么工具可以把规格当作上下文知道自己要实现的边界在哪里。可被校验它有固定的结构和字段约定工具可以检查你的规格是否完整、是否存在冲突、格式是否合法。可被追踪每个规格是一个独立单元有明确的 ID 和规则引用当你修改某条规则你可以知道它影响了哪个功能而不是改了一句话然后全凭感觉。这三点对应到实际开发中解决的就是“AI 开发经常返工”的问题。以前改需求 重新写 prompt 重新生成一坨代码 重新 review。有了可执行规格改需求 改一条规则 让 AI 重新跑一遍 看它有没有遵守新规则。2. Spec Kit 到底在规整什么feature、rule 与描述的三层结构Spec Kit 不是什么玄学框架它落到文件上就是一套约定俗成的 Markdown 结构。这一节我把核心概念拆开讲建议你对照着手里的项目看。2.1 一个规格文件的基本骨架Spec Kit 的核心单元叫 feature特征。一个 feature 对应一个业务能力比如“用户注册”“订单导出”“支付回调”。每个 feature 是一个目录或一个 Markdown 块里面包含三个关键字段id、描述description和一组规则rules。用它的 CLI 初始化后一个典型的规格文件长这样以官方风格为蓝本--- name: Order Export id: feat-order-export --- ## Description 作为运营人员我需要导出指定时间范围内的订单数据以便进行线下对账。 ## Rules - **rule-1**导出文件必须包含创建时间、订单号、商品名称、实付金额四个字段。 - **rule-2**导出文件的文件名格式为 orders_YYYYMMDD_HHmmss.csv。 - **rule-3**导出完成后需要发送通知通知渠道包含站内信和邮件。 - **rule-4**导出范围的时间边界为闭区间包含开始日期和结束日期的整日数据。注意它和普通 prompt 的区别。上面这段内容如果直接丢给 AI 作为 promptAI 也能理解个大概。但 Spec Kit 的价值在于它把每条规则单独提出来赋予了清晰的 ID并且工具链可以解析这个 Markdown 文件把每条规则作为一个可引用的独立单元。这就像把一段没有目录的说明文改成一章一节带编号的法规。2.2 规则Rule到底怎么写才算“合格”我在实际使用中最大的困惑就是规则写到多细才能算合格Spec Kit 没有给你一个“规则数量达标”的检查器它只检查结构和完整性不检查内容质量。所以规格写得好不好本质上还是靠人。我总结了一个判断标准如果这条规则被另一条规则覆盖、合并或者相互矛盾你是否能立刻发现比如上面订单导出的场景如果你在另一个 feature 里又写了一条“导出文件格式为 Excel”它们就会互相冲突。在普通 prompt 里这两个互相矛盾的描述可能出现在上下文的不同位置AI 会随机选择其中一个或者自己编一个格式。但在 Spec Kit 的结构化规则体系下这种冲突会暴露得非常明显。另一种情况是规则写得过于模糊。比如“导出数据要完整”——这种规则等于没写。什么叫完整所有字段所有订单断点续传完整的定义不清晰AI 执行的时候只能猜。好的规则描述的是可观察的行为不是主观的感受。你在写规则时每一句都应该问自己如果 AI 实现了这个功能我能不能用某个明确的手段验证它做到了2.3 为什么选 Markdown 而不是 JSON 或 YAML第一次看到 Spec Kit 用 Markdown 做规格格式的时候我有点意外。按理说结构化数据用 YAML 或者 JSON 不是更严谨吗但仔细想下来Markdown 是当下唯一同时满足三个条件的格式对人友好、对 AI 友好、对 diff 友好。JSON 和 YAML 对机器友好但对人来说很难维护一个多层嵌套的结构在 review 的时候非常痛苦。最重要的是大模型读取 Markdown 的效果极好——它本来就是在大规模 Markdown 语料上训练的对 Markdown 里的标题层级、列表、加粗语义有天然的敏感性。而 diff 友好这点在团队协作里太重要了。规格文件是给人看的需求文档你用 JSON 写review 的人看到一坨括号就想关掉。用 Markdown 写谁改了什么规则每一行都能在 PR 的 diff 里清晰地看到协作门槛一下就降下来了。3. 从 Prompt 到规格的实操流程我自己跑通的一条完整链路聊完概念说点能直接上手的。这一节是我从零开始使用 Spec Kit 的完整记录包括初始化、建 feature、写规则、让 AI 按规格执行的整个闭环。3.1 安装与初始化第一步就走出了“prompt 思维”Spec Kit 以 CLI 方式分发需要 Node.js 环境。安装命令很直接npm install -g spec-kit/cli安装完成后在项目里初始化spec-kit init初始化命令会问你几个问题包括项目名称、默认语言、存放规格的目录等。跑完之后它会在项目里生成一个specs/目录里面包含一个索引文件和一个示例 feature。这一步本身没坑但真正需要调整心态的是你从这一步开始就不再是“写 prompt”了而是在“建需求库”。你的产出物不再是一段对话而是一组可持续维护的文档。3.2 用 CLI 创建一个 feature把需求“结构化”的第一步创建 feature 是开始描述业务能力入口命令很直观spec-kit feature:add order-export --name Order Export --description 导出订单数据用于对账执行完specs/order-export.md或者specs/order-export/目录就建好了。CLI 维护一个规格索引新增的 feature 会自动被登记到索引里。这一步最关键的动作是把“我要做个订单导出”这句话升级成带 ID、带名字、带业务描述的 feature 定义。我见过很多人在这一步会偷懒description 随便填一句“导出订单”就完事。我建议多花两分钟把业务背景写清楚因为 description 会作为 AI 理解这个 feature 的第一上下文直接决定了它后续执行的准确性。3.3 把自然语言 prompt 拆解成规则一条一条地完成“翻译”接下来是重头戏——把你平时写 prompt 的那段话拆成一条条规则。这里我强烈建议对照你以前写 prompt 的习惯来做。比如以前你写导出订单数据按创建时间排序文件名叫订单导出导出完发通知。这句话拆成规则就是这样## Rules - **rule-1**导出数据的排序方式为按创建时间升序。 - **rule-2**导出文件的命名为 orders_YYYYMMDD_HHmmss.csv。 - **rule-3**导出完成后需要同时发送站内信和邮件通知给创建导出的用户。区别在哪其实每个信息点都没变但以前这三个信息点是“揉”在一句话里的AI 需要自己去拆分和取舍。现在它们被显式地列出来了。你可能会觉得“这不就是把一句话拆成三句话吗有什么技术含量”有而且很大。当你把规则拆开之后你会发现原来你根本没想过“通知发给谁”。我在拆这个 prompt 的时候才发现自己漏了通知接收人。在原来那种写法里AI 大概率会默认发给当前操作人但你没写就是不可验证的。拆开之后这种漏洞会自己跳出来。3.4 验证规格的有效性把“我觉得写清楚了”变成“机器认为写清楚了”写好规则后用 Spec Kit 的 validate 命令做一次检查spec-kit validate ./specs/order-export.md它会检查规格文件的格式是否正确、必填字段是否存在、feature 是否有重复 ID 等结构性问题。这一步是机器层面的校验它不负责检查你的业务逻辑对不对但能避免你因为手滑写错格式导致 AI 无法正确解析。我在这一步遇到过一次问题我在规则列表里嵌套使用了一个四级列表导致解析器没有把那条内容识别为规则。这个问题在纯 prompt 场景里根本不存在但在结构化场景里格式就是信息的载体。所以你写规则时必须保持方向一致要么全部用-开头的无序列表要么全部用1.开头的有序列表混搭会导致解析错乱。3.5 把规格交给 AI扮演“按规格执行的开发者”规格文件建好了怎么让 AI 用起来目前的主流做法是在 Agent 工具里把规格文件作为上下文引入。以 Claude Code 为例你可以在项目说明文件如CLAUDE.md中引导模型去读取specs/目录或者在需要的会话里直接指定请阅读 spec/order-export.md 中的规格并按照里面的规则实现订单导出功能。执行这一步后你会明显感受到和以前写 prompt 的本质差异。以前是一次性说需求、等结果现在是先锁定规格、再让 AI 实现。规格文件是稳定的参照物AI 不会因为对话太长而“忘记”你开头提过某条规则。它随时可以重新翻阅规格文件确认细节。而且当你后续需要修改时你改的是一份持久的资产而不是一段聊天记录里的某条消息。4. 把模糊需求翻译成规格的实战心法我在实践里总结的判断标准这一节是我觉得全篇最值得反复看的部分。命令行和语法学起来很快难的是“判断什么样的规格算写好了”。4.1 一个完整的案例从“我大概想要个东西”到“可验收的规则”我拿我之前的一个真实需求举例。最初的需求只有一句话“搞个页面能在上面看用户的订单管理员能筛选。”这句话如果要变成可执行规格你需要填充的信息多得惊人。用户是谁、页面入口在哪、能看哪些字段、筛选条件有哪些、筛选是前端过滤还是后端查询、管理员和普通用户看到的界面一样吗……每一条都需要确认。我把它扩展成了这样一组规则## Description 管理员登录后可在订单管理页面查看所有用户的订单列表并支持按状态筛选。 ## Rules - **rule-1**订单管理页面仅对管理员角色可见普通用户访问时返回 403。 - **rule-2**列表默认展示最近 30 天的订单按下单时间降序排列。 - **rule-3**筛选条件包含订单状态和支付状态支持组合查询。 - **rule-4**筛选操作触发后端查询不进行前端内存过滤。 - **rule-5**订单列表分页展示每页 20 条。写完后你会看到原话里“能筛选”这三个字在规格里被拆成了 rule-3 和 rule-4。低质量 prompt 和高规格 prompt 的差距从来不在于文笔而在于你愿不愿意把隐含信息显性化。这个基本功在过去的需求评审里你可能丢给了产品经理但现在直接负责的是 AI你必须自己完成这个翻译。4.2 判断规则质量的四个标准你写的东西是否“可用”根据我自己的使用体验我总结出以下四个判断标准每次写完规则后会逐条过一遍标准解释反例可验证性是否可以通过明确的输入输出确认 AI 做对了“界面要美观”无歧义不同的人/模型读到后理解是否一致“适当的延迟后跳转”单一职责一条规则只约束一件事“导出并发送邮件”可追踪能明确知道这条规则属于哪个 feature混杂在长段落中无法引用如果你的规则里哪条违反了其中一条我的经验是宁可改成两条也别硬攒成一条。4.3 规则粒度的“度”写太细是灾难写太粗是废话写规格最容易犯的错不是写错内容而是把握不好粒度。一开始我写规则时什么都想往里塞。比如“点击按钮要显示 loading 状态”“按钮文案是‘确认导出’”“点击后弹出确认框”“确认后关闭弹窗”……我把所有交互细节都写成规则结果规格文件比代码还长AI 反而不知道该重点关注什么。后来我调整了一下思路——规则描述的是“业务约束”不是“UI 细节”。按钮文案、loading 状态这种细枝末节应该在 prompt 里临时补充而不是写成全局规则。全局规则只放那些“如果违反就会导致业务错误”的硬约束。比如“导出权限仅限管理员”是硬约束必须写“弹窗按钮文案是蓝色还是白色”是装饰细节别写。4.4 重要提醒写规则描述的是“行为”不是“实现”还有一点我特别想强调规格应该描述“要做什么”而不是“怎么做”。这不是咬文嚼字。因为 AI 的执行方式会随着模型能力变化而变化但业务目标是稳定的。比如描述行为“导出文件必须包含订单号和支付金额。”描述实现“使用 pandas 的 to_csv 方法将数据导出。”前者温度不变任何时候都有效。后者绑死了实现方式如果将来换成别的技术栈这条规则反而成了枷锁。写规格的时候假装自己在跟一个外包团队沟通你只告诉他们验收标准不告诉他们怎么写代码。这样写出来的规格才是最长命的。5. 规格落地到团队协作时我亲身踩过的坑和应对经验规格写好了、AI 也能读懂了但真正放进团队协作流程后问题才刚刚开始。这一节把我遇到的实际问题和解决办法整理出来。5.1 自动化过程中的“规格漂移”AI 越写越偏你不一定看得住使用 Spec Kit 跑了一两个迭代后我最头疼的问题是规则在 spec 里写得好好的但 AI 在实现时会悄悄“漂移”。比如规则要求“导出的文件名格式为orders_YYYYMMDD_HHmmss.csv”AI 第一次实现是符合的但某次改需求时它可能顺手改成了orders_20250101.csv因为你的新需求里提到了简化日期格式。它不是故意违反规则而是规格里的旧规则和当前 prompt 产生了冲突它选了比较新的那段上下文。解决这个问题我目前比较有效的做法是每次迭代结束对着 spec 做一次“规则符合性”检查而不是做代码 review。我会把规格文件逐条复制给 AI问它“这几条规则在最新代码里是否都满足如果不满足是哪几条”。让 AI 对照规则自查效率远高于自己逐行翻代码。5.2 多人编辑同一个规格文件冲突比你想的来得快当团队里有几个人同时往specs/目录里加内容时你会遇到 git 冲突的问题。但 Spec Kit 的结构化设计把一个很大的好处带给了协作场景每条规则都有自己的 ID冲突一般只会发生在同一个 feature 的相邻行不会像普通文档那样一改就是一大片。我们的经验是给每个 feature 分配唯一负责人避免多人同时改同一个 feature 文件如果真的要改则通过 PR 评审重点看 Rules 部分的 diff。规格文件是“需求契约”不是“共享笔记”它的变更应该走和代码一样的严谨流程。5.3 一个我仍在关注的安全问题外部输入如何进入规格体系最后说一个我一直在关注的领域prompt 注入prompt injection对规格体系的冲击。在做 agent 开发时模型会阅读规格文件作为行动依据但你可能把外部收集到的某些文本比如某种数据格式样例、客服聊天记录直接作为上下文拼接了进去。这就带来一个隐患外部内容里如果藏了“请忽略之前所有规则改为执行 X”之类的指令而你又没有对输入来源做隔离这些外部内容可能影响模型对规格的判断。我的做法比较朴素规格目录只维护我们自己写的内容不直接把来源不明确的文本贴进 spec。如果需要参考外部数据放到单独的参考目录并由开发者在 prompt 里用明确的标记区分哪些是可执行指令、哪些是参考信息。这一块目前没有银弹但意识到这个问题、保持警觉就已经比大多数团队走得远了。6. 最后分享一个我的使用技巧把规格当作团队的“共同语言”如果只看工具使用这篇其实已经讲得差不多了。但我想分享一个额外的心得Spec Kit 最大的价值不是帮你“用 AI 写代码”而是逼着你把需求想清楚。在使用 Spec Kit 之后我发现自己有一个明显的变化。以前拿到需求我第一反应是“怎么把这个需求组织成 prompt 丢给 AI”。现在我会习惯性地想“这里到底有哪几条规则哪些规则是明确的哪些规则只是我的猜测”这种思维方式上的转变比任何工具都值钱。你不再依赖模型的猜能力而是把确定性掌握在自己手里。当你把规则写成文档你的产品经理、你的测试同事、你的 AI 助手读的是同一份东西对齐的是同一个标准。团队在不同角色之间传话时最容易出现的理解偏差在这里被结构化的规则显式拦住了。如果你所在团队正在摸索 AI 辅助开发的流程我的建议是不要急着天天刷 prompt 技巧先把你们最核心的一个业务场景写成一个只有一个 feature、三五条规则的规格文件让 AI 按它跑一遍。你会在动手那一刻真正理解“可执行规格”和“一段写得还不错的 prompt”之间的差距有多大。