Paul Jialiang Wu agentic-portfolio English 中文 한국어 日本語✉️ Lista gratuita
← Volver al portafolio

Serie AI-Native · Ingeniería de agentes · Ingeniería de bucles en la práctica

Revisión de PR con IA que no puede mentir

Evidencia por afirmación, "unmeasured" en vez de silencio, y un área de rutas para auto-merge. Un informe de construcción de un repositorio donde la revisión humana se había vuelto el cuello de botella, escrito para el cofundador que lo pidió y para cualquiera que esté por entregarle el botón de merge a un modelo.

Por Paul Jialiang Wu · futuremake.io · 2026-09-08

Cover: white ground with a black left rail. Eyebrow AI-NATIVE SERIES · AGENT ENGINEERING · AI PR REVIEW above the serif title AI PR Review That Cannot Lie, two grey lines: Every claim cites a file:line. Silence is never 'fine'. The AI merges only inside a path envelope it did not choose. Three grey cards: WHAT IT IS, a reviewer that asks, 26 rules as data: 7 machine, 13 AI, 6 human; WHO IT IS FOR, one maintainer, many PRs, where human review is the bottleneck; WHAT YOU LEAVE WITH, a 30-minute build contract, rules file, brief, envelope, negative test. A black band: THE ONE FINDING · FIRST TWO LIVE RUNS, ONE PRIVATE REPO, DAY ONE — 2 runs, 2 'unmeasured', 0 false greens. The reviewer's first two verdicts were about itself: no API key, then an invalid one. It said so both times.
Los dos primeros veredictos del revisor fueron sobre sí mismo. Alcance del número: un repositorio privado, las dos primeras ejecuciones en vivo, el día que se lanzó el workflow. Ningún PR estaba dentro del área de rutas, así que no había ruta de merge alcanzable en ninguna ejecución: el cero mide la rama de honestidad, no el auto-merge.

Resumen en 1 minuto — lo que te llevarás

Qué es esto. Un informe de construcción sobre una AI PR review para una base de código de gestión de calidad en manufactura donde una sola persona había hecho merge de todos los PR y ningún PR había recibido nunca una revisión. El modelo lee cada pull request y publica un breve informe. No puede aprobar según su propio criterio, no puede hacer una afirmación sin archivo y línea, y no puede guardar silencio cuando no pudo ejecutarse.

Por qué importa. Para un ingeniero, un revisor de IA que puede inventar hallazgos o guardar silencio cuando falla es peor que no tener revisor: enseña al equipo a ignorarlo. Para un fundador, el "auto-merge" es una decisión sobre el radio de impacto, no sobre la calidad del modelo, y este diseño pone ese radio en un archivo de datos que el modelo no puede modificar. Para un estudiante, es un ejemplo práctico del único hábito que separa una compuerta de una simple decoración: hacer que falle (se ponga en rojo) a propósito antes de confiar en que apruebe (verde).

Qué puedes hacer después de leer. Replica el esquema en treinta minutos: un archivo de reglas con tres niveles (máquina, IA, humano), un informe de ocho secciones con filtro de evidencia, un área de rutas con lógica de 'deny-wins' (gana la denegación), cinco condiciones AND para auto-merge y una prueba negativa que ejecutas antes de ponerlo en producción. La sección Constrúyelo en 30 minutos es el contrato; la sección del primer día muestra cómo se ve cuando el contrato se cumple incluso con una clave incorrecta.

Qué cubre este informe y por qué una revisión de PR por IA necesita un diseño diferente

Este es un informe sobre una semana de trabajo. Un equipo con el que colaboro identificó la "revisión de PR por un humano" como el único cuello de botella para la velocidad de iteración, y me asignó dos tareas para el mismo día: desplegar un revisor automático en el repositorio y escribir el estándar de revisión que debe aplicar. El repositorio es un sistema de gestión de calidad (QMS) para fábricas, donde cada registro puede ser solicitado después como evidencia en una auditoría de cliente. Eso eleva la importancia de la revisión de una manera concreta: un bug mergeado no es solo un bug, es un registro falso.

