I thought I was being thorough.

My CLAUDE.md file had grown to over 1,500 lines. Every coding convention I’d ever learned. Every edge case I’d encountered. Code snippets for common patterns. Integration examples for every third-party service we used. Database schema references. The works.

I was so proud of that file. Look at all this context I’m giving Claude! Surely this would make it understand my project perfectly.

(Narrator voice: It did not.)

Here’s what actually happened: Claude started missing obvious things. Instructions I knew were in there—ignored. Conventions I’d spelled out clearly—forgotten. The more I added to my CLAUDE.md, the worse Claude performed.

I’d accidentally discovered something that changed how I approach AI-assisted development entirely.

.

.

.

The problem wasn’t that Claude couldn’t follow instructions. The problem was that I’d given it too many to follow.

What Even Is a CLAUDE.md File? (And Why Should You Care?)

Let’s back up for a second—because if you’re new to Claude Code, you might be wondering what I’m talking about.

CLAUDE.md is a markdown file that lives at the root of your project. Claude Code reads it automatically at the start of every session. Think of it as your project’s instruction manual for the AI—persistent memory across what would otherwise be completely stateless conversations.

And here’s the thing: after your choice of model, your CLAUDE.md file is the single biggest point of leverage you have in Claude Code.

One bad line in there? It cascades into everything downstream.

Every decision Claude makes flows from that initial context. A vague instruction becomes a vague spec, becomes vague research, becomes a vague plan, becomes… well, you know how this story ends.

.

.

.

The “Instruction Budget” I Wish Someone Had Told Me About

Here’s where I learned my lesson the hard way.

LLMs have a finite number of instructions they can reliably follow at once. This sounds obvious when I say it out loud, but I’d never really internalized it until I watched my 1,500-line CLAUDE.md file turn Claude into a confused mess.

The counterintuitive part? Adding more instructions doesn’t just risk the new ones being ignored. It degrades performance uniformly across all your instructions—including the ones that worked perfectly before.

Research from Chroma on “context rot” backs this up: as the number of tokens in the context window increases, the model’s ability to accurately recall information from that context decreases. Your beautiful, comprehensive CLAUDE.md file might actually be making Claude worse at remembering what’s in it.

Let me do the math for you: Claude Code’s system prompt already uses around 50 instructions. If the model handles roughly 250 total, you’ve got about 200 left for your CLAUDE.md plus your plan plus your task prompt.

And here’s the part that really stung when I realized it: a bloated CLAUDE.md means you’re filling up the context window before you even send your first instruction. Every session starts with that massive file loaded. Every message you send has to fit alongside it.

If you’ve been struggling with Claude Code eating through your weekly usage too fast, the first place to cut is your CLAUDE.md file. Seriously. Smaller context = fewer tokens consumed = more runway for actual work.

I went digging through public CLAUDE.md files on GitHub recently. About 10% of them exceed 500 lines.

That’s almost certainly too large. (Ask me how I know.)

👉 Aim for under 300 lines. Ideally much shorter.

.

.

.

The Framework That Finally Made Sense

After my bloated-file disaster, I needed a new approach. I landed on something simple: think of CLAUDE.md as an onboarding document.

Imagine you’re bringing a brilliant new hire up to speed on day one. What would you tell them? Three things, really:

WHAT — The tech stack, project structure, key files. “This is a Next.js 14 app with App Router, Prisma, and Stripe.”

WHY — The purpose of the project and its parts. “We’re building an e-commerce platform for artisan sellers.”

HOW — Commands, workflows, conventions. “Use npm, not pnpm. Run tests before commit.”

Everything else? Details that can live elsewhere or get loaded on-demand. (More on that “on-demand” part in a minute—it’s a game-changer.)

.

.

.

Where You Put Things Actually Matters

Here’s something I didn’t appreciate until embarrassingly recently: models pay more attention to the top and bottom of a document than the middle. Primacy and recency effects—same cognitive biases humans have.

So structure your CLAUDE.md accordingly:

At the top (highest weight):

1. Project description (1-3 lines)
2. Key commands (dev, test, build, lint, deploy)
3. Tech stack and architecture overview

In the middle (lower relative weight): 4. Code style and conventions 5. File/folder structure map 6. Important gotchas and warnings 7. Git and commit conventions

At the bottom (high weight again): 8. Explicit DO NOTs 9. References and @imports to deeper docs

Let me walk through the ones that matter most.

Project Description

A concise summary that orients Claude to the big picture. Every decision should tie back to purpose.

# Project: ShopFront
Next.js 14 e-commerce application with App Router, 
Stripe payments, and Prisma ORM. Built for artisan 
sellers to manage inventory and process orders.

Three lines. Claude now knows what you’re building, who it’s for, and the core architecture. That’s it.

Key Commands

Be explicit here. Don’t assume Claude knows your setup—it doesn’t.

## Commands
- `npm run dev`      — Start dev server (port 3000)
- `npm run test`     — Run Jest unit tests
- `npm run test:e2e` — Run Playwright E2E tests  
- `npm run lint`     — ESLint check
- `npm run build`    — Production build
- `npm run db:migrate` — Run Prisma migrations

And include the non-obvious choices! “Use npm not pnpm or bun” saves you from Claude randomly picking bun because it read about it somewhere and thought it’d be helpful. (Thanks, Claude. Very helpful.)

Code Style—Where Most People Go Wrong

This is where I see CLAUDE.md files bloat into monsters. Vague rules that waste your precious instruction budget.

Don’t write this:

• “Use good coding practices”
• “Write clean code”
• “Follow best practices”

These instructions accomplish nothing. They’re the equivalent of telling a new hire “do good work.” Thanks, very actionable.

Write this instead:

• “TypeScript strict mode, no any types”
• “Use named exports, not default exports”
• “Prefer const over let“
• “Use import type {} for type-only imports”

Every instruction should produce a measurable difference in output.

And here’s a secret that took me way too long to figure out: don’t send an LLM to do a linter’s job. If a rule can be enforced by ESLint or Prettier, enforce it there. LLMs are slow and expensive linters. Claude learns from your existing code patterns anyway—it doesn’t need to be told every formatting convention.

One more thing: resist the urge to stuff code snippets, integration examples, and schema references into your CLAUDE.md. I know it feels helpful. I did it too. But all those “handy references” are just bloating your context window and triggering context rot. If Claude needs to see code, it can read your actual codebase.

The DO NOTs

Put these at the bottom (recency effect) and be specific:

## DO NOT
- Do not modify files in `/generated/` — they are auto-generated
- Do not use `console.log` — use the project logger
- Do not run `prisma db push` — always use migrations

Use emphasis sparingly. If everything is IMPORTANT, nothing is.

.

.

.

The Technique That Changed Everything: Lazy Loading Your Context

Okay, here’s where things get really interesting.

Instead of cramming everything into one giant root file, you can distribute smaller CLAUDE.md files across subfolders. The magic? They only load when Claude actually reads files in that folder.

Think about what this means: your Supabase migration instructions only consume tokens when you’re actually working on Supabase. During frontend work? Those instructions don’t exist. They’re not cluttering up Claude’s context. They’re not eating into your instruction budget.

It’s lazy loading for your AI context.

How to Split Things Up

Your root CLAUDE.md stays small—maybe 50-100 lines. Project description, global commands, universal rules. The stuff that applies everywhere.

Then each subfolder gets its own focused file:

• src/CLAUDE.md — Component patterns, state management approach, import rules
• api/CLAUDE.md — Endpoint conventions, auth rules, error format, validation patterns
• supabase/CLAUDE.md — Migration flow, schema rules, dangerous commands to avoid

These load automatically when Claude reads files in those directories. No extra work on your part. Just organize your instructions where they logically belong.

Progressive Disclosure with @imports and Rules

Here’s another trick: reference detailed docs instead of inlining everything.

## References
See @README.md for project overview
See @docs/api-patterns.md for API conventions  
See @docs/auth-flow.md for authentication details
See @package.json for available scripts

Or use the .claude/rules/ directory:

All markdown files in .claude/rules/ load automatically alongside your main CLAUDE.md. Modular. Organized. Maintainable.

If you want to take this further—and I mean really further—I wrote a deep dive on building self-evolving Claude Code rules that keep all your guidelines, code snippets, and best practices organized in a system that actually grows smarter over time: How to Build Evolving Claude Code Rules.

It’s the natural next step once you’ve got the basics of CLAUDE.md structure down.

.

.

.

A Real Example: What This Looks Like in Practice

Here’s a complete root CLAUDE.md that actually works:

# Project: ShopFront
Next.js 14 e-commerce app with App Router, Stripe, Prisma ORM.
Built for artisan sellers to manage inventory and process orders.

## Commands
- `npm run dev`: Start dev server (port 3000)
- `npm run test`: Run Jest tests
- `npm run test:e2e`: Run Playwright E2E tests
- `npm run lint`: ESLint check
- `npm run build`: Production build
- `npm run db:migrate`: Run Prisma migrations

## Tech Stack
- TypeScript (strict mode)
- Next.js 14 (App Router)
- Prisma ORM + PostgreSQL
- Stripe for payments
- Tailwind CSS + Radix UI
- Jest + Playwright for testing

## Architecture
- `/app` — Pages, layouts, API routes
- `/components/ui` — Shared UI components
- `/lib` — Utilities, helpers, shared logic
- `/prisma` — Schema and migrations

## Code Conventions
- Named exports only (no default exports)
- Use `import type {}` for type-only imports
- No `any` types — use branded types for IDs
- Functional components with hooks
- Tailwind classes only, no custom CSS files

## Important
- NEVER commit .env files
- Stripe webhook must validate signatures
- Images stored in Cloudinary, not locally
- Do not modify files in `/generated/`
- Use project logger, not console.log

See @docs/auth-flow.md for authentication details
See @docs/api-patterns.md for API route conventions

That’s roughly 45 lines. Clean. Scannable. Universally applicable.

.

.

.

The Growth Strategy (Or: How to Not Repeat My Mistakes)

Please, I’m begging you: do not start with a giant template or auto-generated file.

Start with the absolute minimum. Project description, key commands. Maybe 20 lines.

Then use Claude Code on your project. When Claude makes a repeated mistake—and it will—add ONE targeted instruction to fix it. Commit that change to Git so you can trace it later.

Here’s the counterintuitive part: with every model release, look at what you can remove from your CLAUDE.md. Not what you can add. Remove.

Newer models have better built-in behaviors. Old workarounds can actively hinder them. Your CLAUDE.md should shrink over time, not grow.

(This was hard for me. I’m a collector by nature. But trust me—less really is more here.)

.

.

.

The Maintenance Checklist I Actually Use

Every few weeks—or after any model upgrade—I run through this:

Remove:

• Redundant rules the model handles naturally now
• Old workarounds for previous model versions
• Vague instructions that don’t change output
• Rules that should be enforced by linters instead
• Code snippets and examples that bloat context

Relocate:

• Domain-specific rules → move to subfolder CLAUDE.md files
• Detailed docs → convert to @imported files
• Rarely-used conventions → put in .claude/rules/

Simplify:

• Merge overlapping instructions
• Replace verbose paragraphs with bullet points
• Make every line earn its place

The Complete Picture

Here’s how all the pieces fit together:

It looks like a lot. But you don’t need all of it. Start with the root file. Add lazy loading when your root gets crowded. Grow organically.

.

.

.

Your Next Step

Here’s my challenge for you:

Open your most active Claude Code project. Look at your CLAUDE.md file (or create one if it doesn’t exist). And ask yourself one question:

What instruction am I going to remove today?

Not add. Remove.

Find the vague rule that accomplishes nothing. Find the workaround for a model behavior that’s been fixed. Find the code snippet that’s just bloating your context. Find the formatting instruction that ESLint already handles.

Delete it.

Every line should earn its place.

You’re tweaking a landing page in Claude Code.

“Make the layout more balanced,” you type—feeling pretty clever about your prompt, if we’re being honest.

Claude adjusts the CSS. You refresh the browser.

Hmm. Not quite right.

“Actually, make the image section wider.”

Claude dutifully changes the grid. You refresh again.

Still off. (Why is this so hard?)

“Can you try pill-shaped buttons instead?”

And now you’re three iterations deep, squinting at your screen, no longer entirely sure what “right” even looks like anymore.

Here’s the thing: I spent an embarrassing amount of time in this loop before discovering there’s a plugin that makes the whole rigmarole unnecessary.

It’s called the Claude Code Playground skill. And it changes everything about how you approach design work.

Stay with me.

.

.

.

The Describe-Refresh-Despair Loop (A Love Story Gone Wrong)

Let’s be real about what’s happening here.

You have a vision in your head. A feeling of what the page should look like. Something about the proportions, the spacing, the way elements breathe together.

But translating that feeling into words?

That’s where the wheels come off the wagon.

The loop goes something like this:

1. Describe a change in words (that you hope Claude interprets correctly)
2. Wait for Claude to apply it
3. Refresh the page
4. Realize it’s not quite what you meant
5. Try different words—maybe “airy” instead of “spacious”?
6. Repeat 8-12 times
7. Eventually settle for “close enough” while muttering under your breath

I burned way too many hours in this loop last week, redesigning a page. Every iteration felt like playing telephone with my own design instincts.

(Spoiler: I was the one garbling the message.)

The problem isn’t Claude. The problem is that words are a terrible interface for visual decisions.

.

.

.

Enter the Claude Code Playground Skill: Your New Best Friend

Anthropic built an official plugin—the Playground skill—that adds something radical to Claude Code:

A visual layer between your brain and your codebase.

