AGENTS.md is the smallest lever that changes the biggest outcomes: a single file that tells AI agents how to behave in your repo. No skills to configure, no complex setup—just markdown that agents read automatically.

Here are some excellent guides:

Vercel’s internal evals found that a tight AGENTS.md beats skills on formatting reliability and error rates. The lesson: keep rules boring and explicit, then let the model do the work. AGENTS.md beats skills and are easier to work with, and agent adherence is high

Quick Start (5 Minutes)

New to AGENTS.md? Start here. This is all you need to get value immediately.

Step 1: Copy This Template

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

# AGENTS.md

## Mission
Ship clean changes with minimal diffs and clear reasoning.
Always use bun over npm
Do not hallucinate; it is OK to not know something and ask questions.
Skip fluff and preambles and sycophantic dictations
Write clean, maintainable code
Check for existing implementations before rearchitecting new ones

## Commands
- Build: `bun run dev`

## Rules
- Ask before adding dependencies or deleting files
- Prefer the smallest change that solves the task
- Run tests when test files are modified
- Update docs when behavior changes
- Prefer maintaining existing documentation over creating new topics unless requested otherwise
- Stop and double-check for any major changes that need reconciliation or potential user errors (example, user is asking for help on the wrong project in the wrong DIR, says change this typescript to... when the project is python, lean towards confirming before proceeding)

## Project Map
- `src/` — Source code
- `docs/` — Documentation (update when behavior changes)
- `tests/` — Test files

Step 2: Customize for Your Stack

  • Replace bun test with your actual test command
  • Replace src/ with your actual source directory
  • Add or remove rules based on your team’s needs

Step 3: Save and Commit

1
2

git add AGENTS.md
git commit -m "Add AGENTS.md for AI agent guidance"

Done. Agents will now read this file automatically at the start of each session.

Who This Guide Is For

Why AGENTS.md Works

AI agents start every session cold. They don’t know your stack, your conventions, or what “clean code” means to your team. AGENTS.md is their onboarding document—loaded automatically before the first prompt.

What changes when you add AGENTS.md:

  • Agents stop guessing at test commands
  • Dependencies aren’t added without discussion
  • Code style stays consistent
  • You stop repeating the same instructions

Size matters. Codex has a default cap (around 64KB). Claude Code loads your full CLAUDE.md into every session. Factory.ai recommends ≤150 lines—long files bury the signal. Small and specific beats long and generic.

AGENTS.md vs CLAUDE.md

AGENTS.mdCLAUDE.md
Used byOpenAI Codex, Cursor, OpenCode, ZedClaude Code only
FormatMarkdown (YAML frontmatter optional)Markdown only
LocationRepo root, subdirectories, ~/.codex/Repo root, subdirectories, ~/.claude/
OverridesAGENTS.override.md per-folderNested CLAUDE.md in subdirectories
LoadingMerges root → subdirectoryHierarchical: global → root → subdirectory

The practical difference: Almost nothing. Both are markdown files with the same purpose. The naming is vendor-specific—OpenAI uses AGENTS.md, Anthropic uses CLAUDE.md. Content-wise, they’re interchangeable.

Multi-tool strategy:

  • Use AGENTS.md as your canonical source
  • Symlink CLAUDE.md → AGENTS.md for Claude Code Ln -s AGENTS.md CLAUDE.md
  • Most teams don’t need both

nested AGENTS.md

├── AGENTS.md ├── CLAUDE.md -> AGENTS.md # optional symlink for compatibility ├── content/ │ ├── AGENTS.md │ └── posts/ ├── scripts/ │ ├── AGENTS.md │ └── build/ └── apps/ ├── AGENTS.md └── web/ ├── AGENTS.md └── src/

Each agent can get their own instructions to adhere to. This saves on context rot, token expenditure, and helps with organization.

Templates by Use Case

General / Documentation Projects

Best for: Static sites, documentation, content repositories

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

# AGENTS.md

## Mission
Maintain consistency and accuracy in all content changes.

