The 3-doc system that'll save you 20 hours of refactoring
Takes 30 minutes upfront. Saves your sanity.
Look, you can absolutely just start building. But you're gonna hit that moment at 2am where nothing connects and you're rewriting auth for the third time.
You're creating 3 documents before you write any code. Think of them as contracts between you and Claude.
DOCUMENT 1: DESIGN STYLE GUIDE
Do this first. Not kidding.
Everyone wants to start with features. But if you don't lock in the visual language early, you'll end up with Frankenstein UI. Every component looking like it's from a different app.
Open a chat. Tell Claude what vibe you want. Be specific. "I want it to feel like Linear meets Spotify. Dark mode. Minimal. Lots of breathing room. Subtle animations."
Then ask for:
- Color palette (background, surface, border, text primary, text secondary, accent, destructive)
- Font stack (what's the display font, what's the body font)
- Spacing scale (4, 8, 12, 16, 24, 32, 48, 64)
- Border radius tokens (none, sm, md, lg, full)
- Shadow tokens (if any)
- Animation timing (what's the default easing, default duration)
Get Claude to output this as a single doc. Save it. This is your bible.
Every time you build a component, you paste this in. No more "make it look nice." You say "follow the style guide."
DOCUMENT 2: FRONTEND PRD
Now you know what it looks like. Time to define what it does.
List every page. For each page, list:
- What the user sees (components, layout)
- What the user can do (actions, buttons, forms)
- What happens when they do it (navigation, state changes)
Don't write code. Write behavior.
Example:
"Dashboard page. Shows a list of projects as cards. Each card shows project name, last edited date, and a dropdown menu with edit/delete. Clicking a card opens the project. Delete asks for confirmation."
Then list your components. Just the names and what they do.
- ProjectCard: displays single project, handles click and dropdown
- ConfirmModal: reusable confirmation dialog
- EmptyState: shows when no projects exist
Finally: global state. What needs to be accessible everywhere?
- User auth state
- Current project
- Theme preference
Save this doc. When you're building frontend, this is what you reference.
DOCUMENT 3: BACKEND PRD
Last one. This is the engine.
Start with your data models. What are the things? What properties do they have?
User: id, email, name, avatar, created_at
Project: id, name, owner_id, created_at, updated_at
Then your API routes. Every endpoint. What it does. What it expects. What it returns.
POST /auth/signup - expects email, password. Returns user object and session.
GET /projects - expects auth header. Returns array of user's projects.
DELETE /projects/:id - expects auth header and project id. Returns success or error.
Then your business logic. The rules.
- Users can only see their own projects
- Deleting a project soft-deletes it for 30 days
- Email must be verified before creating projects
Save it.
HOW TO USE THESE
When you start building, you don't paste all three every time. You paste what's relevant.
Building a component? Paste the style guide.
Building a page? Paste the frontend PRD section for that page plus the style guide.
Building an API route? Paste the backend PRD.
Connecting frontend to backend? Paste both.
Claude now has exactly the context it needs. Not more, not less.
THE REAL UNLOCK
These docs aren't just for Claude. They're for you.
Writing them forces you to actually think through what you're building. You'll catch shit early. "Wait, how does a user actually get to this page?" "What happens if they're not logged in?"
That's the stuff that turns into 3am debugging sessions when you skip it.
30 minutes of docs. 20 hours saved. That's the trade.
Now go write them.