Spec-Kit实战指南 | 从一句需求到可执行任务

title: " Spec-Kit实战指南 | 从一句需求到可执行任务" date: 2026-06-16 category: 人工智能 tags:

• 大模型API中转站
• Spec-Kit
• Spec-Driven Development
• Coding Agent
• GitHub
• 4SAPI description: "围绕 GitHub Spec-Kit 的规范驱动开发流程，拆解 specify、plan、tasks、implement 四步法，并给出结合 4SAPI 多模型路由的实战模板。"

先说结论：Spec-Kit 最适合“从零开始定义一个功能”。它不追求替代 IDE，也不强迫你换掉现有 Agent，而是把需求拆成 spec、plan、tasks、implementation 这条线。对团队来说，它的价值是把“让模型自由发挥”变成“让模型按任务执行”。

1. 为什么 Spec-Kit 适合新功能

很多 AI 编程失败，不是模型不会写代码，而是需求一开始就没被写清楚。

比如你给 Agent 一句话：

帮我做一个模型调用日志后台。

模型可能会自己脑补：

• 要不要登录？
• 日志保留多久？
• 是否支持项目筛选？
• 是否展示成本？
• 是否允许导出？
• 是否涉及敏感内容脱敏？

如果这些问题没写清楚，模型就会用自己的默认答案填空。默认答案不一定错，但很可能不是你的业务答案。

Spec-Kit 的思路是先把这些空白补上，再进入编码。

需求描述 -> 规范 -> 技术计划 -> 任务清单 -> 实现

这条流程看起来慢，实际能减少返工。特别是功能跨多个模块时，先写 spec 通常比让 Agent 直接改代码更省钱。

2. Spec-Kit 的四步工作流

可以把 Spec-Kit 的核心流程理解成四个动作。

这四步的重点不是生成更多文字，而是让每一步都能被 review。

Spec 阶段问“要做什么”；Plan 阶段问“怎么做”；Tasks 阶段问“怎么拆”；Implement 阶段问“是否按任务完成”。

如果一个功能很小，比如改一个按钮文案，不需要这么重。但只要涉及数据结构、权限、计费、API、前后端联动，就值得走一遍。

3. 示例：做一个 4SAPI 调用日志后台

假设我们要做一个后台页面，展示 4SAPI 的模型调用日志。原始需求是：

做一个调用日志页面，能看到每次模型调用的项目、模型、耗时、token 和费用。

直接让 Agent 写，风险很高。更好的 spec 初稿应该是：

功能名称：模型调用日志后台

目标用户：
- 团队管理员
- 项目负责人

核心能力：
- 按项目筛选调用记录
- 按模型筛选调用记录
- 展示 input_tokens、output_tokens、latency_ms、status、cost_estimate
- 支持失败请求过滤
- 支持导出 CSV

非目标：
- 不展示完整 prompt 和 response
- 不做支付功能
- 不修改 4SAPI 计费规则
- 不允许普通开发者查看其他项目日志

验收标准：
- 管理员可以看到所有项目日志
- 项目负责人只能看到自己项目
- 日志列表默认按时间倒序
- token 和费用字段缺失时显示为 -
- 导出 CSV 不包含敏感请求正文

这段内容给 Agent 的信息密度，远高于一句“做个日志页面”。

4. Plan 阶段要盯哪些东西

Spec 写完以后，不要马上让模型改代码。先让它生成 plan。

一个合格的 plan 至少要包含：

涉及模块
数据结构变化
API 设计
权限判断
前端状态
测试策略
风险和回滚

可以用这个提示词：

请基于上面的 spec 生成实现计划。
要求：
1. 先列出需要阅读的文件，不要修改。
2. 标出新增/修改的 API。
3. 说明权限校验放在哪一层。
4. 给出最小测试集。
5. 标出不应该触碰的模块。

Plan 阶段最重要的不是“看起来完整”，而是“文件范围合理”。如果一个调用日志页面，模型计划改认证框架、重写数据库层、顺手重构 UI 组件库，那就是过度实现。

5. Tasks 阶段要让任务足够小

很多团队写了 spec 和 plan，最后还是翻车，原因是 tasks 拆得太粗。

