Objetivo del tema
Aplicar un proceso repetible para que los cambios de Bionic partan de evidencia, respeten un alcance aprobado, superen verificaciones relevantes y puedan auditarse o revertirse antes de incorporarlos al proyecto.
Definición de «terminado»: el agente no termina cuando escribe código, sino cuando explica qué cambió, presenta pruebas reproducibles y el usuario revisa el diff y los riesgos restantes.
14.1 El ciclo completo
1. Línea baseEstado, rama y pruebas antes del cambio.
2. InspeccionarArchivos, flujo, tests y restricciones.
3. PlanificarCambio mínimo y criterios de éxito.
4. CambiarEditar sólo lo autorizado.
5. ProbarChecks enfocados y luego cobertura amplia.
6. RevisarDiff, efectos secundarios y resultado final.
La guía oficial de Bionic recomienda inspeccionar y explicar primero, confirmar cambio y restricciones, editar, ejecutar pruebas enfocadas y revisar los diffs inline y de Git.
14.2 Preparar una línea base
Antes de atribuir un resultado al agente, necesitas saber cómo estaba el repositorio:
git status --short
git branch --show-current
git diff --stat
# Ejecutar la prueba o verificación relevante del proyecto
- Estado: identifica cambios sin confirmar y archivos nuevos.
- Rama: evita trabajar en una rama equivocada.
- Diff inicial: separa trabajo previo del nuevo cambio.
- Pruebas iniciales: detectan fallos que ya existían.
No limpies el repositorio para empezar: si existen cambios ajenos a la tarea, presérvalos. Documenta la situación y limita el trabajo; un reset o una eliminación pueden destruir trabajo no guardado.
14.3 Registrar fallos preexistentes
Si una prueba falla antes del cambio, guarda comando, nombre del caso y mensaje esencial. Decide si:
- El fallo está directamente relacionado y forma parte de la tarea.
- No está relacionado y el cambio puede verificarse de otra manera.
- Impide establecer una línea base confiable y debe resolverse primero.
No pidas al agente «hacer que todas las pruebas pasen» sin investigar: podría borrar casos, relajar aserciones o esconder el problema.
14.4 Fase de inspección: sólo lectura
La inspección debe reconstruir el comportamiento desde la entrada hasta el resultado y localizar las pruebas que lo protegen.
Inspecciona el problema sin modificar archivos, instalar paquetes ni ejecutar comandos que escriban datos.
Explica:
1. comportamiento actual y recorrido de llamadas;
2. archivos, símbolos y configuración implicados;
3. pruebas existentes y casos no cubiertos;
4. causa probable sustentada por código;
5. riesgos y dudas.
Incluye rutas y rangos de líneas. Detente antes de proponer una implementación definitiva.
Abre las referencias que devuelve Bionic. Verifica que la causa se desprenda del código y no sólo del nombre de una función.
14.5 Reproducir antes de reparar
Cuando sea posible, convierte el reporte en una reproducción determinista. Registra:
- Entrada exacta.
- Resultado esperado.
- Resultado observado.
- Versión, plataforma y configuración relevante.
- Comando mínimo que demuestra el fallo.
Una prueba que falla por la razón correcta es evidencia más fuerte que una explicación verbal. Sin embargo, no todas las fallas se reproducen localmente: concurrencia, red o datos reales pueden exigir instrumentación y una estrategia distinta.
14.6 Convertir el diagnóstico en un plan
Elementos de un plan revisable
| Elemento | Pregunta que debe responder |
|---|
| Causa | ¿Qué comportamiento concreto produce el problema? |
| Archivos | ¿Qué se editará y por qué es necesario? |
| Solución | ¿Cuál es el cambio mínimo que satisface el requisito? |
| Compatibilidad | ¿Qué API, formato o comportamiento debe conservarse? |
| Pruebas | ¿Qué caso falla antes y pasa después? |
| Riesgos | ¿Qué podría romperse y cómo se comprobará? |
Si el plan introduce una migración, cambia una API pública, agrega dependencias o modifica más archivos de los esperados, detén la implementación y revisa esa decisión.
14.7 Criterios de aceptación
Los criterios deben ser observables. Incluye casos positivos, negativos y de compatibilidad:
Criterios de aceptación:
- La entrada válida conserva el resultado actual.
- Una entrada vacía devuelve undefined sin lanzar una excepción.
- Las comparaciones ignoran espacios exteriores y mayúsculas.
- No se modifican los objetos recibidos.
- No cambia la firma exportada.
- No se agregan dependencias.
- Pasan la prueba enfocada y la suite completa.
14.8 Autorizar una implementación acotada
Después de aprobar el plan, formula una orden que cierre las decisiones pendientes:
Implementa el plan aprobado.
Limita los cambios a los archivos enumerados. Agrega primero la prueba de regresión, confirma que demuestra el fallo y aplica después el cambio mínimo. No actualices dependencias, no reformatees archivos no relacionados y no crees commits.
Ejecuta las verificaciones acordadas. Si necesitas ampliar el alcance o una prueba existente contradice el requisito, detente y explícalo.
Indicar cuándo detenerse evita que el agente resuelva una dificultad mediante una decisión de producto o arquitectura que no fue autorizada.
14.9 Mantener pequeño el cambio
Un diff pequeño no es automáticamente correcto, pero suele ser más fácil de entender, probar y revertir. Evita mezclar:
- La corrección con un reformateo completo.
- Una funcionalidad con actualizaciones masivas de dependencias.
- Cambios de comportamiento con renombres cosméticos.
- Código generado con ediciones manuales no relacionadas.
Si una refactorización es necesaria para el arreglo, pide que se justifique y que su comportamiento se proteja con pruebas.
14.10 Estrategia de pruebas por capas
Prueba de regresiónDemuestra el caso exacto que motivó el cambio.
Pruebas enfocadasEjecutan el archivo, paquete o componente afectado.
Suite relacionadaDetecta consecuencias en consumidores cercanos.
Análisis estáticoTipos, linter y reglas del proyecto.
CompilaciónComprueba integración, empaquetado y generación.
Validación manualConfirma flujos que la automatización no cubre.
Empieza por la prueba más rápida y específica para obtener retroalimentación clara. Amplía después según riesgo y costo. No todos los proyectos requieren todas las capas en cada cambio.
14.11 Interpretar una prueba que pasa
Un código de salida exitoso sólo prueba lo que el comando realmente ejecutó. Comprueba:
- Que se descubrieron los casos esperados.
- Que no quedaron pruebas omitidas o marcadas como pendientes.
- Que el comando usó la configuración correcta.
- Que las aserciones prueban comportamiento y no sólo ausencia de errores.
- Que la prueba nueva falla al retirar temporalmente la corrección, cuando resulte razonable verificarlo.
14.12 Cuando una prueba falla después del cambio
No encadenes correcciones al azar. Clasifica el fallo:
Interpretación de fallos
| Tipo | Acción |
|---|
| La prueba nueva falla como se esperaba antes del arreglo. | Confirma que el mensaje demuestra el defecto y continúa con la implementación. |
| Una prueba relacionada revela una incompatibilidad. | Revisa el requisito y ajusta el plan, no la ocultes. |
| Falla por entorno o dependencia ausente. | Documenta el bloqueo; no cambies código de producción para enmascararlo. |
| Falla una prueba no relacionada que ya fallaba. | Compárala con la línea base y repórtala por separado. |
| El agente debilitó o eliminó la prueba. | Rechaza el cambio salvo que el requisito modifique explícitamente el comportamiento esperado. |
14.13 Revisar el diff inline
Bionic muestra diffs inline para facilitar la inspección durante el trabajo. Lee cada bloque y pregunta:
- ¿La línea cambiada participa en el requisito?
- ¿Se eliminó una validación, manejo de error o comentario importante?
- ¿La prueba comprueba el resultado o repite la implementación?
- ¿Aparecen credenciales, registros sensibles o rutas locales?
- ¿Hay cambios de formato que esconden la modificación real?
No revises sólo las líneas verdes. Las eliminaciones suelen contener la parte más importante del cambio.
14.14 Revisar con Git
El diff de Bionic ayuda a seguir la sesión; Git ofrece una verificación independiente del estado real del directorio:
git status --short
git diff --stat
git diff --check
git diff
git diff --staged
status revela archivos nuevos, modificados o eliminados.diff --stat muestra el tamaño y distribución del cambio.diff --check detecta algunos errores de espacios.diff muestra cambios no preparados.diff --staged muestra lo que entraría en un commit.
Archivos nuevos: un archivo sin seguimiento puede aparecer en status pero no en git diff hasta que se prepare. Ábrelo y revísalo expresamente.
14.15 Revisar dependencias y artefactos
Si cambian un manifiesto o un lockfile, identifica el motivo y las dependencias transitivas. Una instalación aparentemente pequeña puede modificar cientos de entradas.
- Confirma nombre, versión, licencia y procedencia de la dependencia.
- Comprueba si era posible usar una utilidad existente.
- Separa cachés, compilados y archivos temporales del código versionado.
- Revisa migraciones, esquemas y archivos generados con sus herramientas oficiales.
14.16 Verificaciones no funcionales
Además de «funciona», evalúa propiedades que las pruebas unitarias pueden omitir:
Preguntas adicionales según el riesgo
| Área | Pregunta |
|---|
| Seguridad | ¿Cambia autenticación, autorización, validación o exposición de datos? |
| Rendimiento | ¿Agrega consultas, recorridos o cargas en una ruta frecuente? |
| Concurrencia | ¿Comparte estado o introduce condiciones de carrera? |
| Compatibilidad | ¿Modifica una API, formato, esquema o versión mínima? |
| Observabilidad | ¿Los errores se registran sin filtrar secretos y pueden diagnosticarse? |
| Accesibilidad | ¿El cambio de interfaz sigue siendo utilizable con teclado y lectores? |
14.17 Checkpoints y recuperación
Bionic crea checkpoints automáticos que permiten revisar o retroceder cambios no deseados. Son útiles para iterar, pero no sustituyen una rama, commits conocidos ni una copia de seguridad.
Antes de regresar a un checkpoint:
- Revisa qué archivos y mensajes quedarán afectados.
- Identifica cambios propios o externos que aparecieron después.
- Conserva por separado cualquier trabajo que no deba perderse.
- Comprueba el estado real con Git después de restaurar.
Para comparar dos soluciones alternativas sin sobrescribir la primera, utiliza Fork desde una respuesta elegible.
14.18 Informe final del agente
Pide un cierre breve y comprobable:
Antes de terminar, informa:
- causa confirmada;
- archivos modificados y propósito de cada cambio;
- comandos ejecutados y resultado exacto;
- pruebas agregadas;
- criterios de aceptación verificados;
- verificaciones no ejecutadas y motivo;
- riesgos o trabajo pendiente.
No afirmes que algo fue probado si no se ejecutó el comando correspondiente.
14.19 Práctica: endurecer la búsqueda del inventario
Continúa con inventario-demo del tema 13. Si completaste aquel ejercicio, la función ya ignora espacios y mayúsculas. Inicializa Git y crea una línea base sólo si la carpeta aún no es un repositorio:
git init
git add package.json src/catalogo.js test/catalogo.test.js
git commit -m "chore: linea base del inventario"
npm test
Si el commit falla porque Git no conoce tu identidad, configura tu nombre y correo reales según la política de tu equipo; no permitas que el agente invente esos datos.
Antes de copiar comandos: confirma que estás dentro de inventario-demo y que esos tres archivos son los correctos. No crees un commit que incluya otros cambios tuyos.
Etapa 1: inspección y plan
Inspecciona buscarPorCodigo y sus pruebas. No modifiques archivos.
Nuevo requisito: null, undefined, números y cadenas compuestas sólo por espacios deben devolver undefined sin lanzar una excepción. Los casos válidos deben conservar el comportamiento actual y la lista de productos no debe mutarse.
Propón el cambio mínimo, los casos de prueba exactos y los comandos de verificación. Informa el estado y la rama de Git. Detente para revisión.
Rechaza cualquier plan que convierta arbitrariamente números a texto, cambie los datos almacenados o agregue una dependencia.
Etapa 2: implementación y pruebas
Apruebo el plan con estas condiciones: edita sólo src/catalogo.js y test/catalogo.test.js; agrega pruebas para null, undefined, 123 y " "; no cambies exports ni dependencias.
Ejecuta npm test y git diff --check. Si un comando falla, investiga la causa sin debilitar pruebas. No crees commits.
Etapa 3: revisión independiente
- Abre todos los bloques del diff inline y revisa adiciones y eliminaciones.
- Ejecuta
git status --short y confirma que sólo cambiaron dos archivos.
- Ejecuta
git diff --stat, git diff --check y git diff.
- Ejecuta
npm test manualmente y comprueba que se descubren todos los casos.
- Verifica que la función no modifique el arreglo ni los objetos recibidos.
Resultado esperado: las cuatro entradas inválidas devuelven undefined, las búsquedas válidas siguen funcionando, no hay dependencias ni archivos inesperados y Git muestra cambios sólo en implementación y pruebas.
14.20 Lista de control antes de conservar
- La causa fue comprobada en el código o mediante reproducción.
- El plan y sus decisiones relevantes fueron aprobados.
- El diff coincide con el alcance.
- Los archivos nuevos y eliminados se revisaron expresamente.
- Las pruebas adecuadas se ejecutaron y su salida fue entendida.
- No se debilitaron pruebas ni validaciones para obtener verde.
- Dependencias, lockfiles y artefactos tienen una justificación.
- No se introdujeron secretos ni datos sensibles.
- Se documentaron riesgos y verificaciones pendientes.
14.21 Diagnóstico de problemas
Problemas frecuentes del flujo
| Problema | Respuesta recomendada |
|---|
| El agente edita durante la inspección. | Detén la tarea, revisa el diff y repite con prohibición explícita de modificar. |
| El plan no identifica una causa. | Pide evidencia adicional o una reproducción antes de autorizar. |
| Las pruebas ya fallaban. | Compara con la línea base y separa fallos relacionados de preexistentes. |
| El diff contiene reformateo masivo. | Revierte esa parte y aplica un cambio enfocado. |
| La prueba pasa demasiado fácil. | Comprueba descubrimiento, aserciones y que falle sin la corrección. |
| Git no muestra un archivo nuevo. | Consulta git status y abre el archivo; los no seguidos no aparecen en el diff normal. |
| La restauración afectaría trabajo propio. | No retrocedas hasta separar o respaldar esos cambios. |
14.22 Resumen
- La línea base separa problemas previos de efectos del cambio.
- Inspeccionar significa reunir evidencia antes de escribir.
- El plan debe enumerar causa, archivos, compatibilidad, pruebas y riesgos.
- Los criterios de aceptación convierten una intención en condiciones verificables.
- Las pruebas se ejecutan desde lo enfocado hacia lo amplio según el riesgo.
- Un resultado verde debe interpretarse, no sólo observarse.
- El diff inline y Git ofrecen revisiones complementarias.
- Los checkpoints ayudan a iterar, pero no reemplazan el control de versiones.
En el próximo tema profundizaremos Git, tareas paralelas, subagentes y flujos avanzados de desarrollo.
Fuentes oficiales consultadas: flujo de código inspect-change-test, revisión de diffs y comandos, búsqueda agéntica y diffs inline, checkpoints en flujos de trabajo, análisis de seguridad de comandos y cambios recientes de Git, revisión y permisos.