2025年10月21日-OpenSpec 实战：用规范驱动开发破解 AI 编程协作难题

优质文章学习记录

— 11 min read
2025年10月21日-OpenSpec 实战：用规范驱动开发破解 AI 编程协作难题

1.前言

OpenSpec 是一种 **规范驱动（spec‑driven）**‍ 的开源开发框架，主要面向 AI 编程助手（如 Claude Code、GitHub Copilot、Cursor 等）而设计。它通过在「共识规范 → AI 执行 → 自动验证」的闭环流程，帮助团队在 AI 参与的代码开发过程中明确需求、降低指令歧义、提升代码可追溯性与可维护性。

核心理念与工作流

  1. 共识规范（Spec）
    • 先由人类与 AI 共同撰写结构化的需求规范（包括功能描述、输入/输出、边界条件、测试用例等）。
  2. AI 执行
    • AI 根据规范自动生成代码、文档或变更提案。
  3. 自动验证
    • 框架内置的验证器会依据规范中的测试用例对生成的代码进行自动化检查，确保实现符合预期。
  4. 迭代与归档
    • 通过审查、计划、实现、归档等步骤形成完整的变更历史，便于后续审计与迭代。
img

适用场景

1 新项目、2 功能增强（迭代项目）3、多人协作。 这个项目最有价值的我个人觉的应该是功能增强 和多人协助开发，尤其是大型项目很多都是基于原有项目扩展和改造。之前由于模型上下文的问题导致很多企业级项目以及一些老旧项目升级改造AI 就变得难以搞定。另外AI 开发的项目多人协作也是比较难搞定的。这个项目刚好解决这个2个问题。今天小编就带大家通过一个实战的项目来体验感受一下这个规范驱动开发的框架。

2 项目实战

被修改项目下载

我们先下载一个开源项目下面就拿jimeng-free-api-all 项目作为案例介绍

使用git clone 这个项目

git clone https://github.com/zhizinan1997/jimeng-free-api-all
image-20251021154740605

完成代码下载

image-20251021154806006

我们使用vscode 打开这个项目

image-20251021154846934

安装OpenSpec

我们在终端命令行输入下面命令安装OpenSpec

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

输入下面命令确保安装成功

openspec --version

如果按照失败出下面错误（一般是windows ）

image-20251021155249048

我们可以切换使用pnpm 命令安装

pnpm install -g @fission-ai/openspec@latest
image-20251021155341378
image-20251021155403813

按照上图方式我们就确保openspec安装完成。

openspec init

这个目的主要是在项目中创建一个新的 openspec/ 目录结构，这个方便后面基于这个来控制项目

openspec init

OpenSpec 支持多种开发工具，我这里使用claude code

image-20251021155650133
image-20251021155828402

这个文件夹主要有以下几个文件和内容

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 默认的这2个文件是英文的我们把他翻译成中文。

中文转换

我们输入下面提示词

请帮我把openspec文件夹下AGENTS.md、project.md 内容翻译成中文
image-20251021160937208

需求收集整理

openspec 主要的流程如下：

  1. 起草一份变更提案，明确你期望的规范更新内容。
  2. 与 AI 助手一同审核该提案，直至各方达成一致。
  3. 执行任务，过程中需参考已达成共识的规范文档。
  4. 对该变更进行归档，将已批准的更新内容合并回基准规范文档中。
image-20251021163404637

这个我们会用到比较关键的三个命令

/openspec:proposal 、/openspec:apply、/openspec:archive

那么我们先执行第一个 简单来说就是你把需求给它，它来帮你做拆解详细的计划任务。

接下来我们需要简单交代一下jimeng-free-api-all 项目，这个项目是即梦文生图、文生视频的接口是基于3.0的。目前最新的即梦支持4.0 了。所以我们需要实现即梦4.0 文生图，图生图，文生视频等功能。 这里我们还依赖一下其他的资料。关于这块资料我们就不做详细展开了。 新增加的2个文件是curl4.txt 、curl4.md

image-20251021164222855

提示词如下：

/openspec:proposal 请基于curl4.md内容以及jimeng-free-api-all\src\api\controllers\images.ts 代码，新增补充基于high_aes_general_v40模型功能，请修改images.ts 实现high_aes_general_v40模型能力。 请不要先代码，先把需求整理好，结合原来的项目梳理项目新增的变革需求。

