Giving the AI a memory

You've explained your project to the AI four times this week. You've corrected the same mistake six times. That's not the tool being stupid — it's you keeping your project's knowledge in your head instead of in a file.

The fix is small and enormously effective: put the permanent facts about your project into files the tool reads automatically, every session, forever.

CLAUDE.md — your project's standing brief

Claude Code looks for a file called CLAUDE.md in your project root and reads it at the start of every session. Cursor does the same thing with files under .cursor/rules/. Same idea, different filename.

Get one started by running /init in Claude Code — it'll read your project and write a first draft. Then edit it, because the useful parts are the ones only you know.

# Paws — booking tool for dog walkers

## What this is
A booking tool for independent dog walkers in the UK. Users are
non-technical sole traders on their phones between appointments.
Pre-launch; about 10 beta users.

## Stack
- Next.js (App Router) + TypeScript + Tailwind
- Supabase for database and auth
- Deployed on Vercel
- Emails via Resend

## How this project is organised
- src/app        pages — one folder per route
- src/components shared UI
- src/lib        database access and helpers
- Supabase types are generated; don't edit src/lib/database.types.ts

## Conventions
- Components use the pattern in src/components/Button.tsx
- Dates are always stored UTC, displayed in the user's timezone
- Money is stored in cents as integers, never floats
- All database access goes through src/lib/db.ts — never query
  Supabase directly from a component

## Rules
- Never commit secrets. They live in .env.local.
- Every table has row level security enabled. If you create a
  table, create its policies in the same migration.
- Don't add dependencies without telling me what and why first.
- Mobile is the primary target. Check 375px before saying done.
- I'm non-technical: explain what you changed and what might break.

## Things that have bitten us before
- Supabase auth session must be refreshed in middleware or users
  get logged out randomly on mobile Safari.
- The booking calendar breaks if a walk crosses midnight.

What belongs in it — and what doesn't

Specs: context for one feature

CLAUDE.md is permanent. A spec is context for a single piece of work, and it's the thing that makes bigger features achievable.

Keep a docs/ folder. Before anything non-trivial, write (or have the AI write from an interview) a short document: what the feature does, what the screens are, the rules, the edge cases, what "done" means. Then the prompt becomes: "Implement the booking flow described in docs/booking.md. Start with step 1 only."

Three things this buys you:

• You catch your own vagueness while writing it, which is cheap. Discovering it mid-build is not.
• If the session dies or you come back in a week, the context is on disk rather than in a lost conversation.
• You can point at it and say "this bit is wrong" instead of re-explaining everything.

Screenshots and references

Given your design background, use images relentlessly:

• Current state + target. "Here's what it looks like, here's the reference, close the gap."
• Bug evidence. A screenshot of the broken layout plus the browser console error beats three paragraphs of description.
• Design references. "Match this card's proportions and spacing rhythm, using our colours."

Managing the desk during a session

Read this entire project, then interview me to write a really good CLAUDE.md.

First, tell me everything you can work out on your own: the stack, the folder structure, the conventions you can see in the existing code, how to run it, how it's deployed.

Then ask me — one at a time — for everything you can't work out:
- Who the users are and what constraints that puts on the product
- Decisions that look arbitrary in the code but were deliberate
- Things that have broken before that you'd have no way of knowing
- What I never want changed without being asked first
- What "done" means to me for a typical feature

Then write the file. Keep it under two pages, make every line actionable, and put anything speculative in a separate "open questions" section rather than stating it as fact.

Review the CLAUDE.md in this project critically, as if you were about to have to work from it.

1. Which instructions are vague enough that you could follow them and still do the wrong thing? Rewrite those to be unambiguous.
2. Which lines just restate what's obvious from the code, and could be deleted to save context?
3. What's missing that you'd have had to guess at during your last few tasks?
4. Are any of the rules contradicted by what the code actually does? (That's the worst kind — it makes the whole file untrustworthy.)
5. Is anything in here a secret or otherwise unsafe to have in a file that might become public?

Give me a tightened version, and tell me what you cut and why.

I'm stopping work for today. Write me a handover note I can paste at the start of tomorrow's session, and save it to docs/handover.md.

Include:
- What we were trying to achieve overall
- What's actually finished and verified working (be honest — not what we attempted)
- What's half-done, and exactly where it stopped
- Decisions we made and the reasons, especially ones that would look odd without the reasoning
- Anything currently broken that I should know about before I touch anything
- The exact next step, specific enough that I could start with it cold
- Any files that are in a messy intermediate state

Be accurate rather than optimistic. If something's a mess, say it's a mess.