brooks-lint

AI code reviews grounded in six classic engineering books.
Consistent. Traceable. Actionable.

The Six Decay Risks • What It Looks Like • Benchmark • Installation

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

50 years later, Brooks was still right — and so were McConnell, Fowler, Martin, Hunt & Thomas, and Evans.

Most code quality tools count lines and cyclomatic complexity. brooks-lint goes deeper — it diagnoses your code against six decay risk dimensions synthesized from six classic engineering books, producing structured findings with book citations, severity labels, and concrete remedies every time.

The Six Decay Risks

brooks-lint evaluates your code across six decay risk dimensions synthesized from six classic engineering books:

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

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

This method concentrates four unrelated business responsibilities into a single function, contains a logic bug that silently suppresses email change notifications, and is wide open to SQL injection.

🔴 Change Propagation — Single Method Changes for Four Unrelated Business Reasons

Symptom: update_profile performs profile field updates, email change 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 and vice versa. Every edit carries regression risk across four unrelated domains simultaneously. Remedy: Extract NotificationService, LoyaltyService, and UserCacheInvalidator. UserService.update_profile should orchestrate by calling each — it should hold no implementation logic itself.

🔴 Domain Model Distortion — Silent Logic Bug: Email Notification Never Fires

Symptom: user['email'] = email overwrites the old value before if user['email'] != email — 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. Silent data integrity failure — the system appears functional while violating a business rule. Remedy: Capture old_email = user['email'] before any mutation. Compare against old_email, not user['email'].

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

Architecture Audit with Dependency Graph

In Mode 2 (Architecture Audit), brooks-lint generates a Mermaid dependency graph at the top of the report. Modules are color-coded by severity: red = Critical findings, yellow = Warning, green = clean.

graph TD
    subgraph src/api
        AuthController
        UserController
    end
    subgraph src/domain
        UserService
        OrderService
    end
    subgraph src/infra
        Database
        EmailClient
    end

    AuthController --> UserService
    UserController --> UserService
    UserController --> OrderService
    OrderService --> UserService
    OrderService --> EmailClient
    UserService --> Database
    EmailClient -.->|circular| OrderService

    classDef critical fill:#ff6b6b,stroke:#c92a2a,color:#fff
    classDef warning fill:#ffd43b,stroke:#e67700
    classDef clean fill:#51cf66,stroke:#2b8a3e,color:#fff

    class OrderService,EmailClient critical
    class AuthController warning
    class UserService,UserController,Database clean

The graph renders natively in GitHub, VS Code, and Notion — no extra tools needed.

See More Examples

The Full Gallery has real brooks-lint output across Python, TypeScript, Go, and Java — including PR reviews, architecture audits with Mermaid dependency graphs, tech debt assessments, and test quality reviews.

Benchmark

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

Criterion	brooks-lint	Claude alone
Structured findings (Symptom → Source → Consequence → Remedy)	✅ 100%	❌ 0%
Book citations per finding	✅ 100%	❌ 0%
Severity labels (🔴/🟡/🟢)	✅ 100%	❌ 0%
Health Score (0–100)	✅ 100%	❌ 0%
Detects Change Propagation	✅ 100%	✅ 100%
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 Review	Plain Claude
Detects syntax & style issues	—	✅	✅	~
Structured diagnosis chain	✅	❌	❌	❌
Traces findings to classic books	✅	❌	❌	❌
Consistent severity labels	✅	✅	~	❌
Architecture-level insights	✅	❌	~	~
Domain model analysis	✅	❌	❌	~
Zero config, no plugins to install	✅	❌	✅	✅
Works with any language	✅	❌	✅	✅

~ = occasionally / inconsistently

brooks-lint doesn't replace your linter. It catches what linters can't: architectural drift, knowledge silos, and domain model distortion — the problems that slow teams down for months before anyone notices.

Installation

Claude Code (Recommended)

Via Plugin Marketplace

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

Manual Install

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

