什么是OpenSpec？

OpenSpec 是一个 AI 友好的规范驱动开发工具，官网将其定义为 “A lightweight framework spec-driven development”（轻量级规范驱动框架）。

现在的 AI 世界有个大问题：每个 AI 都是一座孤岛，互相听不懂、连不上。本质上，OpenSpec 想解决的是 AI Agent 时代的“互操作性”问题 —— 让 AI 世界不再碎片化，而是像互联网一样互联互通。它不仅仅是一个文件格式，更是 AI 网络的“通用接口标准”。

核心机制：先定规矩，再干活

OpenSpec 提倡开发者先写好一份标准化的“契约”（Spec），明确规定好输入和输出是什么。

• 对 AI Agent 而言： 智能体只要读懂这份契约，不需要看底层代码就能直接调用工具。这就像乐高积木，只要接口标准统一，任何形状的积木都能拼在一起。
• 对整个生态而言： 它建立了一套 AI 界的“普通话”。无论背后是哪个大模型，无论运行在什么硬件上，只要套上 OpenSpec 的标准外壳，任何 AI Agent 都能无障碍地理解、连接和使用。

终极愿景：AI 能力的自由流动

OpenSpec 试图消除不同模型、不同硬件、不同开发者之间的隔阂。它让 AI 能力像水和电一样，通过标准化的管道，在整个网络中自由流动、被任意 Agent 即插即用，从而构建一个真正协作的 AI 价值网络。

与其他方案对比

对比对象	特点	OpenSpec 的优势
Spec Kit（GitHub）	功能全面但体积庞大，有严格的阶段门控、大量的 Markdown 代码以及 Python 配置	更轻量级，允许自由迭代
Kiro（AWS）	功能强大，但只能使用他们的 IDE，且仅限于 Claude 模型	可以与已使用的工具兼容，不绑定特定 IDE 或模型
无规范的 AI 编码	模糊的提示和不可预测的结果	无需繁琐的流程即可带来可预测性

官方文档

本文参考官方文档而来：

https://github.com/Fission-AI/OpenSpec

安装openspec

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

安装依赖 Node.js 20.19.0 或以上版本。

配置openspec

初始化openspec

进入到工作区（Workspace）目录（一个工作区可包含多个项目）后执行：

openspec init

执行后，会出现如下选择提示：

• /opsx:new Create a change
• /opsx:continue Next artifact
• /opsx:appy Implement tasks

这里会提示选择一个工具（tools），支持丰富的工具，比如：

• Claude Code
• Gemini CLI
• Cursor
• Opencode
• Qwen code
• Trae
• CodeBuddy Code (CLI)

注意按空格键选中后再按回车键确认。如果需要更改，再次执行“openspec init”即可。

假设工作区目录为 /data/workspace，工具选择“CodeBuddy Code (CLI) ”，完成后可看到如下：

[/data/workspace]# tree /data/workspace/.codebuddy/commands/
/data/workspace/.codebuddy/commands/
└── opsx
    ├── apply.md
    ├── archive.md
    ├── explore.md
    └── propose.md

1 directory, 4 files

[/data/workspace]# tree /data/workspace/.codebuddy/skills/
/data/workspace/.codebuddy/skills/
├── openspec-apply-change
│   └── SKILL.md
├── openspec-archive-change
│   └── SKILL.md
├── openspec-explore
│   └── SKILL.md
└── openspec-propose
    └── SKILL.md

4 directories, 4 files

可看到安装了 command 和 skill。这是 openspec-1.2.0 的效果，执行命令“openspec --version”可查看 openspec 的版本号。

开启“/opsx:new, /opsx:continue, /opsx:ff, /opsx:verify, /opsx:sync, /opsx:bulk-archive, /opsx:onboard”等扩展 command 方法，在工作区目录下执行命令“openspec config profile”：

