Vibe Coding for Non-Developers

What You Get

A framework for building real, production-worthy apps with AI coding tools (Claude Code, Cursor, etc.) without ending up with unmaintainable spaghetti. You stay the architect. AI handles the building. Both of you know the rules.

This isn’t a how-to-code tutorial. It’s a how-to-manage-AI-builders playbook.

The Golden Rule

You are the architect. AI is the builder.

You don’t need to understand every line of code. You do need to understand the structure, the naming, the “why” behind decisions. That’s what keeps a codebase sane.

A builder without an architect produces beautiful walls in random places. An architect without a builder produces blueprints that don’t work. You need both.

Before You Code: The Upfront Work

This is 2-3 hours that saves you 20 hours later.

1. Create a claude.md File

Before you write a single line of code, create a claude.md in your project root. This is your project brain file. It tells AI how to think about your project.

Prompt to generate your claude.md:

I'm about to build [APP DESCRIPTION] and I want to set up a claude.md file that guides AI builders on this project.

Here's what I know:
- What we're building: [Clear description of the app]
- Who uses it: [Target user]
- Core problem it solves: [The main job-to-be-done]
- Stack preference: [e.g., "Next.js + Supabase," "vanilla JS + Firebase," "Python + FastAPI"]
- Key constraints: [e.g., "no server cost," "mobile-first," "offline-capable," "real-time sync"]
- Success metric: [How do you know it's working? e.g., "Users coming back daily," "Handles 1000 concurrent users"]

Generate a claude.md that includes:

1. PROJECT OVERVIEW — What this app is, what it does, why it matters
2. TECH STACK — Frontend, backend, database, hosting, auth, any special services
3. FILE STRUCTURE — The intended folder layout (don't build yet, just define it)
4. KEY RULES — Coding standards for this project
5. COMPONENT ARCHITECTURE — How pieces connect (UI to API to database)
6. DATABASE SCHEMA — Tables, relationships, key fields (if applicable)
7. API STRUCTURE — Main endpoints or functions (if applicable)
8. STYLING APPROACH — CSS framework, design tokens, naming convention
9. TESTING STRATEGY — What gets tested, how
10. DEPLOYMENT & MONITORING — How this gets shipped and what we watch

Make this usable for an AI builder. Be specific. "Use semantic HTML" is good. "Use React components with props destructuring and TypeScript interfaces in the Props type" is better.

This takes 30 minutes. It saves hours because every follow-up prompt includes this context and AI doesn’t have to guess about your preferences.

2. Pick a Stack

Don’t overthink this. Pick one and stick with it.

• Web app, solo/small team: Next.js + Supabase (or Firebase). Move fast, hosting is simple.
• Web app, real-time: Next.js + Supabase (real-time is built in).
• Web app, cheap: Vanilla JavaScript + Firebase or Supabase.
• Python backend + web frontend: FastAPI + Next.js + Supabase.
• Mobile first: React Native or Flutter. (Harder to build with AI, but possible.)

Once you pick, write it in claude.md and don’t change it mid-project. Switching stacks is a 10-hour setback.

3. Define File Structure Upfront

Create a folder structure before coding. Something like:

app/
  ├── components/          (UI building blocks)
  │   ├── common/          (buttons, cards, modals — used everywhere)
  │   ├── features/        (feature-specific, like [Feature]Header.tsx)
  │   └── layout/          (navigation, sidebars)
  ├── pages/ or routes/    (page-level components or route handlers)
  ├── lib/                 (utilities, helpers, constants)
  │   ├── api.ts           (API client code)
  │   ├── db.ts            (database queries)
  │   └── utils.ts         (general helpers)
  ├── styles/              (global CSS, design tokens)
  └── types/               (TypeScript types, shared interfaces)

API/
  ├── routes/              (API endpoints)
  ├── middleware/          (auth, logging, etc)
  └── models/              (database models, schemas)

Name folders and files like a human would search for them. “components” not “comps”. “auth” not “a”. “UserProfile” not “UP” or “profile123”.

While Building: The Rules That Matter

Rule 1: One File, One Job

Every file should do one thing. One component = one visual element or behavior. One utility file = one concern (date handling, string formatting, etc).

Bad:

dashboard.tsx  // 2000 lines. Has the header, the sidebar, the analytics charts, 
               // the user settings, everything.

Good:

components/
  ├── DashboardHeader.tsx
  ├── DashboardSidebar.tsx
  ├── AnalyticsChart.tsx
  └── UserSettings.tsx

This makes it easy to find what you’re looking for. This makes it easy to change things without breaking everything.

Rule 2: Comment the WHY, Not the WHAT

Bad comment:

// Get the user's name
const name = user.name;

Good comment:

// Format name for display (handles null gracefully for guest users)
const displayName = user?.name || 'Guest';

AI tends to over-comment. Tell it: “Skip obvious comments. Only explain non-obvious decisions or tricky logic.”

Rule 3: Name Things Like a Human

This matters more than you think.

Bad names:

fn handleClick()      // Handles click of what?
data                  // Data about what?
temp, x, arr          // Could be anything

Good names:

handleUserProfileUpdate()  // Clear what changes
userEmail                  // Specific data
tempFormErrors            // What the temp variable holds
usersList                 // An array of users

When you brief Claude, say: “Name everything like it’s searchable in the codebase.”

Rule 4: Use TypeScript (Even If You Don’t Know It)

You don’t need to write it. Just tell Claude to use TypeScript. It forces clarity. Props get typed. Functions have return types. It catches bugs before runtime.

In your claude.md: “Use TypeScript throughout. Every component should have a Props interface. Every function should have a return type.”

Rule 5: Keep Components Small

A component should fit in your head. 50-100 lines is good. If it’s 500+ lines, break it up.

Bad:

UserForm.tsx — 600 lines. Handles display, validation, API calls, error states, loading states.

Good:

UserForm.tsx — 80 lines. Manages form state. Calls API.
  ├── NameField.tsx — Just renders name input
  ├── EmailField.tsx — Just renders email input
  └── FormError.tsx — Just renders errors

Smaller pieces are easier to test, easier to change, easier to reuse.

Rule 6: No Magic Strings

Bad:

const api = 'https://api.example.com/v1/users/update';
fetch(api, ...)

Good:

const API_BASE = 'https://api.example.com/v1';
const ENDPOINTS = {
  UPDATE_USER: `${API_BASE}/users/update`,
};
fetch(ENDPOINTS.UPDATE_USER, ...)

When you ask Claude to build features, specify: “No hardcoded URLs. No magic numbers. Define constants at the top of files or in a config.”

Rule 7: Test as You Go

You don’t need 100% coverage. But before you move to the next feature, test the one you just built.

Ask Claude: “Write a test file for [component/function]. Test the happy path and one error case.”

One quick test per feature beats 10 manual tests at the end.

The Anti-Patterns (Avoid These)

God Files — A 2000-line file doing 5 different jobs. Impossible to navigate.

No Error Handling — Your app crashes on bad input instead of showing a nice error. Brief Claude: “Every API call should have error handling with user-facing messages.”

Hardcoded Values — API URLs, API keys, thresholds, all baked into the code. Impossible to change without re-coding.

Missing Mobile Check — Looks great on desktop, breaks on phone. When asking for features, specify: “Mobile-first. Test on phone while building.”

No Loading States — User clicks a button, nothing happens for 3 seconds. They click again. 10 duplicate API calls. Brief Claude: “Show loading state during API calls. Disable button while request is pending.”

Ignoring TypeScript Errors — “I’ll fix them later.” You won’t. Use TypeScript properly as you go.

No Comments on Tricky Logic — That clever sorting algorithm makes sense now but looks like magic in 3 months. Brief Claude: “If something isn’t obvious, comment it.”

The Pre-Ship Checklist

Before you call anything “done,” run through this. It takes 20 minutes and catches 80% of issues.

BEFORE YOU SHIP CHECKLIST

ARCHITECTURE
☐ Every file has one clear job
☐ File names are searchable (not "temp," "utils," "stuff")
☐ No unused files or dead code
☐ All TypeScript errors resolved (no "any" types unless documented)

CODE QUALITY
☐ No hardcoded URLs, API keys, or thresholds (all in constants/config)
☐ Error handling exists (API calls fail gracefully, user sees a message)
☐ Loading states exist (buttons disabled, spinners shown during requests)
☐ Comments exist on non-obvious logic

FUNCTIONALITY
☐ Happy path works (the main user flow)
☐ One error case tested (what happens if the API fails?)
☐ Works on mobile (not just desktop)
☐ No console errors or warnings

PERFORMANCE
☐ Images optimized (compressed, right size)
☐ No N+1 queries (not loading the same data 50 times in a loop)
☐ No unnecessary re-renders (React components not rendering every keystroke)

SECURITY
☐ No secrets in frontend code (API keys, tokens, in backend/env only)
☐ API endpoints validate user input
☐ User can't access other user's data without permission

POLISH
☐ Error messages are human-readable (not "Error: 500" but "Sorry, we couldn't save your changes. Try again?")
☐ Loading states are visible
☐ Buttons are clickable (right size, right color, not buried)
☐ Text is readable (not too small, good contrast)

How to Brief Claude for a New Feature

Now you know the rules. Here’s how to ask Claude for something:

I want to add [FEATURE] to the app.

Here's the user flow:
1. User does [action]
2. System does [behavior]
3. Result is [outcome]

Requirements:
- Use the file structure from claude.md (no god files)
- Use TypeScript with full type coverage
- Handle errors gracefully (user sees a message, not a crash)
- Show loading state while the request is pending
- Mobile-first (test on phone size)
- Comment any non-obvious logic
- No hardcoded URLs or thresholds (use constants)

Build [feature] and tell me:
1. What files you created/modified
2. Any environment variables I need to set
3. One test case I should manually verify

This brief tells Claude how to think. The output will be measurably better.

Tips

One: If you end up with spaghetti code, it’s never too late to refactor. Set aside 2 hours, tell Claude: “Help me break this [god file] into smaller pieces,” and rebuild it. Sometimes this takes less time than you’d think because AI can do the mechanical refactoring fast.

Two: Your claude.md is a living document. As you learn what works and doesn’t, update it. After a month of building, you’ll know what rules matter for YOUR app and what’s overkill.

Three: Don’t micro-manage the code. You don’t need to understand every line. You do need to understand: Is this the right architecture? Are we following the rules? Can we change this next week if we need to?

Four: If a feature feels hard to build, that’s often a signal that the architecture is off. Instead of powering through, ask Claude: “This feature is hard to build. Is our architecture wrong? Should we rethink this?”

Five: Keep a shipping mindset. “Perfect code that doesn’t exist” is worse than “working code with rough edges.” Build the MVP. Ship it. Refactor next sprint.

Want more methods? Browse the full library at hazelq.com/methods. Built with Claude. Every prompt in this library has been tested in the latest Claude model.