Perfect CLAUDE.md File Template (2026)

Getting Claude Code to follow your project conventions starts with one file: CLAUDE.md. A well-structured CLAUDE.md eliminates the guesswork Claude faces when generating code, leading to fewer corrections and faster iteration. This guide provides the definitive template you can copy, customize, and start using in under five minutes.

If you have tried writing a CLAUDE.md before and found Claude ignoring parts of it, the problem is almost always structure. (Prefer to generate one automatically? Use the CLAUDE.md Generator.) Claude reads this file into its context window at session start. Vague or bloated instructions get deprioritized. Specific, scannable rules get followed consistently.

Why Structure Matters

Claude Code loads CLAUDE.md into its context alongside your conversation. Every line competes for attention against the actual task. Research across thousands of projects shows that files under 200 lines with clear section headers achieve over 90 percent adherence, while files exceeding 500 lines drop below 60 percent.

The template below uses a hierarchy proven to maximize compliance: identity first, then hard constraints, then soft preferences.

The Annotated Template

Here is the complete template with inline annotations explaining each section:

# CLAUDE.md
## Project Identity
- Project: [Your Project Name]
- Language: TypeScript 5.4 / Node 20
- Framework: Next.js 14 (App Router)
- Package manager: pnpm (never use npm or yarn)
## Hard Rules (Never Violate)
- Use 2-space indentation for all files
- All functions must have explicit return types
- Never import from src/internal/ in public modules
- Run `pnpm test` before every commit
- Maximum function length: 60 lines
- Zero TypeScript errors allowed (strict mode)
## File Organization
- API handlers: src/api/handlers/
- Components: src/components/[Feature]/
- Utilities: src/lib/
- Tests: __tests__/ mirroring src/ structure
## Testing Requirements
- Every new function needs a unit test
- Integration tests for API endpoints
- Use vitest, not jest
- Minimum 80% coverage on new code
## Code Style Preferences
- Prefer named exports over default exports
- Use early returns to reduce nesting
- Destructure function parameters when 3+ fields
- Prefer const assertions for literal types
## Commit Standards
- Conventional commits: feat|fix|docs|refactor|test
- Include ticket number: feat(auth): add SSO [PROJ-123]
- Squash WIP commits before PR

Section-by-Section Breakdown

Project Identity tells Claude the exact technology stack. Without this, Claude guesses based on file contents and sometimes gets it wrong, especially with monorepos containing multiple languages.

Hard Rules are non-negotiable constraints. Keep these to 10 or fewer. Claude treats shorter lists as higher priority. If you list 30 hard rules, Claude will inevitably break some of them.

File Organization prevents Claude from creating files in wrong directories. This single section eliminates the most common complaint about Claude Code: files ending up in unexpected locations.

Testing Requirements specify the test runner and coverage expectations. Without this, Claude defaults to jest even in vitest projects, or skips tests entirely.

Code Style Preferences are softer guidelines. Claude follows these most of the time but may deviate when the task context strongly suggests otherwise. That is acceptable behavior for preferences.

Commit Standards ensure Claude’s git commits match your team’s conventions. This matters when using Claude Code’s built-in commit workflow.

Scoping Your CLAUDE.md Files

Claude Code supports multiple CLAUDE.md files at different scopes:

Scope Location Loaded When
Managed policy /Library/Application Support/ClaudeCode/CLAUDE.md Always (org-enforced)
Project root ./CLAUDE.md Every session in project
Subdirectory ./packages/api/CLAUDE.md Working in that directory
User global ~/.claude/CLAUDE.md Every session, all projects
Local override ./CLAUDE.local.md Personal project overrides

The loading order is: managed policy, then user global, then project root, then subdirectory. Conflicts resolve in favor of the more specific scope.

For team projects, put shared standards in the project root CLAUDE.md and commit it to version control. Individual developers add personal preferences to CLAUDE.local.md, which should be in .gitignore.

Common Mistakes to Avoid

Too many rules. If your CLAUDE.md exceeds 200 lines, Claude starts dropping instructions. Split into scoped files or prioritize ruthlessly.

Vague instructions. “Write clean code” means nothing. “Use early returns to keep nesting under 3 levels” is actionable and verifiable.

Contradictory rules. If your project CLAUDE.md says “use jest” and a subdirectory CLAUDE.md says “use vitest,” Claude gets confused. Audit your files for conflicts.

Stale references. Pointing to directories or tools that no longer exist causes Claude to hallucinate workarounds. Keep your CLAUDE.md current with your actual project structure.

Advanced Patterns

For monorepos, place a root CLAUDE.md with shared rules and per-package CLAUDE.md files with package-specific configuration:

monorepo/
  CLAUDE.md              # Shared: linting, commit standards
  packages/
    api/CLAUDE.md        # API: Express patterns, DB access rules
    web/CLAUDE.md        # Web: React patterns, CSS framework
    shared/CLAUDE.md     # Shared: no external dependencies allowed

For conditional rules based on file type, use explicit scoping in your instructions:

## TypeScript Files
- Strict mode, no `any` types
- Prefer interfaces over type aliases for objects
## CSS/SCSS Files
- BEM naming convention
- No inline styles in components
- Design tokens from src/styles/tokens.ts only

Try It Yourself

Writing a CLAUDE.md from scratch takes time, especially when you need to cover every section. The CLAUDE.md Generator builds a complete, optimized CLAUDE.md file based on your project’s language, framework, and team size. Answer a few questions and get a production-ready template in seconds.

Validating Your CLAUDE.md

After creating your file, test it by starting a new Claude Code session and asking Claude to describe the rules it is following. A well-structured CLAUDE.md produces a response that accurately mirrors your instructions. If Claude misses sections, those sections are likely too vague or buried too deep in the file.

You can also validate by giving Claude a task and checking the output against your rules. For example, ask Claude to create a new API endpoint and verify it follows your file organization, testing requirements, and code style preferences.

Frequently Asked Questions

How long should a CLAUDE.md file be?

Keep it under 200 lines for optimal adherence. Files under 150 lines with clear section headers achieve the highest compliance rates. If you need more rules, split them across scoped subdirectory files.

Can I use CLAUDE.md with other AI coding tools?

CLAUDE.md is specific to Claude Code. Other tools like Cursor use different configuration files. However, the principles of specific, scannable instructions apply universally to any AI coding assistant.

Should I commit CLAUDE.md to version control?

Yes, commit the project-level CLAUDE.md so your entire team shares the same rules. Use CLAUDE.local.md for personal preferences and add it to .gitignore.

What happens if Claude ignores my CLAUDE.md rules?

First check file length. Then verify rules are specific and verifiable. Vague instructions like “write good code” get deprioritized. If a specific rule is still ignored, move it higher in the file or into the Hard Rules section.