CLAUDE.md Starter Template for Web Projects

What CLAUDE.md does

CLAUDE.md is a plain markdown file Claude Code reads at the start of every session, so you stop repeating your stack, commands and rules. Every new session starts with a fresh context window, and this file is how your project knowledge carries over.

• It is context, not a hard lock. Specific, short rules get followed most reliably.
• Commit it to your repo so everyone on the project (and every client hand-off) gets the same rules.
• Claude Code also keeps its own auto memory, but CLAUDE.md is the part you control.

Set it up in 3 steps

1. Open your project folder in Claude Code and type /init. Claude reads your code and writes a starting CLAUDE.md with build commands, test instructions and conventions it finds. If one already exists, /init suggests improvements instead of overwriting it.
2. Open the file and add what Claude can't guess: the stack you insist on, the exact commands, folders and files it must never touch, and how you like changes delivered.
3. Keep it short. The official docs suggest staying under about 200 lines per file. Longer files use more context and get followed less.

The template (copy, then edit the brackets)

Paste this into CLAUDE.md at your project root, replace every [bracket], and delete lines that don't apply.

# [Project name]
[One line: what this site is and who it's for, e.g. "Booking site for a barbershop in Lagos"]

## Stack
- [Next.js 15 (App Router) + TypeScript]
- Styling: [Tailwind only. No new CSS files, no inline styles]
- Hosting: [Vercel]

## Commands
- Dev server: `[npm run dev]`
- Lint: `[npm run lint]` (run after every change)
- Build: `[npm run build]` (must pass before you say a task is done)

## Project layout
- Pages: `[app/]`
- Reusable components: `[components/]` (check here before making a new one)
- Images: `[public/images/]`

## Rules
- Mobile first. Check every layout at 375px wide.
- Use semantic HTML and add alt text to every image.
- Keep changes small. Don't rewrite files you weren't asked to touch.
- Ask before adding a new npm package.

## Never touch
- `.env` and any file with keys or passwords
- `[app/legal/]` (client-approved text)
- `[package-lock.json]` unless you add or remove a package

## Brand
- Colors: [primary #1E3A8A, accent #F97316]
- Fonts: [Inter for body, Space Grotesk for headings]
- Tone of copy: [friendly, short sentences]

## How I want answers
- Show a short plan first for anything bigger than one file.
- After changes, list the files you changed and how to test them.

Where the files live, and tips

• Split a long file with imports: a line like @docs/brand.md pulls that file in. Imports organize the file but still count toward context.
• Already use OpenAI Codex? Claude Code can read an AGENTS.md when there's no CLAUDE.md, so one file can serve both tools.
• Update the file whenever you correct Claude twice about the same thing.
• Don't put secrets in it. It's meant to be committed.

Checked against the official docs (Nov 2026): Claude Code docs: How Claude remembers your project