On this page#
- What is a CLAUDE.md file?
- What is shipped and what is roadmap?
- How does it change your repository setup?
- Commands
- Architecture
- Change rules
- Definition of done
- Who does this matter for?
- The detail that matters in a team repository
- FAQ
What is a CLAUDE.md file?#
A CLAUDE.md file is a repository-level instruction file that Claude Code reads to understand how it should work in that codebase. It gives the agent persistent context—commands, architecture rules, conventions, and boundaries—without requiring developers to repeat those instructions in every prompt. It is configuration for the agent, not application code.
The useful mental model is “README for the coding agent,” but a good CLAUDE.md is narrower and more operational than a normal README. It should tell Claude Code how to make acceptable changes, not explain everything a human might want to know about the project.
Claude Code is an agent built on a large language model: a model that generates responses from supplied context rather than possessing a guaranteed, current understanding of your repository. CLAUDE.md improves that context. It does not turn probabilistic output into deterministic enforcement.
Put information there when all three conditions are true:
- The agent needs it repeatedly.
- The rule applies across multiple tasks.
- Violating it would produce a bad or misleading change.
Typical entries include:
- The canonical build, test, lint, and type-check commands.
- Architectural boundaries that are not obvious from directory names.
- Generated files that must not be edited directly.
- Required validation before a change is considered complete.
- Repository-specific naming and dependency rules.
- Locations of authoritative schemas or configuration.
Do not turn the file into a documentation landfill. Long background narratives, obsolete migration notes, and style advice already enforced by tooling consume context while adding little control. The Claude Code documentation is the authority for Claude Code behavior; your file should describe your repository.
Photo by Daniil Komov on Pexels.
What is shipped and what is roadmap?#
The shipped capability is straightforward: Claude Code supports repository instructions through CLAUDE.md. The roadmap claim is much broader—that one Markdown file will become a universal, interchangeable control plane for Claude Code, Codex, Cursor, and every future coding agent. That portability should be treated as an aspiration unless each tool explicitly documents it.
Here is the boundary:
| Claim | Status | Practical meaning |
|---|---|---|
| Claude Code can use CLAUDE.md as persistent project context | Shipped | You can configure Claude Code around repository rules now. |
| Markdown can describe commands and engineering constraints | Shipped | The file can be reviewed and versioned like other repository documentation. |
| Every coding agent will read CLAUDE.md automatically | Not established | Do not assume another tool discovers or interprets it. |
| One instruction file will behave identically across agents | Roadmap-level expectation | Models, context assembly, precedence, and tool permissions differ. |
| Writing a rule guarantees compliance | False | Text guidance is not enforcement. CI and repository permissions remain necessary. |
This distinction matters because teams often mistake “the agent was told” for “the repository is protected.” That is wrong. If an invariant matters—schema compatibility, generated-code integrity, security checks, or test completion—encode it in executable validation as well as prose.
The official Claude Code documentation can define what Claude Code currently supports. It cannot promise how unrelated agents will interpret the same file. A shared Markdown source may still be valuable, but adapters, duplicated files, or generated agent-specific instructions may be required.
Treat cross-agent reuse as a design objective:
- Keep repository facts tool-neutral.
- Keep agent-specific behavior clearly labeled.
- Verify each tool’s documented discovery rules.
- Enforce critical constraints outside the prompt.
- Review instruction changes like configuration changes.
If you are standardizing a serious repository, the Full Foundry is the relevant PairFoundry path: the hard part is not creating one Markdown file, but designing the surrounding operating system of instructions, validation, and review.
How does it change your repository setup?#
Add CLAUDE.md at the repository level where Claude Code is expected to discover project instructions, then make the smallest necessary supporting changes to executable checks. The file should point to existing sources of truth rather than copying them, and every critical instruction should correspond to a command, policy, or clearly reviewable rule.
A compact starting structure looks like this:
# Repository instructions
*Photo by Daniil Komov on [Pexels](https://www.pexels.com/photo/laptop-with-coding-software-and-coffee-mug-34803973/).*
## Commands
- Install:
- Test:
- Lint:
- Type-check:
## Architecture
- Source of truth:
- Dependency boundaries:
- Generated code:
*Photo by panumas nikhomkhai on [Pexels](https://www.pexels.com/photo/data-center-server-racks-with-active-equipment-37730212/).*
## Change rules
- Required checks:
- Files not to edit directly:
- Documentation requirements:
## Definition of done
- Tests pass.
- Types pass.
- Generated artifacts are current.The empty fields are intentional here; populate them only with facts from your repository. Do not invent a command because it looks conventional. A wrong command in persistent instructions is worse than no command because it repeatedly sends the agent down the same false path.
You may also need to change:
- CI configuration, if required checks are not already automated.
- Package or task scripts, if the canonical commands are difficult to discover.
- Ownership rules, if instruction changes need designated reviewers.
- Contributor documentation, if humans must follow the same workflow.
- Ignore rules only when they match your team’s intended ownership model.
A committed CLAUDE.md is appropriate for shared repository rules. Personal preferences do not belong in a shared control file. “Use this formatter” may be a repository rule; “explain every edit to me in five bullets” is a user preference.
The strongest setup uses three layers:
CLAUDE.mdexplains the expected behavior.- Scripts provide one canonical way to validate it.
- CI rejects changes that violate non-negotiable invariants.
That separation keeps prose concise and enforcement real. PairFoundry’s Foundations track is the sensible next step if your repository does not yet have clear commands or a stable definition of done. The broader packs overview is useful when the missing piece is a repeatable team workflow rather than a single file.
Who does this matter for?#
A CLAUDE.md file matters most to engineers using Claude Code repeatedly in a repository with stable commands, architectural boundaries, or costly failure modes. It matters less in disposable experiments, and it cannot rescue a codebase whose own maintainers cannot identify the source of truth.
The highest-value cases are:
- Mature application repositories: Multiple subsystems make implicit boundaries easy to violate.
- Monorepos: The correct test and build commands vary by package or scope.
- Generated-code repositories: Editing an output instead of its schema or generator creates misleading diffs.
- Regulated or security-sensitive code: Required checks must be visible, though still enforced elsewhere.
- Multi-agent teams: Persistent repository facts reduce repeated prompting, but tool-specific behavior must remain explicit.
- Legacy systems: Non-obvious constraints need concise explanations close to the work.
It is lower priority for a short-lived prototype with one obvious command and no meaningful invariants. Even there, a tiny file can help, but creating a comprehensive policy document would be ceremony without leverage.
The decision test is simple: list the mistakes an otherwise capable agent could make because the repository does not reveal its rules locally. If that list includes recurring, expensive errors, write the file. If it contains only stylistic preferences already enforced by a formatter, improve the tooling instead.
For continuing notes about agent-specific mechanics and boundaries, use PairFoundry’s tool notes rather than bloating repository instructions with general industry commentary.
The detail that matters in a team repository#
In a team repository, CLAUDE.md is shared executable-adjacent configuration even though it is written in prose. A solo developer can change it casually and absorb the consequences. In a team, one ambiguous sentence can alter how every Claude Code-assisted change is planned, edited, and validated.
The central problem is instruction ownership.
A developer may add a rule to solve one immediate task, then commit it as though it were universally correct. Future sessions inherit that local workaround. Because the file looks like documentation, reviewers may skim it even though its behavioral impact can exceed that of an ordinary comment.
Use these controls:
- Assign reviewers who understand repository architecture.
- Require instruction changes to explain which recurring failure they prevent.
- Prefer commands and file paths over adjectives such as “carefully” or “properly.”
- Remove obsolete rules during migrations.
- Separate universal repository facts from temporary task instructions.
- Keep critical rules backed by CI.
- Review contradictory instructions before adding more text.
Bad:
Always update all related files and test thoroughly.Better:
When the public schema changes, update the generated client through the
repository generator. Do not edit generated client files directly. Run the
canonical schema check before completion.The second version identifies a trigger, a prohibited action, and a validation obligation. That is reviewable. The first merely sounds responsible.
Also watch for silent conflicts. A command renamed in package configuration but not in CLAUDE.md creates persistent failure. An architecture rule copied from another document can drift. Link to the authoritative location when possible, and duplicate only the minimum needed for correct action.
The file belongs in the same change-control conversation as CI, ownership, and contributor policy. Treating it as harmless prompt text is the mistake that works for one person and fails for a team.
Related reading#
- No coding AI agent — the detail that matters in a team repo
- Claude Code auto mode — the detail that matters in a team repo
FAQ#
What is a CLAUDE MD file?#
A CLAUDE.md file is a Markdown instruction file used by Claude Code to obtain persistent context about a repository. It commonly records canonical commands, architectural boundaries, prohibited edits, and completion checks.
What is the MD file for Claude AI?#
For Claude Code, the Markdown file provides project-specific working instructions. It does not modify the model or enforce repository policy by itself; it supplies context that should be paired with scripts, CI, and permissions.
Can you upload MD files to CLAUDE?#
Claude can work with Markdown content when the relevant interface accepts files or supplies that content as context. That is separate from Claude Code’s repository-level CLAUDE.md convention, which is designed to provide persistent project instructions.
Is a CLAUDE MD file needed?#
No. Claude Code can operate without one. It becomes valuable when a repository has recurring commands, non-obvious architecture, generated files, or validation requirements that should not be restated in every task.
Is a CLAUDE MD file necessary?#
It is not universally necessary, but it is often justified in a production repository with real invariants. Keep it concise, version it with the code, review team changes, and never use it as a substitute for automated enforcement.