What these files actually are

There are really two kinds of file here: instructions (what the agent should know and do) and config (what it is allowed to run and connectto). In a Claude Code project they sit like this.

your-repo/
├── CLAUDE.md               # main instructions, read every session
├── AGENTS.md               # cross-tool instructions (optional)
├── .mcp.json               # shared MCP servers (tools/data connections)
├── .claude/
│   ├── settings.json       # permissions, hooks, env (team, committed)
│   ├── settings.local.json # your personal overrides (git ignored)
│   ├── rules/              # focused rule files, loaded as memory
│   ├── commands/           # custom /slash-commands
│   ├── agents/             # custom subagents
│   └── skills/             # on-demand skills (SKILL.md each)
└── packages/
   └── payments/
       └── CLAUDE.md       # instructions scoped to this package

CLAUDE.md is the headline act. It is Claude Code's native memory file: plain Markdown, read into context at the start of every conversation. Build commands, code style, workflow rules, the stuff the agent cannot infer from the code itself.

AGENTS.md is the same idea, but vendor-neutral. It is an open standard, a "README for agents,"formalized in August 2025 by the OpenAI Codex team together with Google, Cursor, Factory and others, and handed to the Linux Foundation's Agentic AIFoundation in December 2025. Tens of thousands of open-source projects now ship one, and 20-plus tools read it natively: Codex, Cursor, Copilot, Gemini CLI,Aider, Zed, Windsurf and more. If your teams use a mix of tools, this is the file that speaks to all of them.

The .claude/ directory holds the machinery: settings.json for permissions and hooks, commands/ for reusable slash commands, agents/for custom subagents, skills/ for capabilities loaded only when relevant. And .mcp.json declares the MCP servers, the connections that give your agent access to your issue tracker, your database, your internal docs.

How Claude catches them

Here is the part that surprises people: there is no registration step. You do not tell the agent these files exist. Discovery is by fixed name and location. Claude walks the directory tree, finds CLAUDE.md, reads .claude/settings.json, spots .mcp.json at the root, and loads the rules/, commands/ and agents/folders. Name a file correctly and place it correctly, and it works. Get either wrong and it silently does nothing, which is why the convention matters.

