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

OpenSpec 功能详解：5 分钟搞懂 AI 编程的"规范驱动"核心 OpenSpec 功能详解：5 分钟搞懂 AI 编程的"规范驱动"核心 Modified January 19 3.3 📍 场景 2：Trae（字节跳动） OpenSpec 在初始化时可选择的AI 工具中是不支持 Trae 的，但是很多朋友是基于 Trae 在开发。 所以对于使用 Trae 的朋友，我们在执行 OpenSpec Init 的时候，可以选择最后一个选项 Other Tools (适用于 VsCode 等） 此时初始化后的目录结构如下： Code block Plain Text Copy 项目根目录/ ├── 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. 根据规范执行对应任务 4 OpenSpec 规范核心要点 无论使用哪种 AI 工具，OpenSpec 的核心工作流都是一致的。理解这套规范，你就能更好地与 AI 协作。 三阶段工作流： Code block Plain Text Copy 阶段1：创建变更（Proposal） ↓ 阶段2：实现变更（Apply） ↓ 阶段3：归档变更（Archive） 何时必须创建提案？ 场景 是否需要提案 新增功能或能力 ✅ 必须 破坏性变更（API/Schema） ✅ 必须 架构或模式调整 ✅ 必须 Bug 修复（恢复既有行为） ❌ 跳过 拼写、格式、注释修正 ❌ 跳过 非破坏性依赖升级 ❌ 跳过 常用命令： Code block Plain Text Copy openspec list 列出所有变更 openspec list specs 列出所有规范 openspec validate <id 校验变更 openspec archive <id 归档变更 💡 小贴士：作为人类开发者，你无需记忆这些命令。AI 会自动执行相应的操作来检查和管理变更提案。你只需要理解这套规范的工作流程，就能与 AI 配合无间。 openspec/project.md 的作用 这个文件是项目的"知识库"，用于存放： • 项目目标和背景 • 核心业务术语 • 技术栈说明 • 详细文档索引 5 常见问题解答 5.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文件，直接变更规范，使其更加符合企业内的业务流程。 好文章值得被更多人看见！既然看到这里了，随手点个赞👍和关注，并转发给更多的朋友吧！感谢。 作者：数字生命贾克斯、微信：x h886688 3.3 📍 场景 2：Trae（字节跳动） OpenSpec 在初始化时可选择的AI 工具中是不支持 Trae 的，但是很多朋友是基于 Trae 在开发。 所以对于使用 Trae 的朋友，我们在执行 OpenSpec Init 的时候，可以选择最后一个选项 Other Tools (适用于 VsCode 等） 此时初始化后的目录结构如下： 关键差异：需要手动配置 与 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. 根据规范执行对应任务 4 OpenSpec 规范核心要点 无论使用哪种 AI 工具，OpenSpec 的核心工作流都是一致的。理解这套规范，你就能更好地与 AI 协作。 三阶段工作流： 何时必须创建提案？ 场景 是否需要提案 新增功能或能力 ✅ 必须 破坏性变更（API/Schema） ✅ 必须 架构或模式调整 ✅ 必须 Bug 修复（恢复既有行为） ❌ 跳过 拼写、格式、注释修正 ❌ 跳过 非破坏性依赖升级 ❌ 跳过 场景 场景 是否需要提案 是否需要提案 新增功能或能力 新增功能或能力 ✅ 必须 ✅ 必须 破坏性变更（API/Schema） 破坏性变更（API/Schema） ✅ 必须 ✅ 必须 架构或模式调整 架构或模式调整 ✅ 必须 ✅ 必须 Bug 修复（恢复既有行为） Bug 修复（恢复既有行为） ❌ 跳过 ❌ 跳过 拼写、格式、注释修正 拼写、格式、注释修正 ❌ 跳过 ❌ 跳过 非破坏性依赖升级 非破坏性依赖升级 ❌ 跳过 ❌ 跳过 常用命令： 💡 小贴士：作为人类开发者，你无需记忆这些命令。AI 会自动执行相应的操作来检查和管理变更提案。你只需要理解这套规范的工作流程，就能与 AI 配合无间。 openspec/project.md 的作用 这个文件是项目的"知识库"，用于存放： • 项目目标和背景 • 核心业务术语 • 技术栈说明 • 详细文档索引 5 常见问题解答 5.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 每次对话自动加载 每次对话自动加载 OpenSpec 工作流 OpenSpec 工作流 openspec/AGENTS.md openspec/AGENTS.md 触发关键词后加载 触发关键词后加载 业务上下文 业务上下文 openspec/project.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文件，直接变更规范，使其更加符合企业内的业务流程。 好文章值得被更多人看见！既然看到这里了，随手点个赞👍和关注，并转发给更多的朋友吧！感谢。 作者：数字生命贾克斯、微信：x h886688 🔗 原文链接： https://mp.weixin.qq.com/s/wyUdxh2T... https://mp.weixin.qq.com/s/wyUdxh2T... 原创 数字生命贾克斯 数字生命贾克斯 数字生命贾克斯2026年1月18日 21:21 上海 贾克斯 读完需要5分钟 速读仅需 3 分钟 1 为什么有时候让 AI 发起提案"时灵时不灵"？ 前两天有朋友看了我写的《 如何用 AI + OpenSpec 驱动团队迭代开发 》后，问我一个很有趣的问题： 如何用 AI + OpenSpec 驱动团队迭代开发 "为什么有时候我让 AI 发起 OpenSpec 提案，时灵时不灵？" 其实这个问题很简单，答案就藏在 OpenSpec 的工作原理中。 今天这篇文章，5 分钟的时间帮你快速了解 OpenSpec 的核心原理——它究竟是如何让 AI"听话"地按照规范来工作的。 2 快速认识 OpenSpec OpenSpec 是一个规范驱动开发工具，核心理念极其简单： “ 让 AI 明确知道"知识在哪、如何用、为什么这样做 ” 官网：https://openspec.dev/ 2.1 安装与初始化 初始化时，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 后的目录结构如下： commands/openspec 这个目录定义了三个不同的命令，每个命令文件中所写的提示词，都是 AI 在执行该命令时需要参考的"规范"。上述三个命令分别是： • apply.md ：表示执行已批准的变更 • archive.md ：归档已完成的变更 • proposal.md ：发起新变更提案 当我们需要发起新的提案时，可以直接使用：/openspec:proposal 就可以触发该指令，此时 AI 就会根据 proposal.md 中所定义的规范，来创建一个新的变更提案。 核心文件解读： AGENTS.md 这个文件是 Claude Code 每次对话时的"第一课"，内容如下： 工作原理： 1. Claude Code 启动时自动读取 AGENTS.md 2. 判断用户请求是否触"提案/变更"等关键词 3. 如果触发，自动加载 openspec/AGENTS.md 中的详细规范 4. AI 按照规范执行任务