CLAUDE.md Files

CLAUDE.md files are files that you write which will be loaded into every new context at the system prompt level. Claude files are scoped at different levels:

Managed Policy — organization-wide instructions managed by IT/DevOps. Company coding standards, security policies, compliance requirements; applies to all users in organization.
- macOS: /Library/Application Support/ClaudeCode/CLAUDE.md
- Linux and WSL: /etc/claude-code/CLAUDE.md
- Windows: C:\Program Files\ClaudeCode\CLAUDE.md
Project Instructions — team-shared instructions for the project. Project architecture, coding standards, common workflows; shared with team members via source control. Location: ./CLAUDE.md or ./.claude/CLAUDE.md
User Instructions — personal preferences for all projects. Code styling preferences, personal tooling shortcuts; just you (current project). Location: ~/.claude/CLAUDE.md
Local Instructions — personal project-specific preferences, not checked into git. Your sandbox URLs, preferred test data; just you (current project). Location: ./CLAUDE.local.md

Load order:

CLAUDE.md files at the root directory are fully loaded.
CLAUDE.md in subdirectories load on demand when Claude needs them.

Running /init will have Claude scan your project and create a CLAUDE.md file for you — it searches for patterns, reads files, and once it has enough context, writes the CLAUDE.md file (opening it as a diff you can accept/reject: Yes / Yes, allow all edits during this session (shift+tab) / No).

Claude files are context and not enforced configuration. How you write your instructions determines how reliably Claude follows them.

CLAUDE.md files should be under 200 lines. Long files consume more context and reduce adherence. Split up large files with @imports or .claude/rules/ files.
Use markdown headers and bullets to group related instructions.
Write concrete (specific enough) instructions: "Use 2-space indentation" instead of "Format code properly"; "Run npm test before committing" instead of "Test your changes"; "API handlers live in src/api/handlers/" instead of "Keep files organized".
If two rules contradict each other, Claude may pick one arbitrarily.
Periodically review your Claude files and make adjustments.

claudeMdExcludes is used to prevent specific CLAUDE.md files from being loaded. In large monorepos you want to use this setting to ignore legacy or useless Claude files (in .claude/settings.local.json):

{
  "claudeMdExcludes": [
    "**/monorepo/CLAUDE.md",
    "/home/user/monorepo/other-team/.claude/rules/**"
  ]
}

You can break up your CLAUDE.md into import files:

Both relative and absolute paths are allowed.
Relative paths resolve relative to the file containing the import, not the working directory.
Imported files can recursively import other files, with a maximum depth of five hops.

Example:

# My Project
A full-stack SaaS application built with Next.js, Postgres, and TypeScript.

## Structure
@.claude/architecture.md
@.claude/conventions.md

## Frontend
@src/components/CLAUDE.md
@src/app/CLAUDE.md

## Backend
@src/api/CLAUDE.md
@src/db/CLAUDE.md

## Tooling & Workflow
@.claude/testing.md
@.claude/git-conventions.md
@.claude/deployment.md

## Third-Party Integrations
@.claude/integrations/stripe.md
@.claude/integrations/resend.md
@.claude/integrations/sentry.md