天才娜娜ln1. OpenSpec 项目概述
OpenSpec 是一套用于规范 AI 开发助手行为的工具集，它通过定义标准化的项目结构和规范文件，让 AI 助手能够更好地理解项目上下文并按照既定流程工作。这套工具特别适合在 .NET 项目中使用，但它的理念和方法同样适用于其他技术栈。
提示：OpenSpec 的核心价值在于将人类开发者的项目经验"编码"成机器可读的规范，使 AI 助手能够像资深团队成员一样理解项目需求。
1.1 核心设计理念
OpenSpec 的设计基于三个关键原则：
- 规范即代码：将开发规范、业务流程等知识以 Markdown 文件的形式结构化存储
- 上下文感知：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 CLI
通过 npm 全局安装 OpenSpec 命令行工具：
bash复制npm install -g @fission-ai/openspec@latest
安装完成后，可以通过以下命令验证安装是否成功：
bash复制openspec --version
2.3 项目初始化
进入你的项目目录并执行初始化命令：
bash复制cd /path/to/your-project
openspec init
初始化过程会：
- 询问你使用的主要 AI 工具
- 根据选择创建相应的目录结构
- 生成基础规范文件模板
注意：初始化时选择的 AI 工具会影响生成的目录结构，但后续可以手动调整以适应其他工具。
3. OpenSpec 工作机制详解
3.1 规范注入系统
OpenSpec 的核心机制是通过一套"规范注入"系统，让 AI 在每次对话前先"学习"项目规范。这类似于人类开发者入职时阅读的项目文档，但以机器可读的方式实现。
系统工作流程如下：
- AI 启动时加载基础规范（如编码风格）
- 检测用户请求中的关键词（如"提案"、"变更"）
- 根据关键词加载对应的详细规范文件
- 按照规范执行任务
3.2 不同 AI 工具的适配实现
3.2.1 Claude Code 的实现
对于 Claude Code，OpenSpec 会生成以下目录结构：
code复制.claude/
├── commands/
│ └── openspec/
│ ├── apply.md
│ ├── archive.md
│ └── proposal.md
├── AGENTS.md
└── CLAUDE.md
关键文件说明：
-
commands/openspec目录定义了三个核心命令：proposal.md：变更提案规范apply.md：变更实施规范archive.md：变更归档规范
-
AGENTS.md是 Claude Code 的"第一课"文件，包含：- OpenSpec 使用说明
- 触发条件定义
- 基础项目规范
3.2.2 Trae 的实现
对于 Trae（字节跳动的 AI 开发工具），目录结构略有不同：
code复制项目根目录/
├── AGENT.md # 项目级规范
└── openspec/
├── AGENTS.md # OpenSpec 详细规范
├── project.md # 项目知识库
├── specs/ # 已实现能力规范
└── changes/ # 变更提案
关键差异：
- 老版本 Trae 需要手动将
AGENT.md内容复制到工具的项目规则中 - 2026年1月后的 Trae 版本已支持自动读取
AGENT.md
配置步骤：
- 打开 Trae 的项目设置
- 找到"项目规则"配置项
- 粘贴
AGENT.md内容 - 保存配置
3.3 核心工作流
无论使用哪种工具，OpenSpec 都遵循相同的三阶段工作流：
- 创建变更 (Proposal)：通过
/openspec:proposal命令发起 - 实现变更 (Apply)：通过
/openspec:apply命令执行 - 归档变更 (Archive)：通过
/openspec:archive命令完成
变更提案的必要性判断：
| 场景 | 是否需要提案 |
|---|---|
| 新增功能或能力 | 必须 |
| 破坏性变更（API/Schema） | 必须 |
| 架构或模式调整 | 必须 |
| Bug 修复（恢复既有行为） | 跳过 |
| 拼写、格式、注释修正 | 跳过 |
| 非破坏性依赖升级 | 跳过 |
4. 关键文件详解
4.1 AGENTS.md 文件
这是 OpenSpec 的核心规范文件，通常包含以下内容：
markdown复制# OpenSpec 说明
## 基本规则
- 代码风格要求
- 项目结构约定
- 命名规范
## 触发条件
当请求中包含以下内容时，加载详细规范：
- 提案、规范、变更、计划等关键词
- 新功能、重大变更、架构调整等描述
- 含糊不清且需要权威规范的请求
## 变更管理流程
1. 创建提案：/openspec:proposal
2. 实施变更：/openspec:apply
3. 归档变更：/openspec:archive
4.2 project.md 文件
项目知识库文件，通常包含：
markdown复制# 项目知识库
## 业务背景
- 项目目标
- 核心业务逻辑
- 关键术语解释
## 技术栈
- 主要框架和库
- 架构设计
- 重要配置说明
## 文档索引
- API 文档链接
- 设计文档位置
- 测试用例说明
4.3 命令文件（proposal/apply/archive）
这些文件定义了具体操作的规范，以 proposal.md 为例：
markdown复制# 变更提案规范
## 提案格式要求
1. 标题：简明描述变更
2. 背景：为什么要做这个变更
3. 方案：具体实现方法
4. 影响：对现有系统的影响
5. 测试：需要的测试方案
## 评审标准
- 是否符合项目架构
- 是否考虑向后兼容
- 性能影响评估
- 安全性考虑
5. 实战技巧与问题排查
5.1 提高规范触发率的技巧
如果发现 AI 没有正确加载规范，可以尝试：
-
明确使用触发词：
- ❌ "帮我加个新功能"
- ✅ "帮我创建一个新功能变更提案"
-
直接引用规范文件：
text复制
请先阅读 openspec/project.md，然后帮我设计一个用户管理模块 -
使用完整命令：
text复制
/openspec:proposal 添加用户登录日志功能
5.2 知识分层管理策略
合理组织规范内容可以显著提高 AI 助手的效率：
| 知识类型 | 存放位置 | 加载时机 |
|---|---|---|
| 通用规范 | /AGENTS.md | 每次对话 |
| 工作流 | openspec/AGENTS.md | 触发关键词时 |
| 业务知识 | openspec/project.md | 通过规范间接加载 |
5.3 常见问题解决方案
问题1：AI 忽略了规范中的某些要求
解决方案：
- 检查规范文件是否有明确的格式要求
- 在 AGENTS.md 中添加更具体的触发条件
- 在对话中明确要求 AI 确认是否遵守了某条规范
问题2：不同 AI 工具行为不一致
解决方案：
- 检查各工具的规范文件是否同步更新
- 在 project.md 中明确工具差异说明
- 考虑使用 OpenSpec 的兼容层功能
6. 高级定制与优化
6.1 自定义规范模板
OpenSpec 允许深度定制规范模板：
-
复制默认模板：
bash复制
openspec template copy --name my-template -
编辑模板文件：
bash复制
code .openspec/templates/my-template -
使用自定义模板初始化：
bash复制
openspec init --template my-template
6.2 多工具协同配置
对于同时使用多个 AI 工具的团队：
-
创建共享规范核心：
bash复制
openspec init --core-only -
为每个工具生成适配层：
bash复制
openspec adapt --tool claude openspec adapt --tool trae -
定期同步更新：
bash复制openspec sync
6.3 规范版本管理
将 OpenSpec 规范纳入项目版本控制：
-
创建规范变更提案：
bash复制openspec proposal --type spec -
实施规范变更：
bash复制
openspec apply --spec <spec-id> -
查看规范历史：
bash复制openspec log
在实际项目中使用 OpenSpec 时，我发现定期（如每周）审查规范文件的适用性非常重要。随着项目发展，一些早期制定的规范可能不再适用，及时调整这些规范可以保持 AI 助手的建议始终与项目现状保持一致。