Definir un gate de clean build

1231. Identidad de la lección

Módulo

3.10 — Pipeline de build

Lección

Definir un gate de clean build

Tipo académico

Construcción guiada

Tipo de esquema

práctica

Orden

Lección 2 del módulo

Tiempo estimado

50–65 minutos, incluida la práctica

1232. Objetivo de aprendizaje

Después de esta lección, podrás escribir y ejecutar un checklist de clean build que conecte un estado limpio verificado y unas entradas declaradas con un artefacto identificable, criterios de aceptación observables y evidencia para cada decisión del gate.

1233. Por qué importa

Un build gate convierte el build de una demostración informal en un registro de decisión. Indica qué se construyó, a partir de qué entradas, en qué entorno y qué evidencia se necesita antes de avanzar con el artefacto. Esto es importante cuando los cambios asistidos por IA aumentan el número de ediciones posibles y hacen que la memoria deje de ser una fuente fiable de verdad. El gate no garantiza que el juego sea bueno; establece si este build es válido para la prueba definida.

1234. Conocimientos previos

Debes poder:

• Aplicar el modelo I-A-E-G de la lección anterior: inputs, artefacto, entorno y gate.
• Distinguir entre abrir el juego correctamente en una máquina y disponer de evidencia de un build reproducible.
• Identificar el target de build y el recorrido básico de inicio del proyecto.
• Identificar un commit o tag conocido de Git que pueda registrarse como revisión de origen del build.

1235. Concepto central

Un clean-build gate se documenta mediante cuatro elementos conectados: M-A-C-E.

1. Matriz: las combinaciones declaradas de target, configuración, entorno y entradas relevantes que se probarán.
2. Artefacto: la salida exacta que se evalúa, con una identidad distinguible vinculada a su revisión de origen y a las condiciones del build.
3. Criterios: condiciones observables que determinan si el resultado pasa, falla o queda bloqueado.
4. Evidencia: registros que demuestran el estado limpio declarado, las entradas, la identidad del artefacto, el entorno y el resultado de cada criterio.

Los cuatro elementos deben coincidir. Una matriz sin identidad del artefacto no puede demostrar qué se probó. Un artefacto sin criterios no puede establecer si el resultado es aceptable. Unos criterios sin entradas declaradas o sin evidencia no permiten respaldar la reproducción. La definición del estado limpio forma parte de las entradas y de la evidencia del gate; no sustituye a la matriz, la identidad del artefacto ni los criterios de aceptación.

El estado limpio es un espacio de trabajo en el que ningún artefacto generado previamente, salida temporal ni modificación local no declarada pueda confundirse con la salida que se está evaluando. Define la revisión de origen, las dependencias o paquetes, la configuración, el tratamiento de las salidas generadas y el tratamiento de cachés o datos temporales relevantes para el target. “La carpeta parecía normal” no es una definición suficiente.

La definición del estado limpio y su verificación son cosas distintas. La definición indica qué debe cumplirse. La verificación registra cómo comprobaste que se cumplía antes del build, qué observaste y dónde está la evidencia. Ejecutar un comando de limpieza por sí solo no demuestra el estado resultante.

Un clean build también separa dos decisiones:

• Resultado del build: ¿la cadena de herramientas produjo un artefacto?
• Resultado del gate: ¿ese artefacto cumple los criterios declarados en el entorno declarado y con evidencia suficiente?

Un build puede terminar correctamente y aun así fallar el gate o quedar bloqueado. Por ejemplo, puede producir un artefacto que no inicia, que omite el punto de entrada requerido o del que no existe evidencia de que proceda del estado limpio y de la revisión de origen declarados.

1236. Modelo mental

Usa M-A-C-E para cada gate:

El modelo I-A-E-G de la lección anterior describe el sistema. M-A-C-E es el documento de trabajo que crearás para operar su gate. Una fila útil del gate tiene esta forma:

Matriz → definición del estado limpio y entradas declaradas → identidad del artefacto → acción de prueba → resultado esperado → evidencia → estado

“No apareció ningún error” no es un criterio de aceptación. Indica qué puede observar el jugador, el tester o la persona que ejecuta el build.

1237. Ejemplo concreto

Supón que un juego pequeño tiene un solo target web compatible y una configuración de producción. Un registro débil diría:

El build pasó. Funciona en el navegador.

Un registro M-A-C-E más sólido diría:

