Most linters tell you what is wrong.
None of them tell you why — in a way that makes you think differently about the code.
So I built one that does.
The problem with existing tools
ESLint flags unused variables. Complexity checkers count branches. SonarQube tracks duplication percentages.
All useful. But none of them answer the question a senior engineer would ask:
"What architectural principle is this violating, and what happens if we ignore it?"
I've spent years reading the classics — Fowler, Martin, Evans, Brooks, Ousterhout, McConnell. Each book has a chapter or two that makes you think "I've seen this exact failure before." But the insight stays locked in the book.
I wanted a tool that thinks the same way.
What brooks-lint does differently
brooks-lint is an AI code review plugin for Claude Code, Codex CLI, and Gemini CLI. It diagnoses code against six decay risk dimensions synthesized from twelve classic engineering books.
Every finding follows the Iron Law:
Symptom → Source → Consequence → Remedy
Not just "this is bad." Here's what bad looks like, here's which book explains why, here's what breaks if you ignore it, and here's how to fix it.
A real example
Here's a PaymentProcessor class that processes payments, handles fraud, manages inventory, and sends notifications — all in one method:
class PaymentProcessor {
constructor(
private db: Database,
private stripe: StripeClient,
private mailer: MailService,
private inventory: InventoryService,
private analytics: AnalyticsService,
private taxCalc: TaxCalculator,
private fraudDetection: FraudService
) {}
async processPayment(orderId: string, cardToken: string) {
// 60+ lines of interleaved fraud, inventory, payment, and notification logic
}
}
Here's what brooks-lint returned:
Health Score: 55/100
🔴 Change Propagation — Seven-service constructor signals a God Class in formation
Symptom: PaymentProcessor injects seven dependencies into a single class. The single processPayment method directly orchestrates all seven.
Source: Fowler — Refactoring — Divergent Change; Martin — Clean Architecture — Single Responsibility Principle
Consequence: This class will change for at least four independent reasons: fraud policy changes, inventory logic changes, tax rule changes, and notification content changes. Each change is a merge conflict waiting to happen.
Remedy: Decompose into focused collaborators. Introduce a FraudCheckService, an InventoryDeductionService, and a PaymentNotifier. PaymentProcessor then injects 3 services, not 7.
🟡 Knowledge Duplication — order.total + tax computed three times
Symptom: The expression order.total + tax appears on three separate lines with no shared name.
Source: Hunt & Thomas — The Pragmatic Programmer — DRY; Fowler — Refactoring — Duplicate Code
Consequence: If tax calculation logic changes, all three sites must be updated in sync. Missing one produces a financial inconsistency bug.
Remedy: Assign const totalWithTax = order.total + tax; immediately after tax calculation. Better still, let Order expose a computed get grandTotal() property.
Notice the difference from a typical linter? You get the book citation, the exact consequence, and a concrete remedy — not just a rule ID.
The six decay risks
After synthesizing twelve books, six patterns kept appearing as root causes of software decay:
| Code | Risk | Core Insight |
|---|---|---|
| R1 | Cognitive Overload | Mental load exceeds working memory → mistakes and avoidance |
| R2 | Change Propagation | One change forces unrelated changes elsewhere |
| R3 | Knowledge Duplication | Same fact in two places → they diverge |
| R4 | Responsibility Rot | One module does too many things |
| R5 | Dependency Disorder | Modules depend on modules that depend on modules... |
| R6 | Domain Model Distortion | Code doesn't speak the business's language |
There are also six test-space variants (T1–T6) covering test brittleness, mock abuse, coverage theater, and more.
The twelve books
| Book | Author | Risks |
|---|---|---|
| The Mythical Man-Month | Frederick Brooks | R2, R4, R5 |
| Code Complete | Steve McConnell | R1, R4 |
| Refactoring | Martin Fowler | R1, R2, R3, R4, R6 |
| Clean Architecture | Robert C. Martin | R2, R5 |
| The Pragmatic Programmer | Hunt & Thomas | R2, R3, R4, R5, T2, T3 |
| Domain-Driven Design | Eric Evans | R1, R3, R6 |
| A Philosophy of Software Design | Ousterhout | R1, R4 |
| Software Engineering at Google | Winters et al. | R2, R5 |
| xUnit Test Patterns | Meszaros | T1, T2, T4 |
| The Art of Unit Testing | Osherove | T1, T2, T3 |
| Working Effectively with Legacy Code | Feathers | T3, T4, T5 |
| Unit Testing: Principles, Practices, Patterns | Khorikov | T1, T2, T6 |
Five review modes
/brooks-review → PR code review (diff-focused)
/brooks-audit → Architecture audit
/brooks-debt → Tech debt assessment
/brooks-test → Test quality review
/brooks-health → Codebase health dashboard with score
Works on Claude Code, Codex CLI, and Gemini CLI.
Install
# Claude Code (one command)
/plugin install brooks-lint@brooks-lint-marketplace
# Codex CLI
codex plugin install hyhmrright/brooks-lint
# Gemini CLI
gemini extension install hyhmrright/brooks-lint
Or grab the source: github.com/hyhmrright/brooks-lint
What I learned building it
The books agree more than they disagree. Fowler's Divergent Change smell, Martin's Single Responsibility Principle, and Evans's Bounded Context are all describing the same underlying failure from different angles.
The hard part wasn't synthesizing the principles — it was writing the false-positive guards. A 60-line function in a data migration script isn't the same as a 60-line function in a payment handler. The tool needed to know when not to flag something, which required reading the exception clauses in each book more carefully than I'd expected.
The benchmark suite now has 49 scenarios, including explicit false-positive cases that must not be flagged. That's probably the most useful artifact I built — it forces the skill to be calibrated, not just pattern-matching.
If you've read any of the twelve books and found yourself wishing you could apply that insight systematically — that's what this is for.
Let's discuss
Which of these six decay risks do you see most often in your codebase?
- R1 · Cognitive Overload — functions too long or complex to reason about
- R2 · Change Propagation — touching one thing breaks five others
- R3 · Knowledge Duplication — the same fact lives in multiple places
- R4 · Responsibility Rot — one class that does everything
- R5 · Dependency Disorder — import chains that go on forever
- R6 · Domain Model Distortion — code that doesn't speak the business's language
Drop your answer in the comments. If you share a concrete example, I'll run brooks-lint on it and post the output here.
Try it:
# Claude Code
/plugin install brooks-lint@brooks-lint-marketplace
Top comments (0)