Claude Code

AGENTS.md & CLAUDE.md: How to Write Instructions AI Agents Actually Follow

Crazy Black Dog

30 Aug 2026 • 5 min read

For years, onboarding an AI coding agent meant pasting context into a chat window. You explained the stack, warned about the awkward test runner, and hoped the model remembered any of it ten minutes later. That workflow is disappearing. The agents you use today do not wait for you to explain the project. They open the repository and read the instructions that live inside it.

A growing set of tools, including opencode, Cursor, Codex, and the Gemini CLI, now look for a file named AGENTS.md at the root of the repository before they start working. Claude Code looks for CLAUDE.md. Write these files well and every session starts with your context already loaded. Write them badly, or not at all, and you will keep re-explaining your own codebase to a model that could have known it all along.

What Is AGENTS.md?

AGENTS.md is a plain Markdown file, usually at the repository root, that contains operating instructions for AI agents working in that codebase. The convention spread quickly because tools kept inventing their own equivalents. Anthropic popularized CLAUDE.md for Claude Code, and other tools did not want to depend on one vendor's filename. AGENTS.md became the neutral, multi-tool alternative: opencode, Cursor, Codex, and the Gemini CLI all read it automatically when a session starts in a project.

The content is not documentation in the usual sense. A README explains the project to humans who might want to use it. An AGENTS.md explains the project to a model that is about to modify it. The distinction matters. The agent does not need marketing, history, or screenshots. It needs constraints, commands, and conventions.

One detail changes what this file can do: it may include build and test commands, and the agent will actually run them. Instead of describing the test suite, you point the agent at the exact command that runs it. That turns documentation into executable behavior.

CLAUDE.md: Claude Code's Own Format

Claude Code reads CLAUDE.md automatically. It loads the file at the project root at the start of every session and keeps its contents in context for the whole conversation. Same idea as AGENTS.md, tuned for Anthropic's agent.

The distinctive feature is the hierarchy. Claude Code does not stop at the root. It also reads CLAUDE.md files in subdirectories, and when several apply, the file closest to the file being edited takes priority. Global rules go in the root file. Directory-specific rules go next to the code they govern, which keeps them small enough to stay honest.

A practical hierarchy

Root CLAUDE.md: language, overall architecture, build and test commands, coding style.
Subdirectory CLAUDE.md: rules for that module, local conventions, known traps in that area of the codebase.

The priority rule is what makes this work. A deep file can override a root rule, so the hierarchy grows organically as the codebase grows.

What Good Instruction Files Contain

The best files are short, specific, and actionable. In practice, they cover the same ground:

Build and test commands. The exact invocations to compile, run tests, lint, and typecheck, written so the agent can copy and run them.
Coding conventions. Naming, error handling, and formatting choices that differ from the language default.
Architecture notes. Where the important modules live, how data flows between them, and which parts are off-limits.
Known pitfalls. The traps that waste hours: the flaky test, the generated file that must not be edited, the cache that silently serves stale data.
Preferred workflows. How the team actually ships: the migration process, the release steps, the commit conventions.

Notice what is missing: explanations of why the project exists, instructions for humans, and anything the code itself makes obvious. The file earns its place when it saves a failed build or a reverted diff, not when it reads nicely.

What to Avoid

Bad instruction files fail in predictable ways. If you recognize these patterns, fix them before the agents do:

Vague instructions. "Write clean code" and "follow best practices" carry no information. An agent cannot act on them, and they teach the model to ignore the file. Replace every abstraction with a concrete rule.
Duplicating the README. The agent can read the README itself. Restating it wastes context and creates two documents that drift apart.
Length. Every line costs tokens and attention. A fifty-page handbook gets skimmed or ignored. If a section does not change behavior, delete it.
Bans without alternatives. "Never use X" leaves the agent guessing what to do instead. Pair every prohibition with the sanctioned option, or the model will invent its own.
Stale content. An instruction file that still documents the deleted module is worse than none, because the agent trusts it. Treat it like code: update it in the same PR that changes the behavior.

Anatomy of an Effective File

A useful AGENTS.md fits on one or two screens. One section per domain, imperative sentences, concrete paths and commands:

Overview: two sentences. What this repository is and which parts are unusual.
Commands: build, test, lint, typecheck, each with the exact command.
Conventions: the three or four rules that actually matter, stated as directives.
Architecture: a short file map. Where the entry point lives, where the business logic lives, what not to touch.
Pitfalls: the known traps, each with its workaround in the same bullet.

Write it in the second person, addressed to the agent. "Run npm run test:unit before opening a PR. Never edit files in dist/; they are generated." Clear directives beat descriptive prose every time.

Files and Skills: Instructions on Demand

Instruction files are permanent context. Skills are instructions on demand, and the two complement each other. The skills pattern was popularized by projects like obra/superpowers, a widely starred framework of agentic skills on GitHub. A skill is a folder of instructions the agent loads only when the current task calls for it.

Skills shine for reusable procedures that apply across projects: how to write a plan, how to run a code review, how to scaffold a service. Files shine for project-specific facts that apply in every session. A CLAUDE.md or AGENTS.md can point the agent at the relevant skills, and a skill can reference the file conventions it expects. The combination gives you persistent awareness and on-demand depth without stuffing everything into one document.

The Verdict

Instruction files are the cheapest productivity win available to anyone using AI coding agents. They cost an hour to write and save that hour on the first difficult session. Start with the root file, cover commands and conventions, then add subdirectory files where the codebase gets complicated. Review them the way you review code, and update them when the project changes.

The agents will not tell you they read the file. You will notice it in other ways: fewer questions about the stack, builds that pass on the first try, and diffs that respect conventions you never had to repeat. That is what it looks like when an agent already knows your project.