La pregunta de diseño no es "¿puede un modelo revisar código?". Los modelos revisan código lo suficientemente bien como para ser útiles. La pregunta es qué debe estar prohibido en una AI PR review para que un equipo siga confiando en ella después del décimo PR. Mi respuesta son cuatro prohibiciones y un alcance de rutas, y todo el artículo son esas cinco cosas con su evidencia:

  1. El revisor no puede hacer una afirmación sin una file:line cita. Las afirmaciones sin respaldo se descartan, y el número de descartes se imprime en el informe.
  2. El revisor no puede guardar silencio. Si falta la clave, hay una negativa del modelo o un error de API, cada caso produce un comentario publicado que dice "unmeasured" y "esto no es 'sin problema'".
  3. El revisor no puede volver a juzgar lo que los scripts ya decidieron. El aislamiento de inquilinos, secretos, migraciones, claves foráneas, documentación bilingüe, pruebas y la biblioteca de casos dorados se adjuntan al informe tal como salen de los scripts que los generaron.
  4. El revisor no puede dejar la lista de solo para humanos vacía sin explicar el motivo. "Nada para que un humano juzgue" debe venir con su razón, o la ausencia se interpreta como "el revisor no se ejecutó".
  5. El revisor solo puede activar un merge dentro de un área de rutas que no eligió, y solo como una de cinco condiciones AND.

Lectores: ingenieros de IA que gestionan un mantenedor y muchos agentes; fundadores que necesitan decidir qué puede tocar el "auto-merge"; y estudiantes que quieren ver cómo se construye una compuerta honesta en vez de solo instalarla. La analogía viene después del problema, y es una imagen de un solo dominio: la cocina de un restaurante con tres filtros antes de que salga un plato.

El cuello de botella, medido antes de construir nada

Antes de proponer un revisor, saqué los propios números del repositorio, porque "la revisión es lenta" y "la revisión no existe" requieren soluciones distintas. Veinticuatro PR mergeados. Veinticuatro escritos por la misma persona. Veintitrés mergeados por su autor. Cero registros de revisión en los ocho PR que muestreé. Nueve PR abiertos de otros contribuyentes, todos con cero revisiones, el más antiguo esperando dieciséis días. El tiempo mediano de merge en la historia era de seis minutos; no era revisión rápida, era el autor mergeando su propio PR.

Dos hechos más moldearon el diseño. El CI había fallado en silencio durante once días el mes anterior, cada job muriendo en dos segundos sin pasos porque se habían agotado los minutos de Actions de la cuenta, y nadie lo notó porque un rojo sin pasos se ve igual que un rojo por fallo real desde lejos. Además, el repositorio era de un plan privado gratuito, lo que significaba que no había protección de ramas: cualquier PR en verde o rojo podía ser mergeado por cualquiera, y lo único que lo impedía era la memoria.

El estudio de Google sobre su propia práctica analizó logs de nueve millones de cambios revisados [5]; una práctica que nunca se ha ejecutado no produce tales logs, ni tal aprendizaje. Así que la situación real era un proceso de revisión nunca ejecutado, a punto de recibir nueve PR externos a través de una sola persona, en un repositorio sin capa de enforcement. Un revisor que ocasionalmente alucina un hallazgo, o que a veces falla en silencio, caería en un equipo sin hábito de comprobar. Por eso las prohibiciones van antes que el prompt (instrucción).

El modelo mental: tres filtros en la cocina de un restaurante

Hay una imagen que resume el diseño: la cocina, en el nivel de “dirigir un restaurante”. Un plato sale de una cocina seria tras pasar por tres etapas, y esas etapas son distintas en naturaleza, no solo en rigor.

