DEV Community

Sangmin Lee
Sangmin Lee

Posted on • Originally published at claudeguide.io

How to Write Effective CLAUDE.md Files (With 12 Real Examples)

Originally published at claudeguide.io/claude-md-effective-patterns

How to Write Effective CLAUDE.md Files (With 12 Real Examples)

A CLAUDE.md is the single document Claude Code reads first in every session. Get it right and the agent stops asking questions you already have answers to. Get it wrong and you pay tokens every turn for no behavioral change. This post is the working rubric I use, with twelve examples from real repositories. For more on Claude Code in general, see the Claude Code Complete Guide in 2026.

TL;DR — What a good CLAUDE.md does

  1. Answers five boring questions before the agent asks: stack, where code lives, how to run tests, how to deploy, what not to touch.
  2. Declares the invariants that make this codebase different from the average of its stack.
  3. Stays under ~200 lines. Every line you add is tokens on every request in this project.
  4. Avoids aspiration. "We should someday…" is comment rot. If it's not true right now, it does not belong.
  5. Points at authoritative files, not restates them. A one-line pointer to docs/architecture.md beats a ten-line summary that drifts.

The five questions every CLAUDE.md must answer

I have audited over 60 CLAUDE.md files in open source and internal repos. The ones that produced measurable productivity gains all answered these five. The ones that did not were indistinguishable from no file at all.

1. What is this project, in one paragraph?

Not a marketing paragraph. A technical paragraph an engineer would write on the inside cover of a physical notebook.

## What this is
Payment reconciliation service. Reads nightly bank statements from S3,
matches against Stripe events, emits a reconciliation report and a queue
of exceptions. Runs once per day at 04:00 UTC. No user-facing UI.
Enter fullscreen mode Exit fullscreen mode

The agent now knows it is not allowed to suggest adding a frontend, and that anything touching the schedule is high-stakes.

2. What is the stack?

Exact versions. Not "we use Node." Not "recent TypeScript."

## Stack
- Node 22.11 LTS, TypeScript 5.7 strict
- Postgres 16 via Drizzle ORM
- Fastify 5.2
- Vitest 2.1 for tests
- Deployed on Fly.io (3 regions: iad, fra, nrt)
Enter fullscreen mode Exit fullscreen mode

Versions matter because Claude's training cutoff may be earlier than your actual dependencies, and idiomatic code differs meaningfully across major versions.

3. Where does code live, and why?

The file tree alone is not enough. You want a one-liner per important directory that tells Claude what belongs there.

## Layout
- src/routes/ — HTTP handlers; thin, 1 file per resource
- src/services/ — business logic; no HTTP, no SQL
- src/repos/ — SQL only; no business logic
- src/jobs/ — scheduled tasks; independent of HTTP
- tests/ — mirrors src/; integration tests only, unit tests colocated
Enter fullscreen mode Exit fullscreen mode

Now when you ask for "a new endpoint that charges a customer," the agent places the HTTP wrapper in routes, the business logic in services, and the SQL in repos — without being told per-file.

4. How do I run things?

Two command lists: the ones you use every day, and the ones that run in CI. The agent will pick the right level for the task.

## Commands
Dev:
  pnpm dev              # Fastify on :3000
  pnpm test             # Vitest watch mode
  pnpm test:unit        # unit only
  pnpm db:push          # Drizzle migration to dev DB

CI:
  pnpm build
  pnpm test:ci          # single-run, JUnit output
  pnpm lint
  pnpm typecheck
Enter fullscreen mode Exit fullscreen mode

5. What is off-limits?

This is the section most people skip. It is the highest-leverage section in the file.

## Don't
- Do not run `pnpm db:push` against anything other than `localhost:5432`.
- Do not add new npm dependencies without proposing first; the team has a 
  boring-tech policy and a dependency budget.
- Do not commit migrations that drop or rename columns; we use 
  expand-then-contract migrations only.
- Do not touch `src/billing/` without a design doc in `docs/rfcs/`.
Enter fullscreen mode Exit fullscreen mode

Every one of these rules was learned the hard way. Writing them into CLAUDE.md prevents the agent from independently rediscovering them.

What does NOT belong in CLAUDE.md

These are all tempting and all wrong.

  • Onboarding prose for humans. Your README serves humans. CLAUDE.md serves the agent. The audience is different; the density should be different.
  • Aspirational policies. "We aim to have 90% test coverage" — the agent cannot verify this and will now add irrelevant tests trying to satisfy the aspiration. State the rule you actually enforce in CI, or omit it.
  • A full glossary. If you need glossary terms, link to docs/glossary.md. Inlining drifts.
  • The whole architecture. Link; don't embed.
  • Credentials or anything resembling them. CLAUDE.md is committed to your repo. Treat it like code.

Twelve real examples, annotated

Example 1 — A small Next.js SaaS 

# CLAUDE.md — 03-saas-cost-tracker

## What
Claude API cost tracker for solo builders. Reads Anthropic Admin API usage,
displays dashboards, sets budget alerts. Next.js 15 App Router, Drizzle + Neon,
Polar for billing.

## Run
- `pnpm dev` (Next.js on :3000)
- `pnpm db:studio` (Drizzle Studio)
- `pnpm test` (Vitest)

## Deploy
Vercel (main branch auto-deploys). Preview deploys per PR.

## Invariants
- `app/` is client-ish; `lib/` is server-only. Never import `lib/db` from `app/`.
- Anthropic pricing table lives in `lib/pricing/claude.ts` — one canonical source.
- `.env.local` for dev, Vercel env for prod.

## Don't
- Do not write to DB in client components.
- Do not add routes under `/admin/` without checking `lib/auth/adminGuard.ts`.
Enter fullscreen mode Exit fullscreen mode

Annotation: twenty-five lines, answers all five questions, enforces the "don't import lib/db from app/" invariant that previously caused one production deploy failure per month.

Example 2 — A Python CLI tool 


markdown
# CLAUDE.md — ingest

## What
Ingests legacy XML exports into the current schema. One-off migration tool; 
runs maybe 10 times total in the project's lifetime.

## Stack
Python 3.12, click, pydantic 2, uv-managed env.

## Run
`uv run python -m ingest <file

40 slash command templates. Token-optimized variants. JSONL file for direct import. Tested in production sessions.

[→ Get Claude Code Power Prompts 300 — $29](https://shoutfirst.gumroad.com/l/agfda?utm_source=claudeguide&utm_medium=article&utm_campaign=claude-md-effective-patterns)

*30-day money-back guarantee. Instant download.*
Enter fullscreen mode Exit fullscreen mode

Top comments (0)