Claude Code · Codex · Gemini plugin

# AI code reviews grounded in twelve classic engineering books

Most tools count lines and complexity. brooks-lint diagnoses your code against twelve decay risks synthesized from the classics — every finding cited, scored, and remedied.

> “The bearing of a child takes nine months, no matter how many women are assigned.” — Frederick Brooks, The Mythical Man-Month (1975)

Get Started View on GitHub
12 classic books
12 decay risks (R1–R6 · T1–T6)
94%benchmark pass rate
6 independent skills

## Not a linter. A second opinion from the canon.

Linters catch syntax. brooks-lint catches architectural drift, knowledge silos, and domain distortion — the slow problems that cost teams months.

⚖️

### The Iron Law

Every finding follows one shape: Symptom → Source → Consequence → Remedy. No vague vibes, ever.

📚

### Cited to the books

Brooks, Fowler, Martin, Ousterhout, Evans, Feathers, Meszaros and more — each finding names the author and principle.

🎯

### Six focused skills

PR Review, Architecture Audit, Tech Debt, Test Quality, Health Dashboard, and a Full Sweep that auto-fixes.

🔌

### Zero config, any language

Works in Claude Code, Codex CLI, and Gemini CLI. No plugins to wire up, no language limits.

## The Six Production Decay Risks

Synthesized from the twelve books. Six more (T1–T6) cover test-suite decay.

R1

### 🧠 Cognitive Overload

How much mental effort does it take to understand this?

Code Complete · Refactoring · DDD · Philosophy of SD
R2

### 🔗 Change Propagation

How many unrelated things break on one change?

Refactoring · Clean Architecture · Pragmatic · SE@Google
R3

### 📋 Knowledge Duplication

Is the same decision expressed in multiple places?

Pragmatic · Refactoring · DDD
R4

### 🌀 Accidental Complexity

Is the code more complex than the problem itself?

Refactoring · Code Complete · Brooks · Philosophy of SD
R5

### 🏗️ Dependency Disorder

Do dependencies flow in a consistent direction?

Clean Architecture · Brooks · Pragmatic · SE@Google
R6

### 🗺️ Domain Model Distortion

Does the code faithfully represent the domain?

DDD · Refactoring

## What a finding looks like

Same messy method, two of the eight findings brooks-lint produces — each one cited and actionable.

Health Score: 28/100
This method concentrates four unrelated business responsibilities, hides a logic bug that silently suppresses email notifications, and is wide open to SQL injection.

#### 🔴 R2 — One method changes for four unrelated reasons

Symptom: update_profile does field updates, email notifications, loyalty recalculation, and cache invalidation in one body.
Source: Fowler — Refactoring — Divergent Change; Hunt & Thomas — Orthogonality
Consequence: A change to the loyalty formula risks breaking email notifications. Every edit carries regression risk across four domains.
Remedy: Extract NotificationService, LoyaltyService, UserCacheInvalidator. update_profile should orchestrate, not implement.

#### 🔴 R6 — Silent logic bug: notification never fires

Symptom: user['email'] = email runs before if user['email'] != email — the condition is always False, the code is dead.
Source: McConnell — Code Complete — Ch. 17: Unusual Control Structures
Consequence: Users are never notified when their email changes. A business rule is silently violated while the system looks fine.
Remedy: Capture old_email before any mutation. Compare against old_email, not the already-overwritten value.

## Consistency is the point

Tested across PR review, architecture audit, and tech debt scenarios. The gap isn't what Claude can find — it's what it finds every single time, with evidence.

Criterion | brooks-lint | Claude alone
--- | --- | ---
Structured Symptom→Source→Consequence→Remedy | 100% | 0%
Book citation per finding | 100% | 0%
Consistent severity labels 🔴🟡🟢 | 100% | 0%
Health Score (0–100) | 100% | 0%
Overall pass rate | 94% | 16%

## Standing on twelve giants

The decay risks are our synthesis of their ideas, applied to modern code quality.

The Mythical Man-Month · Brooks Code Complete · McConnell Refactoring · Fowler Clean Architecture · Martin The Pragmatic Programmer · Hunt & Thomas Domain-Driven Design · Evans A Philosophy of Software Design · Ousterhout Software Engineering at Google · Winters et al. The Art of Unit Testing · Osherove How Google Tests Software · Whittaker et al. Working Effectively with Legacy Code · Feathers xUnit Test Patterns · Meszaros

## Get started in seconds

Pick your tool. Then just ask it to review your code, audit your architecture, or assess tech debt.

Claude Code
# add the marketplace, then install /plugin marketplace add hyhmrright/brooks-lint /plugin install brooks-lint@brooks-lint-marketplace
Gemini CLI
/extensions install https://github.com/hyhmrright/brooks-lint
Codex CLI
# just say this in a Codex session Install the brooks-lint skill from hyhmrright/brooks-lint
Then, in any session:
/brooks-review # or /brooks-audit · /brooks-debt · /brooks-test · /brooks-health · /brooks-sweep
Star on GitHub ⭐