brooks-lint: AI code review that cites twelve engineering classics

What brooks-lint actually diagnoses

Most linters count lines and cyclomatic complexity. brooks-lint does something different: it evaluates code against six production-code decay risks and six test-suite decay risks, each synthesized from a set of twelve engineering books. The production risks are Cognitive Overload, Change Propagation, Knowledge Duplication, Accidental Complexity, Dependency Disorder, and Domain Model Distortion. Each risk maps to a diagnostic question, like "How much mental effort to understand this?" for Cognitive Overload, or "Do dependencies flow in a consistent direction?" for Dependency Disorder. The test-suite risks come from books like The Art of Unit Testing and xUnit Test Patterns, though the README does not list the test risk names in the same table. This is a tool for engineers who want review feedback that names a principle and a book, not just a rule ID.

How the six risk dimensions are built

The README includes a table mapping each book to the risks it contributes to. The Mythical Man-Month contributes to Accidental Complexity, Dependency Disorder, and Domain Model Distortion. Refactoring contributes to five of the six production risks. The Pragmatic Programmer contributes to four risks plus two test risks. That mapping is not hidden: the README points to skills/_shared/source-coverage.md for the full source-to-skill mapping, including exceptions and false-positive guards. This is a useful design detail. It means the tool is not just a black box that says "this code is bad." It has a documented trail from a code pattern to a specific book and chapter. The example finding cites Fowler's Divergent Change and The Pragmatic Programmer's Orthogonality for a Change Propagation issue. Whether that mapping is accurate in practice is something you would need to verify by reading the source-coverage file.

A sample finding shows the format

The README gives a concrete example. It shows a Python class UserService with a method update_profile that queries a database with an f-string, overwrites the email field, and then checks if the email changed, which is always false. brooks-lint returns a Health Score of 28/100 and a finding under Domain Model Distortion. The finding is structured as Symptom, Source, Consequence, and Remedy. The source cites McConnell's Code Complete, Chapter 17 on Unusual Control Structures. The consequence states that users are never notified when their email changes, a silent data integrity failure. The remedy says to capture old_email before mutation and compare against that. This format is the core value proposition: each finding is traceable to a book and a chapter, and the remedy is specific enough to act on. The example also shows SQL injection as a separate finding, though that part is truncated.

Six commands and how to run them

brooks-lint is installed as a plugin for Claude Code or as an agent skill for other platforms. The quick start shows two commands for Claude Code: /plugin marketplace add hyhmrright/brooks-lint and /plugin install brooks-lint@brooks-lint-marketplace. For other platforms like Cursor, Codex, Gemini, Copilot, Windsurf, OpenCode, and Kiro, there is a curl command that pipes an install script to bash with a platform argument. After installation, you invoke one of six slash commands: /brooks-review, /brooks-audit, /brooks-debt, /brooks-test, /brooks-health, and /brooks-sweep. The README does not detail what each command does, only that there are six analysis modes including a full-sweep auto-fix. That is a gap in the documentation. A user would need to run each command or check the repository to know the difference between a review and an audit. The install script is a single curl pipe, which is convenient but also a security consideration for teams that prefer pinned versions.

The health score and severity labels

Every finding comes back with a 0-100 Health Score, a severity label, and the Symptom-to-Remedy structure. The example shows a score of 28/100 for a method with multiple issues. The severity labels are not enumerated in the README, but the example uses a red circle emoji to mark a high-severity finding. The score is likely an aggregate of the findings, but the README does not explain the scoring formula. This is a limitation. A score of 28 means something, but without a defined scale, teams cannot compare scores across runs or across codebases. The README mentions a benchmark section in the table of contents, but the provided material truncates before that section. So the benchmark results are not available in this material. That is a notable gap for a tool that claims to be grounded in twelve books; you would want evidence that the diagnoses are consistent and accurate.

Where brooks-lint is the wrong tool

brooks-lint is not a traditional linter. It does not run as a local binary that parses your code and returns a list of violations. It is an AI-powered skill that runs inside an agent platform. That means it depends on the underlying model's ability to reason about code and match it to the book-derived skills. The README does not specify which models are supported or what the failure modes are. If your CI pipeline needs deterministic, reproducible checks, this tool will not give you that. It is also not a security scanner. The example mentions SQL injection, but the six decay risks are about maintainability and design, not security. The tool might flag security issues incidentally, but that is not its focus. If your team wants a tool that enforces a specific style guide or detects known anti-patterns with zero false positives, brooks-lint is the wrong choice. It is a heuristic, opinionated reviewer, not a rule engine.

Alternatives and the difference in approach

A direct alternative is a conventional linter like ESLint for JavaScript or Ruff for Python. Those tools run locally, have deterministic rules, and give you a fixed set of checks with no citations to books. The difference is in the philosophy: ESLint enforces syntax and style conventions, while brooks-lint tries to assess design quality and domain modeling. Another alternative is a human code review with a checklist based on the same books. That gives you the judgment of a senior engineer, but it is slower and less consistent. brooks-lint sits in between: it automates the book-based reasoning but inherits the variability of AI models. The README does not mention any other AI review tools, so the comparison is based on the general landscape. If you want traceability to a specific book, brooks-lint is unique in that regard. If you want a rule that says 'no unused variables', use a traditional linter.

Maintenance and license considerations

The repository is MIT-licensed, which means you can use, modify, and redistribute it freely, including in commercial products, as long as you preserve the copyright notice. The project has had recent releases, with v1.5.0 pushed on 2026-08-14, and earlier patch releases in the same month. That suggests active maintenance, though the README does not state a maintenance policy or a roadmap. The install script is fetched from the main branch, so updates are not pinned to a release unless you manually specify a version. For teams that need stability, you would want to vendor the skill files or pin to a specific release tag. The documentation mentions a website and a source-coverage file, so there is some supporting material, but the core is the skill definitions in the repository. The cost of maintenance is mostly in keeping the book mappings current as the underlying AI models change.

Editorial conclusion

Adopt brooks-lint if your team uses Claude Code or another agent platform and wants code review findings that are traceable to named sources like Fowler and McConnell, with a concrete health score. Skip it if you need a traditional lint rule engine that runs deterministically in CI without an AI model, or if your codebase is not written in a language the six analysis modes handle well. Before adopting, verify the source-to-skill mapping in skills/_shared/source-coverage.md and run it on a small sample to see if the citations match your actual code. The tool is MIT-licensed, so the cost of trying it is low, but the real cost is in trusting its book-based judgments over your own review process.

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes