DEV Community

hyhmrright
hyhmrright

Posted on

I built a Claude Code plugin that reviews code using The Mythical Man-Month

#claudecode #showdev #ai #softwareengineering

The Problem: AI Writes Code, But Who Reviews the Architecture?

Claude Code is great at writing code. It can implement features, fix bugs, and refactor functions quickly. But there's a gap: AI-generated code can accumulate the same architectural problems that human-written code does — and sometimes faster, because AI doesn't have the institutional memory to know why certain patterns were avoided.

I wanted a way to have Claude review its own work through the lens of classic software engineering principles. So I built brooks-lint — a Claude Code plugin that diagnoses code quality using six foundational SE books.

What It Does

brooks-lint gives Claude a structured framework for code review based on these six books:

  • The Mythical Man-Month (Brooks) — conceptual integrity, communication overhead
  • Clean Code (Martin) — naming, function design, comments
  • A Philosophy of Software Design (Ousterhout) — deep modules, information hiding
  • Working Effectively with Legacy Code (Feathers) — seam detection, test coverage
  • xUnit Test Patterns (Meszaros) — test smells, fixture design
  • The Art of Unit Testing (Osherove) — test maintainability, mock discipline

Every finding follows the Iron Law:

Symptom → Source → Consequence → Remedy

No finding without a consequence and a remedy. This prevents the common failure mode of code reviews that just list rule violations without explaining why they matter.

Four Review Modes

Mode 1: PR Review — Review a diff or set of files for the six decay risks:

  • Cognitive Overload
  • Change Propagation
  • Knowledge Duplication
  • Accidental Complexity
  • Dependency Disorder
  • Domain Model Distortion

Mode 2: Architecture Audit — Draw the module dependency map, check for Conway's Law violations, identify structural decay.

Mode 3: Tech Debt Assessment — Score all six decay risks, prioritize by a Pain × Spread formula, output a Debt Summary Table.

Mode 4: Test Quality Review — Analyze test suites for anti-patterns like Fragile Tests, Logic in Tests, Mystery Guests, and Mock Overuse.

Example Output 

## Findings

### 🔴 Critical

**Change Propagation — Payment logic split across three layers**
Symptom: `calculateTotal()` in CartService calls `applyDiscount()` in PricingEngine
which reads `membershipTier` from UserRepository — three hops for one business rule.
Source: A Philosophy of Software Design — Deep Modules
Consequence: Any change to discount logic requires coordinating three files and risks
breaking the cart, pricing, and user data layers simultaneously.
Remedy: Consolidate discount calculation into a single PricingService that owns all
inputs; inject it into CartService as a dependency.
Enter fullscreen mode Exit fullscreen mode

Health Score

Each review produces a score (0–100):

  • 🔴 Critical finding: −15
  • 🟡 Warning: −5
  • 🟢 Suggestion: −1

Install 

/plugin marketplace add hyhmrright/brooks-lint
/plugin install brooks-lint@brooks-lint-marketplace
Enter fullscreen mode Exit fullscreen mode

Then trigger it with:

  • /brooks-lint:brooks-review — PR review
  • /brooks-lint:brooks-audit — architecture audit
  • /brooks-lint:brooks-debt — tech debt assessment
  • /brooks-lint:brooks-test — test quality review

Or just ask Claude to "review this code" and it auto-detects the mode.

Why Book-Grounded Reviews?

I got tired of AI code reviews that say "this function is too long" without explaining what breaks when it isn't fixed. Grounding findings in specific books and named principles forces the review to explain source and consequence, not just pattern-match against a style guide.

It also makes the feedback more memorable. "This violates Ousterhout's deep module principle" carries more weight than "consider refactoring this."

Source: github.com/hyhmrright/brooks-lint

Feedback welcome — especially if you've tried using it on a real codebase and found patterns it misses.

Top comments (0)