This One File Made Claude Code 10x Smarter — CLAUDE.md Tutorial (2026)

Same prompt, same project, same Claude Code. The only difference is one file.

Without the file, Claude makes its own choices. With the file, Claude follows yours.

That file is CLAUDE.md — a Markdown file you drop in the root of any project. Claude Code auto-loads it the moment you start a session in that folder. It's not a setting you toggle, it's not a command you run — the file is just there, and Claude reads it on every turn.

Think of it as a permanent system prompt for that project. Whatever you put inside, Claude treats as ground truth — your stack, your conventions, your forbidden patterns, your test commands. No more re-explaining your project every time you start a new conversation.

In this tutorial, I'll walk through the five rules I keep in every single CLAUDE.md I write. Copy the template at the bottom, fill in your stack, drop it in your project root.

What Is CLAUDE.md?

CLAUDE.md is a plain Markdown file at the root of your repo. Claude Code auto-detects it and includes its contents in every response within that session. Source: Anthropic Claude Code Docs — Memory.

That auto-loading is the whole point. You write your rules once, save the file, and from then on every conversation in that project starts with Claude already knowing them.

Rule 1: What This Project Actually Is

Tell Claude what the project is in three lines.

# Project: <name>
- What it does: One sentence.
- Stack: Next.js 15, TypeScript, Tailwind, Prisma, Postgres
- Deployed on: Vercel

Without this, Claude guesses your stack from the file tree — and it guesses wrong about half the time. Three lines, written once, saves you hours of corrections.

Rule 2: Conventions You Actually Use

List your real conventions. Not the conventions in the framework's docs — yours. The ones you'd say no to in a code review.

# Conventions
- Use server components by default. Client components only when needed.
- All API routes return { data, error } never throw.
- Use Tailwind utility classes. No inline styles. No CSS modules.
- File names: kebab-case. Components: PascalCase.

Claude defaults to whatever's most popular on GitHub. If your team writes things differently, you have to spell it out — or you'll spend half your day correcting.

Rule 3: What NOT to Do (The Never List)

This is the most underrated section. Tell Claude what's off-limits.

# Never do
- Never modify schema.prisma without my permission.
- Never install new dependencies without confirming.
- Never use `any` in TypeScript — use `unknown` and narrow.
- Never write tests with `any` typed mocks.

The agent respects this list because it sits in context for every single response. Without it, Claude will helpfully install three packages you didn't want and refactor a file you told it to leave alone.

Rule 4: Commands That Prove Things Work

Give Claude the verification commands — test, type check, lint. And the trick: the last line tells Claude what to run before claiming a task is done.

# Commands
- Install: npm install
- Dev: npm run dev (port 3000)
- Test: npm test
- Type check: npx tsc --noEmit
- Lint: npm run lint
- Before claiming a task is done: run `npm test && npx tsc --noEmit`

Without that last line, Claude says "done" the moment it writes the code, never runs the tests, and you find out at deploy time. With it, Claude runs the verification first. This one line catches roughly half of all bad outputs.

Rule 5: Project Quirks That Look Like Bugs

Every project has weird stuff that looks broken but isn't. Document those quirks — otherwise Claude will see them and "fix" them.

# Project quirks (these are NOT bugs)
- API routes intentionally return 200 with { error } instead of HTTP error codes — frontend expects this.
- The `useAuth` hook returns null during hydration — that's expected, don't add a loading state.
- The `legacy/` folder is read-only. Do not refactor anything in it.

This section has saved me from agents helpfully refactoring legacy code that was load-bearing.

Before / After — Same Prompt, Different Result

The whole video opens with a side-by-side: same prompt sent to Claude Code with and without CLAUDE.md.

Prompt:

Add a "Save draft" button to the contact form that triggers the existing toast notification.

Without CLAUDE.md — Claude installs a new toast library, builds a custom toast component, picks its own placement for the button, and uses inline styles.
With CLAUDE.md — Claude finds the existing useNotify hook, calls useNotify().success(...), uses Tailwind classes, no new dependencies, runs npx tsc --noEmit before saying "done."

Same task. Different result. One file, written once, used forever.

The Full Template — Copy + Fill In Your Stack

# Project: <name>
- What it does: One sentence.
- Stack: Next.js 15, TypeScript, Tailwind, Prisma, Postgres
- Deployed on: Vercel

# Conventions
- Use server components by default. Client components only when needed.
- All API routes return { data, error } never throw.
- Use Tailwind utility classes. No inline styles. No CSS modules.
- File names: kebab-case. Components: PascalCase.

# Never do
- Never modify schema.prisma without my permission.
- Never install new dependencies without confirming.
- Never use `any` in TypeScript — use `unknown` and narrow.
- Never write tests with `any` typed mocks.

# Commands
- Install: npm install
- Dev: npm run dev (port 3000)
- Test: npm test
- Type check: npx tsc --noEmit
- Lint: npm run lint
- Before claiming a task is done: run `npm test && npx tsc --noEmit`

# Project quirks (these are NOT bugs)
- API routes intentionally return 200 with { error } instead of HTTP error codes — frontend expects this.
- The `useAuth` hook returns null during hydration — that's expected, don't add a loading state.
- The `legacy/` folder is read-only. Do not refactor anything in it.

That's the entire file. Five sections, maybe 30 lines once you fill it in. Save it as CLAUDE.md at the root of your project, restart Claude Code, and watch it stop guessing.

Resources

📖 Anthropic Claude Code Memory Docs: docs.claude.com/en/docs/claude-code/memory
📺 Full video tutorial: youtu.be/D5UUTFOKdSI

Final Word

CLAUDE.md is the highest leverage thirty minutes you'll spend on any Claude Code project. Once it exists, every future session starts with the agent already understanding your project. No more re-explaining. No more silent convention drift. No more "done" without running the tests.

Drop the template in your project root. Watch the difference on your next prompt.

Subscribe to AyyazTech on YouTube — I cover every AI coding tool worth your time so you don't waste yours.