年没人敢碰的老代码，我用AI重构了它——然后翻车了

1 安装与初始化# 全局安装 OpenSpecnpm install -g fission-ai/openspeclatest# 在项目目录下初始化cd /path/to/your-projectopenspec init初始化时OpenSpec 会提示你选择使用的 AI 工具Claude Code、Cursor、Trae、Qoder 等。3 OpenSpec 如何教AI 工作OpenSpec 的核心机制是通过一套规范注入系统让 AI 在每次对话前先学习项目规范。3.1 不同 AI 工具的初始化差异根据你使用的 AI 工具不同OpenSpec 会生成不同的目录结构。这背后的设计理念是最大限度地适配各工具的特性。3.2 ?? 场景 1Claude CodeClaude Code 在执行了 OpenSpec Init 后的目录结构如下.claude/├── commands/│ └── openspec/│ ├── apply.md│ ├── archive.md│ └── proposal.md├── AGENTS.md└── CLAUDE.mdcommands/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 ?? 场景 2Trae字节跳动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 Q2project.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文件直接变更规范使其更加符合企业内的业务流程。窖皇蕾乜