AI 写代码总是"理解错需求"？这个开源工具让它先把需求写清楚再动手

GitHub 56.4k ⭐，3.9k Fork，支持 21 款 AI 编程工具——它彻底改变了人与 AI 协作写代码的方式。

一、我们面临什么问题？

自从 Cursor、Claude Code、GitHub Copilot 这类 AI 编程助手普及以来，开发者的工作效率大幅提升。但随之而来的，是一个越来越普遍的痛苦体验：

你说了半天，AI 理解歪了，写出来的东西完全不是你想要的。

具体表现为：

• • 你说"加个深色模式"，AI 直接开始动手写代码，结果方案和你的架构完全不兼容
• • 你的需求描述越模糊，AI 补脑越离谱，等你发现问题，已经改了几十个文件
• • 没有任何文档记录"为什么这样设计"，三个月后你自己都看不懂
• • 团队协作时，每个人和 AI 的对话是孤立的，知识无法沉淀和共享

传统的解决方案是"写规格说明书"（Specification Document），但那套东西太重了——PRD、技术设计文档、评审会……光流程就能让人崩溃，更别提 AI 根本不知道怎么配合这套流程。

问题的本质是：AI 编程工具天生擅长"执行"，但缺乏一套标准化的"先对齐需求、再动手"的工作流。

二、OpenSpec 是什么？

OpenSpec 是一个专为 AI 编程助手设计的"规格驱动开发"（Spec-Driven Development，SDD）框架。

项目地址：https://github.com/Fission-AI/OpenSpec

用一句话说清楚它的核心思想：

在 AI 写任何一行代码之前，先让它把"要做什么、为什么做、怎么做"写成结构化文档，你确认后再执行。

它不是一个新的 AI 模型，也不是一个 IDE 插件，而是一套工作流规范 + CLI 工具，以斜杠命令的形式无缝嵌入你现有的 AI 编程工具中。

核心设计理念

OpenSpec 明确反对传统瀑布式开发流程的僵化，遵循四个原则：

支持的 AI 工具（21 款）

Claude Code、Cursor、Windsurf、GitHub Copilot、Gemini CLI、Amazon Q、Cline、RooCode、Kilo Code、CodeBuddy、Qwen、Factory、Codex……几乎覆盖了目前市面上所有主流 AI 编程助手。

三、它是怎么工作的？

核心概念：Change（变更单元）

OpenSpec 的核心抽象是 Change——每一次功能开发、Bug 修复、重构，都被封装成一个独立的 Change，包含以下结构化文档：

openspec/changes/add-dark-mode/
├── proposal.md     ← 为什么要做这件事，影响范围
├── specs/          ← 需求和验收场景
├── design.md       ← 技术方案设计
└── tasks.md        ← 具体实现任务清单

核心概念：Delta Spec（增量规格）

对于已有代码库，OpenSpec 使用增量规格而非重写整个说明文档：

# Delta for Auth
## ADDED Requirements
### Requirement: 两步验证
系统必须支持基于 TOTP 的双因素认证。

这让在存量项目上接入 OpenSpec 变得极为轻松——你不需要补写整个系统文档，只需描述"这次的变化是什么"。

工作流全貌

探索想法 → 提案对齐 → AI 实现 → 归档沉淀
/opsx:explore  →  /opsx:propose  →  /opsx:apply  →  /opsx:archive

每个阶段 AI 都有明确的产出物和边界，不会越权行事。

四、怎么用？

第一步：安装 CLI

npm install -g @fission-ai/openspec@latest

需要 Node.js 20.19.0 或以上版本。

第二步：初始化项目

cd your-project
openspec init

运行后，OpenSpec 会自动扫描你的项目，检测已安装的 AI 工具（.claude/、.cursor/ 等目录），并让你选择要集成的工具，完成对应配置文件的生成。整个过程不到一分钟。

第三步：探索想法（可选但强烈推荐）

在你的 AI 聊天界面输入：

/opsx:explore

AI 会读取你的代码库，帮你梳理思路、评估方案可行性，在任何文档或代码被写下之前，先把想法捋清楚。这是避免"AI 理解歪了"的最有效习惯。

示例对话：

你：/opsx:explore
AI：你想探索什么？
你：我想加深色模式，但不确定怎么做比较干净。
AI：我看了你的样式结构……最简洁的方案是 CSS 变量 + 小型主题 Context，
    加上系统偏好检测，不需要引入新依赖。要确定范围吗？
你：好，确定。

第四步：生成提案

/opsx:propose add-dark-mode

AI 会自动生成完整的 Change 目录：

✓ proposal.md  — 为什么要做、影响什么
✓ specs/       — 需求条目和验收场景
✓ design.md    — 技术实现方案
✓ tasks.md     — 实现任务清单
准备好实现了！

你在这里做的事：审阅这些文档，修改不准确的地方，确认后再继续。这是整个流程的关键检查点。

第五步：执行实现

/opsx:apply

AI 按照 tasks.md 中的清单逐一实现，你可以实时看到进度：

✓ 1.1 添加主题 Context Provider
✓ 1.2 创建切换组件
✓ 2.1 添加 CSS 变量
✓ 2.2 接入 localStorage
所有任务完成！

第六步：归档沉淀

/opsx:archive

AI 将这次变更的规格合并到项目主规格文档中，并将 Change 文件归入历史存档：

✓ 规格已合并至 openspec/specs/ui/spec.md
✓ 已归档至 openspec/changes/archive/2025-01-24-add-dark-mode/

这一步的价值：你的项目从此积累了可读、可检索的技术决策文档，团队新成员和未来的 AI 都能读懂"这里为什么这么设计"。

其他实用命令

openspec list              # 查看所有进行中的 Change
openspec show add-dark-mode  # 查看某个 Change 的详情
openspec validate add-dark-mode  # 校验规格格式
openspec view              # 打开交互式面板
/opsx:bulk-archive         # 批量归档多个已完成的 Change
/opsx:onboard              # 11 阶段互动教程，约 15 分钟上手

五、适合哪些场景？

✅ 非常适合：

• • 个人开发者：避免和 AI 反复"拉锯"，一次对齐省去后续大量返工
• • 小团队协作：Change 文档天然成为异步沟通载体，减少口头对齐成本
• • 存量项目维护：Delta Spec 机制让老项目也能低成本接入
• • 追求代码库可维护性的团队：规格文档自动随代码演进沉淀

❌ 不太适合：

• • 一次性脚本、极小改动（直接问 AI 更快）
• • 纯粹探索性原型（需求极度模糊时，连规格都没法写）

六、总结

AI 编程工具的本质局限在于：它们只知道"怎么做"，不知道"做什么、为什么做"。

OpenSpec 填补了这个空白。它不替代你的 AI 工具，而是在你和 AI 之间插入一个"需求对齐层"——用结构化的文档强迫双方在动手前达成共识。

这套思路并不新鲜，软件工程几十年来一直在强调"先设计再实现"。OpenSpec 的价值在于把这套理念以极低的摩擦成本带入了 AI 编程时代，并且做到了真正的工具无关、项目无关、语言无关。

56.4k 个 Star 不是偶然。当你第一次用它成功避开一次"AI 理解歪了"导致的大规模返工，你就明白这颗星为什么值得点了。

项目地址：https://github.com/Fission-AI/OpenSpec
安装命令：npm install -g @fission-ai/openspec@latest
Discord 社区：discord.gg/YctCnvvshC
License：MIT