上周排查一个线上接口问题时我发现团队里同时存在三份描述同一个登录接口的文档产品经理的需求描述、后端开发手写的接口说明、以及测试用例里的预期行为。三份文档在返回码上完全不一致。那一刻我突然意识到问题不在于谁写错了而在于我们一直缺少一种可以同时被人和机器读懂的中间产物。后来同事给我看了一个叫 GitHub Spec Kit 的工具他的做法很简单把自然语言的 Prompt 直接转换成可执行规格比如 OpenAPI、JSON Schema、AsyncAPI。这里的“可执行”不是形容词而是指这些规格文件能直接喂给 Mock 服务、代码生成器、契约测试框架让需求描述从“人读完后各自理解”变成“机器能直接消费”的契约。这篇文章是我自己从零开始用 Spec Kit 的一手记录。无论你是后端开发、全栈工程师、技术产品经理还是正在尝试把 LLM 引入研发流程的人应该都有参考价值。我会从“为什么需要这种转换”讲起然后拆解它的工作方式、安装步骤、完整案例、Prompt 调优技巧最后聊一下它的边界和风险。内容偏实操看完你就能在自己的项目里先跑通一个最小样例。1. 为什么需要把 Prompt 变成可执行规格1.1 需求描述到系统设计之间的鸿沟很多团队用 Copilot 或 ChatGPT 生成代码但生成质量参差不齐。我不认为这是模型能力不够更大的问题是喂给模型的描述根本没有落到契约层面。自然语言充满了默认值、上下文依赖和歧义。“用户登录”这四个字产品经理想的是输入用户名密码进系统后端想的是校验账号状态并签发 token测试想的是各种异常分支的返回结果。如果你直接把一句“用户登录”丢给模型生成接口它能写出一大堆代码但字段名、错误码、边界条件大概率是模型自己脑补的和你团队的真实约定对不上。可执行规格就是用来消除这种歧义的中间层。它把“做什么”翻译成机器能理解的“提供什么契约”。比如 OpenAPI 明确了路径、参数、请求体、响应码、字段类型、必填项这些都是无歧义的。Spec Kit 的思路就是先让大模型生成这一层契约再由现有工具链去生成代码、测试和文档而不是让模型直接写业务代码。1.2 可执行规格到底“可执行”在哪里规格这个词听起来像文档但它和传统文档有本质区别。一份 OpenAPI 或 JSON Schema 可以被工具直接执行至少体现在三个场景生成 Mock Server前端可以立刻拿到一个结构正确的模拟接口不用等后端开发完成。生成客户端 SDK契约确定后自动生成 TypeScript/Java/Go 的强类型调用代码。做契约测试验证真实的线上服务是否满足这份规格防止接口悄悄被改坏。所以当 Spec Kit 输出一份 OpenAPI 文件后它不是一个给评审看的示意图而是项目里的一等公民参与构建、测试和部署流程。这也是它和直接用 ChatGPT 写一段接口说明最大的差别一个只是文字另一个是能跑起来的约束。1.3 Spec Kit 在这个链路里的位置Spec Kit 通常以 CLI 工具的形式存在读取你写好的 Prompt 文件调用配置好的模型服务经过内部针对规格生成的指令模板最终输出 YAML 或 JSON 规格文件。它的定位像是“需求到契约”的转换器。你可以在一个目录里组织大量 Prompt 文件比如按业务模块分开每个文件描述一个独立场景。Spec Kit 会把它们批量处理成规格文件再交给成熟的工具生态。它不是要替代 Postman、Apifox 或任何 API 管理平台而是解决这些平台第一步的数据来源问题——规格文件从哪里来。2. Spec Kit 的组成与工作原理2.1 输入层Prompt 文件怎么组织在实际使用中我会把需求拆成独立文件比如api/login.prompt.md然后在文件开头加上一段 YAML Front Matter用来声明类型和版本。下面是我常用的一个模板--- name: 用户登录 type: openapi version: 1.0.0 --- 当用户发起登录请求时请求体包含用户名和密码。 - 用户名是字符串长度 5-32 位 - 密码是字符串长度 8-64 位 成功后返回 200包含 access_token 和 refresh_token。 如果用户名不存在或密码错误返回 401 和 errorCode 字段。这种组织方式的优势很明显它本身就是一份可读的需求文档业务方和开发能直接看懂同时又能被命令行工具消费。相比在网页对话框里输入 Prompt文件形式更适合版本管理方便做 diff也方便团队 review。2.2 语义解析从自然语言到结构化中间表示Spec Kit 内部的工作大致分三步。第一步用大模型把自然语言段落拆成名词、动词和约束条件。比如“用户名是字符串长度 5-32 位”会被理解成一个字段定义“登录成功返回 token”会被识别为成功响应。第二步把拆出来的元素映射到 OpenAPI/JSON Schema 的对应位置。这个映射过程需要模板和提示词配合因为大多数语言模型并不会天然知道minLength应该放在properties下面。Spec Kit 会在后台注入一套针对规格生成的系统提示词把模型的输出框在规范结构内。第三步用规则引擎检查遗漏。比如某个字段出现在响应里但在请求体中没有定义或者某个响应码被提到但缺少 description。这类检查不需要再次调用模型是纯静态规则。合理设计这些规则往往比依赖模型自觉更可靠。2.3 规格生成器与校验器输出规格之后Spec Kit 还会做两轮校验。语法校验相对简单解析 YAML/JSON 格式是否合法有没有拼写错误。语义校验则包括是否有重复路径、参数类型是否一致、引用的$ref是否存在、路径中的枚举值是否在 schema 中定义过。这一步很关键因为模型生成的内容表面漂亮但经常会在细节上踩到 OpenAPI 规范的边界。我建议你拿到产物后至少再跑一次独立的 lint 工具交叉验证比如redocly/cli或spectral。不要把 Spec Kit 自带的校验当作唯一标准工具链的校验视野往往比较窄独立跑一遍能发现很多隐藏问题。2.4 与现有工具链的配合Spec Kit 不替代已有的 API 管理平台但可以和大量工具联动。我目前常用的组合是场景工具作用Mock 服务Prism / Mockoon根据规格启动本地模拟接口客户端代码生成OpenAPI Generator自动生成多语言 SDK接口文档Redoc / Swagger UI直接渲染成可交互文档契约测试Schemathesis / Dredd自动生成请求并校验响应静态检查Spectral对规格做规则约束这也是我把它叫“套件”而不是“生成器”的原因它提供一整套从需求到契约的转换方案但真正在执行层发挥价值的其实是背后已经成熟的生态。Spec Kit 做的是把最难的“需求转契约”这一步打通。3. 本地环境安装与第一份规格生成3.1 环境准备与安装我以目前社区常见的 Node.js 工具链为例。你需要 Node.js 18 以上版本并且装了 npm 或 pnpm。全局安装命令是npm install -g spec-kit/cli安装完成后新建一个项目目录并初始化mkdir my-api cd my-api spec-kit init初始化命令会在当前目录生成几个基础文件最重要的大概长这样{ model: { provider: openai-compatible, baseUrl: https://api.example.com/v1, apiKeyEnv: LLM_API_KEY, model: gpt-4o-mini }, input: prompts/**/*.prompt.md, output: specs, validation: strict }注意apiKeyEnv字段不从配置文件读密钥而是从环境变量里读取避免把密钥提交到 git。你在.env或 shell profile 里设置LLM_API_KEY即可。这里也顺带说一句别把真实生产环境或带敏感信息的密钥放到配置文件里这个习惯能避免很多事故。3.2 初始化项目并编写第一个 Prompt初始化完成后按照默认目录结构在prompts目录下新建login.prompt.md内容就是 2.1 里那个示例。写 Prompt 的时候建议一个文件只描述一个业务动作不要一口气塞好几个接口。你可以把POST /login、POST /refresh分别放到不同文件里这样模型处理起来上下文更清晰后续增量修改也更方便。3.3 执行生成与产物解读运行生成命令spec-kit generate prompts/login.prompt.md正常的情况下它会调用你配置的模型服务并在输出目录生成specs/openapi.yaml。打开文件你会看到一个完整的 OpenAPI 3.1 规格大致如下openapi: 3.1.0 info: title: 用户登录 version: 1.0.0 paths: /login: post: operationId: login requestBody: required: true content: application/json: schema: type: object required: - username - password properties: username: type: string minLength: 5 maxLength: 32 password: type: string minLength: 8 maxLength: 64 responses: 200: description: 登录成功 content: application/json: schema: type: object properties: access_token: type: string refresh_token: type: string 401: description: 用户名不存在或密码错误 content: application/json: schema: type: object properties: errorCode: type: string第一次看到这个产物的时候我特意检查了字段约束有没有跟 Prompt 里的描述完全对应。结果是我在 Prompt 里明确写的约束基本都被正确翻译了我没写的内容模型也没额外脑补太多。这说明 Spec Kit 的默认策略更倾向于忠实呈现而不是自由发挥。3.4 将生成结果跑通mock 验证有了 OpenAPI 文件之后最直观的验证方式就是用 Prism 启动一个 Mock 服务npx stoplight/prism-cli mock specs/openapi.yaml启动后它监听在http://127.0.0.1:4010我们直接发一个登录请求curl -X POST http://127.0.0.1:4010/login \ -H Content-Type: application/json \ -d {username:alice,password:12345678}返回的结果结构会和规格定义保持一致包含access_token和refresh_token。如果生成结果缺失字段Mock 服务会立刻返回不符合预期的响应问题在开发早期就能暴露。这一步是“可执行”最直观的证明——规格不是拿来收藏的是拿来跑的。4. 实战案例用户登录接口的完整转化路径4.1 初始 Prompt 设计为了演示真实情况我这里故意把第一版 Prompt 写得模糊一些模拟大多数团队需求文档的真实状态--- name: 用户登录 type: openapi version: 1.0.0 --- 用户登录接口用户提供用户名和密码。登录成功返回 token失败返回错误信息。这个描述在真实业务里很典型——信息量不够留了太多空白。我们看看 Spec Kit 会生成什么。4.2 第一次生成结果及问题第一版生成结果确实能跑但问题不少没有定义 token 的具体类型只写了一个token: string没有区分 access_token 和 refresh_token。401 响应里只有 description缺少明确的错误码字段。没有提到用户名和密码的字段约束所以生成的 schema 里没有任何长度限制。整个接口没有定义 tags导致生成的文档在分类上很乱。这些其实不是 Spec Kit 的缺陷而是模型在忠实反映输入。你只给了模糊描述它就还原一份模糊规格。4.3 调整 Prompt 后的二次生成发现问题后我在 Prompt 里补充了显式约束--- name: 用户登录 type: openapi version: 1.0.1 --- 用户发起登录请求时请求体为 JSON 对象包含 username 和 password 两个必填字段。 username 是字符串长度 5-32 位password 是字符串长度 8-64 位。 登录成功后返回 200响应体包含 - access_token: string表示访问令牌 - refresh_token: string表示刷新令牌 - token_type: string取值固定为 Bearer 如果用户名不存在或密码错误返回 401响应体包含 errorCode 和 message 两个字符串字段。 其中 errorCode 在用户不存在时取值 USER_NOT_FOUND密码错误时取值 PASSWORD_INCORRECT。这次生成的结果明显更完整任何一个字段、响应码、枚举值都是根据 Prompt 直接映射出来的。用同一份 Prompt团队里的每个人看到的结果都一致。这份规格已经可以直接作为前后端联调的基准。4.4 人工评审要点二次生成的结果并不代表可以直接上生产。我在评审这个文件时会额外检查几点是否覆盖了 429、500 这类通用错误响应这通常不会写在业务 Prompt 里。是否定义了服务的 Base URL 和鉴权方式OpenAPI 里缺失这些会影响 SDK 生成。是否对敏感字段做了脱敏说明比如是否返回密码摘要这在规格层面没人会管必须人工确认。人工评审不是走流程而是要站在契约角度检查边界。Spec Kit 生成的是从需求语义到规范结构的映射它不会替你决定业务规则最终评审权必须留给熟悉业务的人。5. Prompt 输入的写法与优化技巧5.1 结构化描述的三种有效格式如果你希望 Spec Kit 稳定输出高质量结果我推荐在 Prompt 里使用三种结构化格式第一种是列表式适合枚举字段和约束。每个字段占一行写清楚类型、长度、必填性。这种方法最通用模型很容易解析。第二种是 Gherkin 式用 Given / When / Then 组织行为描述。适合一个接口存在多个分支场景的情况尤其适合生成 4xx/5xx 响应。比如Given 用户名不存在 When 用户发起登录请求 Then 返回 401errorCode 为 USER_NOT_FOUND第三种是代码块式在 Prompt 中直接给出一段 JSON 请求和响应示例。模型对这种示例特别敏感通常能推断出准确的字段结构。5.2 准确指定类型、约束与边界我的经验是尽量用具体数字和枚举避免形容词。“密码比较长”这种描述没有任何价值模型只能随机猜一个长度限制。应该写成“密码长度 8-64 位必须包含至少一个字母和一个数字”。同理“返回用户信息”应该写成“返回用户 id、nickname、avatar_url 三个字段其中 nickname 允许为空”。你给出的约束越接近最终 schema 的语义生成结果就越准。还有一点别怕 Prompt 变长。Spec Kit 处理的不是即时聊天长一点、结构化一点的描述通常效果更好。但要注意控制在一个合理范围内我一般一个 Prompt 文件不超过 800 字如果超过就拆文件。5.3 常见失败模式与对策我踩过不少坑总结几个最典型的失败模式Over-generation模型添加了不存在于 Prompt 的字段比如凭空多加一个expires_in。对策是在 Prompt 末尾写一句“只使用上面明确提到的字段”。代词歧义“用户发起请求后它会返回 token”中的“它”指代不清。对策是每条约束都写清主语避免用代词。术语混用中文里“用户”“客户”“账户”经常混着用。对策是在 Prompt 开头定义一个 glossary 小节明确每个词的含义。枚举遗漏只说了错误时返回 errorCode但没说有哪些取值。对策是尽可能列出所有已知枚举值。5.4 与模型上下文长度的相处之道大模型的上下文窗口再大也是有边界的。当 Prompt 文件太长模型在生成后半部分时会逐渐忘记前面的约束导致输出前后不一致。我常用的办法是保持单一意图。每个 Prompt 文件只描述一个接口或一组高度相关的接口。如果确实需要批量生成比如把整个订单模块都生成出来就用 Spec Kit 的目录模式批量处理而不是把几十个接口塞进同一个文件。每个文件内部也按“概要 字段清单 响应码清单”的顺序组织前文约束尽量在开头集中出现而不是散落在长文本各个角落。6. 使用 Spec Kit 时的边界与隐私风险6.1 三类它处理不了的业务逻辑用了一段时间后我明确了 Spec Kit 的边界。以下几类逻辑它处理不了或者说至少不该指望它自动处理第一类是跨系统的时序规则。比如“用户先扣款再发积分扣款失败则回滚”这个流程涉及多个服务的事务一致性单纯靠一段 Prompt 描述根本不够。你需要用状态机、时序图或伪代码来定义Spec Kit 只擅长把你给出的接口契约提取出来。第二类是复杂的权限模型。像“管理员可以删除他人评论普通用户只能删除自己的”这类规则虽然在 Prompt 中能描述但最终实现往往依赖中间件、权限框架、甚至数据库行级策略。规格里只能反映到接口层面比如表明某个操作需要 admin 角色但没法替你写出权限判断逻辑。第三类是业务状态机。比如订单从“待支付”到“已支付”再到“已发货”每个状态之间有哪些合法迁移这不是几个字段约束能表达的。我建议这类规则单独用状态图管理不要硬塞进规格文件。6.2 不要让敏感信息进入 Prompt这一点务必重视。Spec Kit 生成规格时会把你的 Prompt 发送给配置的模型服务。如果 Prompt 里出现了生产环境的真实手机号、用户 ID、内部数据库字段名、密钥或非公开 IP这相当于把这些信息交给外部服务处理。我见过有同事为了测试方便在 Prompt 里直接写了一个真实的手机号。这个习惯非常危险。建议所有示例数据一律用虚拟内容比如13800000000、test_user_001。如果团队有严格的数据合规要求考虑接入私有化部署的模型服务并仔细阅读服务商的隐私条款和数据保留策略。6.3 人工 review 不可跳过Spec Kit 生成速度快容易给人一种“不需要检查”的错觉。但我的经验是它生成的内容越流畅越要警惕隐含错误。模型会在语法上几乎完美但在业务语义上可能完全站不住脚。我们团队把 Spec Kit 生成的规格文件纳入 MR/PR 流程至少让一个熟悉业务的人 review并且要求改动规格必须同时改动对应的 Prompt 源文件。这样既保证可追溯也防止规格变成“一次性生成后无人维护”的死文档。7. 后续扩展把 Spec Kit 接入 CI7.1 定时校验规格漂移项目跑一段时间后代码和规格之间会产生漂移。接口在代码里改了参数规格文件却还停留在最初版本。只要规格文件没有参与到 CI它就迟早会变成摆设。我的做法是在 CI 里加一个独立 job定时或每次合并前重新跑一次spec-kit generate然后用git diff检查是否有文件变化。如果存在非预期的变化说明需求描述或规格文件没有同步直接让流水线失败。还可以配合 Spectral 规则集强制字段命名风格、禁止未定义的响应码、要求所有接口必须带 tags。这些规则比单个工程师的自觉可靠得多。7.2 与代码生成器串联当规格文件稳定后它可以成为代码生成的唯一来源。在 CI 中完成后端代码生成让接口骨架始终跟随规格更新。前端也可以从同一份规格生成 TypeScript SDK保证前后端对字段的理解永远一致。我记得有一次后端把登录接口的响应结构调整了一下但规格文件没改。如果当时没有契约测试前端直到联调才会发现字段不对。把 Spec Kit 生成的规格接入代码生成和契约测试后这类问题基本能在提交阶段被拦截下来。7.3 团队协作时的文档规范最后是协作层面。如果只有你一个人用 Spec Kit那它只是一个效率工具。如果想让团队都用起来需要约定一套文档规范。我目前采用的目录结构是prompts/ auth/ login.prompt.md refresh.prompt.md users/ create_user.prompt.md get_user.prompt.md orders/ create_order.prompt.md同时在 README 里写清楚工作流改需求先改 Prompt再重新生成规格然后提交代码。这个规范听起来简单但真正执行起来是团队工作方式的转变。我个人的体会是引入 Spec Kit 的头两周最容易出现的问题不是生成结果差而是各方对“规格变更”的提交节奏跟不上。产品还在调整需求文案后端已经把规格改了前端 SDK 又是另一套版本。后来我们把“规格变更”当作一个独立任务看待每次需求变动必须同时更新 Prompt 和规格文件并标记版本号。这个习惯一旦建立起来后面反而省了很多扯皮时间。如果你也在为接口需求的一致性头疼建议先从一个小模块试起不要一上来就重构所有文档。拿登录接口跑一遍让团队感受一下“Prompt 改一行规格和 Mock 服务同步变化”的流程再决定要不要全面铺开。工具本身不复杂真正需要磨合的是大家对契约的敬畏程度。