Skip to main content

Rules

tip

Well-crafted rules help the agent understand your project's unique conventions and constraints.

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​

Claude Code Compatibility​

CLAUDE.md Fallback​

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​

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​

tip

A focused AGENTS.md helps the agent quickly find relevant instructions without noise.

Reference, Do Not Duplicate​

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​