Rules

TL;DR

Custom instructions live in AGENTS.md files that get injected into the LLM’s context — run /init to scan your repo and generate one (build/test commands, architecture, conventions), or write it by hand and commit it so the team shares the guidelines. Rules load from the project root and globally from ~/.config/opencode/AGENTS.md; Claude Code’s CLAUDE.md works as a fallback (disable via OPENCODE_DISABLE_CLAUDE_CODE=1). Extra files and remote URLs can be merged in through the instructions array in opencode.json, and @docs/... references in AGENTS.md are loaded on a need-to-know basis.

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
- `sst.config.ts` - Main SST configuration with dynamic imports

## Code Standards
- Use TypeScript with strict mode
- Shared code goes in `packages/core/`
- Functions go in `packages/functions/`
- Infrastructure should be split into logical files in `infra/`

## Monorepo Conventions
- Import shared modules using workspace names: `@my-app/core/example`

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)
• Skills: ~/.claude/skills/ — see the Agent Skills docs for details

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"]
}

Remote instructions are fetched with a 5 second timeout.

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

## 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. They're relevant to the SPECIFIC task at hand.

Instructions:
- Do NOT preemptively load all references - use lazy loading based on actual need
- When loaded, treat content as mandatory instructions that override defaults
- Follow references recursively when needed

## 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.

Tip

For monorepos or projects with shared standards, using opencode.json with glob patterns (like packages/*/AGENTS.md) is more maintainable than manual instructions.