DEV Community: hyhmrright

Show DEV: brooks-lint — an AI code reviewer that cites Fowler, Martin, and Brooks

hyhmrright — Thu, 16 Apr 2026 16:20:33 +0000

I gave an AI code reviewer a PaymentProcessor class — seven services injected, payment + fraud + inventory + notifications all in one 60-line method.

Here's what it flagged:

🔴 Change Propagation — Seven-service constructor signals a God Class in formation

Source: Fowler — Refactoring — Divergent Change; Martin — Clean Architecture — SRP

Consequence: This class will change for at least four independent reasons. Each change is a merge conflict waiting to happen.

Remedy: Introduce FraudCheckService, InventoryDeductionService, PaymentNotifier. PaymentProcessor then injects 3 services, not 7.

Not "this is bad." Here's which book explains why, what breaks if you ignore it, and how to fix it.

That's brooks-lint — an open-source plugin for Claude Code, Codex CLI, and Gemini CLI. github.com/hyhmrright/brooks-lint · MIT · v1.0.0 shipped this week.

Why I built it

ESLint flags unused variables. Complexity checkers count branches. SonarQube tracks duplication percentages. All useful. None of them answer the question a senior engineer actually asks:

"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 that makes you think "I've seen this exact failure before." But the insight stays locked in the book.

brooks-lint is an attempt to make that insight executable. Every finding follows the same shape:

Symptom → Source → Consequence → Remedy

Symptom is what the linter sees. Source is the book + chapter it comes from. Consequence is what breaks in six months if you ignore it. Remedy is a concrete refactor.

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

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.

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

Source: github.com/hyhmrright/brooks-lint

The hard part wasn't the principles — it was the false positives

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 meant 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.

I'd love your help

v1.0 is out, but a linter grounded in books is only as good as the communities that stress-test it. Three specific ways you can help:

Try it on a real repo and open an issue if a finding feels wrong — false positives are the highest-priority bug class.
Propose a 13th book. If there's a classic that covers a failure mode R1–R6 misses, tell me which chapter and I'll prototype the rule.
Share a code smell you see constantly in the comments. I'll run brooks-lint on a representative example and post the raw output as a reply.

Star if it resonates: ⭐ github.com/hyhmrright/brooks-lint

Which of the six risks (R1–R6) do you hit most often? Drop a line below — happy to dig into specific examples.

I gave Claude the same code review twice. It missed a SQL injection the second time. So I encoded 12 engineering books into it.

hyhmrright — Wed, 15 Apr 2026 09:13:10 +0000

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

Fifty years later, Brooks was still right. And so was the rest of my shelf.

I ran the same code review with Claude twice.

First time: caught the SQL injection, flagged separation of concerns. Solid review.
Second time: focused on naming conventions. Missed the injection entirely.

Same code. Same model. Completely different results.

That's not a Claude problem. That's a consistency problem. And it's fixable — if you give the model a framework to work from.

So I encoded 12 classic engineering books into a Claude Code skill. Here's what happened.

The Problem

Most code quality tools count lines and cyclomatic complexity. That's useful, but it misses the deeper problems: architectural drift, knowledge silos, domain model distortion — the issues that slow teams down for months before anyone notices.

Meanwhile, the software engineering classics have had answers to these problems for decades. Brooks, Fowler, Martin, McConnell, Evans, Ousterhout — twelve books, fifty years of hard-won wisdom. The insights haven't changed. We just stopped encoding them consistently.

What I Built

brooks-lint is a Claude Code skill (also works with Gemini CLI and Codex CLI) that diagnoses code against twelve decay risk dimensions synthesized from 12 classic engineering books, producing structured findings with book citations, severity labels, and concrete remedies every time.

The 12 Books

Book	Author
The Mythical Man-Month	Frederick Brooks
Code Complete	Steve McConnell
Refactoring	Martin Fowler
Clean Architecture	Robert C. Martin
The Pragmatic Programmer	Hunt & Thomas
Domain-Driven Design	Eric Evans
A Philosophy of Software Design	John Ousterhout
Software Engineering at Google	Winters, Manshreck & Wright
xUnit Test Patterns	Gerard Meszaros
The Art of Unit Testing	Roy Osherove
How Google Tests Software	Whittaker, Arbon & Carollo
Working Effectively with Legacy Code	Michael Feathers

The Six Production Code Decay Risks

Risk	Diagnostic Question
🧠 Cognitive Overload	How much mental effort to understand this?
🔗 Change Propagation	How many unrelated things break on one change?
📋 Knowledge Duplication	Is the same decision expressed in multiple places?
🌀 Accidental Complexity	Is the code more complex than the problem?
🏗️ Dependency Disorder	Do dependencies flow in a consistent direction?
🗺️ Domain Model Distortion	Does the code faithfully represent the domain?

