OpenSpec 最佳实践：从“凭感觉”到“照单执行”

OpenSpec 在 Trae 与 Cursor 上的最佳实践：从“凭感觉”到“照单执行”

引言：AI 编程的“凭感觉”困境

想象一下这个场景：周四下午，产品经理找到你：“帮忙加个用户管理功能吧，就是基本的增删改查，应该很简单。”你打开 Cursor，输入需求，AI 很快生成了代码。但你一看——只有简单的列表展示，没有权限控制，没有状态管理，没有批量操作。

于是你开始第二轮、第三轮对话，不断补充需求细节：RBAC 权限、状态转换规则、事务支持……30 分钟过去了，你还在和 AI “拉扯”。

这就是典型的Vibe Coding（凭感觉编码）——你和 AI 在“边聊边改”的低效循环中浪费时间，代码质量参差不齐，最终还是要大量返工。

OpenSpec 正是为了解决这个问题而生。

什么是 OpenSpec？

OpenSpec 是一个 AI 原生的规范驱动开发（Spec-Driven Development）系统。它的核心理念只有一句话：在写任何一行代码之前，先和 AI 就“要做什么”达成明确一致，并把这个共识记录成结构化的规范文件，作为整个开发过程的单一事实来源。

OpenSpec 支持Claude Code、Cursor、Trae 等 22+ 种 AI 编程工具，完全不锁定特定工具。它通过三个核心机制让 AI 编码变得可控：

1. 文件化需求：需求不再是聊天记录中的几句话，而是存在项目里的 Markdown 文件
2. Delta Spec 机制：改需求时只需描述“什么在变化”，让规范演进清晰可追溯
3. 三层验证：从格式到语义到业务逻辑，确保 AI 理解的和你想表达的是同一回事

💡一个形象的类比：如果 AI 开发是盖楼，OpenSpec 就是建筑施工图——明确“做什么、做成什么样”，避免施工方偏离设计方向。

Part 1：在 Trae 上使用 OpenSpec

场景设定

假设你是一位前端开发者，使用Trae CN（字节跳动推出的 AI 原生 IDE）开发一个日历功能。你希望用 OpenSpec 来规范整个开发流程。

第一步：安装 OpenSpec CLI

在终端执行以下命令进行全局安装：

npminstall-g@fission-ai/openspec@latest

安装完成后，运行openspec -V检查版本，确认安装成功。

第二步：初始化项目

进入你的项目目录，执行初始化命令：

cdyour-project openspec init

初始化时，OpenSpec 会提示你选择使用的 AI 工具。由于早期版本的 OpenSpec 初始化选项中暂未直接列出 Trae，你可以选择Other Tools（适用于 VS Code 等）。

初始化后，项目目录下会生成以下结构：

项目根目录/ ├── AGENT.md # 项目级规范（需手动配置） └── openspec/ ├── AGENTS.md # OpenSpec 详细规范 ├── project.md # 项目知识库 ├── specs/ # 已实现能力规范 └── changes/ # 变更提案

第三步：手动配置 Trae 项目规则

关键步骤来了：老版本的 Trae 不会自动读取AGENT.md，你需要手动将规范内容添加到 Trae 的“项目规则”中（新版本Trae会自动加载）。

操作方式很简单：打开 Trae 的设置 → 找到“项目规则”或类似配置入口 → 将openspec/AGENTS.md中的内容复制进去。这样，Trae 在每次对话时就能“学习”到你的项目规范了。

第四步：配置 OpenSpec 完整工作流

OpenSpec 默认只开了核心命令（如 explore、apply、archive），需要手动解锁全部能力。

在终端执行：

openspec config profile

连续两次回车，选择全部的 skills 和 commands。推荐先选择Onboard和Continue change，再按需选择更多。

然后执行更新命令：

openspec update

重启 Trae 后，你就可以看到新增的 Skills 了。

最后，在 Trae 的设置 → 对话流 → 命令运行方式中新增命令白名单，这样在 Solo 模式对话中就能直接识别和执行 OpenSpec 的 skills。