Gemini CLI

Via Extension

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

Manual Install

cp -r skills/brooks-lint ~/.gemini/skills/brooks-lint

Codex CLI

Via Skill Installer (in Codex session)

Install the brooks-lint skill from hyhmrright/brooks-lint

Command Line

python3 ~/.codex/skills/.system/skill-installer/scripts/install-skill-from-github.py \
  --repo hyhmrright/brooks-lint --path skills/brooks-lint --name brooks-lint

Manual Install

git clone https://github.com/hyhmrright/brooks-lint.git /tmp/brooks-lint
mkdir -p ~/.codex/skills/brooks-lint
cp -r /tmp/brooks-lint/skills/brooks-lint/* ~/.codex/skills/brooks-lint/

Slash Commands

Claude Code

Command	Action
`/brooks-lint:brooks-review`	PR-level code review
`/brooks-lint:brooks-audit`	Full architecture audit
`/brooks-lint:brooks-debt`	Tech debt assessment
`/brooks-lint:brooks-test`	Test suite health review

Gemini CLI

Command	Action
`/brooks-review`	PR-level code review
`/brooks-audit`	Full architecture audit
`/brooks-debt`	Tech debt assessment
`/brooks-test`	Test suite health review

Codex CLI

Activate the skill with $brooks-lint, then describe the task. Mode is auto-detected from context.

The skill also triggers automatically when you discuss code quality, architecture, maintainability, or test health.

Usage

PR Review

/brooks-lint:brooks-review          # Claude Code
/brooks-review                      # Gemini CLI
$brooks-lint                        # Codex CLI (then say "review this PR")

Paste a diff or point the AI at changed files. Diagnoses each of the six decay risks with specific findings in Symptom → Source → Consequence → Remedy format.

Architecture Audit

/brooks-lint:brooks-audit           # Claude Code
/brooks-audit                       # Gemini CLI
$brooks-lint                        # Codex CLI (then say "audit the architecture")

Describe your project structure or share key files. It maps module dependencies, identifies circular dependencies, and checks Conway's Law alignment.

Tech Debt Assessment

/brooks-lint:brooks-debt            # Claude Code
/brooks-debt                        # Gemini CLI
$brooks-lint                        # Codex CLI (then say "assess tech debt")

Classifies your debt across the six decay risks, scores each finding by Pain × Spread priority, and produces a prioritized repayment roadmap with Critical / Scheduled / Monitored classification.

Test Quality Review

/brooks-lint:brooks-test            # Claude Code
/brooks-test                        # Gemini CLI
$brooks-lint                        # Codex CLI (then say "review test quality")

Audits your test suite against six test-space decay risks — Test Obscurity, Test Brittleness, Test Duplication, Mock Abuse, Coverage Illusion, and Architecture Mismatch — sourced from xUnit Test Patterns, The Art of Unit Testing, How Google Tests Software, and Working Effectively with Legacy Code. PR reviews also include a lightweight Step 7 Quick Test Check automatically.

Why These Books, Why Now?

In the age of AI-assisted coding, we're writing more code faster than ever. But the insights from six decades of software engineering haven't changed:

"The complexity of software is an essential property, not an accidental one." — Frederick Brooks

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 — it brings the hard-won wisdom of six classic engineering books into your modern development workflow.

The decay risks these authors identified are more relevant than ever:

Adding AI assistants doesn't fix cognitive overload or domain model distortion
Generating more code increases change propagation and knowledge duplication
Moving faster makes accidental complexity and dependency disorder even more dangerous

Project Structure

brooks-lint/
├── .claude-plugin/              # Claude Code plugin metadata
├── .codex-plugin/               # Codex CLI plugin metadata
├── skills/brooks-lint/          # The skill itself (canonical source)
│   ├── SKILL.md                 # Main skill — Iron Law, mode detection, report template
│   ├── decay-risks.md           # Six decay risks with symptoms and book citations
│   ├── pr-review-guide.md       # Mode 1: PR review process (incl. Step 7 Quick Test Check)
│   ├── architecture-guide.md    # Mode 2: Architecture audit + Conway's Law
│   ├── debt-guide.md            # Mode 3: Pain×Spread scoring + Debt Summary Table
│   ├── test-decay-risks.md      # Six test-space decay risks with book citations
│   └── test-guide.md            # Mode 4: Test quality review process
├── hooks/                       # SessionStart hook
├── commands/                    # /brooks-review, /brooks-audit, /brooks-debt, /brooks-test
├── evals/                       # Benchmark test cases
│   └── evals.json
└── assets/
    └── logo.svg

Roadmap

v0.2: Plugin infrastructure (.claude-plugin/, hooks, slash commands)
v0.3: Eight Brooks dimensions, documentation completeness scoring
v0.4: Six-book framework, decay risk dimensions, diagnosis chain, benchmark suite
v0.5: Test Quality Review (Mode 4) — four testing books, six test decay risks
v0.6: Mermaid dependency graph in Architecture Audit
v0.7: GitHub Action for CI/CD integration
v1.0: VS Code extension

Want to help? The best contributions right now are new eval test cases and improved decay risk symptom patterns. See CONTRIBUTING.md.

Contributing

See CONTRIBUTING.md for how to add findings, improve guides, or expand the benchmark suite.

Run /brooks-lint:brooks-review on your own PR — we review contributions with the tool we're building.

License

MIT License — see LICENSE for details.

Acknowledgments

This project stands on the shoulders of ten giants:

Code Quality Framework (v0.4)

Frederick P. Brooks Jr. — The Mythical Man-Month (1975, Anniversary Edition 1995)
Steve McConnell — Code Complete (1993, 2nd ed. 2004)
Martin Fowler — Refactoring (1999, 2nd ed. 2018)
Robert C. Martin — Clean Architecture (2017)
Andrew Hunt & David Thomas — The Pragmatic Programmer (1999, 20th Anniversary Ed. 2019)
Eric Evans — Domain-Driven Design (2003)

Test Quality Framework (v0.5)

Gerard Meszaros — xUnit Test Patterns (2007)
Roy Osherove — The Art of Unit Testing (2009, 3rd ed. 2023)
Google Engineering — How Google Tests Software (2012)
Michael Feathers — Working Effectively with Legacy Code (2004)

The decay risks encoded in this tool are our synthesis of their ideas, applied to modern code quality assessment.

⭐ If this tool helped you see your codebase differently, give it a star!

Name		Name	Last commit message	Last commit date
Latest commit History 83 Commits
.claude-plugin		.claude-plugin
.codex-plugin		.codex-plugin
.github/workflows		.github/workflows
assets		assets
commands		commands
docs		docs
evals		evals
hooks		hooks
skills/brooks-lint		skills/brooks-lint
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
GEMINI.md		GEMINI.md
LICENSE		LICENSE
README.md		README.md
gemini-extension.json		gemini-extension.json
package.json		package.json

Folders and files

Latest commit

History

Repository files navigation

brooks-lint

The Six Decay Risks

What It Looks Like

🔴 Change Propagation — Single Method Changes for Four Unrelated Business Reasons

🔴 Domain Model Distortion — Silent Logic Bug: Email Notification Never Fires

Architecture Audit with Dependency Graph

See More Examples

Benchmark

How It Compares

Installation

Claude Code (Recommended)

Via Plugin Marketplace

Manual Install

Gemini CLI

Via Extension

Manual Install

Codex CLI

Via Skill Installer (in Codex session)

Command Line

Manual Install

Slash Commands

Claude Code

Gemini CLI

Codex CLI

Usage

PR Review

Architecture Audit

Tech Debt Assessment

Test Quality Review

Why These Books, Why Now?

Project Structure

Roadmap

Contributing

License

Acknowledgments

About

Topics

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 10

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages