What Is Claude Code's claude.md File? The Permanent Instruction Manual for Your AI Agent

The Persistent Context File Most Claude Code Users Ignore

If you’ve spent more than a few minutes with Claude Code, you’ve probably run into a familiar frustration: you explain your project setup, your coding conventions, your preferred testing approach — and then you start a new session and have to do it all over again.

The claude.md file (officially CLAUDE.md) exists specifically to fix this. It’s the permanent instruction manual that gets loaded into every Claude Code session automatically, before you type a single message.

Most people either don’t know it exists, or use it in a way that makes it nearly useless. This guide covers what the file actually is, how Claude Code uses it, what belongs in it, and what a well-structured version looks like in practice.

What the CLAUDE.md File Actually Is

CLAUDE.md is a plain markdown file that Claude Code reads at the start of every session. Whatever you put in it gets injected into the model’s context automatically — no prompting required.

Think of it as a standing brief. Every time you open a session in a project, Claude already knows your preferred code style, how the project is structured, which commands to run, and any rules you’ve set for how it should behave.

It’s not a config file in the traditional sense. It doesn’t change how Claude Code the application behaves. It changes what Claude the model knows at the start of every conversation.

Where the File Lives

Claude Code supports multiple CLAUDE.md files in a hierarchy:

Global (~/.claude/CLAUDE.md) — Applies to every project. Good for personal preferences, default coding standards, or tools you use everywhere.
Project root (./CLAUDE.md) — Applies to a specific repository. This is where project-specific context lives.
Subdirectory-level — You can place CLAUDE.md files inside subdirectories (like /frontend or /api) to scope instructions to that part of the codebase.

When you start a session in a project folder, Claude Code reads all applicable CLAUDE.md files in order — global first, then project root, then subdirectory — and combines them into a single context block.

How Claude Code Uses the File

The contents of CLAUDE.md are prepended to Claude’s context at session start. This means:

Claude reads it before your first message.
The instructions are always “in scope” throughout the session.
You don’t have to re-explain things every time.

The file counts toward Claude’s context window, so length matters. A bloated CLAUDE.md that runs thousands of tokens long will eat into the space available for actual conversation, code review, and reasoning.

The goal is signal density: every line should earn its place.

What to Put in Your CLAUDE.md File

This is where most users go wrong. They either write too little (a vague sentence or two) or too much (a 3,000-word document that tries to explain everything about the project).

Here’s a breakdown of what actually belongs in the file — organized by category.

Project Overview (Keep It Short)

One or two sentences about what the project is and what it does. This helps Claude understand scope and intent without you having to mention it every session.

This is a Next.js 14 app for managing B2B invoices. It connects to a Postgres database via Prisma and exposes a REST API consumed by the frontend.

Don’t write a paragraph. Don’t copy-paste your README. One or two sentences that orient Claude to the work.

Tech Stack and Versions

List the key technologies, frameworks, and versions in use. This prevents Claude from suggesting approaches that don’t fit your stack.

- Node.js 20 / TypeScript 5.3
- Next.js 14 (App Router)
- Prisma 5.x + PostgreSQL
- Tailwind CSS 3.x
- Vitest for unit tests, Playwright for E2E

If version matters — and with rapidly-changing tools, it often does — include it.

Common Commands

One of the most practical things you can add is a reference to your development workflow commands. This prevents Claude from guessing at commands or writing incorrect scripts.

## Commands
- `pnpm dev` — Start dev server
- `pnpm test` — Run unit tests (Vitest)
- `pnpm test:e2e` — Run Playwright tests
- `pnpm db:migrate` — Run Prisma migrations
- `pnpm build` — Production build

Code Style and Conventions

If your team has agreed-on conventions, document them here. Claude will follow them without you having to ask.

## Code Conventions
- Use named exports, not default exports
- Prefer `const` over `let` unless mutation is needed
- All async functions must handle errors explicitly
- No inline comments unless explaining non-obvious logic
- File names: kebab-case for routes, PascalCase for components

Keep this focused. Don’t try to reproduce your entire ESLint config in prose — just capture the decisions that are likely to affect how Claude writes code.