AI会更加上面的需求生成需求草案和计划

image-20251021171639172

包括生成的tasks.md文档，这样AI 就会乱写一通，我们在后面执行的时候/openspec:apply AI 就会更加这个文档的约束来实现功能了。此外如果碰到功能点没有写完或者是团队协作开发，这种方式就比较友好好了。我们可以把刚才生成的文档提交代码仓库（gitlab，github等）可以接着后面写。

代码开发执行

接下来我们在使用/openspec:apply 执行上面的功能新增

image-20251021172224498

接下来AI 就会延续之前的tasks.md文档 实现代码编写和测试等相关工作。

image-20251021172353521

经过一段时间的运行后 tasks.md里面的12个子任务已经执行完成，我们看一下执行后的结果

image-20251021174418615

我们查看一下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个任务已经执行完成了。

人工验证

接下来我们先人工方式审查一下它修改的代码

image-20251021174706007

的确是修改了代码。

我们使用Apifox 对这个接口进行验证测试。执行下面命令启动程序

npm install build npm run dev

Apifox 测试

image-20251021175423031

接口成功返回请求信息。

image-20251021175336879

我们在即梦平台可以看到这个请求

img

这个时候新增修改的功能就初步完成了。当然这个后面还有其他功能扩展，这里就不做详细展开。 我们在回到需求整理再执行即

项目归档

上面的新增加的需求变更已经完成。接下来我们需要执行第三命令/openspec:archive，对执行新增功能进行归档操作方便后面修改新功能对归档文档进行阅读。

我们同样执行下面命令

/openspec:archive
image-20251021200959764

AI 执行完成后我们看到下面归档信息

image-20251021201505283

这个时候我们在openspec \changes文件夹下看到新增加的需求已经归档了。

image-20251021201801743

本次新增需求就开发完成了。上面的文档信息和修改的代码提交代码仓库，其他小伙伴也可以依据已经修改的功能继续开发新的功能点了。

3.总结

今天主要带大家了解并实现了 OpenSpec 框架的安装配置与实战应用完整流程，该流程以规范驱动开发为核心，结合 jimeng-free-api-all 项目改造场景，通过 OpenSpec 提供的规范管理、AI 执行与自动验证能力，搭配命令行工具的流程管控能力，形成了一套从需求定义到功能落地的规范化开发解决方案。

通过这套实践方案，团队能够高效应对 AI 参与开发时的协作难题 —— 借助简单的安装配置步骤（包括 OpenSpec 全局安装、项目初始化、规范文档生成），无需担心模型上下文限制或需求传递歧义，就能有序完成旧项目升级（如本次即梦 4.0 模型的功能扩展）。无论是基础的代码生成、测试用例编写，还是通过变更提案实现的多人协作、需求追溯，都能通过 proposal/apply/archive 等简洁命令完成，极大降低了 AI 辅助开发中的管理成本。在实际验证中，OpenSpec 能够稳定支撑规范与代码的一致性，特别是通过 tasks.md 任务清单和自动化验证机制，有效避免了 AI 生成代码的随机性，且适配性远优于传统的直接 prompt 开发模式。同时，方案具备良好的扩展性 —— 小伙伴们可以基于此扩展更多团队协作场景，如迭代式需求拆分、跨团队规范对齐、历史变更审计等，进一步发挥规范驱动开发在大型项目中的应用价值。

感兴趣的小伙伴可以按照文中提供的步骤进行实践，根据项目需求定制规范文档与变更流程。今天的分享就到这里结束了，我们下一篇文章见。

Read more

前端小练习——星辰宇宙（JS没有上限！！！）

前端小练习——星辰宇宙（JS没有上限！！！）

