OpenSpec 是一个专为 AI 编码助手打造的规范驱动开发工具。它试图在人类模糊的直觉和AI机械的执行之间，架起一座坚实的桥梁。

它解决的核心问题，就是需求管理的“黑盒化”。当需求散落在零碎的聊天记录中时它们就像断了线的风筝，再也找不回来。OpenSpec 通过一套轻量级但严谨的流程，将那些模糊的提示词转化为可审查、可落地、可追溯的工程计划。

想象一下你不再是对着空气喊话，而是在和AI签署一份份“技术合同”。这就是 OpenSpec 带来的改变。

在开始这场规范驱动之旅前，我们需要确保你的“武器”是锋利的。OpenSpec 对环境的要求非常亲民，你不需要为了它去重构整个开发环境。

环境要求：请确保你的机器上安装了 Node.js 18 或者geng高版本。这是目前现代前端工程的标准配置，相信大部分开发者douYi经满足了这个条件。

OpenSpec 几乎兼容市面上所有主流的 AI 编码助手。无论你是 Cursor 的忠实粉丝，还是 Windsurf 的早期 adopter，亦或是坚守在 VS Code 阵营，它douNeng完美融入你的工作流。

安装过程简单直接，只需几行命令：

# 全局安装 OpenSpec
npm install -g openspec-cn/openspec
# 进入你的项目目录
cd your-project
# 初始化 OpenSpec 配置
openspec init

当你运行 openspec init 时它会在你的项目根目录下创建一个 openspec/ 文件夹。这个文件夹，就是你未来所有“真相”的存放地。同时它会根据你当前使用的 AI 工具，自动配置好对应的斜杠命令，省去了手动配置的繁琐。

理解 OpenSpec 的目录结构，是掌握它的关键。别担心，这并不复杂。它把项目分为了两个截然不同的世界：一个是Yi经确定的“现实”，另一个是正在酝酿的“未来”。

让我们kankan这个结构：

openspec/
├── specs/        # Yi实现的功Neng
└── changes/      # 待实现的提案
    └── /
        ├── proposal.md   # 为什么要Zuo、Zuo什么
        ├── design.md     # 技术方案
        ├── tasks.md      # 实施清单
        └── specs/        # 规范增量

1. specs/ 目录：真相的唯一来源

这里存放着所有Yi经实现的功Neng规范。在 OpenSpec 的哲学里这里就是“圣经”。Ru果代码实现和这里的描述不一致，那就是代码出了问题。它是项目状态的单一事实来源，避免了“代码即文档”带来的歧义。

2. changes/ 目录：提案的孵化器

任何新功Neng的开发、Bug的修复，或者重构，dou需要先在这里“安家”。每一个变gengdou会拥有一个独立的文件夹。这种独立归档的设计，保证了历史的清晰可追溯。当你几个月后回过头来kan，依然Neng清楚地知道当时为什么要这么改。

在变geng文件夹内，四个关键文件各司其职： * proposal.md阐述动机和目标，解决“为什么Zuo”的问题。 * design.md描述技术路径，解决“怎么Zuo”的问题。 * tasks.md拆解具体步骤，解决“Zuo什么”的问题。 * specs/存放新的或修改后的规范文件，作为对主规范的补丁。

OpenSpec 将开发过程浓缩为四个清晰的步骤。全程你只需要通过简单的斜杠命令与 AI 交互，就Neng完成从想法到代码的转化。我们以“为项目添加深色模式”为例，来实操一下这套流程。

不要急着写代码。我们需要为这个变geng建立一个“档案”。在 AI 对话框中输入：

# 创建一个新的变geng项
/opsx:new add-dark-mode

这条命令会在 openspec/changes/ 下创建一个名为 add-dark-mode 的文件夹。这就像是给AI发了一个“立项通知书”，告诉它：“嘿，我们要开始这件事了先准备好场地。”

接下来是 AI 展现它“智Neng”的时刻。你Ke以让 AI 一次性生成所有规划文档，也Ke以逐步引导它生成。为了效率，我们通常使用快速模式：

# 一次性生成全部规划文档
/opsx:ff

执行后你会kan到 AI 像勤劳的小蜜蜂一样，依次生成： * ✓ proposal.mdAI 分析了你的需求，写明了为什么要引入深色模式。 * ✓ design.mdAI 设计了 CSS 变量的方案，或者切换逻辑的技术选型。 * ✓ tasks.mdAI 列出了详细的清单，比如“定义颜色变量”、“修改 Header 组件”、“添加切换开关”等。 * ✓ specs/生成了对应的规范描述。

这一步的核心在于“人在回路”。AI 生成的提案必须经过你的严格审查。你需要确认它真的理解了你的意图，技术方案是否靠谱。Ru果发现偏差，现在修改的成本几乎为零。

当你对规划点头示意后就Ke以进入实施阶段了。此时OpenSpec 会依据 tasks.md 中的清单，指导 AI 逐步完成代码编写：

# 开始按任务清单实施
/opsx:apply

AI 会按照任务列表，一项一项地修改代码。因为它有了明确的“施工图纸”，所以不再容易跑偏。你会发现，AI 写出的代码geng加结构化，也geng符合预期。

当所有任务完成后这个变geng就成为了历史。我们需要把它归档，并将新的规范合并到主库中：

# 归档变geng
/opsx:archive

这条命令会Zuo两件事：将 changes/add-dark-mode 移动到 changes/archive/ 下存档；将 specs/ 中的增量内容合并回主 specs/ 目录。至此，specs/ 成为了项目当前状态的唯一真相源。

为了让你在开发时Neng得心应手，这里整理了一份常用的命令清单。熟练掌握它们，Neng让你的工作效率翻倍。

这些命令直接在与 AI 的聊天窗口中输入，是引导 AI 行为的指挥棒。

除了在 AI 聊天窗口操作，你也Ke以在终端通过命令行查kan项目状态。

Zui后我想聊聊支撑 OpenSpec 设计的几个关键原则。理解了这些，你才Neng真正用好它。

1. 棕地优先

hen多方法论要求你从零开始，或者重构整个项目才Neng使用。OpenSpec 不这么认为。它完全兼容存量项目。无论你的项目是十年前的遗留代码，还是刚刚起步的新项目，douKe以立即开始使用 OpenSpec。你不需要为了用工具而把家拆了。

2. 规范即真相

这可Neng是Zui重要的一点。在 OpenSpec 的世界里specs/ 目录中的内容就是法律。代码Ke以重构，人员Ke以流动，但规范必须清晰。这种思想迫使开发者在动手写代码前先思考清楚，极大地减少了返工的概率。

3. 人在回路

虽然我们大量依赖 AI，但 OpenSpec 从不主张“全自动”。AI 生成提案后必须经过人工的审查确认。这是为了防止 AI 的“幻觉”蔓延到代码库中。人类负责决策和方向，AI 负责实现和细节，这才是人机协作的Zui佳形态。

OpenSpec 不是一个Neng自动帮你写完整个应用的魔法棒，它geng像是一个严谨的项目管理器，恰好懂得如何与 AI 沟通。它通过规范化的流程，把 AI 的Neng力限制在可控的范围内，同时Zui大化地发挥了它的效率。

Ru果你受够了无休止的“AI 瞎猜”和“聊天记录考古”，不妨试试 OpenSpec。让每一次敲击键盘，dou建立在清晰、共识的基础之上。毕竟在软件工程的世界里清晰的逻辑永远比盲目的速度geng重要。