How to Configure CLAUDE.md Files for Claude Code Projects
Configure CLAUDE.md files for Claude Code to define persistent, system-level instructions that shape every interaction in your project. Place a CLAUDE.md at your repository root to define coding standards, forbidden patterns, testing requirements, and workflow rules. Claude follows them without you repeating yourself each session. You can also create user-level and folder-level variants for layered configuration.
The Three CLAUDE.md Configuration Layers
Claude Code loads instructions from three locations, merged in order of specificity. The project-level file lives at your repo root and gets committed to version control. The user-level file lives in your home directory and applies across all projects. Folder-level files apply only when Claude works on files in that directory subtree.
The three file locations are ~/.claude/CLAUDE.md for user-level personal preferences, ./CLAUDE.md for project-level rules shared with the team, and ./src/CLAUDE.md for folder-level scoped rules.
A Production-Ready Root CLAUDE.md Template
Start with a root file that covers the four areas that cause the most AI coding drift: language and framework constraints, testing expectations, code style rules, and forbidden patterns. The following template works well for a TypeScript backend project.
# CLAUDE.md
## Project Overview
This is a Node.js API service using TypeScript 5.x, Express 4, and PostgreSQL.
The codebase uses ESM modules exclusively. Do not use CommonJS require().
## Code Style
- Use `type` over `interface` unless declaration merging is needed.
- All functions must have explicit return types. No implicit `any`.
- Use named exports, never default exports.
- Error handling: throw typed errors from src/errors/, never plain strings.
## Testing Requirements
- Every new function must have a corresponding test in __tests__/.
- Run `npm run test:unit` before declaring any task complete.
- Never mock the database in integration tests; use the test container.
## Forbidden Patterns
- Do NOT install new dependencies without asking first.
- Do NOT modify files in src/generated/ — these come from codegen.
- Do NOT use `console.log` for logging; use the `logger` from src/lib/logger.ts.Why Structure Matters More Than Length
Claude Code parses CLAUDE.md as context injected into every prompt. This means two things: overly long files burn your context window, and vague instructions get ignored the same way a junior developer would ignore them. The most effective files stay under 100 lines and use imperative, specific language. "Use descriptive variable names" is weak. "All variable names must be at least 3 characters; single-letter variables are only allowed in lambda parameters and loop indices" is strong.
The forbidden-patterns section is arguably the most valuable part. Claude Code is eager to help and will happily install packages, rewrite generated files, or add console.log statements unless you explicitly forbid it. Negative constraints outperform positive suggestions for preventing drift.
# src/api/CLAUDE.md
## Folder Context
This directory contains Express route handlers.
## Rules for This Directory
- Every route handler must use the asyncHandler wrapper from ../lib/async.ts.
- Request validation uses zod schemas from ../schemas/. Never validate inline.
- All responses must go through sendSuccess() or sendError() from ../lib/response.ts.
- Route files export a single Router. Registration happens in src/app.ts only.User-Level Configuration for Personal Preferences
The user-level file is ideal for editor-style preferences that you want everywhere but that would be too opinionated to force on a team. Create it at ~/.claude/CLAUDE.md.
# ~/.claude/CLAUDE.md
## My Preferences
- When showing terminal commands, always explain what each flag does.
- Prefer functional approaches over imperative loops.
- When asked to refactor, show a before/after diff summary.
- Always run the linter after modifying files: use the project's lint command.
- When uncertain between two approaches, present both with tradeoffs
instead of picking one silently.Making Claude Code Run Tests and Validate Its Own Work
One of the most impactful patterns is requiring Claude Code to verify its changes before reporting completion. Without this requirement, Claude often claims a task is done based on syntactic correctness alone. Add verification commands directly into your CLAUDE.md.
# CLAUDE.md (append to your root file)
## Verification Steps
After ANY code change, run these commands and fix issues before reporting done:
1. `npx tsc --noEmit` — must pass with zero errors.
2. `npm run lint` — must pass with zero warnings.
3. `npm run test:unit -- --bail` — must pass all tests.
If any step fails, fix the issue and re-run all three steps.
Do not ask me if I want you to fix it. Just fix it.Common Gotchas and Pitfalls
File size vs. effectiveness: A 500-line CLAUDE.md degrades performance. Claude Code injects this content into every interaction, so you're trading context window for instructions. Keep it under 100 lines. If you need more, split into folder-level files that load only when relevant.
Conflicting instructions between layers: When your user-level file says "prefer functional style" but the project-level file says "use class-based controllers," the project-level file wins because it's more specific. However, Claude can still get confused by direct contradictions. Audit your layers for conflicts.
Stale instructions: Your CLAUDE.md rots the same way any other documentation does. When you migrate from Jest to Vitest but forget to update the testing section, Claude keeps trying to run Jest. Treat CLAUDE.md as living code and review it during dependency upgrades and architectural changes.
Don't repeat what's in config files: You don't need to tell Claude about your TypeScript compiler options or ESLint rules because it can read tsconfig.json and .eslintrc directly. Reserve CLAUDE.md for higher-level intent, workflow rules, and constraints that existing config files can't express.
# Bad: duplicating what tsconfig.json already says.
## TypeScript Config
- Target ES2022. Use strict mode. Enable esModuleInterop.
# Good: adding intent that config files cannot express.
## TypeScript Guidance
- When adding new types, co-locate them in a types.ts file next
to the module that uses them. Only put shared types in src/types/.
- Prefer `satisfies` over type assertions for object literals.
- Use `as const` for configuration objects that should be narrowed.Quick-Start Checklist for a New Project
When adding Claude Code to an existing project, create your CLAUDE.md in this order. First, write one sentence describing what the project is and what stack it uses. This prevents Claude from guessing wrong. Second, add the build, test, and lint commands explicitly, because Claude can't always infer the correct commands from package.json scripts. Third, list the two or three directories that Claude should never modify (generated code, vendored deps, migration files). Fourth, add your verification steps. This minimal file prevents 80% of the issues that teams encounter when they first adopt Claude Code. Expand from there only when you observe a repeated problem.