GitHub 官方的 spec-kit：让 AI 先写规格再写代码，14 万星的方法论怎么落地

页面能打开、按钮能点击离“需求做对了”还有多远spec-kit 尝试把这段距离变成可检查的规格、计划和任务。但它最值得理解的地方也包括那句“已完成”究竟不能保证什么。01照片整理好了原图却不见了假设你让 AI 做一个本地照片整理工具“按日期分相册界面简洁一点支持删除照片。”它很快交出一个能运行的应用有相册、有缩略图也有删除按钮。你点了几下似乎都正常。直到你发现“删除照片”真的把硬盘里的原图删掉了。你原本只想把照片移出相册。再看日期它按文件修改时间归类而你想按拍摄时间。几张没有拍摄信息的照片还被悄悄归进了今天。这是一个教学假设却揭示了 AI 编程里很实际的问题代码可以顺利运行而需求理解早已发生偏差。如果这些决定从未被明确记录验收就会变成一场猜谜你猜 AI 怎么理解需求AI 猜你想要什么。GitHub 的开源项目 spec-kit提供了一种整理这些决定的方法。它采用 SDD也就是规格驱动开发先把预期行为写清楚再据此设计、拆任务和实现。截至 2026 年 10 月 30 日检索仓库展示约 14.4 万星发布页的最新版本为 v1.2.5。星数说明关注度是否适合你的项目还要看它能否减少理解偏差与返工。官方仓库版本记录02先把“删除”讲清楚再决定用什么数据库“规格”听起来很重。放到照片工具里它首先只是把含糊的词改成可以判断对错的行为。下面这些规则是本文示例中的产品选择并非 spec-kit 默认替你作出的决定原来的说法可以验收的说法按日期分组优先使用照片拍摄日期缺少信息的照片进入“日期未知”分组支持删除从相册移除照片时只删除关联记录保留原始文件本地使用照片和元数据保存在本机不向外部服务上传导入要稳定单张文件无法读取时记录失败原因并继续处理其他文件现在讨论终于有了落点。产品负责人能检查规则是否符合预期开发者能判断实现是否可行测试人员也知道该准备哪些样本。spec-kit 把后续工作分成三种主要产物spec.md用户应该得到什么行为。plan.md用什么技术方案实现这些行为。tasks.md把方案拆成哪些具体工作按什么依赖顺序执行。官方流程让这些产物依次进入实现阶段。需求有歧义时可以加入澄清编码前还可以检查文档之间是否冲突。SDD 上手指南以照片工具为例“原图不能被删除”属于规格“用本地数据库存储相册与照片的关联关系”属于方案“实现解除关联接口并补充原图仍存在的测试”才是任务。这样分开之后修改也更容易定位换数据库通常影响方案改变删除含义则必须先改规格。文档的价值体现在它能影响下一步决策。如果三份文件只是把同一句需求换三种说法流程就只增加了阅读量。03“收敛”这一步究竟在检查什么先确立项目原则再按功能推进是 spec-kit 的基本用法。所谓 constitution可以理解成项目的长期约定。例如涉及文件操作时必须保护原始数据关键行为必须有可执行的验证办法。原则变化时这份约定也需要更新。随后每个功能经过规格、计划、任务、实现和收敛检查。因此“项目级原则 功能级五步流程”比“六步收敛环”更容易理解。最值得关注的是 converge。官方定义很具体它对照规格、计划和任务检查代码发现缺口时向 tasks.md 追加工作。它自身不修改或删除代码。命令参考是否按任务实现对照规格、计划与任务检查发现缺口追加待办任务报告 Converged结合测试证据进行评审回到照片工具。假设界面已经完成但没有处理“缺少拍摄日期”的照片。一次检查可能发现这条规格未落实将它补进任务清单再交给实现阶段处理。这里有一个必须保留的边界Converged 表示这次检查没有发现未满足之处不代表软件已被证明没有问题。这是对代理检查能力的工程判断。规格可能遗漏了重要场景代理可能误读代码测试也可能没有覆盖真实使用条件。因此验收时仍要追问拿掉拍摄信息的照片实际导入过吗移除照片后检查过原始文件吗“不上云”有相应检查证据吗如果反复出现同一类缺口我建议暂停循环检查规格是否矛盾、环境是否缺失或者任务是否过大。流程描述中的“反复收敛”不应被理解为一定会自动完成的承诺。04值得关注的变化开发流程也能被复用先写需求、再做设计这件事并不新鲜。spec-kit 更有意思的变化是把这些做法做成编码代理可以执行、团队可以调整的流程。官方项目历史也把它的演进描述为从 SDD 工具包逐步发展为可扩展的流程 harness。项目历史这里的 harness可以理解成围绕 AI 的一套工作安排给它什么上下文按什么步骤推进留下哪些产物在哪里检查结果。对读者而言不必一开始就记住所有组件名。记住几个具体需求就够了你想改变什么对应机制让规格采用团队术语和格式Preset预设增加一个新的检查命令Extension扩展把多个步骤和检查自动串起来Workflow工作流给团队分发一整套配置Bundle配置包这些机制让团队有机会把有效的方法复用到下一个项目而不必每次重写一大段提示词。定制指南我的理解是这体现了一种值得关注的方向AI 编程的方法正在从个人对话技巧变成可以检查和维护的团队流程。不过配置文件里写着“必须测试”还需要真正运行的测试与执行约束来落实。模板本身不能提供质量保证。05做功能、修故障、评估点子入口可以不同spec-kit 当前提供三个第一方流程彼此独立。SDD 在核心中提供bug 和 assess 是按需安装的扩展。官方流程说明继续用照片工具来区分眼前的问题合适的入口已经决定增加日期分组功能SDD明确规格再设计和实现导入某张照片时程序崩溃bug诊断、修复、验证要不要增加跨设备同步assess调查证据再决定是否投入bug 流程特别值得借鉴的一点是把修复和验证分开。验证结果可能是 verified、partial 或 failed如果缺少复现环境应明确记录验证不完整。官方还强调即使测试套件通过没有重新验证最初的复现步骤也不能据此确认问题已解决。故障修复指南assess 则允许得出 go、needs-clarification 或 kill。比如跨设备同步可能引入账号、服务端和隐私成本如果目前没有足够用户需求暂缓投入也可以是有依据的结果。这个例子是本文的产品判断示意。官方明确说明评估通过不会自动启动实现。决定“值得做”与决定“现在开始做”之间仍有人的判断。点子评估指南06第一次试用只做一个能验收的小功能建议从“按日期展示本地照片”开始暂时不加入账号、同步、人脸识别和复杂编辑。官方列出的基础条件是 Python 3.11、uv以及一个受支持且可用的 AI 编码代理。以下以 GitHub Copilot 为例先在终端初始化uv toolinstallspecify-cli specify init photo-organizer--integrationcopilotcdphoto-organizer接着在该项目中打开编码代理。下面是本文改写的教学提示词需要在代理对话框里逐条执行并检查每一步产物/speckit-constitution 原始照片不得被修改或删除关键行为必须提供验证办法保持实现简单。 /speckit-specify 创建一个单用户本地照片整理工具按拍摄日期分组展示缺少拍摄日期的照片进入“日期未知”从相册移除照片时保留原始文件照片和元数据不得上传到外部服务。 /speckit-plan 采用本机运行的 Python 服务与简单网页界面用 SQLite 保存照片索引和相册关系。明确本地文件访问方式、日期读取规则以及不向外部传输数据的验证办法。 /speckit-tasks /speckit-implement /speckit-converge命令形式采用 Copilot 默认技能语法其他代理的调用形式可能不同应查对应集成文档。初始化负责建立流程所需文件具体实现仍由编码代理执行。官方安装与流程入口读完规格后尤其要检查那些“看起来已经写清楚”的词。比如“拍摄日期”是否涉及不同时区首版是否支持所有照片格式发现歧义时先用 clarify 补齐约定投入更正式的功能开发时再按需加入 checklist 和 analyze。本文没有安装或运行上述示例不能据此声称它已通过验证。07什么时候值得用什么时候会变成负担我更愿意用“理解偏差的代价”判断是否采用这套方法。如果只是改一个按钮文案需求明确、差异很小直接修改和验证往往足够。如果一个功能牵涉数据保留、权限、异常处理或者几个人对“完成”的理解不同先明确规格就更有价值。尤其是需要跨会话、跨人员交接的工作记录下来的决策能减少重新解释的成本。反过来如果你还不知道用户到底需要什么立即生成一套精细规格可能只是让尚未验证的假设看起来更加确定。这时可以先做访谈、原型或评估。用 spec-kit 时我建议保留三个习惯评审规则时就带上反例。“照片正常显示”之外还要看损坏文件、缺少日期等情况。把结论与证据放在一起。写清检查了什么、哪些未检查不用“已完成”掩盖未知。需求变化后同步更新产物。防止代码符合旧规格而旧规格已经不符合实际需要。这三条是使用建议不是工具自动完成的保证。AI 能写出越来越多代码之后团队需要更清楚地回答我们原本要求什么实际做到了什么还有什么没有证据。spec-kit 提供了组织这些答案的方法。真正决定验收质量的仍是你写下的规则以及用来检验规则的事实。