Claude Code 进阶必学：OpenSpec 规范驱动开发完整指南

过去几个月，用 Claude Code、Cursor,Opencode 等 AI 编码工具写项目，相信很多人和我一样，既兴奋又痛苦。

兴奋的是 AI 写代码的速度极快，几分钟就能出一个功能；痛苦的是需求一改就乱套、上下文频繁丢失、后期维护像拆炸弹、三个月后自己都看不懂当时为什么这么写……

直到我系统使用 OpenSpec，一切彻底改变了。

今天这篇长文，我将把 OpenSpec 从入门到进阶、从个人项目到团队落地的完整方法论一次性讲透。看完这篇文章，你将掌握一套让 AI 真正成为“靠谱 Senior Engineer”的工程化方法。

一、AI 编码的真实痛点与 OpenSpec 核心理念

当前 AI 编码面临四大核心问题：

• • 需求漂移：聊着聊着功能就变了,路走偏了。远离了需求。
• • 幻觉与不一致：AI 自信地写出不存在的接口或重复造轮子。
• • 文档缺失：代码写完却没有相关的文档，思路、流程完全没有。代码成了黑盒。
• • 维护灾难：新人接手或过段时间自己回头看，一头雾水。代码看不懂了，维护起来越来越复杂。 OpenSpec 正是为了解决这些问题而生。

OpenSpec 是一个轻量级spec-driven开源框架，专为 Claude Code、Cursor 等 AI 编码工具设计。其核心理念只有一句话：

在写任何一行代码之前，先和 AI 就“要做什么”达成明确一致，并把这个一致记录成结构化的 Living Spec（活的规范），作为整个开发过程的单一事实来源（Single Source of Truth）。

它采用经典的 Proposal → Apply → Sync → Archive 四步闭环工作流，把 AI 编码从“艺术创作”升级为“规范工程”。

三大核心技能（Claude Code 环境中）：

• • /opsx:propose：创建结构化需求提案
• • /opsx:apply：AI 严格按提案执行代码实现
• • /opsx:archive：完成归档，保持 Spec 与代码同步

二、5 分钟上手 OpenSpec

步骤 1：环境准备 确保你已在使用 Claude Code 或支持 Skill 的 AI 编码工具。

步骤 2：安装 Skills

npm install -g @fission-ai/openspec@latest

步骤 3：项目初始化 进入项目根目录，输入：

openspec init

系统会自动创建推荐目录结构：

openspec/
  ├── proposals/       # 所有提案记录
  ├── archives/        # 已归档的完成规范
  ├── project.md       # 项目整体规范
  └── config.yaml      # 可选配置

步骤 4：第一个小 Demo 我们来快速创建一个 工作日报记录与生成工具 工具。在 Claude Code 中输入：

/opsx:propose 创建一个支持记录每日工作内容的工作日报 CLI 工具，使用 Python 实现。
主要功能包括：
- 添加今日工作记录（支持多条）
- 查看今日/指定日期的工作记录
- 一键生成结构化日报（支持 Markdown 格式）
- 数据支持本地 JSON 文件持久化
- 支持简单分类（开发、会议、沟通、其他）

AI 会生成一份结构化的 Proposal。你审核通过后，执行：

/opsx:apply [提案名称或ID]

AI 就会严格按照提案生成代码、测试和文档。整个过程规范、可控、5-10 分钟即可跑通第一个完整功能。

三、核心实战：Proposal + Apply + Archive 全流程

这是 OpenSpec 最有价值的部分。我们用一个真实办公场景——在现有 FastAPI 项目中新增「费用报销申请与审批流程」模块 来完整拆解整个流程。

1. Proposal 阶段（最重要的一步）

Proposal 不是简单的需求列表，而是正式合同。推荐使用以下结构：

