Revisión con IA

La forma de una revisión

Una revisión con IA es una ejecución del pipeline predefinido pr_review contra una pull request abierta. El pipeline abre el espacio de revisión del PR, despliega agentes revisores para leer el diff en el checkout aislado de ese espacio, cada uno registra sus hallazgos como nodos de revisión estructurados, un agente líder los consolida en un recorrido guiado y un finalizador calcula un único veredicto: Ship, Hold o Block. Lo que el pipeline nunca hace es publicar: publicar en GitHub es un paso aparte y deliberado que da una persona.

El resto de esta página explica las piezas y por qué tienen esta forma.

Un espacio de revisión por PR

El contexto de revisión de un PR es un espacio de mensajería —modo review, tipo pr— vinculado a la pull request mediante una asociación de espacio de revisión. Se crea de forma idempotente: la página del PR, el pipeline de revisión y las superficies de chat resuelven el único espacio subyacente del PR por la misma ruta de código, así que una plantilla que revisa un PR y una persona que lo abre nunca pueden acabar en dos salas distintas mirando dos checkouts distintos.

El worktree aislado del espacio tiene el PR en checkout en su ref head. Una sola sala también significa un solo checkout: todos los revisores trabajan en el mismo espacio en lugar de tener cada uno su propio clon del espacio de trabajo.

Cada revisor publica en su propio flujo con nombre dentro de ese único espacio, y los hallazgos son mensajes review_node en lugar de prosa sin más. La recopilación de todo el espacio al final es deliberada: un veredicto calculado a partir de los hallazgos de un solo hilo sería en silencio un veredicto sobre un solo revisor.

La asociación lleva una secuencia de estados —requested → in progress → awaiting approval → completed—, que es lo que condiciona el botón Publicar en GitHub en la pestaña Revisar del PR.

Niveles de revisión

Hasta dónde llega una revisión es una política del espacio de trabajo con tres niveles, que se define en Ajustes → Espacio de trabajo → General, en la tarjeta Política del espacio de trabajo:

Nivel	Revisores que se despliegan	Informe
light	Solo el ingeniero	Solo lo que importa de verdad
balanced	Ingeniero, QA y arquitecto (el predeterminado)	La pasada habitual
thorough	Los cinco, incluidos seguridad y rendimiento	Nada se degrada

El nivel mueve dos diales a la vez: qué revisores se despliegan, algo que imponen las compuertas de estado del runWhen de la plantilla del pipeline y no el texto del prompt —el texto del prompt se puede ignorar, una compuerta no—, y dónde se muestran los hallazgos por debajo del umbral. Ninguno de los dos diales elimina jamás un hallazgo: un nivel que informa de menos sigue registrando exactamente lo mismo y agrupa el resto.

Las pasadas de seguridad y rendimiento reutilizan los agentes predefinidos de arquitecto e ingeniero en lugar de introducir otros nuevos. La especialidad está en el encargo con el que se despacha al revisor, no en un agente aparte por eje: un agente por eje serían cinco filas más en cada espacio de trabajo sin ninguna capacidad adicional. La selección de revisores nunca inspecciona el diff en busca de lenguaje o dominio.

Nodos de revisión: hallazgos como datos, no como prosa

Un hallazgo registrado con add_review_node se convierte en un nodo de revisión del PR, que es lo que representa la pestaña Revisar, lo que se usa para calcular el veredicto y lo que «Publicar en GitHub» convierte en un comentario en línea. Un revisor que solo devuelve prosa produce una ejecución del pipeline que parece correcta y una superficie de revisión vacía; el registro es la parte que sostiene todo lo demás.

Cada nodo incluye:

Campo	Valores
Tipo	bug, suggestion, recommendation, question, ticket
Prioridad	P0 (crítico) → P3 (detalle menor)
Tripleta de triaje	categoría (security, stability, …), gravedad, esfuerzo
Ancla	Ruta de archivo, línea de inicio y de fin
Carga de corrección	Líneas de reemplazo sugeridas, un diff opcional y un prompt de corrección opcional
Confianza	Una puntuación en [0, 1]
Razonamiento	El análisis, escrito antes del hallazgo

