What is CLAUDE.md and why does it matter?

CLAUDE.md is a configuration file that sits at the root of your repository and tells Claude Code how to behave in your project. It defines project identity, coding standards, commands, and guardrails. Think of it as the onboarding document you'd give a new engineer — except Claude reads it every single session.

How long should a CLAUDE.md file be?

Keep the root CLAUDE.md under 300-500 lines. Every line costs context tokens, and bloated files cause Claude to miss important instructions. Move detailed documentation into .claude/rules/ files (auto-loaded) or docs/ files (loaded on demand via @imports).

Can CLAUDE.md be used for non-code projects?

Yes. CLAUDE.md works for any workflow — writing, decision briefs, meeting notes, operations playbooks. Templates like those from Artificial Corner show how to structure CLAUDE.md for knowledge workers, not just developers.

What's the difference between .claude/rules/ and @imports?

Files in .claude/rules/ are auto-loaded every session alongside your main CLAUDE.md — use them for always-on guidance like code style and security rules. Files referenced with @path/to/file are pulled in on demand when relevant. Use @imports for architecture docs, API references, and other situational context.

How do enterprise teams manage CLAUDE.md across multiple repositories?

Use a three-tier approach: a shared user-level ~/.claude/CLAUDE.md for organization-wide standards, per-repo CLAUDE.md files for project-specific rules, and subdirectory CLAUDE.md files for sensitive modules. Store your shared rules in a central repo and distribute them through your CI/CD pipeline or Git submodules.

The CLAUDE.md Guide for Enterprise Teams: Templates, Structure, and Best Practices

There are at least a dozen popular CLAUDE.md guides floating around right now. Builder.io published one. ClaudeFast ships a full kit. Dometrain, Gradually AI, scotthavird, Claude for Designers — everyone has a template.

They’re all good. And they’re all aimed at solo developers and startups.

If you’re running Claude Code across an enterprise team — multiple repos, compliance requirements, Azure infrastructure, shared MCP servers, and developers who didn’t all read the same blog post — those templates are a starting point, not a destination.

Here’s what they miss, and what your team actually needs.

At a Glance

CLAUDE.md is Claude Code’s project configuration file — the first thing it reads in every session. The community has converged on solid fundamentals (keep it short, lead with identity, document commands and gotchas). But enterprise teams need more: security boundaries for sensitive modules, multi-repo rule distribution, MCP server declarations, compliance guardrails, and hook-based enforcement that doesn’t rely on the model remembering instructions. This guide covers what the popular templates get right, what they miss, and provides a production enterprise template you can drop into your repos today.

What CLAUDE.md Actually Is

If you’re new to Claude Code, the short version: CLAUDE.md is a markdown file at the root of your repository that Claude reads at the start of every session. It tells Claude what the project is, where things live, what commands to run, and what rules to follow.

I covered the full project structure — CLAUDE.md, skills, hooks, docs, and local overrides — in The Anatomy of a Claude Code Project. Read that first if you need the foundations.

The important thing to understand: CLAUDE.md isn’t a prompt. It’s a configuration file. The difference matters. Prompts are one-shot. Configuration persists across every interaction, every session, every developer on your team.

The Standard Structure Everyone Agrees On

After reviewing every major template — Builder.io’s modular approach, ClaudeFast’s batteries-included kit, scotthavird’s GitHub starter, Dometrain’s .NET-focused guide, Gradually AI’s token-conscious approach — the community has converged on a few universal principles:

Keep it under 500 lines. Context tokens are finite. Bloated files degrade performance.
Lead with project identity. One sentence: what does this system do?
Document exact commands. Build, test, lint, deploy. Claude uses these verbatim.
Capture gotchas. The weird stuff — auth quirks, forbidden files, workaround patterns.
Separate concerns. Heavy docs go in .claude/rules/ or @imported files, not the main file.
Grow organically. Add rules when you catch yourself repeating instructions, not before.

The directory structure is similarly settled:

project/
├── CLAUDE.md                    # Identity, commands, rules (short)
├── .claude/
│   ├── settings.json            # Hooks, permissions
│   ├── commands/                # Slash commands
│   └── rules/                   # Auto-loaded rule files
└── docs/                        # @imported on demand

This is solid. Builder.io’s Steve Sewell popularized the @imports pattern for keeping CLAUDE.md lean. Boris Cherny showed how to tag @claude in PR comments to update rules as part of your review workflow. ClaudeFast took it further with 18 pre-configured agent definitions and 20+ skill modules.

All good work. None of it addresses what happens when you have 15 developers across four repos with an Azure landing zone and a compliance team breathing down your neck.

What Enterprise Teams Need Differently

Security Boundaries

Solo dev templates don’t think about access control because there’s nothing to protect from yourself. Enterprise repos have auth modules, billing logic, infrastructure-as-code, and secrets management that Claude should approach with extreme caution — or not touch at all.

You need local CLAUDE.md files at your sharp edges:

src/auth/CLAUDE.md
src/billing/CLAUDE.md
infra/terraform/CLAUDE.md

Each one contains module-specific constraints: don’t modify token rotation without updating the migration, never hardcode connection strings, always run the compliance check before committing Terraform changes. Claude loads these automatically when working in those directories.

Multi-Repo Rule Distribution

The CLAUDE.md hierarchy — user-level (~/.claude/CLAUDE.md), project-level, subdirectory-level — is powerful but nobody talks about how to manage it across an organization. When you have 30 repos, you need shared standards that don’t require copy-pasting into every project.

The pattern that works: maintain a central claude-standards repo with your organization’s base rules. Distribute them via CI/CD — a pipeline step that syncs shared .claude/rules/ files into each repo. Or use Git submodules if you prefer. The point is that your Azure naming conventions, security baselines, and compliance rules should be authored once and inherited everywhere.

MCP Server Configuration

Model Context Protocol servers give Claude access to external tools — your component library, documentation search, deployment APIs, Jira. Dometrain touched on this with a Shadcn example, but enterprise teams are running multiple MCP servers: internal package registries, Azure resource APIs, policy engines.

Your CLAUDE.md should declare which MCP servers are available and what they’re for, so Claude knows when to reach for external context versus local files.

Hooks for Enforcement

This is the big one. Every template tells Claude “follow these rules.” Enterprise teams can’t rely on the model remembering. You need deterministic enforcement.

Claude Code hooks (.claude/settings.json) fire automatically — before or after specific operations. Use them for everything that must happen every time:

Format code after every file edit
Run security linting on infrastructure changes
Block writes to protected directories
Execute compliance checks before commits

Prompts are suggestions. Hooks are guarantees. The difference between “Claude usually follows our standards” and “Claude always follows our standards” is hooks.

Compliance Rules as Code

If you’re in a regulated industry, your CLAUDE.md rules files should encode your compliance requirements directly. No PII in log statements. No public endpoints without authentication. No resources provisioned outside approved Azure regions. These aren’t style preferences — they’re audit requirements, and they belong in .claude/rules/compliance.md where they’re auto-loaded every session.

Enterprise CLAUDE.md Template

Here’s a production-ready template for an enterprise team running Azure infrastructure with Terraform, a .NET or Node.js application layer, and Intune-managed endpoints:

# Project: ContosoCloud Platform

Enterprise SaaS platform — .NET 8 APIs, React frontend, Azure landing zone.
Managed by the Platform Engineering team at Contoso.

## Commands

- Build: `dotnet build src/ContosoCloud.sln`
- Test: `dotnet test --no-build --verbosity normal`
- Lint: `dotnet format --verify-no-changes && npx eslint src/web/`
- Deploy (staging): `az deployment group create -g rg-contoso-staging -f infra/main.bicep`
- Terraform plan: `cd infra/terraform && terraform plan -var-file=env/staging.tfvars`

## Architecture

