OpenCode AGENTS.md 规则完全指南：从 opencode.json 到 CLAUDE.md 的配置骨架

1. 为什么你的 OpenCode 规则总是「各写各的」如果你同时用过 OpenCode、Claude Code 和 Cursor大概率遇到过这种局面项目根目录躺着AGENTS.md~/.claude/CLAUDE.md里还有一份全局偏好opencode.json又通过instructions引了一堆外部规则文件。三份内容互相重叠改了一处忘了另一处AI 的行为就开始飘。OpenCode 的规则体系本质上是一个分层合并 就近优先的加载器。AGENTS.md是主入口opencode.json的instructions字段负责把外部 Markdown 拉进来而CLAUDE.md是兼容层的回退方案。理解这三者的协同关系才能把「AI 工具规则入口」统一到一处而不是每个工具配一套。这篇面向需要统一规则入口的开发者给出可直接复制的AGENTS.md骨架、opencode.json关键字段、CLAUDE.md对照写法并说明如何用 TaoToken 统一 Key/API 通道完成一次真实的规则加载验证。适合已经在用 OpenCode 做日常编码、但规则文件开始失控的人。2. TaoToken 前置把 Key 和 API 通道先统一规则文件写得再漂亮如果每个工具各配一个 Key、各走一条通道验证起来依然割裂。我的做法是先把模型访问层收敛到 TaoToken让 OpenCode、Claude Code 以及后续任何工具都指向同一个 API 入口。TaoToken 官网入口https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentAPI 基地址不带 UTMhttps://taotoken.net/api你需要先在控制台创建一个 API Key然后把它写进环境变量。OpenCode 读取模型配置时会优先看opencode.json里的 provider 设置其次看环境变量。推荐用环境变量避免 Key 进 Git。# 写入 shell 配置按需替换为你的实际 Key export TAOTOKEN_API_KEYsk-你的实际Key export OPENAI_BASE_URLhttps://taotoken.net/api export OPENAI_API_KEY$TAOTOKEN_API_KEY这里有个容易踩的点OpenCode 默认走 OpenAI 兼容协议所以OPENAI_BASE_URL指向 TaoToken 的/api即可不需要额外改协议。如果你用的是 Anthropic 系模型走 ClaudeCodeAnthropic 通道配置方式类似只是 provider 名称不同。Key 创建入口在控制台的 API Keys 页面建议按项目建不同 Key方便后续排查是哪个项目在消耗额度。接入文档里有完整的字段说明遇到 401/404 先对照文档确认 base URL 有没有多写或少写路径。3. 可复制配置AGENTS.md 骨架 opencode.json CLAUDE.md3.1 AGENTS.md 标准骨架下面这份骨架约 150 行适合中等项目。直接复制到项目根目录按注释替换成你自己的内容。# 项目名称 一句话说清这个项目是什么、给谁用。 ## 项目结构 - src/ - 主要源码 - packages/ - 子包 - infra/ - 基础设施与部署脚本 - docs/ - 设计文档 ## 技术栈 - 语言TypeScript - 框架Vue3 - 构建Vite - 测试Vitest - 包管理bun ## 编码规范 - 变量/函数camelCase - 组件/类型PascalCase - 常量UPPER_SNAKE_CASE - 缩进2 空格 - 禁止使用 any 类型必要时用 unknown 类型守卫 ## 常用命令 - 开发bun run dev - 测试bun test - 构建bun run build - 代码检查bun run lint ## 操作边界 - 允许修改src/views/、src/components/ - 禁止修改src/main.ts、package.json、vite.config.ts - 所有 API 密钥必须放 .env 文件禁止硬编码 ## 注意事项 - 数据库操作必须通过 ORM禁止裸 SQL - 错误必须记录日志返回给用户的消息要脱敏 - 新增依赖前先确认是否已有同类库篇幅建议小项目 60 行左右中等项目 150 行大项目 300 行封顶。超过 300 行就该拆分用opencode.json的instructions引用外部文件而不是把AGENTS.md写成一本手册。3.2 opencode.json 关键字段在项目根目录创建opencode.json核心是instructions字段它支持 GLOB 模式和远程 URL。{ $schema: https://opencode.ai/config.json, instructions: [ docs/**/*.md, .opencode/rules/*.md, packages/*/AGENTS.md ], provider: { openai: { options: { baseURL: https://taotoken.net/api, apiKey: {env:TAOTOKEN_API_KEY} } } } }几个关键点instructions里的文件内容会和AGENTS.md合并注入所以别把同一份规则同时写进两处否则上下文里会出现重复段落浪费 token 还容易让模型困惑。GLOB 模式要克制。**/*.md这种写法会把项目里所有 Markdown 都拉进来包括 README、CHANGELOG、甚至 node_modules 里的文档如果没被忽略上下文瞬间爆炸。只引真正需要的规则目录。远程 URL 仅支持 HTTPS5 秒超时需要网络连接。适合团队共享一份公共规则但要注意网络抖动会导致加载失败关键规则还是本地留一份。provider里的apiKey用{env:TAOTOKEN_API_KEY}语法引用环境变量这样 Key 不会进版本库。3.3 CLAUDE.md 对照写法OpenCode 在没有AGENTS.md时会回退查找CLAUDE.md。如果你同时用 Claude Code可以让两者共用一份内容用软链接或直接复制。# 项目名称 内容与 AGENTS.md 保持一致 ## 项目结构 ... ## 技术栈 ...同层级下AGENTS.md优先于CLAUDE.md所以如果你两份都放了实际生效的是AGENTS.md。跨层级则是项目级优先于全局级子目录优先于根目录。如果你不想让 OpenCode 读 Claude 的配置可以禁用兼容模式export OPENCODE_DISABLE_CLAUDE_CODE1 # 完全禁用 .claude 支持 export OPENCODE_DISABLE_CLAUDE_CODE_PROMPT1 # 只禁用 ~/.claude/CLAUDE.md export OPENCODE_DISABLE_CLAUDE_CODE_SKILLS1 # 只禁用 .claude/skills3.4 分层 AGENTS.md 的 Monorepo 实践根目录AGENTS.md只放「不管改哪个包都必须遵守」的规则技术栈、编码规范、提交约定。子目录AGENTS.md只补充该模块特有的差异比如某个包用 Jest 而不是 Vitest某个包有特殊的构建命令。原则就三条根目录说了的子目录不重复子目录只写差异冲突时子目录优先。这样维护成本最低改根目录规则时不用去翻每个子目录。4. 验证请求确认规则真的被加载了配置写完不代表生效。我习惯用一个最小验证流程确认规则加载链路通了。第一步确认 OpenCode 能读到配置。在项目根目录运行opencode --print-config如果输出里能看到instructions数组和 provider 的 baseURL说明opencode.json解析正常。第二步发一个能触发规则约束的请求。比如在AGENTS.md里写了「禁止使用 any 类型」就让模型生成一段 TypeScript 代码看它是否遵守。opencode run 写一个函数接收一个用户对象返回格式化后的名字如果模型输出里没有出现any而是用了具体类型或unknown说明AGENTS.md的编码规范被注入了。如果它依然随手写any那规则大概率没加载。第三步验证instructions引用的外部文件是否生效。在.opencode/rules/下放一个测试规则比如「所有函数必须写 JSDoc 注释」然后重新发请求看输出是否带注释。第四步确认 API 通道走的是 TaoToken。在请求过程中观察控制台的用量记录如果能看到对应的调用说明 Key 和 baseURL 配置正确。这一步能同时验证规则加载和通道连通性一举两得。实测下来最容易出问题的是instructions的路径写错。GLOB 模式对相对路径敏感docs/**/*.md和./docs/**/*.md在某些版本下行为不一致建议统一用不带./的写法。5. 本篇常见错排查规则不生效模型行为没变化。先确认AGENTS.md在项目根目录且文件名大小写正确。OpenCode 查找的是AGENTS.md不是agents.md。然后确认没有设置OPENCODE_DISABLE_CLAUDE_CODE之类的环境变量误伤了加载。instructions 引用的文件没被加载。检查 GLOB 模式是否匹配到了实际文件。可以用ls docs/**/*.md在 shell 里先验证模式能展开出文件。如果路径里有空格或特殊字符需要转义。上下文超长请求变慢或报错。大概率是instructions引了太多文件或者用了**/*.md这种宽泛模式。把规则拆分成「必读」和「按需」两类必读的放AGENTS.md按需的用引导指令懒加载。API 返回 401。Key 没配对环境变量或者opencode.json里的{env:TAOTOKEN_API_KEY}变量名和实际导出的不一致。在 shell 里echo $TAOTOKEN_API_KEY确认一下。API 返回 404。baseURL 写错了。TaoToken 的 API 基地址是https://taotoken.net/api不要多加/v1之类的路径除非接入文档明确说明。CLAUDE.md 和 AGENTS.md 内容冲突。同层级下AGENTS.md优先所以冲突时以AGENTS.md为准。如果发现生效的是CLAUDE.md检查是不是AGENTS.md没被正确识别。子目录规则没覆盖根目录规则。子目录AGENTS.md只在该目录下的文件被操作时生效。如果你在根目录操作文件子目录规则不会加载这是预期行为。6. 把规则入口收敛到一处规则文件的价值在于「写一次处处生效」。AGENTS.md做主入口opencode.json的instructions做外部引用CLAUDE.md做兼容回退三者各司其职不要互相抄内容。Key 和 API 通道同理收敛到 TaoToken 一处OpenCode、Claude Code 都指向同一个 baseURL验证规则加载时不用来回切换配置。模型对话入口适合快速验证规则是否生效Coding Plan 适合长期编码和 Agent 场景接入文档和 API Keys 页面则是排障时的第一站。最后留一个实用习惯每次改完AGENTS.md或opencode.json用opencode run发一个能触发规则的最小请求确认行为符合预期再提交。规则文件也是代码改了就该验证。