AGENTS.md and CLAUDE.md: which instruction file does what
AGENTS.md is the vendor-neutral instruction file read by several coding agents; CLAUDE.md is Claude Code’s own. What each is read by, how they interact, and how to keep one source of truth.
AGENTS.md is a vendor-neutral instructions file that several coding agents read; CLAUDE.md is the file Claude Code reads. Both sit in the repository, both are plain Markdown, and both are loaded into the agent's context before it starts work. The practical question is not which is better but how to avoid maintaining two copies of the same rules.
What each file is
| AGENTS.md | CLAUDE.md | |
|---|---|---|
| Read by | Codex CLI, opencode, Amp, Kimi and a growing set of others | Claude Code |
| Scope | Repository root, and nested files for subdirectories | Repository root, plus a user-level file in the home directory |
| Typical content | Build and test commands, project layout, conventions | The same, plus Claude-specific workflow rules |
The one-source-of-truth pattern
Keep the shared rules in AGENTS.md, then make CLAUDE.md a symlink to it, or a short file whose first line points at it. Anything genuinely Claude-specific, such as which slash commands to use, stays in CLAUDE.md below that pointer. This keeps the build commands, the directory map and the conventions in one file, which is where drift starts if you let it.
ln -s AGENTS.md CLAUDE.md # simplest version
git add AGENTS.md CLAUDE.mdWhat belongs in it
- The commands: how to build, how to test, how to run one test.
- The layout: which directory holds what, and what must not import what.
- The conventions the codebase actually follows, including indentation and export style.
- The rules that have teeth: what blocks a commit, what needs a human.
What does not belong is background reading. Every line costs context on every session, so a file that explains the company history is a file that crowds out the build command.
Keeping it honest
Instruction files rot. The test command changes, the file keeps the old one, and every agent spends its first two turns discovering that. Treating the file as code, and reviewing it whenever the build changes, is the only thing that works.
Aura reads both files and adds one more source: the conventions it has learned from your own commit history, such as the indentation and import style your repository actually uses. See the MCP server for how those rules reach the agent.
What is the difference between AGENTS.md and CLAUDE.md?
AGENTS.md is a vendor-neutral instructions file that several coding agents read. CLAUDE.md is the file Claude Code reads. Both are plain Markdown in the repository and both are loaded into the agent’s context; the difference is which tools look for them.
Do I need both AGENTS.md and CLAUDE.md?
Only if you use tools that read different files. The common pattern is one real file and a pointer: keep the content in AGENTS.md and have CLAUDE.md reference it, so there is a single source of truth and no chance of the two drifting apart.
What should go in an AGENTS.md file?
Things an agent cannot infer from the code: how to build and test, which commands are safe to run, conventions the codebase follows but does not enforce, and what is off limits. Not a description of the architecture — the agent can read that.
Does Claude Code read AGENTS.md?
Claude Code looks for CLAUDE.md. Other agents look for AGENTS.md. Because both are just Markdown loaded into context, a one-line CLAUDE.md that points at AGENTS.md gets you both without maintaining two copies.
Aura Crew vs Claude Code Loops: the autonomous work-loop, compared
Claude Code defines four loop types — turn-based, goal, time, and proactive. Aura Crew is the same idea productized: a dependency-ordered work-loop with proof, collision-safety, and any agent. Full comparison.
Autonomous coding agent loops, explained: turn-based, goal, time, and proactive
A coding agent loop is an agent repeating cycles of work until a stop condition is met. The four types explained — turn-based, goal-based, time-based, proactive — with when to use each and how to keep quality high.
How to run multiple coding agents in parallel without merge conflicts
Running several AI coding agents at once collides on shared files. The fix: a worktree per agent, a live team radar, and soft-to-hard zone claims so parallel agents never touch the same symbol. How Aura Crew does it.
Goal-based agent loops: giving a coding agent a definition of done
A goal-based loop keeps a coding agent iterating until a success criterion is met. The trick is a deterministic definition of done — tests, a score, a proof — not an LLM guessing at "good enough." How to write one.