1. OpenSpec 项目概述
OpenSpec 是一套面向 .NET 开发者的 AI 辅助开发规范系统,它通过标准化的文件结构和指令集,让 AI 助手能够更好地理解项目上下文和开发规范。这套系统最初由 Fission AI 团队开发,旨在解决 AI 辅助开发中的几个核心痛点:
- 上下文缺失:传统 AI 工具往往缺乏对特定项目架构和业务逻辑的理解
- 规范不一致:不同开发者使用 AI 时可能产生风格迥异的代码
- 协作困难:团队中多人使用不同 AI 工具时难以保持统一的工作流程
我在实际项目中采用 OpenSpec 后发现,它特别适合中大型 .NET 项目,尤其是那些需要长期维护、多人协作的企业级应用。通过规范化的 AI 交互方式,团队可以显著减少代码审查时的风格问题,同时提高 AI 生成代码的业务契合度。
提示:虽然 OpenSpec 最初是为 .NET 设计,但其理念同样适用于其他技术栈。关键在于规范文件的编写质量。
2. 安装与初始化详解
2.1 环境准备
在开始使用 OpenSpec 前,需要确保开发环境满足以下条件:
- Node.js 16+(用于运行 OpenSpec CLI)
- 任一款支持的 AI 开发助手(推荐 Claude Code 或最新版 Trae)
- .NET 6+ 开发环境
bash复制# 检查 Node.js 版本
node -v
# 检查 .NET SDK
dotnet --version
2.2 全局安装 OpenSpec
安装过程非常简单,通过 npm 即可完成:
bash复制npm install -g @fission-ai/openspec@latest
这里有几个值得注意的细节:
- 建议使用
@latest标签确保获取最新版本 - 如果遇到权限问题,可以加上
--unsafe-perm参数 - 安装完成后可以通过
openspec --version验证
2.3 项目初始化
进入你的 .NET 项目目录后执行:
bash复制openspec init
初始化过程会交互式地询问几个关键配置:
- 选择 AI 工具:Claude Code、Cursor、Trae 或其他
- 规范严格级别:宽松/中等/严格(影响默认生成的规则强度)
- 是否包含示例规范:建议初次使用时选择"是"
初始化完成后,你会看到项目目录中新增了几个关键文件和目录,具体结构取决于你选择的 AI 工具。
3. OpenSpec 核心机制解析
3.1 规范注入系统
OpenSpec 的核心创新在于它的"规范注入"机制。与传统 AI 提示工程不同,它不是通过单次对话传递规则,而是建立了一套持续生效的规范体系:
- 启动时加载:AI 工具启动时会自动读取根目录下的 AGENT.md
- 条件触发:当对话涉及特定关键词时加载更详细的规范文件
- 分层管理:将通用规范与业务知识分开维护
这种设计带来了几个显著优势:
- 上下文持久化:无需每次对话都重复说明规则
- 精准触发:只有在需要时才加载相关规范,避免信息过载
- 团队协作:规范文件可以纳入版本控制,全团队共享
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 能自动识别这种目录结构
- 命令集成:可以通过
/openspec:proposal等斜杠命令直接调用 - 自动加载:规范文件会在适当时机自动生效
3.2.2 Trae 方案
对于 Trae(特别是老版本),目录结构略有不同:
code复制项目根目录/
├── AGENT.md
└── openspec/
├── AGENTS.md
├── project.md
├── specs/
└── changes/
主要区别:
- 手动配置:老版本 Trae 需要手动将 AGENT.md 内容粘贴到项目设置中
- 文件位置:规范文件放在更显眼的 openspec 目录下
- 新版优化:2026年1月后的 Trae 版本已经支持自动加载
经验分享:即使使用新版 Trae,也建议定期检查规范是否被正确加载。我曾遇到过缓存导致规范未及时更新的情况。
4. 三阶段工作流实战
4.1 阶段1:创建变更提案
当需要进行以下类型的变更时,应当发起提案:
- 新增功能或能力
- 破坏性变更(如 API/Schema 修改)
- 架构或设计模式调整
提案创建方式:
bash复制# 通过 CLI
openspec proposal "重构用户服务层"
# 或通过 AI 命令
/openspec:proposal 重构用户服务层
提案文件通常包含这些部分:
- 变更目的:为什么要做这个变更
- 影响分析:可能影响哪些模块
- 实施方案:具体的技术路线
- 测试计划:如何验证变更效果
4.2 阶段2:实现变更
提案通过审查后,进入实现阶段:
bash复制openspec apply PROPOSAL_ID
实现阶段的关键注意事项:
- 严格遵循提案:任何偏离都需要重新审查
- 增量修改:保持每个变更小而集中
- 文档更新:同步修改相关文档和注释
4.3 阶段3:归档变更
变更完成并验证后:
bash复制openspec archive PROPOSAL_ID
归档操作会:
- 将变更记录移动到归档目录
- 生成变更摘要
- 更新项目知识库
5. 规范文件编写指南
5.1 AGENTS.md 最佳实践
这是最重要的规范文件,建议包含:
markdown复制# 项目开发规范
## 编码风格
- 使用 Allman 风格大括号
- 私有字段使用 _prefix 命名
- 异步方法以 Async 后缀结尾
## 架构约束
- 控制器不应包含业务逻辑
- 服务层必须实现接口
- 领域模型保持 POCO
## 业务术语
@see openspec/project.md#业务词汇表
5.2 project.md 结构建议
项目知识库建议采用分层结构:
markdown复制# 项目知识库
## 1. 业务背景
- 核心业务流程
- 关键业务规则
## 2. 技术栈
- 主要框架及版本
- 重要第三方库
## 3. 架构图
- 系统上下文图
- 核心组件交互
6. 常见问题排查
6.1 规范未触发问题
症状:AI 没有按预期应用规范
排查步骤:
- 检查 AGENT.md 是否在正确位置
- 验证文件内容格式是否正确
- 确认使用的关键词符合触发条件
- 检查 AI 工具版本是否兼容
6.2 知识库未生效问题
解决方案:
- 在 AGENT.md 中明确引用知识库文件
- 使用完整路径指令:"请先阅读 openspec/project.md#业务背景"
- 确保知识库文件不超过 AI 的上下文窗口限制
6.3 多工具协作问题
当团队使用不同 AI 工具时:
- 统一主要规范文件的内容
- 为每个工具创建适配层文件
- 定期同步各工具的规范更新
7. 高级定制技巧
7.1 自定义命令
可以在 commands 目录下添加自己的命令:
markdown复制<!-- .claude/commands/custom/review.md -->
# 代码审查规范
审查时应检查:
1. 是否符合架构约束
2. 是否有足够的单元测试
3. 文档是否同步更新
然后通过 /custom:review 调用。
7.2 规范版本控制
建议将规范文件纳入 git 管理,并:
- 为重大变更创建分支
- 使用 Pull Request 审查规范修改
- 维护规范的变更日志
7.3 性能优化
对于大型项目:
- 将规范拆分为多个小文件
- 使用索引文件快速定位
- 定期清理过时的规范
经过几个月的实践,我发现这套系统最能发挥价值的场景是在新成员 onboarding 和跨团队协作时。它显著减少了沟通成本,让 AI 真正成为了理解项目语境的智能助手,而不仅仅是代码补全工具。