En la cocinaEn el repositorio
La balanza, el termómetro, el control del ticket. Una balanza no opina. Si el plato no cumple con el peso, no sale, lo haya preparado quien lo haya preparado.Machine gates G1–G7. Scripts ya existentes: revisión AST de inquilinos y permisos, escaneo de formas de secretos, emparejamiento modelo-migración, cadena de evidencia de claves foráneas, emparejamiento de documentación bilingüe, pruebas, biblioteca de casos dorados. El rojo desactiva el botón de merge bajo protección de rama.
El sous-chef prueba la salsa y deja una nota: “la sal está alta en el tercer cucharón; si sale o no esta noche, es tu decisión”. La nota señala un cucharón, no un estado de ánimo.AI pre-review R1–R13. Un brief por PR. Cada hallazgo cita file:line. Hace las preguntas que solo una persona puede responder y sugiere un veredicto que no puede imponer.
El chef lee la nota, prueba esa cucharada y decide si sale o no.Solo para humanos H1–H6. Escenario de negocio, responsable, nodo de aprobación, criterios de cierre, definición de KPI, merge ahora. Un code owner responde solo a lo que plantea el brief.
Entradas frías y aderezos que el sous-chef ya probó salen sin pasar por el chef, porque un aderezo equivocado se rehace, no se reembolsa.Tier-1 auto-merge. Docs, planes, archivos de prueba, casos dorados: bajo radio de impacto por ruta. El bot aprueba y habilita el auto-merge cuando se cumplen otras cuatro condiciones.
La línea caliente espera al chef. Siempre. El sous-chef nunca dice “mándalo” con un filete, por muy seguro que esté.Código de aplicación, migraciones, CI, scripts, frontend source nunca están en el alcance de rutas. La opinión de la AI sobre ellos es insumo, nunca disparador.

La razón por la que una cocina funciona así es la misma por la que el revisor funciona así. En cuanto la nota del sous-chef se convierte en lo que envía los platos, los cocineros empiezan a cocinar para la nota. En cuanto el veredicto de la AI se vuelve la condición de merge, los contribuidores empiezan a escribir PRs para complacer a la AI. Mantener la nota como nota, y la balanza como balanza, es lo que mantiene honestos a ambos.

Diagram titled AI PR REVIEW · THREE PASSES, ONE BRIEF, FIVE CONDITIONS FOR AUTO-MERGE. Top row, three cards: PASS 1 THE SCALE · GATES G1–G7, scripts decide, AI never re-judges, red greys the merge button; PASS 2 THE TASTE · AI R1–R13, one brief per PR, claims cite file:line, unbacked claim dropped and counted; PASS 3 THE CHEF · HUMAN H1–H6, answers questions the AI raised, an empty list must state why. Middle: THE BRIEF, one upserted PR comment, eight sections, never silent; no key, refusal or API error posts UNMEASURED. Bottom: TIER-1 AUTO-MERGE, all five AND-ed: 1 PATH ENVELOPE (docs, plans, test files, golden cases; deny wins for app, alembic, .github, scripts, src), 2 GATES GREEN (4 gate scripts green; tests: required CI check), 3 MEASURED + MERGE, 4 NO block or warn, 5 NO HUMAN ITEMS. All five: github-actions approves and enables auto-merge. Any one fails: label needs-human, list every unmet condition. Footer: negative test required before the reviewer counts as live.
Todo el mecanismo en una sola página. La condición 1 es una lista de prefijos de ruta en un archivo JSON; no depende de nada que diga el modelo.

El mecanismo: cuatro cosas que el revisor no puede hacer

1. Ninguna afirmación sin archivo y línea

El modelo devuelve una salida estructurada restringida por un esquema JSON:[4]una lista de hallazgos, cada uno con un id de regla, una severidad, una afirmación y unevidencearray. Antes de mostrar nada, un filtro recorre cada hallazgo y conserva solo las cadenas de evidencia que cumplenpath:linedonde la ruta está en los archivos modificados del PR o existe en el repositorio en ese commit. Un hallazgo sin evidencia sobreviviente se elimina y se incrementa un contador. El resumen termina con la línea "N claims without file:line evidence were dropped" (Traducción: Se descartaron N afirmaciones sin evidencia de archivo:línea).

