Auditing Architectural Decay with Brooks-Lint

Practical Summary

Brooks-Lint is an AI-powered code review tool designed to diagnose architectural decay by evaluating codebases against six specific risk dimensions. Unlike traditional linters that focus on syntax or cyclomatic complexity, this tool synthesizes principles from twelve classic software engineering books to provide structured, traceable findings. It is intended for developers and architects who need to identify systemic issues such as cognitive overload, dependency disorder, and domain model distortion. By providing a consistent 0-100 health score and actionable remedies, it helps teams move beyond superficial code quality metrics toward long-term architectural health.

Prerequisites and Installation

The tool functions as an Agent Skill, making it compatible with various AI-assisted development platforms. For Claude Code users, the installation is performed via the marketplace:

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

For other platforms, such as Cursor, Windsurf, or OpenCode, you use a curl-based installer. By executing the command below, the tool installs the necessary skills for your specific platform. For Gemini CLI, use the /extensions install command as specified in the official documentation.

curl -fsSL https://raw.githubusercontent.com/hyhmrright/brooks-lint/main/scripts/install.sh | bash -s -- <platform>

Documented Workflow

The workflow centers on six primary slash commands that address different aspects of code quality. The /brooks-review command is the primary entry point for analyzing pull requests or specific files, providing findings in a structured Symptom → Source → Consequence → Remedy format. For deeper architectural analysis, /brooks-audit generates a Mermaid dependency graph to visualize module relationships and identify circular dependencies. Other commands like /brooks-debt and /brooks-test allow for targeted assessments of technical debt and test suite quality, respectively. The /brooks-health command provides a high-level composite score, while /brooks-sweep performs a comprehensive scan across all dimensions to suggest and apply fixes.

Understanding the Decay Risks

The tool evaluates code against six production-code decay risks: Cognitive Overload, Change Propagation, Knowledge Duplication, Accidental Complexity, Dependency Disorder, and Domain Model Distortion. Each risk is grounded in specific literature, such as Martin Fowler's Refactoring or Robert C. Martin's Clean Architecture. For example, Change Propagation is diagnosed by identifying divergent changes where a single method handles multiple unrelated business responsibilities. By tracing these findings back to established engineering texts, the tool ensures that the feedback is rooted in proven design principles. This evidence-led approach helps developers understand the reasoning behind a suggested refactoring.

Interpreting Output and Findings

Every finding produced by the tool includes a severity label (Critical, Warning, or Suggestion) and a clear explanation of the issue. The output is designed to be actionable, providing a specific remedy for each identified symptom. When running an architecture audit, the tool outputs a Mermaid dependency graph that highlights modules based on their health status, using color-coded nodes to distinguish between critical findings and clean components. This visual representation allows teams to quickly identify which parts of the system are most prone to failure or require immediate refactoring. The health score provides a quantitative baseline to track improvements over time.

Configuration and Customization

Users can customize the tool's behavior by placing a .brooks-lint.yaml file in the project root. This configuration allows for adjusting the strictness of the scoring (e.g., strict, balanced, or legacy-friendly), disabling specific risk checks, or overriding severity levels for particular domains. This is particularly useful for legacy codebases where certain architectural patterns may be accepted as necessary debt. By ignoring specific file patterns or suppressing known issues, teams can focus the tool's analysis on the most relevant parts of their codebase, ensuring that the feedback remains useful and avoids noise.

Limitations and Scope

It is important to note that Brooks-Lint is not a replacement for traditional linters or static analysis tools. It does not focus on syntax errors, style enforcement, or basic security vulnerabilities that standard tools like ESLint or Pylint are designed to catch. Instead, it operates at a higher level of abstraction, focusing on architectural drift and domain modeling. Furthermore, while the tool provides automated remedies, multi-file changes often require manual confirmation to ensure that the suggested refactoring does not break existing functionality. The tool's effectiveness is also dependent on the underlying AI model's ability to interpret the codebase correctly.

Choosing When to Use Brooks-Lint

Brooks-Lint is best utilized during significant architectural reviews, onboarding processes, or when preparing for a major release. It is particularly effective for teams struggling with high regression rates or those attempting to modernize legacy systems. By integrating the tool into the development workflow, teams can catch architectural decay before it becomes a bottleneck. For more information on the underlying principles and the full source-to-skill mapping, you can visit the official repository at https://github.com/hyhmrright/brooks-lint. Using the tool consistently allows for a more disciplined approach to maintaining long-term software quality.