Skip to content

Brooks-lint: AI Code Reviews Grounded in 12 Classic Engineering Books

Source: Brooks-lint

TL;DR

Brooks-lint synthesizes wisdom from 12 classic software engineering books (The Mythical Man-Month, Code Complete, Refactoring, Clean Architecture, The Pragmatic Programmer, Domain-Driven Design, and others) into structured, citable code review findings. It detects 6 production decay risks (Cognitive Overload, Change Propagation, Knowledge Duplication, Accidental Complexity, Dependency Disorder, Domain Model Distortion) and 6 test suite decay risks. Each finding follows a Symptom → Source → Consequence → Remedy format with book citations. The tool supports 6 analysis modes: PR Review, Architecture Audit, Tech Debt Assessment, Test Quality Review, Health Dashboard, and Full Sweep Auto-Fix. It is available as a Claude Code Plugin, Gemini CLI Extension, Codex CLI Skill, and GitHub Actions integration.

The Problem: Code Reviews Without Context

Traditional linters catch syntax errors and style violations, but they miss the deeper structural problems that cause long-term software decay. Brooks-lint addresses this gap by codifying the collective wisdom of 12 foundational software engineering texts into review rules that operate at the architectural and design level.

The 12 Source Books

The tool's knowledge base draws from:

  1. The Mythical Man-Month (Fred Brooks) — project management, Conway's Law
  2. Code Complete (Steve McConnell) — construction practices
  3. Refactoring (Martin Fowler) — improving existing code
  4. Clean Architecture (Robert C. Martin) — architectural principles
  5. The Pragmatic Programmer (Hunt & Thomas) — practical craftsmanship
  6. Domain-Driven Design (Eric Evans) — domain modeling
  7. Working Effectively with Legacy Code (Michael Feathers) — safe modification
  8. Design Patterns (Gamma et al.) — reusable solutions
  9. Test-Driven Development (Kent Beck) — testing discipline
  10. Growing Object-Oriented Software, Guided by Tests (Freeman & Pryce) — TDD at scale
  11. Implementation Patterns (Kent Beck) — code-level patterns
  12. Clean Code (Robert C. Martin) — code quality

Decay Risk Detection

Brooks-lint identifies 6 production decay risks:

Risk Description
Cognitive Overload Functions, classes, or modules that exceed human comprehension limits
Change Propagation Modifications that ripple across unexpectedly many files
Knowledge Duplication Repeated domain logic that should be consolidated
Accidental Complexity Unnecessary complexity not inherent to the problem domain
Dependency Disorder Circular, tangled, or excessively deep dependency graphs
Domain Model Distortion Code structures that no longer reflect the actual domain model

It also detects 6 test suite decay risks covering coverage gaps, brittle tests, slow tests, testing implementation instead of behavior, missing edge cases, and test logic duplication.

Finding Format

Every finding follows a structured format:

  • Symptom: What the reviewer or developer would observe
  • Source: Which of the 12 books identifies this pattern
  • Consequence: What happens if left unaddressed
  • Remedy: Specific actions to fix the issue

Each finding is linked to specific passages or principles from the source books, providing a citable rationale for the recommendation.

Analysis Modes

Brooks-lint supports 6 modes for different use cases:

  1. PR Review — Analyses pull requests for structural issues
  2. Architecture Audit — Evaluates overall system architecture against established patterns
  3. Tech Debt Assessment — Quantifies and categorizes technical debt
  4. Test Quality Review — Evaluates test suite health and coverage patterns
  5. Health Dashboard — Provides ongoing monitoring of codebase health metrics
  6. Full Sweep Auto-Fix — Comprehensive analysis with automated remediation suggestions

Integration Options

The tool is available in multiple integration formats:

  • Claude Code Plugin — For use within Anthropic's Claude Code environment
  • Gemini CLI Extension — For Google's Gemini command-line interface
  • Codex CLI Skill — For OpenAI's Codex CLI
  • GitHub Actions — For automated CI/CD pipeline integration

Key Takeaways

  • Brooks-lint codifies wisdom from 12 classic software engineering books into structured, citable code review findings
  • Detects 6 production decay risks (Cognitive Overload, Change Propagation, Knowledge Duplication, Accidental Complexity, Dependency Disorder, Domain Model Distortion) and 6 test suite decay risks
  • Each finding follows Symptom → Source → Consequence → Remedy format with specific book citations
  • Available in 6 analysis modes for different review needs
  • Integrates as Claude Code Plugin, Gemini CLI Extension, Codex CLI Skill, and GitHub Actions