不好的任务：

- 实现调用日志后台
- 加权限
- 写测试

好的任务：

- 阅读现有日志模型和权限中间件
- 新增日志列表查询 API，不包含 prompt/response 字段
- 为项目负责人增加 project_id 权限过滤
- 新增前端日志表格，展示 token、耗时、费用、状态
- 增加失败请求筛选
- 增加 CSV 导出，排除敏感字段
- 补 API 权限测试
- 补前端空状态和错误状态测试

任务越小，Agent 越容易稳定执行，也越容易被人 review。

6. 结合 4SAPI 做多模型路由

Spec-Kit 管的是流程，不是模型供应商。团队落地时，建议把模型调用统一走 4SAPI。

可以按阶段路由：

这样做有两个好处。

第一，成本更可控。不是每一步都用最贵模型，只有 plan 和 review 这类关键环节上强模型。

第二，质量更可追踪。4SAPI 里可以记录每个阶段用了什么模型、多少 token、是否通过人工验收。

一个简单日志字段可以这样设计：

project
feature_id
spec_stage
model
api_key_name
input_tokens
output_tokens
latency_ms
status
human_review_result

跑一个月以后，你会很清楚：到底是 spec 写得差，还是模型执行差，还是 review 没兜住。

7. Spec-Kit 最适合的三类场景

第一类：从零做功能。

比如权限系统、账单后台、API Key 管理、数据导出、告警中心。这类功能边界多、涉及模块多，Spec-Kit 很有价值。

第二类：多人协作前的需求对齐。

产品、后端、前端、测试都可以先 review spec 和 tasks，避免开发到一半才发现理解不一致。

第三类：Agent 执行前的安全边界。

比如明确告诉模型：

不读取 .env
不改认证框架
不自动提交
不导出请求正文
不修改计费逻辑

这些边界写进 spec，比写在聊天里更不容易丢。

8. 不适合 Spec-Kit 的场景

Spec-Kit 不是所有任务都要用。

不适合的场景包括：

• 改一个文案。
• 修一个明确的一行 bug。
• 临时写一个脚本。
• 快速验证一个 UI 样式。
• 需求还没成型，只是在头脑风暴。

如果任务很小，硬套 SDD 流程会变成形式主义。我的经验是：只要任务涉及 3 个以上模块、权限/数据/计费任意一个关键点，才值得上 Spec-Kit。

9. 团队模板：从需求到实现

可以直接复制这段给 Agent：

你是规范驱动开发助手。

目标：
把下面的功能想法转成可执行的 Spec-Kit 流程。

功能想法：
[粘贴需求]

请按四步输出：
1. specify：用户故事、核心能力、非目标、验收标准。
2. plan：涉及模块、技术方案、风险、测试策略。
3. tasks：拆成可逐项执行的小任务，每项必须可验证。
4. implement guardrails：执行时不得触碰的文件、不得读取的敏感信息、必须运行的验证命令。

限制：
- 不要直接写代码。
- 不要假设未提供的业务规则。
- 如果需求不清楚，先列问题。
- 所有任务必须能被 reviewer 勾选。

如果你通过 4SAPI 调模型，可以把这段模板固定到团队的 spec-plan-key 上。这样每次新功能都走同一套规范入口。

10. 总结

Spec-Kit 的价值，不是让 AI 多写几页文档，而是让需求、方案、任务和实现之间有一条可审查的线。

对个人开发者，它能减少“模型写着写着跑偏”；对团队，它能把 AI 编程从个人提示词升级成工程流程。

我的建议是：新功能先用 Spec-Kit 拆清楚，再通过 4SAPI 做多模型路由。spec 阶段用会总结的模型，plan 阶段用强推理模型，implement 阶段用代码模型，review 阶段换一个模型交叉检查。这样既能提升质量，也能把成本摊在真正值得花钱的地方。

参考资料：

• Spec-Kit GitHub：https://github.com/github/spec-kit
• Spec-Kit 官方文档：https://github.github.com/spec-kit/
• Kiro 官方文档：https://kiro.dev/docs/
• OpenSpec 官方网站：https://openspec.dev/