In traditional engineering, you’d never let a developer merge code without a peer review.

So why are we letting AI grade its own homework?

I’ve been building with Claude Code for 750+ sessions across multiple projects — a content pipeline, a marketing site, a design system, decision frameworks. Somewhere around session 200, I noticed a pattern: Claude is brilliant, but it has consistent blind spots. It favors certain architectures. It misses edge cases in its own prompts. It quietly accepts assumptions that a different perspective would challenge.

So I did something unconventional: I gave Claude a sparring partner.

I built an open-source skill called Brainstorm that runs a structured 3-round adversarial dialogue between Claude Code and Google’s Gemini. Not a simple “ask two models the same question” approach — a real debate where each model challenges the other’s reasoning, and they converge on a single actionable recommendation.

Here’s the repo: Claude Starter Kit — the Brainstorm skill is included alongside memory, hooks, and three other Claude Code skills. MIT license, works out of the box.

Let me show you what happened when I put this to work.

The Problem: Single-Model Agentic Workflows Hit a Ceiling

If you use Claude Code daily, you know how productive it is. It reads your codebase, makes changes, runs tests, iterates. For straightforward tasks, it’s incredible.

But for decisions — architecture choices, design system approaches, prompt engineering, evaluation criteria — a single model creates a feedback loop. Claude designs a solution, Claude evaluates it, Claude declares it good. There’s no external challenge.

You might ask: why not just prompt Claude to red-team its own output? Or use a cheaper Claude model to draft and a smarter one to review? We tried both. The problem is fundamental — same provider, same training corpus, same architectural biases. Claude challenging Claude is like asking someone to proofread their own essay. They’ll catch typos but miss the structural issues. A different model family with different training data and different instincts is what breaks the loop.

I hit this wall three separate times before I built a systematic fix:

Wall 1: Design system architecture. Claude recommended using Google’s Stitch tool with post-processing to fix design token adherence. Sounded reasonable. Spent two days implementing it. Token adherence: 35%. The approach was fundamentally flawed, and Claude couldn’t see it because it designed it.

Wall 2: Content pipeline prompts. Claude wrote evaluation prompts for our 7-stage content pipeline. The prompts looked great — well-structured, detailed, comprehensive. But when we actually measured output quality, the scores were mediocre. The prompts had loopholes that Claude couldn’t identify in its own work.

Wall 3: Quality metrics. Claude designed metrics to evaluate content quality, then evaluated content using those same metrics. Circular validation. The scores looked good on paper but didn’t reflect real quality improvements.

Every one of these failures had the same root cause: no adversarial pressure. The model was reviewing its own work with its own biases.

Enter the Brainstorm Skill: Claude vs Gemini in the Terminal

The Brainstorm skill runs a 3-round structured debate between Claude and Gemini. It’s not random back-and-forth — each round has a specific purpose:

Round 1 — Diverge. Both models propose different approaches to the problem. Claude brings codebase context (it can read your files). Gemini brings a fresh perspective from a completely different model family with different training biases.

Round 2 — Deepen. Each model challenges the other’s proposal. “What happens when input is empty?” “What about the edge case where the user has 12 languages?” “Your approach assumes X, but what if Y?” This is where the real value emerges — the challenges neither model would generate reviewing its own work.

Round 3 — Converge. After two rounds of productive conflict, the models synthesize a single recommendation with clear reasoning. You get one actionable path forward, not two competing opinions.

How Gemini gets context: Claude orchestrates the entire flow. It reads your local files, summarizes the relevant context, and passes it to Gemini via the Google GenAI API along with the debate prompt. Gemini never touches your filesystem directly — Claude acts as the bridge, deciding what context is relevant to share. This means your code stays local while Gemini gets exactly the context it needs to give meaningful critique.

The architecture is deliberate. Gemini uses a two-layer approach: Flash-Lite with Google Search grounding gathers real-world facts first (the “ground truth” phase), then Pro reasons on verified data. A mandatory fact-check phase at the end catches any claims that slipped through. A typical brainstorm takes about 40-60 seconds and costs roughly $0.02-0.05 in API calls — overkill for fixing a typo, but invaluable for architecture decisions.

# Install (one command)
git clone https://github.com/awrshift/claude-starter-kit.git my-project
cd my-project && claude

# Or add just the skill to an existing project
git clone https://github.com/awrshift/skill-brainstorm.git .claude/skills/brainstorm

Then just say “brainstorm” in Claude Code, describe your problem, and watch the debate unfold.

Case Study 1: How an AI Code Review Loop Replaced Our Designer

This is the one that convinced me adversarial agentic workflows are the future of development.

