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
brooks-lint reviewing code: a /brooks-review command produces a 28/100 health score and cited Symptom → Source → Consequence → Remedy findings
12classic books
12decay risks (R1–R6 · T1–T6)
94%benchmark pass rate
6independent 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→Remedy100%0%
Book citation per finding100%0%
Consistent severity labels 🔴🟡🟢100%0%
Health Score (0–100)100%0%
Overall pass rate94%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 ⭐