AI 编程热门实践：GitHub Spec Kit 入门，把一句需求变成可验收的代码

摘要

AI 写代码为什么容易偏离需求？结合 GitHub 热门开源项目 Spec Kit，梳理规格驱动开发的六步流程，附博客站内搜索规格模板、适用场景与官方参考资料。

AI 能快速生成代码，但“能运行”和“符合需求”之间，往往还隔着一轮轮返工。做一个搜索框，模型可能顺手加上登录、数据库和推荐功能；修一个小问题，也可能改动原本稳定的模块。规格驱动开发（Spec-Driven Development，简称 SDD）试图解决的，正是需求、实现与验收之间的脱节。

本文结合 GitHub 开源项目 Spec Kit 的官方说明，介绍它的核心流程，并提供一个博客搜索功能的规格示例。资料核对日期：2026 年 11 月 10 日。本文是官方资料解读与示例设计，未进行本地安装实测。

一、为什么这个方向值得关注？

截至资料核对时，Spec Kit 的 GitHub 页面显示约 14.9 万 Stars，仓库仍有更新。这个数字能反映项目受到广泛关注，但不能直接证明它适合所有项目，更不能等同于实际使用人数或生产质量。

对个人开发者来说，值得学习的是它组织任务的方法：先明确用户需要什么，再形成实现计划、拆分任务，最后根据规格检查结果。这样，AI 的输出就有了可追溯的依据，审查代码时也更容易判断某个改动是否必要。

二、Spec Kit 到底是什么？

按官方 README 的定义，Spec Kit 是为 AI 编程代理提供结构化流程、可复用模板和文档化产出的开源工具包，采用 MIT 许可证。它本身不是大模型，也不会独立替代你的编辑器、编程代理或测试工具。

当前仓库提供多种入口：新功能可以采用 SDD；已知故障可以进入 Bug 修复流程；还不确定是否值得开发的想法，可以先做评估。官方明确说明，这些入口相互独立，无须为每个小修复先走一遍完整功能开发流程。

三、新项目如何开始？

官方当前入门要求包括 Python 3.11 或更新版本、uv，以及一个受支持的 AI 编程代理，支持 Linux、macOS 和 Windows。下面摘录官方使用 GitHub Copilot 的初始化示例，供读者参考：

uv tool install specify-cli
specify init my-project --integration copilot
cd my-project

这几条命令在终端执行。随后，在项目目录启动编程代理，再在代理对话中运行流程命令。接入其他代理、已有项目或锁定工具版本时，应以官方文档为准，不要直接套用与当前版本不符的旧教程。

四、从需求到验收，逐步检查六个环节

官方当前 README 展示的 Copilot 默认技能调用形式如下。每条应单独运行，并在检查产出后再进入下一步；它们是代理对话命令，不是终端命令。

/speckit-constitution
/speckit-specify
/speckit-plan
/speckit-tasks
/speckit-implement
/speckit-converge

制定项目原则：明确代码质量、测试和可维护性要求。例如优先复用现有实现，新增依赖需说明必要性。
描述功能规格：写清用户场景、范围、异常情况和验收条件。先解决“要做什么、为什么做”。
形成技术计划：结合现有技术栈与目录结构，确认入口、数据来源和必要改动。
拆分执行任务：将工作拆为便于验证的小步，避免一次生成大量无法审查的代码。
实施代码：沿着已经确认的任务推进，出现新问题时及时修正规格或计划。
检查收敛：依据规格核对产出，发现缺项后继续修复。官方示例建议重复 implement 与 converge，直到报告 Converged。

工具报告只是验收证据的一部分。页面能否使用、原有功能是否回归、部署环境是否一致，仍需结合实际项目检查。

五、可直接改写的案例：给博客添加站内搜索

“帮我做一个好用的搜索功能”包含太多未说明的选择。下面这份简化规格把目标压缩成能够观察、能够判断的行为。它是本文设计的示例，不代表工具自动生成的实测结果。

功能：博客公开文章搜索

用户目标：输入关键词，快速找到相关的已发布文章。

本次范围：
1. 搜索公开文章标题和摘要。
2. 结果显示标题、摘要和文章链接。
3. 不展示草稿、私密文章及受密码保护的内容。
4. 复用现有站点样式和查询能力。

输入与边界：
- 去掉关键词首尾空白。
- 空关键词不发起搜索，并提示输入内容。
- 无结果时显示清晰提示。
- 查询失败时提示稍后重试，不暴露内部错误详情。

验收条件：
- 已知标题关键词能命中对应公开文章。
- 搜索草稿或受限文章的独有关键词时，不泄露其内容。
- 点击结果进入正确文章。
- 中文、英文和包含特殊字符的输入均得到妥善处理。
- 手机页面无明显横向溢出。

本次不包含：
全文向量检索、用户画像、推荐算法、登录与收费功能。

下一步先让代理检查博客系统是否已有搜索功能或插件。如果已有成熟能力，优先复用并做最小调整。只有确认现有方案不能满足规格，才讨论新增实现，避免把一个小需求扩大成搜索平台。