We were building a marketing site called Avoid Content. The question: how should Claude generate UI components that precisely follow our design tokens (colors, typography, spacing)?

Claude’s position (Round 1): Use Google Stitch to generate screens, then post-process the output to replace colors and fonts with our design tokens. Reasonable — Stitch is a powerful UI generation tool.

Gemini’s challenge (Round 2): “Post-processing is fragile. What happens when Stitch generates a gradient that mixes two non-token colors? What about hover states? You’ll spend more time fixing edge cases than you save.” Gemini argued for generating code directly from design tokens — skip Stitch entirely, use a frontend-design approach where tokens are injected into the generation prompt.

The convergence (Round 3): Test both approaches, measure token adherence.

Results:

• Stitch + post-processing: 35% token adherence (18 color references in benchmark components, only 6 matched)
• Direct generation from tokens: 100% token adherence on benchmark components (18/18 exact hex matches — the strict token schema forced compliance)

That brainstorm literally replaced our entire design workflow. And it went further — we built a visual QA loop on top of it:

1. Claude generates a component using design tokens
2. Playwright takes a screenshot
3. Gemini reviews the screenshot visually against a reference design
4. Claude fixes issues Gemini identified
5. Repeat (max 2 iterations)

Typography scores went from 5/10 to 8/10 in a single iteration. Spacing, visual hierarchy, overall polish — all improved measurably because a different model family was doing the AI code review.

We effectively replaced manual design reviews with an automated Claude + Gemini loop. Not “AI-assisted design” — AI-driven design with AI-driven quality assurance. The entire Avoid Content site was built this way: Claude prototyping, Gemini reviewing screenshots, iterating until both models agreed the output was solid.

Case Study 2: Gemini Gates in a 7-Stage Content Pipeline

Our content generation platform runs articles through seven stages: Strategy, Outline, Research, Generate, Verify, Optimize, Finalize. Each stage has specific quality metrics.

The breakthrough wasn’t using Gemini to generate content. It was using Gemini as a gate — a checkpoint that must approve output before it moves to the next stage.

At the prompt design phase for Stage 4 (article generation), we ran the prompt through Gemini for stress-testing:

“Identify how an LLM could misinterpret this prompt. Find loopholes, missing constraints, ambiguous rules.”

Gemini found three critical loopholes Claude missed:

• The prompt said “avoid repetitive sentence starters” but didn’t define what counts as repetitive (per-section vs. article-level)
• Temperature 1.0 + negative instructions (“don’t use X”) triggered the pink elephant effect — the model used X more, not less
• Word count targets lacked adaptive coefficients, causing +25% overshoot

After fixing these based on Gemini’s critique, article quality jumped measurably. And here’s the finding we’ve now confirmed three separate times:

Prompt quality > model quality. A basic prompt on Gemini Pro performed identically to Flash (50% quality score). The same models with a stress-tested prompt hit 75-80%. The bottleneck was never the model — it was the prompt.

This is the single most important lesson from running two AI models together. You don’t need a more expensive model. You need a different model family to find the holes in your prompts.

The same pattern held for our AWRSHIFT decision framework — a structured tool for non-trivial choices (which architecture? build vs. buy?). Through brainstorm sessions, Gemini pushed back on Claude’s overcomplicated 5-mode design and the system converged on a single adaptive flow. Simpler for users, more flexible for the system. That framework is also open-source: skill-awrshift.

A Mini Claude Code Tutorial: The Technical Setup

Getting this running takes about five minutes. Here’s what you need:

Prerequisites:

• Claude Code installed (CLI or Desktop)
• A free Google API key for Gemini
• Python 3.10+ with pip install google-genai

Option 1: Full Starter Kit (recommended)

git clone https://github.com/awrshift/claude-starter-kit.git my-project
cd my-project
claude

Claude runs the setup automatically — asks your name, project description, language preference, and configures everything. You get four Claude Code skills out of the box:

Plus a persistent memory system, session hooks, multi-project journals, and experiments tracking.

Option 2: Just the Brainstorm skill

# Add to existing Claude Code project
git clone https://github.com/awrshift/skill-brainstorm.git .claude/skills/brainstorm

# Set up Gemini
echo "GOOGLE_API_KEY=your-key-here" >> .env
pip install google-genai

Then in Claude Code, just say “brainstorm [your question]” and it works.

Option 3: Gemini skill only (for quick second opinions)

git clone https://github.com/awrshift/skill-gemini.git .claude/skills/gemini

Use it for one-off checks: “ask Gemini if this architecture makes sense” or “get a second opinion on this prompt.”

When to Use Brainstorm vs. Second Opinion

