OpenSpec + Codex从落地到实践

OpenSpec + Codex 前后端开发使用教程

一、概述

1.1 为什么要用 OpenSpec + Codex？

在 AI 辅助编程中，最常见的痛点是什么？需求还没想清楚就让 AI 写代码、讨论结论散落在聊天记录里、AI 根据不完整上下文"猜实现"。OpenSpec 解决的就是这个问题------在写代码之前，先把"要做什么"说清楚、写明白。

OpenSpec 是一个规格驱动开发（Spec-Driven Development）框架，它的核心理念是：先把需求转化为可执行的规范文档，再让 AI 按规范实现。而 Codex 则是执行者，负责根据这些规范文档生成代码、补测试、做 Review。

一句话总结：OpenSpec 管"改什么、为什么改、验收标准是什么"，Codex 管"怎么实现"。

1.2 适用场景

新功能开发：从 0 到 1 构建前后端功能
现有项目改造：在已有代码上做功能迭代（1 → n）
前后端协同：统一前后端契约，避免前端臆造字段、后端未返回等问题
团队协作：规范文档作为人和 AI 达成一致的"锚点"

二、环境安装与初始化

2.1 安装 OpenSpec

OpenSpec 有两种版本可选：

中文版（推荐） ：

bash 复制代码

sudo npm install -g @studyzy/openspec-cn

英文原版：

bash 复制代码

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

后续升级：

bash 复制代码

npm install -g @studyzy/openspec-cn@latest

2.2 安装 Codex CLI

bash 复制代码

npm i -g @openai/codex@0.116.0

2.3 初始化 OpenSpec 项目

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

bash 复制代码

cd your-project
openspec-cn init --tools codex

初始化过程中，系统会提示你选择使用的 AI 工具，选择 Codex 即可。

初始化完成后，OpenSpec 会在项目中生成以下内容：

openspec/ 目录：存放所有规范文档
.codex/skills/ 目录：Codex 专用的技能文件
~/.codex/prompts/ 目录：Codex 的全局命令文件

⚠️ 重要提示 ：Codex 使用的是 $openspec-* 技能调用方式（如 $openspec-propose），而非 /opsx:* 斜杠命令。老版本的 /opsx:propose 等命令在 Codex 中已被废弃。

三、核心工作流

OpenSpec + Codex 遵循 "先讨论 → 写入 OpenSpec → 再实现代码 → 最后归档" 的四步工作流。

3.1 核心命令对照表

功能	命令格式	说明
创建变更提案	`$openspec-propose`	生成 proposal.md、design.md、tasks.md 等
实施变更	`$openspec-apply-change`	按规范文档生成代码
验证实现	`$openspec-verify-change`	校验代码是否与规范对齐
归档变更	`$openspec-archive-change`	完成后归档，更新主文档
探索调研	`$openspec-explore`	探索和调研需求想法

3.2 步骤一：创建变更提案（Propose）

当你有一个新需求时，不要直接让 Codex 写代码，而是先创建 OpenSpec 变更。

在 Codex 对话框中输入：

复制代码

$openspec-propose 用户认证功能

或者用自然语言触发：

"帮我创建一个 OpenSpec 提案，用于添加用户认证功能。"

OpenSpec 会自动解析需求，生成完整的规范文档体系：

复制代码

openspec/changes/user-auth/
├── proposal.md      # 项目提案：为什么要做、做什么、不做什么
├── design.md        # 技术设计：技术选型、架构决策、风险评估
├── tasks.md         # 任务清单：拆分成可执行的任务列表
└── specs/           # 模块规格
    ├── auth-login/spec.md
    ├── auth-register/spec.md
    └── auth-session/spec.md

各文档的职责：

