官方教程中文版Agents & Skills
编写规则
基于 OpenCode 官方 Rules 文档，帮助新手理解 AGENTS.md、全局规则、Claude Code 兼容和外部指令文件。
OpenCode 的 rules 是给 Agent 的项目说明和行为约束。官方推荐用 AGENTS.md 承载项目级规则，并把它提交到 Git，让团队成员获得一致上下文。
先理解规则解决什么问题
规则不是用来写愿望清单的。它应该回答 Agent 每次进入项目都会遇到的问题：
- 这个项目是什么。
- 常用 build、lint、test 命令是什么。
- 哪些目录最重要。
- 有哪些项目特定约定。
- 哪些操作不要做。
- 验证顺序是什么。
好的规则让 Agent 少猜，坏的规则会把上下文塞满但不给行动边界。
第一次怎么生成
官方提供 /init，它会扫描仓库并创建或更新 AGENTS.md。如果仓库已经有 AGENTS.md，它会尝试补充而不是盲目替换。
新手可以先运行 /init，但不要直接相信生成结果。你应该检查：
- 命令是否真实存在。
- 目录说明是否准确。
- 是否写了测试和验证顺序。
- 是否包含不该公开的路径、账号或密钥。
- 是否太长。
生成规则只是开始，人工校正才是关键。
项目规则和全局规则怎么分
项目规则放在仓库根目录 AGENTS.md，适合提交到 Git。它应该服务这个项目的所有协作者。
全局规则放在 ~/.config/opencode/AGENTS.md，只影响你自己的所有 OpenCode 会话。它适合个人偏好，例如表达方式、你自己的工具习惯、常用检查顺序。
不要把个人习惯写进项目规则，也不要把项目特定命令写进全局规则。
Claude Code 兼容怎么理解
OpenCode 支持 Claude Code 的约定作为 fallback：项目里没有 AGENTS.md 时，可以读取 CLAUDE.md；没有 OpenCode 全局规则时，也可以读取 ~/.claude/CLAUDE.md。
这对迁移很有用，但新手不要长期依赖隐式 fallback。OpenCode 项目里最好有明确的 AGENTS.md，这样团队成员不用猜到底读的是哪套规则。
外部指令怎么放
如果规则很多，不要把所有内容塞进 AGENTS.md。官方推荐用 opencode.json 的 instructions 字段引用外部文件，支持本地文件、glob，也支持远程 URL。
新手原则：
AGENTS.md保持短，放入口和关键规则。- 长规范放单独文件。
- 需要多包规则时，用 glob 组织。
- 远程 URL 只引用可信来源。
- 不要要求 Agent 预先加载所有大文件。
新手常见坑
/init后不审查就提交。AGENTS.md写成完整项目文档，太长且没有优先级。- 项目规则混入个人偏好。
- 全局规则写入某个项目的命令。
- 同时存在
AGENTS.md和CLAUDE.md，但团队不知道谁生效。 - 远程 instructions 来自不可信地址。
怎么判断规则健康
健康标准：
- 新人读完能知道项目怎么启动、怎么验证。
- Agent 能知道哪些目录和命令最重要。
- 规则短而明确，没有复述 README。
- 团队共享规则在项目
AGENTS.md。 - 个人规则在全局文件。
- 外部文件按需引用，不一次性塞满上下文。
规则文件的目标是减少误操作，不是证明项目文档很完整。
官方资料
© Anomaly
最近更新：2026年5月4日