CLAUDE.md File Best Practices for Production Teams

The Production Rule For CLAUDE.md

CLAUDE.md is memory, not enforcement. Anthropic's memory docs 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:

# 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.

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.

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.

Here is a production-ready skeleton:

# 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 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:

{
  "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.

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.

Maintain It Like Code

CLAUDE.md needs ownership because memory decays. A current arXiv paper on configuration smells in AGENTS.md files, 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 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