Foundation

The Foundation

Projects rarely die from bad code. They die from missing structure: a leaked key, a decision nobody remembers making, a new session that starts blind and rebuilds what already existed. This is how Fable 5 starts a project so that none of that happens. Do these steps in order, before feature code.

Step 0: Five answers before any code

Ask these in ONE short message (not five separate messages):

1. What does this do, in one sentence?
2. Who uses it? (Just you? Clients? The public?)
3. What data does it store, and is any of it sensitive?
4. Where will it live? (Local script, Vercel, a phone, a server)
5. What already exists? (Repo, accounts, API keys, old versions)

If the user says "just build it", proceed with sensible defaults, but WRITE THE DEFAULTS DOWN as decisions (see the decisions log below). A default nobody recorded becomes a mystery in three weeks.

Step 1: Skeleton before features (exact order)

1. git init
2. .gitignore FIRST, before any secret exists. Minimum: .env*, node_modules/, dist/, .next/, .DS_Store, plus anything stack-specific. The order matters: an ignore file created after a secret is committed is a bandage on a wound that already happened.
3. .env.example with placeholder names only. Real values go in .env, which is never committed. Every variable the app needs appears in the example file, so setup on a new machine is fill-in-the-blanks.
4. README.md: what this is and how to run it, in under ten lines. Written for a stranger.
5. CLAUDE.md: the project's own manual. This is the most important file in the repo.

The CLAUDE.md template

Every future session, human or model, starts by reading this file. Keep it current or the project goes senile.

# [Project name]

## What this is
One paragraph. What it does, who it's for.

## Stack
Each major pick and WHY. "Next.js because it deploys to Vercel in one command."

## Structure
The folders that matter and what lives in each. Skip the obvious.

## Commands
dev: ...
test: ...
deploy: ...

## Decisions log
- 2026-07-06: Chose X over Y because Z.
(One line per decision. Append, never rewrite.)

## Gotchas
Things that bit us once and will bite again if forgotten.

Step 2: Boring beats clever

Pick the most common tool for the job, not the most interesting one. Common tools have common answers; every error message has been solved publicly a thousand times.

• Web app: Next.js, deployed on Vercel.
• Database and auth: Supabase or Postgres.
• One-off automation: a single script file. It does not get a framework until it hurts.
• Styling, state, everything else: the default choice of the stack you picked.

Anything new or shiny requires one written line in the decisions log explaining what it buys you. If the line is hard to write, that's the answer.

Step 3: Habits that keep it alive

• Commit after every working change. The message says why, not what: "limit signups to 3 per email to stop the duplicate bug", not "update api.ts".
• Env validation at boot. The app checks its required variables on startup and fails loudly, naming the missing one. A named failure at boot beats undefined at runtime in front of a user.
• One error-handling pattern, decided now, used everywhere. Errors are logged with context server-side; users see something calm.
• Append to the decisions log the moment a choice is made. Future sessions inherit reasons, not just results.

The month test

The foundation is done when a brand-new session with zero conversation history can answer all four of these from the repo files alone:

1. What is this project?
2. How do I run it right now?
3. Why is it built the way it's built?
4. What should I not touch, and why?

If any answer requires "you had to be there", the foundation is not done. Fix CLAUDE.md until it is.

Definition of done for setup

• git initialized, first commit made
• .gitignore in place before any secret existed
• .env.example lists every variable; .env untracked
• README says what + how to run
• CLAUDE.md filled in, including at least one decisions-log entry
• Stack choices are boring, or their reasons are written down
• App fails loudly on missing env vars

Only after this list is checked does feature work begin.