CLAUDE.md Configuration Guide for Engineering Teams

TL;DR: Learn how to structure CLAUDE.md files for your engineering team. A practical guide for technical leads using Claude Code across a shared codebase.

A CLAUDE.md file is a configuration document that sits in your repository root and instructs Claude Code how to behave in that project. It defines what conventions to follow, what directories to avoid, what commands require human review, and what testing requirements apply before any change is considered complete. Without it, Claude Code operates on defaults, and those defaults know nothing about your stack, your standards, or your client commitments.

The practical consequence of a missing CLAUDE.md is output variance at scale. Each engineer in a 15-person team running Claude Code without shared configuration is effectively setting their own rules through ad hoc prompts and personal habits. The same refactoring task produces different results in different styles. A project-level CLAUDE.md eliminates that variance by establishing a consistent floor of behaviour across every session, every machine, and every engineer on the project.

Where CLAUDE.md Files Live

Claude Code reads instruction files from several scoped locations, and the picture grew slightly richer through 2026. As of May 2026 the documented memory locations include the project root, subdirectories, the user home directory, a personal-project sandbox, and a path-scoped rules folder. Verify the current set on the official memory reference at code.claude.com/docs/en/memory.md before formalising your team's convention.

The repository root is where your primary CLAUDE.md should live. This is the project-level file that every team member gets automatically when they run Claude Code inside the repo. It is committed to version control like any other configuration file, which means changes are reviewed, versioned, and visible. Claude Code also recognises ./.claude/CLAUDE.md at the project level if you prefer to keep configuration co-located with other .claude/ assets.

Subdirectory CLAUDE.md files add local context for specific parts of the codebase. Claude Code walks up the directory tree from the working file and concatenates the discovered CLAUDE.md files into context, rather than letting one override another. If your monorepo has a backend service with different conventions from your frontend, each subdirectory can carry its own additive instructions.

The user home directory (~/.claude/CLAUDE.md) holds personal preferences that apply across all repos on a developer's machine. This is the right place for individual style preferences, tool configuration, or personal conventions. It does not belong in version control and should not duplicate project-level rules.

The personal-project file (./CLAUDE.local.md) is gitignored by default and lets a single developer keep sandbox preferences for the current project without leaking them to teammates.

