入职新公司两个月，为何只写了100行代码？

OpenSpec 是一个革命性的 AI 开发框架，它改变了传统的人机对话模式，通过规范化的命令和流程，让 AI 真正理解你的需求，从而精准地生成代码。本教程将带你从零开始，一步步掌握 OpenSpec，实现“一行代码不写，也能完成开发”的梦想。

安装与配置

在使用 OpenSpec 之前，你需要先完成环境安装和初始化配置。

安装 Node.js

OpenSpec 依赖于 Node.js 运行环境，请确保你的系统已安装。

• Linux 用户：使用包管理器安装，例如 sudo apt install nodejs 或 sudo yum install nodejs。
• Windows 用户：前往 Node.js 官网 下载安装包，按提示安装。

安装完成后，打开终端或命令提示符，验证版本：

# 验证 Node.js 版本
node --version

全局安装 OpenSpec

使用 npm（Node.js 包管理器）全局安装 OpenSpec：

# 使用 npm（推荐）
npm install -g @fission-ai/openspec@latest

小提示： 如果安装过程中间出现权限错误，可以尝试使用 sudo npm install -g @fission-ai/openspec@latest（macOS/Linux 用户）。

验证安装

安装完成后，检查 OpenSpec 版本：

# 检查版本
openspec --version

如果看到版本号，则表示安装成功。

配置 OpenSpec 命令

OpenSpec 默认提供 4 个标准命令：/opsx:propose、/opsx:explore、/opsx:apply、/opsx:archive。如果需要更多命令，可以启动配置向导：

# 启动配置向导
openspec config profile

# 交互式选择配置：
# 1. Delivery and workflows - 基础命令
# 2. Both (skills + commands) - 创建技能和命令
# 3. Custom Profile - 自定义配置（全选，使用↑↓+空格进行选择，[x]表示选中）

重点： 建议选择“3. Custom Profile”，这样可以启用所有可用命令，为后续开发提供更多灵活性。

项目初始化

OpenSpec 是项目级别的，你需要在每个项目目录中初始化它：

# 进入项目目录
cd your-project

# 初始化 OpenSpec
openspec init

初始化过程中，你会被提示选择 IDE（例如 trae）。选择后，项目目录中会新增两个文件夹：

• .traeskill：包含 IDE 的 skill 能力文件，即 OpenSpec 命令。
• openspec：OpenSpec 主文件夹，用于存放规范、变更等文件。

初始化后的目录结构如下：

openspec/
├── specs/            # 主规范（当前系统行为的权威基准）
│   └── /
│       └── spec.md
├── changes/          # 提议中的变更（每个变更独立文件夹）
│   └── /
│       ├── proposal.md  # 为什么做、做什么
│       ├── design.md    # 如何实现
│       ├── tasks.md     # 实现任务清单
│       └── specs/       # Delta 规范（正在变化的部分）
│           └── /
│               └── spec.md
└── config.yaml       # 项目配置（可选）

核心命令与功能

OpenSpec 提供了一套完整的命令，用于规范 AI 开发流程。以下是核心命令及其功能：

openspec-explore (探索)

在正式提交变更之前，使用此命令来思考想法、调查问题、澄清需求。它可以帮助你：

• 理解需求，并与 AI 确认细节。
• 扫描项目代码，分析现有架构。
• 提出多个技术方案供你选择。

注意： 此命令不会产生任何文件，结果仅存在于 AI 的对话上下文中。它比较耗费 token，适合需求模糊或复杂的情况。

openspec-propose (提议)

创建新变更并一步生成所有规划产物。该命令会输出四个核心文件：

• proposal.md：描述为什么做、做什么。
• specs//spec.md：Delta 规范，定义正在变化的部分。
• design.md：技术方案，描述如何实现。
• tasks.md：实现任务清单，带复选框。

重点： 创建变更时，请遵循“小变更”原则。不要一次性提交一个很大的功能，否则会导致运行时间长、token 消耗巨大、后期维护困难。建议将大需求拆分为多个小变更，例如一个接口或一个小功能对应一个变更。

openspec-apply-change (应用)

实现变更中的任务。它会逐步处理任务列表，编写代码并勾选完成项。此命令会自动编译并修复代码，确保项目能正常运行。

小提示： 在执行此命令时，尽量不要操作代码，让 AI 自动完成所有任务。如果发现 bug，可以在命令执行后通过自然语言告知 AI 进行修改。

openspec-verify-change (验证)

验证实现是否与变更产物匹配。从完整性、正确性和一致性三个维度检查。它会：

• 检查 tasks.md 中的所有任务是否已完成。
• 验证规范中的所有需求是否都有对应代码。
• 比对设计决策是否在代码结构中有体现。

此命令可选，但建议在归档前执行，确保代码质量。

openspec-archive-change (归档)

归档已完成的变更。它会将变更文件夹移至 openspec/changes/archive/ 目录下，并同步 Delta 规范到主规范。归档后，你可以将变更推送到 Git 仓库，供团队使用。

实战操作：完整流程演示

