OpenCode Rules 规则系统完全指南：用 AGENTS.md 定制 AI 编程助手的项目行为

在团队协作开发中，每个项目都有自己独特的编码规范、架构约定和工作流程。当使用 AI 编程助手时，如果它能自动理解并遵循这些项目特定的规则，效率和代码质量将大幅提升。OpenCode 的 Rules（规则）系统正是为此而生——通过 AGENTS.md 文件，你可以为项目注入精确、可共享的自定义指令，让 AI 助手真正成为"懂你项目"的编程伙伴。

什么是 OpenCode Rules？

OpenCode Rules 是一个基于 Markdown 文件的指令系统，核心文件是项目根目录下的 AGENTS.md。这个文件包含了针对当前项目的自定义指令，每次启动 OpenCode 会话时，这些指令都会被加载到 LLM 的上下文中，从而定制 AI 助手的行为。

你可以把它理解为项目的"使用说明书"——告诉 AI 助手你的项目用什么语言、什么框架、如何构建、怎样测试，以及有哪些特殊的约定需要遵守。

快速初始化：/init 命令

创建 AGENTS.md 最简便的方式是使用 OpenCode 内置的 /init 命令：

/init

在项目目录中启动 OpenCode 后，输入 /init，它会自动扫描项目中的重要文件，分析项目结构、依赖管理和构建工具链，然后有针对性地询问几个关键问题（比如测试框架偏好、部署流程等），最后生成一份贴合项目实际的 AGENTS.md 文件。

如果项目中已存在 AGENTS.md，/init 会对其进行增补改进，而非盲目覆盖。这意味着你可以放心地反复运行 /init 来持续优化规则文件。

AGENTS.md 示例

一个典型的 AGENTS.md 文件长这样：

# SST v3 Monorepo 项目
这是一个使用 TypeScript 的 SST v3 单体仓库，采用 bun workspaces 管理包依赖。

## 项目结构
- `packages/` - 工作区包目录（functions、core、web 等子包）
- `infra/` - 按服务拆分的基础设施定义（storage.ts、api.ts、web.ts）
- `sst.config.ts` - 主 SST 配置，使用动态导入

## 代码规范
- 使用 TypeScript 严格模式
- 共享代码放在 `packages/core/` 中，并正确配置导出
- 函数代码放在 `packages/functions/` 中
- 基础设施应按逻辑拆分到 `infra/` 下的独立文件

## 单体仓库约定
- 使用工作区名称导入共享模块：`@my-app/core/example`

规则类型

OpenCode 支持从多个位置读取规则文件，不同位置的规则服务于不同目的。

项目级规则（Project）

将 AGENTS.md 放在项目根目录，这些规则仅在该目录及其子目录下生效。这是最常用的方式，适合存放团队共享的项目规范，应当提交到 Git 仓库中。

全局规则（Global）

在 ~/.config/opencode/AGENTS.md 中放置全局规则，这些规则会应用于所有 OpenCode 会话。由于全局规则不会被提交到 Git，适合存放个人偏好设置，比如你习惯的代码风格、常用工具链等。

Claude Code 兼容

如果你是从 Claude Code 迁移过来的用户，OpenCode 提供了向后兼容支持：

• 项目规则：CLAUDE.md（仅当不存在 AGENTS.md 时生效）
• 全局规则：~/.claude/CLAUDE.md（仅当不存在 ~/.config/opencode/AGENTS.md 时生效）
• 技能文件：~/.claude/skills/

如果你不希望 OpenCode 读取 Claude Code 的配置，可以通过环境变量禁用：

export OPENCODE_DISABLE_CLAUDE_CODE=1        # 禁用所有 .claude 支持
export OPENCODE_DISABLE_CLAUDE_CODE_PROMPT=1 # 仅禁用 ~/.claude/CLAUDE.md
export OPENCODE_DISABLE_CLAUDE_CODE_SKILLS=1 # 仅禁用 .claude/skills

规则的优先级

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

本地文件：从当前目录向上遍历，查找 AGENTS.md（或 CLAUDE.md）

全局文件：~/.config/opencode/AGENTS.md

Claude Code 文件：~/.claude/CLAUDE.md（未禁用时）

在每一类中，优先找到的文件胜出。例如，如果同时存在 AGENTS.md 和 CLAUDE.md，只有 AGENTS.md 会被加载。

自定义指令文件

除了 AGENTS.md，你还可以在 opencode.json 中通过 instructions 字段指定额外的指令文件：

{
  "$schema": "https://opencode.ai/config.json",
  "instructions": [
    "CONTRIBUTING.md",
    "docs/guidelines.md",
    ".cursor/rules/*.md"
  ]
}

这个功能非常强大，它支持 glob 模式匹配，可以一次引入整个目录的规则文件。更棒的是，它还支持远程 URL：

{
  "$schema": "https://opencode.ai/config.json",
  "instructions": [
    "https://raw.githubusercontent.com/my-org/shared-rules/main/style.md"
  ]
}

远程指令文件会在启动时被获取（5 秒超时），所有指令文件会与 AGENTS.md 合并后一同加载。

引用外部文件的两种方式

当你希望将规则拆分到多个文件中管理时，有两种实现方式。

方式一：通过 opencode.json（推荐）

使用 instructions 字段集中管理所有规则文件，适合需要共享规则的团队项目：

{
  "$schema": "https://opencode.ai/config.json",
  "instructions": [
    "docs/development-standards.md",
    "test/testing-guidelines.md",
    "packages/*/AGENTS.md"
  ]
}

方式二：在 AGENTS.md 中手动指引

在 AGENTS.md 中明确告诉 AI 助手去读取哪些文件：

## 外部文件加载
重要：当遇到文件引用时（如 @rules/general.md），请使用 Read 工具按需加载。

## 开发指南
TypeScript 代码风格：@docs/typescript-guidelines.md
React 组件模式：@docs/react-patterns.md
API 设计规范：@docs/api-standards.md

这种方式的好处是可以实现按需加载，保持 AGENTS.md 简洁，同时让规则文件模块化、可复用。

最佳实践

提交 AGENTS.md 到版本控制：让整个团队共享同一套规则，新人加入时自动获得项目上下文

保持规则聚焦：只放 AI 助手真正需要知道的项目特有信息，通用知识不需要重复

定期运行 /init：项目结构变化后重新运行 /init 更新规则

善用全局规则：把你的个人编码偏好放在 ~/.config/opencode/AGENTS.md 中，不干扰团队规则

模块化管理：大型项目将规则拆分到多个文件中，通过 instructions 字段统一加载

总结

OpenCode 的 Rules 系统通过 AGENTS.md 和灵活的自定义指令机制，让 AI 编程助手能够深度理解项目上下文并遵循团队规范。无论是通过 /init 快速初始化，还是精细配置多文件规则体系，这套系统都能满足从个人项目到大型团队协作的各种需求。掌握 Rules 系统，是充分利用 OpenCode 能力的必修课。