CLAUDE.md and AGENTS.md: The Complete Guide

CLAUDE.md and AGENTS.md are markdown files in your repository that a coding agent reads before it edits anything. CLAUDE.md is the file Claude Code loads at the start of every session. AGENTS.md is the open, tool-neutral format read by OpenAI Codex, Cursor, GitHub Copilot, Aider and others. Keep one of them as the source of truth, keep it under about 200 lines, and keep it true: regenerate the parts that describe the code instead of editing them by hand.

Part of the Auto Wiki guide.

What are CLAUDE.md and AGENTS.md?

An agent instructions file is persistent project context: the commands, conventions and boundaries an agent cannot reliably infer from reading code. A README explains the project to a person who reads selectively. An instructions file is loaded into the agent's context at the start of a session and shapes every edit after it.

Without one, an agent falls back on generic habits: it reaches for axios when you have a fetch wrapper, or scaffolds a service in the wrong directory. Anthropic describes CLAUDE.md as context rather than enforced configuration, so a rule that must always hold belongs in a hook or a lint, and the file carries what the agent should know.

CLAUDE.md vs AGENTS.md: which does each agent read?

Use the file your agent expects, and let the other point at it. As of October 2026:

Claude Code reads AGENTS.md directly, but only when no CLAUDE.md exists in the working directory or any parent. If both exist, it reads the CLAUDE.md files and skips AGENTS.md. The documented fix for a repo that serves several agents is a one-line import in CLAUDE.md:

@AGENTS.md

## Claude Code
Anything specific to Claude Code goes below the import.

Now there is one source of truth, and a second file that never drifts from it.

What belongs in the file

Include only what changes a decision the agent makes. If a line would not alter an edit, cut it. Seven things earn their place:

• Purpose: one paragraph on what the repo is, with no marketing.
• Layout: top-level packages, apps and entry points.
• Commands: the exact build, test, lint and typecheck commands, copy-paste ready.
• Code rules: naming, formatting, and explicit "do not" rules the linter cannot enforce.
• Architecture notes: the boundaries and how data flows across them.
• Hazards: files with heavy churn or bug history, and what is coupled to what.
• Workflow: what to inspect first and what to confirm before editing.

How long should it be?

Aim for under 200 lines per file. Anthropic's guidance is that longer files consume more context and reduce adherence, and that imports organize a long file without shrinking its context cost, because imported files load at launch too.

Move instructions that matter for only part of the repo out of the root file. Claude Code supports .claude/rules/ files scoped to file paths, which load only when the agent works on matching files. AGENTS.md handles the same need with nested files in each package: the closest one wins.

Best practices and anti-patterns

The gap between a useful file and a liability is discipline.

Do:

• Write rules a person could check: "run npm run test before committing" beats "write good tests".
• Name risky files so the agent slows down near them.
• Review the file when you refactor. Contradicting instructions get resolved arbitrarily.

Avoid:

• Pasting the README. It duplicates a document the agent can already read.
• Rules the code does not follow. The agent obeys the file, then the code review fails.
• Secrets and credentials. The file is committed and read by every tool.
• Letting the file rot. A line pointing to /lib after the code moved to /core actively misleads, and the agent trusts it.

How do you keep the file current?

Generate the parts that describe the code, and write by hand only the parts that describe your intent. A layout section or a hotspot list is a fact about the repo that changes with every merge. A rule like "never call the payments API outside the billing service" is a decision, and only a person can state it.

repowise draws that line in the file itself. repowise init and repowise update write a managed section from the already-built index, with no LLM call and no API key:

The section sits between REPOWISE:START and REPOWISE:END markers in .claude/CLAUDE.md, and in AGENTS.md when you use Codex, OpenCode or Hermes. Everything outside the markers is yours and is never modified. The generator is deterministic: the same index produces the same bytes, and the target is 150 to 250 lines, so it stays close to the budget above.

pip install repowise
repowise init                          # index, write the managed section, register the MCP server
repowise update                        # after commits: refresh the index and the section
repowise generate-claude-md --stdout   # preview the managed section without writing

The repowise wiki for the repowise repository: the overview and module pages the managed section is summarized from

For a monorepo, repowise generate-claude-md --workspace writes a workspace-level file with cross-repo contracts, co-changes and per-repo summaries. repowise init --no-claude-md or --no-agents-md opts out, and --no-editor-setup indexes without writing any config into the repo.

What a file cannot hold

A static file orients the agent; an index answers the follow-up. Even a well-kept 200 lines cannot say who owns a file, what breaks if it changes, or why a pattern exists. repowise registers its MCP server so Claude Code, Codex and Cursor can ask: get_answer for how and why questions, get_context for a file or symbol, get_risk before an edit, get_why before changing an established pattern.

A SessionStart hook covers the one thing a static file cannot: it adds a short block saying whether the index is current against HEAD, plus the standing decisions most relevant to the files in play. See repowise for AI agents for what the index answers, and the auto-wiki behind it. It parses 28 languages to a full AST.

The CLAUDE.md and AGENTS.md cluster

This guide is the hub. The spokes go deeper:

• How to Generate a CLAUDE.md File for Your Repository: the step-by-step workflow.
• Best Tools to Generate CLAUDE.md and AGENTS.md Files: what to use and what a good file needs.