1. OpenSpec 项目概述
OpenSpec 是一套面向 AI 辅助开发的规范管理系统,它通过定义标准化的项目结构和规范文件,让 AI 助手能够更好地理解项目上下文并执行开发任务。这套系统特别适合在 .NET 项目中使用,能够显著提升开发效率和代码质量。
核心设计理念是"规范即代码" - 将项目规范、业务知识和开发流程以结构化的 Markdown 文件形式保存,使 AI 能够像阅读代码一样理解项目要求。这种设计让 AI 不再是简单的代码补全工具,而是真正成为理解项目背景的开发伙伴。
提示:OpenSpec 不是特定 AI 工具的插件,而是一套通用规范体系,可以适配多种主流 AI 开发助手。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 安装与初始化配置
2.1 环境准备
在开始使用 OpenSpec 前,需要确保系统满足以下条件:
- Node.js 16.x 或更高版本
- npm 8.x 或更高版本
- 已安装目标 AI 开发工具(如 Claude Code、Cursor 等)
2.2 全局安装 OpenSpec
通过 npm 全局安装 OpenSpec CLI 工具:
bash复制npm install -g @fission-ai/openspec@latest
安装完成后,可以通过以下命令验证安装是否成功:
bash复制openspec --version
2.3 项目初始化
进入你的 .NET 项目目录,执行初始化命令:
bash复制cd /path/to/your-project
openspec init
初始化过程会引导你完成以下配置:
- 选择主要使用的 AI 工具(Claude Code、Cursor、Trae、Qoder 等)
- 设置项目基本信息(名称、描述等)
- 选择适合 .NET 项目的默认规范模板
初始化完成后,项目目录中会生成 OpenSpec 的标准文件结构。根据选择的 AI 工具不同,生成的文件结构会有所差异。
3. OpenSpec 核心机制解析
3.1 规范注入系统
OpenSpec 的核心创新在于其"规范注入"机制。这套系统确保 AI 在每次对话前都能"学习"项目规范,而不是仅依赖通用知识。其工作原理如下:
- 规范检测:AI 工具启动时自动加载基础规范(如 AGENTS.md)
- 请求分析:分析开发者输入的请求,判断是否需要加载更详细的规范
- 规范注入:根据请求类型动态加载对应的规范文件
- 任务执行:AI 在规范约束下执行开发任务
3.2 多工具适配设计
OpenSpec 针对不同 AI 工具采用了差异化适配策略:
3.2.1 Claude Code 适配方案
Claude Code 的目录结构最为完善:
code复制.claude/
├── commands/
│ └── openspec/
│ ├── apply.md
│ ├── archive.md
│ └── proposal.md
├── AGENTS.md
└── CLAUDE.md
关键文件说明:
commands/openspec/:存放可执行的 OpenSpec 命令AGENTS.md:基础规范,每次对话自动加载CLAUDE.md:Claude 专用配置
3.2.2 Trae 适配方案
对于 Trae 用户,OpenSpec 会生成以下结构:
code复制项目根目录/
├── AGENT.md
└── openspec/
├── AGENTS.md
├── project.md
├── specs/
└── changes/
Trae 用户需要注意:
- 2026年1月前版本需要手动配置项目规则
- 新版本已支持自动加载 AGENT.md
3.3 三阶段工作流
OpenSpec 定义了标准化的变更管理流程:
-
提案阶段 (Proposal):
- 创建变更提案
- 描述变更内容和影响
- 获取团队批准
-
实施阶段 (Apply):
- 根据批准的提案实现变更
- 确保符合规范要求
- 进行必要的测试
-
归档阶段 (Archive):
- 记录变更结果
- 更新项目文档
- 标记提案为完成
4. 核心文件详解
4.1 AGENTS.md 文件
这是 OpenSpec 系统中最重要的文件,相当于项目的"宪法"。它定义了:
- 项目基本规则和要求
- OpenSpec 工作流程说明
- 变更管理规范
- 编码标准和最佳实践
文件内容示例:
markdown复制# OpenSpec 说明
## 基本规则
1. 所有重大变更必须通过提案流程
2. 遵循 Clean Architecture 原则
3. 使用 C# 10 特性
## 工作流程
1. 创建提案: /openspec:proposal
2. 实施变更: /openspec:apply
3. 归档变更: /openspec:archive
## .NET 特定规范
- 使用 MediatR 实现 CQRS
- 领域模型放在 Core 项目
- 基础设施依赖放在 Infrastructure
4.2 proposal.md 文件
定义如何创建有效的变更提案:
markdown复制# 变更提案规范
## 必需字段
1. 变更描述
2. 影响分析
3. 相关模块
4. 预估工作量
## .NET 特定要求
- 必须说明对现有架构的影响
- 需要评估性能影响
- 必须包含单元测试计划
4.3 project.md 文件
项目的知识库,包含:
- 业务领域知识
- 核心概念解释
- 技术栈说明
- 架构决策记录
5. 实际应用场景
5.1 场景:添加新功能
-
发起提案:
code复制
/openspec:proposal 我想添加用户积分系统 -
AI 会根据 proposal.md 提示输入必要信息:
- 功能描述
- 数据库变更
- API 设计
- 测试策略
-
提案批准后实施:
code复制
/openspec:apply 积分系统提案 -
完成后归档:
code复制
/openspec:archive 积分系统
5.2 场景:架构调整
对于 .NET 项目常见的架构变更:
-
明确变更范围:
code复制
我需要将单体应用拆分为微服务,请创建提案 -
AI 会要求提供:
- 服务划分方案
- 通信机制选择
- 数据一致性方案
- 部署策略
-
实施阶段 AI 会:
- 生成新的解决方案文件
- 配置 Docker 支持
- 设置 API 网关
6. 高级配置与定制
6.1 自定义规范
OpenSpec 允许深度定制规范:
- 编辑对应的 .md 文件
- 添加项目特定规则
- 保存后运行:
bash复制
openspec validate
6.2 .NET 特定优化
针对 .NET 项目可以优化:
- 添加 Roslyn 分析器规则
- 配置代码样式规范
- 定义架构测试规则
示例配置:
markdown复制# .NET 代码规范
## 命名约定
- 接口以 I 开头
- 异步方法以 Async 结尾
- 使用 PascalCase
## 架构规则
- 领域层不能引用应用层
- 控制器应该精简
- 使用 MediatR 处理业务逻辑
7. 常见问题解决
7.1 规范未触发问题
现象:AI 没有按照预期加载规范
解决方案:
- 检查请求是否包含触发词(提案、变更等)
- 确认 AGENTS.md 文件位置正确
- 对于 Trae,检查是否手动配置了项目规则
7.2 业务知识未加载
现象:AI 不了解项目特定业务
解决方案:
- 确保业务知识已写入 project.md
- 在对话中明确引用:
code复制
请先阅读 openspec/project.md 中关于订单系统的说明 - 在 AGENTS.md 中添加业务知识索引
7.3 规范冲突问题
现象:不同规范文件要求不一致
解决方案:
- 运行规范校验:
bash复制
openspec validate - 统一相关规范
- 明确规范优先级(通常 AGENTS.md 优先级最高)
8. 最佳实践建议
- 渐进式采用:从小的规范集开始,逐步扩展
- 团队协作:定期评审和更新规范
- 版本控制:将 OpenSpec 文件纳入代码仓库
- 文档优先:先定义规范,再开始编码
- 持续优化:根据项目演进调整规范
对于 .NET 项目特别建议:
- 将 OpenSpec 与 SonarQube 等工具集成
- 定义清晰的架构分层规则
- 建立标准的 DI 配置规范
- 统一异常处理机制
9. 效能评估与优化
9.1 效能指标
衡量 OpenSpec 效果的几个关键指标:
- 提案通过率:首次提案通过的比例
- 返工率:因规范不符导致的修改次数
- 知识检索效率:AI 正确理解业务需求的比率
9.2 优化方向
-
规范精细化:
- 添加更多 .NET 特定规则
- 细化业务场景描述
-
知识结构化:
- 使用标准化的知识模板
- 建立概念之间的关联
-
流程自动化:
- 集成 CI/CD 流水线
- 自动规范校验
10. 未来演进方向
OpenSpec 正在向以下方向发展:
-
智能规范推荐:
- 根据项目阶段推荐相关规范
- 自动检测规范缺失
-
多模态支持:
- 支持图表形式的规范
- 架构图与规范的关联
-
生态集成:
- 与 Visual Studio 深度集成
- 支持更多 .NET 工具链
-
学习型规范:
- 根据团队实践自动优化规范
- 识别并推广最佳实践
对于 .NET 开发者来说,OpenSpec 代表了一种全新的开发范式 - 通过明确定义的规范,让 AI 成为真正理解项目、遵循架构原则的开发伙伴,而不仅仅是代码补全工具。
