The promise of AGENTS.md is simple: one file that makes AI agents behave. The reality is more nuanced. After three months of daily use across OpenAI Codex, Claude Code, Cursor, and OpenCode, patterns have emerged about what works, what doesn’t, and why some teams get consistent results while others fight their tools.

This post is for you if:

  • You’ve tried AGENTS.md but agents still ignore your rules
  • You’re deciding between AGENTS.md and skills
  • You want to understand why certain patterns work
  • You’re managing AGENTS.md across a team or monorepo

This is a synthesis of production usage, Vercel’s internal evaluations, and vendor documentation—distilled into actionable guidance.

New to AGENTS.md? Start with the practical guide and templates first. This post assumes you know the basics.

TL;DR

What works:

  • Concise files (≤150 lines) with explicit rules
  • Command references agents can copy-paste
  • Progressive disclosure (link to docs, don’t paste them)
  • Single canonical source with symlinks for multi-tool teams

What doesn’t:

  • Long manuals agents ignore
  • Conflicting rules across nested files
  • Skills for basic conventions (AGENTS.md wins on adherence)
  • Trying to maintain separate files per tool

Bottom line: AGENTS.md is the highest-leverage configuration you can add. Start with 10-15 lines, iterate based on agent mistakes, and resist the urge to document everything.

The Evidence

Vercel’s Evaluation

In October 2025, Vercel compared AGENTS.md against skills for internal agent workflows:

MetricAGENTS.mdSkillsDelta
Formatting reliability94%78%+16%
Error rate (per task)0.30.7-57%
Setup time5 min30 min-83%

Why AGENTS.md won:

  1. No decision point — Information is present from the start, agents don’t choose whether to load it
  2. Consistent availability — Always in context, unlike skills that load asynchronously
  3. Faster to iterate — Edit a markdown file vs. redeploying skill configurations

When skills make sense: Heavy workflows that need orchestration (multi-step deploys, complex test suites). For conventions and guardrails, AGENTS.md is strictly better.

Production Usage Patterns

From teams using AI agents daily:

Pattern 1: The Minimal Viable File Most effective AGENTS.md files have 6-10 rules and 3-5 command references. Longer files see diminishing returns—agents start ignoring buried instructions.

Pattern 2: Hierarchical Loading Confusion Teams new to AGENTS.md often create conflicting rules:

  • Root says “use single quotes”
  • apps/web/AGENTS.md says “use double quotes”
  • Result: Inconsistent output, frustrated developers

Solution: Root file has global rules, subdirectories only document what’s different.

Pattern 3: The Symlink Strategy Teams using multiple tools (Codex + Claude Code + Cursor) maintain one AGENTS.md and symlink:

1
2

ln -s AGENTS.md CLAUDE.md
mkdir -p .cursor/rules && ln -s ../../AGENTS.md .cursor/rules/rules.mdc

This prevents drift between tool configurations.

How AGENTS.md Actually Works

AI agents load context in a specific order. Understanding this explains why some configurations work and others fail silently.

OpenAI Codex Loading Order

  1. Global: ~/.codex/AGENTS.md (if exists)
  2. Root: ./AGENTS.md
  3. Subdirectory: Nearest AGENTS.md to working directory
  4. Merge: Files combine with subdirectory taking precedence

Size cap: ~64KB total. Large files get truncated.

Claude Code Loading Order

  1. Global: ~/.claude/CLAUDE.md (if exists)
  2. Root: ./CLAUDE.md
  3. Subdirectory: CLAUDE.md in working directory subtree
  4. Context window: Full file loaded into every session

Critical difference: Claude Code loads the entire CLAUDE.md into context. A 500-line file consumes tokens that could be used for code analysis.

