AI Engineering
OpenSpec：AI 编程要先写清楚需求，再让模型动手
AI 编程最常见的失败，不是模型不会写代码，而是它太快开始写代码。需求还没有被拆开，边界还没有被确认，验收条件还没有形成，模型已经开始改文件。第一次输出看起来很快，后面的返工却会吞掉更多时间。
OpenSpec 这类规格驱动工作流的价值，就在于把 AI 的默认冲动往前拦一步：先把变更写清楚，再允许执行。它不是给模型再加几句提示词，而是给团队加一个轻量的需求对齐层。
真正要控制的是“猜着写”
Cursor、Claude Code、Codex、Copilot 这类工具都擅长执行。问题是，用户给出的需求往往天然缺上下文：目标用户、业务优先级、兼容边界、数据迁移、异常场景、验收方式，这些信息通常都在人的脑子里。模型看到一句“加深色模式”，就会按通用模式补全。
补全得越积极，越容易在错误方向上走得很远。几十个文件改完以后才发现主题系统不兼容、设计目标不一致、用户真正需要的是可访问性而不是换色，这种返工才是 AI 编程的隐性成本。
OpenSpec 的核心：把每次变化变成 Change
OpenSpec 把一次功能、修复或重构包装成独立的 Change。一个 Change 里通常包含 proposal、specs、design、tasks 这些文档：为什么做、需求是什么、怎么实现、分几步完成。
这个结构不重。它的关键不是复刻传统瀑布文档，而是让 AI 在动手前先产生可审阅的中间物。人可以在 proposal 阶段纠偏，在 specs 阶段补验收场景，在 design 阶段挡住过度设计，在 tasks 阶段控制改动颗粒度。
适合存量项目，而不是只适合新项目
很多团队不愿意写规格，是因为历史系统太大，补全全量文档不现实。OpenSpec 比较务实的地方，是强调 Delta Spec：只描述本次变化增加、修改或删除了什么。存量项目不需要从零补一本系统说明书，也能逐步沉淀可读的变更历史。
这对 AI 协作尤其重要。每次归档后的规格，都是给未来模型和未来成员看的上下文。三个月后再问“为什么这里这样设计”，答案不再散落在聊天记录里。
什么时候值得用
- 跨模块功能开发，例如账号、计费、权限、主题、通知。
- 会影响数据结构、接口契约或用户路径的改动。
- 多人协作下容易产生理解偏差的任务。
- 需要长期维护、希望留下决策记录的项目。
什么时候不要过度使用
- 一次性脚本、小范围文案、机械格式化，直接改更快。
- 探索性原型还没形成目标时，先做 spike，不要把模糊想法包装成规格。
- 团队没有审阅习惯时，生成再多文档也只是噪音。
落地建议
- 先从高返工风险的任务开始，不要全项目强推。
- 把 Change 名称控制清楚，避免“update-ui”这种无法检索的命名。
- 要求 AI 写验收场景，而不是只写实现步骤。
- 实现前人工审 proposal 和 tasks；实现后归档规格。
- 把规格文档纳入代码审查，而不是放在聊天记录里。
OpenSpec 真正解决的不是“让 AI 多问几个问题”，而是把 AI 编程从即时对话变成可审阅、可归档、可复用的工程流程。模型越强，这层流程越重要。否则执行力提升，只会让错误方向上的速度更快。