What Is the claude.md File? How to Write a Permanent Instruction Manual for Claude Code

Stop Re-Explaining Yourself to Claude Every Single Session

Every developer who uses Claude Code for more than a day hits the same wall. You open a new session, start a task, and within minutes you’re typing out the same context you explained yesterday. “We use TypeScript. Don’t use var. Always write unit tests. Our API follows REST conventions…”

That’s the problem the CLAUDE.md file solves.

The CLAUDE.md file is a plain Markdown document that Claude Code reads automatically at the start of every session. Write it once, and Claude reads it every time it opens your project. It’s your permanent instruction manual — covering your tech stack, coding conventions, brand voice, and any rules you don’t want to re-explain.

This guide covers what the claude.md file actually does, what to put in it, and how to write one that makes Claude consistently more useful across sessions.

What the CLAUDE.md File Actually Does

Claude Code doesn’t retain memory between sessions. Close a conversation, open a new one, and you’re starting from zero. The CLAUDE.md file is the mechanism Anthropic built into Claude Code to address this limitation.

When you launch Claude Code in a directory, one of the first things it does is look for a CLAUDE.md file. If it finds one, it reads the entire contents and loads them into context before you type a single message. The file’s instructions become part of Claude’s working understanding before the conversation begins.

This has a direct practical effect: Claude doesn’t need to ask what language you’re using, what your naming conventions are, or how your codebase is structured. It already knows — because you told it in the file.

Where Claude Looks for CLAUDE.md

Claude Code checks a few locations, in order of specificity:

Project root (./CLAUDE.md) — The most common placement. Rules here apply to that specific project only.
Subdirectories — You can place additional CLAUDE.md files deeper in a project. Claude reads the file closest to the code it’s working on.
Global config (~/.claude/CLAUDE.md) — Applies across all projects. Good for personal preferences that don’t change project to project, like commit message style or communication preferences.

If both a global and project-level file exist, Claude reads both. Project-level instructions take precedence when they conflict.

What Claude Does With the File

The full file contents are loaded into context — not summarized, not selectively parsed. This means:

Instructions apply immediately, before any user message.
Rules in CLAUDE.md persist for the entire session.
Claude can reason about the instructions directly if asked.

One constraint worth knowing: the file counts against Claude’s context window. A very long CLAUDE.md (thousands of tokens) eats into the space available for actual conversation and code. Keep it focused.

What to Put in Your CLAUDE.md File

Most explanations of CLAUDE.md say “put your preferences in it” without specifying what preferences actually matter. Here’s a breakdown of the categories worth including, with reasons each one helps.

Project Overview

A short summary of what the project is and who it’s for. Two to four sentences is enough.

Why it helps: Without context, Claude can misinterpret ambiguous requests. “Add a user endpoint” means something different in a billing API versus a social platform.

## Project Overview
This is a B2B SaaS application for managing invoice workflows.
It's a Next.js frontend with a Node.js/Express backend and a
PostgreSQL database. Main users are finance teams at mid-market companies.

Tech Stack and Architecture

List the core technologies and any architectural constraints Claude should be aware of.

## Tech Stack
- Frontend: Next.js 14 (App Router), TypeScript, Tailwind CSS
- Backend: Node.js, Express, Prisma ORM
- Database: PostgreSQL
- Testing: Vitest, React Testing Library
- Deployment: Vercel (frontend), Railway (backend)

Coding Conventions

This is the highest-value section for reducing friction. Be specific. Don’t say “write clean code” — say what clean code means in your context.

## Coding Conventions
- Use `const` over `let`. Never use `var`.
- All functions must have explicit TypeScript return types.
- Use named exports, not default exports.
- File names: kebab-case for components, camelCase for utilities.
- Prefer `async/await` over `.then()` chains.
- No inline styles. Use Tailwind classes only.

What NOT to Do

A “do not” list is often more useful than a “do” list. Claude is helpful by default, which sometimes means it adds things you didn’t ask for — refactoring adjacent code, adding dependencies, or changing architecture.

## Rules (Do Not Break These)
- Do NOT modify the auth middleware without being explicitly asked.
- Do NOT add new npm packages without listing them and asking first.
- Do NOT refactor code outside the scope of the current task.
- Do NOT remove existing comments.

Common Commands

Include the commands Claude will need for running, building, and testing the project.

## Commands
- Install: `npm install`
- Dev server: `npm run dev`
- Tests: `npm run test`
- Build: `npm run build`
- Lint: `npm run lint`
- Database migrations: `npx prisma migrate dev`

