如何在不丢失上下文的情况下从 Cursor 迁移到 opencode (2026)

规则内容可以原样迁移。 两种工具都接受纯 Markdown 指令并将其提供给模型。Cursor 对该机制的描述非常直白：“大语言模型在补全之间不会保留记忆。规则在提示词级别提供持久、可复用的上下文”，并且“在应用时，规则内容会包含在模型上下文的开头”。opencode 的表述几乎完全相同——AGENTS.md 包含“将包含在 LLM 上下文中以针对您的特定项目自定义其行为的指令”，其文档甚至表示该概念“与 Cursor 的规则类似”。

根目录下的 AGENTS.md 无需任何操作即可迁移。 如果您已经在使用 Cursor 的 AGENTS.md 选项（Cursor 将其定位为“.cursor/rules 的简单替代方案”），opencode 会直接读取它。opencode 中的项目根目录规则“仅在您在此目录或其子目录中工作时适用”。

一旦 glob 正确，您的 .mdc 规则文件就可以作为文件迁移。 opencode 的 instructions 数组接受文件路径和 glob 模式，因此这些文件可以完全保留在 .cursor/rules/ 中的原位置。您只是指向它们，而不是移动它们。这确实比重写要好得多，也是为什么选择这种迁移方式，而不是将所有内容扁平化合并为一个文件的原因。

Frontmatter（前置元数据）无法迁移。 这是最核心的损失。Cursor 的四种规则类型是 Always Apply（始终应用）、Apply Intelligently（智能应用，“当 Agent 根据描述决定其相关时”）、Apply to Specific Files（应用到特定文件，“当文件匹配指定模式时”）和 Apply Manually（手动应用，“在聊天中被 @ 提到时”）。这些是通过三个 frontmatter 字段的交互实现的：在提供 alwaysApply: false 和 globs 时，规则会“在匹配的文件处于上下文中时自动附加”；在提供 alwaysApply: false 和 description 但没有 globs 时，“Agent 会读取描述并在相关时拉入规则”；如果两者都没有，则“仅在您在聊天中 @ 提及该规则时包含”。

opencode 没有任何文档记载的对应机制。其文档指出“所有指令文件都会与您的 AGENTS.md 文件合并”。以前只有在您修改 src/components/** 时才会出现的规则，现在会在每次请求时都出现；同样，您之前因为是极少使用的迁移清单而设置为手动的规则，现在也会每次都出现。这不会引起明显的报错，但您的提示词会变得庞大得多，且针对性变差，这就是我们在为什么 Agent 会忽略您的指令文件中描述的失效模式。

规则内部的 @file 引用无法迁移。 Cursor 规则可以内联引用其他文件——例如以 @migration-template.sql 结尾的规则会拉入该模板。opencode 的文档很直接：“opencode 不会自动解析 AGENTS.md 中的文件引用”。支持的两种解决方法是：自己将引用的文件列在 instructions 中，或者写明明确的文本指示 Agent 去读取它们。

团队规则（Team Rules）无法迁移。 Cursor 的团队规则是在 Team 和 Enterprise 计划的 Cursor 仪表板中管理的，“优先级高于”其他规则类型，并且可以标记为“无法在自定义中禁用”。这是一个组织管理控制台，而不是一个文件。这些规则所表达的任何内容都必须重新表达为提交到版本控制的文件——这也意味着它不再具有相同的强制执行力。

Cursor 有而 opencode 没有的，以及反之。 Cursor 记录的持久化机制是四种形式的规则；搜索 Cursor 的文档索引找不到任何关于会自动写入的记忆库（memory store）的内容，因此准确的说法是，Cursor 没有这方面的文档对应物。opencode 记录的机制是 AGENTS.md 文件、instructions 数组和 /init 命令。这两种工具都没有记录一个可以积累您在工作中所学知识的存储库——而这正是本指南不断提及的第三类内容。

步骤 1：修复 glob，然后在其基础上运行 /init

首先从项目 opencode.json 中的 instructions 数组开始。文档中的示例使用的是 .md；而您的规则是 .mdc，并且 Cursor 支持子目录，例如 .cursor/rules/frontend/components.mdc。因此，您需要的模式是 .cursor/rules/**/*.mdc，这也能捕获嵌套的规则文件夹。如果您在其中有一些普通的 Markdown 文档（Cursor 之前忽略了这些文档，但您实际上希望 opencode 读取它们），也可以将 .md 保留在列表中——这是一种少见但真实存在的情况，因为 Cursor 会丢弃这些文件，而 opencode 不会。

