CubeLabs

1. El problema: revisar con señal, no ruido

Un agente generalista puede leer un diff, pero en cambios grandes tiende a omitir archivos, perder la posición de una línea o producir avisos poco accionables. OpenCodeReview parte de una pregunta concreta: ¿cómo hacer que las partes que no pueden fallar dependan de ingeniería determinista y no solo de texto?

2. Arquitectura híbrida: restricciones más juicio

El proyecto combina un pipeline determinista con un agente que recupera contexto y razona sobre el caso. El pipeline decide qué archivos entran, agrupa unidades relacionadas y aplica reglas por tipo de archivo; el LLM se concentra en entender dependencias, riesgos y semántica.

• Bundling: archivos relacionados se revisan en una misma unidad.
• Reglas finas: el contexto del modelo se ajusta al archivo y escenario.
• Posicionamiento: se valida que el comentario apunte a la línea correcta.

3. Instalación y requisitos

Necesitas Git 2.41 o superior porque la herramienta usa Git para generar diffs, buscar código y operar sobre el repositorio. La distribución recomendada se instala desde npm y expone el comando ocr.

$ git --version
$ npm install -g @alibaba-group/open-code-review
$ ocr --help

4. Configurar el proveedor LLM

Antes de una revisión normal debes elegir un proveedor y un modelo. El asistente interactivo guarda la configuración y prueba conectividad; nunca incluyas una clave API en un commit o captura de pantalla.

ocr config provider
ocr config model

La alternativa es el modo de delegación: el host de IA ejecuta el razonamiento mientras OpenCodeReview resuelve selección de archivos y reglas. Es útil cuando ya trabajas con un agente compatible.

5. Tu primera revisión del workspace

En el directorio del proyecto, ocr review revisa cambios preparados, no preparados y archivos sin seguimiento. Haz cambios mínimos y lee cada comentario junto a su línea y el contexto del archivo.

cd mi-proyecto
ocr review

# Guardar una salida que otro proceso pueda consumir
ocr review --format json --output result.json

El JSON permite separar la generación de hallazgos de su presentación: puedes archivarlo como artefacto de CI, filtrarlo por severidad o convertirlo en comentario de pull request.

6. Ramas, commits y sesiones recuperables

Para revisar una funcionalidad completa, delimita el rango de ramas. OpenCodeReview usa el punto de divergencia de Git para comparar tu trabajo con la base indicada. Para un cambio histórico, apunta a un commit específico.

# Cambios entre la base y la rama de funcionalidad
ocr review --from main --to feature-branch

# Un commit concreto
ocr review --commit abc123
# Reanudar una ejecución interrumpida
ocr session list
ocr review --from main --to feature-branch --resume <session-id>

7. Escanear código cuando no hay diff

Un diff no siempre existe: quizá estás auditando un repositorio heredado o evaluando un directorio antes de modificarlo. ocr scan revisa archivos completos en lugar de depender del historial.

# Todo el repositorio
ocr scan

# Solo una zona de riesgo
ocr scan --path internal/agent

# Reanudar un análisis amplio
ocr scan --resume <session-id>

Limitar --path hace la primera auditoría más asequible y facilita validar la calidad de los resultados.

8. Reglas y salida estructurada

Las reglas permiten que una revisión de migraciones SQL no use el mismo criterio que una de autenticación o componentes de interfaz. El diseño de OpenCodeReview busca resolver reglas por archivo, evitando cargar instrucciones irrelevantes en cada llamada al modelo.

Empieza por reglas breves y verificables: “no registrar tokens”, “validar autorización antes de mutar datos” o “añadir prueba para cada ruta de error”.

9. Integración con agentes y CI

El repositorio incluye integraciones para Claude Code, Codex, Cursor, Kimi Code, OpenCode y agentes compatibles con skills. En delegación, puedes inspeccionar lo que la herramienta preparó antes de ceder el análisis al agente.

ocr delegate preview
ocr delegate rule src/main.go src/handler.go

10. Flujo de trabajo responsable

Una adopción gradual es más útil que imponer un bloqueo automático el primer día. Comienza con informes, compara los hallazgos con revisiones humanas y ajusta reglas. Después, automatiza solo las condiciones con evidencia sólida.

1. Haz una revisión local de un cambio pequeño.
2. Guarda JSON y clasifica falsos positivos o hallazgos útiles.
3. Define reglas por rutas críticas.
4. Prueba en CI como aviso antes de convertirlo en requisito.

Lista de verificación antes de aceptar un hallazgo

Trata cada comentario como una hipótesis que debe convertirse en una afirmación comprobable. Abre el archivo señalado, mira el bloque que llama a esa línea y sigue el dato hasta su origen. Un comentario de seguridad es útil si especifica el activo afectado, la condición que lo activa y el impacto; “esto parece inseguro” no basta para bloquear una entrega.

Ejemplo: revisión de una modificación de autorización

