为什么缺失远程指令文件很难被察觉
OpenCode 从 AGENTS.md 文件中读取自定义指令，此外还会从你在 opencode.json 或全局配置中指定的列表中读取。该列表支持普通路径、glob 模式和 URL，文档中说明的行为是“所有指令文件都会与你的 AGENTS.md 文件合并”。
“合并”是这里的关键词。在启动时会组装成一个合并后的指令主体，而对话中没有任何标记指出哪些条目贡献了内容。成功获取的文件和超时的文件产生的会话在外观上完全相同：智能体正在遵循指令，只是没有遵循全部指令。
对比一下本地条目的表现。列表中的路径要么在磁盘上解析成功，要么解析失败，而磁盘查找不需要 5 秒钟。glob 模式要么匹配到文件，要么什么也匹配不到。这些失败是稳定的——今天错意味着明天也错，这是那种你发现一次就能彻底修复的故障。
而远程条目则是间歇性失败。它在你的办公桌前能用，但在火车上不能用。它对你有效，但对使用较慢代理的同事无效。指令的间歇性缺失是这个问题最糟糕的表现形式，因为当智能体忽略某条规则时，人们通常会重新强调该规则，而不是去检查该规则是否成功加载。这也是导致大多数智能体似乎跳过了指令文件中的规则这一陷阱背后的原因。
同一个列表中还存在第二个更隐蔽的问题。OpenCode 自身关于 instructions 字段的示例中包含一个以 .md 结尾的 .cursor/rules glob 模式。而 Cursor 的项目规则使用的是不同的扩展名，因此以这种方式编写的 glob 模式在装满 Cursor 规则的文件夹中什么也匹配不到——而匹配不到任何内容并不会报错。将一个工具文档中可用的示例直接复制到另一个工具的配置中，最终会导致列表看起来内容丰富，实则毫无用处。
人们尝试的其他替代方案
将每个项目都指向同一个 URL 并称之为集中化。 这确实是集中化的。但它现在也成了公司中每个会话启动路径上的网络依赖。
提高超时时间。 文档中没有提供相关的配置选项。5 秒是固定的行为，而不是你可以调整的默认值。
添加第二个 URL 作为备用。 两个远程条目意味着两次超时的机会，而不是故障转移。文档中描述的行为并没有尝试一个失败后再尝试另一个的机制。
假设获取失败会有明显的提示。 文档中没有任何内容表明当远程指令文件未按时到达时会导致硬性失败或阻塞会话。做好无声失败的准备。
将共享规则复制到每个项目的 AGENTS.md 中。 这是最可靠的选择，但也是远程功能本想避免的做法。它确实有效，但一个月内，各个副本之间就会出现不一致。
假设文件引用语法能帮到你。 它帮不上忙，文档中明确指出：“OpenCode 不会自动解析 AGENTS.md 中的文件引用。”在指令文件中写入路径并不会引入该文件。instructions 字段才是官方支持的途径。
解决方案：保留一个已提交的本地副本作为单一事实来源，并通过网络进行更新
我们的目标是保留共享规则的一个权威版本，同时不将网络请求放在每个会话的关键启动路径上。这意味着 OpenCode 读取的是仓库中的副本，而网络仅用于更新该副本。
步骤 1：将远程条目替换为已提交的本地路径
在 opencode.json 中，将 URL 条目更改为仓库内部的路径。例如，将存放共享指南的 docs 文件夹作为普通路径引用到 instructions 数组中。然后提交该文件。
这颠倒了依赖关系。OpenCode 现在读取磁盘上的文件，该文件要么存在，要么不存在，失败模式从而变得稳定，不再是间歇性的。任何克隆该仓库的人无论能否访问内部主机，都能获得这些规则。
在编辑列表时，检查其中的每一个 glob 模式。确认扩展名与目标工具实际写入的扩展名相匹配——这就是 Cursor 规则示例出错的地方——并确认每个 glob 模式目前至少能匹配到一个文件。匹配不到任何内容的 glob 模式与正常工作的条目是无法区分的，而这正是你想要消除的特性。
步骤 2：将刷新作为一个可见的步骤，而不是启动时的副作用
现在决定如何更新本地副本。正确的答案是你们团队已经在审查的任何流程：在上游指南发生变化时自动发起拉取请求（pull request）的定时任务，或者是依赖项更新流程中的一个步骤。
重要的是，更新必须是人员可见的。当共享指南发生变化时，有人会在该项目的上下文中审查差异（diff），因为在中央仓库中合理的规则有时在特定服务中并不适用。启动时获取会直接给你新文本而无需任何审查；而拉取请求则会给你新文本并让你做出决策。
它还能提供历史记录。六个月后，“这条规则是从什么时候开始适用于我们的”在仓库日志中就能找到答案，而这是通过网络获取文件永远无法提供的。
步骤 3：验证合并后的指令集是否符合预期
启动一个会话并确认规则已生效——不要通过询问智能体它是否拥有这些规则，而是给它一个受这些规则约束的小任务，并检查输出是否遵循了这些规则。
选择一些明确且成本低的任务。如果共享指南要求特定的错误处理形式，让它编写一个必须返回错误的小函数，并观察其形式。如果它要求特定的注释规范，让它创建一个新文件并阅读文件头。
在修改后执行一次此操作，并在每次刷新本地副本时再次执行。运行符合规则的测试是唯一可靠的检查方法，因为指令集被合并为一个整体，没有针对每个条目的报告——这也是有意识地将指令范围限定到特定文件，而不是凭空假设，是非常值得做的事情的原因。
在 MemoryLake 中进行设置
共享指南只是针对某一个工具的配置。而其规则背后的推理——为什么要采用这种错误形式，为什么要划定这个边界——才是你真正希望在每个工具和每个会话中都能使用的内容。MemoryLake 是一个保存这些推理的地方，使其不依赖于网络获取的完成。
你可以用自己的语言亲自编写这些条目。无需从远程指令文件、OpenCode 配置或任何厂商的存储中读取、写入或删除任何内容。
步骤 1：创建 API 密钥
登录并在控制面板中生成一个密钥。该密钥允许智能体直接读取条目，无需获取中间文件，也不会因超时而丢失。
步骤 2：上传你的第一批记忆
添加共享指南所编码的决策，每个条目一条，并附带其原因。“错误返回类型化结果，因为调用者需要根据类型进行分支”是可移植的。而“遵循错误处理指南”则是一个指针，一旦指针断开就会失效。
步骤 3：连接你的 AI 和智能体
将你的智能体指向该工作区。这样，你团队使用的每个工具中都会包含这些推理，而特定于工具的指令文件可以保持尽可能精简。
这在实践中带来了什么改变
第一个改变是，网络状况不佳不再会导致无声的规则失效。从磁盘读取意味着规则要么存在，要么明显不存在，而“明显不存在”是人们在第一次运行时就会注意到的，而不是在三周后的代码审查中才发现。
第二个改变是共享指南增加了一个审查步骤。中央规则仓库会不断累积规则，而在启动时获取规则的项目会自动采用每一次新增的内容，包括那些不适用于该项目的规则。而以 diff 形式呈现的刷新则会被人阅读。
第三个改变是你的指令列表变得可审计。每个条目都是你可以检查的路径或 glob 模式，检查一个 glob 模式只需几秒钟。一旦列表中没有 URL，“我的指令集中有什么”就成了一个有明确答案的问题——这正是让指令文件值得维护的特性，也是为什么文件顺序和优先级值得明确固定下来的原因。
这需要付出代价，坦率地指出这一点：本地副本可能会过时。获取的文件总是最新的，而提交的副本只在最后一次刷新时是最新的。这个权衡是值得的，因为过时的规则在文件中是可见的，而缺失的规则则是不可见的，但这只有在刷新确实发生时才成立。如果你的团队不运行刷新，那么你就是主动选择了过时，而不是被动感到意外。
每当有工具提供从其他地方拉取指令的功能时，都会出现同样的权衡，无论是智能体根据请求为你生成规则，还是将你的配置重写为新工具格式的迁移——任何将项目从 Cursor 迁移到 OpenCode的人都会认同这一点。
构建值得信赖的指令列表的最佳实践
保持启动路径本地化。 OpenCode 在第一轮对话前必须读取的所有内容都应该在磁盘上。网络调用属于刷新任务，而不属于会话启动。
根据目标工具的实际扩展名验证每个 glob 模式。 这是一个两分钟的检查，可以捕获最常见的无声空匹配条目。不要盲信示例，即使是官方示例。
每个仓库保留一个已提交的权威副本。 不要使用指向共享签出的符号链接，也不要使用项目之外的路径。全新克隆项目的人应该能直接获取这些规则。
测试规则，而不是询问规则。 智能体报告它拥有你的指令并不能作为证据。受规则约束的小任务才是。
将原因保存在规则文件之外的持久地方。 当工具发生变化时，规则文件会被重写。规则存在的原因才是让下一个人决定是否保留它的依据。
为本地副本标注日期。 在顶部写上一行说明上次刷新时间的注释，可以让“这是否是最新的”从一项调查变成一目了然的确认。
注意增长情况。 指令列表中的每个条目都会合并到请求中。不断累积条目的列表会导致每轮对话的前缀不断增长，这与每次发送内容带来的 Token 成本是同一个计算问题。
结论
远程指令文件解决了一个实际问题，但也引入了一个特定的问题。OpenCode 获取它们时有 5 秒的超时限制，将成功获取的内容与你的 AGENTS.md 合并，并且不提供针对每个条目的报告——因此，未成功加载的指令文件看起来与成功加载的完全一样。
将列表指向一个已提交的本地副本，将刷新作为一个经过审查的步骤，而不是启动时的副作用，并通过给智能体一个受规则约束的任务来证明规则已生效。你失去了自动更新的便利，但获得了一种可见的失败模式。
然后，将规则背后的推理保存在不属于任何单一工具配置文件的其他地方，因为在下一次迁移后，你仍然需要这部分内容——这也是团队在在智能体之间迁移指令并发现文件其实是最简单的部分时得出的相同结论。