Cursor Loading Order

  1. Project: .cursorrules or .cursor/rules/*.mdc
  2. User: Global Cursor settings

Note: Cursor recently added native AGENTS.md support. Check your version.

The File Format Reality

Three major vendors, three file names:

VendorFileStatus
OpenAIAGENTS.mdNative, preferred
AnthropicCLAUDE.mdNative, preferred
Cursor.cursorrulesNative, plus AGENTS.md support

The community is converging on AGENTS.md as the cross-tool standard (agents.md). It’s just markdown—no proprietary syntax.

Practical impact: Use AGENTS.md as your canonical source. For Claude Code specifically, either:

  • Symlink CLAUDE.md → AGENTS.md, or
  • Use AGENTS.md directly (Claude Code reads it as fallback)

Writing Rules That Stick

Agents follow explicit, actionable rules. Vague guidance gets ignored.

❌ Vague:

1
2

## Code Style
Write clean, maintainable code.

✅ Explicit:

1
2
3
4
5

## Code Style
- Use TypeScript strict mode
- Prefer const over let
- Explicit return types on exports
- No semicolons (Prettier handles this)

Why explicit wins: Agents pattern-match on specific instructions. “TypeScript strict mode” is a concrete configuration. “Clean code” requires interpretation they get wrong.

The Guardrails Pattern

Effective AGENTS.md files establish boundaries, not manuals:

1
2
3
4
5

## Guardrails
- Ask before adding dependencies
- Run tests when test files change
- Update docs when behavior changes
- Prefer small changes over large refactors

These are constraints agents check against. Contrast with:

1
2
3
4

## Architecture
This project uses React 18.2.0 with Next.js App Router. 
The routing system works by...
[500 words of explanation]

Agents don’t need architecture lectures—they need to know whether they can add dependencies without asking.

Common Failures (And Fixes)

Failure 1: Context Bloat

Symptom: Agents ignore instructions at the bottom of long files.

Cause: AGENTS.md over 200 lines. Agents (and underlying models) prioritize recent/early context. Buried instructions lose salience.

Fix: Move extended docs to separate files, reference them:

1
2
3

## Extended Documentation
- Architecture: @docs/architecture.md
- API Design: @docs/api-guidelines.md

Agents load @file references on demand.

Failure 2: Outdated Commands

Symptom: Agents run npm test but your project uses vitest.

Cause: AGENTS.md says npm test but package.json scripts changed.

Fix: Treat AGENTS.md like code. Update it when workflow changes. Add CI check:

1
2
3
4
5
6
7

# Verify AGENTS.md commands exist
grep -o '`[^`]*`' AGENTS.md | tr -d '`' | while read cmd; do
  if ! grep -q "\"$cmd\"" package.json; then
    echo "AGENTS.md command not found: $cmd"
    exit 1
  fi
done

Failure 3: Secret Leakage

Symptom: API keys committed to repo because agent read them from AGENTS.md.

Cause: Including secrets in AGENTS.md for “convenience.”

Fix: Never put secrets in AGENTS.md. Use environment variables:

1
2
3

## Environment
- Copy `.env.example` to `.env` and fill in values
- Never commit `.env` files

Tool-Specific Behaviors

Claude Code: Global Configuration

Claude Code uniquely supports ~/.claude/CLAUDE.md for personal preferences across all projects:

1
2
3
4
5
6

# ~/.claude/CLAUDE.md

## Personal Preferences
- Prefer `rg` (ripgrep) over `grep`
- Use `git diff` before committing to review changes
- Ask before force-pushing

This applies to every repo you work on. Repo-specific CLAUDE.md overrides it.

OpenAI Codex: Override System

Codex supports AGENTS.override.md for temporary deviations:

1
2
3
4
5
6
7

# Normal behavior from root AGENTS.md
codex "refactor auth"

# Override for this session
echo "Skip tests for this refactor" > AGENTS.override.md
codex "refactor auth"  # Uses override
rm AGENTS.override.md  # Back to normal

Useful for experimentation without changing canonical rules.

Cursor: Rules Directory

Cursor supports multiple rule files in .cursor/rules/:

.cursor/
└── rules/
    ├── general.mdc
    ├── react.mdc
    └── testing.mdc

All load into context. Good for organizing complex projects, but watch for conflicts.

Multi-Language Teams

Teams working across Python, TypeScript, and documentation face a challenge: one AGENTS.md or many?

Recommendation: One root file with language-specific sections:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

# AGENTS.md

## Universal Rules
- Ask before adding dependencies
- Update docs when behavior changes

## Python
- Run: `pytest`
- Lint: `ruff check .`

## TypeScript  
- Run: `npm test`
- Lint: `npm run lint`

## Documentation
- Build: `hugo server -D`
- Check links before committing

Agents working in src/python/ see the Python section. Agents in docs/ see documentation rules.

Alternative: Language-specific subdirectories with their own AGENTS.md:

project/
├── AGENTS.md (universal rules)
├── backend/
│   ├── AGENTS.md (Python-specific)
│   └── src/
└── frontend/
    ├── AGENTS.md (TypeScript-specific)
    └── src/

Both approaches work. The subdirectory approach scales better for large teams.

The Iteration Method

The best AGENTS.md files evolve through usage:

  1. Start minimal: 6-10 rules, 3-5 commands
  2. Use agents: Work on real tasks for 1-2 days
  3. Note failures: What did agents get wrong?
  4. Add rules: Document the fix in AGENTS.md
  5. Prune: Remove rules agents always follow correctly
  6. Repeat

Example evolution:

Day 1:

1
2

## Commands
- Test: `npm test`

Day 3: Agent adds dependency without discussion

1
2
3
4
5

## Commands
- Test: `npm test`

## Rules
- Ask before adding dependencies

Day 7: Agent uses wrong test command for subdirectory

1
2
3
4
5
6
7

## Commands
- Root test: `npm test`
- Package test: `npm run test:unit` (in packages/)

## Rules
- Ask before adding dependencies
- Run tests from appropriate directory

When AGENTS.md Isn’t Enough

AGENTS.md sets conventions. It doesn’t handle:

  • Complex workflows — Use skills (Codex) or subagents (Claude Code)
  • External integrations — Use MCP servers
  • Deterministic automation — Use traditional scripts

Decision matrix:

NeedUseExample
Code conventionsAGENTS.md“Use TypeScript strict mode”
Test commandsAGENTS.md“Run npm test”
Multi-step deploySkills“Deploy to staging, run smoke tests, notify Slack”
Database queriesMCP“Query user table via @postgres”
Scheduled tasksScriptsCron job, CI pipeline

Measuring Success

How do you know your AGENTS.md is working?

Quantitative:

  • Agent error rate (mistakes per task)
  • Time to first correct output
  • Number of “please follow the rules” reminders you give

Qualitative:

  • Agents propose changes that match team conventions
  • Less time spent correcting agent output
  • New team members understand codebase faster (via AGENTS.md)

Red flags:

  • Agents consistently ignore specific rules
  • You’re writing long explanations agents don’t follow
  • Same mistakes repeat across sessions

Resources

Documentation:

Tools:

Research:

Last reviewed: 2026-02-07 Evidence level: High (vendor documentation, published evaluations, production usage)