Matriz: Web / producción / clase de navegador compatible
Estado limpio y entradas: revisión de origen COMMIT_OR_TAG; dependencias declaradas presentes; no se incluyen modificaciones locales no declaradas ni salidas generadas previamente; se registra el tratamiento de la caché relevante
Artefacto: contraband-web-build / COMMIT_OR_TAG / checksum cuando esté disponible
Criterios:
  1. El artefacto carga sin un error fatal de inicio.
  2. El punto de entrada previsto se vuelve visible.
  3. La acción principal del jugador produce la respuesta especificada.
  4. Recargar devuelve el juego al estado inicial definido.
Evidencia: registro de verificación del estado limpio, salida del build, commit o tag de Git registrado, entorno, resultado del inicio, notas del resultado de la acción e identificador del artefacto
Estado: PASS solo cuando existen evidencias del estado limpio, la identidad, el entorno y los cuatro criterios

El ejemplo no afirma que el juego esté terminado. Hace que una decisión concreta sobre un build sea inspeccionable y repetible.

1238. Flujo de trabajo nativo de IA

La IA puede redactar el documento, pero no puede aportar evidencia que tú no hayas verificado. Dale el target, la configuración, el entorno previsto, la revisión de origen conocida y la afirmación que debe respaldar el gate. Pídele que proponga pasos del checklist M-A-C-E e hipótesis de fallo. No le entregues secretos, tokens, claves privadas ni configuraciones sensibles sin redactar.

Después, revisa cada propuesta contra el proyecto y la ejecución reales. Corrige la matriz si el entorno o las entradas son incorrectos; corrige la sección del artefacto si la salida no puede distinguirse; corrige los criterios si no son observables; y corrige la evidencia si no muestra la verificación del estado limpio, la revisión de origen, el entorno, las salidas o los límites de secretos. La persona que aprende —no la IA— asigna PASS, FAIL o BLOCKED.

Puedes usar este prompt:

Redacta un checklist M-A-C-E de clean build para este target y configuración. Propón criterios de aceptación observables e hipótesis de fallo. No inventes evidencias, commits, identificadores de artefactos, detalles del entorno ni valores secretos. Marca lo desconocido para que pueda verificarse.

Trata la respuesta como un borrador. Sustituye los marcadores por evidencia observada, elimina las suposiciones sin respaldo y registra qué hipótesis de fallo propuestas se probaron o se descartaron.

1239. Error común

El error común es escribir el checklist como una lista de comandos de herramientas en vez de como un contrato comprobable. “Limpia la carpeta, ejecuta el build y abre el resultado” describe actividad, pero no aceptación. No indica qué significa limpio, cómo se verificó el estado, qué entradas se usaron, cómo se identifica el artefacto ni qué debe observarse después de iniciarlo.

Otro error frecuente es usar un único build correcto como evidencia para todas las filas de la matriz. Cada fila representa una afirmación distinta. Si cambia el target, la configuración, el entorno, el estado limpio o la revisión de origen, la evidencia debe quedar asociada a esa fila y no copiarse desde otra ejecución.

1240. Práctica guiada

Crea y ejecuta un clean-build gate para un target real de tu proyecto. No empieces escribiendo comandos. Empieza por definir la decisión que debe respaldar el gate.

1241. Paso 1: Define la matriz

Completa esta tabla con la matriz mínima útil para el hito actual:

Si solo se justifica una fila, conserva una sola. No añadas plataformas o configuraciones para que la matriz parezca completa. Marca cada fila como requerida o fuera de alcance y explica por qué se excluye una fila fuera de alcance.

1242. Paso 2: Define y verifica el estado limpio

Para cada fila requerida, escribe una definición del estado limpio independiente de las herramientas antes de elegir un comando de ejecución. Indica:

• Qué commit o tag conocido de Git corresponde a la revisión de origen.
• Qué dependencias, paquetes o entradas generadas están permitidos.
• Qué configuración y ajustes del target son obligatorios.
• Qué artefactos generados previamente, salidas temporales o modificaciones locales deben estar ausentes, excluidos o regenerarse de forma explícita.
• Qué tratamiento reciben las cachés o los datos temporales: permitidos, eliminados o irrelevantes para esta afirmación.
• Qué límites de secretos se aplican: ningún valor secreto debe copiarse en el checklist, los logs, las capturas, los prompts ni los artefactos.

Después, verifica la definición antes de producir el artefacto. Registra qué inspeccionaste, qué observaste y si coincidía con el estado declarado. Si no puedes demostrar que el espacio de trabajo coincide con la definición, marca el gate como BLOCKED hasta corregir el estado o cambiar explícitamente el alcance. Ejecutar un comando de limpieza por sí solo no es una verificación.

Usa este registro breve de verificación:

Definición del estado limpio:
Commit o tag de Git de origen:
Dependencias o entradas generadas permitidas:
Configuración y target requeridos:
Tratamiento de salidas previas, datos temporales y cachés:
Límite de secretos comprobado:

