这是一个创建于 95 天前的主题，其中的信息可能已经有所发展或是发生改变。
为什么有时候让 AI 发起提案"时灵时不灵"？
前两天有朋友看了我写的《如何用 AI + OpenSpec 驱动团队迭代开发》后，问我一个很有趣的问题：
"为什么有时候我让 AI 发起 OpenSpec 提案，时灵时不灵？"
其实这个问题很简单，答案就藏在 OpenSpec 的工作原理中。
今天这篇文章，5 分钟的时间帮你快速了解 OpenSpec 的核心原理它究竟是如何让 AI"听话"地按照规范来工作的。
2 快速认识 OpenSpec
OpenSpec 是一个规范驱动开发工具，核心理念极其简单：
“让 AI 明确知道"知识在哪、如何用、为什么这样做”
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 --> 工作原理：
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 <id> # 校验变更 openspec archive <id> # 归档变更 小贴士：作为人类开发者，你无需记忆这些命令。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 | 通过规范索引间接加载 |
实践建议：
5.3 Q3：如何让 AI 自动检索相关背景知识？
A：这是 OpenSpec 的进化方向。
目前最佳实践是：
6 五、总结：OpenSpec 的核心价值
回到开篇的问题：为什么有时候让 AI 发起提案"时灵时不灵"？
答案现在很清楚了：
- 触发机制：AI 需要识别到特定关键词才会加载 OpenSpec 规范
- 工具差异：不同 AI 工具对规范文件的支持程度不同
- 知识分层：业务知识与开发规范需要合理分层存放
OpenSpec 的核心价值在于：通过"规范注入"让 AI 从"项目小白"成长为"熟悉业务的开发伙伴"。
它不是银弹，但当你理解了它的工作原理后，就能让 AI 在团队协作中发挥真正的作用。
当然，在有需要的时候，我们也可以修改 OpenSpec 初始化时所生成的一系列.md 文件，直接变更规范，使其更加符合企业内的业务流程。
欢迎日常交流
AI 驱动团队开发是这个时代的新命题，欢迎大家加微信互相交流心得。
想要进群的朋友，扫码时备注 “AI 实验群”，看到消息后会第一时间拉你进群。
群定位：AI 工具提效/实战经验互助
群规则：不水群、不广告、干货优先
欢迎访问该链接获取群信息： https://zhaozhihao.com/archives/KRMxDLo4
好文章值得被更多人看见！既然看到这里了，随手点个赞和关注，并转发给更多的朋友吧！感谢。
作者：数字生命贾克斯、微信：x_h886688
目前尚无回复
Select Language