Where should a CLAUDE.md file live?

The repository root, committed to version control, for anything the whole team needs. Keep personal preferences in your own home-directory memory file so they do not become team policy by accident.

Does a large CLAUDE.md file slow the agent down or cost more?

Yes, in the sense that every token in it is re-sent as part of the context for the session and dilutes attention across more instructions. Long files are also where contradictions hide. Cutting an unread section usually improves behaviour and cost at once.

Can CLAUDE.md be used maliciously?

It can carry an instruction that weakens a safeguard, and it is a natural target for indirect prompt injection because the model treats it as trusted guidance. The mitigation is ordinary change control — an owner, a review, and a way to detect local edits.

Agent artifacts

CLAUDE.md

definition

CLAUDE.md is a Markdown file that Claude Code loads automatically at the start of a session, giving the model persistent project instructions, conventions, and context.

In depth

CLAUDE.md is the simplest and most effective way to change how an agent behaves in a repository. It holds the things a new engineer would need to be told: how to run the tests, which directories are generated, what the deploy path is, which patterns the team has rejected. Because it is loaded before the first prompt, it shapes every subsequent decision the model makes.

Files resolve as a hierarchy rather than a single location. Claude Code reads memory from enterprise-managed policy, from the user's home directory (`~/.claude/CLAUDE.md`, applying across all their projects), and from the project itself — walking up from the working directory so a file in a subdirectory can add local detail on top of the repository-wide file. Files can also pull in others with `@path/to/file` imports, which keeps a long guide modular.

The practical craft is restraint. Everything in CLAUDE.md occupies context in every session, competing with the actual task, and instructions that are vague or aspirational get ignored while sounding authoritative. Specific, verifiable, imperative statements work; a mission statement does not.

Equivalents exist across the ecosystem — `AGENTS.md` has emerged as a cross-tool convention, and other assistants read their own rule files. The mechanism generalises: a plain-text file in the repository that silently steers an AI agent.

Why it matters for governance

CLAUDE.md is executable policy written in prose, and it is usually the least-reviewed file in the repository. Anyone who can open a pull request can propose an instruction the agent will follow in every future session — 'skip the pre-commit hook when it is slow', or worse. Because it is loaded rather than run, it does not show up in any dependency scan. Treat it as a governed artifact: versioned, reviewed by an owner, distributed centrally, and diffable against what each machine actually has on disk.

Frequently asked

Where should a CLAUDE.md file live?: The repository root, committed to version control, for anything the whole team needs. Keep personal preferences in your own home-directory memory file so they do not become team policy by accident.
Does a large CLAUDE.md file slow the agent down or cost more?: Yes, in the sense that every token in it is re-sent as part of the context for the session and dilutes attention across more instructions. Long files are also where contradictions hide. Cutting an unread section usually improves behaviour and cost at once.
Can CLAUDE.md be used maliciously?: It can carry an instruction that weakens a safeguard, and it is a natural target for indirect prompt injection because the model treats it as trusted guidance. The mitigation is ordinary change control — an owner, a review, and a way to detect local edits.

Sources

Primary sources for the claims on this page. Specifications and vendor documentation change — verify against the source if a detail is load-bearing for a decision you are making.