How to Write a Build Spec and CLAUDE.md That Claude Follows

This post is for anyone using Claude Code, whether you are on your first project or your fifteenth. Beginners will get templates to copy. People already shipping will probably find a few rules in their CLAUDE.md that are hurting more than helping.

Two documents do most of the work in my projects. The build spec describes one feature: what to build, what not to build and how to prove it works. The CLAUDE.md file describes the project: the commands, conventions and gotchas Claude should know in every session. They solve different problems, and mixing them up is the most common mistake I see.

Spec vs CLAUDE.md: what goes where

• Build spec: one feature, written once, used for one or a few sessions. "Add team invites."
• CLAUDE.md: facts that are true for every session. "Run npm run build to check your work." "Never edit files in supabase/migrations that are already applied."

If an instruction only matters for one feature, it belongs in the spec. If you would type it again next week, it belongs in CLAUDE.md.

Part 1: The build spec

A good spec is self-contained. A fresh Claude session with no memory of your earlier chats should be able to read it and build the right thing. Anthropic's own guidance says the most useful specs name the files and interfaces involved, state what is out of scope, and end with an end-to-end verification step.

Here is the template I use:

# Feature: [name]

## Goal
One or two sentences. Who is this for and what can they do
when it is done?

## User stories
- As a [user], I can [action] so that [result].
- (3 to 6 of these, no more)

## Data
- Tables or columns to add or change, with types.
- Who can read and write each one (this becomes RLS policy).

## Screens and behavior
- Page or component, what it shows, what each button does.
- Empty state, loading state, error state.

## Out of scope
- Things that sound related but are NOT part of this feature.

## Files likely involved
- src/pages/..., supabase/functions/..., etc.

## Done means
- [ ] A step-by-step test a human can run in the browser.
- [ ] The build passes.
- [ ] Specific edge cases checked (list them).

The two sections people skip are the two that matter most. Out of scope stops Claude from "helpfully" building the admin panel you did not ask for. Done means gives Claude a check it can run instead of stopping when the work merely looks finished.

Let Claude interview you first

You do not have to write the spec alone. For bigger features I start with a short description and ask Claude to interview me. This is close to the prompt in the official best practices guide:

I want to build [brief description]. Interview me in detail.

Ask about technical implementation, UI and UX, edge cases,
concerns and tradeoffs. Skip obvious questions and focus on
the hard parts I might not have considered.

Keep interviewing until we have covered everything, then
write a complete spec to SPEC.md using the sections: Goal,
User stories, Data, Screens and behavior, Out of scope,
Files likely involved, Done means.

Then, and this matters, start a fresh session to build it. Type /clear or open a new session and say "Read SPEC.md and propose a plan." The new session has clean context focused on building, not on the back-and-forth of the interview.

Make every requirement checkable

Vague specs produce vague apps. Compare:

• Weak: "Invites should be secure."
• Strong: "An invite link expires after 7 days. A user who is not logged in is sent to sign up, then lands on the team page. Accepting an expired link shows the message 'This invite has expired.'"

If you cannot describe how you would test a requirement, Claude cannot either.

Part 2: The CLAUDE.md file

CLAUDE.md is a plain markdown file in your project folder. Claude Code loads it at the start of every session. You can create a starter version by typing /init, which looks at your codebase and writes down the commands and conventions it finds. Then you trim and add to it.

The key thing to understand: Claude treats CLAUDE.md as context, not as enforced rules. It reads it and tries to follow it, but vague, long or contradictory instructions get followed less reliably. The official memory docs are blunt about this.

The rules I follow

• Keep it under 200 lines. That is Anthropic's own target. Longer files use more context and reduce how well Claude follows them.
• Write instructions you could verify. "Use 2-space indentation" instead of "format code properly." "Run npm test before committing" instead of "test your changes."
• Only include what Claude cannot figure out by reading the code. It already knows React conventions. It does not know that your staging database is the one called dev.
• Group with headings and bullets. Dense paragraphs get skimmed.
• Remove contradictions. If two lines disagree, Claude may pick either one.
• Use emphasis once, not everywhere. If Claude keeps skipping one rule, put IMPORTANT on that line. If ten lines say IMPORTANT, none of them stand out.

A test for every line: "Would removing this cause Claude to make a mistake?" If not, cut it.

A CLAUDE.md for a typical Lovable plus Supabase app

# Project
Subscription app for small gyms. React + Vite front end,
Supabase (Postgres, auth, edge functions), Stripe billing.

# Commands
- npm run dev: local dev server
- npm run build: must pass before you say a task is done
- supabase functions serve: run edge functions locally

# Conventions
- Database changes go in a new file in supabase/migrations.
  Never edit a migration that has already been applied.
- Every new table gets RLS enabled and policies in the same
  migration.
- Server secrets live only in edge function environment
  variables. Never put them in src/ or in VITE_ variables.

# Gotchas
- The Stripe webhook function must verify the signature
  using the raw request body.
- profiles.id equals auth.users.id. Do not add a separate
  user_id column to profiles.

# Workflow
- For changes touching more than two files, propose a plan
  first and wait for approval.
- Commit after each working step with a short message.

That is about 30 lines and covers most of what Claude gets wrong in this kind of project.

Where the file can live

• ./CLAUDE.md in your project: shared with anyone who works on it through git.
• ./CLAUDE.local.md: your personal notes for this project. Add it to .gitignore.
• ~/.claude/CLAUDE.md: your preferences across every project.
• .claude/rules/: topic files that can be scoped to certain paths, so a rule about edge functions only loads when Claude works on edge functions.

If your repo already has an AGENTS.md for other coding tools, current versions of Claude Code can read it when there is no CLAUDE.md, or you can import it from your CLAUDE.md with a line that says @AGENTS.md.

When Claude still ignores a rule

1. Run /context and check that your file is listed under memory files. If it is not loaded, Claude never saw it.
2. Make the rule more specific.
3. Look for a second file that says something different.
4. Run /doctor prompt-audit to have Claude check your instruction files for conflicts and outdated content. Nothing changes until you approve.
5. If the rule must happen every single time, like running a linter after every edit, it should not be an instruction at all. Make it a hook, which is a script Claude Code runs at a fixed point no matter what. You can ask Claude to write one: "Write a hook that runs the linter after every file edit."

Keep both documents alive

Add to CLAUDE.md when Claude makes the same mistake twice or when you catch yourself typing the same correction again. Prune it when rules stop mattering. Treat specs as disposable once the feature ships, but keep them in a docs/ folder so you can see why things were built the way they were.

Where to go next

The recipes on NoCode Outlaws are build specs written in this format, ready to hand to Claude Code or Lovable. If you want me to review your spec before you build, bring it to office hours in a cohort.