OpenSpec：面向 AI 编程助手的规范驱动开发框架

这是什么

OpenSpec 是由 Fission-AI 推出的开源规范驱动型 AI 编程工作流框架，主语言为 TypeScript。它旨在解决 AI 辅助编程中“需求在聊天历史中模糊不清”导致的不可预测性问题。

OpenSpec 的核心哲学是 “Fluid not rigid”（流体而非僵化） 和 “Iterative not waterfall”（迭代而非瀑布流）。它通过引入一个轻量级的“规范层（Spec Layer）”，强制在编写任何代码之前，让人类与 AI 就“构建什么”达成共识。

该项目目前 GitHub Star 数超过 56,000，支持 Node.js 20.19.0 及以上版本，并兼容 pnpm、yarn、bun 和 nix 等包管理器。它不仅仅是一个工具，更是一套通过 Slash Commands（斜杠命令）与 AI 编码助手交互的标准协议。

解决的问题

在传统的 AI 编程场景中，存在以下痛点：

1. 上下文污染与遗忘：AI 编码助手（如 Cursor、Copilot 等）的能力强大，但往往不可预测。如果需求仅存在于聊天历史中，随着对话轮次增加，上下文窗口会被稀释，导致 AI 偏离初衷或产生幻觉。
2. 缺乏结构化验证：没有明确的规范文档，开发者难以判断 AI 生成的代码是否真正满足了业务需求，导致大量的返工和调试。
3. Brownfield（遗留项目）适配难：许多现有的规范工具（如 Spec Kit）过于重量级，依赖严格的阶段门控（Phase Gates）和复杂的 Python 环境，难以融入快速迭代的现代前端或全栈开发流程。

OpenSpec 通过引入 proposal.md、specs/、design.md 和 tasks.md 等标准化工件，将模糊的自然语言需求转化为结构化的、可追溯的技术规范，确保 AI 在清晰的约束下执行任务。

核心功能

OpenSpec 提供了一套基于命令行的交互工作流，主要包含以下核心机制：

1. 基于工件的工作流（Artifact-Guided Workflow）

每个功能变更都会生成一个独立的目录结构，包含：

• proposal.md：阐述“为什么做”以及“变更范围”。
• specs/：定义具体的需求和场景（Requirements and Scenarios）。
• design.md：记录技术实现方案。
• tasks.md：可执行的实现清单（Implementation Checklist）。

2. 交互式 Slash Commands

开发者通过终端与 AI 交互，常用命令包括：

• /opsx:explore：无压力的思维伙伴。AI 会阅读代码，权衡选项，在编写代码前制定计划。适合需求不明确时。
• /opsx:propose <idea>：直接提出想法，AI 自动生成上述规范工件。
• /opsx:apply：根据 tasks.md 执行具体的代码实现任务。
• /opsx:archive：将完成的功能归档，更新规范，清理上下文，准备下一个功能。

3. 多工具兼容与扩展性

• 支持 25+ 种工具：OpenSpec 不绑定特定 IDE，通过插件机制兼容主流 AI 编码助手。
• 自定义工作流：支持通过 openspec config profile 切换扩展工作流（如 /opsx:new, /opsx:continue 等）。
• 第三方 Schema Bundles：允许社区分发 opinionated workflows，类似 GitHub Spec Kit 的扩展目录，可集成其他工具。

4. 上下文卫生（Context Hygiene）

OpenSpec 强调在实施前清理 AI 的上下文窗口，并在整个会话中保持上下文整洁。这有助于提高高推理模型（如 Codex 5.5, Opus 4.7）的表现，减少因上下文过载导致的错误。

亮点 / 与同类相比

OpenSpec 的核心优势在于其轻量化和灵活性，特别强调对遗留项目（Brownfield）的支持。

| 对比维度 | OpenSpec | Spec Kit (GitHub) | Kiro (AWS) | 无规范 (Nothing) | | :--- | :--- | :--- | :--- | :--- | | 重量级 | 轻量，基于 Markdown 和 CLI | 重量级，依赖 Python 环境 | 中等，绑定特定 IDE | 无 | | 工作流 | 流体迭代，无僵化阶段门控 | 严格瀑布流，阶段门控多 | 锁定在 AWS 生态 | 无结构，随意对话 | | 兼容性 | 通用，支持 20+ AI 助手 | 有限，侧重 Python/Markdown | 锁定，仅限 Claude 模型及特定 IDE | 任意 | | 适用场景 | 个人项目到企业级，尤其适合 Brownfield | 大型严肃工程 | AWS 内部或特定集成 | 简单脚本或原型 | | 可预测性 | 高，先规范后代码 | 高，但流程繁琐 | 高，但工具受限 | 低，依赖提示词技巧 |

关键亮点：

• Brownfield First：专为已有代码库设计，而非仅适用于从零开始的新项目（Greenfield）。
• Human-AI Alignment：在代码写入前，强制人类与 AI 对齐意图，减少“构建错了东西”的风险。
• 模块化规范：每个变更独立文件夹，便于版本控制和团队协作。

适合谁用 / 上手

适合人群

• 使用 AI 编码助手的开发者：尤其是那些感到 AI 生成代码不可控、需要更结构化流程的开发者。
• 中小型团队：需要快速迭代，但希望保持代码质量和需求一致性的团队。
• 遗留项目维护者：需要在不重构整个项目结构的前提下，引入规范化管理的 Brownfield 项目。
• 追求高效工作流的极客：喜欢通过 CLI 和 Slash Commands 控制开发节奏的用户。

上手指南

1. 环境要求：Node.js 20.19.0 或更高版本。

2. 安装：

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

3. 初始化： 进入项目目录并运行：

   openspec init
   

4. 开始使用：

   • 探索阶段：如果不确定做什么，使用 /opsx:explore。
   • 提案阶段：如果已有想法，使用 /opsx:propose "your idea"。
   • 实施阶段：AI 生成规范后，使用 /opsx:apply 执行代码。
   • 归档阶段：完成后使用 /opsx:archive 清理上下文。

5. 更新与配置：

   • 升级包：npm install -g @fission-ai/openspec@latest
   • 刷新 AI 指令：在项目内运行 openspec update 以激活最新的斜杠命令。

6. 贡献与反馈：

   • 小修复（Bug、拼写）可直接提交 PR。
   • 大功能需先提交 OpenSpec 变更提案。
   • 支持匿名遥测，可通过设置 OPENSPEC_TELEMETRY=0 或 DO_NOT_TRACK=1 禁用。

更多详细文档、工作流示例和故障排除指南，请参考其官方文档首页。