夜雨聆风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:exploreAI 会读取你的代码库，帮你梳理思路、评估方案可行性，在任何文档或代码被写下之前，先把想法捋清楚。这是避免"AI 理解歪了"的最有效习惯。
示例对话：
你：/opsx:explore
AI：你想探索什么？
你：我想加深色模式，但不确定怎么做比较干净。
AI：我看了你的样式结构……最简洁的方案是 CSS 变量 + 小型主题 Context，
加上系统偏好检测，不需要引入新依赖。要确定范围吗？
你：好，确定。第四步：生成提案
/opsx:propose add-dark-modeAI 会自动生成完整的 Change 目录：
✓ proposal.md — 为什么要做、影响什么
✓ specs/ — 需求条目和验收场景
✓ design.md — 技术实现方案
✓ tasks.md — 实现任务清单
准备好实现了！你在这里做的事：审阅这些文档，修改不准确的地方，确认后再继续。这是整个流程的关键检查点。
第五步：执行实现
/opsx:applyAI 按照 tasks.md 中的清单逐一实现，你可以实时看到进度：
✓ 1.1 添加主题 Context Provider
✓ 1.2 创建切换组件
✓ 2.1 添加 CSS 变量
✓ 2.2 接入 localStorage
所有任务完成！第六步：归档沉淀
/opsx:archiveAI 将这次变更的规格合并到项目主规格文档中，并将 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