Comprobación 1:
Estado esperado:
Estado observado:
Resultado: PASS / FAIL / BLOCKED
Evidencia:

Comprobación 2:
Estado esperado:
Estado observado:
Resultado: PASS / FAIL / BLOCKED
Evidencia:

1243. Paso 3: Define la identidad del artefacto

Para cada fila requerida, registra:

• Nombre del artefacto.
• Commit o tag conocido de Git utilizado como revisión de origen. Este campo es obligatorio; si no hay un commit o tag conocido, la fila no puede recibir un PASS válido.
• Configuración y target.
• Ubicación de la salida o identificador del paquete.
• Checksum u otra identidad equivalente cuando tu herramienta lo proporcione.
• Fecha o etiqueta de ejecución que permita distinguir los resultados.

No sustituyas una identidad ausente por “último build”. El commit o tag registrado debe aparecer tanto en la identidad del artefacto como en la evidencia de ejecución. No incluyas valores secretos en el nombre del artefacto, los logs, la evidencia ni el prompt para la IA.

1244. Paso 4: Escribe los criterios de aceptación

Escribe entre tres y cinco criterios usando lenguaje observable. Incluye al menos:

• Comportamiento de inicio o carga.
• Punto de entrada o estado inicial previsto.
• Una acción representativa del jugador y su respuesta esperada.
• Una condición de fallo definida, como un error fatal, contenido ausente o input sin respuesta.

Cada criterio debe poder responderse con PASS, FAIL o BLOCKED. “Se ve bien” no es un resultado válido.

1245. Paso 5: Ejecuta el checklist

Parte del estado limpio declarado y verificado y utiliza únicamente las entradas listadas en el gate. Produce el artefacto, identifícalo y prueba cada criterio en orden. Registra el resultado y la evidencia inmediatamente. Incluye el commit o tag conocido de Git, el entorno, el registro de verificación del estado limpio y la identidad de la salida en la evidencia de ejecución. Si un paso no puede realizarse, marca BLOCKED; no lo marques como PASS porque el build se haya abierto.

Usa este registro de ejecución:

Nombre del gate:
Target/configuración/entorno:
Entradas declaradas:

Definición del estado limpio:
Evidencia de verificación del estado limpio:
Límite de secretos:

Commit o tag de Git de origen:
Identidad del artefacto:
Ubicación de la salida o identificador del paquete:
Checksum o etiqueta de ejecución, si está disponible:

Criterio 1:
Resultado: PASS / FAIL / BLOCKED
Evidencia:

Criterio 2:
Resultado: PASS / FAIL / BLOCKED
Evidencia:

Criterio 3:
Resultado: PASS / FAIL / BLOCKED
Evidencia:

Gate general: PASS / FAIL / BLOCKED
Preguntas abiertas o acciones de seguimiento:

Un PASS requiere un estado limpio verificado, un commit o tag conocido de Git, una identidad distinguible del artefacto, el entorno declarado, evidencia para cada criterio requerido y ningún incumplimiento del límite de secretos. Si falta cualquiera de esos elementos, usa FAIL o BLOCKED según corresponda a una condición fallida o a una condición no verificada.

1246. Paso 6: Toma una decisión

Elige una de estas situaciones, o usa una equivalente de tu ejecución:

• El build termina correctamente, pero un criterio no se probó.
• El artefacto inicia, pero no se puede distinguir de la salida anterior.
• El target funciona en un entorno, pero no se utilizó el entorno declarado.
• El artefacto se produjo, pero no se verificó el estado limpio del espacio de trabajo o el commit o tag de Git de origen.

Decide si el gate general es PASS, FAIL o BLOCKED. Escribe dos frases explicando por qué. La explicación debe referirse a la evidencia observada o ausente, no a la confianza ni a la intuición.

1247. Validación / evidencia

1248. Puntos clave

• M-A-C-E conecta la matriz, la identidad del artefacto, los criterios y la evidencia de un clean-build gate.
• La definición del estado limpio y su verificación son requisitos distintos.
• El éxito del build y la aceptación del gate son decisiones separadas.
• Un commit o tag conocido de Git, un entorno declarado, una salida distinguible y evidencia para cada criterio son necesarios para un PASS defendible.
• La IA puede redactar pasos del checklist e hipótesis de fallo, pero la persona que aprende debe verificar y corregir el registro del gate y no exponer secretos.

1249. Próxima lección

Continúa con 3.11, el destino canónico posterior a 3.10 — Pipeline de build, y lleva este registro de gate como evidencia de build para la siguiente parte del trabajo del hito.

1250. Comprobación