Not every decision needs a 3-round debate. Here’s how we think about it after 750+ sessions:

The rule is simple: if there’s one path and you need a sanity check, use Gemini directly. If there are multiple paths and you need to converge, use Brainstorm.

What We Learned: Five Rules for Multi-Model Agentic Workflows

After building production systems with Claude + Gemini, these patterns held up consistently:

1. Prompt quality always beats model upgrades.
We proved this three times across different domains. A well-crafted prompt on a cheaper model outperforms a lazy prompt on an expensive one. Use Gemini to stress-test your prompts before optimizing your model tier.

2. Gemini’s critique is an input, never the decision.
44% of Gemini’s insights were genuinely unique — things Claude would never catch on its own. But Gemini lacks your codebase context, your prior decisions, your constraints. Always evaluate its recommendations critically before acting.

3. Different model families catch different blind spots.
This is the whole thesis. Claude and Gemini have different training data, different architectures, different biases. When they disagree, that’s where the most valuable insights hide. When they agree, you can be more confident the answer is solid.

4. Fact-check after every brainstorm.
We found that 2 out of 6 brainstorm decisions were invalidated when we checked the claims against live web data. The mandatory fact-check phase (built into Brainstorm v2.1) catches these before they become expensive mistakes.

5. The visual QA loop is underrated.
Most developers only use text-to-text generation. Adding Playwright screenshots + Gemini visual review creates an AI code review feedback loop that catches UI issues no text-based review ever could. Typography, spacing, color contrast — Gemini sees what Claude can only describe.

Exploring the Claude Code Skills Ecosystem

If you’re new to Claude Code skills, they’re essentially reusable capabilities you add to your agent. A skill is a folder with a SKILL.md file that tells Claude when and how to use it.

The ecosystem is growing fast — skills can be shared through the Claude Code plugins marketplace, and the Starter Kit includes a Skill Creator that lets you build your own skills and test them with an eval framework.

Some ideas for custom skills you could build:

• A skill that runs your test suite and interprets failures
• A skill that checks your PR against your team’s code style guide
• A skill that queries your production logs when debugging

Check the Claude skills on GitHub for more examples and inspiration.

Try It Yourself

Everything mentioned in this article is open-source and free:

• Claude Starter Kit — Full setup with memory, skills, hooks, and multi-project support
• skill-brainstorm — Standalone 3-round Claude x Gemini adversarial dialogue
• skill-gemini — Quick second opinions and visual reviews
• skill-awrshift — Structured decision framework with Gemini gates

The setup takes five minutes. The first brainstorm session will probably change how you think about AI pair programming.

Because the real power isn’t in having a smarter AI. It’s in having two AIs that think differently — and making them argue until the best answer wins.

Built by Serhii Kravchenko — based on 750+ sessions building AI content pipelines, multi-agent systems, and design automation with Claude Code.

We’re working toward getting Brainstorm into the official Claude Code plugins directory. If this workflow saved you time, a star on the Starter Kit repo helps us get there faster.

Japanese version: Zenn (Japanese)

This is the third in a series. The first two: Solving Claude Code’s Memory Loss and 7 Phrases That Make Claude Code Actually Reliable. You don’t need to read them, but they give context.

Here’s something I learned the hard way: writing rules for an AI coding assistant is easy. Getting it to actually follow them is a different sport entirely.

I run 25 repos through Claude Code. I have a shared conventions file, session logs, templates, the whole setup. It works. But within two weeks of scaling it up, I found myself repeatedly fixing the same three problems:

1. Claude writing information in the wrong place
2. Convention files bloating until they defeated their own purpose
3. Documentation silently drifting out of sync with reality

My first instinct was to add more rules. “Don’t write project state to memory.” “Keep SESSION.md under 80 lines.” “Check references before pushing.” Rules on top of rules.

It didn’t work. Rules get autocompacted. Rules get ignored. Rules require a human to enforce them, and humans forget.

What actually worked was making Claude enforce the rules on itself.

mkdir -p ~/Claude && cd ~/Claude

The Pattern: Don’t Add More Rules. Add Enforcement.

Every problem had the same shape: Claude does something wrong, I notice too late, I fix it, I write a rule, Claude does it again next week.

The fix was also the same shape every time: instead of telling Claude what to do, I built a mechanism that physically prevents the wrong thing or automatically detects it.

Let me walk through each one.

1. Blocking Wrong Writes with Hooks

Claude Code has a memory system (~/.claude/ files) and I also use SESSION.md for tracking work state. The problem: Claude defaults to stuffing everything into memory. Project status, design decisions, task progress — all shoved into memory where it’s invisible to other machines (memory doesn’t go into Git) and only loaded when Claude feels like it.

