2026 年 9 月 16 日，GitHub 获得 68,666 颗星的 AI 编程工作流工具 OpenSpec 冲上 Hacker News 首页，最新 v1.13.1 版本在次日清晨火速释出。很多使用 Cursor、Claude Code 或 Codex 的开发者以为这是一个替代 IDE 的重型脚手架，其本质是提示词工程的产品化封装。它解决的不是大模型代码生成能力不足，而是需求散落在长对话历史中必然带来的上下文遗忘与行为漂移。
AI 编程陷入混乱的根本原因在于需求只活在临时聊天框里。OpenSpec 将模糊的需求、技术约束与验收标准固化成一组带结构的标准 Markdown 文件，再由命令行接口在恰当时机注入 AI 助手的上下文窗口，把凭感觉改代码变成先立字据再打勾交付。
架构逻辑与提示词工程落地
OpenSpec 的核心理念被称为规格驱动开发（Spec-Driven Development，简称 SDD），即在生成实际业务代码前，开发者必须与 AI 就“要改什么”达成书面共识。
项目初始化后会在根目录生成清晰的目录树：
openspec/
├── specs/ # 事实来源：记录系统当前的既有行为，按业务领域分目录
│ └── <domain>/spec.md
├── changes/ # 提议中的修改，每个变更独立建档
│ └── <change-name>/
│ ├── proposal.md # 变更意图、范围与实现方案
│ ├── design.md # 技术方案与关键架构决策
│ ├── tasks.md # 带复选框的结构化执行清单
│ └── specs/ # 差异规格：相对现状的增量变更
│ └── <domain>/spec.md
└── config.yaml # 项目级上下文与约束规则
整个框架最关键的设计是差异规格（Delta Specs）。OpenSpec 不要求在每次修改时重写整个系统的规格说明，而是使用三段式区块界定变更范围：
## ADDED Requirements
### Requirement: Theme selection
The app SHALL let users switch between light and dark themes, defaulting to the system preference.
#### Scenario: User toggles dark mode
- **WHEN** the user clicks the theme toggle
- **THEN** the app switches to dark mode and persists the choice
## MODIFIED Requirements
（修改既有规格，注明 Previously: ...）
## REMOVED Requirements
（废弃已不需要的旧规格）
每一个需求使用声明式的 SHALL 或 MUST 规范描述，搭配 GIVEN/WHEN/THEN 场景。AI 负责根据讨论生成这些断言，开发者在敲定方案前进行文本审查，从而规避模型在大型任务中擅自做主的问题。
安装准备与核心工作流实操
安装前需确保本地 Node.js 版本达到 20.19.0 或更高。全局安装后即可在目标仓库初始化：
npm install -g @fission-ai/openspec@latest
cd your-project
openspec init
新手入门最常遇到的混淆在于执行位置：
openspec ...系列命令在终端命令行中执行，用于状态检查、配置和文件合并。/opsx:...系列斜杠命令直接在 AI 助手的日常聊天框中敲入，是调用提示词技能的入口。
由于各家 AI 工具对技能语法的解析不同，命令名会略有变形。例如 Claude Code 与 Gemini CLI 使用 /opsx:propose，Cursor 和 GitHub Copilot 采用 /opsx-propose，Codex CLI 采用 $openspec-propose，而 Kimi Code 则映射为 /skill:openspec-。在执行 openspec init 后，终端会打印当前工具对应的准确前缀。
/opsx:explore ──► /opsx:propose ──► /opsx:apply ──► /opsx:sync ──► /opsx:archive
(梳理现状) (产出方案清单) (逐项实现代码) (合并增量规格) (归档完成沉淀)
在日常开发中，建议遵循标准的五步链路：
- /opsx:explore：先让 AI 阅读代码库、梳理路由与中间件走向，把模糊想法收敛为明确范围，期间不写入业务代码。
- /opsx:propose：建立变更文件夹，一次性生成
proposal.md、design.md、specs/和tasks.md。 - /opsx:apply：确认规划无误后让 AI 逐行实现代码，每完成一步在
tasks.md中勾选对应项。 - /opsx:sync：将已完成的差异规格合并回
openspec/specs/主干。 - /opsx:archive：归档已交付任务，使主规格目录沉淀为系统的最新真实状态。
在已有代码库（Brownfield）中落地时，完全不需要预先给所有祖传代码补齐规格文档。OpenSpec 采用增量生长机制，开发者只需挑一个本周计划要做的小改动，让 AI 读取相关模块生成第一份差异规格，随着迭代推进，系统规格文档会自然成型。
项目配置与 CI 规则注入
通过在 openspec/config.yaml 中配置项目级上下文，可以省去每次在聊天中反复黏贴技术栈与代码规范的麻烦：
schema: spec-driven
context: |
Tech stack: TypeScript, React, Node.js
API conventions: RESTful, JSON responses
Testing: Vitest for unit tests, Playwright for e2e
Style: ESLint with Prettier, strict TypeScript
rules:
proposal:
- Include rollback plan
- Identify affected teams
specs:
- "Use Given/When/Then format for scenarios"
design:
- Include sequence diagrams for complex flows
配置文件在解析时有严格的注入逻辑：context 内容会被 rules 内容则根据产物类型注入对应的
AI 编程在缺乏规格管控时往往会随着项目膨胀而逐渐失效，下表对比了不同协作阶段的典型失控问题与解决路径：
| 阶段 | 核心问题 | 留下的硬伤 |
|---|---|---|
| 单次提问 (Raw Prompt) | 需求全凭对话维持，多轮调试后早期约束被截断遗忘 | 代码越改越乱，修好新 Bug 引发未知旧 Bug |
| 规则注入 (.cursorrules) | 约束大多为全局通用准则，无法针对单次复杂重构建立验收边界 | 缺乏分步跟踪机制，遇到大型改动模型容易中途放弃或假装完成 |
| 规格驱动 (OpenSpec) | 规划与落地强绑定，先审阅设计差异与任务清单，再让 AI 照单勾选 | 文档需额外审查，对极小型单行改动存在一定流程成本 |
避坑指南与已知缺陷
在实际落地与持续集成过程中，需格外警惕官方近期修复及社区已确认的几个潜在问题：
1. Windows 环境归档可能静默回滚 在 Windows 11 环境下执行 openspec archive 时，可能因系统权限策略触发重命名 EPERM 报错。此时 CLI 虽然前置打印了成功更新规格的日志，但实际已触发事务撤销，导致主规格文件未生成、残留空目录且 Git 状态显示干净。临时绕过方式是将增量文件中的 ## ADDED Requirements 手动改成 ## Requirements 后合并至主文件，再手工移入归档目录。
2. 配置文件 YAML 冒号解析隐患 在 config.yaml 的规则列表里，如果直接书写带冒号加空格的文本（例如 - Keep the "Why" section concrete: what breaks today），YAML 解析器会将其错误识别为映射而非字符串数组。该错误在终端只会打印一条 stderr 警告，而 CI 执行 openspec validate 时不会校验配置文件完整性，导致整套规则在无报错的情况下被静默丢弃。在编写规则时，务必给整行文本包裹双引号。
3. 任务清单标记严格性 在 v1.13.1 版本中，任务清单仅对 [x] 与 [X] 识别为已完成（支持中括号内包含空格）。若使用 - [~] 1.2 Deferred 等自定义符号，系统会统一判定为未完成，在执行归档校验时会直接拦截。
综合判断与发展边界
OpenSpec 不是又一个企图接管代码生成的庞大 Agent 框架，而是一套专为长生命周期项目设计的状态治理协议。它纠正了一种常见误读：许多开发者认为写提示词就是追求一句话直接生成完美应用，但在真实工程中，将 AI 约束在可复核的设计清单内逐步落地，远比赌单次生成的运气更为稳健。
它适合跨会话续做的复杂功能、重构任务与团队协作项目；对于纯探索性质的临时脚本或几行代码的微调，它的流程确实偏重。一个尚未彻底解决的工程问题在于：当主干业务逻辑演进数月后，如何低成本确保早前归档的历史规格文档不会与实际代码库形成事实上的语义脱节。
引用来源
- GitHub Repository: Fission-AI/openspec (Release v1.13.1), 2026-09-17, https://github.com/Fission-AI/openspec
- Hacker News: OpenSpec – Spec-driven development for AI coding assistants (Story 49734264), 2026-09-16, https://news.ycombinator.com/item?id=49734264
- GitHub Issue #1895: openspec archive fails with EPERM on Windows 11, 2026-09-16, https://github.com/Fission-AI/openspec/issues/1895
- GitHub Issue #1892: config.yaml parse failure prints warning, exits 0, 2026-09-15, https://github.com/Fission-AI/openspec/issues/1892
- GitHub Issue #1891: Rules key dropped when containing unquoted colon-space, 2026-09-14, https://github.com/Fission-AI/openspec/issues/1891
