What are CLAUDE.md and AGENTS.md?

CLAUDE.md and AGENTS.md are plain text files, versioned in the repository, that give a coding agent the context it would otherwise have to rediscover every session: which commands to run to build and test, how the code is organized, which conventions to follow, what not to touch. AGENTS.md is the convention that emerged as a cross-tool standard (Codex, Cursor, others); CLAUDE.md is the variant that Claude Code reads automatically. Many repositories keep only one, or one importing the other, to avoid duplicating the same rules twice. The benefit shows up most as a project grows and people change: a new team member, human or agent, reads the same file instead of reconstructing conventions from scratch through trial and error. The mirror-image risk is a file left behind by the code: an agent trusting an instruction that is no longer true produces mistakes harder to spot than ones made with no guidance at all.

Why it is not a tooling footnote

An agent without this file starts from zero every time: it tries random commands, guesses conventions from existing code, and often makes mistakes a new human teammate would avoid by reading a README. With CLAUDE.md or AGENTS.md the opposite happens: the agent already knows the test suite runs with a precise command, that visible strings live in two localization files, that a certain folder should not be touched without permission. It is the same work once done for a new developer's onboarding document, applied to a reader that does not forget but also does not infer from implicit human context.

It is real technical documentation, not a prompt

The common mistake is treating this file as a list of generic instructions ("write clean code"). The real value lies in specifics: the exact commands, the paths of critical files, the rules the code alone does not communicate (why a certain architectural choice exists, what happens if a test fails, which file is the source of truth for a given list). Writing it well is engineering work in its own right: it must be updated when the architecture changes, kept in sync with the repository's reality, and a stale file is worse than no file, because the agent trusts what it reads.