Here’s how it works: Claude analyzes your existing page, then generates a self-contained HTML file with sliders, dropdowns, and presets that let you see different design directions instantly.

No code changes. No refreshing. No “what I said vs. what I meant” shenanigans.

Just a live preview that updates as you click.

Once you’ve dialed in the exact design you want—with your actual eyeballs—the playground generates a natural language prompt describing your choices.

Copy. Paste. Execute.

One pass. Done.

👉 The key insight: You’re no longer translating visual intuition into words. The playground does that translation for you.

.

.

.

The Real-World Test: Redesigning a WooCommerce Product Page

Enough theory. Let me show you exactly how this worked on my LicenseWP product page.

The existing page was… fine. Functional. The kind of “fine” that makes you wince slightly every time you look at it.

The image area felt cramped. The pricing cards looked squished together. The “Add to cart” button was doing its best impression of a wallflower at a party.

I wanted to experiment with different proportions, card styles, and CTA treatments.

The old me would have spent an hour going back-and-forth with Claude in text prompts.

The new me? Installed the Playground skill.

.

.

.

Step 0: Install the Plugin (30 Seconds, Tops)

First things first—you need the Claude Code Playground skill installed.

Run /plugin in Claude Code, switch to the Discover tab, and search for “playground.”

Hit space to toggle it on.

That’s it. Claude now knows how to build interactive design playgrounds. (11.4K installs can’t be wrong, right?)

.

.

.

Step 1: Send Claude to Do Reconnaissance

Here’s where the magic starts.

I gave Claude a prompt telling it to visit my product page, study the layout like an art critic at a museum, and then build a Design Layout Playground based on what it found.

Claude opens Chrome and starts analyzing—like a very thorough house inspector, but for web pages.

It reads the DOM, extracts text content, and runs JavaScript to pull the full HTML structure.

Screenshots. Scrolling. Full page analysis from header to footer.

(Claude is nothing if not thorough.)

.

.

.

Step 2: Claude Builds You a Custom Design Tool

Once Claude understands your page, it loads the Playground skill and reads the design template.

Then—and here’s the part that made me do a little happy dance—it creates a single self-contained HTML file with everything baked in.

1,253 lines. A complete interactive design tool, built specifically for your page, in about 30 seconds.

Here’s what Claude built for me:

• 5 presets — each one a cohesive design direction
• 7 control groups — layout, gallery, typography, cards, buttons, tabs, colors
• Live preview — using my actual page content (real product names, real prices, real structure)

Ferpetesake, this is exactly what I needed.

.

.

.

Step 3: Play With Designs Like a Kid With New LEGOs

Open the HTML file in your browser.

And then—I’m not going to lie—prepare to lose 20 minutes just playing.

The left panel has all the controls. The right panel shows a live preview that updates instantly as you change anything.

(I may have spent an unreasonable amount of time just clicking the “Gallery Style” options back and forth. Don’t judge me.)

I started by clicking through the presets to find a direction:

• Bold SaaS — too aggressive for this product
• Compact & Dense — too cramped (we’re selling premium themes, not packing a suitcase)
• Clean Editorial — closer! But needed tweaks

Then I fine-tuned individual controls:

• Grid split: 50/50 (equal width for image and details)
• Gallery style: Framed (light background with border instead of that gradient)
• Gallery radius: 24px (rounder corners, friendlier vibe)
• CTA button: Pill-shaped, full-width, large
• Tabs: Pill style, stretched across the full width

Every single change reflected instantly in the preview.

👉 Here’s what hit me: I wasn’t describing what I wanted anymore. I was seeing it. And clicking until it looked right.

.

.

.

Step 4: Copy the Magic Prompt

Once the design felt right, I scrolled to the bottom of the playground.

And there it was.

The Prompt Output panel had already written a clear instruction describing exactly what I chose—and only what differed from the defaults.

Redesign the product single page at http://localhost:8107/product/theme-pro-tc011/ 
with the following design changes:

- product grid split: 50/50
- section spacing: 64px
- gallery style: framed
- gallery border radius: 24px
- product title size: 36px
- tier card border radius: 8px
- selected tier highlight: border-only
- CTA button style: pill-shaped
- CTA button width: full-width
- CTA button size: large
- tab style: pill tabs
- tab alignment: stretch

No ambiguity. No “make it more modern” nonsense.

Just precise specifications that Claude can execute without guessing.

One click on Copy Prompt.

.

.

.

Step 5: Let Claude Do Its Thing

Back in Claude Code. Paste.

Claude immediately recognizes the design instructions and enters plan mode to explore the codebase.

33 tool uses. 101k tokens. 2 minutes of thinking.

Claude reads every relevant CSS file, understands the variable system, and maps out exactly what needs to change.

Then it presents the plan:

Every change mapped out. Exact line numbers. Before/after CSS.

(Is it weird that I find this deeply satisfying? Don’t answer that.)

Verification steps included. Dark mode considerations. Mobile responsiveness checks.

I approved. Claude started executing.

9 CSS edits. All applied.

And… done.

.

.

.

The Result (AKA: The Part Where I Do a Victory Lap)

Here’s the final redesigned product page:

• Equal-width layout. The image and product details now have balanced visual weight.
• Framed gallery. Clean border instead of that dated gradient background.
• Full-width CTA. The “Add to cart” button finally commands the attention it deserves.
• Pill tabs. Stretched across the full width with a modern, cohesive feel.

The design matches what I saw in the playground preview—applied in a single pass.

HECK YES.

.

.

.

The Before & After (Because We All Love a Good Transformation)

The old workflow would’ve taken an hour of back-and-forth (and probably some mild frustration-snacking).

This took 15 minutes—and honestly, most of that was me playing with the controls because it was genuinely fun.

.

.

.

When the Claude Code Playground Skill Really Shines

👉 Redesigning existing pages. You already have something. You want to explore variations without breaking it.

👉 Client projects. Preview before you commit. Show options before you build. (Clients LOVE this, by the way.)

👉 Design indecision. When you don’t know what you want—and let’s be honest, that’s more often than we’d like to admit—clicking through presets beats describing in words.

👉 Reducing the prompt iteration loop. One visual session replaces 10+ text-based rounds of “no, more like… actually less like that… wait, go back.”

The playground acts as a translation layer between your visual intuition and Claude’s execution capabilities. You figure out what “right” looks like with your eyes, then communicate that with precision.

The Prompt Template (Steal This)

Here’s the full prompt I use. Copy it. Adapt it. Make it yours.

First, use the browser to visit and read this page: [YOUR_PAGE_URL]

Study the page's current layout structure, section hierarchy, component patterns, 
and overall visual design. Take note of how content is organized and what 
elements are present.

Then, use the "playground" skill (design-playground template) to build an 
interactive Design Layout Playground based on what you found on that page.

The playground should let me visually explore different layout and component 
style combinations for that page.

## Presets
Include 3–5 named presets that snap all controls to a cohesive combination, 
inspired by what would work well for the page's content. For example:
- "Clean Editorial" — airy spacing, narrow content width, minimal components
- "Bold & Modern" — full-width hero, elevated cards, bold CTAs
- "Compact Dashboard" — tight spacing, grid cards, minimal chrome
- Adapt these to fit the actual content and purpose of the page

## Preview
- Single live preview panel that updates instantly on every control change
- The preview should use a simplified but recognizable representation of the 
  actual page content (use real section names, headings, and placeholder text 
  that matches the page structure)
- Use raw CSS (no Tailwind or frameworks)

