CLAUDE.md for UK indie hackers: the project file that compounds week over week

Every UK indie hacker who tries Claude Code reaches for CLAUDE.md within a week. The Anthropic docs tell you it exists. Generic dev blogs tell you it's "where you put project rules". Neither tells you the thing that actually matters: CLAUDE.md is the file that turns Claude Code from helpful assistant into a builder that compounds. The bad version of CLAUDE.md slows you down. The good version saves you 30 minutes per session, every session, forever.

This post is the UK indie hacker primer. The 7 sections that earn their keep. The 3 anti-patterns that look helpful but rot the file. A real copy-paste template. And the question that decides whether something belongs in CLAUDE.md or not.

What CLAUDE.md actually is

CLAUDE.md is a markdown file you check into the root of your repo. Claude Code reads it at the start of every session and treats its contents as instructions that override its defaults. Anthropic calls this "project memory". A more useful framing for indie hackers: CLAUDE.md is the brief you would otherwise have to type at the start of every session.

The file compounds because every time you spot a recurring mistake or a fact the agent needs, you add a line, commit, and never have to mention it again. After two weeks of disciplined upkeep, a good CLAUDE.md saves roughly 30 minutes a session — that's three to four hours a week back, just from not re-explaining things.

The 7 sections that earn their keep

The order matters. The agent reads top to bottom; the first few sections shape every decision after.

1. Project shape (3-5 lines)

What this project is, who it's for, what stage it's at. This is what stops the agent over-engineering a weekend prototype or under-engineering production code.

## Project

A weekly UK rail fare summary email at GBP 5/month. Pre-revenue, 
3 paying friends. Pre-prod. Optimise for "shipped this weekend" 
over "scalable to 10k users". Single dev (me), no team.

2. Stack (the actual versions)

The agent will pick reasonable defaults if you don't tell it. The defaults are usually three months out of date. Write the exact versions.

## Stack

- Next.js 16 (App Router only, no Pages Router)
- Tailwind CSS 4
- Supabase EU-West (auth, postgres, RLS)
- Stripe (GBP only, UK billing)
- Resend for transactional email
- Vercel deploy (EU region)
- TypeScript strict mode

3. UK / regional rules

The single biggest source of "the AI keeps doing the wrong thing" for UK indie hackers. Make these explicit, near the top.

## UK conventions

- GBP throughout. Never use $ or USD in code or copy.
- EN-UK spelling (colour, organise, behaviour, optimise).
- Dates: ISO format in code (2026-05-12), DD/MM/YYYY in UI.
- VAT-inclusive prices for B2C. VAT-exclusive for B2B.
- Cookie banner required for analytics (UK GDPR + PECR).

