Every app I build with Claude Code starts the same way. Not with code. Not with scaffolding. I write a spec file first. A single SPEC.MD that becomes the source of truth for the whole project.

Without it, every conversation with the AI starts from zero. With it, Claude Code knows exactly what you’re building from the first prompt.

Here’s how I do it.

Step 1: Create the SPEC.MD Link to heading

The spec file gives Claude Code full context about what you’re building. Without one, it’ll hallucinate architecture or invent features you never asked for. I learned this the hard way.

There are two scenarios.

Building a new app from scratch Link to heading

Copy this prompt and paste it into Claude Code. It walks you through an interview, one section at a time, and generates a complete SPEC.MD at the end.

Download the prompt: New Project Spec Creator

Generating a spec from an existing codebase Link to heading

Already have a project? This prompt tells Claude Code to read your source code and produce a SPEC.MD from what it finds. No guessing, just what’s actually in the code.

Download the prompt: Existing Project Spec Creator

What goes in the SPEC.MD Link to heading

A good spec covers everything the AI needs to know, nothing it doesn’t:

  • Overview — What the app does, core features as a short list
  • Architecture — Frontend, backend, data, auth. A few bullets each.
  • Functional Requirements — Grouped by feature, written as “User can…” statements
  • Data Model — Tables with columns, types, and descriptions. Include SQL CREATE TABLE statements.
  • API Design — Endpoints as METHOD /path with request/response shapes
  • Frontend — Pages & Components — Routes and component names with a one-liner each
  • Non-Functional Requirements — Performance, security, reliability. Keep it brief.

Example Link to heading

I built a contact card app and generated a spec for it. Covers every section above:

View example SPEC.MD

Step 2: Set Up CLAUDE.MD Link to heading

CLAUDE.MD is the instruction file Claude Code reads at the start of every conversation. After you generate your spec, prepend this to the top of it:

This app is described in @SPEC.MD.
Read that file for general architectural tasks or to double-check
the exact database structure, tech stack or application architecture.
Keep your replies extremely concise and focus on conveying the key
information. No unnecessary fluff, no long code snippets.

Use websearch or Context7 MCP (if installed) when I need
library/API documentation, code generation, setup or configuration
steps without me having to explicitly ask.

Two things happening here. First, you’re pointing Claude Code at the spec so it knows where the truth lives. Second, you’re setting the tone — be concise, fetch docs automatically, don’t waste my time.

Step 3: Install Context7 Link to heading

Claude Code has a knowledge cutoff. If a library shipped a new version since then, you’ll get outdated suggestions. That gets old fast.

Context7 fixes this. It’s an MCP connector that feeds Claude Code current docs for whatever library you’re using. Install it once, and it pulls fresh documentation on the fly — especially if your CLAUDE.MD tells it to.

Step 4: Prompting Strategies Link to heading

I’ve burned a lot of tokens figuring out what works. Here’s what I’ve landed on.

Be concise and precise Link to heading

Say exactly what you want. “Make the auth work” is bad. “Add email/password signup using better-auth with SQLite. Create the auth API route at /api/auth/[...all]” is good.

Skip the unnecessary context Link to heading

The spec file already has the context. Don’t repeat it. Just say “Per the spec, implement the contacts CRUD endpoints” and move on.

Think first, then prompt Link to heading

Before you type anything, decide what you actually need. Break big features into small tasks. One prompt per task. Not one prompt per feature.

Don’t test the AI Link to heading

Don’t ask “Can you build a full-stack app?” Just tell it what to build. Testing prompts waste tokens and you get back hedging, wishy-washy responses.

Tell it which tools to use Link to heading

Claude Code has a bunch of tools at its disposal. If you don’t tell it which one to use, it’ll explore on its own and burn through context. Be explicit — “Use the Glob tool to find all route files” or “Search with Grep for database queries.”

Putting It All Together Link to heading

  1. Write (or generate) SPEC.MD
  2. Configure CLAUDE.MD to reference it
  3. Install Context7 for live docs
  4. Break your build into focused prompts
  5. Let Claude Code build, review, iterate

The spec is the leverage. Once you have it, every conversation starts with full context instead of from scratch. That’s the whole trick.

For a real-world example, I built playcall — a natural-language NFL stats chatbot — using exactly this workflow. Building is only half of it, though. Once an app works, it has to ship: here’s how I deploy a full-stack app to Google Cloud Run.