CLAUDE.md starter — the single file that shapes every Claude Code conversation

Why CLAUDE.md matters more than you think

When you start a Claude Code conversation, Claude doesn't know what kind of project you're working on. Without CLAUDE.md, it makes reasonable defaults — but reasonable defaults aren't your defaults. Different React projects use different conventions. Different teams care about different things. CLAUDE.md is how you encode those.

Three weeks into a real project, your CLAUDE.md should reflect every mistake Claude has made that you corrected. The longer the project, the longer the file should be — within reason. The goal isn't completeness; it's high signal per byte.

The starter template

Copy this into a CLAUDE.md at the root of your repo. Customise the bracketed bits. Don't worry about getting it perfect on day one — you'll evolve it.

# CLAUDE.md

## What this project is

[ONE PARAGRAPH: what the website is, who it's for, where it's going to live. Reference brand-brief.md for the full voice and audience details. Example: "A personal landing page for Jane Doe, freelance product strategist based in Singapore. Lives at janedoe.com. Five static pages: home, about, services, contact, blog."]

## Stack

- Next.js 16 (App Router)
- TypeScript 5, strict mode
- Tailwind CSS 4 + a single globals.css for design tokens
- MDX for blog posts (if used)
- Resend for any email handlers (no database)
- Hosted on Vercel — that's the only host we ship to
- Domain at Namecheap, nameservers pointed at Vercel

## Files you should always read first

- brand-brief.md — my voice, audience, positioning
- src/content/* — markdown / MDX content lives here
- src/app/layout.tsx — global metadata and shell
- src/app/globals.css — design tokens and shared component styles

## Coding conventions

- App Router server components by default. Mark with "use client" only when actually needed.
- One globals.css plus Tailwind utility classes. No CSS-in-JS, no styled-components.
- Components in src/components/. Hooks-and-state components are client; everything else stays server.
- Content lives in src/content/, separate from src/components/.
- Imports use the @/ alias (configured in tsconfig.json).
- TypeScript strict. Prefer unknown over any when you genuinely don't know the shape.

## Design system

- Background: [your background hex, e.g. #FAF6F0]
- Ink (foreground): [your ink hex, e.g. #1A1612]
- Accent: [your single accent hex, e.g. #DA7B3A]
- Heading font: [Georgia / Inter / etc.]
- Body font: [Inter / system-ui / etc.]
- Spacing scale: 4 / 8 / 16 / 24 / 32 / 48 / 64 / 80 — stick to these.
- Buttons: 8px radius, 12-14px font, weight 600.
- Use CSS custom properties for the palette so Tailwind arbitrary values reference them.

## Voice (load brand-brief.md for the full version)

- Direct, specific, dry.
- No buzzwords ("leverage", "synergy", "unlock potential", "in today's fast-paced world", "let's dive in").
- No emojis in marketing copy unless I explicitly ask.
- Sentences vary in length. Short sentences are fine. Sometimes one word.

## Things I don't want

- Don't refactor unrelated files when working on one thing.
- Don't add libraries without asking first. We're staying minimal.
- Don't write defensive null checks for values that can't be null in this codebase.
- Don't add JSDoc / inline docstrings unless I ask.
- Don't suggest Cloudflare, Netlify, or other hosts. Vercel only.
- Don't add Tailwind plugins beyond the default — we use arbitrary values for anything custom.
- Don't add tests for a 5-page marketing site. We'll add them if the site grows into a product.

## Deploy + dev

- npm run dev — local at http://localhost:3000
- npm run build — production build
- npm run lint — ESLint
- Pushes to main auto-deploy on Vercel (production).
- Preview deploys fire on every PR / non-main push.

## Notes / decisions

[Use this section as a running log. When you decide something non-obvious, add a one-liner here so Claude reads it on next conversation. Example: "2026-06: switched the alumni-strip component from server-rendered to a client fetch because the aigowhere API endpoint can be slow."]

Annotations — what each section is doing

1. 1.What this project is

   The one-paragraph context. If you only had one minute to brief Claude on what this codebase is, what would you say? That paragraph.

   Reference your brand-brief.md but don't duplicate it. Brand-brief is detail; CLAUDE.md is structure.

2. 2.Stack

   Explicit versions matter. 'Next.js 16' and 'Next.js 14' have different conventions for layouts, fonts, metadata. Claude makes different defaults depending on the version. State it.

   Include negative claims: 'no database' is signal. Claude won't propose adding one for ambient state if you've said you don't have one.

3. 3.Files you should always read first

   Claude Code can read your repo, but it reads in priority order. Telling it what to read first means it has the right context before making suggestions.

   Three to five files is the sweet spot. More than that and Claude burns its context budget on reads rather than thinking.

4. 4.Coding conventions

   Be specific. 'Use modern React' is too vague. 'App Router server components by default; mark with "use client" only when needed' is right.

   These conventions also serve as your own check — when Claude suggests something that violates them, you have a clean basis for pushback.

5. 5.Design system

   Specific colour values let Claude write Tailwind arbitrary values that match your palette exactly. 'Use a calm palette' produces drift.

   Spacing scale matters more than people think. Three weeks in you'll have utility classes everywhere; consistent scale keeps the eye happy.

6. 6.Voice

   Anti-voice (what NOT to say) is high-signal. 'No buzzwords' is fine; listing specific buzzwords is better.

   Don't try to capture full voice here — defer to brand-brief.md. CLAUDE.md is the structural fingerprint; brand-brief is the full sample.

7. 7.Things I don't want

   The most under-appreciated section. Every mistake Claude makes that you correct should produce a new line here.

   Negative rules are stronger than positive ones. 'Don't add libraries without asking' protects you better than 'use a minimal stack'.

   Grow this section deliberately

   Three weeks into a project, this section should have 8-15 lines. Don't write them all on day one — let them accumulate from real corrections.

8. 8.Notes / decisions

   A running log of non-obvious decisions. Six months in, you'll be glad it's here.

   Date-stamp entries. They become a kind of architectural commit log Claude can reference when you ask 'why did we do X this way?'

Where CLAUDE.md fits with other AI-tool conventions

Cursor uses .cursorrules. GitHub Copilot uses .github/copilot-instructions.md. Some projects mirror their CLAUDE.md across all three for consistency.

For pure Claude Code projects, just maintain CLAUDE.md. For multi-tool projects, write the canonical version in CLAUDE.md and symlink (or copy) into the other tools' expected locations. Don't fork — they drift.