Reglas de revisión en Open Code Review: cómo escribir tu rule.json con ejemplos reales

Las reglas son lo que convierte a Open Code Review de un revisor genérico en uno que conoce tu proyecto. Le dicen al modelo qué vigilar en cada archivo: "los importes van en céntimos", "toda ruta valida su entrada", "ningún test cubre solo el caso feliz". En esta tercera parte de la guía escribimos un rule.json real para la API de ejemplo de la parte 2, lo depuramos con ocr rules check y te enseñamos el error de orden que nos pilló a nosotros.

Cómo elige ocr la regla de cada archivo

Para cada archivo que pasa el filtro, ocr busca una regla en cuatro capas, por este orden. La primera coincidencia gana y las demás capas ni se miran:

Si un archivo de capa no existe, se salta sin error. La capa de sistema siempre está, así que siempre hay alguna regla.

La regla elegida se inyecta en el prompt del subagente como {{system_rule}}. Por eso una buena regla se nota tanto: es la checklist con la que el modelo revisa ese archivo.

El formato de rule.json

Tiene tres campos, todos opcionales:

{
  "include": ["src/**/*.test.js"],
  "exclude": ["scripts/**"],
  "rules": [
    { "path": "src/routes/**/*.js", "rule": "Texto de la regla..." }
  ]
}

• include: patrones que se saltan las exclusiones por defecto (tests, extensiones no soportadas, dist/…). Ojo, no es una lista blanca: los archivos que no coinciden se siguen revisando con normalidad.
• exclude: patrones que no se revisan nunca. Es el filtro de usuario con más prioridad. Se suma a lo que pases con --exclude.
• rules: lista de {path, rule} que se evalúa en orden. La primera cuyo path coincide decide la regla del archivo.

Cada entrada de rules admite un tercer campo, merge_system_rule. Con false (por defecto) tu regla sustituye a la de sistema para ese archivo. Con true se combinan: primero la regla del lenguaje y después la tuya.

Los patrones usan la sintaxis glob de doublestar: * (sin cruzar /), ** (cualquier profundidad), {ts,tsx} (alternativas), ? y [abc]. Se comparan sin distinguir mayúsculas.

Un rule.json real paso a paso

Nuestra rama feat/cupones añade src/lib/cupones.js (aplica un cupón y reparte el total en cuotas), cambia una ruta Express y trae un test. Queremos tres cosas:

1. Que el código de src/lib/ se revise con las reglas de JavaScript y además con nuestra norma de dinero.
2. Que las rutas se revisen con nuestra norma de validación (sin las reglas genéricas de React, que no aplican).
3. Que los tests, que ocr excluye por defecto, también se revisen, con su propia regla.

{
  "include": ["src/**/*.test.js"],
  "exclude": ["scripts/**"],
  "rules": [
    {
      "path": "**/*.test.js",
      "rule": "Revisa que cada test cubra casos límite (0, 1, valores negativos) y no solo el caso feliz."
    },
    {
      "path": "src/lib/**/*.js",
      "rule": "Dinero: los importes se guardan en céntimos (enteros). Señala cualquier cálculo con decimales, cualquier porcentaje que no se divida entre 100 y cualquier reparto cuya suma no coincida con el total.",
      "merge_system_rule": true
    },
    {
      "path": "src/routes/**/*.js",
      "rule": "Toda ruta Express debe validar req.params y req.body antes de usarlos, esperar (await) cada llamada asíncrona y responder 404 si el recurso no existe."
    }
  ]
}

Tras subir el archivo, ocr review --preview ya muestra src/lib/cupones.test.js en "Will review": el include ha anulado la exclusión por defecto de los tests. También aparece .opencodereview/rule.json, que se revisa con la regla de sistema para JSON.

Comprobar qué regla gana: ocr rules check

ocr rules check <ruta> te dice qué capa y qué patrón ganan para un archivo, y el texto completo de la regla. Es la herramienta de depuración número uno:

ocr rules check src/routes/pedidos.js
ocr rules check src/lib/cupones.test.js
ocr rules check src/lib/cupones.js

En cupones.js, gracias a merge_system_rule: true, la salida tiene dos bloques: ## System-Specific Rules (Mandatory) con la checklist de JS/TS (erratas, código muerto, ===, null checks, async, XSS, eval, secretos…) y ## User-Specific Rules (Mandatory) con nuestra norma de dinero.

Para ver qué haría una regla puntual sin tocar el proyecto, pásala con --rule:

echo '{"rules":[{"path":"**/*","rule":"Solo seguridad: inyección SQL, secretos en código y autorización ausente. Ignora estilo."}]}' > solo-seguridad.json
ocr rules check --rule solo-seguridad.json src/lib/cupones.js
# Source: Custom (--rule)
# Pattern: **/*
ocr review --from main --to feat/cupones --rule solo-seguridad.json

El error que cometimos: el orden de las reglas

