Revisar el cambio contra el encargo

2196. Identidad de la lección

Módulo

5.8 — Revisión de código con IA

Lección

Revisar el cambio con respecto al encargo

Tipo académico

Laboratorio de depuración

Tipo de esquema

práctica

Orden

1

Tiempo estimado

35–45 minutos, incluida la práctica

Esta lección trata la revisión como una decisión de aceptación, no como una opinión general sobre la calidad del código.

2197. Objetivo de aprendizaje

Después de esta lección, podrás redactar una revisión priorizada de un diff generado por IA comparándolo con el encargo, comprobando su contrato y citando evidencia de aceptación.

2198. Por qué importa

Un cambio generado por IA puede compilar, verse pulido y aun así resolver el problema equivocado. Una revisión disciplinada protege el comportamiento solicitado frente a la ampliación del alcance y detecta omisiones antes de que sean más difíciles de aislar. En un flujo de trabajo nativo de IA, la responsabilidad de decidir si el cambio es aceptable corresponde a la persona revisora; el modelo no es quien define cuándo se ha terminado.

2199. Conocimientos previos

Ya deberías poder:

• distinguir un requisito de una preferencia de implementación;
• describir un contrato de sistema mediante entradas, salidas, estado y restricciones;
• inspeccionar un cambio generado por IA y compararlo con un encargo explícito;
• diferenciar un defecto, un problema de alcance y una preferencia de estilo que no bloquea la aceptación.

La lección anterior, 5.7 L2 — Rechazar una abstracción atractiva pero insegura, estableció que un cambio más pequeño y seguro es preferible cuando una abstracción más amplia no tiene un contrato estable.

2200. Concepto central

Una revisión compara tres elementos:

1. Encargo: Qué se pidió y qué se excluyó explícitamente.
2. Cambio: Qué añade, elimina o modifica realmente el diff.
3. Evidencia: Qué demuestra que el comportamiento solicitado funciona y que se conserva el comportamiento existente importante.

La revisión debe responder dos preguntas distintas:

• Contrato: ¿La implementación cumple el comportamiento y las restricciones solicitadas?
• Alcance: ¿Cambió algo que no era necesario para ese comportamiento?

Un cambio puede superar una pregunta y fallar la otra. Por ejemplo, una función puede funcionar y, al mismo tiempo, modificar sistemas que no formaban parte del encargo. Eso sigue siendo un hallazgo de revisión.

2201. Modelo mental

Usa el modelo Encargo → Diff → Evidencia → Decisión:

Asigna la gravedad según su efecto sobre la aceptación, no según cuánto te desagrada la implementación:

1. Bloqueante: El cambio incumple un comportamiento requerido, viola una restricción o exclusión explícita de aceptación, provoca una regresión grave o carece de evidencia para un comportamiento requerido. Un hallazgo bloqueante significa que el cambio no puede aceptarse hasta resolver el problema o revisar deliberadamente el contrato.
2. Importante: El cambio introduce alcance, riesgo o coste de mantenimiento evitable, pero la evidencia disponible no demuestra que impida actualmente la aceptación ni que viole una restricción vinculante. Solicita una corrección antes de aceptar cuando el riesgo sea relevante; no lo llames bloqueante sin demostrar su impacto en la aceptación o el contrato.
3. No bloqueante: La observación se refiere a claridad, nombres, formato u otra mejora que no afecta al comportamiento solicitado, las restricciones, la evidencia ni la decisión de aceptación.

Aplica esta política de decisión de manera coherente:

• Acepta cuando no quede ningún hallazgo bloqueante o importante sin resolver.
• Solicita cambios cuando sea necesario corregir algo antes de aceptar, pero ningún hallazgo bloqueante active un criterio formal de aceptación.
• Bloquea la aceptación mientras quede sin resolver algún hallazgo bloqueante.

Una exclusión explícita es vinculante cuando protege un contrato o un límite de aceptación declarado. Una preferencia de presentación no lo es. Explica la consecuencia y la evidencia que sustentan cada gravedad, y no ocultes un problema bloqueante bajo una lista extensa de preferencias.

2202. Ejemplo concreto

Supón que el encargo dice:

Añadir una acción de reintento para una solicitud fallida. La acción solo puede reintentar la solicitud fallida, debe mostrar un estado de reintento mientras este esté pendiente y no debe alterar la navegación ni el estado de guardado existentes. No introducir un marco general de solicitudes.

Un diff generado por IA:

• añade un botón de reintento;
• vuelve a ejecutar la solicitud fallida;
• modifica un ayudante compartido de navegación para reconstruir la pantalla;
• introduce un RequestController genérico que solo usa esta pantalla;
• incluye una captura que muestra el botón después del fallo;
• no muestra el comportamiento mientras el reintento está en espera.

Una revisión útil no dice simplemente “el código es demasiado abstracto”. Es priorizada y está vinculada al encargo:

1. Bloqueante — falta evidencia de aceptación: La evidencia entregada no demuestra el estado de reintento requerido mientras la solicitud está pendiente. Añade una prueba, traza o evidencia visual que muestre específicamente ese estado durante la espera. Hasta que exista esa evidencia, el comportamiento requerido no puede aceptarse.
2. Bloqueante — incumplimiento explícito del alcance: El cambio modifica el ayudante compartido de navegación aunque el encargo indica que no debe alterarse el comportamiento de navegación no relacionado. Demuestra que el cambio del ayudante es necesario para el contrato declarado y que conserva el comportamiento de navegación, o elimínalo y mantén el cambio local. Si la inspección demuestra que el cambio compartido es aislado e inocuo, pero sigue siendo innecesario, registra la preocupación restante como importante en lugar de afirmar una regresión que no se ha demostrado.
3. Bloqueante — exclusión explícita: RequestController es un marco general utilizado por una sola función y el encargo lo excluía expresamente. Sustitúyelo por el mecanismo local más pequeño, salvo que otro contrato existente demuestre que la reutilización es necesaria. El problema es bloqueante porque la implementación contradice un límite declarado, no simplemente porque la persona revisora prefiera una abstracción menor.

