Last updated: April 2026
The CLAUDE.md PlaybookMemory files that actually move output
CLAUDE.md is a markdown file Claude Code loads on every session. It tells Claude your project conventions, commands, architecture, and the mistakes it should not repeat. A good one cuts repeated context, fewer wrong guesses, and a lot less babysitting. A bad one quietly drifts out of date and makes things worse.
This is the exact pattern I use across a Next.js site, a Python scraper, a Go service, and a monorepo — with the mistakes that forced me to rewrite them.
What CLAUDE.md actually is
CLAUDE.md is a plain markdown file at the root of your project. When you start Claude Code in that directory, the contents are injected into the system prompt for every turn of the session. You never paste it, you never reference it; it is just there. Think of it as the onboarding doc you would hand a new engineer on day one, except the engineer never forgets it and never needs to re-read it.
The file is not magic. It is not a config. It is just text that gets prepended to the conversation. That framing matters: every line in CLAUDE.md competes with your actual request for Claude's attention. The shorter and more specific it is, the better it works.
Where Claude Code reads from
Claude Code loads CLAUDE.md from three tiers and merges them. Knowing the order prevents surprises when a project rule seems to be ignored.
User-global: ~/.claude/CLAUDE.md
Your personal preferences that apply everywhere. Tone, git habits, commenting style, universal dos and don'ts. Short. Project files override it.
Parent directories
Claude Code walks up from your current working directory to the repo root, picking up any CLAUDE.md files along the way. Useful in monorepos: a root file holds org-wide rules, an app folder holds app-specific ones.
Project root: ./CLAUDE.md
Checked into the repo, shared with every contributor. This is the file you spend the most time maintaining and the one that most determines output quality.
Precedence: the most specific file wins. A project-level rule overrides a user-global rule of the same kind. That means you can set a global "prefer TypeScript" preference and still have a Python-only repo ignore it by stating "this repo is Python" at the project level.
Anatomy of a strong CLAUDE.md
Six sections do almost all the work. You do not need every one on every project, but if a section is missing that Claude keeps guessing at, add it.
1. Project identity (one or two lines)
What this project is, in plain English. "Next.js site deployed on Netlify." "Python scraper that feeds an Astro site." Give Claude the frame before the details.
2. Commands
The canonical commands to run, build, test, lint, and deploy. Claude will absolutely run the wrong command if you do not tell it which one is right. This is the single highest-ROI section.
3. Conventions
Patterns you want followed: component style, naming, import paths, brand colours, error-handling approach. Keep it to rules you enforce — aspirational rules rot fastest.
4. Architecture
The top-level map: which folder does what, how data flows, where to put new code. Not a file listing — a mental model.
5. Gotchas / Do not touch
The traps. Generated code. Files owned by another team. Fields that look safe to edit but will blow up a migration. This section saves more embarrassment than any other.
6. Deployment
How changes reach production. Auto-deploy from main? Manual via an Actions button? Netlify? Vercel? Docker push? One paragraph is enough.
Five real CLAUDE.md files
Each one is lightly anonymised but based on a file I actually ship with. Copy the shape, not the content — the value is in seeing how little it takes to be useful.
Next.js site (this site)
A Next.js 13 site with Tailwind and Netlify deployment. Note the brand colours, the routing split between /pages and /pages/api, and the build command.
# PromptWritingStudio Next.js 13 Pages Router site with Tailwind. Deployed on Netlify. ## Commands - npm run dev # local dev server on :3000 - npm run build # production build - npm run lint # ESLint ## Conventions - Functional components only, hooks where needed - Tailwind for all styling (no CSS modules, no styled-components) - Brand colours: #1A1A1A (ink), #FFDE59 (accent yellow), #F9F9F9 (panel bg) - Use <Link> from next/link for internal navigation, never <a> - Import Layout from components/layout/Layout on every page ## Architecture - /pages Next.js pages and API routes - /components Reusable UI + Layout - /data JSON for programmatic SEO pages - /lib Schema generators, helpers ## Programmatic SEO pattern - data/modifiers/*.json drives pages/chatgpt-prompts-for/[modifier].js - When adding a new modifier, add the JSON file and the slug will build automatically ## Deployment - Netlify auto-deploys from main - Redirects live in netlify.toml (put above the Next.js catch-all)
Python data project
A Python scraper + data pipeline. Heavy on commands because Python projects usually have a virtualenv dance and a pytest config to remember.
# Tender Scraper Python scraper for Irish public procurement data. Writes JSON files consumed by the Astro site. ## Setup - python -m venv .venv - source .venv/bin/activate - pip install -r requirements.txt ## Commands - python scrape.py # full daily run - python scrape.py --limit 10 # test with 10 notices - python scrape.py --dry-run # fetch + classify, no writes - pytest -q # run test suite ## Conventions - Type hints on every public function - Use pathlib, not os.path - Keep API keys in .env (loaded via python-dotenv) - Never commit .env or any file under data/raw/ ## Data flow TED API -> scrape.py -> classify.py (Claude Haiku) -> src/data/tenders/*.json ## Gotchas - TED API rate limits to ~10 req/sec; respect backoff - Deadlines from TED are date-only; we default times to 17:00 Irish time - resource_id is the canonical key everywhere; never use title as an identifier
Go microservice
A Go service. Emphasises build discipline, test tags, and what to leave alone.
# Orders Service
Go 1.22 HTTP service backing /orders endpoints. Deployed via Docker to ECS.
## Commands
- make run # run locally against docker-compose stack
- make test # unit tests
- make test-int # integration tests (requires docker-compose up)
- make lint # golangci-lint run
## Conventions
- Use context.Context as the first argument on every function that does I/O
- Errors bubble up with fmt.Errorf("context: %w", err) — never swallow
- Handlers live in /internal/http, business logic in /internal/orders
- Generated code under /internal/pb is regenerated via make proto — never hand-edit
## Do not touch
- /migrations/*.sql — additive only, never edit an existing migration
- go.sum is committed; bump deps via go get, not by hand
## Deployment
- CI builds the image, pushes to ECR, and triggers an ECS service update
- Staging auto-deploys from main; prod is manual via the Actions tabMonorepo (root)
A turborepo monorepo. The root CLAUDE.md covers org-wide rules; each app has its own sub-file.
# Acme Monorepo Turborepo monorepo with pnpm workspaces. ## Layout - /apps/web Next.js marketing site (see apps/web/CLAUDE.md) - /apps/dashboard React app for customers (see apps/dashboard/CLAUDE.md) - /apps/api Node/Fastify API (see apps/api/CLAUDE.md) - /packages/ui Shared React components - /packages/config Shared eslint, tsconfig, tailwind presets ## Commands (root) - pnpm install # install everything - pnpm dev # run all apps in parallel - pnpm -F web dev # run a single app - pnpm turbo run build # full build with caching - pnpm changeset # record a version bump ## Org-wide rules - TypeScript strict mode on everywhere - No cross-app imports — go through /packages - All shared types live in packages/types - Add a changeset for any change that affects a published package ## Read the sub-file Before editing inside an app or package, read that folder's CLAUDE.md. Local conventions (framework versions, test commands, specific quirks) live there.
User-global ~/.claude/CLAUDE.md
Your personal preferences that apply to every project. Keep it short — this loads on top of every project file.
# Personal Preferences ## Tone - Terse responses. No trailing summaries. No "I have completed the task" wrap-ups. - No emojis unless I ask for them. ## Code style - Prefer editing existing files over creating new ones - Do not add features beyond what was asked - Do not add defensive error handling for conditions that cannot happen - Default to no comments; explain WHY, never WHAT ## Git workflow - Always git status before committing to confirm what is staged - Never force-push to main; never amend published commits - Use HEREDOC for commit messages so formatting survives ## Projects I work on - Vendors.ie at ~/src/vendors — Irish B2B comparison site - Tender monitor at ~/src/tenders — procurement data - Each has its own CLAUDE.md with project-specific rules
Common mistakes
The six patterns that degrade CLAUDE.md files over time. Every one of these came from a rewrite I had to do.
Writing a novel
Every line of CLAUDE.md costs tokens on every session. A 900-line manifesto is worse than a 90-line one because Claude has to swim through noise to find the rules that actually matter. Cut aggressively. If a line has not helped Claude in months, delete it.
Listing every file
Do not paste your directory tree into CLAUDE.md. Claude can run ls or glob patterns itself. List folders only when their purpose is not obvious from the name (for example, "internal/pb is generated code — never hand-edit").
Aspirational rules you do not enforce
If your CLAUDE.md says "100% test coverage" but CI passes at 40%, Claude will eventually notice the mismatch and stop trusting the file. Only write rules you actually enforce. Soft preferences go under a "Preferences" heading so they are treated as guidance, not gates.
Duplicating the README
The README is for humans reading the repo. CLAUDE.md is for an AI that will read code directly in seconds. Do not restate what the README already says. Focus on the things Claude cannot infer: which functions are deprecated, which paths are generated, which commands are the canonical way to do something.
Putting secrets in it
CLAUDE.md is committed to the repo. API keys, tokens, internal URLs, and customer data do not belong in it. Use environment variables and reference them by name only ("Set MAILGUN_API_KEY in .env before running send_alerts.py").
Letting it rot
Commands change, dependencies change, deploy targets change. A CLAUDE.md that points Claude at a script that no longer exists will waste a full turn before Claude figures out the truth. Review it when you do a major refactor, change CI, or rename a directory.
Keeping it from drifting
CLAUDE.md rots faster than README.md because you interact with it indirectly — through Claude's output quality rather than by reading it. Three habits keep mine honest.
- Update on the same PR as the change. If you rename a directory, move a command, or deprecate a pattern, update CLAUDE.md in the same commit. Separate "docs PRs" never happen.
- When Claude gets something wrong twice, update the file. The first time is a hiccup. The second time is missing context. Add one line and move on.
- Re-read it every quarter. Open it, scan it, delete anything that is no longer true. A five-minute audit catches 90% of the rot.
Frequently Asked Questions
Questions that come up every time I show this file to another developer.
What is a CLAUDE.md file?+
CLAUDE.md is a plain markdown file you place in your project that gives Claude Code persistent context about the project: conventions, architecture, commands, gotchas, and anything else Claude should know before making changes. It is loaded automatically into every Claude Code session started from that directory, so you never have to repeat the same context.
Where does Claude Code look for CLAUDE.md files?+
Claude Code looks in three places and merges them in this order. First, your user-global file at ~/.claude/CLAUDE.md, which applies to every project. Second, any CLAUDE.md files in parent directories of your project. Third, the CLAUDE.md in your project root. Instructions from more specific (project-level) files win over more general (user-global) ones.
Should CLAUDE.md be committed to the repository?+
Yes. Treat CLAUDE.md as project documentation. Commit it so every contributor (and every Claude Code session on every machine) gets the same context. Keep personal preferences in ~/.claude/CLAUDE.md and team conventions in the project-level file.
How long should a CLAUDE.md be?+
Shorter than you think. Claude Code loads the entire file into the context window on every session, so every line is paying rent. Aim for under 200 lines for most projects. Focus on conventions, commands, architecture, and gotchas. Do not duplicate what is already obvious from the code or README.
What should NOT go in CLAUDE.md?+
Avoid things that are already discoverable. Do not list every file in the project, do not paste full dependency lists, and do not describe the code line by line. Do not include secrets or API keys. Do not write aspirational rules you do not enforce — if your tests pass despite violating a 'rule', Claude will eventually notice and stop trusting the file.
Can I have multiple CLAUDE.md files in one repository?+
Yes. In a monorepo, you can put a root CLAUDE.md with org-wide conventions and then subfolder CLAUDE.md files for individual packages or apps. Claude Code reads every file on the path from the current working directory up to the repo root and merges them. Use this to keep instructions close to the code they describe.
What is the difference between CLAUDE.md and a slash command?+
CLAUDE.md is persistent context loaded every session. Slash commands (stored in .claude/commands/) are one-shot prompts you can invoke by name. Use CLAUDE.md for things Claude should always know. Use slash commands for reusable workflows you trigger intentionally, like /commit or /deploy.
How often should I update CLAUDE.md?+
Update it whenever a convention changes, a new command becomes standard, or you catch Claude making the same mistake twice. A stale CLAUDE.md is worse than no CLAUDE.md — it will confidently point Claude at commands that no longer exist or rules that have been abandoned. Treat it like any other living documentation.
CLAUDE.md is step one. Claude Code is what it serves.
A memory file only pays off if you are actually using Claude Code. If you have not set it up yet, the full guide covers install, auth, workflows, and the slash commands that make it worth keeping open all day.