添加您的 Cursor 规则以前用 @ 引用的文件，因为这些引用将不再被解析。如果您曾有一个指向 @migration-template.sql 的规则，该模板需要放入 instructions 中，或者在文本中明确命名。

然后运行 /init。这是人们经常跳过的一步，但也是最值得做的一步。opencode 的 /init 会“扫描您仓库中的重要文件，在代码库无法回答时可能会提出几个有针对性的问题，然后创建或更新包含简洁的、特定于项目的指南的 AGENTS.md”，并且它明确考虑了“对现有指令源（如 Cursor 或 Copilot 规则）的引用”。至关重要的是，运行它不是破坏性的：“如果您已经有了 AGENTS.md，/init 将在原处对其进行改进，而不是盲目地替换它。”在配置好 instructions 之后运行它，意味着它可以看您已经拥有了什么，而不是凭空捏造。

在创建任何内容之前，需要了解一个优先级规则：opencode 通过“从当前目录向上遍历（AGENTS.md、CLAUDE.md）”来解析本地文件，并在 ~/.config/opencode/AGENTS.md 解析全局文件，并且“每个类别中第一个匹配的文件胜出。例如，如果您同时拥有 AGENTS.md 和 CLAUDE.md，则仅使用 AGENTS.md”。如果您的仓库一直运行在 CLAUDE.md 上，创建 AGENTS.md 会将其停用。同样的模式也适用于全局：~/.config/opencode/AGENTS.md 的优先级高于 ~/.claude/CLAUDE.md。

步骤 2：决定每条无条件规则现在的成本

现在浏览您刚刚指向的 .mdc 文件，并且只阅读它们的 frontmatter。将它们分成三堆。

alwaysApply: true 的规则是无成本的。它们在 Cursor 中是无条件的，在 opencode 中也是无条件的。无需任何操作。

带有 globs 的规则原本被限制在特定的文件类型或目录中。在 opencode 中，它们现在始终处于开启状态。对于简短的规则（例如 5 行 TypeScript 规范），这没问题，将其扁平化是正确的选择。对于冗长的规则，您有两个坦诚的选择：将其缩减为值得在每次请求中都付出成本的部分，或者将其排除在 instructions 之外，并在您在该区域工作时有意识地加载它。没有第三种可以保留条件性的选择，假装有的话只会让指令文件的大小在不知不觉中翻三倍。

带有 description 但没有 globs 的规则是最有趣的一堆，因为 Cursor 将描述用作检索信号——即“Agent 读取描述并在相关时拉入规则”的行为。这种机制在 opencode 中没有立足之地。您可以保留的是意图：将描述文本保留为规则的第一行，以便人类在浏览合并后的提示词时能看出它的用途，并思考该规则到底是一条规则，还是您学到的一个事实。通常情况下，它属于后者，这意味着它应该属于下一节，而不是放在 instructions 中。

两个字段都没有的规则是手动的、仅限 @ 提及的。这些通常是清单 and 模板。完全将它们排除在 instructions 之外，并在需要时通过路径引用它们。opencode 的文档针对外部文件推荐的正是这种模式——教导 Agent 在满足条件时读取文件，而不是提前加载它。

在进行此操作时，Cursor 自身最佳实践建议也值得借鉴：“保持规则在 500 行以内”，“将大型规则拆分为多个可组合的规则”，以及“引用文件而不是复制其内容——这可以保持规则简短，并防止它们随着代码更改而过时”。这三点在 opencode 中比在 Cursor 中更为重要，因为没有条件层来吸收您多余的内容。如果您完全不想失去条件性，将 Cursor 规则迁移到 Codex 介绍了一个作用域工作方式不同的目的地，而将 Cursor 迁移到 Claude Code 介绍了另一个。

整理 frontmatter 堆通常会暴露出一些令人不适的事实：您的 .cursor/rules 内容中很大一部分并不是规则。而是历史记录。“不要使用批量端点进行对账，超过一万行就会超时。”“在第一季度之前，身份验证令牌由旧服务生成，因此不要在此处添加作用域。”这些是某人历经坎坷才学到的事实，被归档在工具提供的唯一可以持久保存的地方。

