1. OpenSpec 项目概述
OpenSpec 是一套面向 AI 辅助开发的规范管理系统,它通过定义标准化的项目结构和规范文件,让 AI 工具能够更好地理解项目上下文和开发流程。这套系统特别适合在团队协作环境中使用,能够显著提升 AI 辅助开发的效率和一致性。
在传统的 AI 辅助开发中,开发者经常面临一个痛点:每次与 AI 交互时,都需要反复解释项目背景、编码规范和业务流程。OpenSpec 通过将所有这些信息结构化地存储在项目中,让 AI 能够"学习"这些规范,从而提供更符合项目需求的建议。
提示:OpenSpec 不是特定 AI 工具的插件,而是一套通用的规范体系,可以适配多种主流 AI 开发工具。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 安装与初始化
2.1 环境准备
在开始使用 OpenSpec 前,需要确保你的开发环境满足以下要求:
- Node.js 16.x 或更高版本
- npm 8.x 或更高版本
- 任意一个支持的 AI 开发工具(Claude Code、Cursor、Trae 等)
2.2 安装 OpenSpec CLI
OpenSpec 提供了一个命令行工具来管理项目规范。全局安装命令如下:
bash复制npm install -g @fission-ai/openspec@latest
安装完成后,可以通过以下命令验证安装是否成功:
bash复制openspec --version
2.3 项目初始化
在项目根目录下执行初始化命令:
bash复制cd /path/to/your-project
openspec init
初始化过程会引导你完成以下配置:
- 选择使用的 AI 工具(Claude Code、Cursor、Trae、Qoder 等)
- 设置项目基本信息(名称、描述等)
- 配置默认规范模板
初始化完成后,OpenSpec 会根据你选择的 AI 工具生成相应的目录结构和规范文件。
3. OpenSpec 核心机制
3.1 规范注入系统
OpenSpec 的核心创新在于它的"规范注入"机制。这套系统让 AI 在每次对话前先"学习"项目规范,而不是依赖开发者在每次交互时手动提供上下文。
工作原理如下:
- AI 工具启动时自动加载基础规范(AGENTS.md)
- 根据用户请求中的关键词判断是否需要加载更详细的规范
- 如果触发条件满足,加载对应的规范文件(如 proposal.md)
- AI 基于这些规范执行任务
3.2 不同 AI 工具的适配策略
OpenSpec 针对不同的 AI 工具采用了不同的适配策略:
3.2.1 Claude Code 适配
对于 Claude Code,OpenSpec 会生成以下目录结构:
code复制.claude/
├── commands/
│ └── openspec/
│ ├── apply.md
│ ├── archive.md
│ └── proposal.md
├── AGENTS.md
└── CLAUDE.md
关键特点:
- 自动加载机制:Claude Code 会自动读取 .claude/AGENTS.md
- 命令集成:通过 /openspec:proposal 等命令直接触发规范
3.2.2 Trae 适配
对于 Trae,目录结构略有不同:
code复制项目根目录/
├── AGENT.md
└── openspec/
├── AGENTS.md
├── project.md
├── specs/
└── changes/
关键差异:
- 老版本 Trae 需要手动配置项目规则
- 2026年1月后的版本支持自动加载 AGENT.md
3.3 核心文件解析
3.3.1 AGENTS.md
这是 OpenSpec 的核心规范文件,定义了以下内容:
- 项目基本规则和约定
- OpenSpec 工作流说明
- 业务知识索引
- 触发条件定义
示例内容:
markdown复制# OpenSpec 说明
这些指令是针对参与本项目的人工智能助手。
当请求中包含以下内容时,请务必打开 `@/openspec/AGENTS.md`:
- 提及规划或提案(如提案、规范、变更、计划等字眼)
- 引入新功能、重大变更、架构调整或重大的性能/安全工作
- 听起来含糊不清,且在编码前需要权威规范
3.3.2 命令文件(proposal.md, apply.md, archive.md)
这些文件定义了具体操作的规范。以 proposal.md 为例:
markdown复制# 变更提案规范
所有新变更提案必须包含以下部分:
1. 变更描述:清晰说明变更内容和目的
2. 影响分析:列出受影响的模块和功能
3. 实施方案:详细的技术实现方案
4. 测试计划:如何验证变更的正确性
5. 回滚方案:出现问题时如何恢复
提案格式要求:
- 使用 Markdown 语法
- 每个部分至少包含3个要点
- 必须引用相关的业务需求或问题单号
4. 工作流程详解
4.1 三阶段工作流
OpenSpec 定义了标准的三阶段工作流:
- 创建变更(Proposal):通过 /openspec:proposal 命令发起
- 实现变更(Apply):通过 /openspec:apply 命令执行
- 归档变更(Archive):通过 /openspec:archive 命令完成
4.2 何时需要创建提案
OpenSpec 提供了明确的决策矩阵:
| 场景 | 是否需要提案 |
|---|---|
| 新增功能或能力 | 必须 |
| 破坏性变更(API/Schema) | 必须 |
| 架构或模式调整 | 必须 |
| Bug 修复(恢复既有行为) | 跳过 |
| 拼写、格式、注释修正 | 跳过 |
| 非破坏性依赖升级 | 跳过 |
4.3 常用命令参考
OpenSpec 提供了一系列管理命令:
bash复制openspec list # 列出所有变更
openspec list --specs # 列出所有规范
openspec validate # 校验变更
openspec archive # 归档变更
注意:开发者不需要记忆这些命令,AI 会自动在适当时机调用它们。
5. 高级配置与定制
5.1 自定义规范模板
OpenSpec 允许你完全自定义规范模板。修改步骤如下:
- 在项目根目录创建 .openspec/templates 目录
- 添加自定义模板文件(如 proposal_custom.md)
- 更新 openspec.config.json 中的模板配置
5.2 多工具并行支持
对于同时使用多个 AI 工具的团队,可以配置 OpenSpec 生成多套规范:
bash复制openspec init --multi-tool
这会为每个支持的 AI 工具生成对应的规范目录,同时维护一个共享的规范库。
5.3 规范版本控制
OpenSpec 支持规范的版本管理和迁移:
bash复制openspec migrate --from-version=1.0 --to-version=2.0
这个命令会自动将旧版规范转换为新版格式。
6. 最佳实践与经验分享
6.1 规范编写技巧
-
分层组织内容:
- 基础规范放在顶层 AGENTS.md
- 详细工作流放在 openspec/AGENTS.md
- 业务知识放在 openspec/project.md
-
明确触发条件:
- 使用清晰的关键词定义
- 为常见场景创建别名
-
保持规范简洁:
- 每个规范文件不超过300行
- 使用清晰的标题和段落
6.2 常见问题排查
6.2.1 AI 不触发规范
可能原因:
- 请求中缺少触发关键词
- 规范文件路径不正确
- AI 工具版本不兼容
解决方案:
- 检查 AGENTS.md 中的触发条件定义
- 确认规范文件位于正确位置
- 更新 AI 工具到最新版本
6.2.2 规范加载不全
可能原因:
- 文件权限问题
- 路径引用错误
- 文件编码问题
解决方案:
- 检查文件权限(确保可读)
- 使用绝对路径引用
- 确保文件使用 UTF-8 编码
6.3 性能优化建议
-
规范文件缓存:
- 对于大型项目,启用规范缓存
- 在 openspec.config.json 中设置 "cache": true
-
按需加载:
- 将不常用的规范移到子目录
- 使用动态导入语法
-
定期清理:
- 归档不再使用的规范
- 使用 openspec purge 命令清理历史版本
7. 实际应用案例
7.1 新功能开发流程
- 开发者输入:"/openspec:proposal 添加用户积分系统"
- AI 加载 proposal.md 规范
- AI 引导开发者完成提案内容
- 提案审核通过后,使用 "/openspec:apply" 实现变更
- 变更测试完成后,使用 "/openspec:archive" 归档
7.2 紧急修复流程
- 确认问题属于"Bug 修复"类别
- 直接描述问题:"修复用户登录超时问题"
- AI 识别不需要提案,直接提供修复方案
- 验证修复后提交变更
7.3 架构调整流程
- 发起提案:"/openspec:proposal 微服务化改造"
- AI 根据规范要求提供架构设计模板
- 团队评审提案
- 分阶段执行变更
- 每个阶段完成后归档对应变更
8. 工具集成与扩展
8.1 与CI/CD集成
OpenSpec 可以无缝集成到持续集成流程中:
yaml复制# .github/workflows/validate.yml
name: Validate OpenSpec
on: [push, pull_request]
jobs:
validate:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- run: npm install -g @fission-ai/openspec
- run: openspec validate
8.2 编辑器插件支持
主流编辑器可以通过插件增强 OpenSpec 支持:
- VS Code:OpenSpec Helper 插件
- IntelliJ:OpenSpec Integration 插件
- Vim:openspec.vim 插件
8.3 自定义报告生成
OpenSpec 支持生成多种格式的报告:
bash复制openspec report --format=html # HTML报告
openspec report --format=json # JSON格式
openspec report --format=md # Markdown格式
9. 未来发展方向
OpenSpec 团队正在开发以下新特性:
- 智能规范推荐:基于项目历史自动推荐相关规范
- 跨项目规范共享:创建可复用的规范模板库
- 规范影响分析:预测规范变更的影响范围
- AI训练集成:直接使用规范训练专属AI模型
10. 使用心得与建议
在实际项目中使用 OpenSpec 几个月后,我总结了以下几点经验:
- 从小开始:不要试图一次性定义所有规范,先从核心工作流开始
- 团队协作:让所有团队成员参与规范制定,确保实用性
- 持续优化:定期回顾规范效果,删除无效内容
- 平衡灵活:在规范性和灵活性之间找到平衡点
对于刚开始使用的团队,我建议按照以下步骤实施:
- 选择1-2个核心工作流(如Bug修复)
- 定义基础规范
- 在小范围试用并收集反馈
- 逐步扩展到其他工作流
- 定期优化规范内容
OpenSpec 最强大的地方在于它让团队能够系统地管理AI的"知识",而不是依赖开发者的临时解释。经过适当配置后,AI助手能够真正成为理解项目上下文的智能协作者,而不是需要不断指导的新手。