Dos detalles importan. La ruta puede apuntar a un archivo que el PR no tocó, porque "esto entra en conflicto con el código existente" es justo el tipo de hallazgo cuya evidencia vive en un archivo antiguo; restringir la evidencia solo al diff eliminaría la categoría más valiosa. Y el conteo se imprime, no se oculta, porque un revisor que descarta silenciosamente la mitad de su propia salida te está diciendo algo sobre su calibración que quieres ver.

La instrucción del sistema lo resume así: las afirmaciones sin evidencia serán descartadas por el sistema, así que es mejor decir menos que inventar. El filtro es lo que hace que esa frase sea cierta y no solo una esperanza.

2. 'Unmeasured' es un estado publicado, nunca silencio

La primera versión del resumen, cuando no había clave de API, mostraba solo los resultados de las machine gates y nada más. Parecía un revisor sin objeciones. Esa es la salida más peligrosa que puede producir un revisor, porque desde fuera "no encontré nada" y "no ejecuté" suenan igual.

La solución es una rama que no se puede saltar. Si no hay credencial, si el modelo devuelve un motivo de rechazo, si la API falla o si la salida estructurada no se puede analizar, el resumen muestra una sección titulada "unmeasured" con la razón exacta, seguida de la frase "this is not 'no problem'" (Traducción: esto no es 'sin problema'), seguida de las machine gates y una nota de que ahora cada ítem solo para humanos necesita intervención humana. El workflow igual lo publica. Un test unitario verifica cada una de esas frases, así que un refactor no puede restaurar silenciosamente la versión silenciosa.

3. Las machine gates se adjuntan, no se re-juzgan

Existen siete machine gates, G1 a G7: un pase AST sobre routers para filtrado de inquilinos y dependencias de permisos; un escáner de forma de secretos sobre líneas añadidas que reporta posiciones y nunca muestra valores; emparejamiento de modelo a migración; una compuerta de clave foránea sobre cada*_idcolumna; emparejamiento de documentación bilingüe; los test suites; y una biblioteca de casos dorados donde los módulos deterministas deben reproducir sus salidas estándar. El propio revisor ejecuta los cuatro scripts que deciden seis de ellas, porque el script de gate de envío cubre secretos, emparejamiento de migraciones y docs bilingües en un solo pase; la séptima, los test suites, corre en sus propios jobs de CI y el revisor no los repite. Así que el resumen muestra cuatro líneas de script bajo "machine gates", y esas cuatro líneas cubren de G1 a G5 y G7. El revisor registra pass o fail con las últimas seis líneas de salida y entrega el resultado al modelo con la instrucción: esto ya está decidido, no lo vuelvas a decidir.

La razón no es que el modelo las vaya a fallar. Es que una segunda opinión sobre una verificación determinista es ruido, y el ruido en un resumen es lo que hace que la gente deje de leer resúmenes. El estudio de campo más citado sobre revisión de código moderna, en Microsoft, encontró que los revisores dedican su esfuerzo a entender más que a cazar defectos, y lo expresó así en el resumen:

"Our study reveals that while finding defects remains the main motivation for review, reviews are less about defects than expected and instead provide additional benefits such as knowledge transfer, increased team awareness, and creation of alternative solutions to problems." (Traducción: Nuestro estudio revela que, aunque encontrar defectos sigue siendo la principal motivación para la revisión, las revisiones tratan menos de defectos de lo esperado y en cambio aportan beneficios adicionales como transferencia de conocimiento, mayor conciencia del equipo y creación de soluciones alternativas a los problemas.)
— Bacchelli and Bird, ICSE 2013, author's copy[6]

Si los revisores humanos sobre todo construyen entendimiento, entonces un resumen de IA que repite una lectura de báscula está gastando la atención del lector en lo único que un script ya resolvió. El modelo debe enfocar su atención donde los scripts no llegan: si una acción de cierre escribe un registro de auditoría, si un endpoint de creación puede llegar a un estado terminal, si un router está haciendo lógica de negocio, si las afirmaciones de la descripción del PR tienen evidencia pegada.

4. Una lista vacía de solo para humanos debe justificarlo