## Output Location
- Save the playground HTML file to `notes/playground/` folder (create it if 
  it doesn't exist)

## Prompt Output
- Generate a natural language instruction at the bottom that I can copy and 
  paste back into Claude to implement the chosen design
- The prompt should describe the layout and component decisions in enough 
  detail to be actionable without the playground
- Only mention choices that differ from the defaults
- Frame it as a direction, e.g.: "Redesign the page with a full-width hero 
  section, 3-column card grid with elevated shadows and 16px gap, airy 
  section spacing (64px), pill-shaped CTAs positioned inline..."
- Include the source page URL in the generated prompt for context

Replace [YOUR_PAGE_URL] with whatever page you want to redesign.

.

.

.

Your Turn

Next time you’re about to type “make it more modern” or “adjust the spacing” or “try a different card style”—stop.

Build a playground first.

Let your eyes make the decisions. Let the Claude Code Playground skill translate those decisions into words. Let Claude execute them precisely.

What page are you going to redesign with this workflow?

Go install the plugin. Run /plugin, search “Playground”, toggle it on.

Now.

(And maybe clear your schedule. Because once you start playing with those sliders, you might lose track of time.)

Last week, I walked you through browser testing with Claude Code using the Ralph loop plugin.

I was pretty proud of it, actually.

Here’s the thing: I was wrong.

Well, not entirely wrong. The tests ran. Things got verified. But what I showed you? That wasn’t a true Ralph loop—not the way Geoffrey Huntley originally designed it. And the difference matters more than I realized at the time.

(Stay with me here. This confession has a happy ending.)

.

.

.

The Problem I Didn’t See Coming

The real Ralph loop is supposed to wipe memory clean at the start of each iteration. No leftover context. No accumulated baggage. Just a fresh, focused agent tackling one task at a time.

The Ralph loop plugin from Claude Code’s official marketplace? It preserves context from the previous loop. The plugin relies on a stop hook to end and restart each iteration—but the conversation history tags along for the ride.

And that’s where everything quietly falls apart.

Here’s what this actually looks like in practice:

Imagine you’re setting out on a multi-day hiking trip. Every morning, you pack your backpack for that day’s trail.

Now imagine that instead of emptying your pack each night, you just… keep adding to it. Day one’s water bottles. Day two’s snacks. Day three’s rain gear (even though it’s sunny now). By day five, you’re hauling 40 pounds of stuff you don’t need, and you can barely focus on the trail in front of you.

That’s context rot.

It happens when an AI model’s performance degrades because its context window gets bloated with accumulated information from previous tasks. The more history your agent carries forward, the harder it becomes for the model to stay sharp on what actually matters right now.

👉 The takeaway: Fresh context isn’t a nice-to-have. It’s the whole point.

.

.

.

What Context Rot Actually Looks Like

Let me make this concrete with Claude Code testing:

Iteration 1: Claude runs test TC-001. Context is clean. Performance is sharp. The backpack is light.

Iteration 5: Claude runs test TC-005. But it’s also dragging along memories of TC-001 through TC-004. The pack is getting heavy.

Iteration 15: Claude runs test TC-015. The model is now swimming through accumulated history, trying to find what actually matters among all the gear from previous days.

Iteration 25: Claude runs test TC-025. Performance has degraded. The model makes weird mistakes. It forgets what it was supposed to verify—because it’s exhausted from carrying everyone else’s context.

Same trail. Same agent. Completely different performance.

And here’s the frustrating part: you might not even notice it happening. The tests still run. They just run… worse. Slower. Less reliably. With occasional bizarre failures that make you question your own test plan.

.

.

.

The Solution That Was Already There

So I went looking for a better approach to Claude Code testing—something that would give me the clean-slate benefits of a proper Ralph loop without the context accumulation problem.

And I found it in a tool I’d been using for something else entirely: Claude Code’s task management system.

Here’s where it gets interesting.

The task management system gives you the same effect as a properly implemented Ralph loop—but with something the Ralph loop never had: dependency management.

Think back to the hiking metaphor.

Each sub-agent is like a fresh hiker starting a new day with an empty pack. They get their assignment, they complete their section of trail, they report back. Then the next hiker takes over with their own empty pack.

• No accumulated gear.
• No context rot.
• No performance degradation over time.

But here’s the bonus: the task management system also handles situations where “Day 3’s trail can’t start until Day 2’s bridge gets built.” Dependencies get tracked automatically. Tests that need prerequisites don’t run until those prerequisites pass.

(Is that two features in one? Well, is a package of two Reese’s Peanut Butter Cups two candy bars? I say it counts as one delicious solution.)

.

.

.

How Claude Code Testing Actually Works With Task Management

Let me show you exactly how to set this up.

Fair warning: there are a lot of screenshots coming. But I promise each one shows something important about the workflow.

Step 1: Put the Prompt as a Command

First, store the entire testing prompt as a command file. This makes triggering your Claude Code testing workflow trivially easy—just a slash command away.

The full prompt (I’ll include it at the end—it’s long but worth having) tells Claude exactly how to read your test plan, create tasks, set dependencies, execute tests sequentially, and track results.

Step 2: Trigger the Command

With the command saved, execution is just:

That’s it. Type /run_test_plan and let the system take over.

Step 3: Claude Reads Your Specs

Since we’re starting fresh—no memory of previous execution—Claude first reads your original specs, test plan, and implementation plan to understand the context.

(Remember: empty backpack. The agent needs to load up on just what it needs for this journey.)

Step 4: Claude Creates the Tasks

After understanding the context, Claude creates one task per test case. Watch how it automatically detects dependencies:

See that dependency analysis?

• TC-004, TC-005, TC-006, TC-008 depend on TC-003 (password field must exist first)
• TC-016, TC-017 depend on TC-014 (categories must exist first)
• TC-019 through TC-023 depend on TC-018 (priority dropdown must exist first)
• TC-029 depends on TC-027 (accent color must be saved first)

The system figured this out by reading the test plan. No manual configuration required.

Step 5: Dependencies Get Locked In

All 30 tasks created.

Now Claude sets up the dependencies and verifies everything:

Step 6: Test Status File Created

Claude creates a test-status.json file to track everything—machine-readable, resumable, and audit-friendly:

The execution order is now crystal clear:

1. Unblocked tasks first: TC-001, TC-002, TC-003, TC-007, TC-009, TC-010, TC-011, TC-012, TC-013, TC-014, TC-015, TC-018, TC-024
2. Tasks blocked by TC-003: TC-004, TC-005, TC-006, TC-008
3. Tasks blocked by TC-014: TC-016, TC-017
4. Tasks blocked by TC-018: TC-019, TC-020, TC-021, TC-022, TC-023
5. Tasks blocked by TC-027: TC-029

Step 7: First Task Begins

Here’s where the magic happens.

Claude spawns a sub-agent—with fresh context—to execute TC-001:

“You are a test execution sub-agent. You have ONE job: execute and verify ONE test case.”

That’s the key instruction. Fresh hiker. Empty backpack. Single trail.

Step 8: Browser Automation for Testing

The sub-agent uses Claude Code’s browser automation to test like a real user would:

It navigates to URLs, clicks buttons, fills forms, takes screenshots at verification points, and checks the DOM state against expected outcomes.

Real browser. Real interactions. Real Claude Code testing.

Step 9: Test Status Gets Updated

After completing a test, the sub-agent updates the status file:

Step 10: Human-Readable Results Too

The results also get appended to a markdown log for human review:

Every test gets logged in two places:

• test-status.json for machine parsing
• test-results.md for human review

(Because sometimes you want to query the data programmatically, and sometimes you just want to read what happened over coffee. Both are valid.)

Step 11: Automatic Progression to Next Task

Once TC-001 completes, Claude automatically moves to TC-002:

Look at those stats: 36 tool uses, 48.1k tokens, 4 minutes 19 seconds for TC-001.

Then a completely fresh sub-agent spawns for TC-002. New hiker. New backpack. No accumulated context from TC-001.

Step 12: Bugs Found? Claude Fixes Them.

TC-002 found a bug. Here’s what happened:

“TC-002 passed after 1 fix (Quick Setup wasn’t saving color options — now fixed in WizardAjax.php).”

The sub-agent detected the failure, analyzed the root cause, implemented a fix, and re-ran the test. All autonomously. All within the same fresh context.

Step 13: Dependencies Unlock Automatically

Now watch the dependency system in action.

Once TC-003 passes:

“TC-003 passed. Now TC-004, TC-005, TC-006, TC-008 are unblocked.”

The password field exists now. All the tests that depend on it can finally run.

👉 This is why dependencies matter: They prevent tests from running before their preconditions are met—avoiding the exact conflicts where one agent messes with something another agent needs.

Steps 14-15: The Marathon Continues

It keeps going. Test after test. Each sub-agent fresh and focused:

Every test runs sequentially. Every sub-agent gets clean context. Every dependency is respected. No context rot in sight.

Step 16: All Tests Complete

After 2 hours and 12 minutes:

30 tests. All passed. Zero known issues.

Step 17: The Full Summary

The orchestrator writes a comprehensive summary:

Here’s what got verified:

• All 6 Critical tests passed (password handling, priority validation, accent color persistence)
• Server-side validation confirmed working (urgent priority rejected, invalid hex rejected, password never stored in wp_options)
• UI behaviors verified (notice dismiss, auto-hide, field error clearing, color sync)
• Accessibility attributes verified on priority dropdown

And that bug that got fixed? handleQuickSetup() in WizardAjax.php wasn’t saving desq_primary_color or desq_accent_color options. Found during TC-002. Fixed autonomously.

.

.

.

Why This Actually Works Better

Let me be direct about the comparison:

The Ralph loop was supposed to start each iteration with a clean slate. The task management system actually delivers on that promise—and adds dependency management that prevents tests from stepping on each other.

.

.

.

The Full Prompt (Copy This)

Here’s the complete command file to drop into .claude/commands/run_test_plan.md:

We are executing the test plan. All implementation is complete. Now we verify it works.

## Reference Documents

- **Test Plan:** `notes/test_plan.md`
- **Implementation Plan:** `notes/impl_plan.md`
- **Specs:** `notes/specs.md`
- **Test Status JSON:** `notes/test-status.json`
- **Test Results Log:** `notes/test-results.md`

---

## Phase 1: Initialize

### Step 1: Check for Existing Run (Resumption)

Before creating anything, check if a previous test run exists:

1. Check if `notes/test-status.json` exists
2. Check if there are existing tasks via `TaskList`

**If both exist and tasks have results:**
- This is a **resumed run** — skip to Phase 2 (Step 7)
- Announce: "Resuming previous test run. Skipping already-passed tests."
- Only execute tasks that are still `pending` or `fail` (with fixAttempts < 3)

**If no previous run exists (or files are missing):**
- Continue with fresh initialization below

### Step 2: Read the Test Plan

Read `notes/test_plan.md` and extract ALL test cases. Auto-detect the TC-ID pattern used (e.g., `TC-001`, `TC-101`, `TC-5A`, etc.).

For each test case, note:

- TC ID
- Name
- Priority (Critical / High / Medium / Low — default to Medium if not stated)
- Preconditions
- Test steps and expected outcomes
- Test data (if any)
- Dependencies on other test cases (if any)

### Step 3: Analyze Test Dependencies

Determine which test cases depend on others. Common dependency patterns:

- A "saves data" test may depend on a "displays default" test
- A "form submission" test may depend on "form validation" tests
- An "end-to-end" test may depend on individual component tests

If no clear dependencies exist between test cases, treat them all as independent.

### Step 4: Create Tasks

Use `TaskCreate` to create one task per test case. Set `blocked_by` based on the dependency analysis.

**Task description format:**

```
Test [TC-ID]: [Test Name]
Priority: [Priority]

Preconditions:
- [Required state before test]

Steps:
| Step | Action | Expected Result |
|------|--------|-----------------|
| 1 | [Action] | [Result] |
| 2 | [Action] | [Result] |

Test Data:
- [Field]: [Value]

Expected Outcome: [Final verification]

Environment:
- Refer to CLAUDE.md for wp-env details, URLs, and credentials
- WordPress site: http://localhost:8105
- Admin: http://localhost:8105/wp-admin (admin/password)

---
fixAttempts: 0
result: pending
lastTestedAt: null
notes:
```

### Step 5: Generate Test Status JSON

Create `notes/test-status.json`:

```json
{
    "metadata": {
        "testPlanSource": "notes/test_plan.md",
        "totalIterations": 0,
        "maxIterations": 50,
        "startedAt": null,
        "lastUpdatedAt": null,
        "summary": {
            "total": "<count>",
            "pending": "<count>",
            "pass": 0,
            "fail": 0,
            "knownIssue": 0
        }
    },
    "testCases": {
        "<TC-ID>": {
            "name": "Test case name",
            "priority": "Critical|High|Medium|Low",
            "status": "pending",
            "fixAttempts": 0,
            "notes": "",
            "lastTestedAt": null
        }
    },
    "knownIssues": []
}
```

### Step 6: Initialize Test Results Log

Create `notes/test-results.md`:

```markdown
# Test Results

**Test Plan:** notes/test_plan.md
**Started:** [CURRENT_TIMESTAMP]

## Execution Log
```

### Verify Initialization

Use `TaskList` to confirm:
- All TC-IDs from the test plan have a corresponding task
- Dependencies are correctly set via `blocked_by`
- All tasks show `result: pending`

Cross-check task count matches `summary.total` in `notes/test-status.json`.

---

## Phase 2: Execute Tests

### Step 7: Determine Execution Order

Use `TaskList` to read all tasks and their `blocked_by` fields. Determine sequential execution order:

1. Tasks with no `blocked_by` (or all dependencies resolved) come first
2. Tasks whose dependencies are resolved come next
3. Continue until all tasks are ordered

**For resumed runs:** Skip tasks where `result` is already `pass` or `known_issue`.

### Step 8: Execute One Task at a Time

For the next eligible task, spawn ONE sub-agent with the instructions below.

**One sub-agent at a time. Do NOT spawn multiple sub-agents in parallel.**

---

#### Sub-Agent Instructions

**You are a test execution sub-agent. You have ONE job: execute and verify ONE test case.**

1. **Read your task** using `TaskGet` to get the full description
2. **Parse the test steps** from the description (everything above the `---` separator)
3. **Parse the metadata** from below the `---` separator
4. **Read CLAUDE.md** for environment details, URLs, and credentials

5. **Execute the test:**

    Using browser automation:
    - Navigate to URLs specified in the test steps
    - Click buttons/links as described
    - Fill form inputs with the test data provided
    - Take screenshots at key verification points
    - Read console logs for errors
    - Verify DOM state matches expected outcomes

    Follow the test plan steps EXACTLY. Do not skip steps.

6. **Determine the result:**

    **PASS** if:
    - All expected outcomes verified
    - No unexpected console errors
    - UI state matches test plan

    **FAIL** if:
    - Any expected outcome not met
    - Unexpected errors
    - UI state doesn't match

7. **If PASS:** Update the task description metadata via `TaskUpdate`:

    ```
    ---
    fixAttempts: 0
    result: pass
    lastTestedAt: [CURRENT_TIMESTAMP]
    notes: [Brief description of what was verified]
    ```

    Mark the task as `completed`.

8. **If FAIL and fixAttempts < 3:**

    a. Analyze the root cause
    b. Implement a fix in the codebase
    c. Increment fixAttempts and update via `TaskUpdate`:

    ```
    ---
    fixAttempts: [previous + 1]
    result: fail
    lastTestedAt: [CURRENT_TIMESTAMP]
    notes: [What failed, root cause, what fix was applied]
    ```

    d. Re-run the test steps to verify the fix
    e. If now passing, set `result: pass` and mark task as `completed`
    f. If still failing and fixAttempts < 3, repeat from (a)

9. **If FAIL and fixAttempts >= 3:** Mark as known issue via `TaskUpdate`:

    ```
    ---
    fixAttempts: 3
    result: known_issue
    lastTestedAt: [CURRENT_TIMESTAMP]
    notes: KI — [Description of the issue, steps to reproduce, severity, suggested fix]
    ```

    Mark the task as `completed`.

10. **Update Test Status JSON** — Read `notes/test-status.json`, update the test case entry and recalculate summary counts, then write back:

    - Set `status` to `pass`, `fail`, or `known_issue`
    - Update `fixAttempts`, `notes`, `lastTestedAt`
    - Increment `metadata.totalIterations`
    - Update `metadata.lastUpdatedAt`
    - Recalculate `metadata.summary` counts
    - If known_issue, add entry to `knownIssues` array

11. **Append to test results log** (`notes/test-results.md`):

    ```markdown
    ## [TC-ID] — [Test Name]

    **Result:** PASS | FAIL | KNOWN ISSUE
    **Tested At:** [TIMESTAMP]
    **Fix Attempts:** [N]

    **What happened:**
    [Brief description of test execution]

    **Notes:**
    [Observations, errors, or fixes attempted]

    ---
    ```

**CRITICAL: Before finishing, verify you have updated ALL THREE locations:**

1. Task description (metadata below `---` separator) via `TaskUpdate`
2. `notes/test-status.json` (test case entry + summary counts)
3. `notes/test-results.md` (appended human-readable entry)

Missing ANY of these = incomplete iteration.

---

### Step 9: Verify and Continue

After each sub-agent finishes, the orchestrator:

1. Uses `TaskGet` to verify the task description metadata was updated
2. Reads `notes/test-status.json` to confirm JSON was updated and summary counts are correct
3. Reads `notes/test-results.md` to confirm a new entry was appended
4. **If any location was NOT updated**, update it before proceeding
5. Determines the next eligible task (unresolved, dependencies met)
6. Spawns the next sub-agent (back to Step 8)

### Step 10: Repeat Until All Resolved

Continue until ALL tasks have `result: pass` or `result: known_issue`.

```
Completion check:
  - result: pass         → resolved
  - result: known_issue  → resolved
  - result: fail         → needs re-test (if fixAttempts < 3)
  - result: pending      → not yet tested

ALL resolved? → Phase 3 (Summary)
Otherwise?    → Next task
```

---

## Phase 3: Summary

### Step 11: Generate Final Summary

When all tasks are resolved, append a final summary to `notes/test-results.md`:

```markdown
# Final Summary

**Completed:** [TIMESTAMP]
**Total Test Cases:** [N]
**Passed:** [N]
**Known Issues:** [N]

## Results

| TC | Name | Priority | Result | Fix Attempts |
|----|------|----------|--------|--------------|
| TC-XXX | [Name] | High | PASS | 0 |
| TC-YYY | [Name] | Medium | KNOWN ISSUE | 3 |

## Known Issues Detail

### KI-001: [TC-ID] — [Issue Title]

**Severity:** [low|medium|high|critical]
**Steps to Reproduce:** [How to see the bug]
**Suggested Fix:** [Potential solution if known]

## Recommendations

[Any follow-up actions needed]
```

---

## Rules Summary

| Rule | Description |
|------|-------------|
| 1:1 Mapping | One task per test case — no grouping |
| Dependencies | Use `blocked_by` to enforce test execution order |
| Sequential | One sub-agent at a time — do NOT spawn multiple in parallel |
| Sub-Agents | One sub-agent per task — fresh context, focused execution |
| Max 3 Attempts | After 3 fix attempts → mark as `known_issue` |
| Metadata in Description | Track `fixAttempts`, `result`, `lastTestedAt`, `notes` below `---` separator |
| Test Status JSON | Always update `notes/test-status.json` after each test |
| Log Everything | Append results to `notes/test-results.md` for human review |
| Resumable | Detect existing run state and continue from where it left off |
| Completion | All tasks resolved = all results are `pass` or `known_issue` |

## Do NOT

- Spawn multiple sub-agents in parallel — execute ONE at a time
- Leave tasks in `fail` state without either retrying or escalating to `known_issue`
- Modify test plan steps — execute them exactly as written
- Forget to update `notes/test-status.json` after each test
- Forget to append to the test results log after each test
- Skip the dependency analysis
- Use `alert()` or `confirm()` in any fix (see CLAUDE.md)

We are executing the test plan. All implementation is complete. Now we verify it works.

## Reference Documents

- **Test Plan:** `notes/test_plan.md`
- **Implementation Plan:** `notes/impl_plan.md`
- **Specs:** `notes/specs.md`
- **Test Status JSON:** `notes/test-status.json`
- **Test Results Log:** `notes/test-results.md`

---

## Phase 1: Initialize

### Step 1: Check for Existing Run (Resumption)

Before creating anything, check if a previous test run exists:

1. Check if `notes/test-status.json` exists
2. Check if there are existing tasks via `TaskList`

**If both exist and tasks have results:**
- This is a **resumed run** — skip to Phase 2 (Step 7)
- Announce: "Resuming previous test run. Skipping already-passed tests."
- Only execute tasks that are still `pending` or `fail` (with fixAttempts < 3)

**If no previous run exists (or files are missing):**
- Continue with fresh initialization below

### Step 2: Read the Test Plan

Read `notes/test_plan.md` and extract ALL test cases. Auto-detect the TC-ID pattern used (e.g., `TC-001`, `TC-101`, `TC-5A`, etc.).

For each test case, note:

- TC ID
- Name
- Priority (Critical / High / Medium / Low — default to Medium if not stated)
- Preconditions
- Test steps and expected outcomes
- Test data (if any)
- Dependencies on other test cases (if any)

### Step 3: Analyze Test Dependencies

Determine which test cases depend on others. Common dependency patterns:

- A "saves data" test may depend on a "displays default" test
- A "form submission" test may depend on "form validation" tests
- An "end-to-end" test may depend on individual component tests

If no clear dependencies exist between test cases, treat them all as independent.

### Step 4: Create Tasks

Use `TaskCreate` to create one task per test case. Set `blocked_by` based on the dependency analysis.

**Task description format:**

```
Test [TC-ID]: [Test Name]
Priority: [Priority]

Preconditions:
- [Required state before test]

Steps:
| Step | Action | Expected Result |
|------|--------|-----------------|
| 1 | [Action] | [Result] |
| 2 | [Action] | [Result] |

Test Data:
- [Field]: [Value]

Expected Outcome: [Final verification]

Environment:
- Refer to CLAUDE.md for wp-env details, URLs, and credentials
- WordPress site: http://localhost:8105
- Admin: http://localhost:8105/wp-admin (admin/password)

---
fixAttempts: 0
result: pending
lastTestedAt: null
notes:
```

### Step 5: Generate Test Status JSON

Create `notes/test-status.json`:

```json
{
    "metadata": {
        "testPlanSource": "notes/test_plan.md",
        "totalIterations": 0,
        "maxIterations": 50,
        "startedAt": null,
        "lastUpdatedAt": null,
        "summary": {
            "total": "<count>",
            "pending": "<count>",
            "pass": 0,
            "fail": 0,
            "knownIssue": 0
        }
    },
    "testCases": {
        "<TC-ID>": {
            "name": "Test case name",
            "priority": "Critical|High|Medium|Low",
            "status": "pending",
            "fixAttempts": 0,
            "notes": "",
            "lastTestedAt": null
        }
    },
    "knownIssues": []
}
```

### Step 6: Initialize Test Results Log

Create `notes/test-results.md`:

```markdown
# Test Results

**Test Plan:** notes/test_plan.md
**Started:** [CURRENT_TIMESTAMP]

## Execution Log
```

### Verify Initialization

Use `TaskList` to confirm:
- All TC-IDs from the test plan have a corresponding task
- Dependencies are correctly set via `blocked_by`
- All tasks show `result: pending`

Cross-check task count matches `summary.total` in `notes/test-status.json`.

---

## Phase 2: Execute Tests

### Step 7: Determine Execution Order

Use `TaskList` to read all tasks and their `blocked_by` fields. Determine sequential execution order:

1. Tasks with no `blocked_by` (or all dependencies resolved) come first
2. Tasks whose dependencies are resolved come next
3. Continue until all tasks are ordered

**For resumed runs:** Skip tasks where `result` is already `pass` or `known_issue`.

### Step 8: Execute One Task at a Time

For the next eligible task, spawn ONE sub-agent with the instructions below.

**One sub-agent at a time. Do NOT spawn multiple sub-agents in parallel.**

---

#### Sub-Agent Instructions

**You are a test execution sub-agent. You have ONE job: execute and verify ONE test case.**

1. **Read your task** using `TaskGet` to get the full description
2. **Parse the test steps** from the description (everything above the `---` separator)
3. **Parse the metadata** from below the `---` separator
4. **Read CLAUDE.md** for environment details, URLs, and credentials

5. **Execute the test:**

    Using browser automation:
    - Navigate to URLs specified in the test steps
    - Click buttons/links as described
    - Fill form inputs with the test data provided
    - Take screenshots at key verification points
    - Read console logs for errors
    - Verify DOM state matches expected outcomes

    Follow the test plan steps EXACTLY. Do not skip steps.

6. **Determine the result:**

    **PASS** if:
    - All expected outcomes verified
    - No unexpected console errors
    - UI state matches test plan

    **FAIL** if:
    - Any expected outcome not met
    - Unexpected errors
    - UI state doesn't match

7. **If PASS:** Update the task description metadata via `TaskUpdate`:

    ```
    ---
    fixAttempts: 0
    result: pass
    lastTestedAt: [CURRENT_TIMESTAMP]
    notes: [Brief description of what was verified]
    ```

    Mark the task as `completed`.

8. **If FAIL and fixAttempts < 3:**

    a. Analyze the root cause
    b. Implement a fix in the codebase
    c. Increment fixAttempts and update via `TaskUpdate`:

    ```
    ---
    fixAttempts: [previous + 1]
    result: fail
    lastTestedAt: [CURRENT_TIMESTAMP]
    notes: [What failed, root cause, what fix was applied]
    ```

    d. Re-run the test steps to verify the fix
    e. If now passing, set `result: pass` and mark task as `completed`
    f. If still failing and fixAttempts < 3, repeat from (a)

9. **If FAIL and fixAttempts >= 3:** Mark as known issue via `TaskUpdate`:

    ```
    ---
    fixAttempts: 3
    result: known_issue
    lastTestedAt: [CURRENT_TIMESTAMP]
    notes: KI — [Description of the issue, steps to reproduce, severity, suggested fix]
    ```

    Mark the task as `completed`.

10. **Update Test Status JSON** — Read `notes/test-status.json`, update the test case entry and recalculate summary counts, then write back:

    - Set `status` to `pass`, `fail`, or `known_issue`
    - Update `fixAttempts`, `notes`, `lastTestedAt`
    - Increment `metadata.totalIterations`
    - Update `metadata.lastUpdatedAt`
    - Recalculate `metadata.summary` counts
    - If known_issue, add entry to `knownIssues` array

11. **Append to test results log** (`notes/test-results.md`):

    ```markdown
    ## [TC-ID] — [Test Name]

    **Result:** PASS | FAIL | KNOWN ISSUE
    **Tested At:** [TIMESTAMP]
    **Fix Attempts:** [N]

    **What happened:**
    [Brief description of test execution]

    **Notes:**
    [Observations, errors, or fixes attempted]

    ---
    ```

**CRITICAL: Before finishing, verify you have updated ALL THREE locations:**

1. Task description (metadata below `---` separator) via `TaskUpdate`
2. `notes/test-status.json` (test case entry + summary counts)
3. `notes/test-results.md` (appended human-readable entry)

Missing ANY of these = incomplete iteration.

---

### Step 9: Verify and Continue

After each sub-agent finishes, the orchestrator:

1. Uses `TaskGet` to verify the task description metadata was updated
2. Reads `notes/test-status.json` to confirm JSON was updated and summary counts are correct
3. Reads `notes/test-results.md` to confirm a new entry was appended
4. **If any location was NOT updated**, update it before proceeding
5. Determines the next eligible task (unresolved, dependencies met)
6. Spawns the next sub-agent (back to Step 8)

### Step 10: Repeat Until All Resolved

Continue until ALL tasks have `result: pass` or `result: known_issue`.

```
Completion check:
  - result: pass         → resolved
  - result: known_issue  → resolved
  - result: fail         → needs re-test (if fixAttempts < 3)
  - result: pending      → not yet tested

ALL resolved? → Phase 3 (Summary)
Otherwise?    → Next task
```

---

## Phase 3: Summary

### Step 11: Generate Final Summary

When all tasks are resolved, append a final summary to `notes/test-results.md`:

```markdown
# Final Summary

**Completed:** [TIMESTAMP]
**Total Test Cases:** [N]
**Passed:** [N]
**Known Issues:** [N]

## Results

| TC | Name | Priority | Result | Fix Attempts |
|----|------|----------|--------|--------------|
| TC-XXX | [Name] | High | PASS | 0 |
| TC-YYY | [Name] | Medium | KNOWN ISSUE | 3 |

## Known Issues Detail

### KI-001: [TC-ID] — [Issue Title]

**Severity:** [low|medium|high|critical]
**Steps to Reproduce:** [How to see the bug]
**Suggested Fix:** [Potential solution if known]

## Recommendations

[Any follow-up actions needed]
```

---

## Rules Summary

| Rule | Description |
|------|-------------|
| 1:1 Mapping | One task per test case — no grouping |
| Dependencies | Use `blocked_by` to enforce test execution order |
| Sequential | One sub-agent at a time — do NOT spawn multiple in parallel |
| Sub-Agents | One sub-agent per task — fresh context, focused execution |
| Max 3 Attempts | After 3 fix attempts → mark as `known_issue` |
| Metadata in Description | Track `fixAttempts`, `result`, `lastTestedAt`, `notes` below `---` separator |
| Test Status JSON | Always update `notes/test-status.json` after each test |
| Log Everything | Append results to `notes/test-results.md` for human review |
| Resumable | Detect existing run state and continue from where it left off |
| Completion | All tasks resolved = all results are `pass` or `known_issue` |

## Do NOT

- Spawn multiple sub-agents in parallel — execute ONE at a time
- Leave tasks in `fail` state without either retrying or escalating to `known_issue`
- Modify test plan steps — execute them exactly as written
- Forget to update `notes/test-status.json` after each test
- Forget to append to the test results log after each test
- Skip the dependency analysis
- Use `alert()` or `confirm()` in any fix (see CLAUDE.md)

.

.

.

Your Turn

If you’ve been frustrated with AI-generated code that “works” but doesn’t actually work, give this a shot.

Define your success criteria upfront with a solid test plan. Let Claude Code testing handle the execution and verification through task management. Walk away while it iterates.

The test-fix-retest loop is boring. Tedious. The kind of thing every developer has always done manually.

Now you don’t have to.

What feature are you going to test with this workflow?

Set it up. Let it run. Come back to green checkmarks.

(And maybe grab a coffee while you wait. Your backpack is empty now—you’ve earned the rest.)

Last week, I showed you my Claude Code implementation workflow.

52 minutes. 13 tasks. 38 test cases worth of functionality. All built by sub-agents running in parallel.

Here’s what I didn’t tell you.

Half of it didn’t work.

(I know. I KNOW.)

.

.

.

The Part Where I Discover My “Complete” Implementation Is… Not

Let me show you what happened when I actually tested the WooCommerce integration Claude built for me.

Quick context: I have a WordPress theme for coworking spaces. Originally, it used direct Stripe integration for payments. But here’s the thing—not everyone wants Stripe. Some coworking spaces prefer PayPal. Others need local payment gateways. (And some, bless their hearts, are still figuring out what a payment gateway even is.)

The solution? Let WooCommerce handle payments. Hundreds of gateway integrations, tax calculations, order management—all built-in.

Claude followed my implementation workflow perfectly.

PERFECTLY.

The settings page looked gorgeous:

There’s even a Product Sync panel showing 3 published plans synced to WooCommerce at 100% progress. One hundred percent!

My plans:

• Hot Desk ($199/month),
• Dedicated Desk ($399/month),
• Private Office ($799/month)

—all published and ready to go:

And look!

They synced perfectly to WooCommerce products:

Everything looked GREAT.

So I clicked “Get Started” on the Hot Desk plan to test the checkout flow. You know, like a responsible developer would do. (Stop laughing.)

And here’s what I saw:

The old Stripe checkout.

The direct integration I was trying to REPLACE.

I switched the payment mode to WooCommerce. I synced the products. Everything in the admin looked correct.

But the frontend? Still using the old Stripe integration.

Ferpetesake.

.

.

.

Why Claude Thinks “Done” When It’s Really “Done-ish”

Here’s where I went full detective mode.

I checked the codebase. The WooCommerce checkout code exists. Functions written. Hooks registered. File paths correct. All present and accounted for.

So why wasn’t it working?

The code was never connected to the rest of the system.

(Stay with me here.)

Claude wrote the WooCommerce checkout handler. Beautiful code. But the pricing page? Still calling the old Stripe checkout function. The new code sat there—perfectly written, completely unused—like a fancy espresso machine you forgot to plug in.

And here’s the thing: this happens ALL THE TIME with AI-generated code.

Claude writes features.

It creates files. It generates functions. And in its summary, it reports “Task complete.”

But “code exists” and “code works”?

Two very different things.

You’ve probably experienced this.

Claude builds a feature. You test it. Something’s broken. You point out the bug. Claude apologizes (so polite!), fixes that specific issue, and introduces two new ones.

The Reddit crowd calls this “nerfed” or “lazy.”

They’re wrong.

👉 Claude lacks visibility into whether its code actually runs correctly in your system.

It can’t see the browser. It can’t watch a user click through your checkout flow. It can’t verify that function A actually calls function B in production.

The fix? Give Claude the ability to test its own work.

(This is where it gets good.)

.

.

.

The Most Important Testing? Not What You Think

You might be thinking: “Just write unit tests. Problem solved.”

And look—unit tests help. Integration tests help more.

But here’s what nobody talks about:

Perfect code doesn’t mean a working product.

The WooCommerce checkout code passed every logical check. Functions syntactically correct. Hooks properly registered. A unit test would have given it a gold star and a pat on the head.

But the pricing page template still imported the old Stripe checkout URL.

That’s a wiring problem. Not a code problem.

The test that catches this? User acceptance testing.

Actual users (or something simulating actual users) verifying the end product meets their needs. Clicking buttons. Filling forms. Going through the whole dang flow.

This is exactly why my implementation workflow generates a test plan BEFORE the implementation plan. The test plan represents success criteria from the user’s perspective:

• Can a user switch payment modes?
• Does the checkout redirect to WooCommerce?
• Does the order confirmation show correct details?

These questions can’t be answered by reading code. They require clicking through the actual interface.

Which brings us to Ralph Loop.

.

.

.

Meet Ralph Loop: Your Autonomous Claude Code Testing Loop

Here’s the workflow I use to make Claude test its own work:

This is an autonomous loop that picks up a test case, executes it in an actual browser, checks against acceptance criteria, logs results, and repeats. If a test fails? Claude fixes the code and retests.

(Yes, really. It fixes its own bugs. I’ll show you.)

The idea comes from Ryan Carson’s video “Ralph Wiggum” AI Agent will 10x Claude Code/Amp.

The core insight: you can’t throw a vague prompt at an autonomous loop and expect magic. The loop needs structure.

Specifically, it needs:

• A test plan defining every test case upfront
• A status.json tracking pass/fail for each case
• A results.md where Claude logs learnings after each iteration

Let me show you exactly how I set this up for Claude Code testing.

.

.

.

1. Create the Ralph Test Folder

First, create a folder to store all your Ralph loop files:

Four files. That’s it.

• prepare.md — Instructions for generating the status.json from your test plan
• prompt.md — The loop instructions Claude follows each iteration
• status.json — Tracks the state of all test cases (starts empty)
• results.md — Human-readable log of each iteration (starts empty)

2. The Prepare Prompt

The prepare prompt tells Claude how to read your test plan and initialize the status file:

Read the test plan file and generate a `status.json` file with all test cases initialized.

## Input

- **Test Plan:** `notes/test_plan.md`

## Output

- **Status File:** `notes/ralph_test/status.json`

## Instructions

1. Read the test plan markdown file
2. Extract ALL test cases (format: TC-XXX)
3. For each test case, extract:
    - TC ID (e.g., "TC-501")
    - Name (the test case title after the TC ID)
    - Priority (Critical/High/Medium/Low)
4. Generate a JSON file with this exact structure:

```json
{
  "metadata": {
    "testPlanSource": "notes/test_plan.md",
    "totalIterations": 0,
    "maxIterations": 50,
    "startedAt": null,
    "lastUpdatedAt": null,
    "summary": {
      "total": <count>,
      "pending": <count>,
      "pass": 0,
      "fail": 0,
      "knownIssue": 0
    }
  },
  "testCases": {
    "TC-XXX": {
      "name": "Test case name from plan",
      "priority": "Critical|High|Medium|Low",
      "status": "pending",
      "fixAttempts": 0,
      "notes": "",
      "lastTestedAt": null
    }
  },
  "knownIssues": []
}
```

````

5. Save the file to the output path

## Extraction Rules

- Test case IDs follow pattern: `TC-NNN` (e.g., TC-501, TC-522)
- Test case names are in headers like: `#### TC-501: Checkout Header Display`
- Priority is usually listed in the test case details or status tracker table
- If priority not found, default to "Medium"

## Example

Input (from test plan):

```markdown
#### TC-501: Checkout Header Display

**Priority:** High
...

#### TC-502: Checkout Elements - Step Progress Display

**Priority:** High
...
```

Output (status.json):

```json
{
    "metadata": {
        "testPlanSource": "./docs/test-plan.md",
        "totalIterations": 0,
        "maxIterations": 50,
        "startedAt": null,
        "lastUpdatedAt": null,
        "summary": {
            "total": 2,
            "pending": 2,
            "pass": 0,
            "fail": 0,
            "knownIssue": 0
        }
    },
    "testCases": {
        "TC-501": {
            "name": "Checkout Header Display",
            "priority": "High",
            "status": "pending",
            "fixAttempts": 0,
            "notes": "",
            "lastTestedAt": null
        },
        "TC-502": {
            "name": "Checkout Elements - Step Progress Display",
            "priority": "High",
            "status": "pending",
            "fixAttempts": 0,
            "notes": "",
            "lastTestedAt": null
        }
    },
    "knownIssues": []
}
```

## Validation

After generating, verify:

- [ ] All TC-XXX IDs from the test plan are included
- [ ] No duplicate TC IDs
- [ ] Summary.total matches count of testCases
- [ ] JSON is valid (no syntax errors)
- [ ] File saved to correct path
````

Read the test plan file and generate a `status.json` file with all test cases initialized.

## Input

- **Test Plan:** `notes/test_plan.md`

## Output

- **Status File:** `notes/ralph_test/status.json`

## Instructions

1. Read the test plan markdown file
2. Extract ALL test cases (format: TC-XXX)
3. For each test case, extract:
    - TC ID (e.g., "TC-501")
    - Name (the test case title after the TC ID)
    - Priority (Critical/High/Medium/Low)
4. Generate a JSON file with this exact structure:

```json
{
  "metadata": {
    "testPlanSource": "notes/test_plan.md",
    "totalIterations": 0,
    "maxIterations": 50,
    "startedAt": null,
    "lastUpdatedAt": null,
    "summary": {
      "total": <count>,
      "pending": <count>,
      "pass": 0,
      "fail": 0,
      "knownIssue": 0
    }
  },
  "testCases": {
    "TC-XXX": {
      "name": "Test case name from plan",
      "priority": "Critical|High|Medium|Low",
      "status": "pending",
      "fixAttempts": 0,
      "notes": "",
      "lastTestedAt": null
    }
  },
  "knownIssues": []
}
```

````

5. Save the file to the output path

## Extraction Rules

- Test case IDs follow pattern: `TC-NNN` (e.g., TC-501, TC-522)
- Test case names are in headers like: `#### TC-501: Checkout Header Display`
- Priority is usually listed in the test case details or status tracker table
- If priority not found, default to "Medium"

## Example

Input (from test plan):

```markdown
#### TC-501: Checkout Header Display

**Priority:** High
...

#### TC-502: Checkout Elements - Step Progress Display

**Priority:** High
...
```

Output (status.json):

```json
{
    "metadata": {
        "testPlanSource": "./docs/test-plan.md",
        "totalIterations": 0,
        "maxIterations": 50,
        "startedAt": null,
        "lastUpdatedAt": null,
        "summary": {
            "total": 2,
            "pending": 2,
            "pass": 0,
            "fail": 0,
            "knownIssue": 0
        }
    },
    "testCases": {
        "TC-501": {
            "name": "Checkout Header Display",
            "priority": "High",
            "status": "pending",
            "fixAttempts": 0,
            "notes": "",
            "lastTestedAt": null
        },
        "TC-502": {
            "name": "Checkout Elements - Step Progress Display",
            "priority": "High",
            "status": "pending",
            "fixAttempts": 0,
            "notes": "",
            "lastTestedAt": null
        }
    },
    "knownIssues": []
}
```

## Validation

After generating, verify:

- [ ] All TC-XXX IDs from the test plan are included
- [ ] No duplicate TC IDs
- [ ] Summary.total matches count of testCases
- [ ] JSON is valid (no syntax errors)
- [ ] File saved to correct path
````

Key elements:

• Points to your test plan location (notes/test_plan.md)
• Specifies the output file (notes/ralph_test/status.json)
• Defines the JSON structure with metadata and test case tracking

Nothing fancy. Just clear instructions.

3. The Loop Prompt

The prompt.md file contains the instructions Claude follows every single iteration:

You are a testing agent in an iterative loop. Each iteration:

1. Read state from files
2. Pick ONE test case
3. Execute or fix it
4. Update state files
5. Check if done → output completion promise OR continue

**You have NO memory of previous iterations.** Files are your memory.

---

## Files to Read FIRST

| File                           | Purpose                                         |
| ------------------------------ | ----------------------------------------------- |
| `notes/ralph_test/status.json` | Current state of all test cases (JSON)          |
| `notes/test_plan.md`           | Full test plan with steps and expected outcomes |
| `notes/ralph_test/results.md`  | Human-readable log (append results here)        |

**Optional context:**

- `notes/impl_plan.md` — Implementation details
- `notes/specs.md` — Specifications details

---

## Environment

wp-env is running:

- Dev site: http://localhost:8101
- Test site: http://localhost:8102
- Admin: http://localhost:8101/wp-admin

Commands:

- Run inside sandbox: Standard commands
- Run outside sandbox: npm, docker, wp-env commands

## Test Credentials

### Admin

- URL: http://localhost:8101/wp-admin
- Username: admin
- Email: wordpress@example.com
- Password: password

### Reset Password (if needed)

```bash
wp user update admin --user_pass=password
```

---

## This Iteration

### Step 1: Read State

Read the test status JSON file. Understand:

- Which test cases exist
- Status of each: `pending`, `testing`, `pass`, `fail`, `known_issue`
- Fix attempts for failing tests

### Step 2: Check Completion

**If ALL test cases are `pass` or `known_issue`:**

Output completion promise and final summary:

<promise>ALL_TESTS_RESOLVED</promise>

Summary:

- Total passed: X
- Known issues: Y
- Recommendations: ...

**Otherwise, continue to Step 3.**

### Step 3: Pick ONE Test Case

Priority order:

1. `testing` — Continue mid-test
2. `fail` with `fixAttempts < 3` — Needs fix
3. `pending` — Fresh test

### Step 4: Execute Test

Using Chrome browser automation (natural language):

- Navigate to URLs
- Click buttons/links
- Fill form inputs
- Take screenshots
- Read console logs
- Verify DOM state

**Follow the test plan click-path EXACTLY.**

### Step 5: Record Result

Update test status JSON:

**PASS:**

```json
{ "status": "pass", "notes": "What was verified", "lastTestedAt": "ISO timestamp" }
```

**FAIL:**

```json
{ "status": "fail", "fixAttempts": <increment>, "notes": "What failed", "lastTestedAt": "ISO timestamp" }
```

Update `metadata.totalIterations` and `metadata.lastUpdatedAt`.

### Step 6: Handle Failures

**If FAIL and fixAttempts < 3:**

- Analyze root cause
- Implement fix in codebase
- Next iteration will re-test

**If FAIL and fixAttempts >= 3:**

- Set status to `known_issue`
- Add to `knownIssues` array with: id, description, steps, severity

### Step 7: Update Human Log

Append to test results markdown:

```markdown
## Iteration [N] — [TIMESTAMP]

**TC:** TC-XXX — [Name]
**Status:** ✅/❌/⚠️
**Notes:** [What happened]

---
```

### Step 8: Continue or Complete

- If all TCs resolved → Output `<promise>ALL_TESTS_RESOLVED</promise>`
- Otherwise → Continue working (loop will restart)

---

## Rules

1. ONE test case per iteration
2. Update files BEFORE finishing
3. Follow test steps EXACTLY
4. Screenshot key verification points
5. Max 3 fix attempts → then known_issue
6. Output promise ONLY when truly complete

You are a testing agent in an iterative loop. Each iteration:

1. Read state from files
2. Pick ONE test case
3. Execute or fix it
4. Update state files
5. Check if done → output completion promise OR continue

**You have NO memory of previous iterations.** Files are your memory.

---

## Files to Read FIRST

| File                           | Purpose                                         |
| ------------------------------ | ----------------------------------------------- |
| `notes/ralph_test/status.json` | Current state of all test cases (JSON)          |
| `notes/test_plan.md`           | Full test plan with steps and expected outcomes |
| `notes/ralph_test/results.md`  | Human-readable log (append results here)        |

**Optional context:**

- `notes/impl_plan.md` — Implementation details
- `notes/specs.md` — Specifications details

---

## Environment

wp-env is running:

- Dev site: http://localhost:8101
- Test site: http://localhost:8102
- Admin: http://localhost:8101/wp-admin

Commands:

- Run inside sandbox: Standard commands
- Run outside sandbox: npm, docker, wp-env commands

## Test Credentials

### Admin

- URL: http://localhost:8101/wp-admin
- Username: admin
- Email: wordpress@example.com
- Password: password

### Reset Password (if needed)

```bash
wp user update admin --user_pass=password
```

---

## This Iteration

### Step 1: Read State

Read the test status JSON file. Understand:

- Which test cases exist
- Status of each: `pending`, `testing`, `pass`, `fail`, `known_issue`
- Fix attempts for failing tests

### Step 2: Check Completion

**If ALL test cases are `pass` or `known_issue`:**

Output completion promise and final summary:

<promise>ALL_TESTS_RESOLVED</promise>

Summary:

- Total passed: X
- Known issues: Y
- Recommendations: ...

**Otherwise, continue to Step 3.**

### Step 3: Pick ONE Test Case

Priority order:

1. `testing` — Continue mid-test
2. `fail` with `fixAttempts < 3` — Needs fix
3. `pending` — Fresh test

### Step 4: Execute Test

Using Chrome browser automation (natural language):

- Navigate to URLs
- Click buttons/links
- Fill form inputs
- Take screenshots
- Read console logs
- Verify DOM state

**Follow the test plan click-path EXACTLY.**

### Step 5: Record Result

Update test status JSON:

**PASS:**

```json
{ "status": "pass", "notes": "What was verified", "lastTestedAt": "ISO timestamp" }
```

**FAIL:**

```json
{ "status": "fail", "fixAttempts": <increment>, "notes": "What failed", "lastTestedAt": "ISO timestamp" }
```

Update `metadata.totalIterations` and `metadata.lastUpdatedAt`.

### Step 6: Handle Failures

**If FAIL and fixAttempts < 3:**

- Analyze root cause
- Implement fix in codebase
- Next iteration will re-test

**If FAIL and fixAttempts >= 3:**

- Set status to `known_issue`
- Add to `knownIssues` array with: id, description, steps, severity

### Step 7: Update Human Log

Append to test results markdown:

```markdown
## Iteration [N] — [TIMESTAMP]

**TC:** TC-XXX — [Name]
**Status:** ✅/❌/⚠️
**Notes:** [What happened]

---
```

### Step 8: Continue or Complete

- If all TCs resolved → Output `<promise>ALL_TESTS_RESOLVED</promise>`
- Otherwise → Continue working (loop will restart)

---

## Rules

1. ONE test case per iteration
2. Update files BEFORE finishing
3. Follow test steps EXACTLY
4. Screenshot key verification points
5. Max 3 fix attempts → then known_issue
6. Output promise ONLY when truly complete

This is crucial for Claude Code testing to work properly.

Each iteration, Claude:

1. Reads status.json to understand current state
2. Picks the next pending test case
3. Executes the test in an actual browser
4. Updates status.json and results.md
5. Ends the iteration (which triggers the next loop)

Rinse. Repeat. Until done.

4. Initialize the Status File

Run the prepare prompt to generate your starting state:

Claude reads your test plan and creates status.json with all 38 test cases initialized:

The generated status file looks like this:

Every test case has:

• status: “pending”, “pass”, “fail”, or “knownIssue”
• fixAttempts: How many times Claude tried to fix this case
• notes: What Claude observed during testing
• lastTestedAt: Timestamp of the last test

All 38 tests. Ready to go. Pending status across the board.

.

.

.

5. Trigger the Ralph Loop

Now the magic happens.

Trigger the Ralph loop with this command:

/ralph-loop:ralph-loop "perform this: @notes/ralph_test/prompt.md" --completion-promise "ALL_TESTS_RESOLVED" --max-iterations 100

• The --completion-promise tells Ralph to keep looping until Claude outputs “ALL_TESTS_RESOLVED.”
• The --max-iterations prevents infinite loops. (Because nobody wants that.)

6. Watch Claude Test Its Own Work

Claude starts by reading the state files to understand the current status:

It picks TC-001: Display Payment Mode Settings.

Then it launches a browser—an actual browser!—navigates to the settings page, and verifies each requirement:

All checks pass. TC-001: PASS ✅

(Look at all those green checkmarks. Gorgeous.)

Claude updates the status file:

Then updates results.md with a human-readable log:

Notice the stop hook at the bottom: “Ralph iteration 2.”

The loop automatically triggers the next iteration.

No manual intervention.

No babysitting.

Just… Claude Code testing itself.

.

.

.

7. The Loop Continues (Without You)

Iteration 2 starts.

Claude reads the state (1 pass, 37 pending), picks TC-002:

TC-002 requires WooCommerce to be deactivated.

So what does Claude do? Runs wp plugin deactivate woocommerce, then tests the settings page behavior.

The test passes—the WooCommerce option correctly shows “Setup Required” when the plugin is inactive:

Claude reactivates WooCommerce and updates the status:

And appends to results.md:

Iteration 2 complete.

Stop hook triggers iteration 3:

This continues automatically. Test after test after test.

You could go make coffee. Take a walk. Do your taxes.

(Okay, maybe not taxes.)

.

.

.

8. When Tests Fail, Claude Fixes Them

HERE’S where Ralph Loop really shines.

During testing, Claude encounters a failing test. The pricing page isn’t displaying plan prices correctly.

Does it give up? Does it log “FAIL” and move on?

Nope.

Claude investigates, finds the issue—the template is using old meta keys instead of the Plan model—and fixes it:

Then Claude retests to verify the fix worked:

The pricing page now shows correct prices. Claude clicks “Get Started” to continue testing the checkout flow.

Test. Find bug. Fix bug. Retest. Confirm fix.

All automatic.

.

.

.

9. All Tests Pass

After 3 hours and 32 minutes, all 38 test cases resolve:

Summary of Test Results:

• Payment Mode Configuration: 5 tests ✅
• Product & Plan Sync: 2 tests ✅
• Checkout Flow: 6 tests ✅
• Subscription Lifecycle: 6 tests ✅
• Renewal Processing: 2 tests ✅
• Plan Changes: 6 tests ✅
• Cancellation: 2 tests ✅
• Member Portal: 4 tests ✅
• Admin Features: 2 tests ✅
• Emails: 2 tests ✅
• Security: 1 test ✅

Total: 38 tests. All passing.

The critical P0/P1 tests that Claude fixed during the loop:

• TC-004: Mode Switch Blocking ✅
• TC-009: Guest Checkout Prevention ✅ (with fix)
• TC-016: Race Condition Prevention ✅
• TC-018: Pre-Renewal Token Validation ✅
• TC-020: 3D Secure Handling ✅
• TC-038: Token Ownership Validation ✅

HECK YES.

.

.

.

The Proof: It Actually Works Now

Remember the checkout problem from the beginning? The one that made me question my life choices?

Let’s see what happens now.

The pricing page displays correctly:

Click “Get Started” on Hot Desk, and you’re redirected to the WooCommerce checkout:

See the difference?

This is the WooCommerce checkout page.

The order summary shows “Hot Desk” with “Billing Cycle: Monthly.” The account creation notice appears because subscriptions require accounts.

(This is the moment I did a small victory dance. Don’t judge.)

Scroll down to payment options—Stripe through WooCommerce:

The Stripe integration now runs through WooCommerce. Same payment processor, but managed by WooCommerce’s subscription system. I can swap in PayPal, Square, or any other gateway without touching theme code.

Complete the purchase, and you land on the welcome page:

Everything works.

The flow connects end-to-end.

The WooCommerce integration that Claude “completed” previously?

Now it’s actually complete.

.

.

.

The Complete Journey: From Idea to Working Product

Let me zoom out and show you how all three parts of this series connect:

Phase 1: Bulletproof Specs

We started by brainstorming comprehensive specifications.

Using the AskUserQuestion tool, Claude asked 12 clarifying questions covering everything from subscription handling to checkout experience to refund policies. Then Claude critiqued its own specs, finding 14 potential issues before we wrote any code.

Phase 2: Test Plan

Before implementation, we generated a test plan.

38 test cases defining exactly what success looks like—from a user’s perspective. These became our acceptance criteria.

Phase 3: Implementation Plan + Sub-Agents

We created an implementation plan mapping tasks to test cases. Then executed with sub-agents running in parallel waves, keeping context usage low while building everything in 52 minutes.

Phase 4: Claude Code Testing + Fixing with Ralph Loop

Finally, we let Ralph loose. The autonomous loop tested each case in an actual browser, found the bugs Claude missed during implementation, fixed them, and verified the fixes.

3 hours 32 minutes later: 38/38 tests passing.

.

.

.

What I’ve Learned About Building With AI

Here’s what this whole journey taught me.

We all want AI to one-shot solutions on the first try. To type a prompt, hit enter, and watch magic happen. And when it doesn’t work perfectly? We blame the AI. Call it nerfed. Call it lazy. Move on to the next shiny tool.

But here’s the thing I keep coming back to:

Even the most experienced developer can’t one-shot a complex feature.

We write code. Test it. Find bugs. Fix them. Test again. That’s just how building software works. Always has been. Probably always will be.

AI is no different.

The breakthrough—the real breakthrough—comes from giving AI the ability to verify its own work. The same way any developer does. Write the code. Test it against real user scenarios. See what breaks. Fix it. Test again.

Ralph Loop makes this autonomous.

You don’t have to manually test 38 scenarios. You don’t have to spot the bugs yourself. You don’t have to describe each fix.

You define success criteria upfront (test plan), give Claude the ability to test against those criteria (browser automation), and let it iterate until everything passes.

👉 That’s the entire secret: structured iteration with clear success criteria.

Not smarter prompts. Not better models. Not more tokens.

Just… iteration.

The same boring, unsexy process that’s always made software work.

Except now, you don’t have to do it yourself.

Here’s a thing that happened to me once.

I moved apartments.

Being the organized person I am, I created the most detailed inventory list you’ve ever seen. Every box labeled. Every item cataloged. “Kitchen – Plates (12), Bowls (8), That Weird Garlic Press I Never Use But Can’t Throw Away (1).”

I handed this masterpiece to the movers and said, “Here you go!”

They looked at me like I’d handed them a grocery list in Klingon.

Because here’s what my beautiful inventory didn’t tell them: Which boxes go to which rooms. What order to load things. Which items are fragile. What depends on what. The fact that the bookshelf needs to go in before the desk, or nothing fits.

They weren’t wrong to be confused. I’d given them a comprehensive what without any how.

This is exactly what happens when you hand Claude Code your bulletproof specs and say “implement this.”

.

.

.

The Gap Nobody Warns You About

Last week, we talked about creating bulletproof specs using the 3-phase method.

You followed the process. You answered every clarifying question. You had Claude critique its own work. Your specs are comprehensive—2,000+ lines of detailed requirements, edge cases, and architectural decisions.

Now you’re ready to build.

So you fire up Claude Code and type: “Read the specs and implement it.”

Claude starts working. Files appear. Code flows.

And thirty minutes later? Half your edge cases are missing. The checkout flow doesn’t match what you specified. That critical race condition prevention you spent three rounds of Q&A perfecting?

Nowhere to be found.

Here’s the thing: Comprehensive specs don’t automatically translate to comprehensive implementation.

Your specs might be 2,000 lines. Claude’s context window is limited. As implementation progresses, early requirements fade from memory. The AI starts making shortcuts. Details slip through the cracks like sand through fingers.

Sound familiar?

(If you’re nodding right now, stay with me.)

The issue isn’t Claude’s capability. It’s the gap between what’s documented and what gets built. Even human developers working from perfect documentation miss things. They get tired. They make assumptions. They interpret requirements their own way.

Claude faces the same challenges—plus context limits that force it to work with only a subset of information at any given moment.

👉 The solution isn’t better prompting. It’s better process.

And that process? It’s what I’ve been calling the Claude Code implementation workflow. Let me show you what I mean.

.

.

.

The Missing Middle Layer

Here’s what most people do:

I call this the “hope-based development methodology.”

(That’s a joke. Please don’t actually call it that.)

Here’s what actually works:

• The test plan answers: “How will we know if each requirement is implemented correctly?”
• The implementation plan answers: “What specific tasks need to happen, and in what order?”
• The task management answers: “How do we keep Claude focused and prevent context overload?”

Think of it like this: your specs are the inventory list. The test plan is the “here’s how we’ll know each box arrived safely” checklist. The implementation plan is the “which room, which order, what depends on what” instruction sheet.

The movers—er, Claude—can actually do their job now.

Let me walk you through exactly how this Claude Code implementation workflow… well, works.

.

.

.

Step 1: Create a Test Plan From Your Specs

Before writing any code, Claude needs to understand what success looks like.

Now, I know what you’re thinking: “Wait—isn’t a test plan for after implementation?”

Traditionally, yes. But for AI-driven development, creating the test plan first serves a completely different purpose.

👉 It forces Claude to deeply analyze every requirement and translate it into verifiable outcomes.

When Claude creates test cases for “handle race conditions during renewal processing,” it has to think through exactly what that means. What are the preconditions? What actions trigger the behavior? What should the expected results be?

It’s like asking someone to write the exam questions before teaching the class. Suddenly, they understand the material much more deeply.

Here’s the prompt I use:

Create a comprehensive test plan that will verify the implementation matches the specs at `notes/specs.md`

### Step 1: Identify Test Scenarios

Based on the specs:
- Happy path flows
- Error conditions
- Edge cases
- State transitions
- Responsive behavior
- Accessibility requirements

### Step 2: Create Test Cases

For each scenario, create detailed test cases:

```markdown
### TC-NNN: [Test Name]

**Description:** [What this test verifies]

**Preconditions:**
- [Required state before test]
- [Required data]

**Steps:**

| Step | Action | Expected Result |
|------|--------|-----------------|
| 1 | [Action to take] | [What should happen] |
| 2 | [Action to take] | [What should happen] |

**Test Data:**
- Field 1: `value`
- Field 2: `value`

**Expected Outcome:** [Final verification]

**Priority:** Critical / High / Medium / Low
````

### Step 3: Organize by Category

Group test cases:

- Functional tests
- UI/UX tests
- Validation tests
- Integration tests (if applicable)
- Edge case tests

### Step 4: Create Status Tracker

```markdown
## Status Tracker

| TC     | Test Case | Priority | Status | Remarks |
| ------ | --------- | -------- | ------ | ------- |
| TC-001 | [Name]    | High     | [ ]    |         |
| TC-002 | [Name]    | Medium   | [ ]    |         |
```

### Step 5: Add Known Issues Section

```markdown
## Known Issues

| Issue | Description | TC Affected | Steps to Reproduce | Severity |
| ----- | ----------- | ----------- | ------------------ | -------- |
|       |             |             |                    |          |
```

## Output

Save the test plan to: `notes/test_plan.md`

Include:

1. Overview and objectives
2. Prerequisites
3. Reference wireframe (if applicable)
4. Test cases (10-20 typically)
5. Status tracker
6. Known issues section

## Test Case Guidelines

- Each test should be independent
- Use specific, concrete test data
- Include both positive and negative tests
- Cover all screens from wireframe (if applicable)
- Test all states from prototype
- Consider mobile/responsive

## Do NOT

- Over-test obvious functionality
- Skip error handling tests
- Forget accessibility basics

Create a comprehensive test plan that will verify the implementation matches the specs at `notes/specs.md`

### Step 1: Identify Test Scenarios

Based on the specs:
- Happy path flows
- Error conditions
- Edge cases
- State transitions
- Responsive behavior
- Accessibility requirements

### Step 2: Create Test Cases

For each scenario, create detailed test cases:

```markdown
### TC-NNN: [Test Name]

**Description:** [What this test verifies]

**Preconditions:**
- [Required state before test]
- [Required data]

**Steps:**

| Step | Action | Expected Result |
|------|--------|-----------------|
| 1 | [Action to take] | [What should happen] |
| 2 | [Action to take] | [What should happen] |

**Test Data:**
- Field 1: `value`
- Field 2: `value`

**Expected Outcome:** [Final verification]

**Priority:** Critical / High / Medium / Low
````

### Step 3: Organize by Category

Group test cases:

- Functional tests
- UI/UX tests
- Validation tests
- Integration tests (if applicable)
- Edge case tests

### Step 4: Create Status Tracker

```markdown
## Status Tracker

| TC     | Test Case | Priority | Status | Remarks |
| ------ | --------- | -------- | ------ | ------- |
| TC-001 | [Name]    | High     | [ ]    |         |
| TC-002 | [Name]    | Medium   | [ ]    |         |
```

### Step 5: Add Known Issues Section

```markdown
## Known Issues

| Issue | Description | TC Affected | Steps to Reproduce | Severity |
| ----- | ----------- | ----------- | ------------------ | -------- |
|       |             |             |                    |          |
```

## Output

Save the test plan to: `notes/test_plan.md`

Include:

1. Overview and objectives
2. Prerequisites
3. Reference wireframe (if applicable)
4. Test cases (10-20 typically)
5. Status tracker
6. Known issues section

## Test Case Guidelines

- Each test should be independent
- Use specific, concrete test data
- Include both positive and negative tests
- Cover all screens from wireframe (if applicable)
- Test all states from prototype
- Consider mobile/responsive

## Do NOT

- Over-test obvious functionality
- Skip error handling tests
- Forget accessibility basics

Claude reads through all the specs, identifies what needs to be tested, and generates a structured test plan.

For my WooCommerce integration, Claude created 38 test cases organized into 12 sections:

Notice the priority distribution:

• Critical (P0): 7 tests — Must pass before deployment
• High (P1): 20 tests — Essential functionality
• Medium: 11 tests — Important but not blocking

Each test case maps directly to a requirement in my specs. Nothing ambiguous. Nothing assumed. Nothing left to interpretation.

(This is the part where past-me would have skipped ahead to coding. Don’t be past-me.)

.

.

.

Step 2: Create an Implementation Plan That Maps to Test Cases

Now Claude knows what success looks like. Next question: how do we get there?

The implementation plan bridges test cases to actual tasks. Every task links back to specific test cases it will satisfy. It’s the “what depends on what” instruction sheet for our movers.

Specs is approved, test plan is ready. Now we need an implementation plan.

- **Specs**: `notes/specs.md`
- **Test Plan:** `notes/test_plan.md`

## Your Task

Create a detailed implementation plan that maps to the test cases.

### Step 1: Analyze Test Cases

For each test case (TC-NNN):
- What functionality must exist?
- What files need to be created/modified?
- What dependencies are needed?

### Step 2: Create Task Breakdown

Group test cases into implementation tasks:

```markdown
## Implementation Plan: [PHRASE_NAME]

### Overview
[Brief description]

### Files to Create/Modify
[List all files]

### Implementation Tasks

#### Task 1: [Name]
**Mapped Test Cases:** TC-001, TC-002, TC-003
**Files:**
- `path/to/file1.php` - [description]
- `path/to/file2.js` - [description]

**Implementation Notes:**
- [Key detail 1]
- [Key detail 2]

**Acceptance Criteria:**
- [ ] TC-001 passes
- [ ] TC-002 passes
- [ ] TC-003 passes

#### Task 2: [Name]
...
````

### Step 3: Identify Dependencies

- What from previous phrases is needed?
- What order should tasks be implemented?
- Any external dependencies?

### Step 4: Estimate Complexity

- Simple: 1-2 tasks, straightforward
- Medium: 3-5 tasks, some complexity
- Complex: 6+ tasks, significant work

## Output

Save the implementation plan to: `notes/impl_plan.md`

Include:

1. Overview
2. Files to create/modify
3. Tasks with TC mappings
4. Dependencies
5. Complexity estimate

## Guidelines

- Every test case must map to a task
- Tasks should be completable in one session
- Include enough detail to guide implementation
- Reference design system patterns

## Do NOT

- Include actual code (next step)
- Over-engineer simple features

Specs is approved, test plan is ready. Now we need an implementation plan.

- **Specs**: `notes/specs.md`
- **Test Plan:** `notes/test_plan.md`

## Your Task

Create a detailed implementation plan that maps to the test cases.

### Step 1: Analyze Test Cases

For each test case (TC-NNN):
- What functionality must exist?
- What files need to be created/modified?
- What dependencies are needed?

### Step 2: Create Task Breakdown

Group test cases into implementation tasks:

```markdown
## Implementation Plan: [PHRASE_NAME]

### Overview
[Brief description]

### Files to Create/Modify
[List all files]

### Implementation Tasks

#### Task 1: [Name]
**Mapped Test Cases:** TC-001, TC-002, TC-003
**Files:**
- `path/to/file1.php` - [description]
- `path/to/file2.js` - [description]

**Implementation Notes:**
- [Key detail 1]
- [Key detail 2]

**Acceptance Criteria:**
- [ ] TC-001 passes
- [ ] TC-002 passes
- [ ] TC-003 passes

#### Task 2: [Name]
...
````

### Step 3: Identify Dependencies

- What from previous phrases is needed?
- What order should tasks be implemented?
- Any external dependencies?

### Step 4: Estimate Complexity

- Simple: 1-2 tasks, straightforward
- Medium: 3-5 tasks, some complexity
- Complex: 6+ tasks, significant work

## Output

Save the implementation plan to: `notes/impl_plan.md`

Include:

1. Overview
2. Files to create/modify
3. Tasks with TC mappings
4. Dependencies
5. Complexity estimate

## Guidelines

- Every test case must map to a task
- Tasks should be completable in one session
- Include enough detail to guide implementation
- Reference design system patterns

## Do NOT

- Include actual code (next step)
- Over-engineer simple features

Claude analyzes both the specs and test plan, then generates a phased implementation plan:

The result: 4 phases, 12 implementation tasks, each explicitly linked to the test cases that will verify them.

• Phase 1: Foundation & Configuration (2 tasks → TC-001 to TC-007)
• Phase 2: Checkout & Lifecycle (2 tasks → TC-008 to TC-014)
• Phase 3: Renewal Processing (3 tasks → TC-015 to TC-021, TC-038)
• Phase 4: Features (6 tasks → TC-022 to TC-037)

Plus a critical path of P0/P1 items that must work before deployment:

• Mode switch blocking when active subscriptions exist
• Race condition prevention (double-charge protection—ferpetesake, the payments!)
• Pre-renewal token validation
• Token ownership security

Now we have specs, a test plan, AND an implementation plan. Three documents that all reference each other. A complete picture.

But here’s where most people (including past-me, again) would stumble.

.

.

.

Step 3: Execute With Sub-Agents (This Is Where It Gets Fun)

Here’s something I learned the hard way.

There’s research showing that LLM performance degrades as context size increases. When Claude’s context fills up with implementation details from Task 1, it starts losing precision on Task 8. It’s like asking someone to remember the first item on a grocery list after they’ve been shopping for an hour.

The fix: run each task in its own sub-agent.

Each sub-agent gets fresh context. It focuses on one task, implements it, and reports back. The orchestrating agent manages dependencies and progress. No context pollution. No forgotten requirements.

It’s like having a team of movers where each person is responsible for exactly one room—and they all have fresh energy because they haven’t been carrying boxes all day.

Here’s the prompt that kicks off the Claude Code implementation workflow execution:

We are executing the implementation plan. All design and planning is complete.

## Reference Documents
- **Specs:** @notes/specs.md
- **Implementation Plan:** @notes/impl_plan.md
- **Test Plan:** @notes/test_plan.md

## Phase 1: Task Creation

### Before Creating Tasks
1. Review @notes/impl_plan.md completely
2. Understand test case expectations from @notes/test_plan.md
3. Reference wireframe/prototype for UI (if applicable)
4. Check design system for patterns (if available)

### Create Tasks from Implementation Plan
Parse the implementation plan and use `TaskCreate` to create a task for each implementation item:

1. **Extract all tasks** from @notes/impl_plan.md
2. **Identify dependencies** between tasks (what must be done before what)
3. **Create each task** with:
   - Clear description including the specific files to create/modify
   - Mapped test cases (TCs) that verify the task
   - `blocked_by`: tasks that must complete first
   - `blocks`: tasks that depend on this one

Tasks should be granular enough to run independently but logical enough to represent complete units of work.

---

## Phase 2: Task Execution

### Execution Strategy
Execute tasks using sub-agents for parallel processing:

1. **Group tasks into waves** based on dependencies
2. **Run each task in its own sub-agent** - This keeps context usage low (~18% vs ~56%)
3. **Process waves sequentially** - Wave N+1 starts only after Wave N completes

### For Each Task (Sub-Agent Instructions)
1. Use `TaskGet` to read full task details
2. Create/modify specified files
3. Implement functionality to pass mapped TCs
4. **Self-verify the implementation:**
   - Check that code compiles/runs without errors
   - Verify the functionality matches test expectations
   - Ensure design consistency with existing patterns
5. Use `TaskUpdate` to mark task complete with a brief summary of what was done
6. Note any deviations, concerns, or discovered issues

### If Issues Are Discovered
- Use `TaskCreate` to add new fix/bug tasks
- Set appropriate dependencies so fixes run in correct order
- Continue with other independent tasks

---

## Phase 3: Completion Summary

After all tasks are complete, provide:

### 1. Summary of Changes
- Files created
- Files modified  
- Key functionality added

### 2. Self-Verification Results
- What works as expected
- Any concerns or edge cases noted
- Tasks that required fixes (if any)

### 3. Ready for Testing
- Confirm all tasks marked complete
- List any setup needed for testing
- Note any known limitations

---

## Important Notes

- **Do NOT run full test suite** - that's the next step
- **Use `TaskList`** periodically to check overall progress
- **Dependencies are critical** - ensure tasks don't start before their blockers complete
- **Keep sub-agent context focused** - each sub-agent only needs info for its specific task

We are executing the implementation plan. All design and planning is complete.

## Reference Documents
- **Specs:** @notes/specs.md
- **Implementation Plan:** @notes/impl_plan.md
- **Test Plan:** @notes/test_plan.md

## Phase 1: Task Creation

### Before Creating Tasks
1. Review @notes/impl_plan.md completely
2. Understand test case expectations from @notes/test_plan.md
3. Reference wireframe/prototype for UI (if applicable)
4. Check design system for patterns (if available)

### Create Tasks from Implementation Plan
Parse the implementation plan and use `TaskCreate` to create a task for each implementation item:

1. **Extract all tasks** from @notes/impl_plan.md
2. **Identify dependencies** between tasks (what must be done before what)
3. **Create each task** with:
   - Clear description including the specific files to create/modify
   - Mapped test cases (TCs) that verify the task
   - `blocked_by`: tasks that must complete first
   - `blocks`: tasks that depend on this one

Tasks should be granular enough to run independently but logical enough to represent complete units of work.

---

## Phase 2: Task Execution

### Execution Strategy
Execute tasks using sub-agents for parallel processing:

1. **Group tasks into waves** based on dependencies
2. **Run each task in its own sub-agent** - This keeps context usage low (~18% vs ~56%)
3. **Process waves sequentially** - Wave N+1 starts only after Wave N completes

### For Each Task (Sub-Agent Instructions)
1. Use `TaskGet` to read full task details
2. Create/modify specified files
3. Implement functionality to pass mapped TCs
4. **Self-verify the implementation:**
   - Check that code compiles/runs without errors
   - Verify the functionality matches test expectations
   - Ensure design consistency with existing patterns
5. Use `TaskUpdate` to mark task complete with a brief summary of what was done
6. Note any deviations, concerns, or discovered issues

### If Issues Are Discovered
- Use `TaskCreate` to add new fix/bug tasks
- Set appropriate dependencies so fixes run in correct order
- Continue with other independent tasks

---

## Phase 3: Completion Summary

After all tasks are complete, provide:

### 1. Summary of Changes
- Files created
- Files modified  
- Key functionality added

### 2. Self-Verification Results
- What works as expected
- Any concerns or edge cases noted
- Tasks that required fixes (if any)

### 3. Ready for Testing
- Confirm all tasks marked complete
- List any setup needed for testing
- Note any known limitations

---

## Important Notes

- **Do NOT run full test suite** - that's the next step
- **Use `TaskList`** periodically to check overall progress
- **Dependencies are critical** - ensure tasks don't start before their blockers complete
- **Keep sub-agent context focused** - each sub-agent only needs info for its specific task

I know. That’s a lot of prompt. But here’s the thing—you set this up once, and then you watch the magic happen.

Task Creation

First, Claude creates all 13 tasks from the implementation plan:

Then sets up dependencies between them. (This is the “bookshelf before desk” part.)

Wave-Based Execution

Before diving into implementation, Claude explores the existing codebase to understand patterns:

Wave 1 starts with 2 sub-agents running Tasks 1.1 and 1.2 in parallel:

Once Wave 1 completes, Wave 2 begins:

Wave 2 completes, Wave 3 (the critical phase) starts with 3 sub-agents:

Wave 3 completes, and Wave 4 launches with 6 sub-agents in parallel:

(Six sub-agents. Running in parallel. Each with fresh context. This is the future we were promised.)

Implementation Complete

All 13 tasks across 4 waves:

Total time: 52 minutes 22 seconds.

That’s 13 tasks. 38 test cases worth of functionality. Parallel execution keeping context usage low throughout.

Remember my WooCommerce integration specs? The 2,000+ lines that would have turned into a context-overloaded mess if I’d just said “implement this”?

Every requirement addressed. Every edge case accounted for. Every critical feature implemented.

.

.

.

The Complete Claude Code Implementation Workflow

Let me put this all together:

Step 1: Create a test plan from your specs

• Claude analyzes every requirement
• Generates verifiable test cases
• Establishes priority levels

Step 2: Create an implementation plan mapped to test cases

• Groups requirements into logical tasks
• Links each task to specific test cases
• Identifies dependencies between tasks

Step 3: Execute with sub-agents

• Create all tasks with dependency tracking
• Process in waves based on blocking relationships
• Each sub-agent gets fresh context
• Parallel execution where dependencies allow

It’s the complete Claude Code implementation workflow—from inventory list to fully unpacked apartment. (Okay, I’ll stop with the moving metaphor now.)

.

.

.

But Wait. There’s a Catch.

You followed the workflow. Claude built everything in 52 minutes. Your implementation summary shows all 38 test cases “implemented.”

Here’s the uncomfortable truth I need to share with you:

“Implemented” and “working correctly” aren’t the same thing.

Claude sometimes takes shortcuts. Features get partially built. Edge cases get acknowledged in comments but not actually handled. The sub-agent said “Done”—but did it really do what the test case required?

You need a verification step. A way to systematically check that every test case actually passes. A process for catching the gaps before you discover them in production.

That’s next week.

(Yes, another cliffhanger 😁)

Imagine this.

You hire a contractor to “update the bathroom.” You wave your hand vaguely at the space, mention something about “modern vibes,” and leave for work.

You come home to discover they’ve ripped out your vintage clawfoot tub—the one you specifically loved—and replaced it with a walk-in shower. They’ve chosen gray tiles. (Gray! When you’re clearly a warm terracotta person.) And oh, they’ve moved the toilet to a spot that now requires you to shimmy sideways to close the door.

“But you said you wanted it updated,” they say, genuinely confused.

Here’s the thing: they weren’t wrong. You did say that.

You just forgot to mention all the things living rent-free in your head—the constraints, the preferences, the “obviously don’t touch THAT” items you assumed were, well, obvious.

This is exactly what happens when you ask Claude Code to add a feature to your existing app.

.

.

.

The “Just Add This Feature” Trap

You’ve got a working application.

It’s not perfect, but it works. Now you want to add something—a new feature, a refactor, maybe squash a bug that’s been giving you side-eye for weeks.

So you fire up Claude Code and describe what you want in two or three sentences.

Claude gets to work. Files change. Functions appear. Code flows.

And then—record scratch—you realize it completely missed the point.

Not because Claude is bad at its job. But because you gave it the software equivalent of “update the bathroom.”

Your codebase has history.

Conventions. Edge cases you’ve already wrestled to the ground. Payment integrations that absolutely, positively cannot break (ferpetesake, the payments!). Claude needs to understand ALL of this before writing a single line of code.

This is where Claude Code spec-driven development comes in.

And honestly?

It’s transformed how I approach every feature request.

.

.

.

Why Spec-Driven Development Changes Everything

Here’s what most people do: describe the feature → let Claude code → discover problems → fix problems → discover MORE problems → question life choices.

Here’s what works: describe the feature → trigger clarifying questions → answer EVERY question → generate comprehensive specs → review specs → THEN code.

The difference isn’t just efficiency (though yes, that too).

👉 The real magic is that Claude surfaces edge cases YOU haven’t thought about.

All those assumptions living in your head? Claude will ask about them. All those “obviously we’d handle it THIS way” decisions? Claude will make you choose explicitly.

It’s like having a brilliant—if occasionally pedantic—architect who refuses to pick up a hammer until every single detail is documented.

Let me show you exactly how this works.

.

.

.

The 3-Phase Method for Claude Code Spec-Driven Development

I’ve been refining this workflow for weeks, and it breaks down into three distinct phases.

(Stay with me—I promise this is more exciting than it sounds. Okay, maybe “exciting” is strong. But genuinely useful? HECK YES.)

.

.

.

Phase 1: Build Your Specs

This is where you go from “vague idea in your head” to “comprehensive document that leaves nothing to chance.”

Step 1: Describe the Task + Trigger the Magic Words

Here’s the prompt structure that makes everything work:

[Describe your task/feature in detail]

Based on the tasks above, write the specs at @notes/specs.md.

Use ASCII diagrams where necessary to illustrate the UI/UX.

Use the AskUserQuestion tool to Ask me clarifying questions until you are 95% confident you can complete this task successfully. For each question, add your recommendation (with reason why) below the options. This would help me in making a better decision.

That last paragraph? That’s the secret sauce.

“Ask me clarifying questions until you are 95% confident” tells Claude not to make assumptions. Not to guess. Not to fill in blanks with whatever seems reasonable.

Instead, Claude will ASK.

Step 2: Let Claude Explore First

Here’s something beautiful: Claude doesn’t immediately pepper you with questions.

First, it explores your codebase. It reads your existing implementation. It studies your patterns, your database schema, your webhook handlers.

In my WooCommerce integration project, Claude spent about 2 minutes analyzing the existing Stripe integration—36 tool uses, 97.5k tokens of context-gathering—before asking its first question.

Then the questions began:

Notice what’s happening here (and this is the part that made me unreasonably happy):

• Claude presents clear options—not vague open-ended questions
• Each option includes an explanation of implications
• Claude adds its own recommendation with reasoning
• You can select an option OR type something custom

That recommendation is EVERYTHING. You’re not making decisions in a vacuum. You’re evaluating Claude’s expert analysis against your own context.

Step 3: Keep Answering Until Claude Hits 95%

After your first answer, Claude asks another question. Then another.

Each question builds on your previous answers. Claude’s understanding deepens with every response.

“But wait,” you might be thinking. “Isn’t this just Plan Mode with extra steps?”

Ah. Good question. (I asked it too.)

Plan Mode asks one batch of questions, then starts planning.

This approach keeps questioning until Claude reaches genuine confidence. If something’s unclear—or conflicts with an earlier answer—Claude asks follow-up questions. It’s more thorough. Sometimes annoyingly so. But annoyingly thorough beats catastrophically incomplete every time.

Step 4: Review the Complete Q&A

By the end of my WooCommerce project, Claude had asked 15 different questions covering:

• Subscription plugin choice
• Renewal flow mechanics
• Checkout experience
• Payment mode switching
• Migration strategy
• Product mapping
• Refund handling
• Member portal UI
• Day pass handling
• Coupon systems
• Settings location
• Email notifications

Every edge case I hadn’t considered? Surfaced as a question.

Every architectural decision that could bite me later? Addressed before a single line of code.

👉 This is the core of Claude Code spec-driven development: front-loading decisions instead of discovering them mid-implementation.

Step 5: Watch Your Specs Materialize

Once Claude hit 95% confidence, it summarized everything and started writing:

The result? A 2,068-line specification document with:

• Architecture decisions (documented!)
• Database schema changes (planned!)
• State machines for subscriptions (visualized!)
• ASCII diagrams for UI mockups (actually helpful!)
• Detailed flow documentation (comprehensive!)
• Edge case handling (the stuff that usually bites you)

Two thousand lines might sound excessive. It’s not. It’s every decision you’d otherwise make on the fly—except now they’re documented, reviewable, and consistent.

Bonus Step: Split Large Specs

Quick practical note: if your specs exceed ~1,500 lines, split them.

Claude’s file reading has a 25k token limit. Large files cause problems during implementation. The fix is simple:

This specs file is too big. Please split it into 3 parts. 
Keep the original file as the index file that links to the 3 parts.

Claude reorganizes everything into digestible chunks:

Now you have:

• specs.md — Index file (~130 lines)
• specs-part1-architecture.md — Sections 1-5 (~490 lines)
• specs-part2-flows.md — Sections 6-10 (~470 lines)
• specs-part3-features.md — Sections 11-20 (~530 lines)

Each part fits comfortably within context limits.

Crisis averted.

.

.

.

Phase 2: Review Your Specs

Here’s where most people stop.

(Don’t be most people.)

Your specs might be comprehensive, but they could still contain conflicts, gaps, or requirements that are—how do I put this diplomatically—completely impossible to implement.

Step 6: Start Fresh and Ask Claude to Critique

Start a new session. Fresh context. Then ask Claude to review its own work with skeptical eyes:

Read the `notes/specs.md`, analyze the codebase and tell me what could be 
the potential problems with this specs. 

Let's look at it from different angles and try to consider every edge cases.

Use ASCII diagrams to illustrate if needed. Don't edit anything yet. 
Let's focus on analysis.

That last line—”Don’t edit anything yet”—is important. You want analysis first. Changes second. Mixing them leads to chaos.

Step 7: Receive Your Brutally Honest Analysis

Claude reads the specs, re-explores your codebase, and delivers feedback that might sting a little:

The analysis includes ASCII diagrams showing exactly where problems would occur:

In my project, Claude found 14 potential issues, organized by severity:

P0 – Critical (the “oh no” tier):

• Race condition in renewal processing → Double charges 😱
• Token deletion not detected → Failed renewals
• Mode switch with active Stripe subs → Billing confusion

P1 – High (the “definitely fix this” tier):

• Proration + coupon calculation undefined → Financial errors
• Guest checkout for subscriptions → Broken flow
• 3D Secure on unattended renewals → Payment failures

Would I have caught all these myself?

Honestly? Maybe half. And probably not until they caused real problems with real users and real money.

👉 Having Claude review its own specs is like getting a code review before the code exists.

.

.

.

Phase 3: Refine Your Specs

Now you have a prioritized list of issues. Time to fix them—but not by guessing.

Step 8: Address Issues With Another Round of Questions

Ask Claude to fix the critical issues, but trigger the questioning mode AGAIN:

Let's address all the P0 and P1 issues.

Update the specs file.

Use the AskUserQuestion tool to Ask me clarifying questions until you are 95% confident you can complete this task successfully. For each question, add your recommendation (with reason why) below the options.

Fixing these issues requires MORE decisions. Should you block mode switches entirely? Allow mixed modes temporarily? Auto-cancel subscriptions?

Claude asks:

Each answer shapes the solution. After this round, Claude updates the specs with concrete, specific fixes:

P0 Fixes:

• Renewal Race Condition → Database row locking with SELECT FOR UPDATE
• Token Deletion → Pre-renewal validation 7 and 3 days before renewal
• Mode Switch Danger → Block switching if ANY active Stripe subscriptions exist

P1 Fixes:

• Proration + Coupon → Calculate from actual paid amounts, keep coupon on upgraded plan
• Guest Checkout → Force account creation for subscription products
• 3D Secure → Request off-session exemption, fallback to email payment link

You can repeat Phase 2 and Phase 3 as many times as needed. Review, refine, review, refine—until you’re genuinely confident in your specs.

.

.

.

The Method, Summarized

Because I know you’re going to want to reference this later:

Phase 1: Build Specs

1. Describe what you want + add the AskUserQuestion trigger
2. Let Claude explore your codebase first
3. Answer every clarifying question
4. Review the generated specs
5. Split large specs into parts (if needed)

Phase 2: Review Specs 6. Start a new session 7. Ask Claude to find problems (analysis only—no edits)

Phase 3: Refine Specs 8. Fix critical issues with another round of questions 9. Repeat Phases 2-3 until satisfied

YOU decide when specs are ready.

Not Claude.

You.

.

.

.

What About Implementation?

Ah. Yes.

You have these beautiful, bulletproof specs. Now what?

You could tell Claude to implement everything in one go. But for specs this comprehensive, that approach has problems:

• Claude might skip features (context limits are real)
• Long implementations drift from the plan
• Details get forgotten mid-stream

The solution?

Claude Code’s task management system—which breaks large specs into trackable tasks, maintains progress across sessions, and ensures nothing slips through the cracks.

That’s next week’s issue.

(Consider this a cliffhanger. I regret nothing.)