The rules folder (.claude/rules/*.md, recursive) is for topic-specific or path-scoped rules that you do want shared across the team. These behave like additional CLAUDE.md fragments and are useful when you want to keep the main CLAUDE.md short and split rules by area.

For a 10 to 20 person engineering team, the project-level file at the repo root is the one that matters most. Start there. Add subdirectory or rules-folder files only when the main file starts to lose focus.

What Your CLAUDE.md Should Contain

The goal is to give Claude Code enough context to make good local decisions without requiring a prompt every time. There are four core categories.

Project context covers what the codebase is, what it does, and how it is structured. Claude Code should know whether it is working in a Django monolith, a Next.js frontend with a separate API layer, or a microservices architecture. Include the main directories, the primary language and framework versions, and any architecture decisions that affect how code should be written.

Coding conventions are the rules your team already enforces through review. Naming conventions, file structure expectations, preferred patterns for async handling, rules around comments, and formatting standards all belong here. If you run ESLint with a specific config, say so. If you use a particular approach to dependency injection, document it. Claude Code will follow explicit conventions more reliably than it will infer them from surrounding code.

Testing approach tells Claude how your team writes and runs tests. Which framework do you use? Do you write tests alongside implementation or after? Are there test utilities or factories it should reuse? Is there a naming convention for test files? Without this, Claude will generate tests in whatever style feels natural to the model, which may not match what your CI pipeline expects.

Prohibited actions are explicit constraints. These might include: do not modify the database migration files directly, do not add new third-party dependencies without flagging them, do not remove error logging, do not refactor code outside the scope of the current task. Prohibited actions are where you prevent the class of well-intentioned Claude mistakes that are hardest to catch in review.

Structuring the File for a Team of 10 to 20

Length matters. A CLAUDE.md file that runs to 500 lines gets ignored, partially read, or quietly deprioritised by the model when context pressure increases. Aim for clarity over completeness.

A practical structure for a mid-sized engineering team looks like this: open with a two to three sentence description of the project and its stack. Follow with a bulleted list of coding conventions, grouped by area (naming, structure, async, error handling). Add a short testing section. Close with a list of hard constraints under a "Prohibited Actions" or "Hard Rules" heading.

Use bullet points rather than prose for anything that functions as a rule. Claude Code parses structured lists more reliably than paragraph-form instructions when applying them to specific code changes.

Keep the main file focused (a few hundred lines is a sensible upper bound for most teams). If it is growing beyond that, you have two clean options. First, split rules into .claude/rules/*.md so each topic lives in its own file. Second, use the @import syntax inside CLAUDE.md to pull in standalone files (for example @docs/coding-conventions.md or @README.md). Imports resolve relative to the file that contains them and Claude Code follows up to five hops. This keeps the operative configuration short while still letting you split content across files that engineers already maintain.

Common Mistakes That Reduce Effectiveness

Too vague: Writing "follow best practices" or "write clean code" gives Claude nothing actionable. Specify what best practice means in your context. "Use named exports, not default exports" is a rule Claude can apply. "Write clean code" is not.

Not updated after architecture changes: CLAUDE.md becomes a liability if it describes a stack you moved away from six months ago. Assign ownership. When a team lead merges an architecture change, updating CLAUDE.md should be part of the same pull request, not a follow-up task.

Confusing global and project config: Personal preferences (preferred terminal tools, personal style choices) belong in the home directory file, not in the project-level file. Mixing them adds noise for the model and creates friction for teammates who do not share those preferences.

Missing the scope of autonomous actions: If your team uses Claude Code in agentic mode for longer tasks, your CLAUDE.md should explicitly state what Claude is and is not allowed to do without human confirmation. Running tests without prompting is fine. Deleting files is not. State this explicitly.

The Global vs. Project Distinction in Practice

For most engineering teams, the clearest mental model is this: the global file at ~/.claude/CLAUDE.md is what you tell Claude about yourself as a developer. The project file at the repo root is what you tell Claude about the codebase it is working in.

Both files are read and merged. Project-level rules take precedence when there is a conflict. This means you can configure personal workflow preferences globally without polluting the shared project config, and project rules will always win when they matter most.

A 15-person engineering team that invests two hours in a well-structured CLAUDE.md will recoup that time within a week in reduced review corrections and fewer sessions where Claude drifts from team conventions. It is operational configuration, not documentation.

Operator Takeaway: What to Do This Week

Three actions for a CTO, engineering lead, or operations leader running a 10 to 20 person team:

1. Stand up a project-root CLAUDE.md with four short sections: project context, coding conventions, testing approach, and prohibited actions. Keep it well under 300 lines, version-controlled, and reviewed in pull requests like any other config.
2. Move personal preferences to ~/.claude/CLAUDE.md and per-developer sandbox tweaks to a gitignored ./CLAUDE.local.md. Stop polluting the team file with individual taste.
3. Decide owner and update cadence. The team lead who merges architecture changes also owns the CLAUDE.md edit in the same pull request. If no one owns it, it ages.

Once the file is in place, evaluate how well your team is set up for Claude Code adoption with the AI Readiness Assessment, or talk to us about structuring the rollout via AI Consulting.

FAQ

Does every developer on the team need to do anything for CLAUDE.md to take effect?

No. Once the file is committed to the repository root, Claude Code reads it automatically for any session run inside that repo. Developers do not need to configure anything individually. The file applies to every session on every machine.

Can we have different CLAUDE.md rules for different branches?

Yes, because CLAUDE.md is a committed file like any other. If you check out a feature branch that has a modified CLAUDE.md, Claude Code will use that version. This means you can experiment with new conventions in a branch before merging them into the main config.

How do we handle secrets or sensitive context in CLAUDE.md?

Do not put secrets in CLAUDE.md. The file is committed to version control and will appear in logs. If Claude Code needs to know about external services, reference them by name and pattern, not by credential. Secrets management stays in your existing secrets infrastructure.

Further Reading

• Claude Code Extended Thinking for SME Teams: How extended thinking mode affects output quality and when engineering teams should use it.
• Claude Code Agent Mode and Autonomous Workflows: A guide to running Claude Code in agentic mode for longer, multi-step development tasks.
• Claude Code Team Evaluation Scorecard: A structured framework for evaluating whether Claude Code is delivering value across your team.
• How Technical Leaders Should Choose an AI Coding Agent: A decision framework for engineering leads comparing AI coding tools on criteria that matter for team adoption.