第五步：开始使用 —— 日历功能实战

在 Trae 的 Solo 模式下，输入：

/opsx:onboard 写一个最简单的日历

AI 会根据 onboard 流程自动生成：

• proposal.md：需求提案，解释为什么做这个功能
• design.md：技术设计方案
• tasks.md：任务拆解清单
• spec.md：详细的功能规格说明

随后，AI 会按照这些文档逐步生成项目代码，并依据规格说明进行测试验收。

如果在开发过程中有任何修改需求，使用/opsx:continue命令即可更新文档和代码。

功能完成后，使用/opsx:archive归档这次变更。

Trae 常用 OpenSpec 命令速查

命令	描述
/opsx:new <change-name>	创建新的 OpenSpec 变更，逐步创建各个 artifact
/opsx:propose <change-name>	创建变更并生成所有 artifact
/opsx:apply <change-name>	实现变更中的任务
/opsx:archive <change-name>	归档完成的变更【8L22】
/opsx:explore	分析问题，思考解决方案
/opsx:continue <change-name>	继续未完成的变更
/opsx:onboard	引导新用户使用 OpenSpec

🎯 Trae 最佳实践小结

1. 初始化时选择Other Tools：虽然 Trae 未被直接列出，但完全可用
2. 手动配置项目规则：这是 Trae 上使用 OpenSpec 的关键一步
3. 解锁全部 commands：用openspec config profile开启完整工作流
4. 善用/opsx:onboard：这是上手最快的方式，让 AI 帮你生成完整的规范文档

Part 2：在 Cursor 上使用 OpenSpec

场景设定

假设你是某电商公司的后端开发，需要为订单系统新增一个“用户管理”功能，包含：RBAC 权限控制、用户状态管理（激活/禁用/删除）、批量操作、搜索和筛选。你希望用 OpenSpec 在 Cursor 中规范地完成这个任务。

第一步：安装与初始化

和 Trae 一样，首先安装 CLI：

npminstall-g@fission-ai/openspec@latest

然后在项目目录下初始化：

cdyour-project openspec init

这次，在初始化提示中选择Cursor。OpenSpec 会自动为 Cursor 生成适配的目录结构。

第二步：理解 Cursor 的集成机制

OpenSpec 在 Cursor 中的集成主要通过.cursor/rules/和.cursor/skills/目录实现。初始化后，Cursor 会自动识别这些规范文件，在每次对话时加载。

核心工作流程是：

• Cursor 启动时自动读取规范文件
• 当用户请求涉及“提案/规范/变更/计划”等关键词时，自动加载详细规范
• AI 严格按照规范执行任务

第三步：发起变更提案

在 Cursor 的对话中输入：

/openspec:proposal 实现用户管理功能，包含RBAC权限控制、用户状态管理、批量操作、搜索筛选

AI 会根据规范生成完整的变更提案，包括：

proposal.md—— 解释为什么要做、影响范围是什么：

## Why 为订单系统提供完整的用户管理能力，支持管理员对用户进行精细化管理。 ## What Changes - 新增用户列表页面（支持分页、搜索、筛选） - 新增用户创建/编辑/删除功能 - 新增 RBAC 权限控制（管理员/普通用户） - 新增用户状态管理（active / disabled / deleted） - 新增批量操作（批量激活、批量删除） ## Impact - 新增文件：`UserManagement.jsx`、`userService.js`、`useUserManagement.js` - 修改文件：`App.jsx`（添加路由）、`api/index.js`（新增接口）

spec.md—— 详细的验收场景（这是 AI 编码的“法律”）：

## Requirement: 用户列表展示 系统应以表格形式展示所有用户，支持分页。 Scenario: 成功加载用户列表 - GIVEN 系统中存在至少一个用户 - WHEN 管理员访问用户管理页面 - THEN 显示用户列表，包含姓名、邮箱、角色、状态、操作列 ## Requirement: 用户状态转换 系统应支持用户状态的有序转换。 Scenario: 激活用户 → 禁用用户（可逆） - GIVEN 用户状态为 active - WHEN 管理员执行“禁用”操作 - THEN 用户状态变为 disabled Scenario: 激活用户 → 删除用户（不可逆） - GIVEN 用户状态为 active - WHEN 管理员执行“删除”操作 - THEN 用户状态变为 deleted，且不可恢复

