AGENTS.md in Practice: Making Coding Agents Actually Work

Coding agents start from scratch every session, and a single Markdown file can solve that. But if written wrong, it can actually drag down efficiency—according to one study, these files raise costs by over 20% on average without delivering better results. This article, based on an in-depth breakdown from a YouTube tech channel, lays out the correct way to use AGENTS.md / CLAUDE.md.

What This File Actually Is

AGENTS.md is a plain Markdown file placed in a code repository. The official site calls it "a README for agents." There's no mandatory format and no schema. OpenAI published the spec in August 2025 and handed it to the Agentic AI Foundation under the Linux Foundation in December of the same year, alongside MCP. Claude Code has its own name for the same concept, CLAUDE.md, while Gemini CLI uses GEMINI.md.

The key mental model is this: the agent loads this file into context at the start of every session. That means every line consumes tokens on every task and competes with your actual request for the model's attention. Anthropic's context engineering article puts it plainly—context is a finite resource with diminishing returns. It's also context, not configuration: if something absolutely must not happen (like pushing to the main branch), writing it in Markdown is just a "request"—you should enforce it with a hook or permission settings.

Context Engineering is a concept emphasized in recent years by model vendors like Anthropic. It refers to strategically selecting and arranging information within a limited context window so the model's attention stays focused on what's most relevant to the current task. It differs from traditional prompt engineering: the latter concerns the wording of a single question, while the former concerns all material that enters context throughout a session—system prompts, tool definitions, retrieved documents, message history, and project files like AGENTS.md. The core assumption is that a bigger context window isn't necessarily better: as tokens increase, the model's attention to each piece of information gets diluted, producing "diminishing returns." So the goal of context engineering isn't to cram in more information but to convey the highest information density with the fewest tokens, using summarization, layered loading, or on-demand retrieval to control size when necessary. Understanding this makes it clear why every line of AGENTS.md has a cost, and why "cutting" often improves agent performance more than "adding."

Hooks and permission settings are enforcement mechanisms offered by agent tools like Claude Code to draw hard boundaries outside of model behavior. Hooks are scripts that run automatically at specific lifecycle events (before a tool call, after a file save, at session start) and can intercept, modify, or reject an operation; permission settings declare which commands, paths, or tools can run without asking, which require human confirmation, and which are forbidden entirely. Unlike Markdown instructions, these mechanisms don't rely on the model "choosing to comply"—they're enforced by the runtime. For example, to prevent an agent from pushing to the main branch, you can check the target branch of a git push in a pre-tool-use hook and block it outright, or list that command as denied in your permission config. The article stresses that "things that absolutely must not happen" should be handed to these mechanisms precisely because a Markdown file is just a request in context—the model may ignore it or forget it in a long context—whereas hooks and permissions are deterministic.

Which Tools Read Which File

As of October 2026, support varies significantly across tools and changes fast:

• Codex: reads AGENTS.md from the project root down to the current folder
• Cursor: reads AGENTS.md in the root directory and subfolders
• GitHub Copilot Agent: uses the nearest AGENTS.md, or a single CLAUDE.md / GEMINI.md in the root; in VS Code, root-level files are on by default, while nested files remain experimental
• Jules and Devin: also read the file
• Gemini CLI: reads GEMINI.md by default, but AGENTS.md can be added to the list via the context file name setting
• Claude Code: natively reads AGENTS.md since version 2.1.277, but by default only when there's no CLAUDE.md in that directory or any parent directory

The recommended approach is to make AGENTS.md the single source of truth. If you still need Claude-specific instructions, create a CLAUDE.md, put @AGENTS.md on the first line to import the shared file, and append Claude-specific content below. This is exactly the configuration Claude Code's docs recommend, avoiding two copies that gradually drift apart.

What to Write: Commands, Conventions, Gotchas

File content should focus on three kinds of information.

Commands. Spell out the exact commands for installing, running a single test file, and linting—not just the full test suite. The agent checks itself repeatedly during each task, so give it the fast one. Claude Code's best practices list "bash commands the agent can't guess" as the top priority.

Conventions. Write only where the project deviates from the obvious default—say, using httpx instead of requests, or one router per file in a given folder. The agent can't anticipate these; it will copy the most common patterns found on the internet.

Gotchas. The things that tripped up the last newcomer: the database must be started before tests, migration files are tool-generated and must not be hand-edited, a certain legacy directory nobody should touch.

This aligns with the research: agents follow instructions in the file well, leading the authors to conclude that these files are well suited to describing non-standard practices. In other words, write down what's "surprising" about your repo, not common knowledge that holds for every repo.

Non-standard practices here means conventions in a repository that deviate from mainstream defaults. Models have seen vast amounts of open-source code in training and tend to replicate the most common patterns on the internet: Python projects default to requests, React projects default to a certain directory structure, tests default to running the full suite. When your project deliberately chooses otherwise—using httpx instead of requests, requiring one router per folder, allowing migration files to be generated only by tooling—the model can't infer it from general knowledge and needs explicit instructions. The research emphasizes that these files are "well suited to describing non-standard practices" precisely because standard practices are already within the model's knowledge; writing them down just burns tokens redundantly, whereas non-standard practices can't be guessed and only change behavior when written down. To judge whether a line is worth writing, ask: is this common knowledge that holds for any repo of this kind? If so, delete it; if it holds only for this repo and is counterintuitive, keep it.