SESSION.md is in the repo. It syncs via Git. It gets loaded every time through the “How to Resume” flow. Memory doesn’t have any of those properties.

I wrote a rule saying “only write user preferences to memory.” Claude followed it for about three days before autocompact wiped the instruction and it went right back to its old habits.

The fix: a PreToolUse hook

Claude Code supports hooks — shell scripts that run before or after tool calls. I wrote one that intercepts writes to the memory directory:

# memory-guard.sh (simplified)
INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')

# Not a memory write? Let it through.
[[ "$FILE_PATH" != *"/.claude/projects/"*"/memory/"* ]] && exit 0
# Index file is fine
[[ "$FILE_PATH" == */MEMORY.md ]] && exit 0

# Block everything else
cat >&2 << 'EOF'
BLOCKED: Writing to memory directory.
Check the destination table in CONVENTIONS.md before proceeding.
EOF
exit 2  # exit 2 = block the tool call

When Claude tries to write to memory, it gets blocked and told to consult the decision table. The table looks like this:

That last row matters more than you’d think. Recording things grep can tell you is how files bloat.

Claude reads the table, realizes “oh, this is project state, not a preference,” and writes to SESSION.md instead. It’s like a compiler error for documentation.

2. File Budgets Against Bloat

My shared conventions file (CONVENTIONS.md) started at 7 sections. Then I added LaTeX equation safety rules. Then Google Calendar MCP rules. Then shared-repo Git workflow guards. Before I knew it: 13 sections.

The irony: CONVENTIONS.md exists to prevent context loss from autocompact. A bloated CONVENTIONS.md accelerates autocompact. A recursive problem.

The fix: split by domain

I moved domain-specific rules to separate files:

claude-config/
├── CONVENTIONS.md      # universal rules (down to 6 sections)
└── conventions/
    ├── latex.md        # equation safety, compiler settings
    ├── mcp.md          # MCP connector rules
    └── shared-repo.md  # multi-author Git workflow

A physics paper repo references conventions/latex.md. A web app repo doesn’t. Simple, but it cut CONVENTIONS.md in half.

SESSION.md gets a budget too

SESSION.md is a work log that Claude updates automatically. Without limits, it grows into a 200-line memoir of every completed task and implementation detail. But its only job is to answer one question after autocompact: “Where was I?”

I set a budget of ~80 lines and made Claude do housekeeping on every push:

• Completed tasks: delete (they’re in git log)
• Implementation details: delete (they’re in commit messages)
• Permanent decisions: move to CLAUDE.md, delete from SESSION.md

This happens automatically. I don’t think about it.

3. Catching Documentation Drift with a 4-Axis Review

SESSION.md says “4 data sources.” Actual count: 6.
CLAUDE.md says “images go in img/.” They moved to assets/ weeks ago.
README references “section 9.” It’s section 5 now.

Documentation rots the moment you write it. I had a “check before push” rule, but it was too vague. “Looks fine” is not a review.

The fix: four explicit axes

Before every git push, Claude runs a structured review:

The invocation is just:

“Check consistency, non-contradiction, and efficiency. Push.”

For public repos, add safety.

This catches things every single time. Today, while rewriting the README for claude-config, it found three issues:

1. Step numbering mismatch between CLAUDE.md (“1, 1b, 2-6”) and README (“1-7”)
2. A missing “external references” entry in a decision table
3. A code example referencing old section “section 9” (now section 5)

All fixed before push. A human reviewer would probably miss at least two of these.

Bonus: LaTeX Unicode Auto-Fix

If you work with collaborators who use Word, you know the pain: curly quotes and em-dashes sneak into .bib files and BibTeX chokes. I wrote a pre-commit hook that auto-converts Unicode to LaTeX commands on every commit. setup.sh detects LaTeX repos and installs it automatically. One less reason to dread bibtex errors at 2 AM.

The Meta-Lesson

Every fix follows the same pattern: I stopped telling Claude what to do and started building mechanisms that make the wrong thing impossible (or at least detectable).

• Hooks make wrong writes impossible
• Budgets make bloat self-correcting
• Structured reviews make drift detectable

None of these require me to remember anything. Claude enforces them on itself, every time, without getting bored or distracted.

The first article in this series was about making Claude manage its own memory. This one is about making Claude manage its own quality. The principle is the same: if you want reliability from an AI tool, don’t rely on yourself to enforce it. Build the guardrail into the workflow and let the AI run into it.

Repo: odakin/claude-config

Previous articles:

• Solving Claude Code’s Memory Loss
• 7 Phrases That Make Claude Code Actually Reliable