CLAUDE.md Hierarchy & Configuration

CLAUDE.md Hierarchy & Configuration

CLAUDE.md is the primary mechanism for giving Claude Code persistent, project-specific context and instructions. Think of it as a system prompt that lives in your repository. Understanding the CLAUDE.md hierarchy — where files are placed, how they are resolved, and what takes precedence — is one of the most heavily tested topics in Domain 3 of the CCA-F exam.

What Is CLAUDE.md?

A CLAUDE.md file is a Markdown file that contains instructions, context, and conventions that Claude Code reads at the start of every session. When you launch Claude Code in a directory that contains (or has parent directories containing) CLAUDE.md files, those files are automatically loaded into the system prompt.

CLAUDE.md files can contain:

• Project architecture descriptions and conventions
• Coding style guidelines (naming, formatting, patterns to follow)
• Build and test commands
• Common pitfalls and things to avoid
• Instructions for how to handle specific types of tasks
• Links to relevant documentation

The Three-Level Hierarchy

CLAUDE.md files exist at three levels, each serving a different purpose. The hierarchy, from broadest to most specific, is:

1. User-Level CLAUDE.md (~/.claude/CLAUDE.md)

This file lives in your home directory and applies to every project you work on with Claude Code. It is personal to you and is never committed to version control.

# ~/.claude/CLAUDE.md

# Personal Preferences
- I prefer functional programming patterns over OOP
- Always use TypeScript strict mode
- When writing tests, I prefer describe/it blocks over test() syntax
- My preferred package manager is pnpm
- When committing, use conventional commit format

Use the user-level file for personal coding preferences that should apply regardless of which project you are working on.

2. Project-Level CLAUDE.md (repo-root/CLAUDE.md)

This file lives at the root of your repository and applies to the entire project. It is typically committed to version control so that all team members share the same Claude Code instructions.

# CLAUDE.md (project root)

# Project: E-Commerce Platform

## Architecture
- Next.js 14 app router in /src/app
- PostgreSQL database with Prisma ORM
- Redis for caching and session storage
- Stripe for payment processing

## Build & Test Commands
- Build: npm run build
- Test all: npm test
- Test single file: npm test -- path/to/test.ts
- Lint: npm run lint
- Type check: npx tsc --noEmit

## Code Conventions
- Use server components by default; add "use client" only when needed
- All API routes go in /src/app/api/
- Database queries should use Prisma, never raw SQL
- Error handling: use Result<T, E> pattern from /src/lib/result.ts
- All monetary amounts stored as integers (cents)

## Common Pitfalls
- Do NOT import from @prisma/client directly; use /src/lib/db.ts
- The /src/legacy/ directory is deprecated; do not add new code there
- Environment variables are validated in /src/env.ts; add new ones there

3. Directory-Level CLAUDE.md (any subdirectory)

You can place CLAUDE.md files in any subdirectory to provide context specific to that part of the codebase. These are loaded when Claude reads or edits files in that directory.

# src/api/CLAUDE.md

# API Layer Conventions
- All endpoints must validate input with Zod schemas
- Use the withAuth() middleware for authenticated routes
- Response format: { data: T, error: null } or { data: null, error: string }
- Rate limiting is configured in /src/api/middleware/rate-limit.ts
- All endpoints must have OpenAPI JSDoc annotations

# src/components/CLAUDE.md

# Component Conventions
- Use named exports, not default exports
- Props interfaces should be named ComponentNameProps
- Colocate styles: ComponentName.module.css next to ComponentName.tsx
- All components must have a displayName for React DevTools
- Use forwardRef for components that wrap native elements

Resolution Order

When Claude Code starts a session, it loads CLAUDE.md files in a specific order. Understanding this order is critical for the exam:

1. User-level (~/.claude/CLAUDE.md) — loaded first, provides the base personal preferences.
2. Project-level (/project-root/CLAUDE.md) — loaded second, provides project-wide context and conventions.
3. Directory-level (e.g., /project-root/src/api/CLAUDE.md) — loaded dynamically as Claude navigates into directories during the session.

The key principle is: more specific instructions take precedence over less specific ones. If the user-level CLAUDE.md says "use spaces for indentation" but the project-level CLAUDE.md says "use tabs for indentation," the project-level instruction wins because it is more specific to the current context.

CLAUDE.md Best Practices

Keep It Concise and Actionable

CLAUDE.md content is loaded into the system prompt, consuming context window space. Every line should provide actionable guidance:

# BAD - vague and wordy
We generally try to write clean code and follow best practices.
Our codebase has evolved over time and there are some legacy patterns
that we are slowly migrating away from.

# GOOD - specific and actionable
- Use Zod for all input validation (not Joi or manual checks)
- New files go in /src/v2/; do not add to /src/legacy/
- Run "npm run typecheck" before committing

Include Build and Test Commands

One of the most impactful things to put in CLAUDE.md is how to build and test the project. Claude Code uses these commands to verify its own work:

# Build & Test
- Build: npm run build
- Test all: npm test
- Test single: npm test -- --testPathPattern=FILENAME
- Lint: npm run lint
- Format: npx prettier --write .
- Type check: npx tsc --noEmit

Document Non-Obvious Patterns

Focus on patterns that Claude would not be able to infer from the code alone:

# Non-Obvious Conventions
- We use a custom ESLint rule that requires all async functions
  to have a try/catch. The linter will fail if you forget this.
- The CI/CD pipeline runs tests with NODE_ENV=test, which swaps
  the database connection to a test database automatically.
- Import aliases: @/components maps to src/components,
  @/lib maps to src/lib

Use Conditional Sections

For monorepos or projects with multiple modules, you can use directory-level CLAUDE.md files rather than putting everything in the root file. This keeps instructions relevant and avoids wasting context window space:

# Project structure with directory-level CLAUDE.md files
my-monorepo/
  CLAUDE.md              # Monorepo-wide conventions
  packages/
    frontend/
      CLAUDE.md          # React/Next.js conventions
    backend/
      CLAUDE.md          # Express/Node conventions
    shared/
      CLAUDE.md          # Shared library conventions

The .claudeignore File

Similar to .gitignore, the .claudeignore file tells Claude Code which files and directories to ignore. This is useful for excluding large generated files, build artifacts, or sensitive content:

# .claudeignore
node_modules/
dist/
build/
.env
.env.local
coverage/
*.min.js
*.bundle.js

CLAUDE.md for Teams

When using CLAUDE.md in a team setting, consider this layering strategy:

• Committed (project + directory level): Shared conventions, build commands, architecture descriptions. Every team member gets these automatically.
• Personal (user level): Individual preferences like preferred test style, editor conventions, and personal workflow habits. Not committed.

# Example team workflow:
# 1. Project-level CLAUDE.md (committed to git)
#    Contains: architecture, build commands, code conventions
#
# 2. Each developer has ~/.claude/CLAUDE.md (personal)
#    Contains: personal style preferences, workflow habits
#
# 3. Directory-level CLAUDE.md files (committed to git)
#    Contains: module-specific patterns and conventions

Exam-Relevant Concepts Summary

• Three levels: user (~/.claude/CLAUDE.md), project (root), directory (subdirectories).
• Resolution order: user → project → directory; more specific wins.
• Project-level CLAUDE.md is committed to git; user-level is personal.
• Directory-level files are loaded dynamically as Claude navigates the codebase.
• CLAUDE.md content goes into the system prompt and consumes context window space.
• Best practice: include build/test commands, coding conventions, and non-obvious patterns.
• .claudeignore works like .gitignore to exclude files from Claude's awareness.