Every finding follows the same chain: Symptom → Source (book + chapter) → Consequence → Remedy

The Six Test-Suite Decay Risks (New in v0.5)

brooks-lint now also audits your test suite against six test-space decay risks sourced from xUnit Test Patterns, The Art of Unit Testing, How Google Tests Software, and Working Effectively with Legacy Code:

Risk	Diagnostic Question
🔍 Test Obscurity	Can you understand what this test verifies at a glance?
🧱 Test Brittleness	Does this test break when unrelated implementation details change?
📋 Test Duplication	Are the same scenarios covered in multiple places?
🎭 Mock Abuse	Are mocks hiding real design problems?
📊 Coverage Illusion	Does high coverage give false confidence?
🏗️ Architecture Mismatch	Do tests reflect the production architecture?

What It Looks Like

Given this code:

class UserService:
    def update_profile(self, user_id, name, email, avatar_url):
        user = self.db.query(f"SELECT * FROM users WHERE id = {user_id}")
        user['email'] = email
        if user['email'] != email:  # always False — silent bug
            self.smtp.send(...)
        points = user['login_count'] * 10 + 500
        self.db.execute(f"UPDATE loyalty SET points={points} WHERE user_id={user_id}")

brooks-lint produces:

Health Score: 28/100

🔴 Change Propagation — Single Method Changes for Four Unrelated Business Reasons
Symptom: update_profile performs profile updates, email notifications, loyalty
         points recalculation, and cache invalidation all in one method body.
Source:  Fowler — Refactoring — Divergent Change
         Hunt & Thomas — The Pragmatic Programmer — Orthogonality
Consequence: Any change to the loyalty formula risks breaking email notifications.
Remedy: Extract NotificationService, LoyaltyService, and UserCacheInvalidator.

🔴 Domain Model Distortion — Silent Logic Bug: Email Notification Never Fires
Symptom: user['email'] = email overwrites the old value before the comparison —
         the condition is always False. The notification is dead code.
Source:  McConnell — Code Complete — Ch. 17: Unusual Control Structures
Consequence: Users are never notified when their email address changes.
Remedy: Capture old_email = user['email'] before any mutation.

(+ 6 more findings including SQL injection, dependency disorder, magic numbers)

Architecture Audit with Dependency Graph (v0.6)

In Mode 2, brooks-lint generates a Mermaid dependency graph color-coded by severity — red = Critical, yellow = Warning, green = clean. It renders natively in GitHub, VS Code, and Notion.

Four Modes

Command	Short Form	Action
`/brooks-lint:brooks-review`	`/brooks-review`	PR-level code review
`/brooks-lint:brooks-audit`	`/brooks-audit`	Architecture audit with Mermaid dependency graph
`/brooks-lint:brooks-debt`	`/brooks-debt`	Tech debt assessment with prioritized roadmap
`/brooks-lint:brooks-test`	`/brooks-test`	Test suite health review

Benchmark Results

Tested across 3 real-world scenarios (PR review, architecture audit, tech debt):

Criterion	brooks-lint	Plain Claude
Structured findings	✅ 100%	❌ 0%
Book citations	✅ 100%	❌ 0%
Severity labels	✅ 100%	❌ 0%
Health Score (0–100)	✅ 100%	❌ 0%
Overall pass rate	94%	16%

The gap isn't what Claude can find — it's what it consistently finds, with traceable evidence and actionable remedies every time.

How It Compares

	brooks-lint	ESLint/Pylint	GitHub Copilot	Plain Claude
Structured diagnosis chain	✅	❌	❌	❌
Traces findings to classic books	✅	❌	❌	❌
Architecture-level insights	✅	❌	~	~
Domain model analysis	✅	❌	❌	~
Zero config, no plugins	✅	❌	✅	✅
Works with any language	✅	❌	✅	✅

brooks-lint doesn't replace your linter. It catches what linters can't.

Installation

Claude Code (Recommended)

/plugin marketplace add hyhmrright/brooks-lint

Gemini CLI

/extensions install https://github.com/hyhmrright/brooks-lint

Codex CLI

$brooks-review  # skills trigger automatically on code quality discussions

Manual Install

cp commands/*.md ~/.claude/commands/
cp -r skills/ ~/.claude/skills/brooks-lint

Configuration (v0.7)

Place a .brooks-lint.yaml in your project root to customize behavior:

version: 1
disable:
  - T5  # skip coverage metrics check
severity:
  R1: suggestion  # downgrade Cognitive Overload for this domain
ignore:
  - "**/*.generated.*"
  - "**/vendor/**"

