OpenSpec实战：AI编程前先写规范，效率提升70%

为什么AI编程需要「先写规范再写代码」？

用AI编程助手写代码，最常见的痛点不是AI写不出来，而是写出来的东西跟你想要的不一样。反复修改、推倒重来，时间全浪费在沟通对齐上。

这个问题在软件工程中被称为「意图对齐」（Intent Alignment）。当前主流的AI编程助手——无论是GitHub Copilot、Cursor、Windsurf还是Cline——都面临同样的挑战：开发者脑中的需求往往是模糊的、隐含的，而AI需要明确的指令才能生成准确的代码。这种信息不对称导致了大量的「乒乓式」交互：开发者描述需求，AI生成代码，开发者发现不对，再修改描述，AI再生成……这个循环在复杂需求中可能重复数十次。研究表明，在AI辅助编程中，开发者花在沟通和修正上的时间往往超过了实际编码时间。

OpenSpec正是为解决这个问题而生的轻量级CLI工具。它的核心思路很简单：在AI写代码之前，先让它写规范文档，对齐了再动手。 这一理念与规范驱动开发（Specification-Driven Development, SDD）一脉相承——SDD强调在编码之前先完成详细的规范文档，类似于测试驱动开发（TDD）中「先写测试再写代码」的思路。在传统软件工程中，需求文档和设计文档一直是开发流程的重要组成部分，但在敏捷开发浪潮中，很多团队为了追求速度而弱化了文档环节。然而随着AI编程助手的普及，规范文档的价值被重新发现：AI需要精确的上下文才能生成高质量代码，而规范文档恰好是最结构化的上下文载体。

OpenSpec目前已获得4.1K Star，支持30多个AI编程工具，不需要API Key，纯Markdown存储在你的代码仓库里，零侵入。

OpenSpec的核心工作流

OpenSpec提供了一套完整的命令体系：Propose → Continue → Apply → Archive，覆盖从需求理解到归档的全流程。

Propose：一次生成四层规范文件

最简单的用法是直接跑Propose命令。你告诉AI要做什么，它一次生成4个文件，层层递进：

• Proposal.md：说明为什么改、改什么（意图层）
• Specs：放需求场景，用Devon文档格式（需求层）
• Design.md：写技术方案（设计层）
• Task.md：列出执行步骤（执行层）

其中，Devon文档格式是一种专为AI编程工具设计的结构化需求描述格式，旨在让AI能够精确理解需求场景中的前置条件、操作步骤和预期结果。它类似于行为驱动开发（BDD）中的Gherkin语法（Given-When-Then模式），但更适配AI的理解方式。这种格式的核心价值在于消除自然语言描述中的歧义性，让需求从「人能看懂」提升到「AI也能准确解析」的水平。

从意图到执行，全部对齐。确认没问题就可以直接Apply，这是最快的路径，适合你清楚要改什么的场景。

Continue：复杂需求逐步把关

但复杂需求不是生成完就完了，你需要在每一步跟AI确认。比如Proposal.md生成后，你发现需求理解偏了，直接反馈修改；AI修正后再往下生成Specs；Specs的场景不够完整，继续补充。每一步确认没问题，再往下推——这就是Continue的作用。

如果你对需求很清楚，还可以用FF（快进）模式，一次跳过中间步骤直接到Tasks，省时间。简单需求用FF快速搞定，复杂需求用Continue逐步把关，灵活选择。

Explore：模糊想法的诊断模式

还有一种常见场景：你不确定具体要改什么代码，只是有一个模糊的想法，比如「性能好像有点慢」。这时候用Explore模式，让AI自由探索你的代码库，帮你分析架构、定位瓶颈、理解现有设计。

在Explore的过程中，你可能发现真正的问题跟你想的完全不一样。等搞清楚了，再从Propose开始正式规划变更。先诊断再开药方，不盲目动手——这个思路在实际开发中非常实用。

OpenSpec的两大核心亮点

大多数规范驱动开发（SDD）工具每次变更都要重写整个Spec，也没有增量变更和完整归档的能力。OpenSpec把这两个能力做进了核心，这是它区别于同类工具的关键。

DeltaSpec：只写变化，不写全文

