I ran the same code review with Claude twice.
First time: caught the SQL injection, mentioned "separation of concerns".
Second time: focused on naming conventions, missed the injection entirely.
Same code. Same model. Completely different results.
That's the problem I set out to fix — and it took 12 classic engineering books to do it.
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 that diagnoses code against six decay risk dimensions synthesized from 12 classic engineering books, producing structured findings with book citations, severity labels, and concrete remedies every time.
The Six 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
Four Modes
/brooks-review — PR-level code review
/brooks-audit — Architecture audit with Mermaid dependency graph
/brooks-debt — Tech debt assessment with prioritized roadmap
/brooks-test — Test suite health review (6 test decay risks)
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.
Installation
Via Claude Code Plugin Marketplace:
/plugin marketplace add hyhmrright/brooks-lint
Also works with Gemini CLI and Codex CLI. MIT licensed, free to use.
GitHub: https://github.com/hyhmrright/brooks-lint
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.
Top comments (0)