The AGENTS.md File: The One Trick That Makes Every Coding Agent 10x Smarter

Every coding agent — Claude Code, OpenCode, Codex CLI, pi.dev, Hermes, even Cursor — shares one feature that most beginners ignore: AGENTS.md.

It’s a single markdown file you drop in your project root. And it’s the difference between an agent that vaguely understands your code and one that builds exactly what you want, the way you want it.

Here’s what it is, why it works, and how to write one in 10 minutes.

What Is AGENTS.md?

AGENTS.md is a plain-text instruction file that your coding agent reads before it touches a single file. Think of it as a briefing document you hand a new teammate on day one.

Without it, your agent flies blind. It guesses your coding style, your test framework, your folder conventions. Sometimes it guesses right. Often it doesn’t.

With it, you tell the agent:

What language and framework you use
How you organize your code
What style guidelines to follow
Where tests live and how to run them
What to never touch

Every major coding agent checks for AGENTS.md at startup. Claude Code scans for it automatically. OpenCode requires it after /init. Codex CLI reads a chain of them from global to local. pi.dev loads it as a context file.

The format is the same everywhere: plain markdown. One file, every tool.

Why Beginners Skip It (And Regret It)

The most common mistake new coding agent users make is jumping straight in:

"Build me a login page"

The agent generates something. It works. But the code doesn’t match your project’s style. It uses a different folder structure. It adds dependencies you don’t want. You spend more time fixing the output than you would have writing it yourself.

That’s not the agent’s fault. You gave it zero context about your project.

AGENTS.md fixes this in one shot. Write it once, reuse it for every session.

The Fastest AGENTS.md You Can Write

Copy this template into AGENTS.md at your project root. Fill in the brackets. You’re done.

# Project Overview

This is a [Next.js / Django / Express / ...] app that [does what?].

# Code Style

- TypeScript strict mode
- Prefer named exports over default exports
- Use functional components with hooks (no classes)
- 2-space indentation
- Max line length: 100

# Project Structure

- `src/app/` — Next.js app router pages
- `src/components/` — shared UI components
- `src/lib/` — utility functions and API helpers
- `src/styles/` — Tailwind CSS configuration
- `prisma/` — database schema and migrations
- `tests/` — Vitest test files, mirrors src/ structure

# Testing

- Run tests with: `npm run test`
- Write tests for every new feature
- Mock external APIs in tests
- Keep unit tests fast — no database connections

# Commands

- Dev server: `npm run dev`
- Build: `npm run build`
- Lint: `npm run lint`
- Type check: `npm run typecheck`

# Rules

- Never edit files in `generated/` — they're auto-generated
- Never commit `.env` files
- Always add error boundaries to new page components
- Keep PRs under 400 lines when possible

That’s it. Save the file, launch your agent, and watch how much better the output fits.

Real Example: Before and After

Before AGENTS.md:

“Add a user profile page”

Agent generates a class component in the root, uses plain CSS, puts tests in a flat __tests__/ folder. Your project uses functional components, Tailwind, and mirrors src/ structure in tests/. You spend 20 minutes reshuffling.

After AGENTS.md:

Agent reads your instructions. It generates a functional component in src/app/profile/page.tsx, uses Tailwind classes, and creates the test in tests/app/profile/page.test.tsx. First try.

This isn’t hypothetical. It’s the single most reported “aha moment” from developers who switch from raw prompting to instruction files.

Advanced: Layered Instructions

Once you’re comfortable, you can get more sophisticated. Several agents support layered instruction files:

~/.config/opencode/AGENTS.md         # Global — your coding style everywhere
~/projects/myapp/AGENTS.md           # Project — conventions for this repo
~/projects/myapp/src/api/AGENTS.md   # Subdirectory — rules for this module

Claude Code calls these “CLAUD.md” in some setups. Codex CLI calls them “instruction inheritance.” The principle is the same: general rules at the top, specific rules close to the code.

You can also create AGENTS.override.md in a subdirectory to supersede the root rules for that folder. Useful when a monorepo package has different conventions than the rest of the project.

Common Pitfalls

Too vague. “Write clean code” means nothing. Be specific: “Use early returns, not nested if statements.”

Too long. Agents respect token limits. Keep your instructions to 30-50 lines. Put the essentials first — agents read top to bottom.

Outdated instructions. If you switch from Jest to Vitest but your AGENTS.md still says “run tests with jest,” the agent will use the wrong command. Treat it like any config file: update it when your toolchain changes.

No negative instructions. Tell the agent what not to do. “Never edit package.json directly — use npm install --save instead.” “Don’t touch the legacy/ folder.”

The One-Line Test

AGENTS.md is worth it if you answer “yes” to this question:

Would you benefit if a new developer joined your project and instantly knew your conventions, commands, and code structure?

If yes, your coding agent benefits too. They’re the same problem. AGENTS.md solves it for both.

Start Now

Create the file, paste the template above, customize three things (your framework, your test command, one “never do this” rule). Launch your agent. The first task will take half the time.

Every major coding agent supports it. One file. No plugins. No configuration. Just markdown.

That’s the one trick.