4. Conventions and gotchas (your repo's "wait, watch out")

The list of things future-you would forget. Append-only; this grows fastest in the first month.

## Gotchas

- Always import db from `@/lib/supabase/server` in server 
  components. The client one will throw on the server.
- Stripe webhook secret comes from `STRIPE_WEBHOOK_SECRET`, 
  NOT `STRIPE_WEBHOOK_SIGNING_SECRET` (that one was the old name).
- Don't auto-format files in `/scripts/migrations/` - 
  prettier breaks the SQL parser.
- Resend's free tier rate-limits at 100 emails/day. Batch 
  jobs over 100 must use the Pro tier (GBP 18/mo).

5. The "do this / don't do this" pairs

This is the file's most expensive real estate, so be tight. Each rule is one line, in the form "do X, not Y". The agent reads these like a checklist.

## Rules

- Server components by default. Client components only when 
  using state or browser APIs.
- Database access via Supabase RLS, never service role from 
  client code.
- New routes get `metadata` for SEO. No exceptions.
- Test files live next to the source file (`x.ts` + `x.test.ts`), 
  not in a separate `tests/` directory.
- Commit messages: conventional (`feat:`, `fix:`, `chore:`).
- One PR per feature. Don't bundle.

6. The "default behaviours" block (mirror Pablo's pattern)

Borrowed from the Pablo project's CLAUDE.md (the AI-PM-shaped one): a numbered list of behavioural defaults. This is the file's biggest force multiplier. The agent treats these as policy, not preference.

## Default behaviours

1. Read the file before editing it. No blind writes.
2. Run `pnpm test` after touching `/app/**/*` or `/lib/**/*`. 
   Don't claim a fix without a green test.
3. Smoke-test after deploys. Curl the live URL, check for 200, 
   verify the change rendered.
4. When in doubt, ask. Better to clarify than to ship the 
   wrong thing.
5. Suggest commits but never push without explicit approval.

7. Sensitive files

Short, explicit, near the bottom. The agent will respect this if you write it clearly.

Sensitive files

Never display, log, or commit:

• .env.local
• supabase/seed.sql
• prompts/customer-data-export.ts

Acknowledge their existence if asked. Never reveal contents.

## The 3 anti-patterns to avoid

### Anti-pattern 1: writing a tutorial

CLAUDE.md is **not** a how-to guide. It is a list of constraints and facts. If you find yourself writing "first you should...", delete it. The agent does not need a tutorial; it needs the rules of the road.

### Anti-pattern 2: aspirational rules

Don't write "all code should have 100% test coverage" if your repo currently sits at 40%. The agent will either ignore the rule (bad) or refuse to write code without tests (worse). Write the rules your repo actually enforces today, not the rules you wish it enforced.

### Anti-pattern 3: the wall of text

A CLAUDE.md that is 800 lines long is a CLAUDE.md the agent skims. Aim for 80-200 lines. If a section is growing past 30 lines, that's a sign the content belongs in a dedicated `docs/<topic>.md` file that CLAUDE.md links to.

## How CLAUDE.md evolves

| Stage | Lines | Sections | What changes |
|---|---|---|---|
| Weekend 1 | 30-50 | 3-4 (project, stack, gotchas, sensitive files) | Set up the bones |
| Week 2 | 50-100 | 5-6 (add UK conventions, default behaviours) | Add things you found yourself re-typing |
| Month 1 | 100-200 | All 7 | Mature. The "rules" section has 10-15 entries |
| Month 3 | 200-300 | All 7 + linked docs | Long-form bits move into `docs/` and get linked |
| Year 1 | 300-400, stable | All 7 + linked docs + agent rosters | The agent does most of its work without you opening the file |

The good signal that you've got it right: you can take a two-week break, come back, and Claude Code will write code that fits the project without you re-orienting it.

## The deciding question: does it belong in CLAUDE.md?

When you're not sure whether to add a line, ask: **"Would I tell this to a new contractor on day one?"**

- Yes → it's CLAUDE.md material.
- No, this is week-three knowledge → it's `docs/<topic>.md` material, linked from CLAUDE.md.
- No, this is "how I personally like to code" → it's `.editorconfig` or `.prettierrc` material.
- No, this is one-off → it's the next session's prompt, not the file.

## A real 80-line UK indie hacker template

The shape that works for most UK micro SaaSs in their first month:

```markdown
# Project — Weekly UK Rail Summary

A weekly UK rail fare summary email at GBP 5/month.
Single dev, pre-revenue, optimise for "shipped this weekend".

## Stack

- Next.js 16 (App Router)
- Tailwind CSS 4
- Supabase EU-West
- Stripe (GBP)
- Resend
- Vercel EU

## UK conventions

- GBP, EN-UK spelling, DD/MM/YYYY in UI, ISO in code
- Cookie banner required (UK GDPR + PECR)
- VAT-inclusive B2C prices

## Gotchas

- Use `@/lib/supabase/server` in server components
- Webhook secret = STRIPE_WEBHOOK_SECRET
- Resend free tier 100 emails/day

## Rules

- Server components default
- RLS for all DB access
- Metadata on every new route
- Tests next to source
- Conventional commits

## Default behaviours

1. Read before edit
2. Run tests after touching app/ or lib/
3. Smoke-test after deploy
4. Ask when unsure
5. Suggest commits, don't push without approval

## Sensitive files

Never log or commit:
- .env.local
- supabase/seed.sql

That's it. 80 lines. It will grow. Commit it on Friday evening before you start building.

What about agent rosters?

If you're using subagents (covered in tomorrow's post), the agent-roster section goes near the end of CLAUDE.md. A short table, one line per agent, role and CLAUDE.md path. That's how Pablo (the project this site runs on top of) routes work to its subagents — same pattern works for a solo UK indie hacker dispatching researcher / scaffolder / test-writer agents from inside Claude Code.

Want a data-backed UK business idea every week? Free reports drop every Thursday — keyword volumes, SERP analysis, builder prompts. Browse the latest free report on IdeaStack.

---