OpenSpec 实战：用规范驱动开发破解 AI 编程协作难题

Ne0inhk

— 10 min read
OpenSpec 实战：用规范驱动开发破解 AI 编程协作难题

1.前言

什么是 规范(Spec)驱动开发?

我们可以知道规范驱动开发的流程

为什么要用 Spec?

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

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

它为 AI 编程工具（Claude Code、Cursor、Codex、OpenCode、windsurf 等）提供一种标准化的方式：

  • 让 AI 生成、跟踪、验证、归档 功能变更；
  • 把“功能需求 → 任务分解 → 实现 → 验收” 全流程结构化；
  • 实现 AI 与人协同开发 的一致性。

🧠 核心理念：

“让 AI 先写清楚规范（spec）再写代码” 而不是盲目凭 prompt 去写。

适用场景

1 新项目、

2 功能增强（迭代项目）

3、多人协作。

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

2 项目实战

1.去https://www.trae.cn/下载trae, 安装到本地

2.安装OpenSpec

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

先决条件

Node.js >= 20.19.0

步骤 1：全局安装 CLI

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

验证安装：

openspec --version

步骤 2：在项目中初始化 OpenSpec

导航到您的项目目录：

cd my-project

openspec init

初始化过程中会发生： 系统会让你选择所用的 AI 工具（Claude Code / Cursor / OpenCode / Codex）； 自动在项目中创建 openspec/ 目录； 生成托管文件 AGENTS.md，用于不同 AI 工具共享说明； 为所选 AI 工具自动配置 /openspec 的斜杠命令（slash commands）。

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

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 支持多种开发工具，我这里使用Qwen Code

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

显示的过程如下:

中文转换

我们输入下面提示词

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

再把另外2个文件也转换成中文的.

请帮我把AGENTS.md和QWEN.md 内容翻译成中文

需求收集整理

openspec 主要的流程如下：

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

使用

  • 主动方式

使用 AI 编程工具的 自定义命令，比如 cursor,windsurf, auggie 等

/openspec:proposal 创建需求 /openspec:apply 执行需求 /openspec:archive 归档需求
  • 被动方式

使用关键词，比如 spec, proposal 等触发创建规格文件

开发

接下来我们需要简单来完成一个需求

/openspec:proposal 请基于雪花id的知识以及雪花.md的内容，帮我完成功能开发。 请不要先代码，先把需求整理好，结合原来的项目梳理项目新增的变革需求。

输出如下:

再次执行:

/openspec:apply

项目归档

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

我们同样执行下面命令

/openspec:archive

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

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

什么时候该使用Spec？

Openspec 规范驱动的原理是什么？

怎么触发的

执行完 openspec init 之后 会生成几个重要的文件(命令/工作流)

Agents.md

openspec-apply.md

openspec-proposal

