How to Write a Good CLAUDE.md for Your Company Repository

How to Write a Good CLAUDE.md for Your Company Repository

To write a good CLAUDE.md, record only what Claude Code cannot work out by reading the code: how to run, test and validate the project, conventions that break from the default, limits on what must not be touched, and where to find everything else. Keep the file short and direct, give it a named owner, and review changes the way you review any other file in the repository.

Key takeaways

• CLAUDE.md is context for the agent, not project documentation. It should hold the minimum that changes the agent's behavior.
• What goes in: build and test commands, non-obvious conventions, security limits and pointers to longer documents.
• What stays out: secrets, personal data, descriptions of what the code already shows, generic good-conduct rules and text that goes stale quickly.
• An instruction in the file guides the agent but does not guarantee anything. Rules that cannot fail belong in permissions and hooks, not in a paragraph of text.
• A good file has an owner, goes through pull request review and loses lines as often as it gains them.

What CLAUDE.md is and why size matters

CLAUDE.md is a text file in the repository root that Claude Code reads at the start of a session and keeps in its working context. According to the tool's official documentation, you can also have files in subfolders and a personal file outside the repository, which helps separate company rules, module rules and individual preferences. Check the documentation for the version your team uses to see how that hierarchy is loaded, because the exact behavior can change.

The central point is that everything in the file takes up space in the context window of every session. Anthropic's engineering writing on context engineering for agents describes context as a finite resource and says the goal is to gather the smallest set of high-signal information that leads to the result you want. In practice, a bloated CLAUDE.md has two costs: it spends the model's attention on things that do not matter, and it dilutes the few rules that do.

Think of the file as the page you would hand an experienced developer on their first day. They know how to program. They do not know how this company works.

What goes in the file

A good test for every line: if I remove this, will the agent make a mistake or waste time? If the answer is no, the line does not need to be there. The items below usually pass that test.

• Exact commands to install dependencies, start the environment, run the full test suite, run a single test, format code and check types. Agents guess badly when a project uses its own scripts.
• A definition of done: what must pass before a task counts as finished (tests, lint, migration applied, changelog updated).
• Conventions that do not show up in the code: branch and commit naming, how to handle errors, where shared helpers live, which library to use instead of another that looks equivalent.
• Architecture decisions the agent tends to undo by accident, with the reason in one sentence. Example: do not access the database directly from controllers, because the service layer applies the permission rules.
• Caution zones: generated directories, migration files that have already been applied, and legacy code that should not be refactored without an explicit request.
• Security limits in operational language: never read or print credential files, never run commands against the production environment, ask for confirmation before deleting data.
• Pointers to detail: instead of copying the API guide, say where it lives and when to consult it.

Notice that almost everything here is verifiable. Phrases like "write clean code" are not, which is why they do not belong in the file.

What stays out of the file

The list of what to cut is usually more useful than the list of what to add, because the most common mistake is accumulation.

