On
Setting Up CLAUDE.md for Claude Code: Complete Guide with Templates

A well-crafted CLAUDE.md file won't do your thinking for you—but it eliminates the tedious repetition of explaining the same technical constraints, boundaries, and verification processes in every conversation. This is where the real productivity gains happen.

The file works best when it's not just a generic wish list. Instead, it should tell Claude Code which commands actually work in your setup, where the critical code lives, which files are off-limits for changes, and how to verify when a task is genuinely complete.

Table of Contents

What CLAUDE.md Does

CLAUDE.md is a standard Markdown file that Claude Code loads into its project memory and uses as supplemental guidance during work sessions. It's the ideal place to store details that apply across multiple tasks:

  • Reliable commands for development, testing, and building your application
  • An overview of key directories and main entry points
  • Architectural patterns and dependency conventions
  • Hard boundaries—for example, "never run database migrations without explicit approval"
  • Clear completion criteria so Claude can verify the work actually meets requirements

This doesn't replace a detailed task description. Specific outputs, scope, and acceptance criteria should still be stated in your current prompt. Conversations can be trimmed or lose important context over time. Put long-term project rules and constraints in this file instead of relying on chat history.

Hierarchical Structure: System-Level, Project-Level, and Subdirectories

Claude Code assembles configuration files based on your working path. On startup, it layers content from outermost folders inward. CLAUDE.local.md in the same directory gets loaded after CLAUDE.md. A CLAUDE.md in a subdirectory gets included in context when Claude reads files in that area.

Example of a real-world hierarchy

~/.claude/CLAUDE.md
  Personal rules applied to every project

~/projects/shop/CLAUDE.md
  General shop project guidelines

~/projects/shop/apps/admin/CLAUDE.md
  Specific rules for the admin frontend

~/projects/shop/apps/admin/src/payments/CLAUDE.md
  Extra safeguards for payment processing

Put shared project information in CLAUDE.md at your project root, or in .claude/CLAUDE.md one level up. Pick a convention and stick with it across the repository. Write rules so they don't conflict with each other—Claude Code merges file contents instead of applying a priority system to resolve contradictions.

Claude Code's official documentation on memory hierarchy
Claude Code's official documentation on memory hierarchy

Anthropic covers project-level, user-level, and local memory files in detail in the official Memory documentation. The exact interfaces and terminology may shift, so check back there when making major configuration changes.

What Goes Into Each File

System-Wide CLAUDE.md

Your ~/.claude/CLAUDE.md file holds personal rules that apply across multiple projects. This might include formatting preferences, your preferred languages for code and comments, or your personal authentication workflow. It shouldn't contain assumptions tied to any specific repository.

Project-Level CLAUDE.md

This file lives in your repository and describes the overall project state. Keep it under version control when your team needs to stay aligned on common commands and rules. Only include information that actually reflects your codebase, configuration, or decisions the team has agreed on.

CLAUDE.local.md

Use CLAUDE.local.md for personal additions at the same location—like local test data or your personal workflow shortcuts. Add this to .gitignore. Passwords, API keys, customer data, and other sensitive information have no place in any CLAUDE.md file.

Rules for Subdirectories

Creating files in subdirectories makes sense when a specific area has unique risks or conventions. Payment processing, data migrations, and mobile apps are classic examples. Don't duplicate your entire root file here—just add rules specific to that area.

Pro Tip: An effective rule is one that drives specific decisions. "Write clean code" is vague. "Run existing migration tests before altering database schema" is something you can actually verify.

System-Wide CLAUDE.md for Your Workflow

Your system-level file at ~/.claude/CLAUDE.md should be repository-agnostic. This is where you define how Claude works with you in general. Avoid assumptions about specific frameworks or projects.

Sample content for ~/.claude/CLAUDE.md

# Personal Working Guidelines

## Collaboration
- Explain your plan and verification steps before making large changes.
- Ask clarifying questions if expected outcomes or scope aren't clear.

## Code
- Prefer TypeScript if the project already uses it.
- Use the project's existing formatters and test runners.

## Before You Finish
- List changed files and completed checks.
- Flag any remaining risks or unknowns.

A Lean Template for Your Project Root

Create the file directly in your project root, or let Claude Code draft an initial version with /init. Auto-generated drafts won't capture your project's nuances. Review, remove bad assumptions, and only add rules you actually follow.

CLAUDE.md template for projects

# Project Name

One sentence describing the product and who uses it.

## Key Directories
- src/app/: routes and pages
- src/lib/: business logic and integrations
- tests/: automated test suites

## Running and Verifying
bash
npm run lint
npm run test
npm run build


## Core Rules
- Check for existing components before creating new ones.
- Validate all input at API boundaries.
- Document changes to public interfaces.

## Hard Limits
- Never log sensitive information to files or output.
- Don't run data migrations without a confirmed plan.
- Ask before proceeding if requirements are unclear.

## Task Complete When
- All agreed-upon checks pass.
- Documentation and tests reflect actual behavior.

Use the @imports syntax to reference long, stable documents. A line like @docs/architecture.md will load that file at startup. What's interesting here is that imports only support a limited depth, so avoid importing your entire documentation suite by default.

How CLAUDE.md Differs from Auto Memory

Auto Memory stores reusable insights privately and locally. The system discovers stable project patterns as Claude works and learns from them. It's different from guidelines you've vetted and shared in your repository.

CLAUDE.md remains the authoritative source for standards, security boundaries, commands, and architectural decisions. Think of Auto Memory as a helper tool. The /memory command lets you view and manage stored items.

What If Claude Code Ignores Your Rules?

  1. Run pwd to confirm Claude Code launched in the intended project directory.
  2. Open /context and check what's loaded in the current session.
  3. Use /memory to make sure Auto Memory isn't conflicting with a specific project rule.
  4. Run claude --version and claude doctor if setup or configuration looks unusual.
  5. Try claude --safe-mode if you're troubleshooting customization errors. This mode skips CLAUDE.md files, skills, plugins, hooks, MCP servers, and Auto Memory. Authentication, model selection, built-in tools, and permissions still work normally. Management policies remain active.

If the file loaded but Claude still misbehaved, narrow down your rules and name specific verification steps. Instead of "be careful with emails," write "display the recipient, subject, and body for confirmation before sending."

Working Alongside Other Development Tools

Some teams also use AGENTS.md files. Avoid duplicating rules across multiple files when you can. Claude Code can include a shared file through an import like @AGENTS.md. Then your CLAUDE.md (kept concise) can explain why that file takes the lead and list Claude-specific additions.

Review your actual commands and most critical rules after each major change. A short, accurate file beats a lengthy collection of outdated guidelines every time.

Description: Learn how to create effective CLAUDE.md files at system, project, and subdirectory levels to guide Claude Code through your workflows.

Related Articles