我们将从一个实际需求出发，演示如何使用 OpenSpec 完成开发，全程无需手动编写代码。

步骤一：使用 openspec-explore 澄清需求

如果你的需求比较模糊，或者需要和 AI 确认细节，可以首先执行此命令。例如，从禅道获取任务：

/openspec-explore mcp获取任务id：2213913，使用getUserTaskList新增两个接口：diff 和 log ，log用于列表的查询，diff用于详情的查询

AI 会扫描你的项目代码，分析现有架构，并输出思考结果。如果 AI 对需求有疑问，它会主动提问，你可以补充细节。

注意： 如果禅道上没有对应的任务，可以直接将 PRD（产品需求文档）粘贴给 AI。

步骤二：使用 openspec-propose 创建变更

在需求澄清后，执行以下命令创建变更：

/openspec-propose 补充几个点：用户点击日志的时候调用log接口，就会进入到第二个图，点击查看的按钮就会调用diff接口

AI 会自动生成四个文件，并输出变更产物。你可以查看这些文件，如果对产物有疑问，可以继续补充：

变更的产物加几个补充点：1.编码的风格要按照现有的代码进行编码2.与数据库相关的操作都写在Repository类3.我问了产品经理，他说外面列表数据可能会有很多条变更记录

重点： 使用自然语言描述，你可以不断规范 AI 做什么以及怎么做，确保最终代码符合预期。

步骤三：使用 openspec-apply-change 实现代码

直接执行命令，让 AI 自动完成所有任务：

/openspec-apply-change

AI 会逐步处理 tasks.md 中的任务，编写代码并自动编译修复。完成后，所有任务会标记为已完成。

小提示： 如果发现代码有 bug，可以直接通过自然语言告诉 AI 进行修改，无需手动编辑。

步骤四：使用 openspec-verify-change 验证代码

检查代码是否与产物匹配：

/openspec-verify-change

建议将 PRD 再次提供给 AI，以确保验证的准确性。此命令会输出关键问题数和警告，帮助你判断是否满足归档条件。

步骤五：使用 openspec-archive-change 归档

确认需求已完成，执行归档：

/openspec-archive-change openspec-changes-cost-config-diff-log

归档后，变更文件夹会被移动到 openspec/changes/archive/2026-07-13-cost-config-diff-log。如果以后需要修改 bug，可以直接告诉 AI：

openspec/changes/archive/2026-07-13-cost-config-diff-log 有个bug：前端传入超长文本，后端报错

AI 会自动找到对应的变更产物，并修改代码。

特色功能与拓展

MCP 服务

MCP（Model Context Protocol）服务可以让你通过自然语言获取第三方系统（如禅道）的数据。如果你的公司有 MCP 服务，配置后即可使用。如果没有，也可以直接将产品文档丢给 OpenSpec，效果一样。

Rule 与 Skills

你可以使用工具级别的 rules 和 skills，通常放在 C:\Users\用户名\.trae-cn 文件夹下。它们会随着 IDE 启动而生效，规范 AI 的编码行为。

智能体

创建自定义智能体，可以让 AI 输出更专业。你可以定义智能体的角色、知识库和行为模式，以满足特定项目需求。

其他 IDE 支持

OpenSpec 是一个框架，支持市面上主流的 IDE。不同 IDE 的命令名称可能不同，例如在 Trae 中命令为 /openspec-apply-change，在其他 IDE 中可能为 /opsx:apply。初始化时选择的 IDE 决定了命令名称，具体可查看对应 IDE 项目文件夹中的 skill 文件。

常见问题与解决方案

Q1：安装 Node.js 时提示“命令未找到”？

请确保 Node.js 已正确安装，并且其路径已添加到系统环境变量中。可以尝试重启终端或命令提示符。

Q2：npm 安装 OpenSpec 失败，提示权限不足？

使用管理员权限运行命令提示符（Windows），或在命令前添加 sudo（macOS/Linux）。

Q3：初始化 OpenSpec 时，找不到对应的 IDE 选项？

请确保你的 IDE 已安装，并且 OpenSpec 支持该 IDE。可以查看官方文档获取支持的 IDE 列表。

Q4：执行 openspec-apply-change 时，AI 运行时间过长？

这通常是因为变更太大。请遵循“小变更”原则，将大功能拆分为多个小变更。如果任务已经很大，可以考虑手动终止，再重新创建更小的变更。

Q5：AI 生成的代码不符合预期？

在 openspec-propose 阶段，多与 AI 沟通，补充细节。使用自然语言描述你的编码规范、技术选型等。同时，可以在 openspec-apply-change 后，通过自然语言让 AI 修改 bug。

总结

OpenSpec 通过规范化的命令和流程，改变了人与 AI 的协作模式。它让 AI 真正理解你的需求，精准输出代码，大幅减少手动编码量。通过本教程，你可以从零开始，掌握 OpenSpec 的安装、配置和实战流程，实现“一行代码不写，也能完成开发”的目标。

AI 在改变世界，而 OpenSpec 是让 AI 为你所用的利器。学起来，拥抱这个新时代吧！