Hierarchy & Rules

Knowledge

The 4-Level Hierarchy in Detail

Claude Code loads CLAUDE.md files from four different locations. The basic rule is simple: More specific wins. If a global rule says "Use tabs" and a project rule says "Use spaces," then spaces apply -- just like CSS specificity.

Level 1: Global (~/.claude/CLAUDE.md)

This file applies to all your projects. Put things here that you always want -- regardless of which project you are working on.

# Global Rules

- Respond in German when I write in German
- Always use TypeScript instead of JavaScript
- Prefer functional programming
- Commit messages in English using Conventional Commits format

Level 2: Project Root (./CLAUDE.md)

The most important level. This file sits in your repository root and is shared with the team via Git. It contains project-specific rules that apply to all team members.

# Project: My App

## Commands
npm run dev          # Development server
npm run test         # Tests with Vitest
npm run lint         # ESLint

## Architecture
- App Router with [locale] segment
- Zustand for state management
- Tailwind CSS 4 for styling

Level 3: Project Config (./.claude/CLAUDE.md)

This file sits in the .claude/ directory of your project, which is typically listed in .gitignore. It is user-specific -- here you can set personal preferences that do not concern the team.

# My Personal Rules for This Project

- I prefer detailed explanations in comments
- Always show me diffs before a commit
- Use Vim keybindings in code examples

Level 4: Subdirectory (subdir/CLAUDE.md)

Claude loads these files on-demand when working in a subdirectory. Perfect for monorepos or projects with different areas.

# src/api/CLAUDE.md

- All API routes use Zod for validation
- Error responses follow the RFC 7807 format
- Rate limiting is mandatory for public endpoints

Understanding

Enterprise: Managed Policies

In enterprise environments, there is an additional level: Managed Policies. Administrators can define organization-wide rules at /Library/Application Support/ClaudeCode/policies/CLAUDE.md (macOS) that cannot be overridden.

# Managed Policy (from IT department)

- No API keys in code
- All external dependencies must come from the company registry
- No execution of rm -rf commands

These policies are treated by Claude Code as immutable rules -- they have the highest priority and cannot be overridden by any other CLAUDE.md.

The @-Import Syntax

You can import other files into your CLAUDE.md to keep it modular:

# CLAUDE.md

@docs/coding-standards.md
@.cursor/rules/api-conventions.md
@scripts/README.md

Each @-import must be on its own line. Claude resolves these references recursively, but with a maximum of 5 nesting levels to prevent infinite loops.

Lazy-loaded Rule Files

For large projects, Claude Code offers .claude/rules/*.md -- rule files that are only loaded when they are relevant. With YAML frontmatter, you can define which file paths a rule applies to:

---
paths:
  - "src/api/**/*.ts"
---
# API Conventions

- Use express-validator for input validation
- All endpoints need JSDoc comments
- Error handlers must log the HTTP status

These rules are only loaded into the context when Claude is working on files that match the paths pattern. This saves valuable context budget.

Technical Details

Survival after /compact: Yes. When you run /compact to compress the context, all CLAUDE.md files are reloaded afterward. Your rules are therefore never lost.

HTML comments: Comments like <!-- TODO: Update this rule --> are automatically filtered out and not sent to Claude. You can use them for internal notes.