✔ What do you want to configure? Delivery and workflows
✔ Delivery mode (how workflows are installed): Both (skills + commands) [current]
? Select workflows to make available:
❯[x] Propose change
 [x] Explore ideas
 [ ] New change
 [ ] Continue change
 [x] Apply tasks
 [ ] Fast-forward
 [ ] Sync specs
 [x] Archive change
 [ ] Bulk archive
 [ ] Verify change
 [ ] Onboard

Create proposal, design, and tasks from a request
Space to toggle, Enter to confirm

“[x]”为当前已经安装好的 command 和 skill，根据需要按空格添加新的或取消已有的，然后按回车键确认。

命令	功能说明
/opsx:propose	创建变更并一步生成规划制品（默认快捷流程）
/opsx:explore	梳理思路、调研问题、明确需求
/opsx:new	新建变更脚手架（扩展工作流）
/opsx:continue	创建下一个制品（扩展工作流）
/opsx:ff	快进生成规划制品（扩展工作流）
/opsx:apply	执行任务实现，并按需更新制品
/opsx:verify	对照制品校验实现结果（扩展工作流）
/opsx:sync	将增量规范同步到主干（扩展工作流，可选）
/opsx:archive	完成后归档
/opsx:bulk-archive	批量归档多个已完成变更（扩展工作流）
/opsx:onboard	引导式完成一次完整端到端变更（扩展工作流）

制品

在软件开发过程中产生的任何文件、数据、代码或实体都是制品，中间代码、测试脚本、甚至本地运行的临时环境，这些都是制品 (Artifacts)。所有的交付件，本质上都是开发过程中产生的制品；但开发过程中产生的大量制品（如测试日志、中间代码），并不会作为交付件交给客户。总之只要是过程中"产出的东西"，都是（包括中间产物）制品，而制品中那些被合同/协议约定要交给对方的部分为交付件。

“/opsx:propose”和“/opsx:new”

执行“/opsx:propose”或者“/opsx:new”开始一个新需求。“/opsx:propose”和“/opsx:new”的区别：

• /opsx:propose 一键搞定：提出变更 + 直接生成完整的规划制品（需求、步骤、验收标准），走「快捷流程」；
• /opsx:new 只搭架子：仅创建一个空的变更脚手架（无实际内容），是「扩展流程」的第一步，后续需要手动补内容。

详细区别：

维度	/opsx:propose（提议）	/opsx:new（新建）
核心动作	「提出变更想法」+「生成完整规划」一步到位	仅创建一个空的变更框架（脚手架），无任何规划内容
流程属性	默认「快捷流程」，适合简单变更	「扩展流程」的起点，适合复杂变更
产出物	有实际内容的规划制品（需求、验收标准、实现步骤）	空的变更目录 / 模板（只有结构，没有具体信息）
后续操作	可直接跳到 /opsx:apply 开始开发	必须接着用 /opsx:continue 逐步补全规划内容
适用场景	小改动（比如改个文案、修复一个小 bug）	大功能 / 复杂变更（比如开发一个新模块、重构核心逻辑）

举个实际例子（以github-buddy项目为例）

场景 1：用 /opsx:propose

想给 github-buddy 加一个「自动刷新IP的小开关」（简单变更），执行“/opsx:propose”→工具直接生成：

• 变更目标：新增 IP 自动刷新开关
• 验收标准：开关打开后每小时自动更新 IP
• 实现步骤：1. 加配置项 2. 写定时逻辑 3. 测试
  （一步到位，直接能开始写代码）

场景 2：用 /opsx:new

想给github-buddy重构整个IP检测逻辑（复杂变更），执行“/opsx:new”→工具只生成一个变更框架：

• 变更名称：[待填写]
• 变更目标：[待填写]
• 验收标准：[待填写]
  （只有结构，需要接着用“/opsx:continue”一步步补全需求、设计、验收标准等内容）

总结

