Appearance
Spec 技能解决的是 AI 写代码前最常见的问题：需求还没说清楚，Agent 已经开始改文件。它适合 Claude Code、Cursor、OpenCode、Codex 这类编程 Agent，用来提前写清目标、范围、项目约束、测试方法和完成标准。
AI 写代码前怎么先把需求说清楚：Spec 技能怎么用
下载 spec-driven-development 中文版 Skill ZIP
你让 AI 做一个登录页，它可能会顺手改路由、改样式、改状态管理，再补一个自己想象出来的后端接口。
这类翻车，通常不是模型不会写代码。
是你让它在猜。
spec-driven-development 这个技能的核心很朴素：写代码前，先把“要做什么”和“做到什么程度算完成”说清楚。它来自 addyosmani/agent-skills，但这里不把它当成某个项目的专属规则，而是当作 AI Agent 编程前的刹车。
Spec 不是长文档
很多人一听到 spec，就想到几十页 PRD、评审会、流程表。
个人开发者不需要那套。
给 AI 用的 spec 更像一张施工单，重点是让 Agent 少猜。它通常只需要写清几件事：
- 目标：这次到底要解决哪个问题。
- 范围：哪些文件、模块、行为可以动，哪些不能动。
- 约束：项目用什么框架、命令、风格、测试方式。
- 验收：用户看到什么结果，或者哪条测试通过。
- 边界：暂时不做什么，避免 AI 顺手扩写。
如果这五件事说不清楚，AI 很容易把“实现一个功能”理解成“重做一套方案”。
什么时候该先写 spec
小修小补不一定要写。
比如改一个错别字、替换一个链接、改一行配置，这些任务边界天然清楚，直接改就行。
更适合写 spec 的场景是这些：
- 你要新增一个页面、接口或完整功能。
- 你自己也不确定功能边界在哪里。
- 任务可能会改到多个文件。
- 你之前被 AI “自作主张”坑过。
- 你希望别人能 review 这次改动。
Spec 的价值不是显得专业，而是把隐含要求提前暴露出来。
比如你说“给设置页加一个 API Key 管理功能”，AI 可能不知道这些问题：
- API Key 是只存在浏览器，还是要存服务端？
- 是否需要加密？
- 保存后是否要立即验证？
- 是否需要显示完整 Key，还是只显示后几位？
- 错误提示应该怎么写？
这些问题如果不提前说清楚，AI 会自己补答案。它补得越自然，你越容易晚一点才发现不对。
一个可复制的 Spec 模板
你可以直接把下面这段给 Claude Code、Cursor 或 OpenCode：
md
我要实现：[一句话目标]
当前背景：
- 项目使用：[框架 / 语言 / 关键依赖]
- 相关文件可能是：[文件或目录]
- 现有行为是：[现在怎么工作]
这次只做：
- [具体改动 1]
- [具体改动 2]
- [具体改动 3]
这次不做：
- [明确排除的功能]
- [不要顺手重构的范围]
验收标准：
- [用户能看到或操作的结果]
- [需要通过的测试或命令]
- [需要保持不变的旧行为]
如果你发现需求不清楚，先问我，不要直接写代码。这段不复杂，但它会把 Agent 从“自由发挥”拉回“按单施工”。
Spec 最容易写错在哪里
常见错误是把 spec 写成愿望清单。
比如：
做一个更好的后台管理系统，要简洁、美观、好用，后续方便扩展。
这对 AI 没有帮助。
“更好”“简洁”“方便扩展”都太虚。Agent 会用自己的审美和经验补空白，于是 diff 越来越大。
更好的写法是：
在现有后台用户列表页增加按邮箱搜索。只改用户列表页和对应查询参数。输入框放在表格上方，回车或点击搜索按钮触发请求。保留原有分页。验收标准是输入邮箱片段后列表只显示匹配用户，清空后恢复全部列表。
这段没有华丽词，但 AI 更容易做对。
Spec 要和验证绑定
没有验证的 spec 仍然容易变成聊天记录。
写给 AI 的需求最好带一个明确的证明方式：
- 页面类功能：本地打开页面，走一遍用户路径。
- 纯逻辑函数：补单元测试。
- bug 修复：先写能复现 bug 的测试，再修。
- 文档内容：检查 frontmatter、内部链接、标题层级。
Agent-skills 里很强调 verification，因为 AI 很容易把“我已经改完”当成“我已经验证”。这两件事差很多。
在古法编程的习惯里，spec 对应 P1：人先写意图、接口、边界和验收，再让 AI 动手。AI 可以执行，但方向盘不该交出去。
你可能还需要
同类技能：
如果你已经把需求说清楚了，下一步通常不是马上开写，而是先把任务拆到 AI 能稳定完成。