CLAUDE.md & AGENTS.md: The Complete Guide
CLAUDE.md and AGENTS.md are plain-markdown instruction files that coding agents read before they touch your repo. They carry the conventions, commands, architecture notes, and risk flags an agent needs to make changes that fit your codebase instead of guessing. The hard part is not writing one — it is keeping it true as the code moves, which is where automatic regeneration on each index earns its place.
Part of the Auto Wiki guide.
What are CLAUDE.md and AGENTS.md?
CLAUDE.md and AGENTS.md are cross-agent context files checked into a repository's root. They tell AI coding agents how the codebase is shaped — its build and test commands, coding conventions, architectural boundaries, and risky files — so the agent works from real repo facts instead of inference. CLAUDE.md is read by Anthropic's Claude Code; AGENTS.md is the tool-neutral equivalent.
The two files solve the same problem from slightly different angles. A README explains the project to a human who will read selectively. An agent instructions file is loaded at the start of a session and shapes every edit that follows.
That difference matters. When an agent has no repo context, it falls back on generic patterns — reaching for axios when you have a custom fetch wrapper, or scaffolding a service in the wrong directory.
What goes in them
A good file is short and high-signal. It answers three questions: what is this repo, how do I work in it, and where are the hazards.
The core fields are stable across both formats:
- Project purpose — one paragraph, no marketing.
- Repo layout — top-level packages, apps, services, and entry points.
- Build and test commands — exact commands, not guesses.
- Code rules — naming, formatting, lint, and explicit "do not" rules.
- Architecture notes — major boundaries and how data flows.
- Risk flags — high-churn files, ownership gaps, and change coupling.
- Agent workflow — what to inspect first and what to ask before editing.
Everything else is noise. If a line does not change a decision the agent makes, cut it.
CLAUDE.md vs AGENTS.md
The files overlap heavily. The practical question is which agent expects which name — and whether you need both.
| Aspect | CLAUDE.md | AGENTS.md |
|---|---|---|
| Primary consumer | Anthropic's Claude Code | Any agent that adopts the open format |
| Scope | Project memory, loaded at session start | Repo instructions, tool-neutral |
| Format | Plain markdown | Plain markdown |
| Hierarchy | Supports nested/imported files | Supports nested per-directory files |
| Best when | Your team standardizes on Claude Code | You support multiple agents |
| Source of truth | One file, mirrored if needed | One file, mirrored if needed |
If you support both, keep one source of truth and mirror it. Two files that drift apart are worse than one file that is current.
AGENTS.md as the emerging cross-agent standard
CLAUDE.md came first and is tied to one tool. AGENTS.md is the attempt to make agent instructions portable, so the same file works whether the developer is driving Claude Code, an editor agent, or a CI bot.
The value of a standard is obvious once a team uses more than one agent. Without it, every tool wants its own context file, and you maintain the same facts in three places.
A tool-neutral file also makes the instructions a contract rather than a note. It says: here is how this repo works, and any agent operating here should follow it.
The format is still settling, but the direction is clear. Treat AGENTS.md as the shared layer and any tool-specific file as a thin mirror.
Best practices and anti-patterns
The difference between a useful file and a liability is discipline. A few rules hold up across repos.
Do:
- Keep the root file short — favor paths, commands, and rules over prose.
- State exact commands the agent can run verbatim.
- Name the risky files explicitly so the agent slows down near them.
- Split deep, module-specific rules into nested files.
Avoid:
- Dumping README content into the file — it is duplication, not signal.
- Writing aspirational rules the code does not actually follow.
- Embedding secrets or credentials.
- Letting the file rot after a refactor, which is the most common failure.
That last anti-pattern is the one that quietly breaks everything. A file that points to /lib after the code moved to /core will actively mislead the agent. Stale context is worse than no context, because the agent trusts it.
Keeping the file fresh automatically
Manual maintenance loses. Codebases change every day, and a file that depends on someone remembering to update it will drift the moment a PR merges.
This is the problem repowise is built to solve. Instead of treating the instructions file as a static artifact, repowise derives it from your source code and git history, then regenerates the codebase-intelligence section on each index. Re-running the index after a commit refreshes the architecture map, entry points, hotspots, and conventions from the real state of the code.
Because the file is regenerated rather than hand-edited, it does not rot between releases. The same intelligence that writes the file also powers the auto-wiki, so the agent gets a current map and a queryable index from one model of the repo.
repowise parses 15 languages, so a polyglot monorepo gets one consistent file rather than a patchwork. The generated section also documents the 9 MCP tools an agent can call for deeper, on-demand context — risk, ownership, dead code, and decision history — beyond what fits in a static file. repowise is open source under AGPL-3.0.
The shape that holds up: a concise, regenerated root file for orientation, plus a live index the agent queries when it needs more than the file can hold.
The CLAUDE.md & AGENTS.md cluster
This guide is the hub. The spokes below go deeper on generating and comparing tools:
- How to Generate a CLAUDE.md File for Your Repository — the step-by-step generation workflow.
- Best Tools to Generate CLAUDE.md / AGENTS.md Files — what to use, what to avoid, and what a good file needs.
Last reviewed: June 2026
FAQ
What is the difference between CLAUDE.md and AGENTS.md?
Both are plain-markdown instruction files for coding agents. CLAUDE.md is read by Anthropic's Claude Code, while AGENTS.md is the tool-neutral format meant to work across agents. The contents overlap almost entirely; the main difference is which agent expects which filename.
What should I put in a CLAUDE.md file?
Keep it to high-signal facts: project purpose, repo layout, exact build and test commands, code rules, architecture notes, and risk flags for high-churn files. Avoid duplicating your README or adding rules the code does not actually follow.
How do I keep CLAUDE.md from going stale?
Regenerate it from real repo data instead of editing by hand. repowise regenerates the codebase-intelligence section on each index, so re-indexing after a commit refreshes the architecture, entry points, and hotspots automatically rather than relying on someone to remember.
Should I use CLAUDE.md or AGENTS.md?
Use the file your agent expects. If you only use Claude Code, CLAUDE.md is enough. If you support multiple agents, treat AGENTS.md as the shared source of truth and mirror a tool-specific file from it so the two never drift apart.
Does repowise send my whole codebase to an LLM to generate the file?
No. repowise does local static analysis and git mining first, then synthesizes a summary from that metadata. It also exposes 9 MCP tools so an agent can query deeper context on demand instead of stuffing everything into one file. repowise is open source under AGPL-3.0.
