CLAUDE.md and Rules

File locations and loading behaviour

CLAUDE.md files live in three locations, each with different scope and loading behaviour.

Project-level — the one you use most:

./CLAUDE.md
# or equivalently
./.claude/CLAUDE.md

Both locations have the same precedence. Use whichever fits your project. If you have a .claude/ directory for other configuration (skills, agents, settings), putting CLAUDE.md there keeps things tidy.

User-level — your personal defaults:

~/.claude/CLAUDE.md

This loads in every project. Use it for personal preferences that apply across all your work — your preferred explanation style, how you like commit messages formatted, whether you want verbose or terse output.

Managed policy — organisation-level, set by administrators:

# macOS
/Library/Application Support/ClaudeCode/CLAUDE.md

# Linux / WSL
/etc/claude-code/CLAUDE.md

This cannot be excluded or overridden. It is designed for organisation-wide compliance rules.

Loading order: All three load and accumulate. The content stacks — project-level instructions add to user-level instructions which add to managed policy. When instructions conflict, more specific scope wins: project overrides user overrides managed.

Walk-up discovery: If you run Claude Code in foo/bar/, it loads CLAUDE.md from both foo/bar/ and foo/. This matters in monorepos — a CLAUDE.md at the monorepo root provides shared context, while a CLAUDE.md in each package provides package-specific context.

Subdirectory loading: CLAUDE.md files in subdirectories below your working directory load on-demand when Claude reads files in that subdirectory. This is automatic — you do not need to configure anything. Place a CLAUDE.md in src/api/ and it loads when Claude first touches a file in that directory.

Extending CLAUDE.md with imports

For projects where even a well-structured CLAUDE.md would exceed 200 lines, the import system lets you reference external files without inlining their content.

The syntax is @path/to/file:

# My Project

@README.md
@docs/architecture.md

## Build Commands
- `pnpm install` — install dependencies
- `pnpm dev` — run development server
- `pnpm build` — build for production

## Coding Standards
@docs/coding-standards.md

When Claude loads this CLAUDE.md, it resolves each @path reference and includes the file content inline. Paths resolve relative to the CLAUDE.md file, not your working directory.

Import limits: Maximum 5 hops of recursive imports. If a.md imports b.md which imports c.md, that works fine. But deeply nested chains beyond 5 levels will stop resolving.

First-time approval: The first time Claude encounters imports in a project, it shows an approval dialog listing the referenced files. If you decline, imports are disabled for that project.

HTML comments for token-free notes: Block-level HTML comments in CLAUDE.md are stripped before injection into Claude's context:

<!-- Team note: we moved testing standards to a skill on 2026-01-15 -->
<!-- Don't add them back here — they load on-demand now -->

# Project Architecture
...

The comments are visible when you open the file but cost zero tokens in Claude's context. Use them for team coordination.

Path-specific rules

Rules live in .claude/rules/*.md and provide modular, scopeable extensions to CLAUDE.md. The key feature: rules can be path-specific, meaning they load only when Claude is working with files that match a glob pattern.

A rule file looks like this:

---
paths: "src/components/**/*.tsx"
---

# React Component Conventions

- All components use functional syntax with TypeScript
- Props interfaces are named {ComponentName}Props
- Use named exports, not default exports
- Co-locate component-specific hooks in the same directory
- Tests live in __tests__/ subdirectory with .test.tsx extension

The paths field in the frontmatter tells Claude Code: only load this rule when working with files matching src/components/**/*.tsx. When Claude is editing an API route, these React conventions are not in context. When Claude starts working on a component, they load automatically.

Rules without a paths field load at startup, just like CLAUDE.md content. Use these for standards that are important enough to warrant their own file but apply broadly:

# Error Handling Standards

- Never swallow exceptions silently
- Log errors with structured metadata: timestamp, request ID, user context
- Use custom error classes for domain-specific errors
- Return appropriate HTTP status codes from API endpoints

Organising rules by domain:

.claude/rules/
├── react-components.md     # paths: src/components/**
├── api-design.md           # paths: src/api/**
├── database-migrations.md  # paths: migrations/**
├── error-handling.md       # no paths — loads at startup
└── testing.md              # paths: **/*.test.*

This structure means Claude always knows your error handling standards but only loads React conventions when working on components, API design rules when working on routes, and testing standards when working on test files.

Decomposing a bloated CLAUDE.md

Here is the framework for deciding where every line of your CLAUDE.md should live.

Keep in CLAUDE.md — information every session needs:

• Project name and one-paragraph description
• Build and run commands (pnpm dev, pnpm build, pnpm test)
• High-level architecture summary (framework, language, key directories)
• Universal coding standards (indentation, naming conventions, import ordering)
• Links to external resources (if using @imports)

Move to .claude/rules/ — domain-specific standards:

• React component conventions → rules/react.md with paths: "src/components/**"
• API design patterns → rules/api.md with paths: "src/api/**"
• Database conventions → rules/database.md with paths: "src/db/**"
• Testing standards → rules/testing.md with paths: "**/*.test.*"

Move to skills — task-specific workflows:

• PR review checklist → .claude/skills/review-pr/SKILL.md
• Deployment procedure → .claude/skills/deploy/SKILL.md
• Changelog generation → .claude/skills/changelog/SKILL.md
• Code migration steps → .claude/skills/migrate/SKILL.md

Move to agents — heavy delegated work:

• Codebase exploration → .claude/agents/explorer/AGENT.md
• Comprehensive code review → .claude/agents/reviewer/AGENT.md
• Test generation → .claude/agents/test-writer/AGENT.md

The result: a CLAUDE.md under 100 lines that gives Claude exactly the foundation it needs, with everything else loading on-demand from the right layer.

The art of effective instructions

Not all CLAUDE.md instructions are created equal. Claude follows specific, concrete instructions far more reliably than vague or aspirational ones.

Bad: "Write clean, well-documented code."

Good: "Use 2-space indentation. Name functions with camelCase verbs: getUserProfile, validateInput, handlePayment. Add JSDoc comments only for exported functions."

Bad: "Follow best practices for error handling."

Good: "Catch errors at API route boundaries. Log with structured metadata: { error: err.message, requestId, userId }. Return { error: string, code: string } to clients. Never expose stack traces in production responses."

The specificity rule: If two developers could reasonably interpret an instruction differently, it is too vague. Rewrite it until there is only one way to follow it.

The 200-line target: Keep your CLAUDE.md under 200 lines. If you cannot fit everything in 200 lines, that is a signal to use @imports or move content to rules. Claude processes shorter, focused files more reliably than long, comprehensive ones.

Structure with headers: Use markdown headers (##, ###) to organise sections. Claude uses these to locate relevant instructions quickly.

# My Project

## Build Commands
...

## Architecture
...

## Coding Standards
...