OpenCode Rules 完整指南

概述

OpenCode的Rules功能通过创建AGENTS.md文件来提供自定义指令，类似于Cursor的规则。这些指令会包含在LLM的上下文中，用于定制特定项目的行为，让AI助手更好地理解项目需求和工作流程。

初始化

自动创建

运行/init命令自动扫描项目并生成AGENTS.md
建议将AGENTS.md文件提交到Git以便团队共享
如果文件已存在，会尝试添加内容而不是覆盖

支持的规则类型

1. 项目规则

位置：项目根目录的AGENTS.md
作用域：仅在该目录及其子目录中生效
共享性：通过Git与团队共享
适用场景：项目特定的编码标准、架构约定、工具配置等

2. 全局规则

位置：~/.config/opencode/AGENTS.md
作用域：所有OpenCode会话
用途：个人规则，不与团队共享
适用场景：个人编码偏好、工作习惯、常用工具配置等

3. Claude Code兼容性规则

OpenCode为从Claude Code迁移的用户提供无缝兼容：

类型	文件位置	使用条件
项目规则	`CLAUDE.md`	项目目录中，无`AGENTS.md`时使用
全局规则	`~/.claude/CLAUDE.md`	无`~/.config/opencode/AGENTS.md`时使用
技能	`~/.claude/skills/`	参见Agent Skills文档

禁用兼容性

可通过环境变量选择性禁用Claude Code兼容性：

bash 复制代码

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 → CONTEXT.md
全局文件 ：~/.config/opencode/AGENTS.md
Claude Code文件 ：~/.claude/CLAUDE.md（除非被禁用）

示例：如果同时有AGENTS.md和CLAUDE.md，只使用AGENTS.md。

自定义指令配置

使用opencode.json

可以通过opencode.json或全局配置文件指定自定义指令文件：

json 复制代码

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

远程指令支持

支持从远程URL加载指令，便于团队共享规则：

json 复制代码

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

注意事项：

远程指令获取超时时间：5秒
所有指令文件与AGENTS.md内容合并

引用外部文件

OpenCode提供两种方式引用外部文件，实现规则的模块化管理：

1. 使用opencode.json（推荐）

支持glob模式，特别适合复杂项目结构：

json 复制代码

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

2. 在AGENTS.md中手动指令

通过明确的加载指令实现按需加载：

markdown 复制代码

# TypeScript项目规则
## 外部文件加载
关键：遇到文件引用时，根据需要使用Read工具加载

指令：
- 不要预加载所有引用 - 基于实际需要懒加载
- 加载后的内容作为强制指令覆盖默认设置
- 必要时递归跟随引用

## 指导文档
对于TypeScript代码风格：@docs/typescript-guidelines.md
对于React组件架构：@docs/react-patterns.md
对于REST API设计：@docs/api-standards.md
对于测试策略：@test/testing-guidelines.md

## 通用指导
读取以下文件，与所有工作流程相关：@rules/general-guidelines.md

实际应用示例

完整的AGENTS.md结构示例

markdown 复制代码

# SST v3 Monorepo项目

这是使用bun工作区的SST v3 monorepo TypeScript项目。

## 项目结构
- `packages/` - 所有工作区包（functions, core, web等）
- `infra/` - 基础设施定义（storage.ts, api.ts, web.ts）
- `sst.config.ts` - 带动态导入的主SST配置

## 代码标准
- 使用TypeScript严格模式启用
- 共享代码放在`packages/core/`并配置适当的导出
- 函数放在`packages/functions/`
- 基础设施应按逻辑文件分割在`infra/`中

## Monorepo约定
- 使用工作区名导入共享模块：`@my-app/core/example`
- 遵循语义化版本控制
- 保持依赖项的版本一致性

最佳实践建议

Monorepo项目

使用opencode.json的glob模式（如packages/*/AGENTS.md）更易维护
通过符号链接或git子模块共享规则
为不同的包类型创建专门的规则模板

规则组织策略

保持AGENTS.md简洁，引用详细指导文档
创建模块化、可重用的规则文件
确保OpenCode仅在特定任务需要时加载文件

团队协作

将项目特定的AGENTS.md提交到版本控制
建立统一的规则模板和标准
定期审查和更新规则内容

迁移策略

对于从Claude Code迁移的团队：

保留现有的CLAUDE.md文件
逐步迁移到AGENTS.md格式
利用OpenCode的兼容性功能确保平滑过渡

高级功能

技能集成

OpenCode支持~/.claude/skills/目录中的技能定义
技能可以扩展AI助手的能力
支持自定义工具和工作流程

动态规则加载

支持基于项目类型的动态规则选择
可以根据文件类型、目录结构应用不同规则
支持条件规则应用

总结

OpenCode的Rules系统提供了强大而灵活的自定义指令管理功能，既支持个人定制，又便于团队协作。通过合理的规则组织和管理，可以显著提升AI辅助编程的效率和准确性。

该系统的核心优势包括：

层次化管理：支持项目、全局和兼容性规则
灵活性：多种配置方式和引用策略
向后兼容：平滑迁移路径
团队友好：易于共享和维护

掌握这些规则功能将帮助开发者构建更智能、更高效的AI辅助编程环境。