design.md—— 技术决策：

## Context 订单系统的用户管理模块，需与现有 RBAC 体系兼容。 ## Decisions - 权限控制：复用现有 RBAC 中间件，基于资源进行权限校验 - 状态管理：使用 Zustand 管理用户列表状态 - 批量操作：后端使用数据库事务保证原子性 - API 设计：RESTful 风格，支持分页参数 `page` 和 `size` ## Risks - 批量删除操作风险较高 → 需二次确认弹窗 - 状态转换规则复杂 → 前端需校验转换合法性

tasks.md—— 可执行的任务清单：

## 1. 前端页面开发 - [ ] 1.1 创建 UserManagement 页面组件 - [ ] 1.2 实现用户列表表格（含分页） - [ ] 1.3 实现搜索和筛选功能 - [ ] 1.4 实现用户创建/编辑弹窗 - [ ] 1.5 实现用户状态切换操作 ## 2. 权限控制 - [ ] 2.1 集成 RBAC 权限校验 - [ ] 2.2 根据角色控制页面元素显隐 ## 3. 批量操作 - [ ] 3.1 实现多选功能 - [ ] 3.2 实现批量激活/删除（含二次确认） ## 4. 测试与验收 - [ ] 4.1 单元测试覆盖核心逻辑 - [ ] 4.2 端到端测试覆盖主要流程

第四步：审查规范

这是最关键的一步。在 AI 开始写代码之前，仔细审查这四个文件：

• spec.md里的场景是否覆盖了所有边界情况？
• design.md的技术选型是否合理？
• tasks.md的任务拆解是否完整？

此时修改成本最低——你只需要改动几行 Markdown，而不是等代码写完后再返工。

第五步：实施

审查通过后，在 Cursor 中输入：

/openspec:apply

AI 会严格按照tasks.md中的清单，一步一步地编写代码。每完成一个任务，自动标记为[x]。你可以随时检查进展。

第六步：归档

功能开发完成并通过测试后：

/openspec:archive

这个命令会将变更文件夹移至archive/目录作为历史记录，并将规范合并到主规范库中。

🎯 Cursor 最佳实践小结

1. 初始化时选择Cursor：OpenSpec 会自动生成适配的目录结构
2. 充分利用自动读取：Cursor 会自动加载规范文件，无需手动配置
3. 重视规范审查环节：在apply之前仔细审阅spec.md和design.md
4. 善用/openspec:propose：让 AI 帮你生成完整的规范文档初稿

总结：Trae vs Cursor 使用对比

对比维度	Trae	Cursor
初始化	选择Other Tools	选择Cursor
规范加载	需手动配置到“项目规则”	自动读取.cursor/rules/
命令方式	/opsx:xxx	/openspec:xxx
上手难度	稍高（需手动配置）	较低（开箱即用）
核心流程	提案 → 审查 → 实施 → 归档	提案 → 审查 → 实施 → 归档

核心 takeaways

无论你用的是 Trae 还是 Cursor，OpenSpec 带来的核心价值是一致的：

1. 告别“AI 失忆症”：规范存储在项目文件中，AI 和人随时查阅，不会因切换对话而丢失上下文
2. 让 AI 更“听话”：AI 的产出变得可预测、可控制，不再是“黑盒”操作
3. 团队协作更顺畅：统一的规范文件让所有人都遵循同一套标准
4. 质量可追溯：每个变更从提案到归档全流程可查，便于复盘

OpenSpec 将 AI 编程从依赖“感觉”的艺术创作，转变为基于规范的工程实践。无论你选择 Trae 还是 Cursor，这套方法论都能让你的 AI 开发流程更加可控、高效、可追溯。