La primera sección del resumen es "necesita tu juicio", y es la única sección que un code owner tiene que leer. Cuando está vacía, el modelo debe llenar un campo adicional con la razón, y el renderizador imprime "vacío; razón: …". Sin eso, una sección vacía es indistinguible de un modelo que nunca consideró la pregunta. Es el mismo principio que la prohibición dos, aplicado con más detalle: la ausencia nunca puede llevar significado.

Reglas como datos, y tres principios que se volvieron reglas

Las 26 reglas viven en un solo archivo JSON, no en el prompt (instrucción) ni en la documentación. Cada regla tiene un id, un nivel, un título, qué revisar, qué gate o persona la decide, y la fuente de donde se derivó. La tabla de la página de documentación se genera desde el archivo mediante un--render-rulescomando, y un--check-doc un comando en CI falla si la tabla en el documento difiere en un solo carácter de lo que genera el archivo. El prompt (instrucción) recibe la misma tabla renderizada. Tres consumidores, una sola fuente, sin desviaciones.

Siete reglas son de nivel máquina y cada una nombra el script que la decide; un test asegura que esos scripts existen, porque este repositorio antes había documentado un escáner de secretos que nunca se escribió. Seis son de nivel humano, tomadas de la checklist de 15 ítems del propio proyecto: los puntos que preguntan "¿qué problema real de fábrica resuelve esto?" no se pueden responder solo con un diff. Trece son de nivel AI. Diez de ellas son el residuo comprobable de las leyes de ingeniería del proyecto: registros de auditoría en acciones críticas, estados terminales inalcanzables desde endpoints de creación, cinco estados de UI, routers que solo orquestan, humanos que firman cada escritura alcanzable por AI, una sola responsabilidad, bitácora de implementación presente, tests para lógica pura modificada, cobertura de gates y descripción que coincide con la evidencia.

Las tres últimas se añadieron porque mi cofundador pidió una revisión "de acuerdo a nuestros principios de OOP, ingeniería de bucles e ingeniería de grafos", y un principio que solo vive en una conversación no es una regla. Así que:

ReglaLo que revisa el revisor
R11 OOPUna responsabilidad por cada nueva clase o función; reutilización de los dominios y capas de ciclo cerrado existentes en vez de copias; reglas de negocio escritas como funciones puras que pueden probarse sin base de datos; los routers solo orquestan.
R12 Ingeniería de buclesCada nuevo gate, regla o automatización se entrega con una forma de hacerla fallar a propósito; las máquinas de estados tienen estados terminales y un rollback; cualquier juicio puede re-ejecutarse con un solo comando; "unmeasured" se cuenta por separado de "passed".
R13 Ingeniería de grafosCada nuevo *_id declara una clave foránea; los efectos entre módulos (queja a acción correctiva del proveedor, violación SPC a problema de proceso, devolución a causa raíz) pasan por los hooks de ciclo cerrado en vez de escribirse en línea; cualquier registro puede rastrearse hasta su documento fuente y su responsable.

R12 es la regla del propio artículo aplicada a sí mismo, por eso existen las dos siguientes secciones.

El alcance de rutas: deciden las rutas, no la confianza

El equipo pidió que los PRs que cumplen el estándar hagan merge sin que una persona se interponga. El diseño anterior decía que la AI nunca debe ser condición de merge. Ambos tienen razón en algo, y la solución no es un compromiso entre ellos, sino otra variable. La pregunta "¿debería el veredicto de la AI causar un merge?" tiene una mala respuesta en ambos sentidos. La pregunta "¿dónde es lo suficientemente bajo el radio de impacto como para que un merge erróneo sea solo rehacer y no reembolsar?" sí tiene una respuesta basada en datos.

El alcance de rutas son dos listas de prefijos de ruta en el archivo de reglas. Permitido: documentación, planes, archivos de casos dorados, directorios de tests y cualquier cosa que termine en .md. Denegado, y la denegación prevalece sobre el permiso (deny-wins): el directorio de workflow, el de scripts, el paquete de la aplicación, las migraciones, el frontend, el Makefile y los dos archivos agent-guide. Un archivo Markdown bajo el directorio de workflow está denegado. Un archivo de test bajo el paquete de la aplicación está denegado. El modelo no ve esta lista como una opción; se aplica después de que el modelo responde.