Dos detalles son deliberados. Solo se ofrece una sugerencia de GitHub con un clic cuando el revisor ha facilitado líneas de reemplazo exactas: inferirlas a partir de un diff unificado sale mal en silencio, y un commit con un clic de una inferencia errónea es peor que no tener ningún botón. Y el esquema de add_review_node presenta reasoning antes del hallazgo, de modo que un modelo que rellena el objeto en el orden del esquema escribe primero el análisis. El campo es opcional: omitirlo no rechaza el nodo. Un nodo cuyo payload tenga un formato incorrecto desaparece en lugar de contaminar la revisión.

Consenso entre pares

Un nodo pasa por open → consensus-ready → resolved o dismissed. El paso intermedio es el corazón del modelo: un hallazgo solo asciende cuando lo confirma un revisor par, y un agente nunca puede confirmar su propio hallazgo. La herramienta MCP publish_review_to_github y el valor predeterminado de RPC siguen publicando solo los hallazgos confirmados por pares. En cambio, el botón Publicar en GitHub de la pestaña Revisar envía todos los hallazgos abiertos que queden.

La regla se aplica en tres lugares independientes —la herramienta de confirmación, el finalizador y el publicador—, así que sobrevive a un llamador con errores en cualquiera de ellos. Todos los cambios de estado pasan por un único servicio, que es lo que hace que un estado signifique algo: antes de eso, dos rutas a medias podían discrepar sobre si el mismo hallazgo se había resuelto.

Cuando los revisores discrepan —mismo archivo y misma línea, prioridades separadas por dos niveles o más, o uno que lo llama bug mientras el otro lo llama suggestion—, la discrepancia se muestra encima de la lista de hallazgos. Ahí es donde las opiniones de los revisores divergen y donde más vale el criterio de una persona.

Descartar un hallazgo también escribe un hecho de supresión débil en el dominio de memoria, con baja confianza: un descarte es una preferencia, no una regla.

Cohortes: aquello en torno a lo que se agrupa la revisión

La pasada de cómputo de la revisión agrupa los archivos modificados de un PR en cohortes derivadas del grafo de código: los archivos modificados se asignan a los símbolos que tocan, los símbolos a los componentes conectados, y las cohortes se ordenan por radio de impacto. Una cohorte incluye un orden de lectura guiado, diagramas y conclusiones en lugar de ser una lista plana de archivos.

Dos reglas de honestidad dan forma a esto. Las claves de cohorte se derivan del contenido y son estables entre pushes, así que los hallazgos y el progreso de la revisión sobreviven a un rebase o a un push forzado en lugar de quedar huérfanos. Y cuando el repositorio no tiene índice de código, la agrupación recurre a rutas simples y lo indica: la alternativa nunca finge confianza semántica.

Ejes de revisión y compuertas

Junto a los hallazgos de los revisores, una revisión acumula resultados de eje: seis ejes, de dos tipos.

Eje	Tipo	Se obtiene de
correctness, security	Basado en tokens	Los propios hallazgos de los revisores
testGap	Basado en tokens	Los hallazgos de los revisores
visual, apiContract	Determinista	Se calcula sin gastar tokens
performance	Determinista	Solo un enum: nada en el producto calcula un resultado

Un veredicto de eje es pass, warn, fail, partial o unavailable, y solo pass o warn superan una compuerta. La distinción entre fail, partial y unavailable es determinante: un eje con compuerta que no pudo completarse o que no pudo ejecutarse en absoluto retiene el veredicto global en lugar de aprobarlo. La ausencia de pruebas nunca se convierte en una compuerta verde.

Algunos ejes son orientativos a propósito. El eje de brecha de tests derivado de las cohortes no puede ver la cobertura de inyección de dependencias ni de factorías: un repositorio sin indexar con una batería de tests exhaustiva y otro sin ningún test se ven idénticos desde ahí, así que afirmar cualquiera de las dos cosas sería mentira; aparece en el panel sin actuar como compuerta. Los ejes de tokens son orientativos porque las prioridades de los hallazgos ya determinan el veredicto, y volver a condicionarlo con ellos supondría contarlo dos veces.

