问题：你的AI智能体构建了东西，但不是你想要的
你向AI编码智能体描述一个功能。比如，"添加一个显示用户活动的仪表板。" 智能体点头，生成代码，交付了一个可工作的仪表板。但它不是你想要的。
也许它显示了错误的指标。也许布局忽略了你的设计系统。也许它从错误的来源拉取数据。你花了一个小时解释你真正的意思，撤销工作，重新提示。智能体构建了技术上正确但功能上错误的东西。
这种情况经常发生，而且不是智能体的错。这是需求问题。
为什么模糊性会破坏AI智能体工作流
AI智能体是强大的代码生成器，但它们基于接收到的信息运作。当你说"用户活动仪表板"时，智能体默默地填补了几十个假设：
- 哪些用户？所有用户，还是当前用户的团队？
- 什么算作"活动"？登录、点击、API调用、内容创建？
- 什么时间范围？最近24小时、最近30天、全部时间？
- 数据从哪里来？现有的分析服务、原始数据库查询、第三方API？
- "显示"是什么意思？表格、图表、摘要卡片？
每个无声的假设都是你想象的和智能体构建的之间潜在的不匹配。功能越复杂，假设就越多。
跳过规范的真实代价
没有书面规范，你要为模糊性付出几种代价：
- 返工周期。 智能体构建，你纠正，它重建。每个周期都消耗时间和token。
- 范围蔓延。 没有边界，智能体可能添加你没有要求的功能，或者跳过你认为理所当然的功能。
- 架构不一致。 不同的会话或智能体做出不同的隐式决策，导致代码无法整合。
- 测试缺口。 如果你没有定义"完成"是什么样子，你就无法验证智能体是否真正完成了任务。
这个模式很熟悉：模糊提示 → 合理输出 → 发现不匹配 → 返工。修复不仅仅是更好的提示，而是一个在代码之前强制清晰度的结构化过程。
好的解决方案应该改变什么
解决这个问题的有效方法应该：
- 尽早暴露假设。 在编写任何代码之前，识别智能体在假设什么，让你纠正它。
- 创建共享参考。 你和智能体都需要一个文档来定义构建什么、为什么以及如何衡量成功。
- 以验证为进度关卡。 在计划被审查之前，不要让智能体从规划阶段进入实施阶段。
- 保持活跃。 需求会变化。规范应该随之更新，而不是成为过时的产物。
这是规范驱动开发的核心理念，这是一种为AI智能体设计的结构化工作流，优先在生成任何代码之前编写书面规范。
介绍规范驱动开发
规范驱动开发是一种AI智能体技能，强制执行四阶段门控工作流：规范、计划、任务、实施。智能体在当前阶段被人类验证之前不能进入下一阶段。
该技能来自Addy Osmani的agent-skills仓库，这是一个AI编码智能体的可重用模式集合。它专为需求不明确、模糊或仅以模糊想法存在的情况设计。
四阶段工作流如何运作
阶段1：规范
智能体首先明确列出其假设。例如：
我正在做的假设：
1. 这是一个Web应用程序（不是原生移动应用）
2. 认证使用基于会话的cookie（不是JWT）
3. 数据库是PostgreSQL（基于现有的Prisma schema）
4. 我们只针对现代浏览器（不支持IE11）
→ 现在纠正我，否则我将按这些假设继续。
这是过程中最有价值的部分。智能体不是默默猜测，而是强制你确认或纠正其理解。然后它编写一个涵盖六个领域的规范文档：目标、命令、项目结构、代码风格、测试策略和边界。
规范还将模糊需求重新定义为具体的成功标准。"让仪表板更快"变成：
- 仪表板LCP在4G连接下 < 2.5秒
- 初始数据加载在 < 500毫秒内完成
- 加载期间无布局偏移（CLS < 0.1）
→ 这些是正确的目标吗？
阶段2：计划
有了验证过的规范，智能体生成技术实施计划。它识别主要组件、实施顺序、风险以及哪些可以并行构建。计划保存到 tasks/plan.md 供审查。
阶段3：任务
计划被分解为离散的任务，每个任务都有明确的验收标准和验证步骤。每个任务应该能在单个会话中完成，并且只涉及大约五个文件。
阶段4：实施
智能体一次执行一个任务，引用与每个任务相关的规范部分，而不是加载整个文档。
何时使用此技能
在以下情况下使用规范驱动开发：
- 从零开始启动新项目或功能
- 需求模糊或仅以模糊想法存在
- 更改涉及多个文件或模块
- 你即将做出架构决策
- 任务实施需要超过30分钟
何时不使用它
此技能对于以下情况是过度的：
- 单行修复或拼写纠正
- 需求明确且自包含的更改
- 有清晰重现路径的简单错误修复
对于这些情况，直接提示更快更合适。
评估此技能是否适合你的工作流
在采用规范驱动开发之前，考虑以下因素：
优势
- 减少返工。 通过在编写代码之前发现误解，避免构建-纠正-重建的循环。
- 作为副产品创建文档。 规范成为未来更改的活参考。
- 适用于任何AI编码智能体。 该技能是过程模式，不绑定特定工具。
- 很好地处理模糊需求。 假设暴露机制专门针对不清晰的输入设计。
局限性和权衡
- 增加前期时间。 编写规范需要15-30分钟。对于小任务，这种开销不合理。
- 每个关卡都需要人工审查。 如果你没有时间审查假设和计划，智能体会停滞。
- 不是沟通的魔法修复。 即使面对澄清问题，如果你无法表达你想要什么，规范仍然会是错的。
- 依赖智能体的纪律性。 智能体必须遵循门控工作流。如果它跳过阶段，好处就消失了。
设置上下文
此技能是记录在 SKILL.md 文件中的过程模式。它不需要安装包或配置工具。你将其加载到AI智能体的上下文中（具体方法取决于你的智能体平台），并指示智能体遵循规范驱动工作流。
该技能在实施阶段引用了同一仓库中的其他技能，包括增量实施、测试驱动开发和上下文工程。这些是可选的配套技能，不是硬依赖。
安全和仓库信号
- 仓库： addyosmani/agent-skills，拥有超过76,000颗星，表明广泛的社区采用。
- 许可证： 仓库包含LICENSE文件。请为你的用例审查它。
- 安全级别： 低风险。该技能是过程文档，不是可执行代码。它不访问外部服务或修改系统状态。
- 主题： 仓库涵盖Cursor、Codex、Claude Code和其他智能体平台的技能。
使用前需要检查什么
- 阅读完整的SKILL.md。 上面的摘录涵盖了核心工作流，但完整文档包含关于保持规范活跃和处理常见合理化的额外指导。
- 检查与你的智能体的兼容性。 该技能假设智能体可以创建文件、遵循多阶段指令并等待人工审查。先用小任务测试。
- 审查引用的技能。 实施阶段引用了
incremental-implementation、test-driven-development和context-engineering。决定你是否也想使用它们。 - 调整规范模板。 六部分模板是一个起点。你的项目可能需要不同的部分（例如API契约、数据模型、部署要求）。
实际示例：构建通知系统
想象你告诉智能体："给应用添加通知。"
没有规范驱动开发，智能体可能使用Firebase构建推送通知、在头部添加铃铛图标、以及创建通知偏好页面。所有合理的猜测，但可能是错的。
使用规范驱动开发，智能体首先列出假设：
假设：
1. 通知仅限应用内（无邮件、无推送）
2. 通知存储在数据库中（不是第三方服务）
3. 用户可以将通知标记为已读
4. 此阶段不创建通知偏好页面
→ 现在纠正我。
你纠正："实际上，我们也需要邮件通知，而且已经有SendGrid集成。"
智能体更新规范，编写计划，分解为任务并实施。结果符合你真正想要的，因为不匹配在前五分钟就被发现了，而不是在两小时编码之后。
结论
规范驱动开发不是关于放慢速度。而是将花在澄清上的时间从过程的末尾（返工）转移到开头（规范）。对于复杂功能、模糊需求或新项目，花在规范上的15分钟可以节省数小时的错误实施。
如果你的AI智能体经常构建错误的东西，问题可能不是智能体的能力，而是输入的清晰度。规范驱动开发提供了一种结构化的方式来修复这个问题。