Claude Code now reads AGENTS.md: one instruction file for every AI coding tool
TL;DR
Teams running several AI coding tools often maintain several config files (CLAUDE.md, .cursor/rules, AGENTS.md…). Claude Code now reads AGENTS.md when a folder has no CLAUDE.md, so one instruction file can serve multiple tools.
Teams using several AI coding tools often maintain several nearly identical instruction files: CLAUDE.md for Claude Code, .cursor/rules for Cursor, AGENTS.md for other tools. Every convention change means editing several places, and they gradually drift apart. Claude Code now reads AGENTS.md when a folder has no CLAUDE.md, so one instruction file can be shared across tools.
What changed
| Point | Detail |
|---|---|
| Version | Claude Code 2.1.277 |
| Priority | CLAUDE.md takes priority; AGENTS.md is only used in folders without a CLAUDE.md |
| Customisation | Use /config to choose reading AGENTS.md, CLAUDE.md or both |
| Exceptions | The session must be able to fetch feature flags from Anthropic; via Bedrock/other providers or with telemetry disabled it falls back to CLAUDE.md |
| AGENTS.md | An open standard, plain Markdown, placed at the repo root; stewarded by the Agentic AI Foundation (part of the Linux Foundation) |
What should go in AGENTS.md?
It's the document a "new colleague", human or machine, needs to work in the repo:
- Key commands: install, build, run tests, lint, run a single test.
- Folder structure: which parts are core code, which are generated and must not be edited.
- Code conventions: naming, formatting, error handling, allowed/forbidden libraries.
- Workflow: branch naming, commit format, requirements before opening a PR.
- Don'ts: don't touch old migrations, don't commit secrets, don't edit file X.
# AGENTS.md
## Build & test
- Install: `pnpm install`
- Test: `pnpm test` (one file: `pnpm test path/to/file`)
- Lint: `pnpm lint`, must be clean before committing
## Conventions
- TypeScript strict; no `any` without an explanatory comment
- Components live in `src/components/<Name>/`
## Don't
- Don't edit `src/generated/` (auto-generated)
- Don't commit `.env` filesStrategy for repos using several tools
- Put the shared instructions in AGENTS.md.
- Keep CLAUDE.md thin for Claude-only parts (hooks, skills, subagents, permissions), pointing to AGENTS.md for the shared part.
- Test on each tool: the same instruction can be interpreted differently by different agents.
- Put AGENTS.md through review as an important document, not a casual note.
Caveats
- Keep it short: instruction files are loaded into context. The longer, the more tokens and the more likely to be ignored; only write what the agent can't infer.
- Avoid contradictions: if a folder has both files, CLAUDE.md wins; don't let the two say different things.
- Check your environment: if your team uses Bedrock or disables telemetry, AGENTS.md behaviour may differ; test it rather than assume.
How to apply it
- Dev: move shared content from CLAUDE.md into AGENTS.md, leaving the Claude-specific part.
- Tech Lead: treat AGENTS.md as onboarding documentation written for both humans and machines; a good test is whether a newcomer can get work done with it.
- PM: a single source of truth lowers maintenance cost when the team changes or adds AI tools.