• • 背景
• • 目标
• • 变更范围（In Scope / Out of Scope）
• • Delta 变更（ADDED / MODIFIED / REMOVED）——特别适合修改现有项目
• • 技术方案与约束
• • 验收标准（Acceptance Criteria，可验证）
• • 非功能性需求（安全、性能、错误处理）
• • 风险与依赖

推荐 Prompt（直接复制使用）：

/opsx:propose 在现有 FastAPI 项目中新增费用报销申请与审批模块。
主要功能包括：
- 员工提交报销申请（金额、类别、日期、事由、发票照片上传）
- 支持多级审批流程（直属领导 → 财务）
- 审批状态流转（待审批、已通过、已拒绝）
- 个人报销记录查询与统计
- 导出 Excel 报销明细
严格基于现有项目结构，使用 SQLAlchemy + Alembic，保持接口风格一致。

AI 生成 Proposal 后，你必须仔细 Review，可让 AI 迭代修改，直到完全满意。

2. Apply 阶段（严格执行）

Proposal 通过后，执行：

/opsx:apply [提案ID]

AI 会生成 Design.md 和 Task.md，拆解任务，然后严格按 Spec 写代码、生成单元测试和集成测试、更新文档。

关键技巧：

• • 如果 AI 出现偏离，立刻停止，使用更新 Proposal 指令修正后再 Apply。
• • 支持多次增量 Apply，适合复杂功能。
• • 推荐结合“Plan 模式”让 AI 先思考架构再编码。

3. Archive 阶段（知识沉淀）

功能测试通过后，执行：

/opsx:archive [提案ID]

Archive 会将提案移入 archives 目录，生成快照，更新 project.md，保证 Spec 与代码长期同步。这一步极大提升了项目可维护性。

通过这个闭环，用户认证模块完成后，你会拥有完整的提案记录、代码实现、测试用例和归档快照，任何人接手都能快速理解。

四、进阶落地：真实项目案例与团队协作

案例 1：遗留中型 FastAPI 项目重构 一个运行 1 年多、1.8 万行代码的项目，技术债严重。使用 OpenSpec 后，我们把重构拆成多个 Proposal（统一错误处理、权限系统升级、缓存机制等）。3 个月后，新增功能速度提升近 2 倍，Bug 率显著下降，新人通过 archives 目录快速上手。

案例 2：从零构建带 Agent 的智能知识管理工具 先写顶层架构 Proposal，再按模块拆分子 Proposal（向量数据库、Agent 记忆、Web 界面）。在 Proposal 中明确写入架构约束（如必须使用 LangGraph）和非功能指标（响应时间、Token 控制、数据隐私），最终实现了 Spec 与代码高度一致。

团队协作最佳实践：

• • Git 分支：feature/openspec-xxx
• • PR 要求附上 Proposal 和 Archive 文件
• • 统一 config.yaml 配置（是否强制审批、自动测试等）
• • Code Review 重点看 Proposal 而非仅看代码

高级用法：

• • 与其他 Claude Skill 联动（安全扫描、文档生成）
• • 非功能需求量化写入（性能 < 200ms、符合 OWASP Top 10 等）
• • 自定义领域 Skill，构建团队专属规范体系

五、工具对比与使用建议

适用建议：

• • 个人小项目、快速实验：Cursor Rules 足够
• • 中大型项目、长期维护、团队协作：强烈推荐 OpenSpec
• • 想极致工程化：OpenSpec + 其他 Skill 组合使用

六、总结与福利

OpenSpec 不是又一个 Prompt 技巧，而是一套让 AI 编码从“随性创作”走向“规范工程”的方法论。它帮助我们把 AI 从“会写代码的工具”升级成“靠谱的团队成员”。

掌握 OpenSpec 后，你会明显感受到开发效率、代码质量和项目可维护性的质变。

行动起来：

• • 立刻在你的下一个项目中尝试 OpenSpec
• • 从一个小功能开始，养成“先 Proposal 再 Apply”的习惯

AI 写代码的速度已经够快了，真正拉开差距的，是我们管理 AI 的能力。