Architecture and Project Structure

A brief description of how the codebase is organized helps Claude navigate your project and generate code in the right place.

## Directory Structure
- `/app` — Next.js App Router pages and layouts
- `/components` — Shared UI components
- `/lib` — Utility functions and helpers
- `/prisma` — Database schema and migrations
- `/tests` — Unit and integration tests

You don’t need to list every file. Just the top-level structure and any non-obvious conventions (e.g., “API route handlers live in /app/api, not /pages/api”).

Behavior Rules

This is where you tell Claude how to behave — not just what to know. These are instructions, not descriptions.

## Rules
- Never modify database migration files that have already been run
- Always write tests for new utility functions
- Ask before refactoring existing code — only change what's needed for the task
- Do not add new dependencies without flagging them first

These constraints are especially valuable for preventing the common failure mode where an AI agent helpfully “improves” things you didn’t ask it to touch.

What to Leave Out

A few things people commonly add that don’t belong:

Lengthy background context — If it takes more than a paragraph to explain, it probably belongs in a separate doc that Claude can reference, not in the persistent file.
Duplicated documentation — If something is already in your README or a /docs folder, don’t copy it into CLAUDE.md. Either reference the file or trust that Claude can read it when needed.
Personal opinions without reasoning — “Don’t use class components” is fine. A three-paragraph philosophical take on OOP is not.
Sensitive credentials or tokens — Never. Even in a local file, this is a bad habit to build.

Structuring Your CLAUDE.md for Readability

Because the file is markdown, you have full formatting control. Use it.

A few structural principles that make the file more effective:

Use headers to separate categories. Claude processes markdown structure well. H2 headers (##) for major categories help delineate between “project context,” “conventions,” and “rules.”

Keep each section scannable. Bullet points are better than dense paragraphs for this kind of reference material.

Put the most important things first. Context window usage isn’t always linear, but in general, Claude gives more weight to earlier context. Your most critical instructions should lead.

Use imperative statements for rules. “Never modify X” and “Always write tests for Y” are more actionable than “It’s preferred that X be avoided.”

Here’s what a clean, practical CLAUDE.md structure looks like:

## Project
One-line description of what this is.

## Stack
- Technology: Version
- Technology: Version

## Commands
- `command` — what it does

## Conventions
- Convention 1
- Convention 2

## Architecture
Brief description of directory structure and key patterns.

## Rules
- Hard rule 1
- Hard rule 2

That’s it. Clean, dense, and useful.

Why Most Users Get It Wrong

There are two failure modes, and they’re equally common.

The empty or minimal file. Some developers create a CLAUDE.md with nothing in it, or just a project title. This wastes the feature entirely. Claude has no standing context, so you end up re-explaining conventions in every session or getting outputs that don’t match your codebase.

The over-stuffed file. The opposite problem: treating CLAUDE.md as a dump for every piece of project documentation that exists. Files that run 2,000+ words become hard for the model to weigh effectively — and they eat into the context that should be available for actual work.

The right mental model is: what would you tell a senior developer joining your team in the first five minutes? That’s what goes in CLAUDE.md.

You’re setting up working knowledge — the stuff that would be annoying to have to explain repeatedly. Not the full onboarding wiki.

Managing Multiple CLAUDE.md Files in a Large Codebase

For monorepos or large multi-service codebases, the file hierarchy is especially useful.

You might have:

A global CLAUDE.md with your personal preferences (preferred patterns, testing philosophy, general style)
A root-level CLAUDE.md with project-wide context (stack, shared commands, top-level architecture)
Subdirectory CLAUDE.md files in /frontend, /api, /workers, etc., with context specific to that service

This keeps each file focused. The frontend CLAUDE.md doesn’t need to explain database migration conventions. The API CLAUDE.md doesn’t need to list Tailwind utilities.

When Claude Code starts a session in /frontend/components, it reads global → root → /frontend in sequence. The combined context is complete, but each individual file stays manageable.

Where MindStudio Fits If You’re Building Beyond a Single Codebase

Claude Code with a well-configured CLAUDE.md is great for focused development work within a project. But once you’re trying to build AI agents that need to do things outside the codebase — send emails, call APIs, trigger workflows, generate images, update CRMs — you’re essentially building infrastructure around your AI.

That’s where MindStudio becomes relevant.

MindStudio is a no-code platform for building and deploying AI agents. If you’re using Claude Code to build agents or AI-powered applications, MindStudio’s Agent Skills Plugin (@mindstudio-ai/agent on npm) gives any AI agent — including those built with or orchestrated by Claude Code — access to 120+ typed capabilities as simple method calls.

So instead of building email-sending infrastructure, retry logic, Google search integration, or image generation pipelines yourself, your agent calls agent.sendEmail(), agent.searchGoogle(), or agent.generateImage() directly. The SDK handles rate limiting, retries, and auth.

For developers who are using Claude Code to build agentic systems, this reduces the amount of plumbing you need to document, maintain, and debug. And because your agent’s capabilities are handled externally, your CLAUDE.md stays focused on what it should be: project context, not infrastructure docs.

You can try MindStudio free at mindstudio.ai.

Keeping Your CLAUDE.md Current

A CLAUDE.md that’s six months out of date is worse than no file at all. It gives Claude confident but wrong information about your project.

A few habits that help:

Update it when your stack changes. New dependency, new testing framework, deprecated service — update the file the same day.
Review it when onboarding changes. Your CLAUDE.md is a proxy for “what does a developer need to know to work effectively here.” If your answer to that question changes, the file should change too.
Treat rule violations as file feedback. If Claude keeps doing something you’ve asked it not to, and you find yourself correcting it repeatedly, that’s a signal your rule isn’t in the file — or isn’t worded clearly enough.

Frequently Asked Questions

Does CLAUDE.md work with Claude Code on any project?

Yes. Any project you open in Claude Code can have a CLAUDE.md at the root. Claude Code will detect and read it automatically. You don’t need to configure anything — just create the file and Claude will pick it up on the next session start.

How long should a CLAUDE.md file be?

There’s no universal rule, but a practical target is under 500 words for a project-level file. Global files can be even shorter — often 100–200 words. If your file is getting long, that’s usually a sign you’re including content that belongs in separate documentation rather than a persistent context brief.

Can I have more than one CLAUDE.md in the same project?

Yes. Claude Code supports a file hierarchy: global (in your home directory), project root, and subdirectory-level files. All applicable files are read in order and combined. This is particularly useful for monorepos or multi-service projects where different parts of the codebase have different conventions.

Will CLAUDE.md affect how Claude Code handles code it reads in the project?

Not directly — CLAUDE.md doesn’t change how Claude reads files. It changes what Claude knows before you start interacting. But if your file contains accurate information about architecture and conventions, it improves the quality of suggestions Claude makes when it does read code, because it has better context for interpreting what it sees.

What’s the difference between CLAUDE.md and system prompts?

CLAUDE.md is Claude Code’s way of injecting project-level context into sessions. A system prompt (in the traditional sense) is a message prepended by the application layer before user input. In Claude Code, CLAUDE.md is the mechanism that effectively serves that role — it’s how you inject standing instructions into the model’s context without using a custom API wrapper or tool configuration.

Can I use CLAUDE.md to change Claude’s tone or communication style?

Yes. You can include behavioral instructions like “respond concisely without unnecessary explanation” or “always explain your reasoning before writing code.” These are treated the same as technical conventions — Claude will follow them throughout the session.

Key Takeaways

CLAUDE.md is a markdown file Claude Code reads at the start of every session, providing persistent context without any prompting on your part.
Files exist in a hierarchy: global (~/.claude/CLAUDE.md), project root, and subdirectory-level — all applied in order.
The most useful content: project overview, tech stack, common commands, code conventions, architecture notes, and explicit behavior rules.
Keep the file short and dense — target under 500 words. A bloated file wastes context and dilutes the signal.
Update it whenever your stack or conventions change; outdated context is actively harmful.
For AI agents that need capabilities beyond the codebase, MindStudio’s Agent Skills Plugin provides 120+ pre-built capabilities that Claude Code agents can call directly — so you’re building the agent, not the infrastructure around it.