boris-vibe-coding

name	boris-vibe-coding
description	Use when starting a vibe coding session or managing parallel AI agents for development - fleet management, plan-first execution, browser verification loops, shared team memory

Boris-Style Vibe Coding

Overview

Engineering discipline applied to AI-driven development. Run fleets of parallel agents, always plan before executing, verify through the browser (not by trusting Claude's word), encode every mistake into CLAUDE.md.

Core principle: "A wrong fast answer is slower than a right slow answer."

When to Use

• Starting any non-trivial feature or session
• Multiple independent tasks that can run in parallel
• Any task with a UI component that needs verification

Do NOT skip this for "quick" changes — quick changes without planning/verification create the most rework.

The 5-Part Workflow

1. Fleet Management (not serial chat)

Run 5–15 Claude sessions in parallel, not one after another:

Terminal tabs: 1 | 2 | 3 | 4 | 5
claude.ai/code: 5–10 additional sessions

• Number tabs, use system notifications to know when input is needed
• Treat AI as distributed cognitive capacity, not a single assistant
• Independent tasks → assign to separate sessions immediately

Baseline violation: Running tasks serially when they have no dependencies.

2. Plan Mode First (always)

Session start → Plan Mode → iterate until plan is good → switch to auto-accept → 1-shot execution

Never jump directly to code. Back-and-forth in Plan Mode costs nothing compared to rework.

For complex sessions, create two lightweight files at session start:

task_plan.md   → goals, phases, current step
findings.md    → research notes, API docs, decision rationale

Claude reads these before every major decision — not relying on context memory. Delete or archive when session ends.

Why this matters: CLAUDE.md = permanent team memory across sessions. task_plan.md = working memory within a session. Long sessions drift without it — Claude forgets the original goal by sub-task 8.

Baseline violation: Jumping straight to implementation to "save time."

3. Shared CLAUDE.md (team memory)

• One CLAUDE.md checked into git, shared by entire team
• When Claude makes any mistake → add it to CLAUDE.md immediately
• Errors become team knowledge; they should never repeat

# In CLAUDE.md:
## DO NOT
- Use `useEffect` for data fetching — use React Query instead
- Import from `../utils` — always use `@/utils` alias

Baseline violation: Noting the mistake mentally but not encoding it, causing the same error next session.

4. Browser Verification Loop (most important)

Never trust Claude's self-report of "done." Always verify through the browser.

Write code → start dev server → Claude opens browser → tests UI/UX
→ if wrong: fix code → reload → re-test → repeat until it actually works

Use Recon-First pattern — inspect before interacting:

1. browser_snapshot()              ← capture full page structure
2. wait for load state             ← ensure dynamic content (React/Vue) is rendered
3. analyze snapshot, locate refs   ← find exact target elements
4. browser_click / browser_type    ← interact with accurate targets

Never click blind. Jumping straight to interaction without a snapshot causes selector failures and wastes retry cycles.

Implementation with Playwright MCP (already configured):

1. Start dev server in background (npm run dev & or equivalent)
2. browser_navigate → localhost:3000
3. browser_snapshot → read structure, find element refs
4. browser_wait_for → confirm dynamic content loaded
5. browser_click / browser_type / browser_fill_form with known refs
6. If UI is wrong → fix code → browser_navigate again → repeat from step 3

Do not stop until the browser confirms it works.

Baseline violation: Treating successful compilation as "done." It's not done until the browser says it's done.

5. Model Selection

Default: Opus + thinking enabled for everything.

Situation	Model
Architecture decisions	Opus + thinking
Code generation	Opus + thinking
"Just a quick fix"	Still Opus + thinking
Simple file rename	Sonnet is fine

Wrong answers = rework. Rework cost > token cost.

Quick Reference

Situation	Action
Starting new feature	Plan Mode + task_plan.md first
Multiple independent tasks	Parallel fleet sessions
Long/complex session	Create task_plan.md + findings.md
Claude says "it's done"	Browser verification loop
Browser element not found	Recon-first: snapshot before interacting
Claude makes a mistake	Document in CLAUDE.md immediately
Speed vs accuracy	Always choose accuracy (Opus)
Quick PR	Plan Mode → auto-accept → 1-shot → browser verify

Common Mistakes

Mistake	Fix
Serial sessions for independent tasks	Open parallel tabs, assign immediately
Skipping Plan Mode for "small" changes	Small changes cause the most rework
Trusting npm run build success as verification	Open the browser and click through it
Clicking elements without snapshot first	Recon-first: snapshot → locate → interact
Goal drift in long sessions	Create task_plan.md at session start
Noting mistakes mentally	Write to CLAUDE.md before moving on
Using fast model to save time	Wrong answer is slower than slow answer

Red Flags — Stop and Reset

• "I'll just quickly write the code first"
• "It compiled, so it's working"
• "I'll add it to CLAUDE.md later"
• "This is too simple for Plan Mode"
• "Using Sonnet for this is fine"
• "I'll just click around and see what happens" (browser verification without snapshot)
• "I remember the plan, I don't need task_plan.md"

All of these have caused rework. Follow the workflow.