Files do not overwrite each other. They stack. Everything discovered is concatenated, ordered from the filesystem root down to your working directory, so more specific instructions come last and carry the most weight.

 ┌─────────────────────────────────────────────┐
 │ MANAGED POLICY  (IT-deployed, unoverridable)│  ← wins, always
 ├─────────────────────────────────────────────┤
 │ PROJECT   ./CLAUDE.md  (committed, shared)  │
 │   └─ nested packages/*/CLAUDE.md (on demand)│
 ├─────────────────────────────────────────────┤
 │ USER     ~/.claude/CLAUDE.md  (your machine)│
 ├─────────────────────────────────────────────┤
 │ LOCAL     ./CLAUDE.local.md  (git ignored)  │
 └─────────────────────────────────────────────┘
      concatenated, root-to-cwd,specific wins

In a mono repo this is the useful bit. Claude loads every CLAUDE.md above your working directory at launch, and pulls in the ones below on demandwhen it actually reads files in that subtree. So a developer working in packages/payments/gets the root instructions plus the payments-specific ones, and nothing from the twelve other packages they are not touching.

Two things worth knowing. First, executable config is gated.The first time you open an untrusted repo, its .mcp.json servers andhooks do not run until you accept a trust prompt. Pulling a repository never silently executes someone else's tooling on your machine, which is exactly the

property you want when config travels through git. Second, Claude Code reads CLAUDE.md, not AGENTS.md. If you want one file to serve both, put a single line at the top of CLAUDE.md, @AGENTS.md, and Claude imports it. That import syntax works for any file (@docs/testing.md),resolves relative to the file it sits in, and goes four levels deep.

What to put in them

The most common mistake is treating CLAUDE.md as documentation. It is not. It is a behavior file, and every line you add dilutes the ones that matter. Anthropic's own guidance is blunt about the test to apply to each line: would removing this cause the agent to make a mistake?If not, cut it. Bloated files cause the agent to ignore your actual instructions. Practitioners push harder still, aiming to keep these files under a couple of hundred lines, because frontier models reliably follow only so many instructions before the list becomes wallpaper.

So the rule is high signal only. Include the things the agent cannot guess and would get wrong.

#CLAUDE.md  (annotated skeleton)

## Commands            ← the non-obvious ones only
- Build:  pnpm build              (Turbo-cached, never `npm`)
- Test:   pnpm test -F <pkg>"x"  (scoped; don't run the full suite)
- Lint:   pnpm lint --fix

## Architecture        ← the map, not a file-by-file tour
- apps/api talks to packages/core; core imports nothing upward
- Auth lives in packages/identity. Do not duplicate it.

## Conventions         ← where you differ from the default
- ES modules only (import/export), never require()
- Conventional Commits; branch names feat/*, fix/*

## Guardrails          ← the landmines, stated as hard rules
- NEVER touch the generated/ folder by hand
- YOU MUST run type check before declaring a change done

## Pointers            ← progressive disclosure, not inlining
- Deploy steps:  see agent_docs/deploy.md
- Data model:    see packages/core/schema.ts

‍

Real projects prove the pattern. The openai/codex repo encodes hard lint rules ("collapse if statements","make match exhaustive") plus a flat security guardrail forbidding edits to a sandbox variable. apache/airflow tells agents to write "Dag" in title case and never to run pytest on the host, only through its breeze wrapper. cloudflare/workers-sdk declares "use pnpm, never npm or yarn" and gives scoped test commands. temporal io/temporal opens with a persona and a mandatory review gate. get sentry/sentry uses its file to settle governance outright: AGENTS.md is the single source of truth, do not add to CLAUDE.md or the Cursor rules.

Notice what is absent from all of them: no restating of language basics, no file-by-file walkthroughs, no "write clean code."Two more moves keep these files lean. Push code-style rules into your linter, which is faster and cheaper than nagging the agent in prose. And use pointers over copies: reference file:line or a doc path rather than pasting a snippet that goes stale the moment someone edits the real thing.Anything that must happen every single time belongs in a hook, not advisory text. Anything occasional belongs in a skill, loaded only when relevant.

Distributing across many repos and teams

Now the part that actually matters at scale. How do fifty repos and twelve teams end up with consistent, current config?

The base case is almost anticlimactic: it is just git. These are committed files. Someone opens a pull request that improves CLAUDE.md, it gets reviewed like any code change, it merges, and every developer and agent on the next pull is upgraded. The only discipline is knowing what to commit and what to keep personal.

  COMMITTED (shared)          GIT IGNORED (personal)
  ─────────────────           ─────────────────────
  CLAUDE.md                   CLAUDE.local.md
  AGENTS.md                   .claude/settings.local.json
  .claude/settings.json         (secrets, personal prefs;
  .claude/rules|commands|        Claude auto-ignores it)
    agents/
  .mcp.json

Across many repos, git alone leaves you with drift: one team writes twenty tidy lines, another writes five hundred contradictory ones. A few patterns fix that, and they trade off cleanly.

 ORG-WIDE                          PER-REPO
  ┌──────────────────┐
  │ Managed policy   │  IT-deployed via MDM / Ansible /
  │ CLAUDE.md +      │  dev-container image. Uncircumventable
  │ managed-settings │  security + compliance baseline.
  └───────┬──────────┘  Machine-level, not repo-specific.
          │  inherited by every machine
          ▼
  ┌──────────────────┐   ┌──────────────────┐
  │.github / template│──▶│ new-service repo │  bootstraps with
  │ repo (starter    │   │ .claude/ + CLAUDE│  gooddefaults
  │ CLAUDE.md, MCP)  │   │from first commit │  at creation time
  └──────────────────┘   └──────────────────┘
          │  template change
          ▼
  ┌──────────────────┐    sync script + GitHub Action fans the
  │ shared DX repo   │──▶ update out to every repo via automated
  │ (canonical rules)│    PRs. Real drift control, you maintain it.
  └──────────────────┘

Managed policy is the strongest lever. Ship a policy-level CLAUDE.md and managed-settings.json to every machine through your device management, and it cannot be overridden by any individual setting. Use it for the non-negotiables: security rules, blocked tools, compliance baselines. It is machine-level, not repo-aware, so keep project specifics out of it.

Template repositories are the cheapest win. Put a starter .claude/and CLAUDE.md, plus your approved MCP servers, into a .github or template repo, and every new service is agent-ready from its first commit.The catch is that templates apply at creation and then drift, so pair them with a shared developer-experience repo that holds the canonical rules and a sync script. A GitHub Action fans changes out as automated pull requests when the template updates, which turns "please copy the new rules" into are view queue instead of a hope. For a mono repo you often need none of this:nested CLAUDE.md files per package, plus one root file, already give each team local control with shared defaults.

Whatever you choose, treat it as code. Review config changes in PRs, add a small CI check that asserts the required fields exist and no blocked MCP server sneaks in, and prune regularly. Claude Code's own /doctor will even propose trims by stripping what the agent can already derive from the codebase and keeping the pitfalls.

The payoff

Do this and something quietly shifts. Onboarding a new e ngineer stops being a week of "oh, you also need to know"conversations, because the repo tells them. Onboarding a new agent, or a newagent tool, stops being anything at all, because it reads the same files. Yourconventions become versioned, reviewed, and enforced instead of remembered.

The whole move is unglamorous, which is why most teams skip it and then wonder why their AI keeps running the wrong test command. Write itdown. Commit it. Let git do the distributing. That is the entire trick, and itis the difference between an agent that guesses at your codebase and one that already knows it.