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

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

引言

在使用 AI 编程助手时，你是否遇到过这样的困扰：让 AI 改代码，它却改错了方向；让它写测试，它又用了项目里不存在的框架；让它遵循项目规范，它总是"我行我素"。这些问题的根源在于——AI 不了解你的项目。

OpenCode 的规则系统（Rules）正是为解决这个问题而生。通过 AGENTS.md 文件，你可以为每个项目定制专属的 AI 行为规则，让 OpenCode 像熟悉项目的老队员一样工作。本文将全面介绍 OpenCode 规则系统的使用方法、最佳实践和高级技巧。

什么是 Rules

Rules 是 OpenCode 提供的一套自定义指令机制。你只需要在项目根目录创建一个 AGENTS.md 文件，OpenCode 就会在每次会话中自动加载其中的内容，将其作为系统提示的一部分注入给 LLM。这意味着你可以告诉 AI 你的项目结构、编码规范、测试命令等关键信息，让它的每一次响应都更贴合你的项目实际。

AGENTS.md 的作用类似于 Cursor 的 .cursorrules，但 OpenCode 提供了更灵活的层级结构和更丰富的引用机制。

快速上手：初始化 Rules

OpenCode 提供了 /init 命令来快速创建 AGENTS.md 文件。在项目目录中启动 OpenCode 后，运行：

/init

OpenCode 会自动扫描你的项目文件，分析项目结构、包管理器、构建工具等关键信息，然后生成一份量身定制的 AGENTS.md。如果项目存在 package.json、tsconfig.json、Dockerfile 等配置文件，/init 能智能提取其中的关键信息。

更贴心的是，/init 是幂等的——如果你已经有一个 AGENTS.md，它会在此基础上优化补充，而不是直接覆盖。你可以随时运行 /init 来更新规则，让 AI 始终掌握项目的最新状态。

AGENTS.md 的内容结构

一份典型的 AGENTS.md 应该包含以下内容：

# 项目名称与描述
这是一个基于 Next.js 14 的博客系统，使用 TypeScript 和 Prisma ORM。

## 项目结构
- `src/app/` - Next.js App Router 页面
- `src/components/` - 可复用 UI 组件
- `src/lib/` - 工具函数和数据访问层
- `prisma/` - 数据库 Schema 和迁移文件

## 构建与测试命令
- 开发：`npm run dev`
- 构建：`npm run build`
- 测试：`npm run test`
- Lint：`npm run lint`
- 类型检查：`npm run typecheck`

## 编码规范
- 使用函数组件和 Hooks，避免 class 组件
- API 路由统一放在 `src/app/api/` 下
- 数据库查询通过 Prisma Service 层封装
- 错误处理使用统一的 `ApiError` 类

## 项目约定
- 环境变量在 `.env.local` 中定义
- Tailwind CSS 用于样式，不使用 CSS Modules
- 使用 `zod` 进行表单验证
- 提交信息遵循 Conventional Commits 规范

这段规则包含了 AI 最需要的上下文：项目是什么、代码怎么组织、如何运行和验证、编码风格是什么。写好这些，AI 的工作质量会有质的提升。

规则的层级结构

OpenCode 支持多层级规则，你可以根据不同场景灵活配置。

项目级规则（Project Rules）

将 AGENTS.md 放在项目根目录，规则只在该项目及其子目录中生效。这是最常用的方式，适合为每个项目定制专属规则。

全局规则（Global Rules）

将 AGENTS.md 放在 ~/.config/opencode/ 目录下，规则会在所有 OpenCode 会话中生效。适合配置个人偏好，比如你希望 AI 始终使用中文回复、或者始终使用特定的代码风格。这个文件不会被提交到 Git，属于个人配置。

Claude Code 兼容规则

如果你从 Claude Code 迁移过来，OpenCode 提供了向下兼容支持：

• 项目级：使用 CLAUDE.md（如果没有 AGENTS.md）
• 全局级：使用 ~/.claude/CLAUDE.md（如果没有 ~/.config/opencode/AGENTS.md）

如果你不希望 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"
  ]
}

这个功能非常实用，比如你可以：

• 复用已有的 CONTRIBUTING.md 作为 AI 的协作指南
• 加载 docs/ 目录下的技术规范文档
• 支持 glob 模式匹配，批量加载规则文件
• 甚至支持远程 URL，从 GitHub 加载团队共享规则：