GitHub: https://github.com/hyhmrright/brooks-lint — MIT licensed, free to use.

AI can help you write code faster, but it can't tell you whether you're building a cathedral or a tar pit. brooks-lint bridges that gap.

If you've used AI for code reviews, I'm curious: what's your biggest frustration with consistency? Drop it in the comments — I'd love to hear what decay risks you're seeing most.

If this was useful, a ❤️ or unicorn helps others find it.

I built a Claude Code plugin that anchors code reviews to 6 classic SE books

hyhmrright — Mon, 30 Mar 2026 12:49:28 +0000

If you've used Claude Code for code reviews, you've probably noticed something: the feedback is smart, but it's vague. "This function is too long." "Consider breaking this up." Great — but why? And what's the actual risk if you don't?

I built brooks-lint to fix this. It's a Claude Code plugin that anchors every finding to a specific chapter in one of six classic software engineering books.

The Problem with AI Code Reviews

Generic AI reviews are good at spotting syntax issues and surface-level smells. But they struggle to explain consequence — why a particular pattern is dangerous in the long run, not just aesthetically displeasing.

The result: developers nod, maybe fix the obvious stuff, and move on. The deeper structural decay continues.

What brooks-lint Does Differently

Every finding follows a four-part structure I call the Iron Law:

Symptom   → what the code is doing
Source    → which book + chapter describes this exact pattern
Consequence → what breaks if you ignore it
Remedy    → concrete fix

Example output:

Symptom: UserService has 847 lines and handles auth, billing, notifications, and user CRUD.

Source: Clean Architecture, Ch. 7 — SRP violation; responsibilities should have separate reasons to change.

Consequence: Any change to billing logic risks breaking auth; test isolation becomes impossible.

Remedy: Extract BillingService and NotificationService; keep UserService focused on identity only.

No vague advice. Just: here's the book, here's the chapter, here's exactly what goes wrong.

The Six Source Books

The plugin draws from six foundational texts:

Book	Focus
The Mythical Man-Month	Project complexity, conceptual integrity
Clean Code + Refactoring	Code-level smells and refactoring patterns
Clean Architecture	Dependency rules, component boundaries
Code Complete	Implementation craft, construction quality
The Pragmatic Programmer	DRY, orthogonality, adaptability
Domain-Driven Design	Ubiquitous language, bounded contexts

Four Review Modes

/brooks-lint:brooks-review   # PR review — what changed and what it risks
/brooks-lint:brooks-audit    # Architecture audit — structural health of the whole system
/brooks-lint:brooks-debt     # Tech debt — classify and prioritize what to fix
/brooks-lint:brooks-test     # Test quality — coverage gaps, fragile tests, wrong abstractions

The test quality mode (brooks-test) draws from xUnit Test Patterns, The Art of Unit Testing, and Google's Software Engineering book — it flags things like over-mocking, test logic duplication, and tests that verify implementation instead of behavior.

Eval Results

I ran an evaluation comparing reviews with and without the plugin on a set of intentionally seeded codebases:

94% of findings included a book citation and structured consequence analysis with the plugin
16% of findings had equivalent depth without it

The plugin doesn't make Claude smarter — it makes Claude accountable. When every finding has to cite a chapter, hand-wavy feedback can't survive.

Install

# Via plugin marketplace (recommended)
/plugin marketplace add hyhmrright/brooks-lint
/plugin install brooks-lint@brooks-lint-marketplace

# Manual
cp -r skills/brooks-lint/ ~/.claude/skills/brooks-lint

Why "Brooks"?

Fred Brooks wrote The Mythical Man-Month in 1975. Most of what he described — conceptual integrity, the second-system effect, the surgical team model — still shows up every week in production code. The plugin is named after him as a reminder that the hard problems in software aren't new, and the best answers to them are already written down.

GitHub: hyhmrright/brooks-lint

Happy to answer questions about how the skill detection works or how I structured the decay risk taxonomy.

Update (March 2026): Now on Gemini CLI Too

brooks-lint v0.5.2 now supports Gemini CLI as a first-class platform, in addition to Claude Code.

Gemini CLI install:

/extensions install https://github.com/hyhmrright/brooks-lint

Claude Code install:

/plugin marketplace add hyhmrright/brooks-lint
/plugin install brooks-lint@brooks-lint-marketplace

Both platforms use the same skill files — same decay risk framework, same Iron Law diagnostics, same book citations. The only difference is the entry point configuration. If you use both tools, one install covers both.

The extension is also listed on the official Gemini CLI extension gallery.