CLAUDE.md: What It Is and Why Your Team Needs One
CLAUDE.md is the single highest-leverage thing an engineering team can do to make AI tools work reliably. Here is what to put in it, what to leave out, and how to keep it alive.
A CLAUDE.md is a file in the root of your repository that tells AI tools what your codebase is, how it is organised, and how to work within it effectively. It is not documentation. It is context infrastructure: the foundation that determines whether AI tools in your codebase produce architecturally consistent output or architecturally coherent nonsense.
Most engineering teams that have adopted AI tools do not have one. This single gap explains a significant share of the frustration teams report with AI coding tools: the experience of getting output that is technically correct but wrong for their system. Wrong patterns, wrong conventions, wrong assumptions about how the codebase handles state, errors, or shared logic. The tools are not broken. They have no context to work from.
A well-maintained CLAUDE.md changes this. It is also the single fastest improvement most teams can make to move from AI-assisted to AI-native engineering.
What a CLAUDE.md Actually Does
The name comes from Anthropic's Claude model, which reads this file automatically when it is present in a repository. Other tools read it too: Cursor uses .cursorrules, GitHub Copilot reads context from the workspace, and most modern AI coding tools have some mechanism for repository-level context. The CLAUDE.md convention has become the de facto standard because it is explicit, readable by any tool, and maintained as a first-class file rather than hidden configuration.
What it does is straightforward. When an AI tool starts working in your codebase, before it reads a single line of your actual code, it reads the CLAUDE.md. This gives it a baseline understanding of the system: what it does, how it is organised, what conventions govern how code is written, and what constraints apply. Every subsequent suggestion the tool makes is informed by this context.
Without this context, AI tools infer from what they can see locally. They look at the files immediately around the task, the patterns in the nearest components, the conventions in the code they have been given direct access to. If that local area is well-maintained and representative of the whole codebase, the output may be fine. If it is not, or if the AI is working in a less familiar area, the output reflects the local context rather than the intended architecture of the system.
The practical difference is significant. Teams with a CLAUDE.md consistently report that AI tools produce output that fits their system rather than output that needs to be corrected for architectural consistency. The time saved is not just in writing code. It is in review: code that fits the system requires less correction and less back-and-forth than code that is structurally out of place.
What to Put in Your CLAUDE.md
The goal of a CLAUDE.md is to give an AI tool the context a well-informed senior engineer would have before starting work in the codebase. That framing is useful because it tells you what to include: the things a new senior engineer would need to know that are not obvious from reading the code alone.
System overview. Start with what the system does, who uses it, and what the core domains are. Two to four sentences is enough. The goal is not comprehensive product documentation. The goal is to tell the AI what kind of system this is so it can calibrate its defaults. A payment processing system has different correctness requirements than a content management system. The AI should know which one it is working in.
Architecture and major components. Describe the high-level structure of the codebase: what the major components are, what each is responsible for, and how they relate to each other. This does not need to be exhaustive. It needs to be accurate. If your system has a service boundary that AI tools should respect, describe it. If there is shared state that requires special handling, note it. If certain components have known technical debt that influences how new code should be written, say so.
Conventions and standards. List the conventions that govern how code is written in this codebase: naming patterns, file organisation, testing approach, error handling patterns, logging conventions. These are the things that experienced engineers on the team do automatically and new engineers take time to pick up. AI tools pick them up immediately if they are written down. Without this, the AI defaults to whatever conventions are most common in its training data, which may not match yours.
Key constraints and anti-patterns. What should not be done in this codebase? Are there architectural boundaries that should not be crossed? Libraries that should not be used for specific purposes? Patterns that were tried and abandoned? Explicitly stating these prevents AI tools from helpfully introducing things the team has deliberately avoided.
Testing expectations. Describe what the test suite covers, how tests are organised, and what the expectations are for new code. This is particularly important for agent-ready test infrastructure. If tests should be written before implementation, say so. If there are specific testing patterns for different types of components, document them. AI tools that understand your testing expectations produce test code that actually fits the suite rather than test code that looks plausible but misses your conventions.
What to Leave Out
A CLAUDE.md that tries to document everything becomes a document that nobody maintains and nobody trusts. The usefulness of the file depends on its accuracy, which depends on it being short enough to update when things change.
Leave out detailed API documentation. Your code and your actual documentation systems are better sources for that level of detail. The CLAUDE.md should describe patterns and constraints, not enumerate endpoints or function signatures.
Leave out historical context that does not affect how new code should be written. The story of why the system was built a certain way seven years ago is interesting background but not useful context for an AI tool making decisions about a new feature today.
Leave out aspirational architecture. Document the system as it is, not as you intend it to be. An AI tool that reads about a clean layered architecture and then encounters a codebase that does not match it will produce output that reflects the documentation rather than the reality, which is worse than no documentation at all.
The test for whether something belongs in the CLAUDE.md: would a senior engineer making a contribution need to know this? If yes, it goes in. If it can be inferred from reading the code, it probably does not need to be stated explicitly.
How to Keep It Accurate Over Time
An outdated CLAUDE.md is worse than no CLAUDE.md. If the file describes conventions the team has abandoned or constraints that no longer apply, AI tools will produce output that is inconsistent with the actual current state of the system. The context infrastructure becomes misleading rather than helpful.
Keeping the file accurate requires making it part of the workflow for significant changes. The two moments when the CLAUDE.md should be updated: when a new architectural decision changes how new code should be written, and when a convention is explicitly changed or deprecated.
The practical mechanism for this is the same as for any shared document: put it in the review checklist. When a PR introduces a meaningful architectural change, the review should include a question about whether the CLAUDE.md needs to be updated. This is a low-overhead addition to review that prevents the file from drifting.
The file does not need to be comprehensive and it does not need to be perfect. It needs to be accurate on the things it does cover. A CLAUDE.md that is 200 lines of accurate, relevant context is more valuable than a 2,000-line document where accuracy is uncertain.
The Difference It Makes in Practice
Teams that build and maintain a CLAUDE.md consistently report three changes in how AI tools perform in their codebase.
First, output consistency. Code produced by AI tools respects the patterns and conventions of the codebase rather than defaulting to generic patterns from the model's training data. This reduces the rework that comes from architecturally inconsistent suggestions.
Second, review efficiency. When AI-generated code fits the system's patterns, review can focus on logic and correctness rather than on structural cleanup. The review process scales better with higher AI-generated output volumes when the output is architecturally consistent to begin with.
Third, agent reliability. If your team is moving toward agentic workflows, where agents operate on tickets end-to-end rather than just assisting individual engineers, the CLAUDE.md is not optional. Agents working without context make architectural decisions based on local inference. At the volume that agents operate, architecturally inconsistent output compounds quickly. With a CLAUDE.md, agents have the same starting context a senior engineer would have and produce output that reflects it.
The connection to the broader AI-native transition is direct. Context infrastructure is the first of the four capabilities that separate AI-native engineering from AI-assisted engineering. The AI-Native Engineering Guide covers all four. The CLAUDE.md is the specific, tangible starting point for building that first capability.
If your team does not have one, this is the highest-leverage thing you can add this week. It takes a focused half-day to write the first version and improves every subsequent AI-assisted engineering task in the codebase.
I help engineering teams close the gap between "we use AI tools" and "AI actually changed how we deliver." Book a 20-minute call and I'll tell you where the leverage is.
Working on something similar?
I work with founders and engineering leaders who want to close the gap between what their technology can do and what it's actually delivering.