Tier-1 entonces exige cinco cosas a la vez: cada ruta cambiada dentro del alcance de rutas; cada script de gate en verde (las cuatro líneas del brief; G6, los test suites, es un check de estado requerido que el auto-merge de GitHub espera); la revisión AI medida con veredicto de merge; cero hallazgos en severidad block o warn (un tercer nivel, info, se muestra en el brief pero nunca afecta el tier); y una lista humana vacía. Cuando se cumplen las cinco, el workflow aprueba el PR como la identidad de Actions y habilita el auto-merge de GitHub, así que el merge ocurre cuando terminan los checks requeridos. Si falla cualquiera, el PR recibe la etiqueta "needs human" y el brief lista todas las condiciones incumplidas, no solo la primera. Ese último punto vino de un test unitario: la primera implementación terminaba en el primer fallo, lo que significa que un contribuidor arreglaría "ruta fuera del alcance", volvería a ejecutar y solo entonces vería el hallazgo de nivel warn. Tres razones deben imprimirse como tres razones.

Dos ajustes de GitHub hacen que el visto bueno del bot cuente: el repositorio debe permitir que Actions apruebe pull requests [3], y la protección de ramas [1] no debe requerir que la aprobación venga de un code owner, porque la identidad de Actions no lo es. El auto-merge es una función propia de GitHub [2]; el workflow solo lo habilita. El archivo code-owners sigue dirigiendo las solicitudes de revisión a personas. El script de protección por defecto pide una aprobación requerida con el requisito de code-owner apagado, y muestra ambos ajustes del repositorio después de aplicarlos, porque un plan gratuito ignora silenciosamente el ajuste de auto-merge y un script que no lee de vuelta es un script que miente.

Día uno: los dos primeros veredictos del revisor fueron sobre sí mismo

El workflow se publicó en un PR, y ese PR fue lo primero que revisó. Todavía no había clave API en el repositorio. El brief lo dijo así: "unmeasured: ANTHROPIC_API_KEY missing (repository secret not configured). This is not 'no problem'." Debajo, los cuatro scripts de gate, todos en verde, y la línea de tier: needs human, porque las rutas cambiadas incluían el workflow y el directorio de scripts, y porque la revisión AI estaba unmeasured.

Mi cofundador añadió el secreto. El siguiente PR, el que agregaba el área de rutas (envelope), fue el segundo que revisó. El informe decía: "unmeasured: AuthenticationError 401, invalid x-api-key." (sin traducir, porque es salida literal del sistema). Misma línea de tier, mismos dos motivos, más un tercero: la clave que se le había dado a la plataforma no era una clave que la plataforma aceptara.

Dejo esto registrado como el resultado del primer día, no como una vergüenza, porque así es como el diseño responde bajo la carga para la que fue creado. Un revisor que hubiera guardado silencio en ambas ejecuciones habría producido dos PRs que parecían revisados y no lo estaban. En cambio, ambos PRs llevaron una declaración explícita de que la IA no había corrido, por qué, y qué implicaba eso para la persona. El mecanismo no hizo merge de ninguno por sí solo; ambos estaban fuera del área de rutas permitida, y además la segunda condición falló. Cero falsos verdes es el número; el alcance es dos ejecuciones, un repositorio, un día.

Ese mismo día hubo un segundo fallo silencioso, una capa más abajo. La protección de ramas es una función de pago en repositorios privados, y la actualización se había comprado. La API respondió a una actualización pagada con un 403 durante diez minutos seguidos de polling, y la configuración de auto-merge volvió a quedar en falso. El script de protección sale con código distinto de cero y la URL de upgrade cuando eso pasa; no simula éxito. La causa a nivel de cuenta sigue en diagnóstico mientras escribo esto, que es el estado honesto de la última condición, y está en la página y no en una nota al pie por la misma razón que el informe publica "unmeasured".

Patrones, antipatrones y el primer principio