This matters because Claude Code can execute terminal commands. When it knows your project’s specific scripts, it doesn’t guess or run generic commands that might fail.

Environment Notes

Flag anything unusual about your setup.

## Environment Notes
- Node version: 20.x (use `nvm use` before running anything)
- Requires a `.env.local` file — see `.env.example`
- Database must be running locally via Docker before starting dev server

Brand Voice (For Non-Code Projects)

If you’re using Claude Code for writing, documentation, or content production, define tone and style here. This is where CLAUDE.md earns its keep for non-developers.

## Brand Voice
- Tone: Direct, honest, slightly informal. Never corporate or fluffy.
- Audience: Developers and technical founders.
- Avoid: Exclamation points, filler phrases, passive voice unless necessary.
- Always use second person ("you"), not third person.
- Oxford comma: always.

For more on how tone and style instructions interact with AI output, see the MindStudio guide to prompt engineering fundamentals.

How to Write Instructions Claude Will Actually Follow

Writing the file is one thing. Writing it so Claude reliably respects it is another.

Be Specific, Not Aspirational

“Write good code” does nothing. “Functions should be under 40 lines; if longer, extract helper functions” is something Claude can act on.

The more concrete and measurable a rule is, the more consistently Claude applies it.

Use Imperative Language

Phrase rules as direct commands, not suggestions.

❌ “It would be helpful to include unit tests.”
✅ “Write a unit test for every new function.”

Claude scans the file’s structure as part of reading it. Clear H2 and H3 sections make it easier for Claude to find and apply rules in context — the same reason good prompt structure matters in any AI workflow.

Don’t Include Rules You Don’t Mean

Every rule in the file is something you’re implicitly committing to enforcing. Aspirational rules you don’t follow create noise. If you write “always ask before making changes,” that needs to reflect how you actually want to work.

Iterate on It

Your first CLAUDE.md will be imperfect. Update it after sessions where Claude made assumptions you didn’t like, or when your project’s conventions change. The file improves as your working relationship with Claude matures.

A Complete CLAUDE.md Template

Here’s a starting point you can adapt. The structure works for any type of project — code, writing, or otherwise.

# Project Instructions for Claude

