# CLAUDE.md File Best Practices for Production Teams

> Write a CLAUDE.md that keeps Claude Code useful in production: scope memory, keep rules concise, move enforcement to hooks, and review drift.

Source: https://dvnc.dev/blog/claude-md-file-best-practices-production-teams

---

:::intro
A production `CLAUDE.md` should behave like a tight project briefing, not a giant policy manual. Put the durable context Claude Code needs in every session there, then enforce risky behavior with hooks, settings, permissions, and review gates.
:::

## The Production Rule For CLAUDE.md

`CLAUDE.md` is memory, not enforcement. [Anthropic's memory docs](https://code.claude.com/docs/en/memory) say Claude Code loads `CLAUDE.md` and auto memory at the start of every conversation, but treats both as context rather than enforced configuration. The practical consequence is simple: use `CLAUDE.md` to make the right behavior likely, and use settings, permissions, `PreToolUse` hooks, CI, and human review to make unsafe behavior impossible.

That distinction matters once Claude Code is used by a team. A file that says "never touch migrations without approval" is useful context. It is not a control. A project setting that denies secret files, a hook that blocks migration edits without a ticket reference, and a PR workflow that routes database changes to an owner are controls.

The best `CLAUDE.md` for a production team answers the questions a senior engineer would answer during onboarding:

- What does this repo do?
- Which commands are safe and expected?
- Which directories own which responsibilities?
- Which patterns are approved?
- Which files, tools, or actions need a human gate?
- Where should Claude look before changing risky code?

That is enough. If the file becomes a place for every preference, every long procedure, every lint rule, and every edge case, it starts competing with the codebase for context. Anthropic recommends targeting under 200 lines per `CLAUDE.md` file because longer files consume more context and reduce adherence.

## What Belongs In The File

Put durable project context in `CLAUDE.md`: build commands, test commands, architecture boundaries, naming conventions, common workflows, and rules that should apply in almost every Claude Code session. Anthropic describes this file as the place to write down what you would otherwise re-explain.

A useful production file is specific enough to verify. "Write clean code" is noise. "Run `pnpm test -- --runInBand` before changing billing flows because the integration suite shares a test database" is useful. "Use the repository's data-access layer" is vague. "Do not query `stripe_subscriptions` directly outside `src/billing/repositories/*`" gives Claude a concrete boundary.

Use this minimum shape:

```markdown
# Project Brief

## What This Repo Owns
- API and worker code for the customer billing control plane.
- Next.js admin UI lives in `apps/dashboard`.
- Billing state changes must go through `src/billing/repositories`.

## Commands
- Install: `pnpm install`
- Typecheck: `pnpm typecheck`
- Unit tests: `pnpm test`
- Billing tests: `pnpm test apps/api/src/billing`

## Architecture Rules
- Keep HTTP handlers thin. Put business rules in service modules.
- Never bypass repository methods for billing tables.
- Prefer existing queue helpers in `src/jobs`.

## Review Gates
- Ask before editing migrations, payment code, auth middleware, or deployment config.
- Do not read `.env`, key files, or production credential exports.
- For risky changes, explain the blast radius before writing code.
```

The file should not carry long code samples, full runbooks, generated API docs, copied lint output, or personal preferences. Put procedures in docs, skills, or runbooks and link or import only what Claude needs. Put personal preferences in local memory. Put hard restrictions in settings and hooks.

:::callout{variant="warning" title="The dangerous anti-pattern"}
The most common failure is treating `CLAUDE.md` as a soft security product. It can remind Claude not to read secrets. It cannot guarantee that outcome. Use `permissions.deny` and hooks for the boundary.
:::

## Where To Put Instructions

Scope decides who receives the instruction, so choose the location before writing the rule. Anthropic documents managed, user, project, and local scopes for `CLAUDE.md`.

| Scope | File | Production use |
| --- | --- | --- |
| Managed policy | macOS `/Library/Application Support/ClaudeCode/CLAUDE.md`, Linux and WSL `/etc/claude-code/CLAUDE.md`, Windows `C:\Program Files\ClaudeCode\CLAUDE.md` | Organization-wide security and engineering standards managed by IT or platform engineering |
| User | `~/.claude/CLAUDE.md` | Personal defaults across projects |
| Project | `./CLAUDE.md` or `./.claude/CLAUDE.md` | Team-shared repository memory committed to source control |
| Local | `./CLAUDE.local.md` | Personal project notes, sandbox URLs, or test data, kept out of git |

For a team rollout, make the repository file boring and shared. It should describe the codebase, commands, architecture, and review gates that every engineer agrees to. Do not put one developer's preferred verbosity, local port, shell aliases, or throwaway test credentials in the committed file.

Claude Code loads `CLAUDE.md` and `CLAUDE.local.md` files above the working directory in full at launch. Files in subdirectories load when Claude reads files inside those directories. That makes nested memory useful in a monorepo, but it also creates drift risk. A root file might say one testing command, while a package file says another. Claude receives both as context, not as an override system.

Use this rule for monorepos:

- Root `CLAUDE.md`: company or repo-wide commands, release rules, ownership map.
- Package `CLAUDE.md`: package-specific architecture and test commands.
- `.claude/rules/`: path-specific rules for file types or directories.
- `CLAUDE.local.md`: personal notes that should never become team policy.

Anthropic's `.claude/rules/` support is the cleaner route when a rule only applies to matching paths. Rules can be scoped with `paths` frontmatter, while rules without `paths` load unconditionally. Use that for frontend component standards, database migration rules, or API handler rules that would make the root file too noisy.

## The Team Rollout Template

The production version of `CLAUDE.md` should be short enough to scan and strict enough to prevent wasted review cycles. Start with `/init` if the repo has no file. Anthropic says `/init` generates a starting `CLAUDE.md`, and if one already exists it suggests improvements instead of overwriting it. The environment variable `CLAUDE_CODE_NEW_INIT=1` enables an interactive multi-phase flow that can set up `CLAUDE.md` files, skills, and hooks.

Then edit the generated file down to the parts a teammate would trust.

::::steps
:::step{title="Write The Repository Contract"}
Describe what the repository owns, what it does not own, and where the core runtime paths live. Keep this factual. Claude does not need the company story; it needs the ownership map.
:::
:::step{title="Pin The Commands"}
List install, typecheck, unit test, integration test, lint, and local run commands exactly as they should be executed. Include known slow or flaky commands only if Claude needs that fact before making changes.
:::
:::step{title="Name The Architecture Boundaries"}
Point to the modules that own data access, auth, billing, model calls, queues, and deployment configuration. Tell Claude where not to put new code.
:::
:::step{title="Declare Review Gates"}
List the classes of change that need explicit approval: migrations, auth, secrets, billing, production infrastructure, data deletion, customer-visible emails, and release scripts.
:::
:::step{title="Link The Real Runbooks"}
Do not paste long procedures. Import or link the runbook, then state when Claude should consult it.
:::
::::

Here is a production-ready skeleton:

```markdown
# CLAUDE.md

## Repo Contract
- This repository owns the API, worker, and admin dashboard for the product.
- Do not add new infrastructure providers without an architecture note.
- Prefer existing helpers before creating new framework code.

## Commands
- Install dependencies: `pnpm install`
- Typecheck: `pnpm typecheck`
- Unit tests: `pnpm test`
- Targeted test: `pnpm test -- <path>`
- Build: `pnpm build`

## Architecture Boundaries
- API routes call service modules, not database clients directly.
- Billing writes go through `src/billing/repositories`.
- Agent runs are persisted through `src/ai/runs`.
- Queue jobs belong in `src/jobs`.

## Coding Standards
- Match existing file patterns before adding abstractions.
- Keep new modules owned by one domain.
- Add focused tests for shared behavior and risky branches.

## Safety And Review Gates
- Ask before editing migrations, auth middleware, billing code, or deploy config.
- Never read `.env`, private keys, credential exports, or production dumps.
- Before destructive actions, state the exact files and command involved.

## References
- API conventions: @docs/api-conventions.md
- Deployment runbook: @docs/deploy.md
- Incident checklist: @docs/incidents.md
```

The `@` imports are powerful, so use them deliberately. Anthropic documents `@path/to/import` syntax, relative paths that resolve from the file containing the import, and recursive imports up to four hops. Imports enter context at launch. They organize memory; they do not make context free.

If the repository already has `AGENTS.md`, do not fork instructions manually. Anthropic says Claude Code reads `CLAUDE.md`, not `AGENTS.md`, and recommends creating a `CLAUDE.md` that imports `@AGENTS.md`. Add Claude-specific notes below the import only when needed.

## Move Enforcement Out Of CLAUDE.md

Hard boundaries belong in settings, hooks, CI, and review ownership. [Anthropic's settings docs](https://code.claude.com/docs/en/settings) say to use `permissions.deny` in `.claude/settings.json` to prevent access to sensitive files such as API keys, secrets, and environment files. That is the control layer. The memory file can explain why the rule exists.

Use project settings for team-shared defaults and local settings for personal overrides. Claude Code settings scopes include Managed, User, Project, and Local. Anthropic lists precedence as Managed, command line arguments, local project settings, shared project settings, then user settings. That means organization policy can stay above repo and developer preferences.

A practical repo policy looks like this:

```json
{
  "permissions": {
    "deny": [
      "Read(.env)",
      "Read(.env.*)",
      "Read(**/*secret*)",
      "Read(**/*credential*)"
    ]
  }
}
```

Then wire hooks for actions that need deterministic checks. If your `CLAUDE.md` says "do not edit migrations without approval," a `PreToolUse` hook can inspect attempted writes under `db/migrations/` and block or route the action. If your team is already using hooks, connect the memory file to the policy by linking to the hook docs or pointing to the local hook file. We have a deeper pattern in [/blog/claude-code-hooks-production-teams](/blog/claude-code-hooks-production-teams).

For security-sensitive review, do not let Claude Code become the final approver. Treat it as an early reviewer that can find likely defects, missing tests, and risky diffs, then route the change through ordinary ownership. That keeps the line clear: Claude can propose, CI can check, hooks can block, humans approve. The rollout pattern is covered in [/blog/claude-code-security-review-production-teams](/blog/claude-code-security-review-production-teams).

## Maintain It Like Code

`CLAUDE.md` needs ownership because memory decays. A current arXiv paper on [configuration smells in `AGENTS.md` files](https://arxiv.org/abs/2606.15828), submitted on 14 Jun 2026 and revised on 17 Jun 2026, analyzed 100 popular open-source repositories containing either `AGENTS.md` or `CLAUDE.md`. It identified six configuration smells and found Lint Leakage in 62% of files, Context Bloat in 42%, and Skill Leakage in 35%.

Those failures map directly to production maintenance:

- Lint Leakage: the file repeats low-value lint rules that should live in tools.
- Context Bloat: the file grows until Claude stops following the important parts.
- Skill Leakage: task-specific procedures sit in always-loaded memory instead of skills.
- Conflicting Instructions: root, package, local, and imported rules disagree.

Another [empirical study](https://arxiv.org/abs/2509.14744) analyzed 253 `CLAUDE.md` files from 242 repositories and found shallow hierarchies dominated by operational commands, technical implementation notes, and high-level architecture. That is directionally useful: the best files look more like operational onboarding notes than essays.

Set a small maintenance loop:

- Assign an owner for the root file.
- Review it when build commands, release process, architecture boundaries, or security policy changes.
- Remove rules that are enforced by tooling.
- Move long procedures to skills or docs.
- Check nested files for conflicts before major team rollout.
- Keep personal notes in `CLAUDE.local.md`.

The file is doing its job when a new Claude Code session starts with the same high-signal project context a good engineer would give during onboarding, and nothing more.

## FAQ

::::faq
:::faq-item{q="What is the Claude MD file?"}
`CLAUDE.md` is a markdown memory file for Claude Code. Anthropic describes it as persistent instructions for a project, a personal workflow, or an organization, loaded at the start of a session.
:::

:::faq-item{q="Where does my CLAUDE.md file go?"}
Put team-shared project instructions in `./CLAUDE.md` or `./.claude/CLAUDE.md`. Put personal project-specific notes in `./CLAUDE.local.md` and keep them out of git.
:::

:::faq-item{q="Do I need a Claude MD file?"}
Use one when the same project context would otherwise be repeated in every session: commands, architecture, conventions, and review gates. Skip it for preferences that belong in local memory or rules that tooling should enforce.
:::

:::faq-item{q="Should we use AGENTS.md or CLAUDE.md?"}
Claude Code reads `CLAUDE.md`. If your repository already has `AGENTS.md`, create a `CLAUDE.md` that imports `@AGENTS.md`, then add Claude-specific notes below it only when needed.
:::

:::faq-item{q="Can CLAUDE.md stop Claude from reading secrets?"}
No. It can tell Claude the boundary, but Anthropic documents memory as context rather than enforced configuration. Use `permissions.deny`, hooks, CI, and review gates for enforcement.
:::
::::

:::summary
- Treat `CLAUDE.md` as a concise project briefing, not a policy engine.
- Keep team-shared instructions in source control and personal notes in `CLAUDE.local.md`.
- Target under 200 lines per file and move path-specific detail into `.claude/rules/`.
- Use settings, `permissions.deny`, hooks, CI, and human review for enforcement.
- Review the file like code because context bloat and conflicting instructions compound quickly.
:::

::card{href="/services/claude-code-team-rollout" title="Scope Your Claude Code Rollout" description="Roll out Claude Code with project memory, hooks, permissions, review gates, and team workflows that survive production work."}
