为什么需要 OpenSpec？
传统 AI 编程助手的痛点
- AI 根据模糊提示生成不符合需求的代码。
- 遗漏重要功能要求或误加入不必要的功能。
- 代码行为不可预测，修改过程混乱。
OpenSpec 的解决方案
- 明确共识：编码前确认所有需求。
- 结构化变更：文档集中管理，清晰可追踪。
- 可审查输出：AI 生成代码可预测且易审查。
- 版本控制：完整追踪变更历史。
核心特点
轻量级
无需 API 密钥，最小化设置，快速上手。
现有项目优先
特别适合修改现有功能（1→n 开发），增量更新。
变更跟踪
完整生命周期管理，跟踪提案、任务和规范差异。
AI 工具集成
支持 Claude Code, Cursor, GitHub Copilot 等。
准备工作 & 快速开始
系统要求
Node.js >= 20.19.0
支持的 AI 编程助手（如 Claude Code、Cursor 等）
1. 安装 CLI
$ npm install -g @fission-ai/openspec@latest
2. 验证安装
$ openspec --version
3. 初始化项目
$ cd your-project-directory
$ openspec init
# 初始化过程会：
# - 询问使用的 AI 工具
# - 自动配置斜杠命令
# - 创建 openspec/ 目录
# - 生成 AGENTS.md
$ openspec init
# 初始化过程会：
# - 询问使用的 AI 工具
# - 自动配置斜杠命令
# - 创建 openspec/ 目录
# - 生成 AGENTS.md
4. 验证设置
$ openspec list
核心概念：双文件夹模型
OpenSpec 使用两个核心目录来管理规范的生命周期。
规范格式 (Markdown)
# Auth Specification ## Purpose Authentication and session management. ## Requirements ### Requirement: User Authentication The system SHALL issue a JWT on successful login. #### Scenario: Valid credentials - WHEN a user submits valid credentials - THEN a JWT is returned
变更差异 (Delta)
# Delta for Auth ## ADDED Requirements ### Requirement: 2FA The system MUST require a second factor. #### Scenario: OTP required - WHEN a user submits valid credentials - THEN an OTP challenge is required
完整工作流程
1. 起草变更提案
AI 自动创建目录和文件：proposal.md, tasks.md, specs/。
2. 审查与对齐
与 AI 助手讨论，确保所有人对规范达成一致。
3. 实施任务
AI 按照任务清单逐步实施，完成任务后标记。
4. 归档与更新
归档完成的变更，更新主规范并移入 archive/。
实际示例：添加用户资料搜索过滤
workflow-demo
# 1. 创建提案
$ /openspec:proposal Add profile search filters
# 2. 验证和审查
$ openspec validate add-profile-filters
$ openspec show add-profile-filters
# 3. 实施变更 (AI 自动执行)
$ /openspec:apply add-profile-filters
# 4. 归档
$ /openspec:archive add-profile-filters
$ /openspec:proposal Add profile search filters
# 2. 验证和审查
$ openspec validate add-profile-filters
$ openspec show add-profile-filters
# 3. 实施变更 (AI 自动执行)
$ /openspec:apply add-profile-filters
# 4. 归档
$ /openspec:archive add-profile-filters
常见问题
AI 助手没有显示新的斜杠命令怎么办？
重启 AI 编程助手并运行
openspec update。如果问题仍然存在，可以尝试重新初始化 OpenSpec 配置：openspec init --force。
可以同时处理多个变更吗？
是的，OpenSpec 支持多个变更提案并行处理，但每次只能应用一个。建议为不同的功能领域创建单独的变更提案，以保持代码库的清晰性。
如何修改已归档的规范？
创建新的变更提案，通过相同流程更新现有规范。OpenSpec 会自动处理规范的版本管理，确保所有变更都有可追溯的历史记录。
OpenSpec 适用于绿地项目吗？
虽然特别适合修改现有功能，OpenSpec 也可以用于新项目，建议从简单功能开始。对于新项目，可以使用 OpenSpec 来建立完整的规范体系，为后续的开发和维护奠定基础。
OpenSpec 如何与版本控制系统集成？
OpenSpec 完全兼容 Git 等版本控制系统。规范文件存储在项目目录中，可以像代码一样提交和管理。建议为规范变更创建单独的提交，以便于跟踪和审查。
如何处理复杂的规范变更？
对于复杂的变更，建议将其分解为多个小的、可管理的变更提案。这样可以更容易地审查和验证每个变更，减少引入错误的风险。
OpenSpec 支持哪些编程语言和框架？
OpenSpec 是语言无关的，理论上可以用于任何编程语言和框架。它通过通用的规范格式和变更管理流程，为不同技术栈提供统一的开发方法。
如何衡量 OpenSpec 对开发效率的影响？
可以通过以下指标来衡量：
- 需求变更频率的减少
- 缺陷率的降低
- 开发周期时间的缩短
- 团队协作效率的提高
- 代码质量和可维护性的改善
许多采用 OpenSpec 的团队报告说，这些指标都有显著的改善。