AGENTS.md Guide: Configure OpenCode Like a Pro
By Tyler Cyert
If you're using OpenCode as your AI-powered coding assistant, the single most impactful thing you can do is set up an AGENTS.md file. This AGENTS.md guide walks you through the format, shows you a real-world example, and explains how to get the most out of your OpenCode configuration.
What Is AGENTS.md?
AGENTS.md is a markdown file that lives in your project's root directory. It tells OpenCode how to behave when it works on your codebase. Think of it as a system prompt that's version-controlled alongside your code.
Every time OpenCode starts a session, it reads your AGENTS.md and applies the instructions inside. Your preferences, coding standards, and project-specific context are loaded automatically — no copy-pasting prompts, no repeating yourself.
The AGENTS.md Format
The format is straightforward: standard markdown. No special syntax, no YAML frontmatter required. OpenCode parses the entire file and treats the contents as persistent instructions for the session.
What to Include
| Section | Purpose | Example |
|---|---|---|
| Project overview | What the project is, what stack it uses | "Next.js 15 app with Drizzle ORM and Postgres" |
| Architecture | Key directories, patterns, data flow | "All API routes live in src/app/api/" |
| Code style | Formatting, naming, import conventions | "Use named exports, avoid default exports" |
| Do / Don't rules | Explicit guardrails | "Never modify migration files directly" |
| Testing | How to run tests, what framework you use | "Run npm test — use Vitest" |
| Build & run | Commands for dev, build, deploy | "npm run dev starts on port 3000" |
A Practical Example
# Acme Dashboard
Full-stack TypeScript app using Next.js 15 (App Router), Drizzle ORM, and Postgres.
## Stack
- Next.js 15 with App Router
- TypeScript (strict mode)
- Tailwind CSS v4
- Drizzle ORM + PostgreSQL
## Architecture
- src/app/ — pages and API routes
- src/lib/ — shared utilities, database client
- src/components/ — React components by feature
- drizzle/ — generated migration SQL files (do not edit)
## Code Style
- Use @/ path alias for all imports from src/
- Named exports only — no default exports except pages
- Prefer server components
## Rules
- Never modify files in drizzle/ directly
- Do not install new packages without approval
- All database queries go through src/lib/db.ts
## Build & Run
- `npm run dev` — dev server on port 3000
- `npm run build` — production build
- `npm run db:push` — push schema changesAGENTS.md vs CLAUDE.md
Both files serve the same purpose — persistent instructions for an AI coding agent — but they belong to different tools.
| AGENTS.md | CLAUDE.md | |
|---|---|---|
| Used by | OpenCode | Claude Code |
| Location | Project root | Project root |
| Format | Markdown | Markdown |
| Loaded | Every session | Every session |
About 90% of the content transfers directly. The differences are mostly in tool-specific features: Claude Code supports hooks and permissions in a .claude/ directory, while OpenCode uses .opencode/ with commands and modes.
DotBox supports both formats — build once, export for either platform.
Tips
- Be specific. "Use TypeScript strict mode with no
anytypes" beats "Use TypeScript." - Include commands. Don't assume the agent knows how to run your tests.
- State what not to do. Guardrails prevent expensive mistakes.
- Keep it current. Update when your stack changes.
- Version control it. Commit to your repo so every contributor works from the same playbook.