Patrones que se mantuvieron. Evidencia como campo del esquema, filtrada por existencia, con el conteo de descartes impreso. Estados de fallo mostrados como secciones, nunca como ausencia. Chequeos deterministas adjuntados desde sus scripts, no re-derivados por el modelo. Reglas en un solo archivo de datos, renderizadas en el prompt (instrucción) y la documentación por la misma función, con verificación de drift en CI. Radio de impacto expresado como prefijos de ruta con la lógica de deny-wins (gana la denegación), aplicado después de que el modelo responde. Cada condición incumplida listada, no solo la primera.

Antipatrones que esto reemplazó. Un revisor que aprueba. Un informe que omite una sección para decir "sin problema". Un puntaje de confianza en vez de una cita. Una regla que vive en un prompt (instrucción) y otra copia en un documento. Un salto silencioso cuando falta la credencial. Un retorno anticipado que reporta una razón cuando hay tres verdaderas. Cada uno de estos parecía un primer borrador razonable y cada uno habría hecho que el revisor fuera más fácil de ignorar para el décimo PR.

El primer principio, en una frase. Una señal de revisión solo vale la pena si tanto su ausencia como su fallo son visibles, y sus afirmaciones pueden comprobarse sin tener que confiar en ella; todo lo demás en este artículo es esa frase aplicada a un botón de merge.

Constrúyelo en 30 minutos

Esto es el contrato, no el código. El código es específico de cada repositorio; el contrato sí se puede transferir. Treinta minutos es el tiempo que el contrato estima para quien copia la tabla en un repositorio nuevo; no es un tiempo que yo haya medido. La estructura base aquí se escribió de una sola vez, y las pruebas, los dos documentos y las ejecuciones del primer día tomaron el resto del día.

ElementoEspecificación
EntradasEl diff del PR contra la base de merge, ordenado por riesgo (primero el código de aplicación) y limitado por número de caracteres, con cada archivo omitido listado por nombre en el informe. El título y cuerpo del PR. El resultado (aprobado/fallido) y las últimas seis líneas de salida de cada machine gate existente. La tabla de reglas renderizada desde el archivo de reglas.
SalidaUn objeto estructurado:needs_human[] con regla, pregunta y motivo;needs_human_empty_reason; substance; risks[] yconflicts[] con regla, severidad en {block, warn, info}, afirmación, evidencia[];verdict en {merge, hold, request_changes};verdict_reason; post_merge_checks[]; global_notes[]. Se muestra como un solo comentario en Markdown en ocho secciones (necesita tu juicio, sustancia, riesgos, conflictos, veredicto, chequeos post-merge, tier de auto-merge, machine gates) con un marcador oculto para que las re-ejecuciones editen en vez de agregar.
InvarianteCada hallazgo mostrado tiene al menos una cadena de evidencia que coincide con path:line y cuyo path existe. El informe se publica en cada ejecución, incluso si falla. Los resultados de las machine gates aparecen textualmente. Una lista vacía de solo para humanos siempre lleva una justificación.
Regla de paradaEl modelo se ejecuta una sola vez por evento de PR. No hay reintentos si se rechaza o falla el parseo; esos casos pasan a "unmeasured". El proceso sigue aunque haya errores, para que una caída del revisor sea visible pero nunca bloquee un merge.
Esquema mínimoUn archivo de reglas: {id, level ∈ {block, ai, human}, title, check, gate, source} (el nivel de machine se escribe block en el archivo, después de lo que hace con el botón de merge) más auto_merge: {allow_prefixes, allow_suffixes, deny_prefixes}. Esa es toda la superficie de configuración.
El umbral de CIEl auto-merge solo se activa si se cumplen las cinco condiciones. La verificación de doc-drift (--check-doc) es una machine gate estática obligatoria. El propio job del revisor no es un check requerido.
Deliberadamente ausenteSin reintentos, sin segundo modelo como juez, sin puntajes de confianza (un hallazgo está evidenciado o se descarta), sin ponderación por regla, sin aprendizaje de PRs anteriores. Cada uno es un punto donde la primera versión habría ganado ingenio y perdido auditabilidad.
La prueba negativaAntes de ponerlo en producción: reproduce un PR con un defecto conocido. En este repositorio, el candidato es el fix que impidió que un endpoint de creación aceptara un estado cerrado directamente; revertir esos tres archivos debe producir un hallazgo R2 de nivel block apuntando al router. Un revisor que no se pone en rojo ante eso no cuenta como vivo. Esta ejecución está pendiente de la clave válida.
# The whole loop, from a PR event
diff, omitted   = collect_diff(merge_base, changed_files)      # risk-ordered, capped, omissions listed
gates           = run_machine_gates(base)                       # scripts decide; last 6 lines kept
review          = call_model(meta, files, diff, gates, rules)   # structured output, one call, no retry
review, dropped = filter_findings(review, files)                # path:line or it is gone; count kept
tier, reasons   = classify_tier(brief, envelope)                # five conditions, all reasons listed
brief           = render_brief(...)                             # never silent; unmeasured is a section
post_comment(pr, brief); apply_tier(pr, tier)                   # upsert; approve + auto-merge only on tier-1

