← All posts
·4 min read

How to Set Up a CLAUDE.md File (With Examples)

The single highest-leverage thing you can do to make Claude Code better at your project is write a good CLAUDE.md file. It takes ten minutes and pays off on every session.

What a CLAUDE.md File Is and Why It Matters

A CLAUDE.md file is a plain markdown file that Claude Code reads automatically at the start of every session. It loads into context before you type a single word. Think of it as the onboarding doc you wish every new engineer read on day one — except this reader actually reads it.

Without it, Claude has to rediscover your project every time. It guesses your build command, infers your conventions from scattered files, and sometimes gets it wrong. With it, Claude starts each session already knowing how you work.

The difference shows up fast. Fewer wrong assumptions. Fewer "actually, we use pnpm not npm" corrections. Less back-and-forth before the real work starts. You are front-loading the context that would otherwise leak out one mistake at a time.

Where to Put It: Project vs Global vs Nested

There are three places a CLAUDE.md file can live, and they stack.

  • Project root — the most common spot. Put CLAUDE.md at the top of your repo and commit it. Everyone on the team shares it, and it travels with the code.
  • Global — ~/.claude/CLAUDE.md applies to every project on your machine. This is for your personal preferences: how you like commits written, tools you always reach for, your general working style. It is not committed to any repo.
  • Nested — drop a CLAUDE.md inside a subdirectory and Claude picks it up when working in that part of the tree. Handy in monorepos where the frontend and the API have different conventions.
The mental model: global is you, project root is this repo, nested is this corner of the repo. They combine, with more specific files adding detail rather than replacing the broader ones.

What to Include

Keep it focused on what Claude cannot easily infer. Good things to cover: a one-line project overview, the build and test and lint commands, code conventions, key architecture notes, and the gotchas that bite newcomers.

Here is a realistic example for a small Next.js app:

# Project: Acme Dashboard

Next.js admin dashboard for managing customer accounts.
TypeScript, App Router, Postgres via Prisma.


Commands


  • Install: pnpm install (we use pnpm, not npm)
    • 

  • Dev server: pnpm dev
    • 

  • Tests: pnpm test (Vitest)
    • 

  • Lint + typecheck: pnpm check before every commit
    • 



Conventions


  • Server Components by default; add "use client" only when needed
    • 

  • Data fetching lives in src/lib/queries/, never inline in components
    • 

  • Use the cn() helper from src/lib/utils for class names
    • 

  • No default exports except in page.tsx files
    • 



Architecture


  • src/app/ — routes (App Router)
    • 

  • src/lib/ — shared logic, db client, queries
    • 

  • src/components/ui/ — primitives; do not edit by hand, generated by shadcn
    • 



Gotchas


  • The Prisma client is a singleton in src/lib/db.ts — import from there
    • 

  • Env vars are validated in src/env.ts; add new ones there or the build fails
Notice it points to specific files. That is the move — Claude can read a file you reference far more reliably than it can guess where logic lives.

What to Leave Out

A CLAUDE.md file is loaded into context every session, so every line costs tokens. Bloat is a real tax. Leave out anything Claude can discover on its own or that does not change how it should act.

Skip the full dependency list — it can read package.json. Skip long prose explaining why you chose a framework. Skip generated files, lockfiles, and anything already obvious from the directory structure. Skip secrets and credentials entirely; this file gets committed.

If a section is not changing Claude's behavior, it does not belong. When in doubt, cut it.

Tips for Keeping It Lean

A CLAUDE.md file is a living document. Treat it like code, not a one-time setup.

  • Start small. A dozen lines that are all correct beats a hundred that are half stale. Add detail when you notice Claude repeatedly getting something wrong.
  • Reference, don't duplicate. Point to other docs with a path instead of pasting their contents. You can even reference another file inline so it loads on demand rather than every session.
  • Prune regularly. When a convention changes, update the file in the same commit. A stale CLAUDE.md is worse than none because it actively misleads.
  • Watch for repeated corrections. If you find yourself telling Claude the same thing twice, that is a line your CLAUDE.md is missing.
For bigger setups, pair your CLAUDE.md with reusable tooling. Claude Code subagents let you hand specialized work to focused agents, and slash commands turn repeated prompts into one-word triggers. Your CLAUDE.md sets the context; those handle the workflows.

Want a head start instead of building everything from scratch? AgentsCamp is a directory of ready-to-use Claude Code agents, skills, and slash commands you can drop into any project with npx agentscamp add. Browse them at agentscamp.com and spend your ten minutes on the CLAUDE.md instead.

← All posts