← forthedev.site · Free Chapter · 8 min read

CLAUDE.md, the Honest Way

Chapter 2 of Claude Code Mastery — The Solo-Dev Workflow. Free to read. The remaining 9 chapters live behind €39 / €49 bundle.

The single biggest leverage point

If you read one chapter of this course and ignore the rest, read this one. CLAUDE.md, done well, is worth more than every other technique combined. Because it's the file Claude reads every single session, automatically, no prompting needed.

A bad CLAUDE.md is decorative. A good one is the difference between Claude as a confused intern and Claude as a senior dev who already knows your repo.

What belongs in there

Six sections, in this order. Skip any that don't apply.

1. Stack

One paragraph. Languages, frameworks, build tool, DB, deploy target. Like the first paragraph of a README, but tighter. Claude already knows what Next.js is — you're telling it which version, with which adapter, with which DB driver.

2. Dev commands

The 5 commands you actually run. pnpm dev. pnpm test. pnpm test:e2e. pnpm db:push. pnpm typecheck. Not all 30 commands in package.json — the ones you'd want a junior to know on day one.

3. Where to edit

The map. "Routes live in app/<route>/page.tsx. Server logic in server actions co-located. DB schema in prisma/schema.prisma — never edit migrations by hand." Two minutes to write, saves hours per week.

4. Where NOT to edit

The dark corners. Generated files. Vendored code. The legacy module that's getting deleted next month. Be specific. "Anything under src/legacy/ is being phased out — do not extend, only delete."

5. Conventions

The unwritten rules. "All server actions return { ok: true } | { ok: false, error: string }." "We use cn() for class merging, not template literals." "Tests live next to source: Foo.tsx + Foo.test.tsx." These are the rules that, when violated, make you go "who wrote this" — write them down so future-Claude doesn't.

6. Things that bit us

The most important section. Past incidents. Subtle gotchas. "Prisma + edge runtime = silent failure, keep DB calls in node runtime." "Tailwind class merging in attribute strings — won't tree-shake, use cn()." "Stripe webhooks: idempotency keys are mandatory or we double-charge."

This section is the one nobody writes and everyone needs. It's also the one Claude can't infer from reading the code, because the absence of bugs is invisible. You have to tell it.

What does NOT belong in there

A surprising amount.

Out: anything Claude can read from the code

Don't list every file. Don't explain what each function does. Claude can cat. The CLAUDE.md is for things Claude can't discover by reading.

Out: long architecture lectures

If your CLAUDE.md is 800 lines, it's wrong. Long context dilutes attention. The good CLAUDE.md is dense — every line earns its place. Aim for 100–300 lines. Tighter is better.

Out: roadmap, future plans, TODOs

These rot fast and confuse Claude into "helpfully" implementing them. Keep roadmap in a separate file. CLAUDE.md is current state and conventions, nothing else.

Out: marketing copy, project history, founder story

If a section doesn't change Claude's behavior in this session, it doesn't belong.

Out: secrets, API keys, anything you wouldn't paste in a tweet

CLAUDE.md is committed to your repo. Treat it like any source file.

Two-file structure

For solo devs, the optimal setup is two CLAUDE.md files:

• ./CLAUDE.md — repo-specific. Stack, conventions, this-codebase wisdom.
• ~/.claude/CLAUDE.md — your global preferences. Output style, commit message format, your "no sycophancy" rules, your default test framework opinions.

The global one applies across every project. It's where you put your taste — terse responses, no emojis, "delete > add" bias, etc. Mine is included in the bonus templates of the bundle.

If you find yourself writing the same instruction in every repo's CLAUDE.md, it belongs in the global one instead.

The capture loop

The hardest part of CLAUDE.md isn't writing it once. It's keeping it true.

Three habits that solve this:

1. The "Why?" Capture

Whenever you correct Claude — "no, do it this other way" — pause and ask: would CLAUDE.md have prevented this? If yes, add a line to CLAUDE.md right then. Takes 30 seconds. Saves 30 minutes the next time it would have come up.

2. The Quarterly Audit

Every 90 days, read your CLAUDE.md cold. Anything that's no longer true, delete. Anything that surprises you ("did we really still do that?"), verify. CLAUDE.md rots; treat it like dependencies.

3. The Tribal-Knowledge Quiz

Ask Claude: "What 5 things about this codebase are you most likely to get wrong because they aren't documented anywhere?" Read its answers critically. Each correct guess is a hole in your CLAUDE.md. Patch.

A real example

Here's the CLAUDE.md from one of my own indie projects — a Next.js app, redacted:

# Stack
Next.js 15 (app router), TS strict, Tailwind, Prisma + Postgres on Neon, deploy via Vercel.
Auth: lucia (yes still). Background jobs: Trigger.dev v3.

# Dev
pnpm dev (port 3000) | pnpm test (vitest) | pnpm test:e2e (playwright)
pnpm db:push (dev only) | pnpm db:migrate (commits a migration)
pnpm trigger:dev (run jobs locally — needs separate terminal)

# Edit
- Routes: app/<route>/page.tsx (RSC by default, mark 'use client' only if needed)
- Server logic: server actions next to the route OR app/api/ for webhooks only
- DB: prisma/schema.prisma — never edit prisma/migrations/<timestamp>/sql by hand
- Components: components/ (shadcn-style)
- Background jobs: jobs/ (one file per job, registered in jobs/index.ts)

# Don't edit
- prisma/migrations/* (generated)
- .next/, public/_static/ (build output)
- legacy/* (Sept 2025, getting deleted)

# Conventions
- Server actions return { ok: true, data } | { ok: false, error: string }. NEVER throw across boundary.
- Zod-validate all external input at top of server actions.
- No barrel imports (no index.ts re-exports). Import the file directly.
- Tests next to source: Foo.tsx + Foo.test.tsx.
- Tailwind: use cn() from lib/utils.ts. Don't string-concat classes.

# Bit us
- Prisma + edge runtime = breaks silently. Force node runtime on routes touching DB.
- Trigger.dev v3 + Vercel: env vars must be in BOTH places.
- Stripe webhooks: ALWAYS check idempotency_key, we double-charged in March.
- shadcn `Button` ref-forwarding broken in our version, use forwardRef wrapper in components/ui-fixed/.

Total: 35 lines. That's the whole file. Every line earns its keep.

Workflow Drill

Time: 15 minutes (the only long drill in the course — it's worth it).

1. Open your most-active project.
2. Use the template above as a skeleton. Fill it in.
3. Skip anything you'd have to invent. If you don't know if you have a convention, you don't have one.
4. Critical: add at least 2 entries to "Bit us." Think of the last 2 things that surprised you, even if minor. Future-Claude will thank you.
5. Commit it: chore: add CLAUDE.md.

You're now doing the single highest-leverage thing in this course.

---