Skip to main content

Rules

Rules are instruction files that shape agent behavior, enforce project conventions, and provide contextual guidance. opencode supports multiple rule sources that compose together into a unified instruction set for every session.

The AGENTS.md File​

The primary mechanism for project-specific instructions is AGENTS.md at the project root. This file is loaded automatically at the start of every session and its contents are included in the system prompt.

Creating AGENTS.md with /init​

The /init command scaffolds a comprehensive AGENTS.md file by analyzing your project and asking targeted questions.

Run it from the project root:

opencode /init

The /init workflow:

  1. Scans the project – Detects languages, frameworks, build tools, test runners, and project structure.
  2. Asks questions – Prompts you about architecture decisions, coding conventions, testing requirements, and deployment constraints.
  3. Generates AGENTS.md – Produces a structured instruction file with the collected information.

Questions /init Asks​

The /init command focuses on these areas:

  • Build commands – What commands compile, bundle, or transpile the project.
  • Lint and format commands – What tools enforce code quality and style.
  • Test commands – How to run unit tests, integration tests, and end-to-end tests.
  • Architecture – High-level structure, design patterns, and key modules.
  • Conventions – Naming rules, import styles, error handling patterns, and preferred APIs.
  • Gotchas – Known pitfalls, legacy code concerns, and environment-specific issues.

Example AGENTS.md​

# Project: web-platform

## Build & Development
- Build: `npm run build`
- Dev: `npm run dev`
- Lint: `npm run lint`
- Test (unit): `npm run test -- --run`
- Test (e2e): `npm run test:e2e`
- Type check: `npm run typecheck`

## Architecture
- Monorepo with apps/web and packages/*
- apps/web: Next.js 14 App Router
- packages/ui: Shared React component library (shadcn/ui)
- packages/api: tRPC router definitions
- packages/db: Drizzle ORM schema and migrations
- State management: React Query for server state, Zustand for client state
- Auth: NextAuth.js with GitHub and Google providers

## Coding Conventions
- TypeScript strict mode, no `any` unless absolutely necessary
- React components use named exports, not default exports
- CSS uses Tailwind utility classes; avoid inline styles
- Error boundaries at each route group level
- API routes validate input with Zod schemas
- Database migrations are irreversible; always create new migrations

## Testing
- Vitest for unit and integration tests
- Playwright for e2e tests
- Test files co-located with source files as *.test.ts
- Mock external services with MSW handlers

## Gotchas
- The `packages/db` schema file is auto-generated; do not edit directly
- Environment variables are validated at build time in `env.ts`
- The payment webhook endpoint must remain idempotent
- PRs targeting `main` require all CI checks to pass

Types of Rules​

Project Rules​

Placed at the root of your project as AGENTS.md. These instructions are scoped to the current repository and are loaded whenever you start a session in that project.

Global Rules​

Placed at ~/.config/opencode/AGENTS.md. These instructions apply to every session across all projects. Global rules are useful for personal preferences, universal conventions, and cross-project standards.

Custom Instructions via opencode.json​

The instructions field in opencode.json references additional instruction files:

{
  "instructions": [
    "CONTRIBUTING.md",
    "docs/guidelines.md",
    "docs/architecture.md",
    "docs/deployment.md",
    "docs/testing-strategy.md",
    ".cursor/rules/*.md",
    ".github/CODE_OF_CONDUCT.md"
  ]
}

Instruction files can be:

  • Local paths – Relative to the project root.
  • Glob patterns – docs/rules/*.md includes every Markdown file in that directory.
  • Remote URLs – Fetched over HTTP with a 5-second timeout.

Remote Instruction URLs​

Remote instructions are useful for organization-wide standards hosted on an internal wiki or GitHub:

{
  "instructions": [
    "https://raw.githubusercontent.com/org/engineering/main/docs/coding-standards.md"
  ]
}

Remote files are fetched with a 5-second timeout. If the fetch fails, the instruction is silently skipped and the session continues.

Lazy Loading​

External instruction files are loaded lazily. The contents are fetched and injected into the system prompt only when the agent begins its work, not at session startup. This keeps session initialization fast even with many instruction files.

Claude Code Compatibility​

opencode maintains compatibility with Claude Code's rule system for users migrating between tools.

CLAUDE.md Fallback​

If no AGENTS.md exists in the project root but CLAUDE.md does, opencode falls back to CLAUDE.md automatically. Similarly, if no ~/.config/opencode/AGENTS.md exists, opencode checks ~/.claude/CLAUDE.md.

Precedence​

When multiple rule sources exist, they are applied in this order:

  1. Project AGENTS.md – Highest precedence for project-specific rules.
  2. Project CLAUDE.md – Used only when AGENTS.md is absent.
  3. Global AGENTS.md (~/.config/opencode/AGENTS.md) – Personal preferences and cross-project rules.
  4. Global CLAUDE.md (~/.claude/CLAUDE.md) – Used only when the global AGENTS.md is absent.

All matched files are loaded and composed together. None replaces another; the agent receives instructions from every available source.

Disabling Claude Code Compatibility​

Set one of these environment variables to prevent opencode from reading Claude Code configuration files:

export OPENCODE_DISABLE_CLAUDE_CODE=true
export OPENCODE_DISABLE_CLAUDE_CODE=1

When set, opencode ignores CLAUDE.md and ~/.claude/CLAUDE.md entirely.

Referencing Files Inside AGENTS.md​

You can reference external files from within AGENTS.md using Markdown links and @file patterns. The agent reads these files and incorporates their content into its context.

## Reference Documents

See @docs/api-contracts.md for endpoint specifications.
See @CONTRIBUTING.md for the PR workflow.
See @packages/shared/src/constants.ts for shared enum definitions.

The @file syntax creates a direct reference that the agent resolves when loading instructions.

Best Practices​

Keep AGENTS.md Focused​

Include only information that is relevant to an AI agent working on the codebase. Omit onboarding instructions, team norms, and HR policies that do not affect code generation.

Reference, Do Not Duplicate​

Use the instructions field in opencode.json to reference existing documentation rather than duplicating content in AGENTS.md. This keeps the rule set maintainable as documentation evolves.

Structure by Category​

Organize AGENTS.md with clear sections so the agent can efficiently locate relevant instructions:

## Build & Dev Commands
## Architecture
## Coding Conventions
## Testing Requirements
## Deployment
## Security Constraints
## Gotchas

Review and Update​

Treat AGENTS.md as a living document. Update it when:

  • Build or test commands change.
  • New architectural patterns are adopted.
  • Significant gotchas are discovered.
  • Dependencies are added or removed.