60,000+ repos have one. 30+ AI tools read it. But most AGENTS.md files are either too long, too vague, or generated by an LLM (which makes your agent worse). Here's how to write one that works.
Our coding agent kept generating class components. The entire codebase was functional React with hooks. The README said "React 19, functional components." The contributing guide explained it in detail.
The agent didn't read the README. It doesn't know to.
Then we added an AGENTS.md file with one line in the style section: Always use functional components with hooks. Never use class components. Plus one code example showing the pattern.
The problem disappeared instantly.
That's what AGENTS.md does. It's a Markdown file at the root of your repository that gives AI agents the project-specific context they need to work correctly. Not documentation for humans. Instructions for machines. And as of 2026, it's read natively by 30+ AI tools including Claude Code, GitHub Copilot, Cursor, OpenAI Codex, Gemini CLI, Windsurf, Devin, Aider, and Amazon Q.
The convention has been adopted by over 60,000 repositories and is now stewarded by the Agentic AI Foundation under the Linux Foundation. If you build with AI agents and don't have an AGENTS.md, your agents are guessing at conventions they should know.
Here's how to write one that actually improves agent behavior instead of wasting context tokens.
What goes in an AGENTS.md (and what doesn't)
The common mistake is treating AGENTS.md like documentation. Long explanations. Architecture philosophy. Design rationale. History of the project.
Your agent doesn't need to know why you chose Next.js over Remix. It needs to know that you use Next.js 15 with App Router, and the test command is pnpm test, not npm test.
Research across 2,500+ repositories found that AGENTS.md files over 150 lines deliver diminishing returns and can increase inference costs 20-23% without improving agent performance. The technical maximum is 32 KiB, but aim for under 150 lines.
Here are the sections that matter, in the order they should appear:
Project stack (5-10 lines)
Language, framework, major dependencies, runtime. Be specific.
Good: Next.js 15 App Router, React 19, TypeScript 5.4, Tailwind CSS, Drizzle ORM, Bun
Bad: This is a modern web application built with React and various supporting libraries.
Build and test commands (5-10 lines)
Exact commands with exact flags. Package manager matters. Build targets matter.
Good: Build: bun run build. Test: bun test. Lint: bun run lint --fix. Deploy: bun run deploy:staging
Bad: Run the standard build and test commands as described in package.json.
Code style conventions (10-20 lines, with examples)
One code example per convention beats three paragraphs describing it. This is the single most important insight from studying effective AGENTS.md files. Show, don't tell.
Architecture constraints (5-15 lines)
Directory structure rules. Module boundaries. Import restrictions. Data flow patterns.
Boundaries (5-10 lines)
What the agent should never touch. "Never commit secrets" was the most common helpful constraint across the 2,500-repository analysis. Add: generated files, legacy modules, configuration files that shouldn't change, directories managed by other tools.
Git workflow (5 lines)
Branch naming, commit message format, PR conventions. Squash merge only. Conventional commits: feat:, fix:, chore:, docs:.
The three mistakes that make AGENTS.md useless
Mistake 1: Letting an LLM generate it
This is the most common mistake and the most damaging. Research found that LLM-generated AGENTS.md files reduce task success in 5 out of 8 tested settings and add 2.45-3.92 extra steps per task.
Why? LLMs generate generic, verbose instructions that state the obvious. "Follow best practices for error handling." "Write clean, maintainable code." "Use descriptive variable names." Your agent already knows this. You're burning context tokens on advice the model was trained to follow by default.
Write your AGENTS.md by hand. Include only the conventions that are specific to YOUR project and that an agent wouldn't know without being told.
Mistake 2: Describing conventions instead of showing them
Bad:
Use our custom error handling approach where errors bubble up through
the service layer and are caught by the global error handler rather
than being caught at individual function level.
Good:
// Error handling: Let errors propagate. Do not wrap individual calls
// in try/catch. The global handler catches everything.
// CORRECT
async function getUser(id) {
const user = await db.users.findById(id);
return user;
}
// WRONG
async function getUser(id) {
try {
const user = await db.users.findById(id);
return user;
} catch (e) {
logger.error(e);
throw e;
}
}
The code example communicates instantly what three paragraphs of description fail to convey.
Mistake 3: Not updating it
An AGENTS.md with stale table names, deprecated commands, or outdated architecture constraints is worse than no AGENTS.md. It actively misleads the agent.
Update your AGENTS.md in the same PR where conventions change. Set a quarterly review to remove stale guidance. A useful signal: when an agent repeatedly produces incorrect output, that's a gap in your AGENTS.md.
AGENTS.md vs CLAUDE.md vs .cursorrules (which do you need?)
Here's the honest answer: start with AGENTS.md, add tool-specific files only if you need their unique features.
AGENTS.md has the broadest compatibility. 30+ tools read it natively. It's the universal format.
CLAUDE.md is Claude Code-specific. Its unique feature is @imports that compose instructions from multiple files. If your team uses Claude Code exclusively and needs modular instruction files, add CLAUDE.md alongside AGENTS.md.
.cursorrules is Cursor-specific. Its unique feature is MDC frontmatter with glob patterns that activate different instructions for different file types. If your team uses Cursor and needs per-filetype rules, add .cursorrules.
90% of the content across all three files is identical. Build commands, architecture rules, testing conventions, and boundaries don't change per tool. A converter tool called rule-porter can translate between formats if needed.
Write AGENTS.md first. It's the single source of truth that every tool reads. Add CLAUDE.md or .cursorrules only for features that AGENTS.md can't express.
Beyond coding: AGENTS.md for business agents
Here's where things get interesting. The AGENTS.md convention was born in coding repositories. But the same principle applies to any AI agent: give the agent structured, project-specific context at session start, and it performs better.
For business agents (support, sales, operations), the equivalent configuration includes:
- Identity: Who the agent is. Name, role, company, tone of voice.
- Capabilities: What the agent can do. Which tools it has access to. Which integrations it can call.
- Constraints: What the agent cannot do. Actions that require human approval. Topics it should escalate. Data it should never share.
- Trust level: How much autonomy the agent has. Draft-only? Execute with approval? Fully autonomous within boundaries?
- Escalation rules: When to hand off to a human. Sentiment triggers, confidence thresholds, sensitive categories.
- Output format: How the agent should respond. Structured JSON? Natural language? Specific templates?
For coding agents, AGENTS.md is a file you write and maintain manually. For business agents, this configuration should be visual and managed through a platform.
This is exactly how BetterClaw's agent builder works. Every field that would go into a business AGENTS.md is a visual input in the builder. Identity, capabilities, constraints, trust levels (Intern, Specialist, Lead), escalation rules, output format. Version-controlled by the platform. No file management. No forgetting to update. Free plan with every feature. $19/month per agent on Pro. BYOK with zero markup.
The annotated template (copy and adapt)
Here's a minimal, effective AGENTS.md template. Delete sections that don't apply. A shorter, accurate file outperforms a comprehensive, generic one.
# Project Name
Next.js 15 App Router, React 19, TypeScript 5.4, Tailwind CSS, Drizzle ORM, Bun.
## Commands
Build: `bun run build`
Test: `bun test`
Lint: `bun run lint --fix`
Single test: `bun test path/to/file.test.ts`
## Code Style
Functional components only. Never class components.
Use `const` exclusively. Never `var`, never `let` unless reassignment is needed.
Named exports only. Never default exports.
// Component pattern:
export const UserCard = ({ name, email }: UserCardProps) => {
return <div className="p-4">{name}</div>;
};
## Error Handling
Let errors propagate. Do not wrap individual calls in try/catch.
The global error handler in middleware.ts catches everything.
## Architecture
/app -> Routes and page components
/components -> Shared UI components
/lib -> Business logic and utilities
/db -> Database schema and migrations
Never import from /app into /lib. Data flows one direction.
## Boundaries
Never modify files in /generated/.
Never commit .env or any file containing secrets.
The /legacy/ module uses sync patterns. Do not convert to async.
## Git
Squash merge only.
Conventional commits: feat:, fix:, chore:, docs:.
Branch format: type/short-description (e.g., feat/user-auth).
That's under 50 lines. It communicates everything an agent needs to work correctly in this codebase. Every line is specific. Every section has a reason to exist.
Gartner projects 40% of enterprise applications will embed AI agents by end of 2026. The teams that invest 30 minutes in a good AGENTS.md today will save hours of agent correction every week. The teams that skip it will keep wondering why their agent "doesn't follow instructions."
The best AGENTS.md file is the one your team actually maintains. Not the one that comprehensively documents every edge case and is outdated by next sprint.
Start with 30 lines. Add a section when an agent consistently gets something wrong. Remove a section when the convention changes. Treat it like code, not documentation.
And if your agents are business agents, not coding agents, this entire configuration belongs in a visual builder, not a markdown file. Give BetterClaw a look. Free plan with 1 agent and every feature. $19/month per agent for Pro. Agent configuration through the UI. No files to forget to update.
Frequently Asked Questions
What is an AGENTS.md file?
AGENTS.md is a Markdown file placed at the root of a code repository that provides AI coding agents with project-specific instructions: build commands, code style conventions, architecture constraints, testing procedures, and boundaries. It's read natively by 30+ AI tools including Claude Code, GitHub Copilot, Cursor, OpenAI Codex, and Gemini CLI. Over 60,000 repositories have adopted it, and it's now stewarded by the Agentic AI Foundation under the Linux Foundation.
How does AGENTS.md compare to CLAUDE.md and .cursorrules?
AGENTS.md has the broadest compatibility (30+ tools read it). CLAUDE.md adds Claude-specific features like @imports for modular instruction files. .cursorrules adds Cursor-specific features like glob-based auto-attach rules. 90% of the content is identical across all three. Start with AGENTS.md as your universal source of truth, and add tool-specific files only for features AGENTS.md can't express. A converter tool (rule-porter) can translate between formats.
How long should an AGENTS.md file be?
Under 150 lines. Research across 2,500+ repositories found that files beyond 150 lines deliver diminishing returns and can increase inference costs 20-23% without improving agent performance. The technical maximum is 32 KiB. Shorter, accurate files consistently outperform comprehensive, generic ones. Start with 30-50 lines covering stack, build commands, code style (with examples), and boundaries. Add sections only when an agent consistently makes a specific mistake.
Should I use an LLM to generate my AGENTS.md?
No. Research found that LLM-generated AGENTS.md files reduce task success in 5 out of 8 tested settings and add 2.45-3.92 extra steps per task. LLMs generate generic, verbose instructions that state things agents already know ("write clean code," "follow best practices"). Write your AGENTS.md by hand with only the conventions specific to your project that an agent wouldn't know without being told. One real code snippet is worth more than three paragraphs of description.
Can AGENTS.md principles apply to business agents, not just coding agents?
Yes. The core principle (give the agent structured, specific context about identity, capabilities, constraints, and boundaries) applies to any AI agent. For business agents, the equivalent sections are identity, capabilities, constraints, trust levels, escalation rules, and output format. The difference is that business agent configuration belongs in a visual builder (like BetterClaw) rather than a markdown file, since business agents don't operate from a code repository.