Supón que una rama cambia un controlador para actualizar el perfil de un usuario. Una revisión seria no se limita a buscar la palabra auth. Debe seguir el identificador del usuario: ¿viene de la sesión autenticada o del cuerpo de la petición?, ¿la autorización se evalúa antes de escribir?, ¿la consulta está filtrada por organización?, ¿la prueba cubre a un usuario no propietario? Estas preguntas convierten una alerta genérica en un criterio técnico claro.

# Crear un cambio mínimo y revisar solo lo que cambió
git checkout -b ejemplo-perfil
git diff --stat main...HEAD
ocr review --from main --to ejemplo-perfil --format json --output review.json

# Inspeccionar después el artefacto y contrastarlo con las pruebas
python -m json.tool review.json

No automatices una corrección solo porque un modelo la sugiera. Para cada hallazgo aceptado, redacta el motivo de la corrección, añade una prueba que hubiera detectado el defecto y vuelve a ejecutar la revisión. El valor está en cerrar el bucle: cambio, evidencia, prueba, revisión y decisión.

Medir la calidad del proceso

Durante las primeras semanas, conserva una muestra de revisiones humanas y calcula cuántas observaciones del sistema eran correctas. La precisión representa qué fracción de los avisos fue realmente útil; la cobertura señala qué parte del cambio recibió revisión; y el tiempo de ciclo indica si el control está ayudando o frenando al equipo. No uses una métrica aislada: un sistema muy silencioso puede parecer preciso y, sin embargo, no detectar problemas importantes.

OpenCodeReview publica un benchmark basado en 50 repositorios open-source, 200 pull requests y 10 lenguajes, con incidencias anotadas por revisores. Ese tipo de benchmark es una señal para explorar la herramienta, no una garantía de que tendrá el mismo comportamiento con tu lenguaje, reglas, proveedor o código propietario. Ejecuta una evaluación propia antes de definir políticas de bloqueo.

Política gradual para CI

Si el código o los logs son sensibles, consulta primero las políticas de datos y del proveedor LLM. Un diff puede contener credenciales, información personal o detalles de infraestructura. Filtrar archivos, usar proveedores aprobados y rotar claves comprometidas son controles previos, no tareas posteriores.

Diseñar una prueba de evaluación interna

La forma más honesta de saber si una herramienta sirve a tu equipo no es repetir una cifra pública: es medirla contra cambios que tu equipo entiende. Construye una muestra pequeña de pull requests ya fusionados. Incluye cambios de bajo riesgo, correcciones de errores, modificaciones de autorización, migraciones y refactorizaciones. Para cada caso, anota qué defectos detectó el equipo en la revisión o después del despliegue, y separa los hechos conocidos de las conjeturas.

Ejecuta OpenCodeReview con la misma configuración sobre toda la muestra. Después compara sus observaciones con una rúbrica sencilla: confirmado si el problema existe y el comentario permite localizarlo; útil pero incompleto si señala una zona que merece atención; falso positivo si una defensa existente lo invalida; y no accionable si no ofrece suficiente contexto para tomar una decisión. Esta rúbrica evita que “parece interesante” se convierta en una medida engañosa de calidad.

Qué pedir a una regla de revisión

Una buena regla describe una propiedad comprobable y el contexto en que importa. “Escribe código seguro” es demasiado amplio. “En rutas que modifican un recurso, comprueba que el identificador de la sesión tiene permiso sobre el recurso antes de persistir” señala qué buscar, dónde y por qué. Empieza con unas pocas reglas relacionadas con fallos que ya hayas visto; aumenta el conjunto solo cuando puedas evaluar su efecto.

# Ejemplo de preparación antes de una revisión de rama
# 1. Actualiza la referencia base sin cambiar tu trabajo local
git fetch origin main
# 2. Inspecciona qué archivos estarán en el alcance
git diff --name-status origin/main...HEAD
# 3. Revisa el rango y guarda un artefacto trazable
ocr review --from origin/main --to HEAD --format json --output review.json

El segundo paso importa: si la lista de archivos no coincide con tu expectativa, no interpretes el resultado del LLM todavía. Puede que la base esté desactualizada, que la rama contenga merges inesperados o que el rango no represente la propuesta real. La reproducibilidad de una revisión empieza por la identidad del diff.

Comentarios que ayudan a aprender

Al responder a un hallazgo, deja una nota breve que conecte causa y decisión. Por ejemplo: “confirmado: el identificador venía del cuerpo de la petición y permitía editar otro usuario; añadimos comparación con session.userId y una prueba negativa”. O: “falso positivo: el middleware requireOrgRole se ejecuta antes del controlador y la prueba de integración cubre el rol”. Con el tiempo, esas decisiones se convierten en material para mejorar reglas, pruebas y documentación del equipo.

Finalmente, conserva el control de versiones de la configuración de revisión junto al código cuando sea apropiado. Igual que una regla de lint o una prueba, una regla de revisión puede introducir ruido, quedar obsoleta o necesitar una explicación. Revisarla en pull request permite discutir su alcance y evita que una política invisible cambie el comportamiento de la automatización.