规则

为 opencode 设置自定义指令。

你可以通过创建 AGENTS.md 文件为 opencode 提供自定义指令。这类似于 Cursor 的规则。它包含将被纳入 LLM 上下文的指令，以针对你的特定项目自定义其行为。

初始化

要创建新的 AGENTS.md 文件，你可以在 opencode 中运行 /init 命令。

提示： 你应该将项目的 AGENTS.md 文件提交到 Git。

这将扫描你的项目及其所有内容，以了解项目的用途，并生成一个包含这些信息的 AGENTS.md 文件。这有助于 opencode 更好地导航项目。

如果你已有 AGENTS.md 文件，这将尝试在其基础上添加内容。

示例

你也可以手动创建此文件。以下是一些可以放入 AGENTS.md 文件的内容示例。

我们在这里添加项目特定的指令，这将在你的团队中共享。

类型

opencode 还支持从多个位置读取 AGENTS.md 文件。这服务于不同的目的。

项目级

在项目根目录放置 AGENTS.md 用于项目特定规则。这些规则仅在你在此目录或其子目录中工作时适用。

全局级

你也可以在 ~/.config/opencode/AGENTS.md 文件中设置全局规则。这将应用于所有 opencode 会话。

由于这不会提交到 Git 或与团队共享，我们建议使用它来指定 LLM 应遵循的任何个人规则。

Claude Code 兼容性

对于从 Claude Code 迁移的用户，OpenCode 支持 Claude Code 的文件约定作为后备：

• 项目规则：项目目录中的 CLAUDE.md（如果没有 AGENTS.md 则使用）
• 全局规则：~/.claude/CLAUDE.md（如果没有 ~/.config/opencode/AGENTS.md 则使用）
• 技能：~/.claude/skills/ — 详见代理技能

要禁用 Claude Code 兼容性，请设置以下环境变量之一：

优先级

当 opencode 启动时，它按以下顺序查找规则文件：

• 本地文件：从当前目录向上遍历（AGENTS.md、CLAUDE.md）
• 全局文件：位于 ~/.config/opencode/AGENTS.md
• Claude Code 文件：位于 ~/.claude/CLAUDE.md（除非禁用）

每个类别中第一个匹配的文件获胜。例如，如果你同时有 AGENTS.md 和 CLAUDE.md，只会使用 AGENTS.md。同样，~/.config/opencode/AGENTS.md 优先于 ~/.claude/CLAUDE.md。

自定义指令

你可以在 opencode.json 或全局 ~/.config/opencode/opencode.json 中指定自定义指令文件。这允许你和你的团队重用现有规则，而不必将它们复制到 AGENTS.md。

示例：

你也可以使用远程 URL 从网络加载指令。

远程指令的获取超时时间为 5 秒。

所有指令文件都会与你的 AGENTS.md 文件合并。

引用外部文件

虽然 opencode 不会自动解析 AGENTS.md 中的文件引用，但你可以通过两种方式实现类似功能：

使用 opencode.json

推荐的方法是使用 opencode.json 中的 instructions 字段：

在 AGENTS.md 中手动指令

你可以通过在 AGENTS.md 中提供明确的指令来教 opencode 读取外部文件。以下是一个实际示例：

这种方法允许你：

• 创建模块化、可重用的规则文件
• 通过符号链接或 git 子模块在项目间共享规则
• 保持 AGENTS.md 简洁，同时引用详细指南
• 确保 opencode 仅在特定任务需要时加载文件

提示： 对于 monorepo 或具有共享标准的项目，使用带有 glob 模式的 opencode.json（如 packages/*/AGENTS.md）比手动指令更易于维护。