This is the deep version of the CLAUDE.md template. You can find a stripped-down free version in the Prompt Library. This article walks through why each section exists and which specific failure it prevents.
Section 1: Project overview
This is the only section that's purely informational. One paragraph: what this project is, who uses it, where it deploys.
Why it matters: Without this, Claude defaults to generic best practices. With it, Claude gives you advice that fits your deployment target. "We deploy on Railway with auto-deploy from main" changes how it suggests rollback strategies. "This is a B2B SaaS for dental clinics" changes the user-facing language it generates.
Section 2: Important rules
The single most load-bearing section. These are non-negotiables. They go at the top because Claude reads top-down and takes the first instructions most seriously.
Rule 1: Task completion is binary and explicit
A task is not complete until it's pushed to GitHub. Always run git add, git commit, and git push before declaring any task complete.
Without this rule, Claude will routinely tell you "the change is complete" when the file is edited but not committed. With this rule, "complete" means deployed.
Rule 2: No emojis
Do not use emojis anywhere in the codebase. Use Font Awesome or SVG icons instead.
This isn't aesthetic preference. AI-generated code often signals itself with emoji-laden comments and UI. Banning emojis removes the most obvious tell that a human didn't write this. If you ever ship to enterprise clients, this matters.
Rule 3: Read before write
Before changing any file, read it fully. Before creating a new file, search for an existing file with overlapping responsibility.
The single biggest cause of bad AI-generated diffs: Claude edits files it didn't read. This rule, in writing, at the top, is what prevents that 80% of the time.
Rule 4: Verify before done
Before claiming a task is complete: run typecheck, run tests, paste the output. For UI changes, open the page in dev. For API changes, hit the endpoint with curl.
Without this rule, "done" means "I think it works." With this rule, "done" means "here is the evidence that it works." Cuts down on false-positive completions enormously.
Rule 5: No defensive code without cause
This is subtle but huge. Without it, Claude wraps every operation in try/catch, adds default values for impossible cases, and validates internal data. That code is worse than no code — it hides bugs and adds noise.
The rule:
- No try/catch unless we have a specific error to handle.
- No fallback values for cases that cannot happen.
- No validation for internal data we already control.
- Validate at boundaries (user input, external APIs) only.
Rule 6: Surgical diffs
Touch only files necessary for the task. Do not refactor surrounding code. Do not rename variables. Do not add comments that paraphrase the code.
The rule that makes PRs reviewable. Without it, a 1-line bug fix becomes a 200-line refactor. With it, the bug fix is 1 line and the refactor is a separate PR you can choose to take or skip.
Section 3: Tech stack
List versions, not just frameworks. "Next.js 15" is different from "Next.js 14" — the App Router behavior differs. "React 19" enables features 18 doesn't have. Specificity here saves whole categories of mistakes.
Section 4: Conventions
Six bullets max. The non-obvious ones:
- Naming — kebab-case for files, camelCase for functions, PascalCase for components. Pick one and write it down.
- Imports — absolute or relative? Order? Without this, Claude's first commit will have a different style than the rest of your codebase.
- Test framework — Vitest, Jest, Playwright. Where tests live (next to the code? in a /tests dir?). Otherwise Claude guesses.
Section 5: Commands
The actual commands for your project. Not "npm test" if your test command is "npm run test:unit". Be exact.
Without this, Claude will run `npm test`, get an error, then try `yarn test`, then `pnpm test`. Wastes time. With this, Claude runs the right command first try.
Section 6: What "done" means
The checklist that closes the loop:
- [ ] Code changes complete
- [ ] Types check
- [ ] Tests pass
- [ ] Manually verified
- [ ] Committed with descriptive message
- [ ] Pushed to main (or PR opened)
- [ ] Deployment verified live (if production)
Make Claude check these explicitly. Otherwise the gap between "wrote the code" and "shipped to production" is a coin flip.
Section 7: Common pitfalls
This is the magic section. After 6 months on a codebase, you know which footguns exist. Write them down here. Examples from real 47 Industries CLAUDE.md files:
- "Don't use Prisma
db pushin this repo — we use migrations only. The dev DB has drift; ask before creating a migration." - "This project ships to mobile via React Native bridge. Don't add browser-only APIs without a fallback."
- "Stripe webhook handler must be idempotent — events are retried up to 3 days."
Each line saves a future bug.
The download
The full template (with the optional sections — owners, security, monitoring, performance budgets) is included in the Vibe Coding Playbook. Drop into any project and customize.
