spec-app

A Claude Code skill that interviews you before you start building an app, then writes a CLAUDE.md and a ready-to-paste opening prompt — so you start with constraints, not chaos.

What it does

Before you open Claude Code and start vibe coding, this skill runs a short interview. It asks what you're building, who uses it, what it must do, and what it should never touch. Then it:

1. Writes a CLAUDE.md to your project directory with architecture rules, a feature list, and explicit exclusions
2. Shows you the exact opening prompt to paste into Claude Code

The result: the AI builds what you actually want instead of a production SaaS app with auth, notifications, and a microservices backend.

Why it matters

Research on AI-assisted coding shows accuracy drops from ~87% to ~54% when specs are too long or missing constraints. This skill keeps CLAUDE.md under 80 lines and front-loads prohibitive rules — "do not install libraries not on the approved list" — rather than descriptive ones.

Tested against a baseline (Claude without the skill):

• With skill: 100% pass rate across 3 eval scenarios
• Without skill: 16% pass rate — Claude typically skipped the interview entirely and produced a 140–180 line implementation spec with no constraint rules or opening prompt

When it triggers

The skill auto-triggers when you describe a greenfield project:

• "I want to build an app that..."
• "Help me plan a new project"
• "How do I start building X?"
• "I want to make something that does Y"
• "What's the best way to spec out an app before vibe coding it?"

It does not trigger when you're working on existing code (adding features, fixing bugs, refactoring).

Tracks

• Short track (1 day or less): 2-section interview, minimal CLAUDE.md
• Full track (3–7 days): 5-section interview, full CLAUDE.md with stack, constraints, red lines
• Too big: redirects to GSD for multi-phase projects

Install

Requires Claude Code.

# Copy SKILL.md to your Claude skills directory
cp SKILL.md ~/.claude/skills/spec-app/SKILL.md

Or drop SKILL.md into any folder Claude Code is watching for skills.

Once installed, just describe what you want to build — the skill triggers automatically.

Output

CLAUDE.md (written to your project directory):

## App
A local tool that tracks movies I've watched and lets me rate them.

## Context
This is a single-user, local-only app. Runs on one machine.

## Stack (exact)
- Next.js 15
- Tailwind CSS
- shadcn/ui
- SQLite + Drizzle ORM

## Architecture Rules
IMPORTANT: Do not install libraries not in the Stack list above without asking first.
IMPORTANT: Check if logic already exists before writing new code.
IMPORTANT: Keep changes minimal and related to the current request.
IMPORTANT: Keep the diff small. Do not rewrite half a file because you got excited.

## Do NOT
- Do not delete any data or files without explicit confirmation
- Do not modify the database schema without telling me what you're changing and why
- Do not add any library not listed in Stack above without asking me first
- Do not change the overall architecture without discussing it with me first

## Features (MVP)
- I can add a movie I've watched with a title, date, and rating
- I can view my full watch history sorted by date
- I can filter by rating

## Out of Scope (MVP)
- No user accounts or login
- No sharing or social features
- No recommendations
- No mobile app

Opening prompt (you paste this into Claude Code):

## App: Movie Tracker
A local tool that tracks movies I've watched and lets me rate them.

## This is a single-user, local-only app.
No auth system needed. No multi-user data isolation. Data lives locally.

## Stack (exact, non-negotiable)
...

## Do NOT start coding yet. Tell me your plan first.

Files

SKILL.md        — The skill itself (Claude reads this)
evals/
  evals.json    — Test cases used to validate the skill