proposal.md：说明为什么要做、做什么、不做什么
design.md：技术方案、关键决策、风险和取舍
tasks.md：拆成可执行的任务
specs/*.md：沉淀可验证的行为要求

3.3 步骤二：审查与修正（Review & Refine）

这是最关键的一步。OpenSpec 生成的文档不一定完美，需要人工审查并修正。

假设你的需求是"用户认证功能"，但文档中遗漏了"密码重置"或"第三方登录"，你需要让 Codex 修正：

复制代码

把 user-auth 的提案修正一下：
1. 增加密码重置功能（通过邮箱验证）
2. 暂不支持第三方登录（Google、微信），放在二期
3. 认证方式使用 JWT，有效期 7 天

为什么要修正文档而不是直接改代码？ 因为如果文档不修正，后面执行 $openspec-apply-change 时，Codex 可能会按照错误的前提实现代码。

💡 最佳实践：OpenSpec 不是一次性写完的，它应该随着讨论变准。多轮修正后再进入实施阶段。

3.4 步骤三：实施变更（Apply）

当你确认 proposal.md、design.md、tasks.md、specs/*.md 已经把需求说清楚了，再开始实施。

在 Codex 对话框中输入：

复制代码

$openspec-apply-change user-auth

Codex 会读取 OpenSpec 里的所有文档，按任务逐个实现。你也可以限制范围：

复制代码

$openspec-apply-change user-auth --scope backend

3.5 步骤四：验证与归档（Verify & Archive）

代码生成后，进行验证：

复制代码

$openspec-verify-change user-auth

校验生成的代码是否完全与规格文档对齐。

联调测试通过后，进行归档：

复制代码

$openspec-archive-change user-auth

归档后，变更会自动合并进主文档，形成"活文档"。

四、实战案例一：支付收银台项目（前后端全栈）

这是一个从零开始构建支付收银台演示项目的完整案例，涵盖前端（React + Vite）和后端（FastAPI + MySQL）。

4.1 项目背景

实现一个支付收银台页面，支持微信和支付宝双渠道扫码支付。项目不涉及真实资金交易，专注实现订单管理、二维码生成、支付状态轮询、前后端数据交互等核心功能。

4.2 步骤一：创建提案

在 Codex 对话框中输入：

复制代码

$openspec-propose 我想实现一个支付平台，有收银台页面，可以通过微信和支付宝进行扫码支付

4.3 步骤二：审查生成的规范文档

OpenSpec 自动生成以下文档：

复制代码

openspec/changes/payment-cashier/
├── proposal.md
├── design.md
├── tasks.md
└── specs/
    ├── cashier-page/spec.md          # 收银台页面规格
    ├── order-management/spec.md      # 订单管理规格
    ├── payment-gateway-mock/spec.md  # 模拟支付网关规格
    ├── payment-status-polling/spec.md # 支付状态轮询规格
    └── payment-qr-codes/spec.md      # 支付二维码规格

proposal.md 中明确了：

前端依赖：React、Vite、axios
后端依赖：FastAPI、PyMySQL、SQLAlchemy
数据库：MySQL

design.md 中明确了技术决策：

前端：React + Vite，生态成熟、开发高效
后端：FastAPI，支持自动接口文档、数据校验、异步处理
UI：京东风格，收银台布局采用上下分区
二维码：后端生成 Base64 格式
支付状态：前端定时轮询

specs/ 下的模块规格详细定义了每个模块的功能场景、交互流程、参数规则、异常处理。

4.4 步骤三：审查修正

假设你发现设计文档中缺少了"支付超时自动取消订单"的逻辑，让 Codex 修正：

复制代码

把 payment-cashier 的 design.md 补充一下：
支付超时（5分钟未支付）自动取消订单，释放库存

4.5 步骤四：实施

确认文档无误后：

复制代码

$openspec-apply-change payment-cashier

Codex 会按照规范文档自动生成：

前端：React 页面组件、路由配置、API 请求封装
后端：FastAPI 路由、数据模型（SQLAlchemy）、业务逻辑
数据库：MySQL 迁移脚本

4.6 步骤五：验证与归档

复制代码

$openspec-verify-change payment-cashier

验证通过后进行归档：

复制代码

$openspec-archive-change payment-cashier

五、实战案例二：连接器搜索功能（现有项目改造）

这是一个在已有项目上做功能迭代的案例，更贴近日常开发场景。

5.1 项目背景

需求：RPA 文档列表支持按"店铺/连接器"切换搜索，连接器搜索最终按 connector_id 查询。

5.2 步骤一：先讨论事实，再创建提案

在创建提案之前，先和 Codex 讨论清楚现状：

复制代码

帮我分析一下 RobotReportFileDTO 和 RobotReportFileParam 这两个类的字段

Codex 分析后发现：

RobotReportFileDTO 有 connectorId，没有 connectorName
RobotReportFileParam 有 connectorId，也有 connectorName

这个发现很关键------如果不确认清楚，后面实现时可能错误地假设 DTO 里也有 connectorName。

5.3 步骤二：创建提案

复制代码

$openspec-propose batch-download-store-connector-search

RPA 文档列表支持店铺/连接器切换搜索。
连接器搜索最终按 connector_id 查。
RobotReportFileDTO 只有 connectorId，没有 connectorName。
connectorName 需要在落库前通过 connectorId 补齐。
老数据 connector_id / connector_name 允许为空，第一期不回填。

5.4 步骤三：审查修正

假设在审查时发现文档中有一个错误------误以为 RobotReportFileParam 也有 connectorName，但实际上它也没有。立即让 Codex 修正：

复制代码

把 batch-download-store-connector-search 里的结论修正一下：
RobotReportFileDTO 只有 connectorId，没有 connectorName。
RobotReportFileParam 也只有 connectorId，没有 connectorName。
connectorName 需要在 convertFile 前基于 connectorId 补齐。
老数据第一期允许为空，不通过 job_uuid 粗暴反推。

⚠️ 关键提醒 ：如果文档不修正，后面 $openspec-apply-change 时 Codex 可能会按照错误前提实现。

5.5 步骤四：实施

复制代码

$openspec-apply-change batch-download-store-connector-search

5.6 步骤五：验证与归档

复制代码

$openspec-verify-change batch-download-store-connector-search
$openspec-archive-change batch-download-store-connector-search

六、前后端开发的最佳实践

6.1 规范先行，前后端对齐

在前后端分离项目中，最怕的是前端臆造字段、后端未返回。OpenSpec 的方案是：

在 design.md 中明确定义 API 契约：路径、方法、入参、出参、错误码
在 specs/ 中为每个接口写验收场景：正常流程、异常流程、边界情况
前后端共用同一份 OpenSpec 文档 ：前端看 specs/ 决定 UI 渲染，后端看 specs/ 决定接口实现

6.2 按业务域而非技术栈拆分任务

不建议按"前端任务"和"后端任务"来拆分，而是按业务功能拆解，每个功能包含前后端完整实现。

例如"用户登录"这个功能，应该是一个完整的任务单元，包含：

前端：登录页面、表单校验、API 调用
后端：登录接口、JWT 生成、密码校验

6.3 多轮修正，宁慢勿快

宁可多花时间在提案和修正阶段，也不要让 Codex 在错误的前提上写代码。OpenSpec 的文档修正成本远低于代码重构成本。

6.4 使用 MCP Server 增强体验

可选的增强工具------OpenSpec MCP Server 将 OpenSpec 命令封装成"工具"，安装后 Codex 能更智能地执行操作：

bash 复制代码

codex mcp add openspec-server npx -y @igor-olikh/openspec-mcp-server

七、常见误区

❌ 误区 1：把 Param 的字段当成 DTO 也有

就像案例二中的情况，Param 有 connectorName 不代表 DTO 也有。

❌ 误区 2：只补 DO 字段就以为能落库完整

改了数据对象（DO）的字段，不等于数据库表结构也改了。

❌ 误区 3：文档错了还继续 apply

如果文档有错误，先修正文档，再执行 $openspec-apply-change。

❌ 误区 4：跳过审查直接实施

OpenSpec 生成的文档必须经过人工审查，确认无误后再实施。

八、总结

OpenSpec + Codex 的工作流可以概括为：

复制代码

讨论需求 → 创建提案(propose) → 审查修正 → 实施(apply) → 验证(verify) → 归档(archive)

核心理念：把讨论沉淀成可执行的变更文档，再让 Codex 按文档实现。

对前端开发者：通过 OpenSpec 明确 API 契约和 UI 规格，避免前端等后端、后端改前端的尴尬。

对后端开发者：通过 OpenSpec 明确数据模型、接口规范和业务逻辑，让 Codex 按规格生成可落地的代码。

对全栈开发者：OpenSpec 是连接前后端的"契约锚点"，一份文档同时指导前后端实现。