OpenCode 规则指南：作用域、优先级与自定义指令

项目规则适合测试命令、生成目录、文件归属、安全边界和发布检查等仓库事实。它随仓库进入评审，能与被保护的代码一起更新。全局规则适合跨项目稳定的个人习惯，例如希望如何总结 diff 或先运行哪条无害检查。URL 规则适合可信文档上下文，但不能成为关键安全规则的唯一来源。

外部 URL 还带来网络和来源边界。应确认主机、传输、维护者和变更记录，并为密钥、生产路径、生成文件等高风险约束保留本地兜底。

官方 Rules 文档覆盖 Initialize、Types、Precedence、Custom Instructions 和外部文件引用。应先使用当前版本的初始化流程或检查生成的项目文件，再确认本机版本真正读取的路径。不要从别的 Agent 框架照抄目录名。

规则文件应靠近它描述的项目约定，写清保护什么、用哪条命令证明完成、如何更新。长流程应移到 skill，规则只保留约束和入口。

全局规则和项目规则可能重叠，例如全局要求先跑快速测试，而项目要求另一条命令或禁止改生成目录。实际行为取决于官方记录的规则类型和优先级。先读当前 Rules 页面，再写一个小冲突案例观察谁生效。

实务上应让最具体的项目安全边界负责仓库行为。遇到冲突时删除重复表达、保留项目约束，并把原因写进规则或评审记录。不要通过复制两份指令来制造更长的 prompt。

好的规则要回答五个问题：何时生效、Agent 必须做什么、必须避免什么、什么证据证明完成、如何禁用或更新。优先写具体路径和命令，不要只写“注意生产环境”这样的空话。

把事实和偏好分开。仓库文档明确的测试命令属于项目规则；偏好的解释长度更适合全局规则或 skill。这样不会把个人习惯误变成团队政策。

外部文件可以集中维护共享说明，但 URL 会成为执行边界。应检查域名、传输、归属、更新历史和是否无需审查就能变化。能成功返回页面，不代表适合交给可写会话。

外部引用先用于低风险上下文，例如 API 命名或公开风格指南。密钥、部署、破坏性命令和客户数据规则必须留在本地；网络不可用时要明确失败或使用已审查副本。

Rules 表达持久指令；skills 表达可复用步骤；agents 定义角色、模型、工具和输出契约；permissions 决定工具动作是允许、询问还是拒绝；config 管理 provider 和目录等产品设置。它们可以协作，但职责必须可见。

不要把完整发布流程塞进规则文件，再用权限例外让它自动运行。规则保留护栏，重复流程放进 command 或 skill，高影响动作要求显式批准。

用一次性分支或小仓库验收新规则。先让 OpenCode 解释它采用的规则、列出可能触碰的文件，再执行只读任务。随后做一次无害编辑，检查 Git diff，并与契约对照，尽早发现路径错误、语法过期、作用域泄漏和全局冲突。

保留回滚路径：删除项目规则、禁用外部引用或从 Git 恢复旧文件。回滚后复跑同一任务，确认行为确实改变。更新规则时记录日期、原因和验证命令，避免升级后出现无法解释的政策漂移。