La captura es evidencia útil para un estado, pero no demuestra el contrato completo. Una captura más clara o unos nombres más limpios serían una observación no bloqueante por sí solos; la falta de comportamiento o evidencia requerida no lo es.

2203. Flujo de trabajo nativo de IA

Usa la IA como asistente de comparación, no como revisora final:

1. Entrega al modelo el encargo, incluidas las exclusiones y las condiciones de aceptación.
2. Pídele que reformule el contrato como una lista de comprobación, sin proponer código.
3. Inspecciona el diff por tu cuenta y marca cada zona modificada como necesaria, de apoyo o no relacionada.
4. Pide al modelo que compare tu inventario con el encargo e identifique posibles omisiones o ampliaciones de alcance.
5. Verifica cada hallazgo sugerido contra el diff real y la evidencia disponible.
6. Redacta la revisión final con tu propio orden de prioridad y cita el comportamiento o la zona modificada que sustenta cada hallazgo.

No preguntes “¿Se ve bien?”. Esa pregunta favorece una aprobación general. Formula preguntas que expongan omisiones: “¿Qué requisito del encargo no tiene evidencia?” y “¿Qué zona modificada no es necesaria para el comportamiento solicitado?”.

2204. Error común

El error común es tratar la ejecución correcta como prueba de aceptación. Un cambio puede producir el resultado visible y, aun así, incumplir una exclusión, modificar un contrato compartido o dejar sin probar un estado importante. Otro error frecuente es informar de todas las preferencias con la misma gravedad, o llamar bloqueante a un cambio innecesario sin identificar su consecuencia sobre la aceptación o el contrato. Una revisión debe reservar la categoría bloqueante para riesgos demostrados de aceptación, restricciones vinculantes, regresiones graves o carencias de evidencia requerida; las mejoras de presentación permanecen como no bloqueantes.

2205. Práctica guiada

Revisa este encargo ficticio, el rango de commits, el resumen generado por IA y el paquete de evidencia.

Encargo: Añadir una interacción de mantener pulsado para una acción destructiva. La acción solo debe completarse cuando se alcance toda la duración; debe reiniciarse si el puntero sale del objetivo y no debe cambiar el comportamiento actual de cancelación. Mantén la implementación local a la pantalla de la acción.

Rango de commits: 8c21a4e..9af40bd

Resumen generado por IA — compruébalo contra el diff: «Añade una interacción local de mantener pulsado con progreso y conserva la cancelación».

diff --git a/ui/ActionScreen.ts b/ui/ActionScreen.ts
@@ function onPointerDown() {
+  holdProgress = 0;
+  showHoldProgress();
+  completeDestructiveAction();
 }
@@ function onPointerLeave() {
-  cancelCurrentPress();
+  // Preserve progress so the user can resume the hold.
 }
diff --git a/input/SharedInput.ts b/input/SharedInput.ts
@@ export type InputOptions = {
+  holdMode?: boolean;
 }

Paquete de evidencia:

• progress-50.png muestra el indicador de progreso al 50 %;
• cancel-test.txt informa de que pulsar Cancelar sigue cerrando la confirmación sin completar la acción;
• ninguna prueba, traza ni evidencia visual demuestra que la acción solo se complete tras alcanzar la duración requerida ni que el progreso se reinicie cuando el puntero sale.

Redacta tres hallazgos. Para cada uno, incluye:

• prioridad: bloqueante, importante o no bloqueante;
• la cláusula del encargo implicada;
• el archivo y el símbolo o hunk del diff afectados, vinculados con la cláusula correspondiente del encargo;
• la evidencia ausente o contradictoria;
• la acción siguiente solicitada;
• una frase que explique por qué la prioridad elegida corresponde a su efecto sobre la aceptación.

El contrato incompleto de duración y el comportamiento al salir el puntero son bloqueantes porque contradicen comportamientos requeridos. La utilidad compartida de entrada es bloqueante si su uso incumple el límite explícito de mantener el alcance local; si se revisa el encargo o la inspección demuestra que el cambio de utilidad está aprobado, no tiene impacto y solo sirve de apoyo, vuelve a evaluarlo como importante en lugar de asumir que todo cambio en un archivo compartido es bloqueante. No clasifiques como bloqueante ni importante una observación de presentación, como hacer más claro el texto del indicador de progreso, salvo que afecte a un requisito declarado.

Debes tomar una decisión explícita: aceptar el cambio, solicitar cambios o bloquear la aceptación. Tu decisión debe desprenderse del hallazgo de mayor prioridad, no del número de hallazgos.

2206. Validación / evidencia

2207. Puntos clave

• Revisa el encargo, el diff real y la evidencia de aceptación como fuentes separadas.
• Comprueba tanto el cumplimiento del contrato como la disciplina de alcance.
• Asigna una gravedad bloqueante, importante o no bloqueante según el impacto en la aceptación y la evidencia.
• Trata la falta de evidencia como un hallazgo bloqueante cuando no pueda aceptarse de otro modo el comportamiento requerido.
• Usa la IA para exponer omisiones; después verifica los hallazgos y asume el juicio final.

2208. Próxima lección

Continúa con 5.8 L2 — Encontrar la causa raíz, la responsabilidad y el riesgo de regresión.

2209. Comprobación