概述
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兼容性：
exportOPENCODE_DISABLE_CLAUDE_CODE=1# 禁用所有.claude支持exportOPENCODE_DISABLE_CLAUDE_CODE_PROMPT=1# 仅禁用~/.claude/CLAUDE.mdexportOPENCODE_DISABLE_CLAUDE_CODE_SKILLS=1# 仅禁用.claude/skills优先级规则
OpenCode启动时按以下顺序查找规则文件（每个类别中第一个匹配的文件获胜）：
本地文件：从当前目录向上遍历
AGENTS.md→CLAUDE.md→CONTEXT.md
全局文件：
~/.config/opencode/AGENTS.mdClaude Code文件：
~/.claude/CLAUDE.md（除非被禁用）
示例：如果同时有AGENTS.md和CLAUDE.md，只使用AGENTS.md。
自定义指令配置
使用opencode.json
可以通过opencode.json或全局配置文件指定自定义指令文件：
{"$schema":"https://opencode.ai/config.json","instructions":["CONTRIBUTING.md","docs/guidelines.md",".cursor/rules/*.md"]}远程指令支持
支持从远程URL加载指令，便于团队共享规则：
{"$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模式，特别适合复杂项目结构：
{"$schema":"https://opencode.ai/config.json","instructions":["docs/development-standards.md","test/testing-guidelines.md","packages/*/AGENTS.md"]}2. 在AGENTS.md中手动指令
通过明确的加载指令实现按需加载：
# 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结构示例
# 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辅助编程环境。
