TypeScriptNode.jsAI
OpenSpec 实战：用规范驱动开发破解 AI 编程协作难题
介绍 OpenSpec 规范驱动开发框架在 AI 编程协作中的实战应用。通过 jimeng-free-api-all 项目升级案例，演示了从需求提案（proposal）、任务执行（apply）到归档（archive）的完整工作流。利用结构化规范约束 AI 生成代码，解决上下文限制和多人协作歧义问题，实现旧项目功能扩展与自动化验证，降低管理成本并提升代码可追溯性。
介绍 OpenSpec 规范驱动开发框架在 AI 编程协作中的实战应用。通过 jimeng-free-api-all 项目升级案例，演示了从需求提案（proposal）、任务执行（apply）到归档（archive）的完整工作流。利用结构化规范约束 AI 生成代码，解决上下文限制和多人协作歧义问题，实现旧项目功能扩展与自动化验证，降低管理成本并提升代码可追溯性。
OpenSpec 是一种 规范驱动（spec‑driven） 的开源开发框架，主要面向 AI 编程助手（如 Claude Code、GitHub Copilot、Cursor 等）而设计。它通过在「共识规范 → AI 执行 → 自动验证」的闭环流程，帮助团队在 AI 参与的代码开发过程中明确需求、降低指令歧义、提升代码可追溯性与可维护性。
该项目核心价值在于功能增强和多人协作开发，尤其是大型项目很多都是基于原有项目扩展和改造。以往因模型上下文限制，企业级项目及老旧项目的 AI 升级改造较为困难。此外，AI 辅助开发的多人协作也面临挑战。本项目旨在解决上述两个问题。本文将通过实战项目演示该规范驱动开发框架的应用。
我们先下载一个开源项目，下面拿 jimeng-free-api-all 项目作为案例介绍。
使用 git clone 这个项目：
git clone https://github.com/zhizinan1997/jimeng-free-api-all
完成代码下载。
使用 VSCode 打开该项目。
在终端命令行输入以下命令安装 OpenSpec：
npm install -g @fission-ai/openspec@latest
输入以下命令确保安装成功：
openspec --version
如果安装失败出现如下错误（常见于 Windows）：
可尝试使用 pnpm 命令安装：
pnpm install -g @fission-ai/openspec@latest
按图示操作即可完成 OpenSpec 安装。
此命令用于在项目中创建一个新的 openspec/ 目录结构，方便后续基于此来控制项目。
openspec init
OpenSpec 支持多种开发工具，这里使用 Claude Code。
这个文件夹主要有以下几个文件和内容：
openspec/
├── specs/ # 规范目录（存放各类正式规范文档）
│ └── auth/ # 认证相关规范子目录
│ └── spec.md # 当前认证规范文档（若存在）
└── changes/ # 变更目录（存放规范的修改提案与增量内容）
└── add-2fa/ # 新增双因素认证（2FA）的变更子目录（由 AI 创建完整结构）
├── proposal.md # 变更提案文档（说明为何修改、修改内容）
├── tasks.md # 实施任务清单（记录需完成的具体开发/修改任务）
├── design.md # 技术设计文档（技术方案决策，可选）
└── specs/ # 变更对应的规范增量目录
└── auth/ # 变更涉及的认证规范子目录
└── spec.md # 规范增量文档（仅展示新增/修改的内容，即差异部分）
OpenSpec 根目录下有 AGENTS.md、project.md。这是项目修改变更的依据，有了它们，AI 就不会乱生成，尤其是对于变更项目比较友好。
AGENTS.md、project.md 默认为英文，需翻译为中文。
输入以下提示词：
请帮我把 openspec 文件夹下 AGENTS.md、project.md 内容翻译成中文
OpenSpec 主要的流程如下：
这里会用到三个关键命令：/openspec:proposal、/openspec:apply、/openspec:archive。
首先执行第一个命令，简单来说就是把需求给它，让它帮你拆解详细的计划任务。
接下来简要说明 jimeng-free-api-all 项目背景。该项目是即梦文生图、文生视频的接口，基于 3.0 版本。目前最新的即梦支持 4.0 了，所以需要实现即梦 4.0 文生图、图生图、文生视频等功能。此处依赖的其他资料不做详细展开。新增加的两个文件是 curl4.txt、curl4.md。
提示词如下：
/openspec:proposal 请基于 curl4.md 内容以及 jimeng-free-api-all\src\api\controllers\images.ts 代码，新增补充基于 high_aes_general_v40 模型功能，请修改 images.ts 实现 high_aes_general_v40 模型能力。请不要先写代码，先把需求整理好，结合原来的项目梳理项目新增的变革需求。
AI 将根据上述需求生成需求草案和计划。
包括生成的 tasks.md 文档，这样 AI 就会避免随意生成代码，我们在后面执行的时候 /openspec:apply AI 就会依据这个文档的约束来实现功能了。此外如果碰到功能点没有写完或者是团队协作开发，这种方式就比较友好。我们可以把刚才生成的文档提交至代码仓库以便后续继续开发。
随后使用 /openspec:apply 执行上面的功能新增。
接下来 AI 就会延续之前的 tasks.md 文档实现代码编写和测试等相关工作。
经过一段时间的运行后，tasks.md 里面的 12 个子任务已经执行完成，我们看一下执行后的结果。
查看一下 tasks.md：
## 1. 实施 high_aes_general_v40 模型支持
- [x] 1.1 在 MODEL_MAP 中添加 jimeng-4.0 模型映射
- [x] 1.2 更新 DEFAULT_MODEL 配置（如需要）
- [x] 1.3 验证模型参数配置正确性
## 2. 优化图片生成参数支持
- [x] 2.1 支持更高的分辨率配置（2560x1440）
- [x] 2.2 确保与现有参数的兼容性
- [x] 2.3 添加分辨率比例验证
## 3. 增强批量生成能力
- [x] 3.1 优化 generateImages 函数支持批量生成
- [x] 3.2 确保与现有 API 接口的兼容性
- [x] 3.3 添加错误处理和日志记录
## 4. 测试和验证
- [x] 4.1 单元测试：模型映射功能
- [x] 4.2 集成测试：图片生成流程
- [x] 4.3 验证与 curl4.md 中描述的参数一致性
看到 12 个任务已经执行完成了。
接下来先人工方式审查一下它修改的代码。
确认修改了代码。
使用 Apifox 对这个接口进行验证测试。执行以下命令启动程序：
npm install build && npm run dev
Apifox 测试。
接口成功返回请求信息。
在即梦平台可以看到这个请求。
此时新增修改的功能就初步完成了。当然这个后面还有其他功能扩展，这里就不做详细展开。我们回到需求整理再执行即可。
上面的新增加的需求变更已经完成。接下来我们需要执行第三个命令 /openspec:archive，对执行新增功能进行归档操作，方便后面修改新功能时对归档文档进行阅读。
同样执行以下命令：
/openspec:archive
AI 执行完成后看到下面归档信息。
这个时候我们在 openspec/changes 文件夹下看到新增加的需求已经归档了。
本次新增需求就开发完成了。上面的文档信息和修改的代码提交代码仓库，其他团队成员也可以依据已经修改的功能继续开发新的功能点了。
本文介绍了 OpenSpec 框架的安装配置与实战应用完整流程。该流程以规范驱动开发为核心，结合 jimeng-free-api-all 项目改造场景，通过 OpenSpec 提供的规范管理、AI 执行与自动验证能力，搭配命令行工具的流程管控能力，形成了一套从需求定义到功能落地的规范化开发解决方案。
通过这套实践方案，团队能够高效应对 AI 参与开发时的协作难题 —— 借助简单的安装配置步骤（包括 OpenSpec 全局安装、项目初始化、规范文档生成），无需担心模型上下文限制或需求传递歧义，就能有序完成旧项目升级（如本次即梦 4.0 模型的功能扩展）。无论是基础的代码生成、测试用例编写，还是通过变更提案实现的多人协作、需求追溯，都能通过 proposal/apply/archive 等简洁命令完成，极大降低了 AI 辅助开发中的管理成本。在实际验证中，OpenSpec 能够稳定支撑规范与代码的一致性，特别是通过 tasks.md 任务清单和自动化验证机制，有效避免了 AI 生成代码的随机性，且适配性远优于传统的直接 prompt 开发模式。同时，方案具备良好的扩展性 —— 开发者可以基于此扩展更多团队协作场景，如迭代式需求拆分、跨团队规范对齐、历史变更审计等，进一步发挥规范驱动开发在大型项目中的应用价值。
开发者可按文中步骤进行实践，根据项目需求定制规范文档与变更流程。
微信公众号「极客日志」，在微信中扫描左侧二维码关注。展示文案：极客日志 zeeklog
生成新的随机RSA私钥和公钥pem证书。 在线工具，RSA密钥对生成器在线工具，online
基于 Mermaid.js 实时预览流程图、时序图等图表，支持源码编辑与即时渲染。 在线工具，Mermaid 预览与可视化编辑在线工具，online
将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具，Base64 字符串编码/解码在线工具，online
将字符串、文件或图像转换为其 Base64 表示形式。 在线工具，Base64 文件转换器在线工具，online
将 Markdown（GFM）转为 HTML 片段，浏览器内 marked 解析；与 HTML转Markdown 互为补充。 在线工具，Markdown转HTML在线工具，online
将 HTML 片段转为 GitHub Flavored Markdown，支持标题、列表、链接、代码块与表格等；浏览器内处理，可链接预填。 在线工具，HTML转Markdown在线工具，online