VibeCoding Pro#

The AI coding upgrade that actually ships working software.

VibeCoding is fun. VibeCoding Pro is reliable.

---

What VibeCoding Gets Wrong#

Most AI coding workflows look like this:

text

You → "build a login form" → AI generates → "looks good!" → ship it
                                            ↑
                                   This is the problem.

Why it's broken: The same AI that generated the code judges whether it works. It suffers from cognitive commitment bias — it can't objectively evaluate what it just built because it already committed to the approach. Bugs survive. Edge cases break. UX issues ship.

The evidence: Anthropic's 2026 engineering research ran an experiment. Solo Claude agents produced 2D game makers where the core game loop was fundamentally broken — entities rendered but ignored all player input. The agent called its own output "working." Only when a separate Evaluator agent physically clicked through the game did it discover the wiring between entity definitions and game runtime was severed.

---

What VibeCoding Pro Gets Right#

text

User Goal / Spec
      ↓
 ┌─────────────┐
 │  Generator  │ ← "Build X according to spec"
 │  (vibe)     │
 └──────┬──────┘
        │ artifact
        ↓
 ┌────────────────────────────────────┐
 │           Evaluator                │
 │  • Reads SPEC (NOT generator output)│
 │  • Opens URL in real browser        │
 │  • Clicks, fills, navigates         │
 │  • Scores on rubric (0-100)          │
 │  • Returns structured JSON feedback  │
 └────────────────┬───────────────────┘
                  │ score + feedback
                  ↓
         ┌────────────────┐
         │ score ≥ threshold? │
         │ YES → Done     │
         │ NO → Generator  │
         └────────┬────────┘
                  └── Loop (5-15 rounds)

The structural fix: Evaluator never reads the generator's code, reasoning, or commit messages. It only reads the SPEC and operates the deployed artifact. This eliminates anchoring bias architecturally — not through clever prompting.

---

When to Use VibeCoding Pro#

ScenarioApply?WhyReact / H5 / Web UI with real interactions✅ YesPlaywright can actually click through itMulti-step form flows (wizard, checkout, onboarding)✅ YesEvaluator can exercise each stepAPI + frontend integration✅ YesEvaluator calls endpoints and checks DB stateSingle utility function⚠️ OptionalMight be overkillPure backend logic (no UI)⚠️ Use API Evaluator templateEvaluator calls endpoints directlyDesign-sensitive work (brand identity, layout)✅ YesHuman-in-the-loop variant works best

---

Quick Start#

Step 1: Write a Spec Contract#

The SPEC is the most important artifact. It's the Evaluator's only reference.

markdown

# Spec: [Feature Name] v1.0

## Goal
[One sentence: what exists when this is done?]

## Functional Requirements
- FR-001: [Specific, testable, observable]
- FR-002: [...]

## Interaction Specifications
- UI-001: [User clicks X → Y happens]
- UI-002: [Form accepts type Y, rejects type N]

## Acceptance Criteria
- AC-001: [Measurable outcome]
- AC-002: [...]

## Out of Scope
- [Explicitly NOT required]

## Test Scenarios
**Scenario 1:** Happy path — normal user completes primary action
**Scenario 2:** Edge case — empty data, error state
**Scenario 3:** Boundary — max input length, concurrent actions

Step 2: Run the Loop#

1. Generator Agent receives: SPEC + iteration history + previous Evaluator feedback
2. Generator builds artifact and deploys
3. Evaluator Agent receives: SPEC + deployed URL (NOT generator code)
4. Evaluator opens browser, clicks through test scenarios, screenshots, scores
5. Evaluator returns structured JSON with score breakdown
6. If score ≥ threshold → done. If not → loop back to Generator.

---

Architecture Reference#

See references/architecture.md for:

• Four architecture variants (Sequential / Parallel / Staged / Human-in-loop)
• GAN theory deep-dive and why it works
• Spec Contract template (copy-paste ready)
• History format and loop control logic
• Anti-patterns and how to fix them

---

Evaluator Templates#

See references/evaluator-prompts.md for:

TemplateWhen to UseEvaluator ModeWeb/H5 UIReact/Vue/H5/Web componentsPlaywright browser automationAPI/BackendREST endpoints, microservicesDirect HTTP callsContent/DocsReports, copy, documentationStructured text scoring

Each template includes:

• System prompt (calibrated for evaluator independence)
• User prompt with rubric
• Required JSON output schema
• 4 calibration examples (30/60/85/95 score ranges)

---

Iteration Loop Scripts#

See scripts/iteration_loop.py for a complete Python implementation:

• run_generator() — adapt to your agent (Claude API, OpenAI, subagent, etc.)
• run_evaluator() — adapt to your QA stack (Playwright, HTTP client, etc.)
• Full loop control: plateau detection, approach switching, escalation
• CLI: python iteration_loop.py --spec spec.md --url http://localhost:3000 --threshold 85 --rounds 15

See scripts/calibrate_evaluator.py for evaluator calibration utility:

• Run on 4 known examples before production
• Auto-detects score drift and suggests rubric adjustments

---

Scoring Rubric#

Default rubric (adjust weights by domain):

DimensionWeightMeasuresFunctional completeness30%Every spec requirement works end-to-endInteraction quality25%Click/form/nav behavior as a real userEdge case handling20%Error states, empty data, boundary inputsCode/design quality15%Consistency, readability, no anti-patternsOriginality/craft10%Avoids template defaults and AI slop patterns

Threshold guidelines:

Use CasePASS_THRESHOLDMAX_ROUNDSInternal prototype7010User-facing feature8515Production critical9520 + human review

---

Why This Works (Research Background)#

Source: Anthropic Engineering, "Harness Design for Long-Running Application Development" (March 2026)

Key findings:

• Solo Claude agents on 16-feature game maker: core game loop broken, entity runtime wiring severed
• Full harness (Generator + Evaluator): fully working, sprite animation, sound, AI-assisted level design
• Opus 4.6 vs 4.5: improved planning reduced harness complexity needed
• Evaluator value is situational: worth the cost when task exceeds what the model reliably does solo

GAN theory parallel: The Generator tries to fool the Evaluator. The Evaluator tries to catch failures the Generator misses. The adversarial tension drives quality upward. Unlike ML GANs, this uses natural language feedback — it's fully inspectable and steerable.

---

Common Mistakes#

MistakeWhy It FailsFixSame agent generates and evaluatesCognitive anchoring biasSeparate agents with separate promptsEvaluator reads generator's codeJudges intent, not realityShow only deployed URLSkipping calibrationScore inflation/driftRun 3-5 known examples firstVague scoring ("7/10 looks fine")Unactionable feedbackRequire structured JSON per rubricToo few roundsGenerator never convergesMinimum 10 rounds for complex UINever switching approachGets stuck in local minimumSwitch strategy after 3 plateauing roundsUsing for trivial tasksOverhead > valueReserve for multi-feature/full-page work

---

OpenClaw Integration#

In OpenClaw, use the coder + tester subagents:

text

Generator → sessions_spawn(agentId="coder", ...)
Evaluator → sessions_spawn(agentId="tester", ...) + browser tool

The tester subagent should use the Playwright MCP tool:

• browser_navigate → open URL
• browser_click → interact
• browser_fill → form input
• browser_screenshot → capture evidence

---

Built on Anthropic's 2026 engineering research. Inspired by GAN theory and adversarial validation patterns.