Forem: hyhmrright

brooks-lint v0.7.0: A Claude Code Plugin for Code Review Based on 10 Classic Engineering Books

hyhmrright — Mon, 06 Apr 2026 05:27:17 +0000

I built a Claude Code plugin that reviews your code through the lens of 10 classic software engineering books — and v0.7.0 just shipped.

What is brooks-lint?

brooks-lint diagnoses code quality by applying principles from books like Refactoring, Clean Code, Designing Data-Intensive Applications, A Philosophy of Software Design, and 6 more.

It surfaces decay risks across four modes:

PR Review — catch issues before merge
Architecture Audit — spot structural decay
Tech Debt Assessment — classify and prioritize debt
Test Quality Review — evaluate test health

Each finding follows the Iron Law: Symptom → Source → Consequence → Remedy, with a Health Score (base 100, deductions per finding).

What's new in v0.7.0

Project config (.brooks-lint.yaml)

Teams can now customize review behavior per project:

disable: [T3]            # skip coverage checks
severity:
  R1: suggestion         # downgrade severity
ignore: ["**/vendor/**"]
focus: [R1, R2, R3]     # evaluate only these risks

10-book framework

Expanded from 6 to 10 books, adding:

A Philosophy of Software Design — Ousterhout
Software Engineering at Google
Working Effectively with Legacy Code — Feathers
xUnit Test Patterns — Meszaros

Short-form commands

/brooks-review, /brooks-audit, /brooks-debt, /brooks-test — no namespace prefix needed.

The 6 decay risks

Code	Risk	Books
R1	Responsibility Creep	Clean Code, Refactoring
R2	Implicit Contract	Hyrum's Law
R3	Shallow Module	A Philosophy of Software Design
R4	Premature Generalization	Mythical Man-Month
R5	Test-Prod Divergence	xUnit Test Patterns
R6	Consistency Erosion	Software Engineering at Google

Plus 6 test-space decay risks (T1–T6) for the Test Quality Review mode.

Install

# Via Claude Code plugin marketplace
/plugin marketplace add hyhmrright/brooks-lint
/plugin install brooks-lint@brooks-lint-marketplace

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.

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

hyhmrright — Sun, 29 Mar 2026 04:55:17 +0000

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.

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

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.

Forem: hyhmrright

brooks-lint v0.7.0: A Claude Code Plugin for Code Review Based on 10 Classic Engineering Books

What is brooks-lint?

What's new in v0.7.0

Project config (.brooks-lint.yaml)

10-book framework

Short-form commands

The 6 decay risks

Install

Links

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

The Problem with AI Code Reviews

What brooks-lint Does Differently

The Six Source Books

Four Review Modes

Eval Results

Install

Why "Brooks"?

Update (March 2026): Now on Gemini CLI Too

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

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

What It Does

Four Review Modes

Example Output

Health Score

Install

Why Book-Grounded Reviews?