• Secrets, tokens, passwords, connection strings and any personal data about customers or employees. The file goes into version control and is read by anyone with access to the repository. For Brazilian companies this is also an LGPD (Brazil's data protection law) issue, not just technical hygiene.
• Descriptions of structure the agent can see with a folder listing. Copied directory trees go out of date at the first reorganization.
• A full architecture manual, decision history or people onboarding. Those live in their own documents, and CLAUDE.md only points to them.
• Generic advice such as "be careful", "think before acting" or "follow best practices". It changes nothing and consumes attention.
• Instructions for rare tasks. A release procedure that happens once a quarter works better as a skill loaded on demand. See Claude Code Skills: How to Create Them for Your Team.
• Rules that must be followed every time. Text is guidance, and the model may ignore it at some point. Whatever cannot fail should be enforced by tooling: hooks that apply rules before and after actions, plus permissions and sandboxing, covered in Claude Code security for teams.
• Information that changes every week, such as sprint status, a list of open bugs or who is on call.

A lean structure you can copy

There is no required format, but a stable order makes the file easier to read and review. A suggested set of sections, each only a few lines long:

• Project overview: two or three sentences on what the system does and for whom, just enough for the agent to understand the domain.
• Commands: install, run, test, test one file, format, check types.
• Workflow: how to name branches, how to write commits, what to verify before opening a pull request.
• Code conventions: only what departs from the default of the language or framework.
• Limits: what to never do and what requires human confirmation.
• Where to find more: a list of paths to documents, each with one sentence saying when to consult it.

Write in the imperative with short sentences, and prefer the positive form where you can: "use the internal HTTP client instead of calling the library directly" works better than a bare prohibition. When a rule has a reason, give the reason in a few words. The agent generalizes better when it understands why.

If the repository is a monorepo, keep the root file for what applies to everyone and put each package's details in its own file inside the matching folder. That way, someone working on the API does not load the rules for the mobile app.

How to write it, step by step

This routine works for a new repository and for trimming a file that has already grown too large.

• Start with what the tool generates. Claude Code's initialization command produces a draft from the project. Treat it as a starting point and cut anything that merely describes the obvious.
• Watch a real session. Give the agent a typical task with no extra instructions and note where it goes wrong: wrong command, ignored convention, a file it should not have touched. Each recurring mistake becomes a candidate line.
• Write the shortest possible rule and test it. Repeat the same task with the line added. If the behavior did not change, the line has not earned its place.
• Separate guidance from enforcement. For each critical limit, ask whether a permission or a hook handles it better. If so, configure it and leave only a one-line explanation in the file.
• Move long material out. Extended procedures become skills or referenced documents. CLAUDE.md keeps the pointer.
• Review in a pull request. Every change to the file goes through review, with one simple question: is this still true and still needed?

Illustrative scenario: a monorepo with an API and an admin dashboard

Illustrative scenario: a software company maintains a monorepo with an API and an admin dashboard. The first CLAUDE.md had a complete folder tree, a summary of the product's history and a list of general best practices. In sessions, the agent ran the entire test suite after every small change, because the command for testing a single file was not recorded, and it edited migration files that had already been applied.

The team rewrote the file in short sections. The folder tree, the history and the generic advice came out. In went the command to test a single file, the definition of done, a line saying applied migrations are never edited (a new one is created instead), and a pointer to the API contracts guide. For the migration rule, the team also set up an automatic check, leaving the text only as an explanation. The file became small enough to read in full during a review meeting, and that is what makes it maintainable.

This example is illustrative and does not represent a measured result for any client.

How to keep the file alive without turning it into a dumping ground

CLAUDE.md degrades in a predictable way: someone adds a line after a mistake and nobody removes anything afterward. After a few months, the file contradicts the code. A few simple practices prevent this.

• Name one owner per repository, even if editing is open to everyone.
• Treat the file as code: changes arrive by pull request, with a description of the problem the line solves.
• Reserve a short periodic review for deleting. Every line has to justify its presence again.
• When a mistake repeats, first decide whether the fix is text, a skill, a permission or a hook. Not every mistake should become a sentence in the file.
• If several teams use the tool, standardize a common skeleton and let each team fill in its own. The Claude Code for Teams adoption guide goes into this kind of arrangement.

The method we use in AI projects applies well here. Map: observe how the agent works today and where it goes wrong, before writing any rule. Limit: decide what it can read, run and change, and enforce that with tooling. Pilot: start with one repository and one recurring task, with an agreed success criterion, for example less rework in code review. Transfer: hand over the file with an owner, a review routine and a recorded decision to expand to other repositories, adjust or stop. For the general idea of limiting an agent's scope, Anthropic's engineering articles "Building effective agents" and "Effective harnesses for long-running agents" are worth reading.

One separation helps keep the file technically honest: what comes from official documentation (how the tool loads context), what comes from implementation experience (what tends to work in teams) and what is still a hypothesis (a new rule you are testing). Mark hypotheses with a short comment and remove them if the test shows no effect.

Frequently asked questions

How long should a CLAUDE.md be? There is no right size, but the file should fit in a quick read by one person. If you have to scroll a lot to find a rule, the agent will also struggle to prioritize. Once it grows past that, move procedures into skills or referenced documents.

Can I put passwords, API keys or customer data in the file so the agent can use them? No. The file goes into version control and circulates among many people and tools. Credentials belong in secret managers and environment variables, with permissions that stop the agent from reading them. Personal data requires attention to LGPD and does not belong in a context file.

Does CLAUDE.md guarantee the agent will follow the rules? No. It is context that guides behavior, and the model may fail to follow it in some situation. For rules that cannot fail, such as blocking dangerous commands or requiring tests before finishing, use permissions, sandboxing and hooks, and leave only the explanation of the reason in the file.

Should I have one CLAUDE.md per repository or one for the whole company? The ideal is a common skeleton across repositories and a separate file in each one, with the real commands and conventions of that project. Company-wide rules, such as security and review flow, can be copied from a template, but content specific to a codebase should live next to it so the people who maintain it can review and update it.

Sources

• Anthropic: Effective context engineering for AI agents
• Anthropic: Building effective agents
• Anthropic: Effective harnesses for long-running agents