How I Prototype with Claude Code - w/Claude.md

I edited this post to be an expanded version. If you read the original, this covers the same ground but goes deeper into the why behind each step.

This might be useful to you if you're curious how someone actually builds things with Claude Code day to day. Not theory. Not a prompt library. Just the process.

This walkthrough uses vanilla HTML, CSS, JavaScript, and .MD files. You'll need Claude Code installed already. The provided Claude.md is specifically tuned for making vanilla HTML, CSS, JavaScript things.

---

## Let's Set the Mood

This feels more like sculpting with a friend than prompt engineering. Very organic.

I have Claude create a basic idea. A lump of clay. Not pretty. Then we build from there. I imagine what I want and ask Claude to make updates. It updates the file. I test it. I ask for more updates. We keep doing this until we make something we like.

We take very small steps. I want to feel each change in UX.

This is important. If you try to describe the whole finished product upfront, Claude will give you something that looks complete but feels hollow. Buttons that technically work but don't feel right. Layouts that check boxes but don't flow. You end up spending more time explaining what's wrong with the output than it would've taken to just build it in small pieces.

Small steps let you steer. You feel each change. You catch problems when they're small. And you discover ideas you never would have thought of sitting in front of a blank spec.

---

## What We're Building

As an example, let's make something extremely useful. We will call it "Useless Spinner App." It will help me make important life decisions.

Here's the finished product: https://3toedsoftware.com/demos/useless-spinner/

I picked this because it's small, visual, and instantly testable. You click things. They spin. You see if it works. If something's wrong, you'll know in two seconds.

---

## Setup

Two things.

