Summary

brooks-lint provides AI-driven code reviews that diagnose software decay risks based on principles from twelve classic engineering books. It targets engineers and researchers seeking deeper, traceable insights beyond traditional linters, offering actionable remedies to improve code quality and maintainability.

How It Works

The tool synthesizes wisdom from foundational texts like "The Mythical Man-Month" and "Code Complete" to identify six core "decay risks" (e.g., Cognitive Overload, Change Propagation) and six test-suite risks. It analyzes code, providing structured findings that include symptoms, root causes cited from specific books, consequences, and concrete remedies. An architecture audit mode generates visual dependency graphs using Mermaid.

Quick Start & Requirements

Installation is primarily through AI assistant plugin marketplaces (Claude Code, Gemini CLI, Codex CLI) or manual setup by copying files. No specific language versions or hardware are mandated for the tool itself, but integration with AI coding environments is required. Links to official documentation and examples are available within the repository.

Highlighted Details

• AI code reviews grounded in 12 classic engineering books, offering decay risk diagnostics with book citations.
• Six analysis modes: PR Review, Architecture Audit (with Mermaid dependency graphs), Tech Debt Assessment, Test Quality Review, Health Dashboard, and Full Sweep with auto-fix capabilities.
• Benchmarks demonstrate superior structured findings, book citations, severity labels, and overall pass rates compared to plain AI models.
• Designed for zero configuration and works across multiple programming languages.

Maintenance & Community

The project outlines a clear roadmap to v1.0 and welcomes contributions, particularly new eval test cases and improved decay risk symptom patterns, as detailed in CONTRIBUTING.md. It encourages users to run reviews on their own contributions.

Licensing & Compatibility

Licensed under the MIT License, it permits commercial use and integration with closed-source projects. The tool is designed to be language-agnostic.

Limitations & Caveats

Effectiveness is dependent on the integrated AI coding assistant environment. Auto-fix functionality requires user confirmation for multi-file or interface-touching changes. While it complements linters, it does not replace them for syntax and style checks. Usage costs are associated with CI/CD integrations.