怎么使用

  • 使用关键词触发，比如 proposal,spec 之类的
  • 使用 slash command(需要 AI 编程工具支持）指定触发， claude code 比较特殊，“/”命令后，收入输入，不要直接 enter 键
  • 引用文件到对话框中，主要针对不支持 Agents.md 、Claude.md以及 slash command的工具

生成格式

  • 执行 openspec init 命令后，会生成如下的目录结构
openspec/ ├── project.md # 项目约定 ├── specs/ # 当前真实情况 - 已构建的内容 │ └── [capability]/ # 单一聚焦能力 │ ├── spec.md # 需求和场景 │ └── design.md # 技术模式 ├── changes/ # 提案 - 应该变更的内容 │ ├── [change-name]/ │ │ ├── proposal.md # 为什么、什么、影响 │ │ ├── tasks.md # 实施检查清单 │ │ ├── design.md # 技术决策（可选；见标准） │ │ └── specs/ # 增量变更 │ │ └── [capability]/ │ │ └── spec.md # ADDED/MODIFIED/REMOVED │ └── archive/ # 已完成的变更

proposal.md：

## Why（为什么） [关于问题/机会的 1-2 句话] ## What Changes（变更内容） - [变更项目列表] - [用 **BREAKING** 标记破坏性变更] ## Impact（影响） - 受影响的规范：[列出能力] - 受影响的代码：[关键文件/系统]

spec.md

## ADDED Requirements（新增需求） ### Requirement: 新功能 系统应当提供... #### Scenario: 成功案例 - **WHEN** 用户执行操作 - **THEN** 预期结果 ## MODIFIED Requirements（修改需求） ### Requirement: 现有功能 [完整的修改后需求] ## REMOVED Requirements（移除需求） ### Requirement: 旧功能 **Reason（原因）**: [为什么移除] **Migration（迁移）**: [如何处理]

如果影响多个能力，在 changes/[change-id]/specs/<capability>/spec.md 下创建多个增量文件 - 每个能力一个。

tasks.md：

## 1. 实施 - [ ] 1.1 创建数据库模式 - [ ] 1.2 实现 API 端点 - [ ] 1.3 添加前端组件 - [ ] 1.4 编写测试

在需要时创建 design.md：

如果满足以下任何条件，则创建 design.md；否则省略：

  • 跨领域变更（多个服务/模块）或新的架构模式
  • 新的外部依赖或重大数据模型变更
  • 安全、性能或迁移复杂性
  • 在编码前需要技术决策的歧义

最小 design.md 骨架：

## Context（背景） [背景、约束、利益相关者] ## Goals / Non-Goals（目标/非目标） - Goals（目标）：[...] - Non-Goals（非目标）：[...] ## Decisions（决策） - Decision（决策）：[什么和为什么] - Alternatives considered（考虑的替代方案）：[选项 + 理由] ## Risks / Trade-offs（风险/权衡） - [风险] → 缓解 ## Migration Plan（迁移计划） [步骤、回滚] ## Open Questions（开放问题） - [...]
  • Spec 驱动不是帮你解决 ”业务/逻辑/算法" 难题

它不是解决难题，是建立规范，产生文档，记录变更

Read more

8款高效科研绘图工具推荐：从流程图到专业结构图，AI助力学术可视化

8款高效科研绘图工具推荐：从流程图到专业结构图，AI助力学术可视化

在现代科研工作中，数据的可视化表达已成为论文撰写、项目汇报、成果展示中不可或缺的一环。一张清晰、专业、美观的图表不仅能提升论文的可读性与说服力，更能帮助研究者更直观地梳理逻辑、传达思想。然而，对于许多非设计背景的研究人员而言，使用传统绘图软件（如Visio、PPT、Adobe Illustrator）制作高质量科研图表往往耗时费力、学习成本高、易出错。 幸运的是，随着人工智能和自动化技术的发展，一批专为科研人员打造的智能绘图工具应运而生。它们支持通过自然语言描述自动生成各类图表，涵盖流程图、机制图、结构图、时序图等常见类型，极大降低了科研可视化的门槛。 本文将为您详细介绍8款当前主流且实用的科研绘图工具，涵盖不同学科领域与应用场景。其中，我们将重点解析“PaperXie AI科研绘图模块”，并结合其界面截图进行详细功能说明，确保内容真实、贴合产品实际，避免任何夸大或误导性描述。 一、PaperXie AI科研绘图模块 —— 面向多学科的专业级智能绘图助手 官网地址：点击直达https://www.paperxie.cn/tools/drawing 核心亮点：

By Ne0inhk
Linux 进程信号深度解析（上）：信号的产生与本质（含完整案例）

Linux 进程信号深度解析（上）：信号的产生与本质（含完整案例）

🔥草莓熊Lotso：个人主页 ❄️个人专栏: 《C++知识分享》《Linux 入门到实践：零基础也能懂》 ✨生活是默默的坚持，毅力是永久的享受！ 🎬 博主简介： 文章目录 * 前言： * 一. 信号的快速认知：从生活场景到技术本质 * 1.1 生活角度理解信号 * 1.2 技术视角的信号定义 * 1.3 查看系统信号：kill -l 命令 * 二. 信号的产生：5 种核心方式（含完整案例） * 2.1 系统命令产生信号（kill 命令） * 2.2 终端按键产生信号（键盘，最常用） * 2.2.1 Ctrl+C：SIGINT（2

By Ne0inhk
Flutter for OpenHarmony：data_assets — 资源映射与自动装配实践（适配鸿蒙 HarmonyOS Next ohos）

Flutter for OpenHarmony：data_assets — 资源映射与自动装配实践（适配鸿蒙 HarmonyOS Next ohos）

欢迎加入开源鸿蒙跨平台社区：https://openharmonycrossplatform.ZEEKLOG.net。 前言 在大型鸿蒙（OpenHarmony）工程中，手动管理静态资源路径极其容易出错。data_assets 提供了一套严谨的代码生成方案，能自动扫描资源并将其转换为强类型的 Dart 类，从根本上消灭了资源引用的运行时错误。 一、核心价值 1.1 基础概念 data_assets 的核心是资源到代码的静态映射。 引用 Assets.homeIcon 编译期校验路径 导致 assets/data: JSON, PNG, SVG DataAssets 生成器 assets.dart: 强类型索引类 鸿蒙业务逻辑 错误的文件名 编译失败提示 1.2 进阶概念 * Type Safety (类型安全)：将字符串路径转化为

By Ne0inhk

Ubuntu24.04.3——ROS2一键安装

这篇文章在开局需要叠个甲，这片文章基本上是摘自于B站up鱼香ROS机器人的动手学ROS2文章（链接：动手学ROS2），如有侵权，请联系我删除，相关视频参考【鱼香ROS】动手学ROS2|ROS2基础入门到实践教程|小鱼带你手把手学习ROS2_哔哩哔哩_bilibili 一、一键安装ROS2 首先启动虚拟机或者启动双系统中的ubuntu，打开终端（快捷键Alt+Ctrl+T） 输入下面的指令 wget http://fishros.com/install -O fishros && . fishros 输入密码 在选项界面选择1-一键安装 注意这里的24.=版本的ubuntu只有jazzy和rolling版本，我选的是jazzy版本，选什么版本会导致之后你的终端命令的一些代码会有改动。 出现如图所示，即ROS2安装完成 2.出现问题可以这样卸载 sudo apt remove ros-jazzy-* sudo apt autoremove 3.ROS2到底装哪里了

By Ne0inhk