Por Qué las Reglas Son el Arma Secreta
de la Revisión de Código con IA

En diffray, resolvimos esto con reglas estructuradas. Déjame mostrarte por qué son la clave para que la revisión de código con IA realmente funcione.

El Problema: La Dilución de Contexto Mata el Rendimiento de la IA

Cuando vuelcas un PR completo en un LLM con un prompt como "revisa este código", varias cosas salen mal:

La Solución: Reglas Estructuradas

Una regla estructurada no es solo un prompt — es una especificación completa que le dice a la IA exactamente qué buscar, dónde buscar y cómo reportar hallazgos.

Así es como se ve una regla:

rules:
  - id: sec_sql_injection
    agent: security
    title: "Inyección SQL vía concatenación de strings"
    description: "Input de usuario concatenado en queries SQL permite ejecutar SQL arbitrario"
    importance: 9

    match:
      file_glob:
        - "src/api/**/*.ts"
        - "src/routes/**/*.ts"
        - "!**/*.test.ts"
      content_regex:
        - "query.*\$\{|\+.*query"

    checklist:
      - "Encuentra todos los lugares donde se usa input de usuario en queries SQL"
      - "Verifica si se usan queries parametrizadas o prepared statements"
      - "Verifica que NO se use concatenación de strings para construir queries"

    examples:
      bad: |
        const query = `SELECT * FROM users WHERE id = ${userId}`;
        await db.execute(query);
      good: |
        const query = 'SELECT * FROM users WHERE id = ?';
        await db.execute(query, [userId]);

Esta estructura habilita tres capacidades críticas que hacen que la revisión de código con IA realmente funcione.

1. Resultados Deterministas Mediante Targeting Preciso

¿Notas la sección match? Eso es pattern matching que determina cuándo se ejecuta la regla.

Sin pattern matching, revisar un PR de 50 archivos significa analizar todos los 50 archivos para cada posible problema. Con pattern matching:

Si un PR tiene 5 archivos API que contienen queries SQL, solo esos 5 archivos se envían para verificación de inyección SQL. La IA ve exactamente lo que necesita evaluar — nada más.

Esta precisión elimina la aleatoriedad que plagaba los intentos anteriores de revisión de código con IA. Mismo código + mismas reglas = mismos hallazgos. Siempre.

2. Arquitectura Multi-Agente: El Experto Correcto para Cada Problema

Aquí es donde se pone interesante. diffray no usa una IA para revisar todo — usa 31 agentes especializados, cada uno enfocado en lo que hace mejor:

Cada agente tiene un system prompt especializado con expertise de dominio. Un agente de seguridad conoce OWASP Top 10. Un agente React entiende las reglas de hooks. Esta especialización mejora dramáticamente la calidad de detección.

Pero aquí está la clave: las reglas determinan qué agente maneja qué.

- id: react_useeffect_cleanup
  agent: react              # Manejado por especialista React
  match:
    file_glob: ["**/*.tsx"]
    content_regex: ["useEffect"]
  checklist:
    - "Verifica si useEffect retorna una función de cleanup"
    - "Verifica que los event listeners y subscriptions se limpien"

Esta regla solo va al agente React, solo para archivos TSX, solo cuando useEffect está presente. El agente recibe contexto enfocado sobre exactamente una cosa — no 50 preocupaciones diferentes compitiendo por atención.

3. Curación de Contexto: El Secreto para No Diluir la Atención de la IA

Los LLMs modernos pueden manejar más de 200k tokens. Pero la investigación muestra que el rendimiento práctico alcanza un tope alrededor de 25-30k tokens para razonamiento complejo. Más allá de eso, estás pagando por tokens que el modelo no puede usar efectivamente.

El sistema de gestión de contexto de diffray asegura que cada agente reciba precisamente la información que necesita:

Cada agente recibe exactamente lo que necesita para hacer su trabajo. Nada más. El resultado: atención enfocada, mejores hallazgos, menos falsos positivos.

4. Flexibilidad: Reglas Específicas de Proyecto y Equipo

Aquí es donde las reglas realmente brillan para equipos. Cada codebase tiene convenciones que las herramientas genéricas desconocen:

Tus librerías internas:

- id: use_internal_http_client
  agent: consistency
  title: "Usar wrapper interno de cliente HTTP"
  match:
    file_glob: ["src/**/*.ts"]
    content_regex: ["\\bfetch\\(", "axios\\."]
  checklist:
    - "Encuentra llamadas raw de fetch() o axios"
    - "Verifica si el código debería usar httpClient de @/lib/http-client"
  examples:
    bad: |
      const response = await fetch('/api/users');
    good: |
      import { httpClient } from '@/lib/http-client';
      const data = await httpClient.get('/api/users');

Tus patrones específicos de dominio:

- id: money_use_decimal
  agent: bugs
  title: "Usar Decimal para valores monetarios"
  match:
    content_regex: ["(price|amount|total)\\s*:\\s*(number|float)"]
  checklist:
    - "Encuentra campos monetarios usando tipos float/number"
    - "Verifica que el almacenamiento use centavos (integer) o tipo Decimal"

Tus requisitos de cumplimiento:

- id: pii_logging_check
  agent: compliance
  title: "Nunca loguear PII directamente"
  tags: [compliance-gdpr, compliance-hipaa]
  match:
    content_regex: ["log.*(email|phone|ssn|password)"]

Colócalas en .diffray/rules/ y estarán activas en el próximo PR. Sin cambios de infraestructura, sin actualizaciones de herramientas — solo agrega YAML y tu revisor de IA aprende tus estándares.

¿Por Qué YAML? La Estructura Habilita la Inteligencia

Podrías preguntarte por qué usamos YAML estructurado en lugar de solo escribir prompts. La estructura habilita capacidades que los prompts de forma libre no pueden:

Un prompt plano no puede proporcionar esta separación de responsabilidades.

El Resultado: Revisión de Código con IA que Realmente Funciona

Cuando combinas reglas estructuradas con arquitectura multi-agente y gestión inteligente de contexto, obtienes:

Esto es lo que marca la diferencia entre "revisión de código con IA" como demo y revisión de código con IA como infraestructura en la que tu equipo realmente confía.