夜雨聆风你让 AI 写个登录页，它给你整出一套宇宙级架构；你让它加个验证码，它把整个认证模块重构了——需求说东它写西，代码风格一天一个样。
这不是 AI 的锅，是你没给它"规矩"。
今天介绍一个神器：OpenSpec——给 AI 编码助手一份"说明书"，让它照着你的规范干活，不再自由发挥。
一、OpenSpec 是什么？
一句话：OpenSpec 是一个让 AI 编码助手按规范写代码的工具。
你可以把它想象成开发团队的"菜谱"。AI 是厨师，菜谱写清楚了每一步该怎么做——用什么食材、什么火候、什么顺序。没有菜谱，厨师只能凭感觉乱做；有了菜谱，每道菜都稳定出品。
三个核心能力：
· 对齐需求：把你的需求写进 proposal.md，AI 有据可查，不再跑偏
· 规范代码：统一命名规则、项目结构、代码风格，不管谁用哪个 AI 工具都产出一致
· 记录变更：每个功能的从提案到上线，全程留痕，随时追溯
硬指标：
GitHub 57,000+ Stars，社区活跃度极高
纯本地文件系统操作，不需要 API Key，不需要 MCP，不需要装额外服务
支持 25+ 种 AI 编码助手集成，本文以 Claude Code 为例讲解
二、OpenSpec 能帮你做什么？
场景 1：让 AI 按规范写代码
团队有命名规范、目录结构约定，但 AI 编码助手不知道这些规范，每次生成的代码风格都不一样。OpenSpec 把规范写进 specs 文件，AI 自动遵守——不管今天用 Cursor 还是明天用 Claude Code，代码风格始终统一。
场景 2：多人协作，工具不同但产出一致
团队里有人用 Cursor，有人用 Claude Code，有人用 Windsurf——不同工具生成的代码风格各异，合并代码像打仗。OpenSpec 统一规范，不管用什么 AI 工具，产出都符合团队标准。
场景 3：老项目直接上手（不用重构）
不是只有新项目才能用。已有项目直接 openspec init，OpenSpec 自动分析现有代码结构，生成初始规范文档。不用重构，不用迁移，直接在老项目上开始规范开发。
一句话总结：OpenSpec 是让 AI 编码助手从"麻烦"变"助手"的关键桥梁。
三、裸用 AI 和加 OpenSpec 有什么区别？
| 裸用 AI 编码助手 | + OpenSpec | |
|---|---|---|
| 需求传达 | 口头描述，容易跑偏 | 写进 proposal.md，有据可查 |
| 代码质量 | 随 AI 发挥，风格不一 | 按 specs 规范写，风格统一 |
| 可追溯性 | 对话记录看完就丢 | 变更全程记录在文件里 |
| 多人协作 | 各用各的工具，代码打架 | 统一规范，产出一致 |
| 上手门槛 | 零门槛，但质量不可控 | 5 分钟初始化，质量可控 |
| 额外配置 | 可能要配 API Key、MCP | 纯文件操作，无需任何配置 |
四、5 分钟快速上手
步骤 1：安装 OpenSpec
前提：Node.js 版本 ≥ 20.19.0（没有的话先装 Node.js）。
npm install -g @fission-ai/openspec@latest安装完验证一下：
openspec --version步骤 2：初始化项目
进入你的项目目录，选择 Claude Code 初始化：
openspec init --tools claudeOpenSpec 会自动完成三件事：
· 创建 openspec/ 目录（config.yaml、specs/、changes/）
· 生成 .claude/skills/openspec-*/ 目录，每个命令一个 Skill 文件
· 这些 Skill 文件就是 Claude Code 的"说明书"，Slash command 的定义写在这里
关键一步：初始化完成后，必须重启 Claude Code！
Skill 文件是启动时加载的，不重启命令不会生效。重启后在聊天框输入 /opsx: 应该能看到命令补全列表。
初始化完成后，建议编辑 openspec/config.yaml 的 context: 字段，填写项目的技术栈和编码规范。Claude Code 每次执行 /opsx: 命令时都会读取。
提示：路径不要用中文，避免报错！
步骤 3：认识核心目录（以 Claude Code 为例）
初始化完成后，项目结构如下：
your-project/
├── openspec/
│ ├── config.yaml ← 项目配置（schema、context、rules）
│ ├── specs/ ← 事实来源：描述系统当前的行为规范
│ │ └── auth/ ← 按领域组织（如 auth, payment）
│ │ └── spec.md
│ ├── changes/ ← 变更提案：每个功能一个文件夹
│ │ ├── add-captcha/
│ │ │ ├── proposal.md ← 为什么做、做什么（意图、范围）
│ │ │ ├── design.md ← 怎么做（技术方案，可选）
│ │ │ ├── tasks.md ← 实施清单（带复选框）
│ │ │ └── specs/ ← 增量规范：描述具体变动
│ │ │ └── auth/
│ │ │ └── spec.md ← 用 ADDED/MODIFIED/REMOVED 标记
│ │ └── archive/ ← 已完成的变更归档（按日期组织）
│ │ └── 2026-07-20-add-captcha/
├── .claude/ ← Claude Code 的 Skill 文件
│ └── skills/
│ ├── openspec-new/
│ ├── openspec-ff/
│ ├── openspec-apply/
│ └── openspec-archive/
└── ...（你的项目代码）五个关键位置：
config.yaml：项目配置入口，context 字段记录技术栈和编码规范
specs/：项目的"事实来源"，记录系统当前的行为规范，按领域组织
changes/：所有正在进行的变更提案，每个变更一个文件夹
changes/*/proposal.md：每个变更的需求描述——为什么做、做什么
changes/archive/：已完成的变更归档，按日期组织
五、工作流：new → ff → apply → archive
OpenSpec 1.0 通过 openspec init --tools claude 初始化后，Claude Code 默认获得 10 个命令，覆盖完整开发流程。最常用的核心 4 步：
OpenSpec 核心工作流：
|
/opsx:new 创建变更 |
/opsx:ff 快速规划 |
/opsx:apply AI实现 |
/opsx:archive 归档完成 |
/opsx:new <change-name>：创建一个变更文件夹，初始化 proposal.md 框架
/opsx:ff：一键生成所有规划文档（proposal、specs、design、tasks）
/opsx:apply：AI 按 tasks.md 逐步实现代码
/opsx:archive：归档完成，自动合并规范并移入 changes/archive/
此外还有 6 个进阶命令——/opsx:continue（逐步生成）、/opsx:verify（质量检查）、/opsx:sync（手动同步规范）、/opsx:explore（先思考再动手）、/opsx:bulk-archive（批量归档）、/opsx:onboard（交互教程）。
输入 /opsx: 就能看到 Claude Code 补全所有可用命令，不需要记。
六、实战演示：让 Claude Code 给登录页加验证码
步骤 1：创建变更（new）
在 Claude Code 的聊天窗口输入：
/opsx:new add-captcha-to-login
OpenSpec 会创建变更文件夹 openspec/changes/add-captcha-to-login/，生成空的 proposal.md 框架。
你可以在 proposal.md 里填写需求背景和目标。比如：
为登录页面添加图形验证码功能，防止暴力破解。验证码在用户点击登录时生成，5 分钟过期，支持刷新。
小贴士：如果你还不确定要做什么功能，可以先 /opsx:explore 让 Claude 帮你梳理思路，零风险，不会产生任何文件。
步骤 2：快速生成规划（ff）
提案写好后，输入：
/opsx:ffClaude Code 会一次性生成四份文档：
· proposal.md：需求提案（你刚填的 + AI 补充）
· specs/：功能规范——验证码应该怎么实现（用 ADDED/MODIFIED/REMOVED 标记）
· design.md：设计方案——技术选型、接口设计
· tasks.md：任务清单——一步步要做什么（带复选框）
步骤 3：让 Claude Code 按计划实现（apply）
确认规划没问题后，输入：
/opsx:applyClaude Code 会按 tasks.md 里的任务清单，逐步实现代码。每完成一个任务，自动勾选复选框。你可以随时打开文件检查代码，不满意就手动修改。
步骤 4：归档完成（archive）
代码写完、测试通过后，输入：
/opsx:archive
OpenSpec 把变更从 changes/add-captcha-to-login/ 移到 changes/archive/2026-07-20-add-captcha-to-login/，同时自动将增量规范合并到顶层 specs/。
成就达成 ✓
流程总结：
|
/opsx:new 创建 |
/opsx:ff 规划 |
/opsx:apply 实现 |
/opsx:archive 归档 |
四步走，从需求到代码，全程有据可查。
七、避坑指南 + 高级技巧
四个常见坑
坑 1：init 后命令不生效
在 Claude Code 里输入 /opsx: 看不到命令补全。
原因：Skill 文件是启动时加载的，openspec init 之后没重启。
解决方案：重启 Claude Code。如果重启后还是没有，终端执行 openspec update 再重启。
坑 2：提案写得太模糊
"给登录页加点安全功能"——这种描述 AI 只能自由发挥，结果大概率不符合你的预期。
解决方案：写清楚目标，比如"添加图形验证码，防止暴力破解，5 分钟过期"。不用写技术细节，但目标必须明确。
坑 3：忘记归档变更
完成开发后不执行 /opsx:archive，变更一直留在 changes/ 里，主规范文档不会更新。
解决方案：完成必归档，养成习惯。
坑 4：路径用中文
项目路径或文件名包含中文，在某些系统上会报错。
解决方案：路径和文件名统一用英文。
两个高级技巧
技巧 1：Skill 文件与 CLAUDE.md 的关系
Claude Code 启动时会同时读取两个东西：
· .claude/skills/openspec-*/ — OpenSpec 的 Slash command 定义（由 openspec init 生成）
· 项目根目录的 CLAUDE.md — 你自己写的架构约定
两者互补。你在 CLAUDE.md 里写的规则（比如"所有 Redis 操作必须用 Redisson"），/opsx:propose 生成 design.md 的时候 Claude 是能看到的，不需要在 OpenSpec 里重复写。Skill 文件管"怎么做 SDD 流程"，CLAUDE.md 管"这个项目有什么特殊规矩"。各司其职，天然配合。
技巧 2：增量规范与 ADDED/MODIFIED/REMOVED 标记
每个变更都有自己的 specs/ 文件夹（增量规范），用 ADDED、MODIFIED、REMOVED 三种标记来描述具体变动。归档后，增量规范合并到顶层 specs/（事实来源）。这意味着你可以随时查看某个功能的历史演进——它当初是怎么规划的、做了什么改动、最终实现了什么。
八、总结：OpenSpec 的真正价值
需求对齐：告别"你说的和它做的不是一回事"
规范统一：不管用什么 AI 工具，代码风格始终一致
全程留痕：每个功能从提案到归档，完整记录
OpenSpec 不是让 AI 变聪明，而是让 AI 变可控。聪明但不可控的助手，不如可控但稳定产出。
现在就用 OpenSpec 初始化一个新项目，体验规范开发的爽感：
npm install -g @fission-ai/openspec@latest
openspec init --tools claude
# 重启 Claude Code！两条命令，5 分钟上手。
资源
OpenSpec 官网：https://openspec.dev
GitHub 仓库：https://github.com/Fission-AI/OpenSpec
OpenSpec 文档：https://openspec.pro/getting-started
觉得有用？转发给需要的朋友，一起让 AI 编码助手不再乱写代码。
