1 安装与初始化
# 全局安装 OpenSpec
npm install -g @fission-ai/openspec@latest
# 在项目目录下初始化
cd /path/to/your-project
openspec init
初始化时，OpenSpec 会提示你选择使用的 AI 工具（Claude Code、Cursor、Trae、Qoder 等）。
3 OpenSpec 如何"教"AI 工作？
OpenSpec 的核心机制，是通过一套规范注入系统，让 AI 在每次对话前先"学习"项目规范。
3.1 不同 AI 工具的初始化差异
根据你使用的 AI 工具不同，OpenSpec 会生成不同的目录结构。这背后的设计理念是：最大限度地适配各工具的特性。
3.2 ?? 场景 1：Claude Code
Claude Code 在执行了 OpenSpec Init 后的目录结构如下：
.claude/
├── commands/
│ └── openspec/
│ ├── apply.md
│ ├── archive.md
│ └── proposal.md
├── AGENTS.md
└── CLAUDE.md
commands/openspec 这个目录定义了三个不同的命令，每个命令文件中所写的提示词，都是 AI 在执行该命令时需要参考的"规范"。上述三个命令分别是：
apply.md：表示执行已批准的变更
archive.md：归档已完成的变更
proposal.md：发起新变更提案
当我们需要发起新的提案时，可以直接使用：/openspec:proposal 就可以触发该指令，此时 AI 就会根据 proposal.md 中所定义的规范，来创建一个新的变更提案。
核心文件解读：AGENTS.md
这个文件是 Claude Code 每次对话时的"第一课"，内容如下：
# OpenSpec 说明
这些指令是针对参与本项目的人工智能助手。
当请求中包含以下内容时，请务必打开 `@/openspec/AGENTS.md`：
- 提及规划或提案（如提案、规范、变更、计划等字眼）
- 引入新功能、重大变更、架构调整或重大的性能/安全工作
- 听起来含糊不清，且在编码前需要权威规范
使用 `@/openspec/AGENTS.md` 来学习：
- 如何创建和应用变更提案
- 规范格式和约定
- 项目结构和指南
保留此托管块，以便"openspec update"可以刷新指令。
工作原理：
Claude Code 启动时自动读取 AGENTS.md
判断用户请求是否触"提案/变更"等关键词
如果触发，自动加载 openspec/AGENTS.md 中的详细规范
AI 按照规范执行任务
3.3 ?? 场景 2：Trae（字节跳动）
OpenSpec 在初始化时可选择的AI 工具中是不支持 Trae 的，但是很多朋友是基于 Trae 在开发。
所以对于使用 Trae 的朋友，我们在执行 OpenSpec Init 的时候，可以选择最后一个选项 Other Tools (适用于 VsCode 等）
此时初始化后的目录结构如下：
项目根目录/
├── AGENT.md # 项目级规范（需手动配置）
└── openspec/
├── AGENTS.md # OpenSpec 详细规范
├── project.md # 项目知识库
├── specs/ # 已实现能力规范
└── changes/ # 变更提案
关键差异：需要手动配置
与 Claude Code 不同，老版本的 Trae 不会自动读取 AGENT.md。此时你需要手动将规范内容添加到 Trae 的"项目规则"中。
但是对于Trae 2026 年 1 月份最新的一次版本变更中，也已经兼容了读取 AGENT.md 文件作为项目规则来使用。
所以使用老版本 Trae 的朋友需要基于下述步骤进行配置：
打开 Trae 的项目设置
找到"项目规则"配置
将 AGENT.md 的内容粘贴进去
保存后，Trae 每次对话都会加载该规则
配置完成后，Trae 的工作流程与 Claude Code 类似：
每次对话自动加载项目规则
判断是否触发 OpenSpec 规范
根据规范执行对应任务
3 OpenSpec 规范核心要点
无论使用哪种 AI 工具，OpenSpec 的核心工作流都是一致的。理解这套规范，你就能更好地与 AI 协作。
三阶段工作流：
阶段1：创建变更（Proposal）
↓
阶段2：实现变更（Apply）
↓
阶段3：归档变更（Archive）
何时必须创建提案？
场景 是否需要提案
新增功能或能力 ? 必须
破坏性变更（API/Schema） ? 必须
架构或模式调整 ? 必须
Bug 修复（恢复既有行为） ? 跳过
拼写、格式、注释修正 ? 跳过
非破坏性依赖升级 ? 跳过
常用命令：
openspec list # 列出所有变更
openspec list --specs # 列出所有规范
openspec validate # 校验变更
openspec archive # 归档变更
?? 小贴士：作为人类开发者，你无需记忆这些命令。AI 会自动执行相应的操作来检查和管理变更提案。你只需要理解这套规范的工作流程，就能与 AI 配合无间。
openspec/project.md 的作用
这个文件是项目的"知识库"，用于存放：
项目目标和背景
核心业务术语
技术栈说明
详细文档索引
4 常见问题解答
4.1 Q1：为什么有时候 AI 不触发 OpenSpec 规范？
A：这通常是因为触发条件未被满足。
OpenSpec 的触发机制基于关键词匹配（如"提案"、"变更"、"规范"等）。如果你的请求不包含这些关键词，AI 则不会加载 OpenSpec 规范。
解决方案：
明确使用触发词："帮我创建一个变更提案"
直接指定文件："先阅读 openspec/project.md 再回答"
使用斜杠命令：/openspec:proposal（如果工具支持）
5.2 Q2：project.md 中的业务知识什么时候生效？
A：只有触发 OpenSpec 规范后才会读取。
这是一个重要的设计权衡：
知识类型 存放位置 触发条件
通用开发规范 /AGENTS.md 每次对话自动加载
OpenSpec 工作流 openspec/AGENTS.md 触发关键词后加载
业务上下文 openspec/project.md 通过规范索引间接加载
实践建议：
将通用规则（如项目结构、编码风格）放在 /AGENTS.md 中
将业务知识索引也写在 /AGENTS.md 中，便于日常对话触发
或者在对话中明确要求 AI 先阅读特定文档
5.3 Q3：如何让 AI 自动检索相关背景知识？
A：这是 OpenSpec 的进化方向。
目前最佳实践是：
在 /AGENTS.md 中建立业务知识索引
采用提案方式讨论业务逻辑（自动触发规范）
对话中明确指定："先阅读 docs/xxx.md 再回答"
6 五、总结：OpenSpec 的核心价值
回到开篇的问题：为什么有时候让 AI 发起提案"时灵时不灵"？
答案现在很清楚了：
触发机制：AI 需要识别到特定关键词才会加载 OpenSpec 规范
工具差异：不同 AI 工具对规范文件的支持程度不同
知识分层：业务知识与开发规范需要合理分层存放
OpenSpec 的核心价值在于：通过"规范注入"让 AI 从"项目小白"成长为"熟悉业务的开发伙伴"。
它不是银弹，但当你理解了它的工作原理后，就能让 AI 在团队协作中发挥真正的作用。
当然，在有需要的时候，我们也可以修改 OpenSpec 初始化时所生成的一系列.md文件，直接变更规范，使其更加符合企业内的业务流程。晌张煤甘
