Los controles que comparte todo proyecto con agentes de IA, nuevo o de migración, para preparar el entorno, limitar lo que puede hacer el agente, verificar cada cambio y conservar la evidencia.
Esta es la base común. Aplica igual cuando construyes software nuevo que cuando modernizas un sistema existente.
Antes de delegar trabajo, la plantilla y los acuerdos del proyecto dejan por escrito las reglas que el agente no debe inventar.
Lo que el sistema debe cumplir además de sus funciones: prácticas de OWASP, autenticación, autorización y cifrado; objetivos de servicio (SLO), tiempos de respuesta y límites de recursos; capas, límites entre dominios y registros de decisiones de arquitectura (ADR); logs estructurados, trazas y métricas.
La estructura, los límites, los patrones y las decisiones de arquitectura que afectan el cambio.
Resultados que se puedan observar y pruebas esperadas. Si algo es ambiguo, se resuelve con el equipo responsable antes de empezar.
Imagen base, dependencias y servicios con versión; estructura de módulos y contratos; lint, análisis estático de seguridad (SAST), estructura inicial de pruebas y CI base; políticas del proyecto, prompts de cada rol y scripts de verificación.
Cada tarea corre en un entorno que tu equipo puede crear, revisar y verificar siempre de la misma forma.
Devcontainer o Compose con la imagen base y los servicios dependientes fijados, y comandos conocidos como make test y make lint. El entorno sale de la plantilla aprobada.
Evidencia o salida: Configuración versionada y pasos que cualquiera puede repetir para crear el espacio de trabajo.
Una rama o worktree por tarea, datos de prueba separados y redes internas sin salida libre a internet. Nada de secretos de producción; sólo los permisos que la tarea necesita.
Evidencia o salida: Repositorio, red, herramientas, datos y permisos acotados.
Pruebas unitarias, de integración, de contratos y análisis, dentro del mismo entorno donde se implementó. Los datos de prueba van separados y cada punto de la definición de terminado (DoD) se convierte en un comando repetible.
Evidencia o salida: Comandos y resultados reproducibles ligados al cambio. Pasar las pruebas en este entorno es la condición para cerrar.
Todo proyecto con agentes trabaja bajo estas capas. Tu equipo las configura antes de delegar trabajo, y cubren herramientas, prompts, repositorios y credenciales.
Un punto único por el que pasan todas las peticiones y prompts hacia proveedores de IA y agentes de codificación (Cursor, Claude Code, etc.).
Evita que archivos .env, claves o tokens entren al espacio de trabajo o al historial de Git.
.env.example, sin valores reales.Sólo en desarrollo, QA y pruebas. Producción nunca se configura a través del agente.
El agente no recibe credenciales de producción ni libera cambios por su cuenta.
Cuando quien hace el cambio no es quien lo revisa, los errores aparecen antes y el resultado no depende de una sola respuesta del agente.
Define alcance, arquitectura, criterios de aceptación y límites, y resuelve las decisiones que no estén documentadas.
Entrega: Solicitud y criterios aprobados.
Divide el trabajo, prepara el contexto, fija los intentos y pide evidencia para cada criterio.
Entrega: Un plan de tarea acotado que se puede verificar.
Modifica el código dentro del entorno y los permisos aprobados, corre las pruebas que correspondan y avisa lo que no pudo validar.
Entrega: El cambio y sus resultados de pruebas.
Revisa el cambio contra la solicitud, los criterios, la arquitectura y las pruebas, sin dar por hecho que el relato de quien lo construyó demuestra que está bien.
Entrega: Hallazgos que se pueden reproducir y un veredicto de cumplimiento.
Resuelve los hallazgos, acepta excepciones y autoriza las decisiones de riesgo, la integración y la liberación.
Entrega: La decisión registrada, con una persona responsable.
Estos controles son iguales para un cambio escrito por una persona o por un agente. En una migración, la solicitud de cambios (pull request o PR) suma además la evidencia del inventario y de la paridad.
Corre Gitleaks, lint, una prueba rápida y las políticas del repositorio. Si hay un hallazgo crítico, se bloquean los secretos, el estilo inválido y los cambios a requerimientos protegidos.
Evidencia o salida: El resultado reproducible de las verificaciones locales.
Corre los escaneos remotos y la DLP cuando aplique. Se revisan la rama, el tamaño del cambio, las dependencias nuevas y la exposición de datos, con las mismas reglas para el agente y para las personas.
Evidencia o salida: Escaneos y verificaciones del flujo de integración.
El Auditor revisa en un contexto limpio, junto con los escáneres de seguridad y privacidad y las pruebas de la CI. Se revisan la definición de terminado, la arquitectura, los patrones y los resultados, y se adjuntan el rastro del trabajo y la evidencia.
Evidencia o salida: Un PR revisado, con sus hallazgos atendidos.
Sólo se integra con todas las verificaciones aprobadas, en una rama protegida y sin saltarse reglas. Siempre hay una forma documentada de revertir, y el agente pasa por las mismas puertas que las personas.
Evidencia o salida: Verificaciones aprobadas y el cambio integrado en la rama protegida.
Una persona aprueba los cambios en autenticación, datos, pagos e infraestructura según su riesgo, y autoriza la liberación cuando corresponde.
Evidencia o salida: Aprobación humana registrada para los cambios críticos.
Nueve hábitos que sirven en cualquier proyecto con agentes, nuevo o de migración. En cada uno te contamos qué hacer, por qué importa y cómo llevarlo al día a día.
Por qué importa: Los modelos son optimistas y pueden reportar éxito aunque el código no compile o las pruebas fallen.
Cómo hacerlo: El Orquestador planea, el Implementador construye y el Auditor revisa en un contexto nuevo, sin ver el razonamiento del Implementador. La referencia es la especificación, no el relato de quien construyó.
Por qué importa: Un “creo que está bien” del agente es la señal menos confiable. Un comando que pasa o falla es evidencia real.
Cómo hacerlo: El Orquestador sólo cierra la tarea si esos comandos salen en verde. Si el agente dice “terminé” pero make test falla, la tarea sigue abierta.
Por qué importa: Si se equivoca, o si un prompt malicioso lo desvía, el daño queda acotado. Menos permisos, menos alcance de un error.
Cómo hacerlo: Una lista de comandos permitidos y ninguna credencial de producción. Una persona aprueba las acciones que no se pueden deshacer, como borrar tablas, cambiar la configuración de DNS o integrar en la rama principal en zonas críticas.
Por qué importa: En una corrida larga, el agente “olvida” lo que se acordó al inicio. Un archivo no se olvida.
Cómo hacerlo: Escribe un PLAN.md con el objetivo, los criterios de aceptación y el estado. Guarda logs de pruebas y hallazgos en evidence/. Cada subagente vuelve a leer esos archivos.
Por qué importa: Si dos agentes o dos corridas tocan los mismos archivos a la vez, se pierde el control de los cambios y de cómo revertirlos.
Cómo hacerlo: Una tarea, una rama (por ejemplo agent/feat-login-validation). Al terminar sale un PR limpio; si algo falla, se descarta la rama sin afectar la principal.
Por qué importa: Si se baja la exigencia sólo para la IA, termina integrándose código que a una persona le habrían rechazado.
Cómo hacerlo: Las mismas reglas de protección de ramas para todos: pruebas, lint, seguridad y revisores. El agente no se salta reglas ni fuerza integraciones.
Por qué importa: Cuando algo falla en QA o en una auditoría y alguien pregunta “¿quién cambió esto y por qué?”, tienes que responder con hechos, no con “el chat dijo que estaba bien”.
Cómo hacerlo: Adjunta ese rastro al PR o a un registro de corridas, con el enlace al plan y a la evidencia de pruebas.
Por qué importa: Si divides mal el trabajo (por ejemplo, dos agentes tocan el mismo servicio de autenticación), cada uno puede “arreglar” su parte, pero al juntarlas el resultado queda roto o inconsistente. Los errores se suman en lugar de detectarse.
Cómo hacerlo: El Orquestador sólo paraleliza cuando una parte no necesita el resultado de la otra. Si hay dependencia, como una API y el cliente que la usa, o un cambio de esquema y el código que lo consume, van en orden: primero una y luego la otra.
Por qué importa: Un error en un botón es una molestia; un error en autenticación, datos personales o infraestructura puede ser un incidente grave.
Cómo hacerlo: El agente prepara el PR, corre la CI y deja la evidencia. Una persona revisa y aprueba la integración cuando el cambio toca autenticación, datos sensibles, pagos, infraestructura o secretos. Los cambios de bajo riesgo siguen el flujo normal de revisión de tu equipo.
Antes de empezar una tarea con agentes, revisa con tu equipo que estas condiciones estén claras.
Hay una persona que puede resolver dudas y aprobar el resultado.
La tarea se puede desarrollar y probar de forma reproducible.
El agente sólo usa herramientas aprobadas y no recibe secretos de producción.
Tu equipo puede saber de forma objetiva si el cambio cumple.
Se sabe qué controles, qué revisores y qué autorizaciones hacen falta.
Las herramientas, los datos permitidos y los permisos corresponden a lo que de verdad está configurado y a la política del cliente.
Gitleaks o equivalente corre en el pre-commit y en la CI, y ningún archivo versionado tiene credenciales reales.
Cada corrida conserva su plan y sus resultados fuera de la conversación con el agente, listos para revisarse.
Cuéntanos qué sistema o iniciativa quieres revisar y qué resultado necesitas conseguir.