El veredicto

El finalizador calcula el veredicto sobre los hallazgos con estado open o consensus-ready:

• cualquier hallazgo P0 con confianza ≥ 0,7 → Block
• si no, cualquier P0 (de baja confianza) o cualquier P1 → Hold
• si no → Ship

El veredicto incluye una confianza agregada derivada de la dispersión de las confianzas que contribuyen: el acuerdo la sube y la divergencia la baja.

La consolidación del agente líder (CEO) es una pasada editorial, no una nueva lista: una segunda copia escrita a mano de los hallazgos es justo lo que acaba divergiendo de la real. Los hallazgos duplicados se degradan en lugar de repetirse: varios revisores apuntan a un mismo diff con ámbitos deliberadamente solapados, así que un mismo defecto que llega tres veces al finalizador es el sistema funcionando bien; publicarlo tres veces es el sistema filtrando su propia arquitectura a la bandeja de entrada del lector. En una nueva revisión, se calcula la huella de los hallazgos y se comparan con la ronda anterior, así que lo que aparece es el delta.

Por último se incorporan los ejes, y solo pueden hacer el veredicto más grave: un eje con compuerta que falla fuerza Block —los hallazgos no pueden ganarle por votos—, y un eje con compuerta que no pudo completarse fuerza como mínimo Hold.

Publicar sigue en tus manos

El pipeline no publica en GitHub a propósito; la publicación la controla el usuario, así que una revisión nunca puede publicarse dos veces. Cuando pulsas Publicar en GitHub:

• Se envía una única revisión a GitHub. Se omiten los hallazgos ya resueltos o descartados. El botón publica todos los hallazgos abiertos que queden (selection: all_open). La herramienta MCP publish_review_to_github sigue usando de forma predeterminada solo los hallazgos confirmados por pares (consensus).
• Los hallazgos anclados a un archivo y una línea se convierten en comentarios en línea; todo lo demás se integra en el cuerpo del resumen, y cada uno lleva un pie de página «— Control Center AI review» para que la fuente no deje lugar a dudas.
• Las anclas se vuelven a verificar contra el diff actual del PR en el momento de publicar. Un comentario sobre código que ya se ha reescrito es lo que más destruye la confianza que puede dejar un revisor; si GitHub rechaza igualmente un ancla en línea, se reenvía toda la revisión con todos los hallazgos integrados en el cuerpo para que nada se descarte en silencio.
• Un veredicto Block se envía como REQUEST_CHANGES; Hold como COMMENT; Ship como APPROVE desde el botón (approve_on_ship: true). La herramienta MCP deja Ship como COMMENT a menos que pases approve_on_ship.
• La revisión se publica con la identidad de la app del servidor. Quién pulsó Publicar queda registrado para el control de roles y el registro de auditoría; no es el autor en GitHub.

Publicar declara la clase de acción prPublish, así que el punto de control de las barandillas lo condiciona como cualquier acción que muta: pide aprobación de forma predeterminada y falla en cerrado cuando no hay ningún aprobador conectado. Consulta Barandillas.

Qué puede hacer un revisor

Los agentes revisores se ejecutan en modo review: un entorno aislado de solo lectura y una lista blanca de herramientas seleccionadas que abarca hallazgos, comentarios, tickets y revisión entre pares, pero ninguna mutación. Un revisor no puede corregir el código que critica; puede adjuntar una corrección sugerida que aplica una persona. El mensaje de rechazo del modo indica al agente que intenta actuar de todos modos que finalice la revisión y deje que el usuario actúe sobre el resumen publicado.

Conceptos relacionados

• Barandillas — el motor de políticas que condiciona la publicación
• Modos — qué cambia el modo review para un agente
• Pipelines y automatización — el motor sobre el que se ejecuta la revisión
• Ciclo de vida del despacho de agentes — de dónde sale el worktree aislado

Guías relacionadas

• Usar revisión con IA — ejecuta una revisión y publícala
• Despachar agentes revisores — elige tú los revisores
• Cómputo de revisión — cohortes, ejes y diffs