Misma historia, cinco salidas

LectorLa decisión claveLa acción clave
EstudianteUna compuerta solo es una compuerta después de verla fallar (en rojo).Toma cualquier checker en el que confíes, rompe a propósito lo que verifica y confirma que falla. Si no falla, tienes solo una decoración.
IngenieroLa evidencia es una restricción del esquema, no una petición en el prompt (instrucción).Agrega un campo evidence[] a la salida de tu revisor, filtra por la existencia de path:line y muestra cuántos se descartaron.
FundadorEl auto-merge es una decisión sobre el radio de impacto; define ese radio en un archivo de datos.Escribe las listas de rutas permitidas y denegadas antes de escribir el prompt, y haz que la lista de denegadas siempre tenga prioridad (deny-wins).
Ejecutivo"Review exists" y "review has run" son afirmaciones distintas; mide la segunda.Pide el número de PRs sin registros de revisión, y el número de ejecuciones del revisor que reportaron "unmeasured".
InversionistaEl equipo que te muestra su revisor fallando a propósito ante un defecto plantado tiene un proceso de revisión; el que solo te muestra verdes tiene una captura de pantalla.Pide ver la prueba negativa.

Qué está medido, y qué aún no

Lee también

Parte de la Serie AI-Native · Ingeniería de Agentes. Los números en este artículo están acotados donde aparecen; la cocina es solo un modelo, no una métrica. El archivo de reglas, el revisor, el workflow, el script de protección y las pruebas descritas aquí existen en un repositorio privado; las estructuras se reproducen completas arriba para que nada dependa de tener acceso a ese repo.

Referencias

  1. GitHub Docs. Sobre ramas protegidas. docs.github.com — verificaciones de estado requeridas, revisiones requeridas y la disponibilidad de protección según el plan en repositorios privados.
  2. GitHub Docs. Fusión automática de un pull request. docs.github.com — el comportamiento de auto-merge en el que se apoya Tier-1.
  3. GitHub Docs. Administrar la configuración de GitHub Actions para un repositorio. docs.github.com — la configuración que permite que un workflow apruebe un pull request.
  4. Anthropic. Structured outputs. docs.anthropic.com — la respuesta restringida por esquema sobre la que opera el filtro de evidencia.
  5. Sadowski, C., Söderberg, E., Church, L., Sipko, M., Bacchelli, A. (2018). Modern Code Review: A Case Study at Google. ICSE-SEIP, DOI 10.1145/3183519.3183525. research.google · author's copy (PDF) — descrito, no citado: 12 entrevistas, una encuesta a 44 personas y registros de revisión de 9 millones de cambios revisados.
  6. Bacchelli, A., Bird, C. (2013). Expectativas, resultados y desafíos de la revisión de código moderna. ICSE 2013. copia del autor (PDF) — la cita anterior proviene del resumen de esta copia, revisada palabra por palabra contra el PDF; la versión oficial en IEEE puede diferir en la tipografía.