Nuestra primera versión tenía la regla de tests al final, después de src/lib/**/*.js. Parecía lógico ir de lo general a lo específico. ocr rules check nos sacó del error:

src/lib/cupones.test.js coincide con src/lib/**/*.js, y como esa entrada iba primero, ganaba. La regla de tests no se aplicaba nunca, y no había ningún aviso. La solución es la del rule.json de arriba: de lo más específico a lo más general. Y si dos de tus reglas deben aplicarse al mismo archivo, escríbelas juntas en una sola: merge_system_rule solo combina con la capa de sistema, no tus reglas entre sí.

Recetas útiles

Seguridad global encima de las reglas de cada lenguaje

En ~/.opencodereview/rule.json, para todos tus repos:

{
  "rules": [
    {
      "path": "**/*",
      "rule": "Security review: flag hardcoded secrets, unvalidated redirects, and missing authz checks.",
      "merge_system_rule": true
    }
  ]
}

Sin merge_system_rule, ese **/* sustituiría las reglas de Java, Python, Go… en todos los archivos. Con true, cada archivo recibe la regla de su lenguaje más la tuya. Recuerda que la capa global es la de menos prioridad: si el proyecto tiene una regla que coincide, la global no se aplica.

Ignorar código generado y centrarse en src

{
  "include": ["src/**/*.{ts,tsx,js,jsx}"],
  "exclude": ["**/*.gen.ts", "**/generated/**", "migrations/**"]
}

Normas de backend en Go o SQL

{
  "rules": [
    {
      "path": "internal/api/**/*.go",
      "rule": "Todo handler que abra una transacción debe hacer defer tx.Rollback() justo después. Los errores se envuelven con fmt.Errorf(\"...: %w\", err)."
    },
    {
      "path": "**/*mapper*.xml",
      "rule": "Revisa inyección SQL (${} en lugar de #{}), parámetros sin enlazar y etiquetas XML sin cerrar."
    }
  ]
}

Regla de documentación sincronizada

El propio repositorio de Open Code Review usa esta técnica en su .opencodereview/rule.json: cuando alguien toca internal/llm/providers.go, la regla exige actualizar la tabla de proveedores en los cuatro idiomas de la documentación y añadir un test por proveedor nuevo. Es un buen modelo de regla de "si cambias A, cambia también B", que ningún linter detecta.

Reglas y contexto: --background

Las reglas dicen cómo revisar; --background dice qué pretendía el cambio. Son complementarios:

ocr review --from main --to feat/cupones \
  -b "Cupones de descuento (porcentaje 0-100) y pago en cuotas. Importes en céntimos."
# o desde un archivo con los requisitos
ocr review --from main --to feat/cupones -B docs/cupones.md

Con el contexto, el modelo puede decir "esto no cumple el requisito", no solo "esto tiene mal estilo".

Errores frecuentes

Mi regla no se aplica. Ejecuta ocr rules check <archivo>. Casi siempre es una de estas: otra entrada anterior coincide antes (el caso de arriba), el patrón no cubre la profundidad (src/*.js no entra en subcarpetas; usa src/**/*.js) o hay un --rule que anula el proyecto entero.

Un archivo no se revisa aunque tiene regla. Las reglas no deciden si un archivo se revisa: eso lo hace el filtro. Mira el motivo con ocr review --preview y, si es default_path o unsupported_ext, añade el patrón a include.

Añadí include y ahora "solo revisa eso". No debería: include no es lista blanca. Si quieres limitar de verdad, usa exclude.

include no recupera vendor/. Si la carpeta está en la raíz del repo, se filtra al leer el diff (provider_directory) y no hay include que la recupere. Una vendor/ anidada (api/vendor/) sí se puede incluir.

.env no se revisa nunca. Es intencionado: las rutas de secretos se excluyen antes que tus reglas y no se pueden forzar.

Preguntas frecuentes

¿Puedo escribir las reglas en español? Sí. El texto de la regla va tal cual al prompt; nosotros las escribimos en español y el modelo las aplicó. Para que los comentarios también salgan en español, usa ocr config set language Español.

¿Dónde veo las reglas de sistema? Con ocr rules check sobre un archivo de ese lenguaje (sin reglas de proyecto que coincidan), o en internal/config/rules/rule_docs/ del repositorio (un Markdown por lenguaje).

¿Las reglas valen también para el modo delegación? Sí. ocr delegate rule <archivos> resuelve las mismas capas y agrupa los archivos que comparten regla. Lo verás en la parte 4.

¿Debo subir .opencodereview/rule.json al repo? Sí, está pensado para eso: así todo el equipo y el CI revisan con las mismas normas.

Conclusión

Un rule.json corto y bien ordenado es lo que más rendimiento saca a Open Code Review: reglas específicas primero, merge_system_rule: true cuando quieras sumar y no sustituir, e include para revisar lo que por defecto se ignora. Antes de fiarte de una regla, compruébala con ocr rules check.

En la parte 4 usamos estas mismas reglas desde Claude Code, sin API key, con el modo delegación.