OpenCode 规则与指令系统完全指南：用 AGENTS.md 和 instructions 智控 AI 编程助手

OpenCode 规则与指令系统完全指南：用 AGENTS.md 和 instructions 智控 AI 编程助手

引言

使用 AI 编程助手时，最让人困扰的问题莫过于它不了解你的项目规范和编码习惯。每次都要反复提醒"用 TypeScript 严格模式"、"遵循项目的命名规范"、"测试要覆盖边界情况"，既浪费时间又容易遗漏。OpenCode 的规则与指令系统就是为了解决这个问题而设计的。通过 AGENTS.md、全局规则和 instructions 配置，你可以让 AI 助手自动理解项目的所有约定，无需重复解释。本文将全面介绍 OpenCode 规则系统的工作原理和最佳实践。

什么是 OpenCode 规则系统

OpenCode 的规则系统是一套层次化的指令注入机制，它将你定义的项目规范、编码标准和工作流程注入到 AI 模型的上文（context）中，让模型从一开始就了解项目的上下文和约束条件。规则文件通常使用 Markdown 格式编写，支持从多个来源加载并按优先级合并。

规则系统由三个核心部分组成：

• AGENTS.md 文件 — 项目级别的规则，通常提交到 Git 仓库中与团队共享
• 全局规则文件 — 存放在 ~/.config/opencode/AGENTS.md，属于个人偏好设置
• instructions 配置项 — 在 opencode.json 中通过指令数组引用外部规则文件

初始化项目规则：/init 命令

在项目根目录运行 OpenCode 后，第一步应该是执行 /init 命令：

/init

该命令会自动扫描项目中的重要文件，分析项目结构、构建工具、依赖管理方式等，然后生成或更新 AGENTS.md 文件。/init 会重点关注以下信息：

• 构建、代码检查和测试命令
• 命令的执行顺序和关键的验证步骤
• 架构和仓库结构中不易从文件名看出的信息
• 项目特有的约定、配置中的特殊情况和操作经验
• 对已有 Cursor 或 Copilot 规则文件的引用

例如，一个 TypeScript 项目的 AGENTS.md 可能包含如下内容：

# SST v3 Monorepo Project
This is an SST v3 monorepo with TypeScript. The project uses bun workspaces.

## Project Structure
- `packages/` - Contains all workspace packages (functions, core, web, etc.)
- `infra/` - Infrastructure definitions split by service (storage.ts, api.ts, web.ts)

## Code Standards
- Use TypeScript with strict mode enabled
- Shared code goes in `packages/core/`
- Functions go in `packages/functions/`

你 .gitignore 这个文件，并提交到 Git 仓库中，这样整个团队都能共享这些规则。

规则文件的位置与类型

OpenCode 支持从多个位置加载规则文件，每个位置有不同的用途和优先级。

项目规则

在项目根目录放置 AGENTS.md 文件。这些规则仅在你在此目录或其子目录下工作时生效，适合存放项目特有的规范和约定。这是最常用的规则类型。

全局规则

在 ~/.config/opencode/AGENTS.md 存放全局规则，这些规则会应用到所有 OpenCode 会话中。由于全局规则不会提交到 Git 仓库，建议用于存放个人偏好的规则，例如：

• 个人偏好的代码风格
• 常用的工具链配置
• 特定语言的个人最佳实践

Claude Code 兼容规则

如果你是从 Claude Code 迁移过来的用户，OpenCode 自动支持 Claude Code 的文件约定作为后备规则：

• 项目规则：项目目录下的 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。

自定义指令系统：instructions 配置

除了 AGENTS.md，OpenCode 还提供了一种更灵活的方式来注入规则：通过 opencode.json 中的 instructions 配置项。

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

instructions 接受一个包含文件路径和 Glob 模式的数组。这些文件会被自动读取并合并到 AI 模型的上下文中。支持以下类型的引用：

本地文件路径

路径相对于项目根目录，可以是单个文件或使用 Glob 模式匹配多个文件：

{
  "instructions": [
    "docs/development-standards.md",
    "test/testing-guidelines.md",
    "packages/*/AGENTS.md"
  ]
}

使用 Glob 模式时，所有匹配的文件都会被加载。这对于微前端或 monorepo 架构特别有用——你可以让每个子包都有自己的 AGENTS.md，然后通过 packages/*/AGENTS.md 一次性加载所有子包的规则。

远程 URL

OpenCode 也支持从远程 URL 加载规则文件：

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

远程指令会在 5 秒超时内完成拉取。这适合跨项目共享团队规范，只需要在一个中央仓库维护规则文件即可。

全局 instructions

你也可以将 instructions 配置在全局配置 ~/.config/opencode/opencode.json 中，这样所有项目都会加载这些自定义指令：

{
  "instructions": [
    "~/.config/opencode/my-global-rules.md"
  ]
}

~ 开头的路径指向用户主目录，可以引用全局目录下的规则文件。

在 AGENTS.md 中引用外部文件

如果你不想使用 opencode.json 配置，也可以在 AGENTS.md 中通过指令告诉 AI 在需要时读取外部文件：

# TypeScript Project Rules

## External File Loading
CRITICAL: When you encounter a file reference (e.g., @rules/general.md),
use your Read tool to load it on a need-to-know basis.

## Development Guidelines
For TypeScript code style: @docs/typescript-guidelines.md
For React component architecture: @docs/react-patterns.md
For testing strategies: @test/testing-guidelines.md

这种方式的优点是 AGENTS.md 保持简洁，而详细规则放在各自独立的文件中。AI 会根据实际任务按需加载相关文件，而不是一次性加载所有规则。

规则系统的最佳实践

1. 分层设计规则

将规则分为三个层次：

• 项目通用规则（AGENTS.md）— 构建命令、架构概览、命名约定
• 领域特定规则（instructions 引用）— API 设计规范、测试策略、数据库操作规范
• 个人偏好规则（全局 AGENTS.md）— 编辑器配置、个人编码风格

2. 保持规则文件简洁

每个规则文件聚焦一个主题，避免大而全的"万能规则"。这有助于 AI 准确理解和使用规则，也方便维护。

3. 为 monorepo 使用 Glob 模式

如果你在 monorepo 中工作，在每个子包中维护自己的 AGENTS.md，然后在根 opencode.json 中配置：

{
  "instructions": ["packages/*/AGENTS.md"]
}

这样 AI 在任何子包中工作时都能自动加载对应的规则。

4. 定期更新规则

使用 /init 命令定期重新生成 AGENTS.md，确保规则与项目实际状态保持一致。特别是当项目依赖、构建工具或目录结构发生变化时。

5. 将规则纳入代码审查

将 AGENTS.md 和指令文件的变更纳入代码审查流程。规则文件的质量直接影响 AI 助手的工作效果，值得团队花时间共同维护。

总结

OpenCode 的规则与指令系统是一个强大而灵活的机制，让你能够精确控制 AI 编程助手的行为。通过合理配置 AGENTS.md、全局规则和 instructions，你可以让 AI 自动理解项目的编码规范、架构约定和工作流程，无需重复解释和提示。

无论是个人开发者还是团队协作，建议从 /init 开始初始化项目规则，再根据实际需求逐步补充和完善。规则系统写得好，AI 助手才能真正成为得力的编程伙伴。