前言：在刚开始学习前端的时候，我们会学习到前端三件套中的JavaScript，可能那时候读者没有觉得JavaScript这个语言有多么的牛逼，本篇文章将会使用一个炫酷的案例来刷新你对JavaScript这个语言的认知与理解。 ✨✨✨这里是秋刀鱼不做梦的BLOG ✨✨✨想要了解更多内容可以访问我的主页秋刀鱼不做梦-ZEEKLOG博客 先让我们看一下最终的结果： 在开始讲解这个炫酷的案例之前，先让我们了解一下本案例所需的前置知识： Three.js：一个用于创建和显示3D图形的JavaScript库。代码中导入了Three.js的核心库和轨道控制库（OrbitControls），用于处理3D场景的创建和相机控制。WebGL：用于在网页中绘制3D图形的底层API。Three.js封装了WebGL，使得3D渲染变得更简单。模块化 JavaScript：使用 ES6 的模块导入语法 (import) 引入外部库，使代码结构更加清晰。着色器编程：自定义顶点和片段着色器，通过 onBeforeCompile 方法替换默认着色器，控制点的大小、颜色和运动效果。缓冲几何体：

别装了！你写的JS代码全在“裸奔”，99%前端都在背锅！

今天，我想直接撕开一个血淋淋的真相。 在这个行业里，我审查过无数的JavaScript应用程序，甚至包括那些大厂出品的标杆项目。然而，它们几乎无一例外地都藏着致命的安全漏洞。 这不是因为前端开发者们在摸鱼，也并非因为团队对最佳实践视而不见。 真正的原因在于，现代JavaScript这头巨兽实在太复杂、进化太快了，而且它从头到脚都布满了让人防不胜防的暗坑。 无论是在初创公司的草台班子、企业级的豪华看板，还是那些每天处理着真金白银和海量真实用户的核心生产系统里，我一遍又一遍地看着同样的悲剧反复上演。 JS的安全漏洞，最喜欢玩“死一般寂静” 报错导致APP崩溃？那反而是你修了八辈子福得来的福报！ 通常来说，当你把代码搞砸了，你立马就能收到反馈。 比如一个直接报错的API请求，一个四分五裂的页面布局，或者测试控制台里那片刺眼的爆红。 但是，安全漏洞根本不跟你玩这套，它们就像隐形杀手一样，蛰伏在死一般的寂静中。 你的UI看起来美轮美奂。你的API跑得顺风顺水。你的自动化测试全绿通过。 可就在同时，在那些你看不见的阴暗角落里，黑客可能正在疯狂窃取你用户的会话令牌（Session

PHP 基础案例教程之 06-Web 前后端数据交互

HTTP HTTP 概述 HTTP（Hyper Text Transfer Protocol，超文本传输协议） 是浏览器与 Web 服务器之间进行数据交互时需要遵循的一种协议，用于定义浏览器与 Web 服务器之间数据交换的格式。 HTTP 的特点： * 简单快速：客户端向服务器发送请求时，只需要传送请求方式和请求路径等简单信息。 * 灵活：HTTP 允许传输任意类型的数据。 * 无连接：限制每次连接只处理一个请求,服务器处理完客户端的请求，并收到客户端的应答后，就会断开连接，节省传输时间。 * 无状态：协议对于事物处理没有记忆能力，如果后续的处理需要使用前面请求的数据，则必须重新传递，这样可能导致每次连接发送的数据量增大，但当在服务器不需要前面的请求数据时，应答就比较快。 HTTPS（Hyper Text Transfer Protocol over SecureSocket Layer，超文本传输安全协议）解决了 HTTP 明文传输不安全的问题，它在 HTTP
【Java Web学习 | 第八篇】JavaScript(2) 基础知识2

【Java Web学习 | 第八篇】JavaScript(2) 基础知识2

🌈个人主页: Hygge_Code🔥热门专栏:从0开始学习Java | Linux学习| 计算机网络💫个人格言: “既然选择了远方，便不顾风雨兼程” 文章目录 * JavaScript 运算符与流程控制全解析 * 一、运算符：自增、比较与逻辑🥝 * 1. 自增运算符（++） * 2. 比较运算符 * 3. 逻辑运算符 * 二、条件判断语句🥝 * 1. if 语句 * 2. 三目运算符 * 3. switch 语句 * 三、循环语句🥝 * 1. while 循环 * 2. for 循环 * 总结🍂 JavaScript 运算符与流程控制全解析 在 JavaScript 中，运算符和流程控制是实现逻辑处理的基础。本文在前文基础上补充for循环内容，全面讲解比较运算符、