
AGENTS.md and CLAUDE.md: instructions for coding agents
In short: AGENTS.md and CLAUDE.md are project files that give coding agents your commands, conventions and rules at the start of every session.
AGENTS.md and CLAUDE.md are plain Markdown files in a repository that give AI coding agents standing instructions: build and test commands, coding conventions, folders to avoid and rules to follow. The agent reads them at the start of each session. AGENTS.md is the cross-tool format, used by over 60k open-source projects according to its site in November 2026; CLAUDE.md is Claude Code's own file.
AGENTS.md in plain words
The README is for humans joining the project. AGENTS.md is the onboarding note for the AI teammate: the house rules it would otherwise have to guess.
How it works
When a session starts, the agent loads the file into its context. Some tools also load nested files from subfolders and user-level files from your home directory; the AGENTS.md site says the nearest file in the directory tree takes precedence.
Claude Code's memory documentation, read in November 2026, says Claude Code reads CLAUDE.md at the start of every session and, from version 2.1.277, reads a repository's AGENTS.md when no CLAUDE.md is present. A CLAUDE.md can also import AGENTS.md. The same page suggests keeping each file under 200 lines, because longer files consume more context and reduce adherence.
Example
# AGENTS.md
## Commands
- Install: pnpm install
- Test: pnpm test (run before every commit)
- Lint: pnpm lint --fix
## Rules
- Never edit files in /generated.
- Use the existing logger in lib/log.ts, not console.log.
- Database changes need a migration in /migrations.
Where you'll meet it
- Claude Code, which reads
CLAUDE.mdand falls back toAGENTS.md - OpenAI Codex, opencode, Cursor, Gemini CLI and other agents listed on the AGENTS.md site
- Open-source repositories adding agent guidance next to
CONTRIBUTING.md - Monorepos with per-package files
What it changes for you
For developers, it is a cheap fix for repeated mistakes: write the correction down once. For tech leads, it turns tribal knowledge into versioned, reviewable rules. For teams, it should be reviewed in pull requests like code, because a wrong rule is followed confidently every time.
AGENTS.md vs README
README explains the project to people. AGENTS.md gives operational instructions to agents: exact commands, hard rules, things not to touch.
Common mistake
My view: turning the file into a style guide essay. Agents follow short, testable rules ("run X before committing") far better than paragraphs of philosophy. Claude Code's documentation says the file is treated as context and is not enforced, so if a rule matters, also enforce it with a hook or a CI check.
Related terms
Claude Code · Agent memory · Claude Code hooks · Agent skills · Context engineering
Keep the instruction file short and testable, and back any rule that matters with a hook or a CI check.


