💻 OpenCode

OpenCode Rule 使用教程

在使用 OpenCode 进行 AI 辅助编程时，默认行为往往难以匹配不同项目的技术栈、编码规范与协作要求。为此 OpenCode 推出 Rule（规则）体系，开发者可通过 AGENTS.md 规则文件自定义 LLM 行为，将项目约束、开发规范、架构说明等内容注入对话上下文，让 AI 深度适配当前项目。该功能对标 Cursor 规则体系，同时兼容 Claude Code 规则文件，支持项目级、全局两级配置，还可扩展加载本地 / 远程指令文件，是团队统一 AI 编码风格、提升协作效率的核心功能。

本文将从零讲解 OpenCode Rule 的核心概念、规则文件创建、分级配置、加载优先级、Claude Code 兼容设置、外部指令引用以及实战案例与最佳实践，帮助个人开发者与团队快速落地规则配置。

一、核心概念：规则文件概述

OpenCode 的规则本质是自定义指令集合，所有指令会被加载至 LLM 运行上下文，约束 AI 的编码逻辑、文件操作、命令执行等行为。核心载体为 AGENTS.md，同时兼容传统的 CLAUDE.md 文件。

规则文件分为两大使用维度：

项目级规则：作用于单个项目，由团队共享，统一项目内 AI 行为；
全局级规则：作用于本机所有 OpenCode 会话，多用于配置个人编码习惯、通用要求。

规则支持纯手动编写、命令自动生成、外部文件引用、远程指令加载等多种创建方式，灵活性极高，适配单体项目、多仓库 Monorepo、大型团队等各类场景。

二、规则文件快速创建与初始化

AGENTS.md 是 OpenCode 规则的核心文件，提供命令自动生成和手动创建两种方式，推荐优先使用命令初始化，减少基础配置工作量。

2.1 命令自动初始化（推荐）

借助 OpenCode TUI 内置的 /init 命令，可自动扫描项目目录、技术栈、文件结构，智能生成 AGENTS.md 基础内容；若项目已存在该文件，命令会在原有内容基础上补充优化。

启动 OpenCode TUI：

opencode

在交互界面中执行初始化命令：

/init

补充说明

生成的 AGENTS.md 会放置在项目根目录；
团队协作场景下，务必将该文件提交至 Git 仓库，保证所有成员使用同一套项目规则；
命令仅生成基础框架，开发者需根据项目实际补充编码规范、目录约束等细节。

2.2 手动创建规则文件

若需从零定制规则，可直接在对应目录新建 AGENTS.md 文件，使用标准 Markdown 语法编写指令，无特殊语法限制，文本内容会完整作为指令传入 LLM。

# 进入项目根目录，手动创建项目级规则文件
touch AGENTS.md

# 进入全局配置目录，手动创建全局规则文件
mkdir -p ~/.config/opencode && touch ~/.config/opencode/AGENTS.md

三、规则文件分级与生效范围

OpenCode 区分项目级和全局级两类规则文件，同时兼容 Claude Code 旧版规则文件，不同文件拥有独立存放路径、生效范围与使用场景，下面分类详解。

3.1 项目级规则文件

文件路径：项目根目录 AGENTS.md
生效范围：仅在当前项目及所有子目录启动的 OpenCode 会话生效
使用场景：定义项目专属架构、编码规范、目录权限、项目命令、已知问题等，是团队协作的核心规则文件。
协作要求：必须纳入 Git 版本控制，保证团队所有成员规则统一。

3.2 全局级规则文件

文件路径：~/.config/opencode/AGENTS.md（Linux / macOS）
生效范围：本机所有 OpenCode 会话，不受项目目录限制
使用场景：配置个人通用编码习惯、全局禁用行为、通用工具使用规范等个人专属规则。
协作要求：该文件仅保存在本地，不提交 Git，仅作用于当前设备。

3.3 Claude Code 兼容规则文件

为方便从 Claude Code 迁移的用户，OpenCode 原生兼容 Claude Code 的规则文件与技能文件，作为降级方案使用：

项目降级规则：项目根目录 CLAUDE.md（项目无 AGENTS.md 时自动启用）
全局降级规则：~/.claude/CLAUDE.md（全局无 ~/.config/opencode/AGENTS.md 时自动启用）
技能文件兼容：~/.claude/skills/ 目录下的技能文件可正常加载

3.4 关闭 Claude Code 兼容功能

若无需兼容 Claude Code，可通过环境变量关闭对应能力，分为全量关闭、单独关闭规则 / 技能兼容三类配置：

3.4.1 临时生效（当前终端会话）

# 关闭所有 Claude Code 兼容能力（规则 + 技能）
export OPENCODE_DISABLE_CLAUDE_CODE=1

# 仅关闭全局 ~/.claude/CLAUDE.md 规则兼容
export OPENCODE_DISABLE_CLAUDE_CODE_PROMPT=1

# 仅关闭 ~/.claude/skills 技能文件兼容
export OPENCODE_DISABLE_CLAUDE_CODE_SKILLS=1

3.4.2 永久生效

将上述环境变量写入 Shell 配置文件（~/.bashrc、~/.zshrc 等），执行 source 命令刷新后永久生效。

四、规则文件加载优先级

当本地同时存在多份规则文件时，OpenCode 会按照固定顺序检索、加载规则，匹配到第一个有效文件后停止检索，优先级从高到低如下：

本地项目目录遍历：从当前目录向上逐级查找 AGENTS.md，优先于同目录下的 CLAUDE.md；
OpenCode 全局规则：加载 ~/.config/opencode/AGENTS.md；
Claude 全局降级规则：加载 ~/.claude/CLAUDE.md（已关闭兼容则跳过）。