**1. Create a folder on your desktop.** Call it "Useless Spinner App" (or whatever you're building).

**2. Copy the Claude.md into the folder.** This file is attached to the post. Read it if you want nerd points, but you don't have to understand every line. It tells Claude how we want it to work. Think of it as the rulebook for your sculpting partner.

What the Claude.md does at a high level:

- Tells Claude to write HTML/CSS/JS

- Offers code quality tools (more on these later)

- Tells Claude to create and maintain an ARCHITECTURE.md file (this becomes critical as projects grow)

- Establishes the rules of the road so you don't have to repeat yourself every session

---

## The Process

### Step 1: Describe the Basic Idea - Lump of Clay

Open your terminal, point it to your working folder, then start Claude Code (/claude) and tell it what you want to make. Keep it loose.

> "I want to make a spinner app to help me make decisions."

You're not writing a spec. You're starting a conversation.

### Step 2: Pick Your Materials

Claude will offer suggestions. It might propose a framework, a library, something fancy. Steer it toward simple.

> "Let's make it with HTML, JavaScript, and CSS. Stay concise and follow your Claude.md."

HTML, CSS, and JavaScript is a really fast way to prototype something visually. Claude updates the file, you refresh the browser, you see the result. That speed is super important when you're iterating.

Ask Claude to "stay concise and follow your Claude.md". It reinforces the rules you set up. This is the only time you need to say this. Claude reads the file automatically, but one reminder at the start of a session helps lock it in.

### Step 3: Let Claude Make Something Lumpy

Claude will ask to create and edit files. Let it.

I chose this option:

> "Yes, allow all edits during this session."

What you get back will not be pretty. That's the point. You now have something real to react to. A lump of clay on the table. It's easier to say "make this part bigger" when you can see the thing than to describe the perfect version from nothing.

### Step 4: Open It Up and Look at It

Ask Claude to open the file in your browser so you can see what it made. Poke around. Click everything.

### Step 5: Break It On Purpose

This is a critical step. Test everything.

Click every button. Drag every slider. Resize the window. Try to use it on your phone. Try the thing it's obviously not designed for.

You are looking for three things:

1. **Things that are broken.** Buttons that don't work. Text that overlaps. Layouts that fall apart.

2. **Things that feel wrong.** A button that works but feels too small. A transition that's too fast. A color that doesn't sit right.

3. **Things that are missing.** What do you wish was there? What are you reaching into the screen for that doesn't exist? What was missed?

Open a notepad and write down everything. Every bug. Every feeling. Every "I wish this did X instead."

### Step 6: Feed the List

Give your list to Claude. I like to feed problems one at a time when I'm still learning the codebase. If I know the project well and I'm confident the changes won't step on each other, I might give it the full list.

Why one at a time? Because each fix can create new problems. If you give Claude ten things to fix at once, it might fix eight of them and introduce two new issues in the process. One at a time lets you verify each fix before moving on. Small steps.

### Step 7: Repeat Until It's Good

Back to Step 5. Test. Note. Fix. Test. Note. Fix.

This loop is where the real work happens. Each pass makes it a little more like what you actually wanted. You'll find that what you want changes as you use it. That's normal. That's the whole point of building this way. You discover the product by using the product.

You'll know you're done with this phase when you use it and nothing bugs you. Not "it's perfect." Just "I like this. This works."

### Step 8: Extract the Blueprint

Ask Claude to create a comprehensive prompt that describes exactly what you just built. Every feature. Every interaction. Every design decision. The look, the feel, the behavior. It should feel HEAVY. You should understand everything. Not the code, but the structure and how everything relates to everything else. This prompt is the spec you couldn't have written at the beginning because you didn't know what you wanted yet. Now you do, because you built the prototype.

---

## What Comes After Prototyping

You now have two things: a working prototype and a blueprint that describes exactly what it does. You know what you're building. That clarity is earned.

This is the perfect starting point for Jake's folder architecture. The prototype was discovery. The folder architecture is how you structure the real build so Claude stays oriented as the project grows. Routing tables, workspace context files, the full system.

If you haven't been through it yet, start with **The Foundation 3.1** in the classroom. It's a 23-minute walkthrough of the whole method. Everything you just did in Steps 1-8 gives you the context to get the most out of it.

**One thing to note:** The Claude.md attached to this post is set up for building web apps. The toolbelt it offers to help you install is web-specific (ESLint, Stylelint, HTMLHint). The code style is web-specific. If you're doing something else, the prototyping process works the same way, but you'd start with a different Claude.md for your tools and workflow.

---

## Evil Context Partitioning

This is the biggest problem I've run into and I think it's worth understanding even if you're just getting started. The sooner you know about it, the less time you'll waste being confused.

**What it is:** As your project grows, Claude can only hold so much of it in its head at once. It has a context window. Think of it like a desk. Claude can only spread so many papers across the desk before some fall off the edge.

So Claude makes a change that looks right in isolation. It fixes a function in one file. Perfect fix. Except there's another file it hasn't read that depends on that function working the old way. Now something is broken in a place neither of you are looking.

This shows up as:

- Duplicate functions (Claude writes a new one because it forgot one already exists)

- Naming conflicts (two things get the same name because Claude only saw one of them)

- Styles that override each other (CSS in one file stomps on CSS in another)

- "I swear this was working yesterday" moments

**Why it happens:** Claude isn't being lazy or careless. It literally cannot see the whole project at once past a certain size. It's working with whatever's on the desk right now. If the relevant file isn't on the desk, Claude doesn't know about it.

**How to fix it:** This is where the ARCHITECTURE.md comes in. It's a summary of how everything connects in the code base. What files exist. What they do. How data flows between them. Think of it like a map of a building. You might not be in every room at once, but you can look at the map and know what's behind every door.

Claude.md directs Claude to read the ARCHITECTURE.md at the start of every session. So even when it can't hold the whole codebase in context, it has a map. It knows where things are before it starts changing things.

The Claude.md I've provided tells Claude to create and maintain the ARCHITECTURE.md automatically. You don't have to write it yourself. Claude updates it as the project grows. But you should read it occasionally to make sure it's accurate. It's Claude's map of your code. If the map is wrong, Claude will make confident wrong turns.

**Small steps help here too.** The less you change at once, the less chance something collides with something Claude forgot about. Big sweeping changes across multiple files are where context partitioning bites hardest. One file, one change, one test. Then the next.

---

## The Toolbelt

I have Claude set up all of these tools automatically. They're written into the Claude.md as install suggestions. You don't need to understand them deeply to use them, but here's what they do and why they matter.

**Git** saves checkpoints so you can go back in time to previous versions. If Claude makes a change that breaks everything, you roll back to the last checkpoint. These checkpoints are usually called "commits." It's your undo button for the whole project.

**ESLint** catches bugs and mistakes in your JavaScript before they become problems. Missing variables. Unused code. Patterns that tend to cause issues. Think of it as a spell-checker for code logic.

**Stylelint** does the same thing for CSS. Catches duplicate rules, deprecated properties, and structural issues. If two CSS rules are fighting each other (which is a context partitioning symptom), Stylelint can flag it.

**HTMLHint** catches structural issues in your HTML. Missing attributes. Unclosed tags. Accessibility problems. The kind of stuff that works in one browser and breaks in another.

**Prettier** auto-formats all your code so spacing and style stay consistent. This sounds cosmetic, but it matters. Consistent formatting makes it easier for both you and Claude to read the code. If every file looks different, Claude wastes context on parsing the formatting instead of understanding the logic.

**Hooks** are an action/reaction system. When something happens (like saving a checkpoint), a hook can trigger something else (like running all the code checkers). It means you don't have to remember to check your code. It happens automatically.

**Husky** makes hooks easy to set up. It wires all the tools above into your Git workflow so they run automatically before every commit. If the code has problems, the commit gets blocked until you fix them. Your checkpoints stay clean.

Together, these tools catch problems at the door. Claude writes the code. The tools verify it before it gets saved. You get fewer surprises.

---

## Putting It All Together

The whole process in one view:

**Setup:** Folder + Claude.md. Your workspace and your rules.

1. **Describe the basic idea** - Tell Claude what you want. Keep it loose.

2. **Pick your materials** - HTML, CSS, JS. Simple. Fast.

3. **Let Claude make something lumpy** - Not pretty. Real.

4. **Open it up and look at it** - See what Claude made.

5. **Break it on purpose** - Test everything. Make a list.

6. **Feed the list** - One fix at a time. Small steps.

7. **Repeat until it's good** - Test, note, fix, test.

8. **Extract the blueprint** - Have Claude write the comprehensive spec.

The prototype is where you discover what you're building. The blueprint is what you take into the real build.

---

## Things I've Learned the Hard Way

- **One-shotting is fun but fragile.** I try it sometimes for fun. But the larger the codebase, the higher the chance things go sideways. Details start to pour through Claude's fingers.

- **Refactors are impressive but nerve-wracking.** I've done several, like switching everything to ES Modules after building giant single files. Claude handles it well, but things do break.

- **Context partitioning is the real boss fight.** The moment your project is too big for Claude to hold in its head, you need a map (ARCHITECTURE.md) and discipline (small steps and many iterations). Everything else is manageable.

- **The sculpt-then-rebuild loop is not wasted work.** It feels like you're doing the job twice. You're not. The first pass is research. You're learning what the thing should be by building the wrong version of it. The second pass is execution. You build the right version because now you know what right looks like.

- **This process might be better for visually oriented people.** I definitely prefer to see something as I think through it. If you're the kind of person who prefers to hold the thing in your hands before you can improve it, this might click for you.

---

That's how I make stuff. It's not the only way. But it's the way that stuck for me after a lot of trial and error.

If you have questions, drop them below. Happy to walk through any part of this in more detail.

2 comments