概述

OpenSpec 是一款专为 AI 编程设计的规范驱动开发框架。主要目标是让开发者与 AI 在写代码前先对齐需求，避免“凭感觉聊天”导致的返工。它通过结构化规范把模糊计划，比传统的 vibe coding 更加详尽。主要特点的观点是，

• 让项目更加规范。按需求文档逐步推进，一步步来。
• 融合 Harness Engineering的特性。
• 适合长期维护、多人协作的项目。话说回来，

者痛点一览

在实际项目中。很多团队遇到以下难题：

• 需求不清晰导致返工频繁：缺乏可审查的需求文档，让后期实现与原始想法偏差。
• 协作失效：多人接手同一代码库时缺少统一规格导致理解成本高。
• 持续集成与发布难度大：变更频繁、历史记录不完整，难以快速回滚。
• 技术债务累积：项目演进中功能堆砌而缺乏清晰拆分和优先级排序。

快速安装

npm install @openspeccn/openspec --registry=https://registry.npmjs.org

在 VS Code 中使用 OpenSpec

1. Create an empty project folder and open it in VS Code.
2. Avoid running commands in unrelated terminals.
3. Select project folder terminal .

A small snippet to bootstrap:

# Ensure current directory is your project folder
npx okcode # Initialize Claude code trust for this directory
openspec init # Create OpenSpec configuration files

The wizard will guide you through selecting tools:

1. Select corresponding tool by pressing Enter.

If installation succeeds you’ll see two new folders inside your project:

OpenSpec 文件夹说明

• .claude
  • 说到/opsx。explore – 用 AI 探索产品新功能 / 新方案，一般在开始项目前使用，用来生成详细规格文档。
  • /opsx这方面，new – 开始新的变更。
  • 再看/opsx，archive – 项目打包归档。
  • /opsx的观点是，apply – 实施任务。其实，

• : 存放规格文件。

• : 全局配置文件，可定义技术方法、样式等作为后期交互参考。

初始化使用流程

关闭 Claude code 界面与 VS Code 的终端；选中「config.yaml」。点击右上角 Claude code 图标，就可以完成初始化配置。

产品探索 - opsx:explore 命令示例

A typical exploration session starts with a prompt like this:

/opsx:explore 开发一款理财记账。主要功能是记录消费与收入
Yes
# 输出包含场景概念图和自然问题列表

SUGGESTIONS TO CLARIFY MVP:\
• “理财”重量级别\
• 多币种 / 单币种支持\
• 多账户类型\
• 使用者激励方式
使用者可以根据业务主要选择回答这些问题，从而形成可执行的规格文档。下面是一段使用者回答示例：
"理财"重量级别：中等；加入预算/分类统计/趋势图；币种支持人民币+美元，多账户配置；每日微信提醒，月底收入图表+趋势预测。\
继续探索…，此过程将自动生成 proposal.md / design.md / task.md 三个文件，为后续实现奠定基础。

创建项目规格说明文件夹 - opsx:new 命令示例

A new spec folder is created under `` when you run:
/opsx:new 

"项目名"未输入时会提示默认名称或要求补充名称，接下来在 `/changes//` 下创建三份文件：proposal.md / design.md / task.md。
**proposal.md** – 项目目标与变更概览；\
**design.md** – 技术设计细节；\
**task.md** – 后续任务清单。

根据 task.md 执行项目任务 - opsx:apply 命令示例

The `apply` command reads `task.md` and scaffolds necessary files or runs automated scripts to move project forward.

阶段性项目归档 - opsx:archive 命令示例 

This command packages completed work into a snapshot under `/archive//`. It helps maintain clean history and facilitates rollback if needed.

& 推荐实践