• 简单变更（小修小改）：直接用“/opsx:propose”，省时间，一键到位；
• 复杂变更（大功能 / 重构）：先用“/opsx:new”搭架子，再用“/opsx:continue”分步完善，流程更可控；
• 核心差异：propose 是「提想法 + 做规划」，new 只是「建空架子」。

使用openspec

实战项目：https://github.com/eyjian/github-buddy

构建文档

执行“/opsx:propose”开始一个新需求。提示词：根据文件ai_requirements.md的内容执行，放在/data/workspace/github.com/eyjian/github-buddy目录下。完成后可到openspec/changes/github-buddy目录下查看生成的文件。

[/data/workspace/github.com/eyjian/github-buddy]# tree openspec/
openspec/
└── changes
    └── github-buddy
        ├── design.md
        ├── proposal.md
        ├── specs
        │   ├── auto-update
        │   │   └── spec.md
        │   ├── backup-rollback
        │   │   └── spec.md
        │   ├── cli-commands
        │   │   └── spec.md
        │   ├── hosts-management
        │   │   └── spec.md
        │   └── ip-detection
        │       └── spec.md
        └── tasks.md

8 directories, 8 files

OpenSpec 通过"/opsx:propose"生成的四个核心制品概览如下：

制品	说明
✓ proposal.md	why we’re doing this, what’s changing（变更提议 — 为什么要做、改什么）
✓ specs/	requirements and scenarios（需求规范 — 具体需求与场景）
✓ design.md	technical approach（技术设计 — 技术方案与架构决策）
✓ tasks.md	implementation checklist（任务清单 — 实现步骤与检查项）

这四个制品构成了一个完整的"从提议到落地"的闭环：proposal.md 回答"为什么做"和"做什么"，specs/ 细化"具体要求是什么"，design.md 规划"怎么做"，tasks.md 拆解"分几步做完"。AI 在执行"/opsx:apply"时，正是依据这四个制品来自动生成代码。

各目录和文件说明：

路径	类型	说明
openspec/	根目录	OpenSpec 规范驱动开发的核心目录，存放所有与项目变更相关的规划、设计、规范和任务制品
openspec/changes/	目录	项目所有变更（change）的根目录，每个子目录对应一个独立的变更项（此处仅包含 github-buddy 一个核心变更）
openspec/changes/github-buddy/	目录	「GitHub-Buddy 工具开发」变更项的专属目录，聚合该变更的全量 OpenSpec 制品
openspec/changes/github-buddy/design.md	文件	技术设计 — 采用 C++17 + CMake 构建，使用 CLI11/spdlog/libcurl 等库，平台抽象层设计，关键决策与风险分析
openspec/changes/github-buddy/proposal.md	文件	变更提议 — 阐述为何需要此工具（解决 GitHub 网络访问痛点），以及变更内容（5 个核心 capability）
openspec/changes/github-buddy/specs/	目录	5 个 spec 文件，详细需求规范 — 覆盖 IP 检测、Hosts 管理、备份回滚、自动更新、CLI 命令 5 个模块
openspec/changes/github-buddy/specs/auto-update/	目录	「IP 自动更新」功能模块的专属目录
openspec/changes/github-buddy/specs/auto-update/spec.md	文件	定时自动更新（缓存机制、过期检查、配置管理）
openspec/changes/github-buddy/specs/backup-rollback/	目录	「hosts 备份与回滚」功能模块的专属目录
openspec/changes/github-buddy/specs/backup-rollback/spec.md	文件	hosts 安全保障（自动备份、一键回滚、完整性校验）
openspec/changes/github-buddy/specs/cli-commands/	目录	「CLI 命令」功能模块的专属目录
openspec/changes/github-buddy/specs/cli-commands/spec.md	文件	命令行界面（init/update/rollback/status + 错误处理 + 日志）
openspec/changes/github-buddy/specs/hosts-management/	目录	「hosts 文件管理」功能模块的专属目录
openspec/changes/github-buddy/specs/hosts-management/spec.md	文件	「跨平台 hosts 文件管理（自动识别、提权、标记区块、增量更新）
openspec/changes/github-buddy/specs/ip-detection/	目录	「IP 检测与筛选」功能模块的专属目录
openspec/changes/github-buddy/specs/ip-detection/spec.md	文件	智能 IP 检测与质量筛选（多维度检测、评分排序、兜底切换）
openspec/changes/github-buddy/tasks.md	文件	实现任务清单 — 9 个任务分组、37 个可追踪的实现任务

