OpenSpec 深度指南

OpenSpec 是一个规格驱动的 Agent 开发框架。它要求先描述变更、规格和任务，再让 AI Coding Agent 按规格实现。

是什么

很多 Agent 开发失败，不是因为模型不会写代码，而是因为需求没有被说清楚。OpenSpec 解决的是这个问题：在编码前先建立一个项目级规格目录，把“为什么改、改什么、怎么验收”写下来。

初始化后，项目里会出现类似结构：

openspec/
  project.md
  specs/
  changes/
    archive/

然后你通过 /opsx:* 这类命令让 Agent 创建变更、补规格、写任务和执行实现。

官方地址

类型	地址
官网	https://openspec.dev/
官方文档	https://openspec.pro/getting-started/
官方 GitHub	https://github.com/Fission-AI/OpenSpec

适用场景

场景	是否推荐
复杂功能开发	推荐
团队希望需求、设计、任务可追踪	推荐
修改会影响多个模块或接口	推荐
一次性小改文案	不必使用
不愿意维护项目规格文档	可能不适合

安装准备

环境	检查命令	说明
Node.js / npm	node --version、npm --version	安装 OpenSpec CLI
Git	git --version	追踪规格变更
Coding Agent	Claude Code、Codex、Cursor、OpenCode 等	加载 OpenSpec 生成的命令
项目根目录	pwd	建议在项目根目录执行 init

安装方式

npm

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

pnpm

pnpm add -g @fission-ai/openspec@latest

yarn

yarn global add @fission-ai/openspec@latest

bun

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

验证：

openspec --version

初始化项目

进入项目根目录：

cd your-project
openspec init

如果要直接指定工具：

openspec init --tools claude
openspec init --tools codex
openspec init --tools all

openspec init 会创建 openspec/ 目录，并根据选择的工具生成对应命令或 skill。

不同工具的文件落点

工具	生成位置	说明
Claude Code	.claude/skills/openspec-*、.claude/commands/opsx/	重启 Claude Code 后加载
Codex	.codex/skills/openspec-*、~/.codex/prompts/opsx-*.md	prompts 可能受 CODEX_HOME 影响
Cursor	.cursor/commands/openspec-*.md	Cursor 命令文件
OpenCode	.opencode/commands/openspec-*.md	OpenCode 命令文件
Windsurf	.windsurf/workflows/openspec-*.md	Windsurf workflow
GitHub Copilot	.github/prompts/openspec-*.prompt.md	Copilot prompt 文件

命令大全

OpenSpec 有两类命令：CLI 命令和 Agent 内部 slash command。

CLI 命令

命令	作用	示例	注意事项
openspec --version	查看版本	openspec --version	安装后先执行
openspec init	初始化当前项目	openspec init	会生成目录和工具集成
openspec init [path]	初始化指定路径	openspec init ./app	默认是当前目录
openspec init --tools claude	只生成 Claude Code 集成	openspec init --tools claude	适合单工具项目
openspec init --tools codex	只生成 Codex 集成	openspec init --tools codex	会涉及 Codex prompts
openspec init --tools all	生成所有支持工具集成	openspec init --tools all	文件较多，团队项目要先确认
openspec list	查看当前 OpenSpec 状态	openspec list	初始化后验证
openspec update	重新生成工具集成文件	openspec update	升级或配置变化后使用

Agent slash commands

不同宿主工具展示方式不同，但核心通常是 opsx 前缀：

命令	作用	示例
/opsx:new	创建新变更	/opsx:new add-dark-mode
/opsx:plan	生成或完善计划	/opsx:plan add-dark-mode
/opsx:implement	按 OpenSpec 任务实现	/opsx:implement add-dark-mode
/opsx:review	审查规格和实现是否匹配	/opsx:review add-dark-mode
/opsx:archive	完成后归档变更	/opsx:archive add-dark-mode

实际命令名称以 openspec init 生成的文件为准。

推荐工作流

创建一个新功能

openspec init
  -> /opsx:new add-dark-mode
  -> 填写 proposal / design / tasks
  -> /opsx:implement add-dark-mode
  -> 运行测试
  -> /opsx:review add-dark-mode
  -> /opsx:archive add-dark-mode

修改已有能力

先让 Agent 阅读 openspec/project.md 和相关 specs/，再创建 change。不要直接让它改代码，否则 OpenSpec 的约束就失效了。

与 Claude Code、Codex、Gemini 的关系

OpenSpec 不是 Coding Agent 本身，而是“规格层”。它通过生成不同宿主可识别的命令和 skill，让 Claude Code、Codex、Cursor、OpenCode 等工具按相同的规格目录工作。

工具	推荐方式
Claude Code	openspec init --tools claude
Codex	openspec init --tools codex
多工具团队	openspec init --tools all 后把不需要的文件排除

安全建议

• openspec/ 是项目资产，团队项目建议纳入版本控制。
• 初始化前先看 git status，避免混入无关变更。
• --tools all 会生成较多工具文件，先确认团队是否需要。
• Codex prompts 可能写到用户级目录，卸载时别只删项目文件。
• 规格不等于真相，最终仍要用测试和 review 验证。

排错

slash command 没出现

重启对应 Agent。很多工具只在启动时扫描命令文件。

Claude Code 可检查：

ls .claude/skills
ls .claude/commands/opsx

Codex 可检查：

ls .codex/skills
ls ~/.codex/prompts

想添加另一个工具

如果项目已经初始化，可以再次运行：

openspec init --tools codex

OpenSpec 会进入扩展模式，补充对应工具文件。

想清理 OpenSpec

官方公开 CLI 文档没有统一的项目卸载命令。实用做法是手动删除生成文件：

rm -rf openspec
rm -rf .claude/skills/openspec-*
rm -rf .claude/commands/opsx
rm -rf .codex/skills/openspec-*
rm -f ~/.codex/prompts/opsx-*.md

执行前一定先确认这些文件确实不再需要。

总结

OpenSpec 适合复杂需求和团队协作。它牺牲了一点“马上开写”的速度，换来更清晰的需求、可追踪的变更和更稳定的 Agent 执行边界。

如果你的 AI 编程已经从“试试看”进入“真实交付”，OpenSpec 值得作为项目流程的一部分。