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 ）

何时必须创建提案？

常用命令：

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 中
• 将业务知识索引也写在 /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 编程的"规范驱动"核心