在这个过程中，如何AI设计的不符合预期，可对话方式优化，比如开发语言采用了C++17，需要改为Go1.21+。所有问题都确认好后，即可执行“/opsx:apply”驱动开发。

编写代码

执行“/opsx:apply”，AI即开始根据specs目录下的文件，生成对应的代码。AI会安装task.md中的任务，逐步完成代码实现。如下是部分任务实现过程：

好的！状态是 ready，41 个任务，0 个已完成。现在读取所有上下文文件来开始实现。proposal.md 已在附件中，让我读取其余的上下文文件：

读取文件
design.md
读取文件
tasks.md
读取文件
spec.md
读取文件
spec.md
读取文件
spec.md
读取文件
spec.md
读取文件
spec.md
所有上下文文件已读取完毕。让我先查看当前项目目录结构：

查找目录
github-buddy
好的，项目目前只有 doc/ 和 openspec/ 目录，没有任何代码文件。从零开始！

Implementing: github-buddy (schema: spec-driven)
Progress: 0/41 tasks complete
Remaining: 41 tasks

现在开始逐步实现。先从任务 1.1 开始：

Working on task 1/41: 1.1 初始化 Go Module 项目结构
执行命令
cd /data/workspace/github.com/eyjian/github-buddy && go mod init github.com/eyjian/github-buddy && mkdir -p cmd/github-buddy internal/platform internal/storage internal/detector internal/hosts internal/backup internal/cache internal/config internal/logger pkg
现在创建 main.go 入口文件：

编辑文件
main.go
创建根命令占位文件（将在任务 1.2 中完善）：

编辑文件
root.go
现在标记任务 1.1 完成，同时开始安装依赖（任务 1.2）：

执行命令
cd /data/workspace/github.com/eyjian/github-buddy && go get github.com/spf13/cobra@latest github.com/rs/zerolog@latest gopkg.in/natefinch/lumberjack.v2@latest && go mod tidy
依赖安装成功。验证编译是否通过：

执行命令
cd /data/workspace/github.com/eyjian/github-buddy && go build ./cmd/github-buddy/ && echo "BUILD SUCCESS"
编译成功！现在标记任务 1.1 和 1.2 完成，然后继续实现任务 1.3（平台抽象层）和 1.4（存储模块）：

编辑文件
tasks.md
✓ Task 1.1 complete
✓ Task 1.2 complete

。。。。。。

Working on tasks 25-30/41: CLI 命令实现
现在实现日志系统（任务 7.1-7.3，CLI 命令依赖日志），然后是 CLI 命令。

编辑文件
logger.go
现在实现 CLI 命令。首先更新 root.go 加入日志初始化和全局参数：

编辑文件
root.go

现在实现 init 命令：

编辑文件
cmd_init.go
编辑文件
cmd_update.go
编辑文件中

在这个“/opsx:apply”过程中，AI不但自动编写代码，还会自动编译代码，同时还好对程序进行测试，确保代码质量，这是一个迭代过程，但都是AI在吭哧吭哧的干，基本不需要人工参与。

在“/opsx:apply”完成后，会给出执行总结：

Implementation Complete

Change: github-buddy
Schema: spec-driven
Progress: 41/41 tasks complete ✓

已完成的 9 大模块