## Project Overview
[2–4 sentences describing what this project is and who it's for.]

## Tech Stack
- [Core technology 1]
- [Core technology 2]
- [Include versions where they matter]

## Project Structure
- `/src/components` — React components
- `/src/lib` — Shared utilities and helpers
- `/src/api` — API route handlers
- `/src/types` — TypeScript type definitions

## Coding Conventions
- [Convention 1]
- [Convention 2]

## Rules (Do Not Break)
- [Non-negotiable rule 1]
- [Non-negotiable rule 2]

## Common Commands
- Dev: `[your dev command]`
- Test: `[your test command]`
- Build: `[your build command]`

## Current Focus
[What you're actively working on right now.
Update this when your focus changes.]

## Known Issues / Gotchas
[Things Claude should know to avoid common mistakes.]

The “Current Focus” Section

The “Current Focus” section is one of the most underused parts of a CLAUDE.md file. Because Claude reads the file fresh each session, you can update this section to point Claude toward what matters right now.

## Current Focus
Working on the invoice export feature. All new work should be in
/src/features/invoice-export/. Ignore the payment module for now —
it's being rewritten by another team.

This turns CLAUDE.md into a session-specific briefing as well as a permanent guide.

Global vs. Project-Level: How to Split Responsibilities

You don’t have to choose between a global and project-level file — both can coexist and serve different purposes.

What Goes in the Global CLAUDE.md

Personal preferences that hold across all your work:

Preferred code style (if consistent across languages)
Communication preferences (“Explain your reasoning when you make a non-obvious choice”)
General constraints (“Never suggest third-party libraries unless the task can’t be done without one”)
System-level environment notes

What Goes in the Project CLAUDE.md

Everything project-specific:

Tech stack and architecture
File structure
Project-specific coding rules
Commands
The “Current Focus” section

Keeping these separate means you maintain your global file once and update project files as those projects evolve. Team members who open the same repository get the same project context automatically.

Common Mistakes That Undermine Your CLAUDE.md

Even well-intentioned files can cause problems. Here are the failure modes to avoid.

Making It Too Long

Every token in your CLAUDE.md uses context window space. A file that runs over 2,000 tokens starts eating into the space Claude needs for actual work. If you have extensive technical documentation, reference external files rather than inlining everything.

Vague Rules That Don’t Constrain Anything

“Be professional” isn’t a rule. “Never use informal contractions in API documentation, but informal tone is fine in code comments” is a rule. Claude needs something concrete to act on.

Contradictions Between Global and Project Files

If your global file says “prefer functional components” and your project file says “use class components for this legacy codebase,” Claude will follow the more specific project instruction. But conflicting signals can still cause inconsistent behavior. Review both files if you’re seeing unexpected output.

Not Updating It

A CLAUDE.md that reflects your project from six months ago is worse than no file at all. If your stack changes, your architecture evolves, or your team’s conventions shift, update the file.

Including Sensitive Information

Never put API keys, passwords, or secrets in your CLAUDE.md file. This file is read into context and could be logged depending on your setup. Reference environment variables by name only.

How MindStudio Handles Persistent AI Context at Scale

The CLAUDE.md file solves the memory problem for Claude Code in your local development environment. But if you’re building AI workflows that your whole team accesses, that run on a schedule, or that connect to external tools — a local config file isn’t enough.

MindStudio is a no-code platform for building AI agents that carry context persistently, without manual session management. Where CLAUDE.md tells Claude what to know at the start of a session, a MindStudio agent encodes that context into its configuration permanently — and can be deployed so anyone on your team accesses the same AI tool, every time.

For developers specifically, the Agent Skills Plugin is an npm SDK that lets any AI agent — including agents you build with Claude Code — call MindStudio capabilities as simple method calls: agent.sendEmail(), agent.searchGoogle(), agent.runWorkflow(). The infrastructure layer (rate limiting, retries, authentication) is handled automatically.

If you’ve invested time in a detailed CLAUDE.md that defines how Claude should understand your project, you’ve already done the thinking needed to build a MindStudio agent that does the same job persistently, at scale, for a whole team.

You can try MindStudio free at mindstudio.ai.

Frequently Asked Questions

What is the difference between CLAUDE.md and a system prompt?

A system prompt is typically set in a UI or API call — it’s passed to the model at the start of a conversation. CLAUDE.md is a file-based version of the same concept, scoped to your project directory and read automatically by Claude Code. The key practical difference is that CLAUDE.md lives in your codebase and can be version-controlled, while a system prompt usually lives outside it.

Does CLAUDE.md work in all Claude interfaces?

No. CLAUDE.md is specifically a Claude Code feature. It’s read by the Claude Code CLI when it starts in a directory. It doesn’t apply in Claude.ai chat, the Anthropic API, or other Claude integrations unless those tools have explicitly implemented support for it.

How long should a CLAUDE.md file be?

Aim for 200–800 words for most projects. Long enough to cover essential context, short enough to preserve context window space. If you find yourself writing several pages, ask whether all of that detail genuinely needs to be in the file, or whether Claude can infer parts of it from your codebase.

Can I have multiple CLAUDE.md files in one project?

Yes. You can place CLAUDE.md files in subdirectories, and Claude Code reads the one closest to the code it’s working on. This is useful for monorepos or projects where different parts have different conventions — a /frontend directory with React conventions and a /backend directory with different standards, for instance.

Do I need to restart Claude Code after editing CLAUDE.md?

Yes. Claude reads the file at the start of a session, so changes take effect the next time you open a new Claude Code session. Edits made during an active session aren’t automatically picked up.

Should I commit CLAUDE.md to version control?

Generally yes, if the file contains project-specific instructions that your whole team would benefit from. When teammates open Claude Code in the same repository, they get the same context automatically. If your file contains personal preferences specific to you rather than the project, keep those in your global ~/.claude/CLAUDE.md instead.

Key Takeaways

The CLAUDE.md file is a Markdown document that Claude Code reads automatically at session start, giving Claude persistent context without manual re-entry.
Place project-specific rules, tech stack details, coding conventions, and commands in a project-level file. Use ~/.claude/CLAUDE.md for personal preferences that apply across all projects.
Write rules in imperative language and be specific — vague instructions don’t translate into consistent behavior.
Add a “Current Focus” section and update it regularly to steer Claude toward what’s relevant right now.
Keep the file under ~800 words to preserve Claude’s context window for actual work.
For persistent, team-accessible AI workflows that go beyond local development, MindStudio lets you deploy agents that carry context without manual session management — start free and have something running in under an hour.