AGENTS.md: The Configuration That Can Break Your Agent

If you’ve set up a code agent, you’ve probably created an AGENTS.md assuming more context means better performance. I believed that too until I saw the data: an auto-generated AGENTS.md can reduce your success rate by up to 2% while spiking costs by 20%. In this post, I explain what research says about these configuration files and how to write yours so it actually helps.

Note on conventions: Claude Code uses CLAUDE.md, while Cursor, Zed, and OpenAI Codex use AGENTS.md. The principles in this post apply to both formats.

Why do AGENTS.md files usually fail?

Recent research on context files reveals a counterintuitive pattern: auto-generated files actually degrade agent performance. The data is clear:

According to [1]:

• LLM-generated AGENTS.md files reduce success rates between 0.5% and 2%
• Increase inference costs between 20% and 23%
• Add 2.45-3.92 extra steps per task without improving results

The problem isn’t the concept, but the implementation. Auto-generated files tend to duplicate information that already exists in your project documentation, creating noise instead of clarity.

In most tools, agents read the entire AGENTS.md in each conversation — though exact behavior varies by client; check your tool’s documentation — so every unnecessary line dilutes the instructions that actually matter.

What actually works in an AGENTS.md?

Human-written files improve performance in the 2-6% range (average 4%) for most agents, but also increase inference costs up to 19%. Important note: Claude Code shows marginal improvements but is not consistently superior to other agents according to [1]. It’s critical they follow the WHY-WHAT-HOW framework to justify this trade-off:

The WHY: Purpose and architecture

Explain why your project exists and how the main components relate. Don’t list directories, but provide architectural context:

// ❌ Bad: directory listing
// src/
//   components/
//   services/
//   utils/

// ✅ Good: architectural context
// This is a multi-tenant SaaS platform where:
// - Each tenant has isolated data (tenant_id scoping)
// - Background jobs handle document processing
// - Real-time updates use WebSockets for collaboration

The WHAT: Stack and specific structure

Document your tech stack and non-obvious decisions. This is critical in monorepos:

# Tech stack the agent needs to know
Runtime: Bun
Database: PostgreSQL with Drizzle ORM
Testing: Vitest (not Jest)
Linting: Biome (not ESLint/Prettier)
Deployment: Render with Docker

The HOW: Tools and verification

Include build, test, and verification commands. Mentioning specific tools dramatically increases their use by the agent according to [1]:

# Build & test workflow
bun install           # Never use npm
bun run build         # Builds all packages
bun test              # Runs Vitest across monorepo
bun run typecheck     # TypeScript validation

What NOT to include in your AGENTS.md?

Detailed code overviews

Agents can discover structure on their own:

Include	Don’t include
”auth/ handles JWT authentication"	"auth/controllers/, auth/models/, auth/views/"
"Background jobs in workers/"	"workers/email.js, workers/pdf.js, workers/…”
Purpose of each module	Detailed file structure

Code style guidelines

Use linters and formatters instead of instructions. They’re faster, cheaper, and deterministic. If you have Biome configured, you don’t need to explain style in AGENTS.md.

Task-specific instructions

Since AGENTS.md goes into every session, only include universal instructions. Task-specific ones dilute focus:

❌ "For WebSocket debugging, check logs in /tmp/socket.log"
✅ "Application logs in logs/ directory"

❌ "When updating schema, run migrations on staging first"
✅ "Database changes require migrations (see docs/database.md)"

How to structure AGENTS.md for maximum impact?

Keep it short

General consensus is under 300 lines. HumanLayer keeps theirs under 60 lines. Each line goes into every session — make it count.

Progressive disclosure

Don’t put everything in AGENTS.md. Create specific files in agent_docs/:

Note: behavior varies by tool. Some clients open referenced files automatically; others require the agent to request them explicitly or you specify this in the prompt.

# In AGENTS.md (references, not full content)
## Documentation Structure
- `agent_docs/database.md` - Schema and migration workflow
- `agent_docs/testing.md` - Test setup and mocking patterns
- `agent_docs/deployment.md` - Environment config (no real credentials; use .env.example)

## Quick Start
bun install && bun dev

Pointers instead of copies

Reference locations file:line instead of embedded code snippets that become outdated. When possible, prefer referencing by function or class name rather than line number:

❌ Copy 20 lines of TypeScript configuration
✅ "TypeScript config in tsconfig.json:12-25"

Common mistakes

The auto-generated AGENTS.md

If you use /init in Claude Code (generates CLAUDE.md) or equivalent commands in other tools, you’re sabotaging performance. Data shows it reduces success and increases costs with no benefit.

How to detect it: If your AGENTS.md has extensive file listings or documentation that duplicates existing READMEs.

How to fix it: Completely rewrite it, focusing on the 3-5 things the agent really can’t infer.

Treating AGENTS.md as a linter substitute

Putting style rules in AGENTS.md is sending an LLM to do linter work.

How to detect it: Instructions like “use single quotes”, “don’t use var”, “prefer arrow functions”.

How to fix it: Configure Biome/ESLint and remove all style rules from AGENTS.md.

Instructions contradicting your tools

If your AGENTS.md says “use npm” but your package.json has bun lockfiles, you create confusion.

How to detect it: Verify that commands in AGENTS.md match tools in package.json/composer.json/requirements.txt.

The bloated context file

Including information the agent can discover by navigating the codebase.

How to detect it: If your AGENTS.md has more than 300 lines.

How to fix it: Reduce to essentials, move details to separate files in agent_docs/.

Implementation checklist

• AGENTS.md written manually (never auto-generated)
• Under 300 lines total
• Includes WHAT (stack), WHY (purpose), HOW (commands)
• Doesn’t duplicate information available in existing documentation
• Build/test/verification commands specified
• Uses progressive disclosure with agent_docs/ files for details
• All mentioned tools match actual configuration
• No style guidelines (use linters instead; do include architectural conventions that linters can’t verify)
• Universal instructions only (no task-specific ones)

Sources

1. Research on Context Files for Code Agents — ArXiv — performance and cost data for auto-generated vs human-written context files.
2. Writing a good CLAUDE.md — HumanLayer — WHY/WHAT/HOW framework and progressive disclosure strategies.

Frequently Asked Questions

What if my AGENTS.md has more than 300 lines?

Every extra line dilutes important instructions. LLMs have practical limits on followable instructions, and Claude Code already includes significant internal instructions in each session. Your AGENTS.md should use remaining space wisely, prioritizing information the agent can’t infer from the codebase.

Should I include code examples in AGENTS.md?

No. Prefer file:line references that point to real code in your repo. Code snippets in AGENTS.md become outdated and waste valuable space. If you need to show patterns, create separate files in agent_docs/ with complete examples.

What tools should I mention in the HOW section?

Only non-standard or non-obvious tools. If you use npm, don’t mention it — it’s the default. If you use bun, uv, or poetry, definitely include it. Mentioning specific tools dramatically increases their use by the agent according to [1].

How do I know if my AGENTS.md is working?

Measure success rates on repetitive tasks and the number of steps it takes to complete them. An effective AGENTS.md should reduce unnecessary steps (like using wrong tools) without significantly increasing total task time.

Can I have different AGENTS.md files for different projects in a monorepo?

Technically yes, but behavior varies by tool — Claude Code reads from the current directory upward; other tools may behave differently. If you have very different needs per project, consider using progressive disclosure: a root AGENTS.md that references projects/api/agent_docs/ and projects/frontend/agent_docs/ for project-specific context.