What to Delete Even More

Omitting matters more than adding. Four categories should be cut decisively:

1. Repository tours. Explaining directory by directory seems thoughtful, but the agent can list files itself. The research found that repo overviews, despite being popular and recommended by model vendors, don't actually help.
2. Things you'd know from reading the code. Frameworks, languages, file-by-file descriptions—Claude Code's docs explicitly ask you to exclude these.
3. Generic advice. "Write clean code" and "follow best practices" only burn tokens without changing behavior.
4. Rules the tooling already enforces. Anything a formatter can fix doesn't need explaining—just give the command. And remember: never put secrets or tokens in there—the file gets committed to the repo and read by every tool.

On generated files: Claude Code's init command scans the repo and writes a first draft, which is a decent starting point, but the study's "no improvement" finding applies equally to generated files and developer-written ones. Treat the draft as material to be trimmed, not a finished product.

Keep It Short: The Hard Limits of 200 Lines and 32KB

Claude Code's docs recommend keeping each file under 200 lines, because longer files consume more context and reduce compliance. Its best practices page offers a practical trimming test: for each line, ask yourself—would deleting it cause the agent to make a mistake? If not, delete it. The docs also note that if the agent repeatedly ignores a rule, the file is probably too long and the rule is getting drowned out.

Some tools have hard limits: Codex stops adding once instruction files total 32KB, and Devin reads only the first 16KB of each file—anything after that the agent never sees.

Maintain it like code: review changes in PRs, and delete lines when the code changes. My rule is—only add a line after the agent makes the same mistake twice. Once could be noise; twice is worth a sentence. When adding, include the reason, e.g., "never hand-edit migration files, because they are generated"—rules with reasons hold up better in unforeseen situations.

Monorepos and Nested Files

A single root file can't cover everything: the frontend uses pnpm, and the billing service has rules about money. Put globally applicable content in the root file, and package-specific commands and gotchas in that package's AGENTS.md. The official convention is simple—the file nearest the code being edited wins.

Implementations vary: Codex merges all files from the root down to the current directory, with later ones overriding earlier ones; Copilot Agent uses the nearest one; Claude Code loads files above the working directory at startup, loads that level on demand when it reads subfolder content, and merges rather than replaces what it finds. A practical corollary: don't contradict the root file in a nested file, or the model may see both and be forced to choose one. Be specific in nested files rather than contrarian. If you want rules organized by file type rather than directory, Claude Code has a rules folder where you can tag applicable paths, and Copilot has instructions files with apply-to patterns.

Loading and precedence of nested instruction files is a key mechanism in monorepo scenarios, and implementations differ considerably across tools—understanding the model helps avoid rule conflicts. There are three common strategies: first, "merge and override," as in Codex, which reads from the repo root down to the current directory, with later files overriding earlier rules of the same name; second, "nearest wins," as in GitHub Copilot Agent, which uses only the single file closest to the code being edited; third, "layered merge," as in Claude Code, which loads files above the working directory at startup and then loads that level on demand when the agent reads subfolder content, merging rather than replacing what it finds. These differences mean the same rule placed in the root file versus a nested file can have completely different effects. The practical corollary: put only globally applicable content in the root file, and write package-specific commands and gotchas in nested files; don't directly negate root rules in a nested file—be more specific instead, or the model may see two contradictory instructions at once and be forced to choose, making behavior unpredictable.

The Full Recipe and a Security Reminder

Putting it all together: use AGENTS.md as the single source of truth, plus a CLAUDE.md that imports it; fill in commands, non-default conventions, and gotchas; delete tours, the obvious, and generic talk; stay under 200 lines and prune it like code. To verify the effect, run a small-scale test modeled on the researchers' approach—give the agent the same few real tasks and compare results and token usage with and without the file.

One final warning: an AGENTS.md in a cloned repository is a set of instructions your agent will follow. Before pointing your agent at an untrusted repo, read it first.

One-line Summary

AGENTS.md is context loaded every session—written well it boosts efficiency, written poorly it raises costs.

Paragraph Summary

The article systematically lays out the correct usage of agent instruction files like AGENTS.md / CLAUDE.md. The core mental model: the file is loaded into context at the start of every session, and every line consumes tokens and competes with the actual request for the model's attention, so it's context rather than enforced configuration—absolute prohibitions should be handed to hooks or permission settings. Content should include only commands, non-default conventions, and pitfalls, while deleting repo tours, information evident from reading the code, generic advice, and rules the tooling already enforces. Keep files under 200 lines; Codex truncates at 32KB and Devin reads only the first 16KB. In monorepos, use nested files for package-level rules, with the nearest file winning, and avoid contradicting the root file. Finally: an AGENTS.md in a cloned repo is a set of instructions the agent will follow—always read it before use.