在这两种工具中，规则都不是存放这些内容的正确容器。Cursor 自己也说过：规则是“提示词级别的持久、可复用上下文”，每次都会重新发送。您在七月份学到的事实并不是提示词级别的配置；它是知识，它会无限制地积累，并且它是被发现的，而不是被编写出来的。

MemoryLake 就是存放这部分内容的地方。它独立于这两种工具之外，保存您团队确立的事实，而不是您团队的工作方式，并且可以通过 MCP 或 API 被您当前使用的任何客户端读取。这在迁移中的实际效果是，instructions 数组可以保持足够简短，从而使失去条件性不再那么令人痛苦。

步骤 1：创建 API 密钥

生成密钥并在大约 30 秒内发出您的第一次请求。一个密钥覆盖所有界面，这就是重点——知识不应该属于某个编辑器。

步骤 2：上传您的第一批记忆

放入已经承载您项目既定决策的文档、图像和文件，以及您刚刚识别为历史记录而非规范的规则文件。从您厌倦了反复解释的内容开始。

步骤 3：连接您的 AI 和 Agent

让 Claude、Codex、OpenClaw 和其他 Agent 通过 MCP 或 API 进行访问。在 opencode 会话中，这意味着既定的事实可以按需检索，而不是永久占用您合并后的指令提示词。

instructions 数组保持很小，这使得失去条件性变得可以接受。Cursor 的条件层之所以存在，是因为规则目录会不断膨胀；如果这种膨胀转移到其他地方，扁平的数组实际上完全没有问题。

团队规则不再是迁移的阻碍。存在于 Cursor 仪表板中的组织内容被干净地拆分：可强制执行的规范变成提交到版本控制的文件，而既定的决策变成每个团队成员的 Agent 都可以读取的记忆，无论使用什么工具或订阅级别。

再次切换变得非常廉价。opencode 的 instructions 数组和 Cursor 的 .mdc frontmatter 都是特定于工具的格式。而通过 MCP 可访问的存储库则不是，这意味着下一次迁移只是配置更改，而不是知识审计。

而最初促使人们编写规则的特定烦恼——在同一件事上被纠正两次，或者重新教导 Agent 文件在仓库中的存放位置——在正确的层面上得到了解决。这从来都不是规则问题。这是一个试图用提示词解决的记忆问题。

验证 glob 是否匹配到了内容。 配置好 instructions 后，让 opencode 总结它加载的指南。如果您的 Cursor 规则缺失，首先要检查的就是扩展名。

在配置之后运行 /init，而不是在此之前。 它会在原处改进现有的 AGENTS.md，所以让它看到您真实的配置。

每个目录保留一个指令归属地。 同一位置的 AGENTS.md 会抑制 CLAUDE.md，因此选择其中一个并删除另一个，而不是留下一个看起来像在起作用的死文件。

小心远程指令 URL。 opencode 可以从 URL 加载指令，并且“远程指令的获取超时时间为 5 秒”。这使得共享团队规则文件成为可能，但也让您的会话依赖于主机的可用性。

不要通过粘贴内容来重新创建 @ 引用。 将文件添加到 instructions 中或在文本中命名。粘贴是 Cursor 自身指南所警告的行为，因为副本会过时。

在扁平化之前将历史记录移出。 只有在规则实际上是规范时，扁平化条件规则才是安全的。任何读起来像实战故事的内容都属于记忆层。

对这次迁移的客观总结是，opencode 的 instructions 数组确实是一个很好的想法——复用您已经编写的规则文件比重写它们要好——但已发布的示例中没有警告您两个文档中存在的差距。一个是显而易见的：glob 必须是 .mdc，而不是 .md，因为 Cursor 会忽略 .cursor/rules 中的普通 Markdown，因此您的规则全都是 .mdc。另一个是结构性的：instructions 会合并提供给它的所有内容，因此 Cursor 的“始终 (Always) / 智能 (Intelligently) / 按文件 (By-File) / 手动 (Manual)”的区别会坍缩为“始终开启”。

这两者都是可以解决的，第二个问题之所以好解决，主要是因为填满您规则目录的大部分内容根本就不应该成为规则。正确指向 glob，在其基础上运行 /init，将 frontmatter 分类为无成本、高成本和按需加载，并将积累的历史记录移动到这两种工具都不需要拥有的层。剩下的就是一个简短的指令文件，说明如何在这个仓库中工作——而这正是规则系统唯一擅长的事情。