## Commands
- Build: `hugo server -D` (dev) / `hugo --gc --minify` (production)
- Test: `./scripts/check-links.sh`

## Content Standards
- Use sentence case for headings
- Keep frontmatter consistent (check existing files)
- Run link checker before committing
- Update dates in `last_reviewed` fields when modifying content

## File Organization
- `content/` — All published content (Markdown)
- `static/` — Assets (images, CSS, JS)
- `layouts/` — Templates (don't modify without testing)
- `scripts/` — Build and validation scripts

## Prohibited
- No AI-generated content without human review markers
- Never commit secrets or API keys
- Don't delete content without archiving first

Why this works: Documentation projects need consistency more than code style. The focus is on accuracy, link integrity, and workflow rules.

Python Projects

Best for: Django, Flask, FastAPI, data science, scripts

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

# AGENTS.md

## Mission
Write clean, tested Python following project conventions.

## Commands
- Install: `pip install -r requirements.txt` or `pip install -e .`
- Test: `pytest` (or `python -m pytest`)
- Lint: `ruff check .` or `flake8`
- Format: `ruff format .` or `black .`
- Type check: `mypy src/` (if using types)

## Code Style
- Follow PEP 8
- Use type hints for function signatures
- Docstrings for public functions (Google or NumPy style)
- Prefer f-strings over `.format()` or `%`

## Testing Rules
- Run tests when modifying logic
- Maintain or improve test coverage
- Use pytest fixtures for shared setup

## Project Structure
- `src/` or package root — Source code
- `tests/` — Test files (mirror source structure)
- `requirements.txt` or `pyproject.toml` — Dependencies
- `docs/` — Documentation

## Definition of Done
- All tests pass
- Linting passes with no errors
- Type checks pass (if applicable)
- No new dependencies without approval

Key differences from general template:

  • Specific Python tooling (pytest, ruff/black, mypy)
  • Type hints and docstring requirements
  • Test coverage rules
  • Package structure conventions

TypeScript / Node.js Projects

Best for: React, Next.js, Express, Node APIs

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44

# AGENTS.md

## Mission
Ship type-safe changes with consistent style and passing tests.

## Commands
- Install: `bun install` or `pnpm install`
- Dev: `bun run dev` or `pnpm dev`
- Build: `bun run build`
- Test: `bun test` or `pnpm run test:unit`
- Lint: `bun run lint` (includes ESLint + Prettier)
- Type check: `bun run typecheck` or `tsc --noEmit`

## Code Style
- TypeScript strict mode enabled
- Prefer `const` and `let` over `var`
- Explicit return types on exported functions
- No `any` types without justification
- Single quotes for strings
- No semicolons (Prettier handles this)

## Testing Requirements
- Unit tests for business logic
- Run full test suite before PR
- Update tests when changing behavior

## Project Structure
- `src/` — TypeScript source
- `dist/` or `build/` — Compiled output (don't edit directly)
- `tests/` or `__tests__/` — Test files
- `package.json` — Dependencies and scripts

## Security
- Never log secrets or API keys
- Use environment variables for sensitive config
- Check for secrets before committing: `git diff --cached | grep -i "api_key\|password\|secret"`
- Ensure secrets, intel, and private data are properly ignored, configured, and safe from mishap, exposure and exfiltration. 

## Definition of Done
- TypeScript compiles without errors
- All tests pass
- Linting passes
- No console errors in dev build
- No new dependencies without discussion

Key differences from Python:

  • TypeScript-specific (strict mode, no any)
  • bun/pnpm/yarn workflow
  • Build step required (dist/ folder)
  • ESLint + Prettier integration
  • Security check for secrets

Common Mistakes to Avoid

Learn from others’ failures. These are the top issues that make AGENTS.md ineffective:

❌ Writing a Manual Instead of Guardrails

1
2
3

# BAD: Too long, agent will ignore half of it
This project uses React 18.2.0 which was released in...
[500 lines of architecture explanation]

✅ Be concise:

1
2
3

# GOOD: Actionable rules
- React 18, Next.js App Router
- Run `pnpm test` before committing

❌ Including Sensitive Data

1
2
3
4

# NEVER DO THIS
API_KEY=sk-abc123...
DATABASE_URL=postgres://...
SEED_PHRASE = 'CAUTION DANGEROUS SITUATION HALT DONT PROCEED CAUTION'

Security note: Agents read AGENTS.md before every task. Never commit secrets. Use environment variables instead.

❌ Conflicting Instructions Across Files

  • Root says “use single quotes”
  • Subdirectory says “use double quotes”
  • Result: Agent confusion, inconsistent output

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

❌ Outdated Information

  • Commands that no longer exist
  • Dependencies you’ve removed
  • Old file paths

Fix: Treat AGENTS.md like code. Review it when your workflow changes.

❌ One Giant File

Hierarchical Loading (Monorepos)

Both Codex and Claude Code support nested configuration files. The closest file to the working directory takes precedence.

Example monorepo structure:

my-project/
├── AGENTS.md           # Global rules
├── package.json
├── apps/
│   ├── web/
│   │   ├── AGENTS.md   # Web-specific overrides
│   │   └── src/
│   └── api/
│       ├── AGENTS.md   # API-specific overrides
│       └── src/
└── packages/
    └── shared/
        └── src/

Root AGENTS.md (shared rules):

1
2
3
4
5
6

# Global rules for all packages

## Rules
- Ask before adding dependencies
- Use conventional commits
- Update AGENTS.md when conventions change

apps/web/AGENTS.md (specific rules):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

# Web app specific rules

## Commands
- Test: `bun test` (uses Vitest)
- Build: `bun run build` (Next.js)

## Rules
- Use React functional components
- Prefer server components where possible
- Tailwind classes only (no inline styles)

How it merges: Agents read the root first, then override with subdirectory rules. Don’t repeat global rules—only document what’s different.

Multi-Tool Setup

Using multiple AI tools? You have options:

Option 1: Single source (recommended)

1
2
3
4
5
6

# Use AGENTS.md as canonical
ln -s AGENTS.md CLAUDE.md

# For Cursor (if not using AGENTS.md natively)
mkdir -p .cursor/rules
ln -s ../../AGENTS.md .cursor/rules/rules.mdc

Option 2: Tool-specific files Keep separate files if your teams use different tools:

  • AGENTS.md — OpenAI Codex rules
  • CLAUDE.md — Claude Code rules (can reference same content)

Option 3: Progressive disclosure

1
2
3
4
5
6
7
8

# AGENTS.md
## Core Rules
[6-10 universal rules here]

## Extended Documentation
- Architecture: @docs/architecture.md
- API Reference: @docs/api.md
- Deployment: @docs/deploy.md

Agents load @file references when needed, keeping your main file small.

Advanced Patterns

Use these only after you’ve mastered the basics.

Global Configuration

Claude Code:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

# Create global preferences
mkdir -p ~/.claude
cat > ~/.claude/CLAUDE.md << 'EOF'
# Personal preferences (apply to all repos)

## Workflow
- Prefer `git diff` before committing to show changes
- Use conventional commits (feat:, fix:, docs:)
- Ask before force-pushing
EOF

OpenAI Codex:

1
2
3
4
5
6
7
8

mkdir -p ~/.codex
cat > ~/.codex/AGENTS.md << 'EOF'
# Global defaults

## Commands
- Prefer bun over pnpm when available
- Use `rg` (ripgrep) instead of `grep` for searches
EOF

Global files apply to all projects, repo-specific files override them.

Override Files (Codex Only)

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

Verification Checklist

Before relying on your AGENTS.md:

  • File is under 150 lines
  • Commands actually work (test them)
  • File paths match your repo structure
  • No secrets or sensitive data
  • Rules don’t conflict with each other
  • Links to extended docs use @file syntax
  • Last reviewed date is recent

References