- `src/api/` — .NET 8 Web API (Clean Architecture)
- `src/web/` — React 18 + TypeScript frontend
- `infra/bicep/` — Azure Bicep templates (landing zone)
- `infra/terraform/` — Terraform modules (networking, DNS)
- `scripts/` — CI/CD pipeline scripts
- `.claude/rules/` — Auto-loaded team standards

## Rules

- Never hardcode secrets. Use Azure Key Vault references.
- All API endpoints require authentication. No anonymous access.
- Follow Azure naming convention: `{resource}-{project}-{env}-{region}`
- Terraform changes require `terraform plan` output in PR description.
- No `any` types in TypeScript. No `dynamic` in C# unless justified.

## MCP Servers

- `azure-docs` — Search Azure documentation (use for service limits, SKU details)
- `component-lib` — Internal React component library (check before building new UI)
- `jira` — Project tracking (reference ticket numbers in commits)

## Gotchas

- Auth uses MSAL with custom token cache — see `src/api/Auth/CLAUDE.md`
- Database migrations are EF Core — never modify generated migration files
- The staging Key Vault has a different access policy than prod — check before assuming
- Bicep modules in `infra/bicep/modules/` are shared across 3 teams — coordinate changes

@docs/architecture.md
@docs/adr/
@docs/runbooks/incident-response.md

Pair this with .claude/rules/ files for code style, security policy, and compliance:

.claude/rules/
├── code-style.md          # Formatting, naming, patterns
├── security.md            # Auth requirements, secret handling, input validation
├── compliance.md          # Data residency, PII handling, audit logging
├── azure-conventions.md   # Naming, tagging, resource group structure
└── terraform.md           # Module patterns, state management, plan requirements

And enforce the non-negotiable rules with hooks in .claude/settings.json:

{
  "hooks": {
    "postFileEdit": [
      { "command": "dotnet format src/ContosoCloud.sln --include ${file}" },
      { "command": "npx eslint --fix ${file}" }
    ],
    "preCommit": [
      { "command": "dotnet test --no-build" },
      { "command": "scripts/compliance-check.sh" }
    ]
  }
}

Common Mistakes

Dumping everything into one file. Your root CLAUDE.md should be a table of contents, not an encyclopedia. If it’s over 500 lines, you’re wasting context tokens and Claude will start missing instructions.

No hooks, only prompts. If a rule matters enough to write down, it matters enough to enforce. Hooks are cheap to configure and impossible to forget.

Ignoring the hierarchy. Every template shows root-level CLAUDE.md. Few discuss subdirectory overrides or user-level defaults. Enterprise teams need all three tiers working together.

Copy-pasting templates without trimming. The Builder.io ShopFront example is great — for a Next.js e-commerce app. Your Azure landing zone repo needs different instructions. Start with /init, then cut aggressively.

No team ownership. If one person writes the CLAUDE.md and nobody maintains it, it rots. Assign ownership of rule files to the teams that care about them. Security team owns security.md. Platform team owns azure-conventions.md. Treat these like code — they go through pull requests.

FAQ

See the FAQ section below — it covers the most common questions we get about CLAUDE.md from enterprise teams.

Get Your Team Up to Speed

The gap between “developer using Claude Code” and “team deploying Claude Code at scale” is structure. The templates get you started. The enterprise patterns — security boundaries, distributed rules, hook enforcement, compliance integration — get you to production.

Big Hat Group helps enterprise teams build this infrastructure. We run Claude Code and AI agent training for IT teams, and our consulting practice specializes in the exact patterns described here: multi-repo CLAUDE.md strategies, MCP server integration, OpenClaw deployment, and the governance frameworks that make compliance teams comfortable with AI-assisted development.

If your team is past the experimentation phase and ready to operationalize Claude Code, get in touch.

Kevin Kaminski is a Microsoft MVP and Principal at Big Hat Group, where he helps enterprise teams deploy AI agents, Windows 365, and modern management solutions.