OpenSpec
为AI编程助手提供结构化「规格先行」工作流，解决方向漂移和返工问题
加载项目详情…
本应用为开源项目，仅供学习研究，请遵守其开源协议。
微信扫码咨询客服
POMOAI — 让开源 AI 即刻运行
为AI编程助手提供结构化「规格先行」工作流，解决方向漂移和返工问题
加载项目详情…
本应用为开源项目，仅供学习研究，请遵守其开源协议。
想象一下：你请了一位超级能干的助手帮你装修房子，但你只跟他说"帮我把家弄好看点"。他会怎么干？大概率会东敲一下西补一下，最后出来的效果和你想象的天差地别。
AI 编程助手也面临同样的困境——没有清晰的规格说明（Spec），它就只能靠猜。Chat History 里的上下文是模糊的、碎片化的，AI 很容易在实现过程中跑偏，然后花大量时间返工。
OpenSpec 就是来解决这个问题的——它为 AI 编程助手提供了一套结构化的「施工图纸」工作流，让人类和 AI 在写代码之前先对齐：我们要做什么、做成什么样、怎么做。
AI 编程助手在 2023-2024 年迎来爆发，Claude Code、GitHub Copilot、Cursor 等工具让「用自然语言写代码」成为现实。但热潮之下，一个根本性问题始终存在：AI 生成代码的质量取决于 prompt 的清晰程度，而大多数人的 prompt 其实是模糊的。
模糊的 prompt 导致：
GitHub 早在 2024 年初就推出了 Spec Kit，主打「规格驱动开发」（Spec-Driven Development，SDD）概念，但 Spec Kit 设计偏重、流程僵硬，需要 Python 环境、phase gate 机制，不够灵活。
OpenSpec 的诞生就是为了让 SDD 变得轻盈、迭代、实用。
OpenSpec 是一个AI 原生的 CLI 工具，通过一套约定的目录结构 + slash 命令，让 AI 编程助手在写代码前先产出结构化的规格文档。
核心哲学五条：
OpenSpec 最常用的工作流只有三步：
第一步：提出提案 /opsx:propose "你要做什么"
用户: /opsx:propose add-dark-mode
AI: Created openspec/changes/add-dark-mode/
✓ proposal.md — 为什么做这个改动
✓ specs/ — 需求和场景
✓ design.md — 技术方案
✓ tasks.md — 实施清单
第二步：应用实现 /opsx:apply
AI 根据 tasks.md 逐项执行，实现代码。
第三步：归档 /opsx:archive
提案归档到 openspec/changes/archive/，规格文档更新，准备下一个循环。
这套工作流解决了两个核心问题：对齐预期（proposal + specs）和保持专注（tasks 清单不跑偏）。
OpenSpec 为每个提案创建一个独立的 change folder，结构如下：
openspec/changes/
add-dark-mode/
proposal.md — 改动动机
specs/ — 规格说明（.md 文件）
design.md — 技术设计
tasks.md — 实施清单
archive/ — 归档后移入此处
这个结构让每次改动都有完整的上下文记录。即使 AI 在中途换人（换了一个新的对话 session），新的 AI 也能从文件夹里恢复所有上下文，不需要人类重新解释。
OpenSpec 不绑定特定工具，支持主流的 AI 编程助手：
| 类别 | 工具 |
|---|---|
| CLI | Claude Code、OpenCode、Cosmo、Cline |
| IDE | Cursor、Zed、Windsurf、Copilot |
| 其他 | Roo Code、LLM Code、Swe-agent 等 |
每个工具通过 slash 命令（如 /opsx:propose）触发，工具无关，workflow 统一。
npm、pnpm、yarn、bun 均支持，甚至还有 Nix flakes 安装方式。Node.js >= 20.19.0 即可。
npm install -g @fission-ai/openspec@latest
cd your-project
openspec init
/opsx:propose "add-login-feature"
OpenSpec 提供了完整的 .devcontainer/devcontainer.json 配置，可以在 Docker 容器中开发。如果团队使用 Dev Container 工作流，可以一键拉起带 OpenSpec 依赖的开发环境。
OpenSpec 使用 TypeScript 开发，发布为 npm 包 @fission-ai/openspec，是一个 Node.js CLI 工具。
核心技术栈：
| 组件 | 技术选型 | 作用 |
|---|---|---|
| 核心语言 | TypeScript | 类型安全 |
| CLI 框架 | Commander | 命令行参数解析 |
| 交互提示 | @inquirer/core + @inquirer/prompts | 交互式命令行界面 |
| 数据验证 | Zod | 规格文件 schema 验证 |
| YAML 处理 | yaml | 解析和生成 YAML 配置 |
| 文件匹配 | fast-glob | 快速扫描项目文件 |
| 遥测 | posthog-node | 匿名使用统计（可关闭） |
代码结构（src/）：
src/
cli/ — CLI 入口
commands/ — 各个 slash 命令实现（propose, apply, archive 等）
core/ — 核心逻辑（目录结构、文件生成）
prompts/ — AI prompt 模板
telemetry/ — 遥测模块
ui/ — 终端 UI 组件（进度条等）
utils/ — 工具函数
测试框架： Vitest（现代、快速、TypeScript 原生支持）
Schema 系统： schemas/spec-driven/ 和 schemas/workspace-planning/ 提供两类规格模板，支持自定义扩展。
Nix 支持： 项目包含 flake.nix，Nix 用户可以通过 nix develop 或 flakes 直接进入开发环境。
OpenSpec 是一个纯本地 CLI 工具，所有文件都存在本地项目目录下，不上传到任何服务器。
内置的匿名遥测（PostHog）只收集命令名和版本号，不收集任何参数、路径、文件内容或个人信息。可通过以下方式完全关闭：
export OPENSPEC_TELEMETRY=0
# 或
export DO_NOT_TRACK=1
OpenSpec 并非银弹，有几个值得注意的点：
1. 依赖 AI 自觉执行工作流 AI 有时会在压力大的时候跳过 proposal/specs 阶段直接写代码。需要人类主动要求 AI 先做规格文档。
2. 不适合简单改动 加个注释、改个变量名这种微小改动，用 OpenSpec 反而增加开销。项目越大、工作流越复杂，OpenSpec 的价值越明显。
3. Context 管理仍需手动 虽然解决了规格文档的问题，但 AI 的 context window 管理仍需要开发者主动清理，否则大项目仍会遇到 context 溢出。
4. 与 IDE 深度集成为时尚早 目前主要是 CLI 工具，IDE 插件（如 VS Code / Cursor Extension）尚未成熟，体验依赖 AI 工具对 slash 命令的支持程度。
5. 与 GitHub Spec Kit 的关系 GitHub Spec Kit 走的是重型企业路线，OpenSpec 走轻量路线。两者定位不同，并非直接竞争，但用户在选型时需要权衡「规范度」和「灵活性」。
OpenSpec 背后反映的是一个更大的趋势：AI 编程正在从「 prompt 即一切」走向「工作流即一切」。
早期大家关注的是 prompt 工程技巧，后来关注的是模型能力（o1、Claude Sonnet）。但真正的工程化落地，需要的不只是更强的模型，还需要可靠的开发流程。
Spec-Driven Development 在传统软件开发中是常识，在 AI 编程中却被忽视了太久。OpenSpec 的出现填补了这个空白——它不是又一个 AI 工具，而是一个让 AI 工具可靠工作的元工具（tool for AI tools）。
图1：OpenSpec 工作流示意——提案创建后的目录结构
总结一句话： OpenSpec 是 AI 编程助手的「规格先行」框架，通过结构化的提案→规格→任务→归档工作流，让人类和 AI 在写代码之前先对齐预期，解决 AI 编程中「方向漂移、频繁返工」的核心痛点。