How to Write a Good CLAUDE.md File: A Beginner's Guide (2026)

A CLAUDE.md file is a short, plain-English document that Claude Code reads automatically at the start of every session. It's where you tell the AI what your project is, how to run and test it, the rules it must follow, and the mistakes to avoid — so it starts each conversation already knowing your setup instead of guessing. Think of it as the onboarding note you'd hand a new teammate on day one. This guide shows you exactly what to write, what to leave out, and gives you a starter file you can copy today.

What is a CLAUDE.md file, and why does it matter?

CLAUDE.md is a Markdown file you keep in your project folder. Every time you open Claude Code in that folder, it reads the file before doing anything else. That means your instructions are always "in the room" — you don't have to re-explain your project, paste the same rules, or remind it which command runs your tests every single time.

Without one, Claude Code is smart but blind to your specifics. It might try npm test when your project uses something else, or rewrite a file you never wanted touched. With a good CLAUDE.md, it acts like someone who already read the onboarding doc: fewer wrong turns, fewer wasted rounds, and results that match how you actually work.

What will you learn in this guide?

• What a CLAUDE.md file is and where it lives on your computer
• The fastest way to create one (a single command)
• The five things worth including — and how to phrase them
• The four things you should NOT put in it (a common beginner mistake)
• A copy-paste starter file you can adapt in minutes
• How to keep it short and healthy as your project grows

Where does the CLAUDE.md file go?

In most cases it sits in the top folder of your project, right next to your code, named exactly CLAUDE.md. Claude Code looks for it there automatically. You can also keep a personal one that applies to every project — but if you're just starting, a single file in your project folder is all you need.

• Project file — CLAUDE.md in your project's main folder. Shared with anyone who works on that project. This is the one to start with.
• Personal file — a global CLAUDE.md that applies across all your projects, for your own preferences. Optional, and best added later.
• Folder files — extra CLAUDE.md files inside sub-folders, for rules that only apply to one part of a big project. Advanced; skip it at first.

What's the fastest way to create a CLAUDE.md file?

You don't have to write it from scratch. Run the /init command inside your project and Claude Code looks at your files, works out your tech stack, and drafts a starter CLAUDE.md for you. Then you read it, fix anything wrong, and trim what you don't need. Starting from /init and editing is far easier than facing a blank page.

What are the five things worth putting in a CLAUDE.md?

You don't need many sections — you need the right ones. These five cover almost everything a beginner benefits from. The rule for each: include it only if Claude couldn't reliably guess it on its own.

• Project summary — one or two lines on what this project is. Example: "A small website for a local bakery, built with Next.js." It orients the AI more than you'd expect.
• How to run, test, and build it — the exact commands. Claude Code can't know whether you use one tool or another; tell it, and you save it from guessing wrong and burning several turns.
• Key conventions and structure — a quick map: where the important folders are, which patterns you follow, anything unusual about how the project is organized.
• Rules and boundaries — what it must NOT do without asking. For example: don't delete files, don't change the database, always show a plan before a big change.
• Gotchas — the project-specific traps. "The config file looks unused but it's loaded at build time" is the kind of note that prevents a painful mistake.

What should you NOT put in a CLAUDE.md file?

This is where most people go wrong: they treat CLAUDE.md as a dumping ground and it balloons to hundreds of lines. A bloated file is actually worse than a short one, because the important rules get lost in the noise. Leave these out:

• Anything a formatter or linter already enforces. Don't spend lines telling the AI to add semicolons or use two-space indentation — your tools do that automatically. Never send an AI to do a linter's job.
• Things Claude can just read from the code. If the answer is obvious from the files themselves, you don't need to repeat it. Recent Claude Code versions even flag CLAUDE.md content it could have figured out on its own.
• Long pasted documents. Instead of pasting a whole style guide, point to it: "See docs/style.md." A short pointer beats a giant wall of text.
• Secrets, passwords, or API keys. The file is often shared with your whole team and checked into version control. Sensitive values never belong here.

How long should a CLAUDE.md file be?

Shorter than you'd think. A high-signal CLAUDE.md is usually well under 150 lines, and many good ones are closer to 80–120. The goal isn't to cover everything — it's to cover the things the AI can't guess and would otherwise get wrong. If a line wouldn't make a human reviewer raise an eyebrow when it's broken, it probably doesn't need to be there.

There's also a simple test for where a rule belongs. If breaking it would block your project from building or shipping, enforce it with an automatic tool, not a sentence in CLAUDE.md. If breaking it would just make a teammate frown, that's exactly the kind of thing CLAUDE.md is for.

A copy-paste starter CLAUDE.md you can adapt

Here's a clean, minimal starter. Copy it into a file named CLAUDE.md in your project folder, then swap in your own details. Keep only the lines that are true for you — delete the rest rather than padding it out.

# Project
A small marketing website for a local bakery. Built with Next.js.
# Commands
- Run locally: npm run dev
- Run tests: npm test
- Build for production: npm run build
# Structure
- Pages live in src/app
- Shared components live in src/components
- Do NOT edit anything in src/generated (it's auto-created)
# Rules
- Show a plan before any large change, and wait for my OK
- Never delete files or run data-changing commands without asking
- Match the style of the surrounding code
# Gotchas
- The config in next.config.ts looks unused but is read at build time

How do you keep a CLAUDE.md healthy over time?

A CLAUDE.md isn't set-and-forget, but it also shouldn't grow endlessly. The trick is to edit it when reality changes — not to keep piling on. Two simple habits keep it in good shape:

• Update it when a rule changes. If you switch a command or add a new folder Claude should avoid, fix the line. An out-of-date instruction is worse than no instruction.
• Trim it when it gets long. Every few weeks, skim the file and cut anything the AI is clearly getting right on its own. Shorter files get followed more reliably.

Newer Claude Code versions also remember useful things they learn as they work, so you don't have to write down every small detail yourself. That's one more reason to keep CLAUDE.md focused on the non-obvious rules that really matter, and let the tool handle the rest.