阶段	模块	文件
1. 项目基础	Go Module + cobra + zerolog	cmd/github-buddy/main.go, root.go, go.mod
2. IP 检测	数据源获取 + ICMP/TCP 检测 + 评分筛选	internal/detector/ (6 个文件)
3. Hosts 管理	读取/写入/标记区块/冲突检测	internal/hosts/ (4 个文件)
4. 备份回滚	自动备份 + SHA256 校验 + 回滚恢复	internal/backup/backup.go
5. 缓存配置	IP 缓存 + 过期检查 + 配置管理	internal/cache/ + internal/config/
6. CLI 命令	init update rollback / status	cmd/github-buddy/cmd_*.go (4 个文件)
7. 日志系统	zerolog + lumberjack 双后端	internal/logger/logger.go
8. 测试	4 个 _test.go 文件，全部通过	detector hosts backup / platform
9. 构建分发	Makefile + GitHub Actions + Goreleaser	Makefile, .github/, .goreleaser.yml

四个核心命令

• github-buddy init — 初始化目录、首次检测最优 IP、更新 hosts

• github-buddy update — 强制重新检测、备份并更新 hosts

• github-buddy rollback — 从备份恢复 hosts 文件

• github-buddy status — 实时检测并展示当前状态表格

所有任务已完成！可以使用 /opsx:archive 来归档这个变更。

可以看到AI输出的结构很标准漂亮：

[.../workspace/github.com/eyjian/github-buddy]# tree .
.
├── cmd
│   └── github-buddy
│       ├── cmd_init.go
│       ├── cmd_rollback.go
│       ├── cmd_status.go
│       ├── cmd_update.go
│       ├── main.go
│       └── root.go
├── doc
│   ├── ai_requirements.md
│   ├── Getting_Started_with_OpenSpec.md
│   └── manual_requirements.md
├── github-buddy
├── go.mod
├── go.sum
├── internal
│   ├── backup
│   │   ├── backup.go
│   │   └── backup_test.go
│   ├── cache
│   │   └── cache.go
│   ├── config
│   │   └── config.go
│   ├── detector
│   │   ├── defaults.go
│   │   ├── detector.go
│   │   ├── detector_test.go
│   │   ├── ping.go
│   │   ├── scorer.go
│   │   ├── source.go
│   │   ├── tcp.go
│   │   └── types.go
│   ├── hosts
│   │   ├── block.go
│   │   ├── conflict.go
│   │   ├── hosts_test.go
│   │   ├── reader.go
│   │   └── writer.go
│   ├── logger
│   │   └── logger.go
│   ├── platform
│   │   ├── platform.go
│   │   └── platform_test.go
│   └── storage
│       └── storage.go
├── Makefile
├── openspec
│   └── changes
│       └── github-buddy
│           ├── design.md
│           ├── proposal.md
│           ├── specs
│           │   ├── auto-update
│           │   │   └── spec.md
│           │   ├── backup-rollback
│           │   │   └── spec.md
│           │   ├── cli-commands
│           │   │   └── spec.md
│           │   ├── hosts-management
│           │   │   └── spec.md
│           │   └── ip-detection
│           │       └── spec.md
│           └── tasks.md
└── pkg

22 directories, 42 files

AI自动生成的命令标准专业，中英文混合了，这个可通过对话调整为英文，也可通过设置rule方式约束好，省去每次都要调整的麻烦。

[.../workspace/github.com/eyjian/github-buddy]# ./github-buddy -h
GitHub-Buddy 通过智能维护 GitHub 域名-IP 映射并修改系统 hosts 文件，
解决开发者执行 go mod tidy 和 git clone 时的网络访问问题。

Usage:
  github-buddy [command]

Available Commands:
  completion  Generate the autocompletion script for the specified shell
  help        Help about any command
  init        初始化 github-buddy
  rollback    回滚 hosts 文件
  status      查看当前状态
  update      强制更新 GitHub IP

Flags:
  -f, --force     跳过确认提示，强制执行
  -h, --help      help for github-buddy
  -v, --verbose   输出详细日志到控制台
      --version   version for github-buddy

Use "github-buddy [command] --help" for more information about a command.