CLAUDE.md Starter — Anti-Overflow Edition

The 30-second version

Copy the block below into a file named CLAUDE.md at the root of your project. Edit the bracketed sections for your stack. That's it.

# CLAUDE.md — [Your Project Name]

This is the project memory for Claude Code. Re-read at the start of every session
and after any 20 messages.

## What this project is

[One sentence: what does this app do, for whom?]
[One sentence: stack — language, framework, deploy target.]

## Don't load (anti-overflow rules — CRITICAL)

Claude: do NOT load the following into context unless I explicitly ask:
- `node_modules/**`
- `.next/**`, `dist/**`, `build/**`, `.turbo/**`
- `**/*.lock`, `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`
- `public/**` (binary assets)
- `**/__tests__/snapshots/**`
- Any file >2000 lines unless I name it directly
- Old chat transcripts in `.claude/` or `chat-history/`

**Compaction trigger:** if the conversation exceeds 50,000 tokens, summarize the
prior thread into a 200-word "session memory" block and continue from there.

**Re-read rule:** every 20 user messages, re-read THIS file (CLAUDE.md) before
responding. If you notice context drift, say so explicitly and ask if I want to
compact.

## Stack conventions

- **Language:** [TypeScript / Python / Go / etc.]
- **Framework:** [Next.js 16 / FastAPI / etc.]
- **Style:** [Prettier defaults / Black / gofmt]
- **Tests:** [Vitest / pytest / etc.] — write the test first when possible.
- **Database:** [Postgres / Supabase / SQLite]
- **Deploy:** [Vercel / Render / Fly / etc.]

## Naming + structure

- Files: kebab-case for components, snake_case for Python modules.
- Functions: small, composable, testable. Avoid classes unless they reduce mocking.
- One concept per file. If a file >300 lines, propose a split.
- Comments: only for non-obvious caveats. The code should read like prose.

## What I want Claude to do automatically

- Run `[your test command]` before declaring any change "done."
- Run `[your formatter command]` on edited files.
- If you make a change that affects routes, env vars, or DB schema, flag it
  explicitly so I can review.
- If you're about to delete more than 20 lines, pause and confirm.

## What I want Claude to NEVER do

- Commit changes without me asking.
- Push to remote.
- Modify `.env*` files unless I explicitly ask.
- Add a new dependency without a one-sentence justification.
- Use `--force` on any git operation.

## My commands (Q-shortcuts)

When I type any of these, do the listed thing:

- **qnew** — re-read this file, summarize what you understood, ready for a task.
- **qplan** — propose a plan for the current task, list files you'll touch, no code yet.
- **qcode** — implement the plan, run tests, run formatter, report results.
- **qcheck** — review your last change as a skeptical senior engineer; flag what's
  fragile, missing tests, or over-complicated.
- **qgit** — stage, commit (conventional commits format), do NOT push.

## Open questions / known fragility

[List anything ongoing: a known bug, a dependency upgrade in progress, a tech
debt item you're aware of. Update this section as state changes.]

Why this works (the actual learning)

1. The "Don't load" section is the anti-overflow lever.

Claude's context window is finite. If you don't tell it what to ignore, it loads your entire repo (yes, node_modules and all) at the start of every session. Sessions that include node_modules die at the third message. Listing files to skip is more important than telling Claude what your project does.

2. The compaction trigger prevents drift, not loss.

"Just compact at 50k tokens" is wrong — you lose nuance. Instead: summarize the prior thread into a 200-word memory block, then keep going. Claude maintains project-level state but sheds conversation-level noise. I caught this pattern in 3 of my own SaaS builds where Claude started hallucinating after long sessions.

3. The re-read rule is the loop-back insurance.

Without it, Claude drifts. With it, Claude reminds itself of your stack + conventions every 20 messages, which is roughly the half-life of context relevance in my experience.

4. The Q-shortcuts compound.

Once you train yourself to type qnew / qplan / qcode / qcheck / qgit, you stop typing 200-word prompts. Same outcome, 10× less keyboard time. I borrowed this pattern from Sabrina Ramonov's published rules — it works.

What I'd add for production projects

If your project is past v1 + has paying users, add these sections to your CLAUDE.md:

## Customer data — DO NOT TOUCH

Claude: never write code that reads/modifies these tables without me explicitly
asking AND reviewing the change:

- `users`
- `orders`
- `payments`
- Any table containing PII or PCI data

## On-call escalation

If a deploy fails or production breaks, do NOT attempt to fix without my approval.
Roll back to the previous version (`[your rollback command]`) and notify me.

## Compliance — what we are subject to

[List: GDPR / HIPAA / SOC 2 / PCI / etc.]
Claude: any change touching auth, logging, or data export requires a compliance
review note in the commit message.

Common mistakes I see

1. Adding "be helpful and thorough" to the top of CLAUDE.md. Doesn't do anything. Claude is already trying to be helpful and thorough. Save the tokens.
2. Not listing the files to skip. This is the single biggest failure mode.
3. Putting code samples in CLAUDE.md. Claude doesn't need examples — it needs constraints. Tell it what NOT to do.
4. Updating CLAUDE.md after a bug, then never re-reading it. Stale CLAUDE.md is worse than no CLAUDE.md. The re-read rule fixes this.

Going deeper

• Watch the channel for the "I rebuilt a broken Lovable + Supabase SaaS in 6 hours" build (Post 7). Most of the rebuild was actually CLAUDE.md tuning.
• Drop questions in DMs at @cory_salisbury on TikTok.