{
  "instructions": [
    "https://raw.githubusercontent.com/my-org/shared-rules/main/style.md"
  ]
}

远程文件会在 5 秒超时内获取，所有指令文件会与 AGENTS.md 合并后一起注入给 LLM。

引用外部文件的高级技巧

虽然 AGENTS.md 是核心规则文件，但将项目所有规范都塞进去会导致文件过于庞大。更好的做法是使用文件引用机制。

通过 opencode.json 的 instructions 字段是推荐方式。另一种方式是在 AGENTS.md 中明确告知 AI 如何读取外部文件：

## 外部文件加载
重要：当你遇到文件引用（如 @rules/general.md）时，请使用 Read 工具在需要时加载它们。这些文件与当前任务相关时才需要读取。

## 开发指南
- TypeScript 编码规范：@docs/typescript-guidelines.md
- React 组件设计模式：@docs/react-patterns.md
- API 设计与错误处理：@docs/api-standards.md
- 测试策略与覆盖率要求：@test/testing-guidelines.md

这种方式的优势在于：

• 规则文件模块化，方便维护
• 按需加载，避免上下文塞满不必要的信息
• 可通过 symlink 或 git submodule 跨项目共享规则

实战案例

案例一：Monorepo 项目

# SST v3 Monorepo
这是一个 SST v3 TypeScript monorepo，使用 bun workspaces 管理包。

## 项目结构
- `packages/` - 工作区包（functions、core、web 等）
- `infra/` - 按服务拆分的基础设施定义
- `sst.config.ts` - 主 SST 配置

## 包管理
- 添加依赖：`bun add <package>`
- 运行测试：`bun test`
- 部署：`npx sst deploy --stage production`

## 导入规范
- 共享模块使用 workspace 命名导入：`@my-app/core/example`
- 函数代码放在 `packages/functions/` 下
- 核心逻辑放在 `packages/core/` 下

案例二：Laravel 项目

# Laravel 10 电商系统
使用 PHP 8.2 + Laravel 10 + Livewire 构建。

## 目录结构
- `app/Models/` - Eloquent 模型
- `app/Http/Livewire/` - Livewire 组件
- `app/Services/` - 业务逻辑层
- `resources/views/` - Blade 模板

## 关键命令
- 启动开发服务器：`php artisan serve`
- 运行测试：`php artisan test`
- 代码格式化：`./vendor/bin/pint`
- 静态分析：`./vendor/bin/phpstan analyse`

## 编码约定
- 所有数据库操作通过 Model 或 Service 层，不在 Controller 中直接查询
- 表单验证使用 FormRequest 类
- Blade 组件使用 attribute 方式传递数据
- 队列任务使用 `app/Jobs/` 目录

有了这些规则，OpenCode 生成的代码会天然符合项目规范，不再需要反复修改。

最佳实践

1. 提交到版本控制

AGENTS.md 应该提交到 Git 仓库。它是项目文档的一部分，团队成员都能受益。这也是 OpenCode 团队强烈推荐的做法。

2. 定期更新

项目结构变化时，记得更新 AGENTS.md。可以定期运行 /init 命令，让 AI 帮你检测是否需要更新。

3. 保持简洁

规则不是越多越好。只包含 AI 无法从代码中自行推断的信息。比如项目特有的架构约定、非标准的构建流程、重要的脚本命令等。

4. 分层次管理

• 项目级 AGENTS.md：放团队共享的规则
• 全局级 AGENTS.md：放个人偏好
• opencode.json 的 instructions：引用外部文档

5. 善用 glob 模式

对于 monorepo 或有子包的项目，使用 glob 模式批量加载子包规则。例如 packages/*/AGENTS.md 会自动加载每个子包的规则文件。

总结

OpenCode 的规则系统是提升 AI 编程助手输出质量的关键工具。通过 AGENTS.md 文件，你可以让 AI 深度理解项目的结构、规范和约定，从而生成更准确、更符合项目风格的代码。

无论是个人项目还是团队协作，花 5 分钟写好规则文件，就能让 AI 的工作效率翻倍。从今天开始，为你的项目创建 AGENTS.md 吧！