AGENTS.md across Codex, Claude Code, and GitHub Copilot: what belongs in the file

An instruction file looks deceptively simple: put a Markdown document in a repository and the coding agent reads it before working. The hard part is deciding what deserves to be present in every task.

These three coding-agent environments do not treat the filename in exactly the same way. Codex uses AGENTS.md as its native project-instruction format. Claude Code uses CLAUDE.md, but now documents an explicit way to import an existing AGENTS.md. GitHub Copilot supports AGENTS.md for its agents while also retaining GitHub-specific repository-wide and path-specific instruction files.

That makes AGENTS.md useful as a portable core, not a fully portable configuration. The shared file can hold facts and working agreements that apply everywhere. Each tool may still need a thin adapter for its own discovery rules or specialized features.

The same file enters three different instruction systems

These differences matter most in monorepos. A root file can define organization-wide build and review expectations, while a file inside apps/web/ can describe frontend-only commands. The nesting mechanism is not an invitation to copy the same rules into every directory. It is a way to keep irrelevant context away from tasks that do not need it.

Codex: AGENTS.md is a layered instruction chain

Codex reads instruction files before it starts work . It first checks for global guidance in the Codex home directory. Within a project, it walks from the project root down to the current working directory and includes at most one instruction file per directory. An AGENTS.override.md takes priority over AGENTS.md at the same level, and files closer to the working directory appear later in the combined prompt.

The default combined project-instruction limit is 32 KiB. Reaching that limit should normally trigger editing rather than expansion: remove repetition, move specialized procedures elsewhere, or scope guidance closer to the code it governs.

Claude Code: import AGENTS.md; do not pretend the name is native

Claude Code reads `CLAUDE.md`, not `AGENTS.md` . Anthropic’s documented interoperability pattern is a tiny CLAUDE.md containing @AGENTS.md. Claude expands the import at session start, and Claude-specific instructions can follow it. A symlink also works when no tool-specific additions are needed.

Claude Code concatenates discovered instruction files rather than treating a closer file as a literal replacement. It loads files above the working directory at launch and brings descendant instructions into context when it reads files in those subtrees. Anthropic recommends keeping each CLAUDE.md under 200 lines, using path-scoped rules for narrower guidance and skills for multi-step procedures that should not occupy every session.

GitHub Copilot: support depends on the surface