举例说明：

项目根目录同时存在 AGENTS.md 和 CLAUDE.md：仅加载 AGENTS.md；
项目无任何规则文件，本机存在两份全局规则：优先加载 ~/.config/opencode/AGENTS.md；
关闭 Claude 兼容后：系统会直接跳过 CLAUDE.md 相关文件检索。

五、[AGENTS.md](AGENTS.md) 编写规范与实战示例

AGENTS.md 采用标准 Markdown 格式，内容无强制语法，建议按照「项目介绍 → 目录结构 → 技术栈 → 编码规范 → 常用命令 → 约束要求」的结构编写，提升可读性与实用性。以下提供多场景可直接复用的实战模板。

5.1 通用基础模板（适用于绝大多数项目）

# 项目全局规则
## 一、项目概述
简述项目用途、技术定位、核心业务。

## 二、目录结构约定
- `src/`：核心源码目录（允许修改）
- `public/`：静态资源目录（仅新增文件，不修改原有内容）
- `config/`：项目配置文件（修改前必须确认）
- `tests/`：单元测试目录，代码变更必须同步更新测试用例

## 三、技术栈规范
- 编程语言：TypeScript 5.0+
- 框架：React 18 + Vite
- 代码检查：ESLint + Prettier
- 禁止使用废弃 API 和实验性功能。

## 四、编码规则
1. 组件统一使用函数式组件，禁止类组件；
2. 所有变量、函数必须补充 TypeScript 类型定义；
3. 注释使用 JSDoc 规范，公共函数必须编写注释。

## 五、常用开发命令
- 本地启动：npm run dev
- 代码格式化：npm run format
- 单元测试：npm run test
- 生产打包：npm run build

## 六、风险约束
1. 禁止直接删除目录与核心配置文件；
2. 修改数据库相关代码必须额外说明风险；
3. 遇到未知问题优先输出排查思路，而非直接修改代码。

5.2 Monorepo 多仓库项目示例

针对 PNPM / Bun 管理的 Monorepo 项目，重点补充分包规则、导入规范：

# SST v3 Monorepo 项目规则
## 项目说明
基于 TypeScript + Bun Workspaces 构建的 Monorepo 全栈项目，使用 SST 做云服务编排。

## 目录结构
- `packages/`：所有业务分包（functions、core、web）
- `infra/`：云服务基础设施配置（按服务拆分文件）
- `sst.config.ts`：项目主配置文件

## 代码标准
1. 全局启用 TypeScript Strict 严格模式；
2. 公共通用代码统一存放至 `packages/core`；
3. 后端函数代码统一存放至 `packages/functions`；
4. 基础设施配置拆分至 `infra` 下独立文件。

## 导入规范
跨分包导入必须使用工作空间别名：@my-app/core/xxx，禁止相对路径跨包引用。

5.3 后端 Java 项目示例

# Java SpringBoot 项目规则
## 技术栈
Java 17 + SpringBoot 3.2 + MyBatis-Plus + MySQL

## 目录约束
- `controller`：接口层，仅处理参数接收与响应返回
- `service`：业务逻辑层，核心代码存放目录
- `mapper` / `entity`：数据库映射层，禁止随意修改表结构

## 编码规范
1. 接口返回统一使用全局 Result 封装类；
2. SQL 语句禁止写在代码中，统一存放至 XML 映射文件；
3. 新增接口必须补充接口注释与参数说明。

## 操作约束
1. 修改数据库字段前，先输出 SQL 变更语句；
2. 生产环境相关配置禁止直接修改。

六、自定义指令扩展（instructions 配置）

当规则内容较多、需要模块化管理，或是需要复用团队公共规则时，可通过 opencode.json 配置文件中的 instructions 字段，批量加载本地文件、通配符目录、远程网络文件，所有加载的指令会自动与 AGENTS.md 内容合并生效。该功能是大型项目、团队公共规则复用的最佳方案。

6.1 基础配置语法

在项目根目录或全局配置 ~/.config/opencode/opencode.json 中添加 instructions 数组，支持三种资源类型：本地单独文件、Glob 通配符目录、远程 HTTP 链接。

补充说明：远程指令文件获取超时时间为 5 秒，网络不佳时建议优先使用本地文件。

6.2 实战配置示例

6.2.1 加载多个本地规则文件

加载项目内开发规范、贡献指南等文档作为补充指令：

{
  "$schema": "https://opencode.ai/config.json",
  "instructions": [
    "CONTRIBUTING.md",
    "docs/development-guidelines.md",
    "docs/api-standard.md"
  ]
}

6.2.2 使用 Glob 通配符批量加载（Monorepo 推荐）

匹配指定目录下所有规则文件，无需逐个手动填写路径，适配多分包项目：

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

6.2.3 加载远程公共规则文件

从团队 Git 仓库加载公共编码规范，实现全团队规则统一更新：

{
  "$schema": "https://opencode.ai/config.json",
  "instructions": [
    "https://raw.githubusercontent.com/team-name/public-rules/main/ts-standard.md"
  ]
}

# TypeScript 项目主规则
## 外部文件加载规则
重要约束：
1. 遇到 @xxx 格式的文件引用时，按需使用 Read 工具加载对应文件；
2. 禁止提前加载所有引用文件，采用懒加载模式；
3. 被引用文件内容优先级高于当前文件默认规则；
4. 支持递归读取多层引用文件。

## 专项规范引用
1. TypeScript 编码规范：@docs/typescript-rules.md
2. React 组件规范：@docs/react-pattern.md
3. 接口设计规范：@docs/api-rules.md
4. 通用基础规范：@rules/base-guideline.md