Starting a Brand-New Project

Start from a truly empty folder

The empty-folder ritual

Terminal 
$ mkdir my-app
$ cd my-app
$ git init
$ claude
In VS Code
  1. Create a new folder and open it with File → Open Folder…
  2. Open the built-in terminal (Ctrl+`)
  3. Run git init, then claude

git init comes before claude on purpose: version control exists before any code does, so even the scaffold lands as a reviewable commit.

The Initialization Prompt

Paste this as your first message, filling in the three blanks in [square brackets]:

The Initialization Prompt — use once per new project 
We are initializing a brand-new project from zero. Work in plan mode first: show me the plan before creating anything.

PROJECT: [1-3 sentences: what it is, who it's for — e.g. "A recipe-sharing website for home cooks. Static-first, must be fast on mobile."]

STACK: [your choice, e.g. "Astro (latest), vanilla CSS, deployed on Cloudflare Pages" — or write "recommend a stack for this project and justify it in 5 lines, then wait for my approval"]

REQUIREMENTS: [bullet the 3-6 things v1 must do]

Once I approve the plan:

1. Scaffold the project with the official starter for the chosen stack. Sensible folder structure, .gitignore (MUST include .env and .claude/settings.local.json), README with run instructions.

2. Get a "hello world" page running: tell me the exact command to see it in my browser.

3. Run /init-style analysis and write CLAUDE.md (max 60 lines): stack, folder map, key paths, conventions, commands, and the rule "read docs/TODO.md before any task; update docs/STATUS.md and commit after any task."

4. Create docs/TODO.md with the requirements above as unchecked items, docs/STATUS.md ("Project initialized — next: first TODO item"), and empty docs/DECISIONS.md.

5. First commit: "chore: project scaffold + memory system".

Do NOT install extra libraries beyond the starter, and do NOT build any features yet — scaffold only.

Filling in the three blanks

  • PROJECT — one to three sentences: what it is, who it's for, and any hard quality ("must be fast on mobile"). This shapes hundreds of small decisions Claude will make.
  • STACK — name it if you know it. If you don't, the "recommend and justify in 5 lines, then wait" variant is genuinely good: you get a reasoned suggestion and a veto, instead of a silent choice.
  • REQUIREMENTS — the three to six things version 1 must do. Not the dream backlog — the first slice. Everything else can be added to TODO.md later.

Why the prompt is built this way

  • "Plan mode first" — a wrong stack or structure is catastrophically cheap to fix at the plan stage and painful after. This is the cheapest moment there will ever be.
  • "Scaffold only — do NOT build features yet" — the classic eager-AI failure is a skeleton with three half-finished features baked in. You want a clean, boring, working base; features come one at a time, each verified and committed.
  • The memory system is born with the project — CLAUDE.md, TODO, STATUS and DECISIONS exist from commit one, so every later session starts smart. Bolting memory onto an old project works too, but born-with is effortless.
  • .gitignore before secrets exist — .env is ignored before there's anything to leak, exactly as the safety chapter demands.

Ten minutes later, you have…

  1. A hello-world page running locally, with the exact command to see it.
  2. A lean CLAUDE.md describing the project it was born into.
  3. docs/TODO.md holding your requirements as the queue, plus STATUS and DECISIONS ready to work.
  4. One clean first commit: chore: project scaffold + memory system.

From here, work is just the loop: pick the top TODO item, run the Feature prompt (chapter 11), verify, commit, clear, repeat.

Up next: the Prompt Library — starting with the five-part shape that every good Claude Code prompt shares. Learn the shape once and you can write every prompt you'll ever need.

FAQ

Frequently Asked Questions

How do I start a brand-new project with Claude Code?
Create an empty folder, run git init, start claude, and paste the Initialization Prompt with your PROJECT, STACK and REQUIREMENTS filled in. It plans first, scaffolds the official starter, gets hello-world running, writes CLAUDE.md and the docs/ memory files, and makes the first commit.
Should I let Claude choose my stack?
A good middle path: ask it to "recommend a stack and justify it in 5 lines, then wait for my approval". You get a reasoned suggestion plus a veto — better than guessing, safer than a silent choice.
Why does the prompt say "scaffold only — no features yet"?
Because the classic eager-AI failure is a skeleton with three half-finished features baked in. A clean, boring, working base first; then features one at a time, each verified and committed separately.
Why run git init before starting Claude?
So version control exists before any code does. Even the scaffold lands as a reviewable first commit, and every later change has a clean baseline to diff against.