Copilot on GitHub recognizes three instruction shapes : repository-wide .github/copilot-instructions.md, path-specific .github/instructions/*.instructions.md, and agent instructions in one or more AGENTS.md files. For agent instructions, the nearest AGENTS.md in the directory tree takes precedence.

Copilot CLI also loads custom instructions at session start , including AGENTS.md and .github/copilot-instructions.md. GitHub’s product family has several surfaces with different support matrices, so “Copilot supports this file” should not be interpreted as “every editor feature consumes every instruction type identically.” Check the target feature before relying on an instruction for a review or automation boundary.

Karpathy did not write your AGENTS.md

A popular set of four rules is often called “Karpathy’s AGENTS.md” or “Karpathy’s CLAUDE.md.” That attribution compresses two separate events into one.

In a January 2026 post about coding heavily with Claude , Andrej Karpathy described a rapid shift in his own workflow from mostly manual and autocomplete-based coding to mostly agent coding. He also listed recurring failure modes: agents can make incorrect assumptions without asking, miss inconsistencies and trade-offs, overcomplicate implementations, change code they do not sufficiently understand, and need verifiable goals to use their persistence well.

The post did not publish an AGENTS.md file. Community authors later translated those observations into four memorable sections:

• Think before coding: expose assumptions and ambiguity instead of silently selecting an interpretation.
• Simplicity first: implement the smallest solution that satisfies the request.
• Surgical changes: avoid drive-by refactors and preserve code outside the task.
• Goal-driven execution: turn vague work into observable checks and iterate until they pass.

Those rules are useful, but they are a community-authored interpretation of Karpathy’s observations, not a file he should be described as having written or installed. The distinction matters because a viral template should still be reviewed against the needs of the repository that adopts it.

What belongs in the shared file

The best entries are facts or constraints that the agent cannot safely infer and that matter across many tasks.

Verified commands

Name the package manager and the shortest commands that actually work for setup, focused tests, type checking, linting, and the production build. Include unusual prerequisites. Do not paste the entire CI pipeline when a stable script already represents it.

A compact map to sources of truth

Point to the directories or documents that own architecture, schemas, generated types, migrations, design tokens, and release procedures. A map is more durable than copying their contents. The agent can open the source when the task makes it relevant.

Repository-specific boundaries

Document rules whose violation would create a plausible but wrong patch: generated files that must not be edited, APIs that require backward compatibility, migrations that must be additive, or modules owned by another system. Prefer concrete statements such as “edit the schema and regenerate types with npm run db:types” over “keep types in sync.”

A definition of done

Tell the agent which evidence is expected before it hands work back: a focused regression test, type checking, a build, a rendered screenshot, or an updated API fixture. Match verification to the change; requiring the largest possible suite after every edit wastes time and encourages agents to treat ritual as evidence.

Escalation boundaries

State which decisions require a person: adding a production dependency, making a destructive migration, changing a public API, deploying, or sending an external message. Remember that prose guides model behavior; it is not a security control. Use sandboxing, permissions, hooks, branch protections, and CI for enforcement.

What should stay out

An instruction file becomes harmful when it collects everything anyone has ever wanted an agent to remember.

• Do not duplicate the README or handbook. Link to stable documentation and record only the agent-specific delta.
• Do not restate enforced formatter and linter rules. The tool output is more precise and cannot be forgotten halfway through a session.
• Do not put occasional workflows in always-on context. A release procedure, migration playbook, or deep-review checklist belongs in a skill or task-specific rule.
• Do not include unverified commands. A confident but stale command creates more work than discovery would have.
• Do not write conflicting absolutes. “Never ask questions” and “always clarify ambiguity” cannot both govern the same task.
• Do not turn past incidents into a scar log. When possible, encode the lesson in a regression test, static check, permission boundary, or clearer architecture.

This is not only a matter of taste. A 2026 preprint evaluating coding agents found that context files increased inference cost by more than 20% in its tested settings without a statistically significant improvement in task completion; developer-written files performed better than generated ones, but still added work. The authors recommend keeping only minimal requirements that are not already in ordinary documentation. Read the study and its limitations .

The evidence is still developing. A later preprint covering 288 runs across Claude Code and Codex also found no measurable correctness change from context injection in its task set. That does not prove instruction files are useless. It shows that they did not compensate for implementation difficulty in those experiments, and that their value should be measured on the repository’s real work rather than assumed. Read the ablation study .

A third 2026 preprint examined 100 open-source configuration files and catalogued 207 instruction “smells.” The most common was lint leakage: spending context on rules already enforced by automated tooling. Read the configuration-smells study .

The current direction: less permanent context, better routing

Taken together, the current product documentation points away from one ever-growing Markdown file and toward layered context:

1. Keep a small shared core for repository-wide facts and working agreements.
2. Put subtree-specific facts near the subtree or in path-scoped instructions.
3. Load repeatable, task-specific procedures as skills when they are relevant.
4. Enforce safety and mechanical rules with tools rather than prose.
5. Evaluate changes to instructions using representative tasks, not anecdotes alone.

This makes maintenance part of the engineering loop. When an agent repeats a mistake, first ask whether it lacked durable repository knowledge. If so, add one specific instruction. If the failure can be detected deterministically, add a test or check instead. If the behavior is needed only for one workflow, create a skill. Delete rules when the codebase or tooling makes them obsolete.

A small portable starting point

The following is deliberately incomplete. Replace every placeholder with a verified repository fact and remove sections that add no information.

# AGENTS.md

## Repository map
- Application code: src/
- Tests live beside the code they cover.
- Architecture decisions: docs/decisions/

## Working commands
- Install: npm ci
- Focused test: npm test -- <test-file>
- Type check: npm run typecheck
- Production build: npm run build

## Change rules
- Make the smallest change that satisfies the request.
- Preserve public APIs unless the task explicitly changes them.
- Do not edit generated files; run the documented generator.
- Ask before adding a production dependency.

## Verification
- Reproduce bugs with a failing test when practical.
- Run the focused test after each meaningful change.
- Before handoff, run the checks relevant to the changed surface.

For Codex, commit that file at the project root. For Claude Code, add this adapter:

@AGENTS.md

## Claude Code
- Put only Claude-specific additions here.

For GitHub Copilot agents and CLI, the root AGENTS.md supplies the shared guidance. Add .github/copilot-instructions.md or path-specific Copilot instructions only when a supported Copilot feature needs guidance that does not belong in the cross-tool core.

The goal is not to tell an agent how to be a software engineer in general. It is to give three capable tools the smallest amount of local knowledge they need to make correct, reviewable changes in this repository.

Further reading

• OpenAI — Custom instructions with AGENTS.md
• Anthropic — How Claude remembers your project
• GitHub — Adding repository custom instructions for Copilot
• AGENTS.md open format
• Andrej Karpathy — notes from coding with Claude