每次变更不重写整个规范，只描述变化——edit新增、modify修改、remove删除。就像装修清单，不改整栋楼的图纸，只写「客厅刷白漆」。

效果非常显著：规范输出从800行压缩到250行，比传统方式短70%。 这不仅减少了AI的Token消耗，更重要的是让变更意图一目了然，review效率大幅提升。

要理解这个优化的意义，需要了解大语言模型（LLM）的Token机制。Token是LLM处理文本的基本单位，每次与AI交互时，输入的提示词和输出的生成内容都会消耗Token。当前主流模型如GPT-4o、Claude等虽然上下文窗口已扩展到128K甚至更大，但Token消耗直接影响响应速度和API成本。更关键的是，模型在处理超长文本时容易出现「注意力稀释」问题——即在海量上下文中忽略关键信息。DeltaSpec通过只传递变化部分，既降低了成本，又让AI能更聚焦于真正需要关注的变更内容。

完整归档：全程可追溯

Apply时源Spec和DeltaSpec自动合并成最新版本，Spec始终保持最新状态。Archive则把整个变更过程打包保留：

• Proposal记了为什么改
• Design记了怎么改
• Task记了改的顺序

再配上Verify命令，随时验证代码是否符合规范。完整的决策过程随时可查，全程可追溯。这对于团队协作和后期维护来说价值巨大——三个月后回头看，你能清楚知道当时为什么做了这个决定。

实战案例：给项目添加暗黑模式

来看一个完整的工作流案例。假设你要给项目加暗黑模式：

1. Propose：告诉AI「添加暗黑模式支持」，生成Proposal明确改动范围——主要涉及颜色系统、主题切换逻辑、用户偏好存储
2. Continue：逐步确认每一层规范，确保场景覆盖完整
3. Apply：按清单执行，源Spec和DeltaSpec自动合并，Spec始终显示最新状态
4. Archive：把Proposal、Design、Task全部打包归档，完整的决策过程随时可查

花一分钟写Proposal，省掉几小时返工。 这就是规范驱动开发的核心价值。

适用场景与使用建议

OpenSpec并不是所有场景都需要。以下是一些使用建议：

• 简单bug修复：直接让AI改就行，不需要走完整流程
• 中等功能开发：用Propose + FF快进模式，快速对齐后执行
• 复杂架构变更：用Explore先诊断，再Propose + Continue逐步把关
• 团队协作项目：Archive归档能力特别有价值，让决策过程透明可追溯

有意思的是，OpenSpec是纯Markdown方案，存储在代码仓库里，不依赖任何外部服务。选择Markdown作为规范文档的存储格式并非偶然——Markdown是一种轻量级标记语言，几乎所有的代码编辑器、Git平台（GitHub、GitLab等）和文档工具都原生支持渲染。将规范文档以Markdown形式存储在代码仓库中，意味着它可以享受Git提供的所有版本控制能力：分支、合并、差异对比、Pull Request审查等。这种「文档即代码」（Docs as Code）的理念在DevOps领域已被广泛采用，OpenSpec将其延伸到了AI编程的规范管理中。规范文档和代码一起管理、一起review，天然融入现有的开发工作流。

总结

OpenSpec代表了AI编程工具链中一个重要的演进方向：不是让AI更快地写代码，而是让AI更准确地理解你要什么。 DeltaSpec的增量变更和Archive的完整归档，解决了规范驱动开发中两个长期痛点。对于经常使用AI编程助手的开发者来说，值得花时间了解和尝试。

下次用AI写代码之前，试试先跑一遍Propose，感受一下「先对齐意图再动手」的开发节奏。

核心要点

• OpenSpec是轻量级CLI工具，核心思路是让AI先写规范文档再写代码，支持30多个AI编程工具
• DeltaSpec增量变更机制只描述变化部分，规范输出从800行压缩到250行，减少70%
• 完整工作流包含Explore探索、Propose规划、Continue逐步确认、Apply合并、Archive归档五个环节
• Archive归档能力保留完整决策过程（为什么改、怎么改、改的顺序），全程可追溯
• 纯Markdown存储在代码仓库中，零侵入，可与Git版本控制无缝配合