OpenSpec 构建“共识规范 → AI 执行 → 自动验证 → 变更归档”的闭环，大幅提升开发确定性与可维护性。其核心理念是 先定规范，再写代码，为开发者与 AI 助手建立明确的协作“契约”，不绑定特定 AI 工具、无需 API 密钥，可无缝融入现有开发流程——尤其适配存量项目（1→n）的功能迭代。
该框架直面当前 AI 编程三大现实挑战：
- CHALLENGE 01 需求歧义问题：AI 理解与开发者需求存在偏差，自然语言描述缺乏结构化约束，导致“猜需求”现象频发，开发方向易偏离；
- CHALLENGE 02 代码可追溯性缺失：缺乏系统性的变更历史记录，难以进行审计与回溯分析，团队成员交接成本高昂；
- CHALLENGE 03 协作效率低下：编码前缺乏共识建立机制，返工率高、沟通成本大，新成员上手困难、学习曲线陡峭。
OpenSpec 通过三阶段演进机制系统性破局：
STEP 01 前置约束机制
在编码开始前建立明确的功能边界，通过结构化 spec 锁定功能描述、输入输出、边界条件和测试用例等关键要素，从源头消除语义模糊。
STEP 02 契约式协作模型
为开发者与 AI 助手建立权威协作契约，将 spec.md 作为双方理解与执行的唯一依据，显著提升协作确定性与可审查性。
STEP 03 轻量无侵入设计
极简配置要求，零架构改造承诺，所有能力均通过命令行工具集交付，特别适配存量项目的渐进式功能迭代场景。
三阶段变更管理流程
OpenSpec 的核心工作流围绕 changes/ 提案目录与 specs/ 规范目录展开，形成清晰的“提案—实施—归档”生命周期：
-
Stage 1：创建变更
触发条件包括：添加新功能、进行重大变更（API/架构）、更改模式、优化性能（改变行为）、更新安全策略等。
此阶段生成 changes/<change-name>/ 目录，内含：
proposal.md：说明“为什么做、做什么、影响范围”tasks.md：结构化任务清单（支持依赖关系与并行标记）specs/ 子目录：存放增量规范文件（如 specs/chat-input/spec.md），按 capability 组织- （可选）
design.md：用于跨领域、高风险或需技术权衡的变更
-
Stage 2：实施变更
按 tasks.md 清单逐项执行，严格遵循 proposal.md 与 design.md 约定。每项任务完成后标记为 [x]，确保可验证、可追踪。
-
Stage 3：归档变更
部署验证通过后，执行 openspec-cn archive <change-name>，自动完成：
- 将
changes/<change-name>/ 移至 changes/archive/YYYY-MM-DD-<change-name>/
- 将增量规范合并至
specs/<capability>/spec.md
- 更新全局规范状态，供后续变更引用
整个流程由 template system 动态驱动，通过 AGENTS.md 统一注入 AI 工具上下文，并原生集成斜杠命令（如 /openspec-proposal），实现 IDE 内一键触发。
命令行工具集：覆盖完整生命周期
OpenSpec 提供开箱即用的 CLI 工具集，覆盖从初始化到归档的全部环节：
| 命令 |
功能 |
使用场景 |
openspec-cn init |
初始化项目，创建核心目录结构 |
新项目启动时 |
openspec-cn new <change-name> |
创建新的变更提案 |
需要新增功能或进行重大变更时 |
openspec-cn list |
查看所有活动变更 |
日常开发状态检查 |
openspec-cn show <change-name> |
查看变更详情 |
详细了解某个变更的具体内容 |
openspec-cn validate <change-name> |
验证规范格式正确性 |
提交前确保规范格式正确、语义完备 |
openspec-cn archive <change-name> |
归档变更，合并增量并移至历史 |
变更完成后进行归档 |
openspec-cn view |
启动交互式规范仪表板 |
可视化查看 spec 与 change 状态 |
终端中运行 openspec-cn view 后，可直观看到当前项目摘要：
base
OpenSpec 仪表板
摘要：
● 规范：1个规范，1个需求
● 活动变更：0个进行中
● 已完成变更：0
规范
■ chat-input 1需求
使用 openspec-cn list --changes 或 openspec-cn list --specs 查看详细信息
同时支持细粒度查询：
openspec-cn list --specs # 列出所有已部署规范
openspec-cn list --changes # 列出所有待处理变更
目录结构：规范与提案分离设计
OpenSpec 采用清晰的双轨目录结构，实现“已构建”与“应改变”的物理隔离：
openspec/
├── project.md # 项目级约定（技术栈、代码风格、Git 流程等）
├── specs/ # 当前真相 —— 已构建并部署的内容
│ └── [capability]/ # 单一专注功能（如 chat-input、ai-handler）
│ ├── spec.md # 需求与场景定义（权威规范）
│ └── design.md # 技术决策（可选）
└── changes/ # 提案 —— 应该改变的内容
├── [change-name]/ # 如 optimize-token-consumption
│ ├── proposal.md # 为什么、什么、影响
│ ├── tasks.md # 实施清单（带状态标记）
│ ├── design.md # 技术方案（如需）
│ └── specs/ # 增量规范变更
│ └── [capability]/
│ └── spec.md # ADDED/MODIFIED/REMOVED
└── archive/ # 已完成的变更（时间戳归档）
这种设计确保：
specs/ 是可信的“单一事实来源”，代表当前系统行为；changes/ 是可审计的“变更日志”，完整记录每次演进的动机、过程与结果；archive/ 支持按时间回溯，满足合规与知识沉淀需求。
初始化实战：以 Kilo Code 为例
OpenSpec 初始化过程分三步，全程交互式引导：
步骤 1/3：欢迎与基础配置
~/Documents/A_Code/SourceCode/ai-goofish-monitor master > openspec-cn init
OPENSPEC
欢迎使用 OpenSpec!
步骤 1/3
配置您的 OpenSpec 工具
让我们连接您的 AI 助手，让它们理解 OpenSpec。
按回车键继续。■
步骤 2/3：选择 AI 工具
支持主流编码助手，包括：
- Amazon Q Developer、Antigravity、Auggie (Augment CLI)
- Claude Code、Cline、Codex、CodeBuddy Code (CLI)
- Cursor、GitHub Copilot、Gemini CLI、Kilo Code（示例选用）
- 通用
AGENTS.md 兼容方案（适用于 VS Code、Amp 等）
终端中高亮选择 Kilo Code 后确认。
步骤 3/3：确认与生效
Kilo Code
✓ OpenSpec 已初始化。正在检查缺失文件...
AI 工具已配置 ✔
OpenSpec 工具配置已更新！
工具摘要：
为其助手手工创建根 AGENTS.md 存根
已创建：Kilo Code
已跳过：Amazon Q Developer, Antigravity, Auggie, ...（共 18 个）
⚠️ 关键提示：重启您的 IDE，确保斜杠命令在启动时加载；新命令将出现在命令面板中。
初始化后，系统自动生成两类核心文件：
1. openspec/AGENTS.md（主指令模板）
包含完整的三阶段工作流说明、CLI 快速参考、文件用途指南及搜索技巧。所有内容被 <!-- OPENSPEC:START --> 和 <!-- OPENSPEC:END --> 标记包裹，便于后续 openspec-cn update 安全刷新。
2. 根目录 AGENTS.md（存根引用）
仅保留一行指向主文件的引用：
@/openspec/AGENTS.md
该设计统一入口、保障动态更新，避免多处维护不一致。
此外，还生成 .kilocode/workflows/ 下的三类工作流文件：
openspec-proposal.md：专注提案生成（读取 project.md + list + 创建骨架 + 验证）openspec-apply.md：专注代码实施（读取 proposal.md/tasks.md + 执行修改）openspec-archive.md：专注归档收尾（校验状态 + 运行 archive + 验证规范）
所有工作流均受 <!-- OPENSPEC:START/END --> 保护，用户自定义内容永不被覆盖。
规范文件格式：精准、可解析、强约束
OpenSpec 对 spec.md 文件格式有严格约定，确保机器可解析、人工可读、AI 可执行。
以 chat-input 组件语音输入功能为例，其规范片段如下：
# Chat-Input Specification
## Purpose
TBD - created by archiving change add-speech-input-action. Update Purpose after archive.
## 需求：语音输入按钮点击事件
ChatInput 组件的语言输入按钮被点击时，**必须**触发语音输入动作，通知宿主应用启动语音输入功能。
#### 场景：用户点击语音输入按钮
##### 前置条件：
- ChatInput 组件已渲染
- 渲染器上下文 "rendererCtx" 已传入组件
##### 用户操作下：
- 用户点击语音输入按钮（麦克风图标按钮）
##### 预期行为：
- 组件调用 rendererCtx.emitAction(RENDERER_ACTIONS.SPEECH_INPUT)
- 宿主应用接收到 "speechInput" 动作事件
- 宿主应用可据此后语音输入功能（如调用语音识别 API）
#### 场景：渲染器上下文未提供
##### 前置条件：
- ChatInput 组件已渲染
- 渲染器上下文 "rendererCtx" 为空或未传入
##### 用户操作下：
- 用户点击语音输入按钮
##### 预期行为：
- 组件不抛出错误
- 点击操作无副作用（静默忽略）
关键格式规则：
- 必须使用
## 新增需求 / ## 修改需求 / ## 移除需求 / ## 重命名需求 作为一级操作标题；
- 每个需求下至少包含一个
#### 场景：xxx（四级标题），不可用粗体或列表替代；
- 场景内使用
**当** / **那么** / **并且** 结构化表达前置条件与预期行为；
- 使用
MUST / SHALL 表达强制约束，避免 should / may 等模糊措辞。
验证命令 openspec-cn validate <change-id> --strict 会严格校验上述格式，失败时返回精确定位的错误信息，例如：
"变更必须至少有一个增量" → 检查 changes/<name>/specs/ 是否存在 .md 文件；"需求必须至少有一个场景" → 检查是否使用 #### 场景： 格式；"静默场景解析失败" → 推荐调试命令 openspec-cn show <change> --json --deltas-only。
实战案例：优化 Token 消耗的全流程
以 ai-goofish-monitor 项目中“优化 AI 分析 Token 消耗”为例，展示 OpenSpec 全流程落地：
1. 创建提案（Proposal）
执行 openspec-cn new optimize-token-consumption，生成骨架后填充：
proposal.md 明确问题根源（图片 Base64 过大、JSON 冗余、无监控）与四大优化目标；design.md 记录技术决策（如图片最大宽度 1024px、JPEG 质量 85%、卖家评价保留最近 20 条）；tasks.md 拆解为 6 类共 17 项可验证任务，标注依赖与并行关系；specs/ai-handler/spec.md 定义四类新增需求，每类含多个 #### 场景，覆盖正常、边界、禁用等用例。
2. AI 协同实施（Apply）
调用 /openspec-apply.md 工作流，AI 依 tasks.md 顺序修改：
src/config.py：新增 MAX_AI_IMAGES 等环境变量；src/ai_handler.py：新增 optimize_image_for_ai()、prepare_product_data_for_ai() 等函数；requirements.txt：追加 Pillow 依赖；tasks.md：自动将完成项标记为 [x]。
3. 归档与验证（Archive）
确认所有任务完成且测试通过后，执行：
openspec-cn archive optimize-token-consumption --yes
系统自动：
- 将
changes/optimize-token-consumption/ 移入 changes/archive/2025-04-12-optimize-token-consumption/；
- 将增量规范合并至
specs/ai-handler/spec.md；
- 运行
openspec-cn validate --strict 确保归档后规范仍通过全部校验。
归档后的 specs/ai-handler/spec.md 中，### 需求：图片压缩优化 新增关键约束：
- **必须处理并发送所有图片，不可限制或减少图片数量**
这一条款源于提案阶段客户反馈，体现 OpenSpec 对需求变更的敏捷响应能力——规范不是静态文档，而是持续演进的活契约。
何时使用？清晰的决策边界
OpenSpec 并非万能锤，其适用场景有明确边界：
✅ 应当使用（需创建变更提案）：
- 添加新功能或特性
- 进行重大变更（API、架构、数据模型）
- 更改架构或设计模式
- 优化性能（且改变用户可见行为）
- 更新安全策略或权限模型
❌ 不应使用（直接编码即可）：
- 错误修复（恢复预期行为）
- 拼写错误、格式化、注释补充
- 非破坏性依赖项更新（如 minor 版本升级）
- 纯配置变更（如调整日志级别）
- 现有行为的测试补全
该边界由 openspec/AGENTS.md 中的“决策树”明确定义，并在 openspec-proposal.md 工作流中强制执行，避免过度工程化。
与云栈社区的技术共鸣
OpenSpec 所倡导的“规范先行、契约协作、轻量演进”理念，与云栈社区长期深耕的后端 & 架构实践高度契合。它不追求颠覆式重构，而是在分布式系统设计、高并发场景应对、RPC 协议治理等成熟方法论基础上，为 AI 时代注入结构化、可验证、可追溯的新范式。对于正面临 AI 工程化落地挑战的团队，OpenSpec 提供了一条兼顾敏捷性与可靠性的务实路径。
参考资料
[1] OpenSpec：面向 AI 编程的规范驱动开发框架, 微信公众号：mp.weixin.qq.com/s/JHZEv8aXpBs_kUE9v2KeHQ
版权声明：本文由 云栈社区 整理发布，版权归原作者所有。
发表于 2026-2-10 18:20:22
|
查看: 28|
回复: 0
