CLAUDE.md and AGENTS.md: The Configuration Layer That Makes AI Coding Agents Actually Follow Your Rules

Your AI coding agent doesn't remember yesterday. Every session starts cold — it doesn't know you use yarn not npm, that you avoid any types, or that the src/generated/ directory is sacred and should never be edited by hand. So it generates code with the wrong package manager, introduces any where you've banned it, and occasionally overwrites generated files you'll spend an hour recovering. You correct it. Tomorrow it makes the same mistake. You correct it again.

This is not a model quality problem. It's a configuration problem — and the fix is a plain Markdown file.

CLAUDE.md, AGENTS.md, and their tool-specific cousins are the briefing documents AI coding agents read before every session. They encode what the agent would otherwise have to rediscover or be corrected on: which commands to run, which patterns to avoid, how your team's workflow is structured, and which directories are off-limits. They're the equivalent of a thorough engineering onboarding document, compressed into a form optimized for machine consumption.

Teams that invest in these files stop correcting the same mistakes. Teams that don't invest in them end up supervising their agents more than they save by using them.

What These Files Actually Do

AI coding agents are stateless. Without explicit instructions, they default to common patterns they've seen in training data — which is often not your project's pattern. A CLAUDE.md or AGENTS.md file gives the agent a persistent layer of project context that survives across sessions.

The content that matters most is the stuff the agent cannot infer from code alone:

• Toolchain specifics: yarn vs. npm vs. pnpm; why the project uses a particular test runner; build flags that aren't obvious from package.json
• Workflow expectations: how to structure commits, PR conventions, whether to run typecheck before finishing
• Non-obvious constraints: directories that are auto-generated and must not be edited, files that are copied from elsewhere at build time, environment variables required at runtime
• Architectural decisions: which layer owns what, why a particular abstraction exists, known anti-patterns the team has already rejected

The agent reads this file at the start of every session and uses it to calibrate its decisions throughout. Think of it as institutional memory that survives model updates, team turnover, and session boundaries.

CLAUDE.md vs. AGENTS.md: Picking the Right Format

These two formats serve the same purpose but differ in scope and capability.

CLAUDE.md is the native format for Claude Code. It has the deepest feature set of any agent instruction format:

• @import syntax: Reference external files with @path/to/file.md. This lets you modularize — keep domain-specific guidance in agent_docs/database.md, agent_docs/api-conventions.md, and so on, and import only what's relevant.
• Path-scoped rules: YAML frontmatter restricts rules to specific file patterns. A section with globs: ["**/*.tsx"] only activates when Claude is editing React components — not when it's fixing a shell script.
• Five-level hierarchy: Global (~/.claude/CLAUDE.md) → project root (./CLAUDE.md) → subdirectory files (loaded on demand) → path-scoped rules → user personal imports. All levels concatenate; lower levels supplement rather than replace.
• Auto-memory: Claude can write session notes to ~/.claude/projects/<project>/memory/, creating an organic learning layer on top of your explicit instructions.
• Hooks: For behaviors that must happen with zero exceptions — running a linter after every edit, refusing to push without tests passing — use hooks in .claude/settings.json rather than CLAUDE.md instructions. Hooks are deterministic; instructions are advisory.

AGENTS.md is an open standard stewarded by the Agentic AI Foundation under the Linux Foundation. It's supported by 60+ tools: OpenAI Codex, Cursor, GitHub Copilot, Windsurf, Aider, Gemini CLI, Zed, Warp, Devin, JetBrains Junie, and more. The format is pure Markdown — no required fields, no special syntax. The nearest file to the edited code takes precedence in the directory tree.

OpenAI's Codex implementation adds three-tier hierarchy (global ~/.codex/AGENTS.md → project root → subdirectory AGENTS.override.md), a 32 KiB byte limit, and configurable fallback filenames. The openai/codex repository itself uses 88 AGENTS.md files distributed across its directory structure.

The practical question is which one to use. If your team works primarily in Claude Code, CLAUDE.md gives you more leverage through imports, path scoping, and hooks. If your team uses multiple tools — or if you maintain an open-source project where contributors might use any agent — AGENTS.md is the higher-leverage choice because a single file benefits everyone.

Many teams maintain both: AGENTS.md holds universal rules applicable to any agent, while CLAUDE.md imports AGENTS.md and adds Claude-specific enhancements. GitHub Copilot's .github/copilot-instructions.md can often be symlinked from AGENTS.md to avoid duplication.

The Instruction Budget Problem

Here's the constraint that most engineers miss when they first write these files: frontier LLMs can follow roughly 150–200 instructions with reasonable consistency. Claude Code's built-in system prompt already consumes around 50 of those slots. Every line you add competes for that budget.

A 600-line CLAUDE.md file doesn't give your agent 600 pieces of guidance — it gives it a file from which it will selectively attend to some fraction, possibly ignoring the rules you most care about. Claude Code's own system prompt includes a reminder that CLAUDE.md context "may or may not be relevant to your tasks," signaling that Claude will actively discard sections it judges irrelevant.

This means the discipline of these files is not comprehensiveness — it's ruthless prioritization.

Include:

• Bash commands Claude cannot guess from reading the code
• Style rules that diverge from language defaults
• Test and build commands with their exact flags
• Repository workflow conventions (branch naming, commit format, PR expectations)
• Architectural constraints specific to your project
• Non-obvious gotchas and known failure modes

Exclude:

• Anything the agent can figure out by reading the code
• Standard language conventions it already knows
• Detailed API documentation (link to it instead)
• Generic advice like "write clean code" or "use meaningful variable names"
• Information that changes frequently (it will go stale fast)
• Full file-by-file descriptions of the codebase

The official Claude Code docs make this explicit: "Bloated CLAUDE.md files cause Claude to ignore your actual instructions." HumanLayer keeps their CLAUDE.md under 60 lines. A reasonable ceiling for most projects is 300 lines. If you're over that, you should be pulling content into @imported subdocuments, not adding more to the root file.

One corollary: use a linter instead of instructions for code style. Never send an LLM to do a linter's job. Prettier, Biome, and ESLint with auto-fix enforce style deterministically and at zero token cost. If your CLAUDE.md is full of spacing and formatting rules, you have a linter configuration problem, not a context problem.

What a Well-Structured File Looks Like

A good memory file follows a simple structure: WHAT (tech stack, architecture, key directories), WHY (project purpose, component roles, decisions that aren't obvious from the code), and HOW (commands, workflow, exceptions). In practice:

# Project: MyApp

## Stack
- Frontend: React 18, TypeScript, Tailwind CSS
- Backend: Koa.js, GraphQL, MongoDB (Typegoose)
- Package manager: yarn (not npm)

## Critical rules
- Never edit files in src/generated/ — auto-generated at build time
- Run `yarn typecheck` before finishing any TypeScript change
- Use ES modules (import/export), not CommonJS (require)

## Commands
- Dev server: yarn start
- Build: yarn build
- Lint: yarn lint --fix

## Workflow
- Branch names: feat/*, fix/*, chore/*
- One logical change per PR — no bundling unrelated fixes
- Squash commits before merging

For larger projects, use progressive disclosure. Store task-specific guidance in an agent_docs/ directory and reference it from the root file with brief descriptions and import paths. Claude loads the relevant file before starting work in that domain without polluting every session with rarely-needed context.

The OpenAI Codex team's own AGENTS.md is a useful reference for tone and density. It covers Rust naming conventions, Clippy compliance, testing libraries, TUI styling patterns, and API payload naming — roughly 300 words of dense, actionable guidance. Nothing self-evident. No filler.

The Comparison Across Tools

Each major AI coding tool has its own flavor of instruction file:

Cursor originally used .cursorrules — now deprecated and ignored in Agent mode. Current Cursor uses .cursor/rules/*.mdc files with four activation modes: Always Active, Auto Attached (glob-matched), Agent Requested (agent pulls in when relevant), and Manual. This gives Cursor the most granular per-rule control of any tool.

Windsurf uses .windsurf/rules/*.md for developer-written rules and separately maintains Cascade Memories — automatically generated from interactions and stored in ~/.codeium/windsurf/memories/. The dual-layer model separates explicit team norms (version-controlled) from organic learning (local only). Teams can promote autogenerated memories to explicit rules.

GitHub Copilot reads .github/copilot-instructions.md for repository-wide instructions and .github/instructions/*.instructions.md for path-specific rules (using applyTo: frontmatter). Personal instructions at ~/.github/copilot-instructions.md take highest priority. Organization-level instructions became generally available in April 2026.

Aider uses a YAML config file (.aider.conf.yml) and falls back to AGENTS.md for content-level guidance.

The AGENTS.md standard's value is interoperability: write it once, and it works across Codex, Copilot, Aider, Gemini CLI, Cursor, Windsurf, and 55+ other tools without per-tool maintenance.

Making the Investment Pay Off

The data on AI coding tool adoption is mixed. Developers using AI tools complete more tasks individually, but organizations often don't see improvements in company-level delivery metrics. Research examining thousands of developers found that individual PR throughput increases but PR review time grows substantially, creating downstream bottlenecks — and AI tool adoption correlates with a modest increase in bugs per developer.

The teams that avoid these failure modes are the ones that treat configuration as a first-class engineering concern. A well-crafted instruction file, combined with deterministic enforcement through linting hooks and test requirements, is what separates "AI-assisted but messy" from "AI-assisted and productive."

Concretely: if your agent keeps making the same mistake, that's a signal to add a rule. If the rule doesn't change the behavior, that's a signal the file is too noisy and the rule is being drowned out. Reduce the noise rather than increase the specificity.

The /init command in Claude Code is a useful starting point — it analyzes your codebase and generates a draft CLAUDE.md. Treat the output as a rough draft. Remove anything the agent would get right without being told. Then treat the file as a living document: commit it to git, keep it team-owned, and update it whenever you catch a recurring mistake.

The teams that do this report the most consistent results: the correction loop shrinks, the agent's first attempts land closer to acceptable, and the supervision overhead that makes some AI tool adopters feel like they're moving backward starts to disappear.

That's the promise of these files — not magic, but memory.