brooks-lint
Revisiones de código con IA fundamentadas en doce libros clásicos de ingeniería.
Consistentes. Trazables. Accionables.
English ·
简体中文 ·
繁體中文 ·
日本語 ·
한국어 ·
Español
Inicio rápido •
Los seis riesgos de deterioro •
Cómo se ve •
Benchmark •
Instalación
→ Visita el sitio web
---
> *"Gestar un hijo lleva nueve meses, sin importar a cuántas mujeres se asigne."*
> — Frederick Brooks, *The Mythical Man-Month* (El mítico hombre-mes) (1975)
**50 años después, Brooks seguía teniendo razón — y también McConnell, Fowler, Martin, Hunt & Thomas, Evans, Ousterhout, Winters, Meszaros, Osherove, Feathers y el equipo de Testing de Google.**
La mayoría de las herramientas de calidad de código cuentan líneas y complejidad ciclomática. **brooks-lint** va más a fondo: diagnostica tu código frente a seis dimensiones de riesgo de deterioro sintetizadas a partir de doce libros clásicos de ingeniería, produciendo cada vez hallazgos estructurados con citas de libros, etiquetas de severidad y remedios concretos.
Para el mapeo completo de fuente a skill, incluyendo excepciones y protecciones contra falsos positivos, consulta
[`skills/_shared/source-coverage.md`](skills/_shared/source-coverage.md).
## Inicio rápido
```bash
# Claude Code
/plugin marketplace add hyhmrright/brooks-lint
/plugin install brooks-lint@brooks-lint-marketplace
# Cualquier otra plataforma de Agent Skills — Cursor · Codex · Gemini · Copilot · Windsurf · OpenCode · Kiro · …
curl -fsSL https://raw.githubusercontent.com/hyhmrright/brooks-lint/main/scripts/install.sh | bash -s --
```
Luego solo pide ("revisa este PR", "audita la arquitectura") — o ejecuta un comando:
| Comando | Qué hace |
|---------|--------------|
| `/brooks-review` | Revisa un PR o diff |
| `/brooks-audit` | Audita la arquitectura (+ grafo de dependencias en Mermaid) |
| `/brooks-debt` | Hoja de ruta de deuda técnica priorizada |
| `/brooks-test` | Revisión de calidad de la suite de pruebas |
| `/brooks-health` | Panel de salud en todas las dimensiones |
| `/brooks-sweep` | Barre todas las dimensiones y corrige hallazgos automáticamente |
Cada hallazgo se devuelve como **Síntoma → Origen → Consecuencia → Remedio** con una cita de libro y una puntuación de salud de 0 a 100. Las opciones completas de instalación (8 plataformas más), el uso por comando y la configuración de CI/CD están [más abajo](#instalación).
## Los doce libros
| Libro | Autor | Contribuye a |
|------|--------|----------------|
| *The Mythical Man-Month* | Frederick Brooks | R2, R4, R5 |
| *Code Complete* | Steve McConnell | R1, R4 |
| *Refactoring* | Martin Fowler | R1, R2, R3, R4, R6 |
| *Clean Architecture* | Robert C. Martin | R2, R5 |
| *The Pragmatic Programmer* | Hunt & Thomas | R2, R3, R4, R5, T2, T3 |
| *Domain-Driven Design* | Eric Evans | R1, R3, R6 |
| *A Philosophy of Software Design* | John Ousterhout | R1, R4 |
| *Software Engineering at Google* | Winters, Manshreck & Wright | R2, R5 |
| *The Art of Unit Testing* | Roy Osherove | T1, T2, T4, T5 |
| *How Google Tests Software* | James A. Whittaker, Jason Arbon & Jeff Carollo | T5, T6 |
| *Working Effectively with Legacy Code* | Michael Feathers | T4, T5, T6 |
| *xUnit Test Patterns* | Gerard Meszaros | T1, T2, T3, T4 |
## Los seis riesgos de deterioro
brooks-lint evalúa tu código frente a **seis riesgos de deterioro del código de producción** y **seis riesgos de deterioro de la suite de pruebas**, sintetizados a partir de doce libros clásicos de ingeniería:
| Riesgo de deterioro | Pregunta diagnóstica | Fuentes |
|------------|---------------------|---------|
| 🧠 Sobrecarga cognitiva | ¿Cuánto esfuerzo mental cuesta entender esto? | Code Complete, Refactoring, DDD, Philosophy of SD |
| 🔗 Propagación de cambios | ¿Cuántas cosas no relacionadas se rompen con un solo cambio? | Refactoring, Clean Architecture, Pragmatic, SE@Google |
| 📋 Duplicación de conocimiento | ¿La misma decisión se expresa en varios lugares? | Pragmatic, Refactoring, DDD |
| 🌀 Complejidad accidental | ¿El código es más complejo que el problema? | Refactoring, Code Complete, Brooks, Philosophy of SD |
| 🏗️ Desorden de dependencias | ¿Las dependencias fluyen en una dirección consistente? | Clean Architecture, Brooks, Pragmatic, SE@Google |
| 🗺️ Distorsión del modelo de dominio | ¿El código representa fielmente el dominio? | DDD, Refactoring |
> Philosophy of SD = *A Philosophy of Software Design* (Ousterhout) · SE@Google = *Software Engineering at Google* (Winters et al.)
## Cómo se ve
Dado este código:
```python
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 produce:
---
**Puntuación de salud: 28/100**
*Este método concentra cuatro responsabilidades de negocio no relacionadas en una sola función, contiene un error lógico que suprime silenciosamente las notificaciones de cambio de correo electrónico y queda totalmente expuesto a inyección de SQL.*
### 🔴 Propagación de cambios — Un solo método cambia por cuatro razones de negocio no relacionadas
**Síntoma:** `update_profile` realiza la actualización de los campos del perfil, las notificaciones de cambio de correo, el recálculo de puntos de fidelidad y la invalidación de caché, todo en el cuerpo de un mismo método.
**Origen:** Fowler — *Refactoring* — Divergent Change (Cambio divergente); Hunt & Thomas — *The Pragmatic Programmer* — Orthogonality (Ortogonalidad)
**Consecuencia:** Cualquier cambio en la fórmula de fidelidad arriesga romper las notificaciones de correo y viceversa. Cada edición conlleva riesgo de regresión en cuatro dominios no relacionados de forma simultánea.
**Remedio:** Extrae `NotificationService`, `LoyaltyService` y `UserCacheInvalidator`. `UserService.update_profile` debería orquestar llamando a cada uno — no debería contener lógica de implementación propia.
### 🔴 Distorsión del modelo de dominio — Error lógico silencioso: la notificación de correo nunca se dispara
**Síntoma:** `user['email'] = email` sobrescribe el valor anterior antes de `if user['email'] != email` — la condición siempre es `False`. La notificación es código muerto.
**Origen:** McConnell — *Code Complete* — Cap. 17: Estructuras de control inusuales
**Consecuencia:** Los usuarios nunca son notificados cuando cambia su dirección de correo. Fallo silencioso de integridad de datos — el sistema parece funcionar mientras viola una regla de negocio.
**Remedio:** Captura `old_email = user['email']` antes de cualquier mutación. Compara contra `old_email`, no contra `user['email']`.
*(+ 6 hallazgos más, incluyendo inyección de SQL, desorden de dependencias y números mágicos)*
### Auditoría de arquitectura con grafo de dependencias
En el Modo 2 (Auditoría de arquitectura), brooks-lint genera un **grafo de dependencias en Mermaid** en la parte superior del informe. Los módulos se colorean según su severidad: rojo = hallazgos Critical, amarillo = Warning, verde = limpio.
```mermaid
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
```
El grafo se renderiza de forma nativa en GitHub, Notion y otros entornos Markdown — sin herramientas adicionales.
## Más ejemplos
La [Galería completa](docs/gallery.md) contiene salida real de brooks-lint en Python, TypeScript, Go y Java — incluyendo revisiones de PR, auditorías de arquitectura con grafos de dependencias en Mermaid, evaluaciones de deuda técnica y revisiones de calidad de pruebas.
¿Nuevo en los riesgos de deterioro? La [**Guía de campo de los riesgos de deterioro**](https://hyhmrright.github.io/brooks-lint/guide.html) explica los seis — pregunta diagnóstica, síntomas característicos, libros de origen y remedio para cada uno.
---
## Benchmark
Probado en 3 escenarios del mundo real (revisión de PR, auditoría de arquitectura, evaluación de deuda técnica):
| Criterio | brooks-lint | Claude solo |
|-----------|:-----------:|:------------:|
| Hallazgos estructurados (Síntoma → Origen → Consecuencia → Remedio) | ✅ 100% | ❌ 0% |
| Citas de libros por hallazgo | ✅ 100% | ❌ 0% |
| Etiquetas de severidad (🔴/🟡/🟢) | ✅ 100% | ❌ 0% |
| Puntuación de salud (0–100) | ✅ 100% | ❌ 0% |
| Detecta Propagación de cambios | ✅ 100% | ✅ 100% |
| **Tasa de aprobación global** | **94%** | **16%** |
La brecha no está en lo que Claude *puede* encontrar — está en lo que encuentra de forma *consistente*, con evidencia trazable y remedios accionables cada vez.
### Benchmarks reproducibles
La tabla anterior es ilustrativa. Estas cifras son **deterministas y puedes reproducirlas localmente**:
**Fidelidad del parser** — la exportación a SARIF y los gates de CI dependen de parsear correctamente el informe Markdown del modelo. Frente a un **corpus congelado de 30 informes reales generados por el modelo** que abarcan los seis modos (`evals/benchmark-corpus.json`), cada uno emparejado con un inventario de hallazgos **calificado de forma independiente** (un pase de modelo separado, revisado manualmente por muestreo), el parser distribuido obtiene — ejecuta `npm run benchmark`:
| Métrica (n = 30, corpus congelado) | Resultado |
|---|:---:|
| Coincidencia exacta del conteo de severidad (parser vs. verdad calificada) | 30 / 30 |
| Precisión / recall del código de riesgo | 100% / 100% (56 códigos a nivel de hallazgo, 0 FP / 0 FN) |
| SARIF 2.1.0 válido emitido | 30 / 30 |
Como el parser es determinista y el corpus está congelado, `npm run benchmark` da a todo el mundo el mismo resultado, y `npm test` lo protege como regresión. El corpus incluye deliberadamente 9 informes de falsos positivos / compensaciones (por ejemplo, un diseño de puertos y adaptadores que *parece* un ciclo de dependencias) que deben permanecer limpios.
**Determinismo del scoring** — para un conjunto fijo de hallazgos (2 Critical / 3 Warning / 1 Suggestion), los presets de severidad producen exactamente las puntuaciones que predice su tabla de `common.md`: strict **34**, balanced **54**, legacy-friendly **74** — y solo `legacy-friendly` encabeza con las tres correcciones principales.
**Calidad del modelo** — si el modelo encuentra los riesgos *correctos* en código real se mide con la **suite de evaluaciones de 57 escenarios** (`evals/evals.json`): `npm run evals` (estructural) y `npm run evals:live` (en vivo, requiere `ANTHROPIC_API_KEY`).
> Alcance y honestidad: las cifras del parser son deterministas y exactamente reproducibles. Las cifras de severidad y de la suite de evaluaciones son mediciones en vivo de una sola ejecución contra el modelo y varían ligeramente entre ejecuciones. El benchmark del parser mide la fidelidad del parseo de informes (¿lee la herramienta cada hallazgo que el informe declara?), no si un hallazgo dado es "correcto". La coincidencia del conteo de severidad es la señal totalmente independiente; la concordancia de códigos de riesgo también refleja la leyenda canónica compartida de nombre→código.
## Cómo se compara
| | brooks-lint | ESLint / Pylint | GitHub Copilot Review | Claude sin más |
|---|:---:|:---:|:---:|:---:|
| Detecta problemas de sintaxis y estilo | — | ✅ | ✅ | ~ |
| Cadena de diagnóstico estructurada | ✅ | ❌ | ❌ | ❌ |
| Rastrea los hallazgos hasta libros clásicos | ✅ | ❌ | ❌ | ❌ |
| Etiquetas de severidad consistentes | ✅ | ✅ | ~ | ❌ |
| Perspectivas a nivel de arquitectura | ✅ | ❌ | ~ | ~ |
| Análisis del modelo de dominio | ✅ | ❌ | ❌ | ~ |
| Cero configuración, sin plugins que instalar | ✅ | ❌ | ✅ | ✅ |
| Funciona con cualquier lenguaje | ✅ | ❌ | ✅ | ✅ |
> `~` = ocasionalmente / de forma inconsistente
**brooks-lint no reemplaza a tu linter.** Captura lo que los linters no pueden: deriva arquitectónica, silos de conocimiento y distorsión del modelo de dominio — los problemas que frenan a los equipos durante meses antes de que alguien lo note.
## Instalación
### Claude Code (recomendado)
#### Mediante el Plugin Marketplace
```bash
/plugin marketplace add hyhmrright/brooks-lint
/plugin install brooks-lint@brooks-lint-marketplace
```
Los comandos en forma corta (`/brooks-review`) se instalan automáticamente al iniciar la primera sesión. Para instalarlos manualmente:
```bash
bash hooks/session-start
```
#### Instalación manual
```bash
mkdir -p ~/.claude/skills/brooks-lint
cp -r skills/* ~/.claude/skills/brooks-lint/
```
### Gemini CLI
#### Mediante extensión
```bash
/extensions install https://github.com/hyhmrright/brooks-lint
```
#### Instalación manual
```bash
mkdir -p ~/.gemini/skills
cp -r skills/* ~/.gemini/skills/ # flat — Gemini discovers skills only one level deep
```
> O simplemente: `./scripts/install.sh gemini`
### Codex CLI
#### Mediante el instalador de skills (en una sesión de Codex)
```
Install the brooks-lint skill from hyhmrright/brooks-lint
```
#### Línea de comandos
```bash
python3 ~/.codex/skills/.system/skill-installer/scripts/install-skill-from-github.py \
--repo hyhmrright/brooks-lint --path skills --name brooks-lint
```
#### Instalación manual
```bash
git clone https://github.com/hyhmrright/brooks-lint.git /tmp/brooks-lint
mkdir -p ~/.codex/skills
cp -r /tmp/brooks-lint/skills/* ~/.codex/skills/ # flat — matches the skill-installer layout
```
> O simplemente: `./scripts/install.sh codex`
### Más plataformas — OpenCode · Cursor · Windsurf · Antigravity · pi · Copilot · Kiro · Factory Droid
brooks-lint se distribuye como [Agent Skills](https://agentskills.io) estándar. **Cualquier agente que cargue Agent
Skills ejecuta los seis modos sin conversión alguna** — un solo comando los instala:
```bash
# elige tu plataforma; --project instala en el repositorio actual en lugar de en tu configuración global
curl -fsSL https://raw.githubusercontent.com/hyhmrright/brooks-lint/main/scripts/install.sh | bash -s --
# = opencode · cursor · windsurf · antigravity · pi · kiro · copilot · droid · gemini · codex · agents
```
El instalador copia los skills **de forma plana** en la carpeta correcta para tu plataforma, de modo que el framework
compartido (`../_shared/`) siempre se resuelve — no puedes equivocarte con el diseño. Luego solo pide
("revisa este PR", "audita la arquitectura") y el skill correspondiente se activa automáticamente desde su
`description`. ¿Nuevo en los skills, o usas otro agente? Consulta **[docs/getting-started.md](docs/getting-started.md)**.
OpenCode
`./scripts/install.sh opencode` → `~/.config/opencode/skills` (también lee `~/.claude/skills` y
`AGENTS.md`). Guía completa: [docs/opencode-setup.md](docs/opencode-setup.md).
Cursor (2.4+)
`./scripts/install.sh cursor` → `~/.cursor/skills` (también `.agents/skills`; lee `AGENTS.md`).
Guía completa: [docs/cursor-setup.md](docs/cursor-setup.md).
Windsurf (Cascade)
`./scripts/install.sh windsurf` → `~/.codeium/windsurf/skills` (lee `AGENTS.md`).
Guía completa: [docs/windsurf-setup.md](docs/windsurf-setup.md).
Antigravity (Google)
`./scripts/install.sh antigravity --project` → `.agent/skills` (lee `AGENTS.md` / `GEMINI.md`).
Guía completa: [docs/antigravity-setup.md](docs/antigravity-setup.md).
pi (earendil-works)
`./scripts/install.sh pi` → `~/.pi/agent/skills`, o apunta el ajuste `skills` de pi a un clon.
Guía completa: [docs/pi-setup.md](docs/pi-setup.md).
GitHub Copilot
`./scripts/install.sh copilot --project` → `.github/skills` (también detecta automáticamente `.claude/skills`; lee
`AGENTS.md`). Guía completa: [docs/copilot-setup.md](docs/copilot-setup.md).
Kiro (AWS)
`./scripts/install.sh kiro` → `~/.kiro/skills` (registra automáticamente `/brooks-review`; lee `AGENTS.md`).
Guía completa: [docs/kiro-setup.md](docs/kiro-setup.md).
Factory Droid
`./scripts/install.sh droid` → `~/.factory/skills` (registra `/brooks-review`; lee `AGENTS.md`).
Guía completa: [docs/factory-droid-setup.md](docs/factory-droid-setup.md).
⭐ Si esta herramienta te ayudó a ver tu base de código de otra manera, ¡dale una estrella!