The CLAUDE.md File That Made My Side Project 10× Better

The single biggest upgrade you can make to your Claude Code workflow takes about ten minutes and adds one file to your project. It’s called CLAUDE.md and it’s the difference between Claude as a tool and Claude as a teammate.

What it is

CLAUDE.md is a Markdown file you put in the root of your project. Claude Code reads it automatically every time you start a new session. Think of it as the project’s permanent memory — the stuff Claude needs to know to do good work without you re-explaining it every time.

Without one, every conversation starts from scratch. With one, Claude shows up already understanding your stack, your conventions, your style, and your goals.

The template I use on every project

# Project: [name]

## What this is
One paragraph describing what this project does and who it's for.

## Stack
- Frontend: [e.g., Next.js + Tailwind]
- Backend: [e.g., Supabase]
- Hosting: [e.g., Vercel]
- Payments: [e.g., Stripe]

## Conventions
- Use TypeScript for all new files
- Tailwind utility classes only — no custom CSS files unless explicitly asked
- Server components by default, client components only when needed
- File naming: kebab-case
- Component naming: PascalCase

## Things I care about
- Speed (I will notice if you add a slow dependency)
- Mobile-first (every UI must work on a 375px screen)
- Accessibility (semantic HTML, alt text, keyboard nav)
- No bloat (no Lodash, no Moment, no Bootstrap)

## Things I don't care about
- 100% test coverage. Test the critical path.
- Premature optimization

## How to run
- `npm run dev` — start dev server
- `npm run build` — production build
- `npm run lint` — check for issues

## When in doubt
Ask me a clarifying question before generating a lot of code.

Copy that. Paste it into a new CLAUDE.md file in your project root. Adjust to taste.

Why it works

Three reasons:

1. Consistency. Without conventions in CLAUDE.md, Claude makes a different choice every session. With them, your codebase actually feels like one project instead of a Frankenstein.
2. Less back and forth. Instead of typing “use TypeScript, use Tailwind, mobile-first” in every prompt, Claude already knows.
3. Better questions. The “Ask me a clarifying question” line at the bottom is the single most valuable thing in the whole file. It turns Claude from a coder into a collaborator.

Things I learned the hard way

A few rules I’ve added over time after watching Claude make the same mistakes more than once:

• Be specific about what you don’t want. “Don’t add Lodash” is more useful than “keep dependencies minimal.”
• Tell Claude how to test things. If your project has a non-obvious test command, write it down. Otherwise Claude will try to be helpful and run the wrong thing.
• Update it as you go. Every time you find yourself correcting Claude on something twice, add it to CLAUDE.md.
• Don’t over-stuff it. A 200-line CLAUDE.md is worse than a 30-line one. If it’s too long, Claude can’t hold all of it in active context.

The advanced move: per-folder CLAUDE.md files

Once you’re comfortable with the basics, you can add CLAUDE.md files inside subfolders for context that’s only relevant in that part of the project. For example, your app/api/ folder might have its own CLAUDE.md with conventions about API responses and error handling.

Claude will read both files when working in that folder. The folder-level one wins for any conflicts.

Try it on your next project

Honestly, the easiest way to feel the difference is to just do it. Pick a project you’re working on. Spend ten minutes writing the CLAUDE.md. Run your next prompt. Notice the difference.

You’ll never go back.