OpenCode Rules (AGENTS.md)

In OpenCode,Rules are the core mechanism for controlling AI behavior.。

We can, viaAGENTS.mdthe file, provide custom instructions to OpenCode, letting it develop according to your project standards.

Tools determine what AI can do; AGENTS.md determines how AI should do it.

AGENTS.md = Setting team development standards for AI.

1. What is AGENTS.md

AGENTS.mdIt is a rules file, used for:

  • Defining project structure
  • Enforcing code style
  • Standardizing development workflow
  • Guiding AI on how to execute tasks

This content will be added to the LLM context.

Effects:

  • AI understands your project better
  • Generated code better conforms to specifications
  • Reduces repeated revisions

2. Quick Initialization

Run in OpenCode:

/init

This command will:

  • Scan your project structure
  • Analyze code organization
  • Automatically generate AGENTS.md

Recommendation:

  • Commit AGENTS.md to Git
  • As a unified team standard

3. Example Structure

# 项目说明

这是一个基于 TypeScript 的 monorepo 项目。

## 项目结构

- packages/ 核心模块
- infra/ 基础设施
- web/ 前端应用

## 代码规范

- 使用 TypeScript 严格模式
- 公共代码放在 packages/core
- 所有函数必须添加注释

## 开发约定

- 使用 workspace 方式引用模块
- API 必须统一错误处理

Essence: Write team standards "for AI to see"

4. Scope of Rules

1. Project-level Rules

Path:

./AGENTS.md

Effect:

  • Applies only to the current project
  • Shared by the team

2. Global Rules

Path:

~/.config/opencode/AGENTS.md

Effect:

  • Applies to all projects
  • Personal use

Suggested uses:

  • Personal coding habits
  • Output style control

5. Claude Code Compatibility

OpenCode is compatible with Claude Code's rules system:

  • Project rules: CLAUDE.md
  • Global rules: ~/.claude/CLAUDE.md
  • Skills directory: ~/.claude/skills/

If you don't want to use it, you can disable it:

export OPENCODE_DISABLE_CLAUDE_CODE=1

6. Rule Loading Priority (Important)

OpenCode loads rules in the following order at startup:

  1. Search upward from the current directory for AGENTS.md
  2. If not found → look for CLAUDE.md
  3. Global rules ~/.config/opencode/AGENTS.md
  4. Claude global rules ~/.claude/CLAUDE.md

Key points:

  • AGENTS.md has the highest priority
  • At the same level, only the first matching file is used

7. Extended Rules (instructions)

You canopencode.jsonload additional rule files from:

{
  "instructions": [
    "CONTRIBUTING.md",
    "docs/guidelines.md",
    ".cursor/rules/*.md"
  ]
}

Advantages:

  • Reuse existing documentation
  • Avoid duplicate maintenance

Supports remote rules

{
  "instructions": [
    "https://raw.githubusercontent.com/xxx/rules/main/style.md"
  ]
}

Note:

  • URL loading supported
  • Timeout: 5 seconds

8. Modular Rules (Advanced)

Recommended method (using instructions)

{
  "instructions": [
    "docs/dev.md",
    "test/rules.md",
    "packages/*/AGENTS.md"
  ]
}

Suitable for:

  • monorepo
  • Large projects

Method 2: Manually reference in AGENTS.md

# 规则加载说明

当遇到 @xxx 文件时，请使用 read 工具加载。

- 不要一次性加载全部文件
- 按需加载
- 加载后必须遵守

Example:

TypeScript 规范：@docs/typescript.md
React 规范：@docs/react.md
API 规范：@docs/api.md

Implement "load rules on demand"

9. Best Practices (Key Points)

1. Rules should be specific

❌ Don't write:

The code should follow standard conventions.

✅ You should write:

所有函数必须添加 JSDoc 注释

2. Rules should be executable

AI can only execute explicit rules, not abstract descriptions.

3. Don't make them too long

Suggestion:

  • Write core rules in AGENTS.md
  • Break detailed rules out into instructions files

4. Maintained uniformly by the team

  • Put under Git management
  • As part of development standards
Other extensions