Rules

OpenCode allows you to provide custom instructions through an AGENTS.md file, similar to Cursor’s rules. These instructions are included in the LLM’s context to customize behavior for your specific project.

Tip

You should commit your project’s AGENTS.md file to Git so your team can benefit from shared guidelines.

Initialize

To create a new AGENTS.md file, run the /init command in OpenCode:

/init

/init scans important files in your repo and may ask targeted questions when the codebase cannot answer them, then creates or updates AGENTS.md with concise project-specific guidance.

It focuses on what future agent sessions most likely need:

• Build, lint, and test commands
• Command order and focused verification steps
• Architecture and repo structure not obvious from filenames
• Project-specific conventions, setup quirks, and operational gotchas
• References to existing instruction sources like Cursor or Copilot rules

If you already have an AGENTS.md, /init will improve it in place.

Example

You can also create this file manually. Here’s an example:

# SST v3 Monorepo Project

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

## Project Structure
- `packages/` - All workspace packages
- `infra/` - Infrastructure definitions

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

Types

OpenCode supports reading AGENTS.md from multiple locations for different purposes.

Project

Place an AGENTS.md in your project root for project-specific rules. These only apply in that directory or its sub-directories.

Global

You can also have global rules in ~/.config/opencode/AGENTS.md. This applies across all OpenCode sessions. Use this for personal rules since it’s not committed to Git.

Claude Code Compatibility

For users migrating from Claude Code, OpenCode supports Claude Code’s file conventions as fallbacks:

• Project rules: CLAUDE.md in your project directory (used if no AGENTS.md exists)
• Global rules: ~/.claude/CLAUDE.md (used if no ~/.config/opencode/AGENTS.md exists)

To disable Claude Code compatibility:

export OPENCODE_DISABLE_CLAUDE_CODE=1        # Disable all .claude support
export OPENCODE_DISABLE_CLAUDE_CODE_PROMPT=1 # Disable only ~/.claude/CLAUDE.md
export OPENCODE_DISABLE_CLAUDE_CODE_SKILLS=1 # Disable only .claude/skills

Precedence

When OpenCode starts, it looks for rule files in this order:

1. Local files by traversing up from current directory (AGENTS.md, then CLAUDE.md)
2. Global file at ~/.config/opencode/AGENTS.md
3. Claude Code file at ~/.claude/CLAUDE.md (unless disabled)

The first matching file wins in each category.

Custom Instructions

You can specify custom instruction files in your opencode.json:

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

You can also use remote URLs:

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

All instruction files are combined with your AGENTS.md files.

Referencing External Files

While OpenCode doesn’t automatically parse file references in AGENTS.md, you can achieve this in two ways:

Using opencode.json

The recommended approach uses the instructions field in opencode.json:

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

Manual Instructions in AGENTS.md

You can teach OpenCode to read external files by providing explicit instructions:

# TypeScript Project Rules

## Development Guidelines
For TypeScript code style: @docs/typescript-guidelines.md
For React patterns: @docs/react-patterns.md

OpenCode loads files on a need-to-know basis rather than preemptively.