OpenSpec 功能详解：5 分钟搞懂 AI 编程的规范驱动核心

为什么有时候让 AI 发起提案"时灵时不灵"？

前两天有朋友看了我写的《如何用 AI + OpenSpec 驱动团队迭代开发》后，问我一个很有趣的问题：

"为什么有时候我让 AI 发起 OpenSpec 提案，时灵时不灵？"

其实这个问题很简单，答案就藏在 OpenSpec 的工作原理中。

今天这篇文章，5 分钟的时间帮你快速了解 OpenSpec 的核心原理——它究竟是如何让 AI"听话"地按照规范来工作的。

2 快速认识 OpenSpec

OpenSpec 是一个规范驱动开发工具，核心理念极其简单：

“让 AI 明确知道"知识在哪、如何用、为什么这样做”

官网：https://openspec.dev/

2.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:START -->
# OpenSpec 说明
这些指令是针对参与本项目的人工智能助手。
当请求中包含以下内容时，请务必打开 `@/openspec/AGENTS.md`：
- 提及规划或提案（如提案、规范、变更、计划等字眼）
- 引入新功能、重大变更、架构调整或重大的性能/安全工作
- 听起来含糊不清，且在编码前需要权威规范
使用 `@/openspec/AGENTS.md` 来学习：
- 如何创建和应用变更提案
- 规范格式和约定
- 项目结构和指南
保留此托管块，以便"openspec update"可以刷新指令。
<!-- OPENSPEC:END -->

工作原理：

1. Claude Code 启动时自动读取 AGENTS.md
2. 判断用户请求是否触"提案/变更"等关键词
3. 如果触发，自动加载 openspec/AGENTS.md 中的详细规范
4. 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 的朋友需要基于下述步骤进行配置：

1. 打开 Trae 的项目设置
2. 找到"项目规则"配置
3. 将 AGENT.md 的内容粘贴进去
4. 保存后，Trae 每次对话都会加载该规则

配置完成后，Trae 的工作流程与 Claude Code 类似：

1. 每次对话自动加载项目规则
2. 判断是否触发 OpenSpec 规范
3. 根据规范执行对应任务

3 OpenSpec 规范核心要点

无论使用哪种 AI 工具，OpenSpec 的核心工作流都是一致的。理解这套规范，你就能更好地与 AI 协作。

三阶段工作流：

阶段1：创建变更（Proposal）↓
阶段2：实现变更（Apply）↓
阶段3：归档变更（Archive）

何时必须创建提案？

场景	是否需要提案
新增功能或能力	✅ 必须
破坏性变更（API/Schema）	✅ 必须
架构或模式调整	✅ 必须
Bug 修复（恢复既有行为）	❌ 跳过
拼写、格式、注释修正	❌ 跳过
非破坏性依赖升级	❌ 跳过

常用命令：

openspec list              # 列出所有变更
openspec list --specs      # 列出所有规范
openspec validate <id>     # 校验变更
openspec archive <id>      # 归档变更

💡 小贴士：作为人类开发者，你无需记忆这些命令。AI 会自动执行相应的操作来检查和管理变更提案。你只需要理解这套规范的工作流程，就能与 AI 配合无间。

openspec/project.md 的作用

这个文件是项目的"知识库"，用于存放：

• 项目目标和背景
• 核心业务术语
• 技术栈说明
• 详细文档索引

4 常见问题解答

4.1 Q1：为什么有时候 AI 不触发 OpenSpec 规范？

A：这通常是因为触发条件未被满足。

OpenSpec 的触发机制基于关键词匹配（如"提案"、"变更"、"规范"等）。如果你的请求不包含这些关键词，AI 则不会加载 OpenSpec 规范。

解决方案：

1. 明确使用触发词："帮我创建一个变更提案"
2. 直接指定文件："先阅读 openspec/project.md 再回答"
3. 使用斜杠命令：/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 的进化方向。

目前最佳实践是：

1. 在 /AGENTS.md 中建立业务知识索引
2. 采用提案方式讨论业务逻辑（自动触发规范）
3. 对话中明确指定："先阅读 docs/xxx.md 再回答"

6 五、总结：OpenSpec 的核心价值

回到开篇的问题：为什么有时候让 AI 发起提案"时灵时不灵"？

答案现在很清楚了：

1. 触发机制：AI 需要识别到特定关键词才会加载 OpenSpec 规范
2. 工具差异：不同 AI 工具对规范文件的支持程度不同
3. 知识分层：业务知识与开发规范需要合理分层存放

OpenSpec 的核心价值在于：通过"规范注入"让 AI 从"项目小白"成长为"熟悉业务的开发伙伴"。

它不是银弹，但当你理解了它的工作原理后，就能让 AI 在团队协作中发挥真正的作用。

当然，在有需要的时候，我们也可以修改 OpenSpec 初始化时所生成的一系列.md文件，直接变更规范，使其更加符合企业内的业务流程。

欢迎日常交流

AI 驱动团队开发是这个时代的新命题，欢迎大家加微信互相交流心得。

👉 想要进群的朋友，扫码时备注 “AI实验群”，看到消息后会第一时间拉你进群。

群定位：AI工具提效/实战经验互助

群规则：不水群、不广告、干货优先

欢迎访问该链接获取群信息：https://zhaozhihao.com/archives/KRMxDLo4

好文章值得被更多人看见！既然看到这里了，随手点个赞👍和关注，并转发给更多的朋友吧！感谢。

作者：数字生命贾克斯、微信：x_h886688

公众号原文地址：OpenSpec 功能详解：5 分钟搞懂 AI 编程的"规范驱动"核心