DEV Community

hyhmrright
hyhmrright

Posted on

caveman + brooks-lint + logic-lens: The Complete AI Code Review Stack for Claude

#claudeai #codereview #webdev #ai

If you use Claude Code regularly, you've probably heard of caveman — the skill that makes Claude talk like a caveman to cut token usage by 65%. It's brilliant in its simplicity and has earned 49k+ stars for good reason.

But here's a question I started asking myself: what happens after caveman helps Claude think faster and cheaper? Who's actually reviewing the quality of what gets written?

That's the gap I built two new Claude skills to fill. Let me show you how all three tools work together as a complete AI-assisted development stack.

Quick Recap: What caveman Does

caveman is a Claude Code skill that compresses Claude's internal monologue. Instead of verbose reasoning, Claude thinks in primitive shorthand — and uses 65% fewer tokens doing it.

It's a token optimizer. It makes Claude faster and cheaper without changing the quality of what it produces.

What it doesn't do: caveman doesn't review whether your code has architectural debt, logic errors, or violates established software engineering principles. That's not its job — and that's exactly where brooks-lint and logic-lens come in.

The Two Skills That Complete the Stack

1. brooks-lint — The Architectural Review Layer

brooks-lint is a Claude skill that reviews code through the lens of 12 classic software engineering books:

Category Books
Complexity & Design A Philosophy of Software Design, Clean Code, Refactoring
Architecture Clean Architecture, Designing Data-Intensive Applications
Team & Process The Mythical Man-Month, The Pragmatic Programmer
Reliability Release It!, Site Reliability Engineering
Security & Quality The Art of Software Security, Accelerate, Software Engineering at Google

It maps problems to 6 risk categories (R1–R6):

  • R1 – Accidental Complexity (Ousterhout)
  • R2 – Rotting Design (Fowler — needs refactoring)
  • R3 – Mythical Man-Month risk (Brooks — hidden coordination cost)
  • R4 – Pragmatic debt (Hunt & Thomas — quick fixes that compound)
  • R5 – Release risk (Nygard — production reliability issues)
  • R6 – Security concern (Viega & McGraw)

Real example — what it catches:

/brooks-review src/payment/PaymentService.ts

Reviewing 847 lines...

⚠️ R1 – ACCIDENTAL COMPLEXITY (HIGH)
PaymentService handles: payment processing, retry logic, 
notifications, audit logging, and fraud detection.
God class with 5 responsibilities. Split into focused services.

⚠️ R2 – ROTTING DESIGN (MEDIUM)  
processPayment() is 340 lines with 6 nesting levels.
Feature envy: reaching into Order internals 12 times.
Refactoring opportunity: extract PaymentValidator.

⚠️ R5 – RELEASE RISK (HIGH)
No circuit breaker on payment gateway calls.
Retry loop can cascade during gateway outages.
Enter fullscreen mode Exit fullscreen mode

5 usage modes:

/brooks-review file.ts        # Full architectural review
/brooks-quick file.ts         # Fast scan, critical issues only
/brooks-refactor file.ts      # Refactoring suggestions
/brooks-security file.ts      # Security-focused review
/brooks-compare v1.ts v2.ts   # Before/after comparison
Enter fullscreen mode Exit fullscreen mode

2. logic-lens — The Logic & Correctness Layer

logic-lens is a Claude skill that focuses on runtime correctness — the things that compile fine but fail in production:

/logic-lens src/order/OrderProcessor.ts

Analyzing logic patterns...

🔴 CRITICAL – NULL DEREFERENCE (Line 47)
user.address.city accessed without null check.
If user has no address (guest checkout), NullPointerException.
Fix: use optional chaining user.address?.city ?? 'Unknown'

🔴 CRITICAL – RACE CONDITION (Line 103)  
inventory.count checked then decremented in separate operations.
Under concurrent load, two threads can both pass the check.
Fix: Use atomic decrement with minimum-value guard

🟡 MEDIUM – OFF-BY-ONE (Line 156)
Loop runs i <= items.length instead of i < items.length
Will throw ArrayIndexOutOfBoundsException on last iteration

🟡 MEDIUM – SILENT FAILURE (Line 203)
try/catch swallows exception with empty catch block
Payment failures will be silently ignored
Enter fullscreen mode Exit fullscreen mode

logic-lens covers 9 risk categories across 49 scenario types: null/undefined access, race conditions, integer overflow, SQL injection, memory leaks, auth bypass, state machine violations, and more.

How the Three Tools Work Together

Here's the workflow I've settled into:

caveman → [Claude writes code faster & cheaper]
    ↓
/brooks-review → [Is the architecture sound?]
    ↓
/logic-lens → [Will it actually work correctly at runtime?]
Enter fullscreen mode Exit fullscreen mode

Think of it as three layers of defense:

  1. caveman — Efficiency layer. Saves tokens, speeds up iteration.
  2. brooks-lint — Architecture layer. Catches structural problems inspired by engineering classics.
  3. logic-lens — Correctness layer. Catches runtime bugs before they reach production.

A Real Workflow Example 

# Step 1: Use caveman for fast, cheap code generation
# (caveman handles this automatically in background)

# Step 2: Check architectural integrity
/brooks-review src/checkout/CheckoutService.ts

# Step 3: Verify runtime correctness
/logic-lens src/checkout/CheckoutService.ts

# Result: Code that's architecturally sound AND logically correct
Enter fullscreen mode Exit fullscreen mode

Why These Tools Are Complementary (Not Overlapping)

Tool Focus Catches
caveman Token efficiency Nothing — it optimizes Claude's thinking
brooks-lint Architecture & design God classes, tight coupling, missing patterns, technical debt
logic-lens Runtime correctness Null refs, race conditions, off-by-ones, auth gaps

There's almost zero overlap. Each tool catches a completely different class of problems.

Installation

All three are Claude Code skills — install in seconds:

# caveman (token optimization)
claude mcp add caveman

# brooks-lint (architectural review)
claude skills add https://github.com/hyhmrright/brooks-lint

# logic-lens (logic & correctness)
claude skills add https://github.com/hyhmrright/logic-lens
Enter fullscreen mode Exit fullscreen mode

The Bottom Line

caveman makes Claude think faster. But fast + cheap code that has architectural debt and runtime bugs is still problematic code.

With all three tools in your Claude Code setup:

  • You write code 65% cheaper (caveman)
  • Your architecture stays sound (brooks-lint: 12 books, R1–R6 categories)
  • Your logic stays correct (logic-lens: 49 runtime scenarios)

That's the complete stack. Try all three and let me know what you catch in your codebase.

Built both skills with Claude Code. Happy to answer questions about the implementation in the comments.

Links:

  • caveman (the original — 49k stars, highly recommended)
  • brooks-lint — architectural review grounded in 12 books
  • logic-lens — runtime correctness across 49 scenarios

Top comments (0)