Checklist de incorporación para código heredado de IA en agencias

Por qué las agencias necesitan un intake distinto para código heredado de IA

Muchos proyectos generados por IA lucen bien en una demo. La ruta feliz funciona, la interfaz parece pulida y nadie nota las lagunas hasta que llegan usuarios reales. Entonces la app empieza a fallar de maneras que parecen aleatorias: los inicios de sesión entran en bucle, los pagos caducan y los datos acaban en el lugar equivocado.

Esa discrepancia es predecible. Muchos prototipos generados por IA se construyen para parecer completos antes de ser seguros o fiables. Las herramientas de IA pueden ensamblar pantallas rápido, pero a menudo se saltan el trabajo aburrido que mantiene el software funcionando en producción.

Los puntos de fallo tienden a repetirse entre proyectos: la autenticación está a medio hacer o parcheada, secretos viven en el repo o en el entorno equivocado, el modelo de datos cambia semana a semana y el despliegue depende de pasos manuales que solo recuerda una persona. Si haces el intake como una construcción normal (listas de deseos, preferencias de diseño, plazos), te pierdes esos riesgos y heredas sorpresas.

Un buen intake para código heredado de IA se centra menos en “¿qué quieres añadir?” y más en “¿qué podría romper la próxima semana?” Obtén respuestas claras sobre:

• Dónde se atascan los usuarios reales hoy (no lo que está en la hoja de ruta)
• Quién controla el repo, el hosting y las cuentas de terceros
• Qué datos se almacenan y qué debe protegerse
• Qué debe funcionar para que el negocio opere (login, checkout, emails)
• Qué ya se ha “arreglado”, y por quién

Si aspiras a una ventana corta de estabilización (a menudo 48-72 horas), el primer trabajo es parar la hemorragia: hacer la app fiable, cerrar huecos de seguridad obvios y lograr un despliegue repetible. Las mejoras vienen después de que lo básico se mantenga.

Un escenario común: un fundador dice “básicamente está hecho” porque el signup demo funciona. Tu intake debe confirmar qué pasa cuando 50 usuarios se registran, se restablecen contraseñas y la app despliega desde cero.

Fija el objetivo: estabilizar primero, mejorar después

Cuando heredas código generado por IA, la forma más rápida de perder confianza es prometer nuevas funciones antes de que lo básico funcione. Establece un primer objetivo claro: estabilización. Eso da a todos una definición compartida de “hecho” para las primeras 48-72 horas y hace tu estimación defendible.

Define “estabilizado” en términos llanos que el cliente pueda probar. Para la mayoría de las apps, significa:

• El login y el signup funcionan de punta a punta (incluido el restablecimiento de contraseña, si se usa)
• El flujo principal de usuario se completa sin caídas ni errores confusos
• La app se despliega de la misma manera cada vez (sin pasos misteriosos)
• Los datos no están obviamente en riesgo (no hay keys expuestas, ni acceso admin abierto)

Luego traza una línea clara entre estabilización, reconstrucción y nuevas funciones.

• La estabilización para la hemorragia.
• Una reconstrucción reemplaza cimientos frágiles.
• Las nuevas funciones esperan hasta que el producto sea fiable.

Pon ese lenguaje en tu intake para que todo el equipo (y el cliente) use las mismas definiciones.

Establece guardarraíles temprano: cronograma, límites de presupuesto y quién toma la decisión final cuando haya trade-offs como “arreglar rápido” vs “reescribir limpio”. Nombra un aprobador y un suplente, y acordad tiempos de respuesta para no quedar bloqueados durante la ventana de estabilización.

Finalmente, elige un único lugar para decisiones y requisitos. Puede ser un doc corto o un tablero de tickets, pero debe responder tres preguntas: qué se supone que hace la app hoy, qué cuenta como defecto y qué queda fuera de alcance hasta después de la estabilización.

Preguntas rápidas de triaje del proyecto (10 minutos)

Una llamada de triaje rápida previene sorpresas. El objetivo no es entender cada detalle. Es saber qué estás heredando, qué está roto ahora mismo y si una ventana de estabilización de 48-72 horas es realista.

Usa estas preguntas para obtener lo básico rápido:

• ¿Quién lo construyó (persona o proveedor), y qué herramienta de IA se usó (Lovable, Bolt, v0, Cursor, Replit, etc.)? ¿Qué cambió desde la última vez que "funcionó"?
• ¿Dónde corre hoy: solo en el portátil de alguien, en un sitio de staging, en producción o en ningún lado? ¿Quién puede acceder?
• ¿Quién lo está usando ahora (si alguien), y cuáles son los 1-2 flujos principales que deben funcionar (registro, checkout, reserva, ediciones admin)?
• ¿Qué está fallando ahora mismo, en palabras sencillas? Pide un ejemplo reciente que encontró un usuario (mensaje de error, página en blanco, dato equivocado).
• ¿Hay fechas límite ligadas a una demo de ventas, piloto, hito de financiación o revisión de cumplimiento? ¿Qué pasa si se retrasa una semana?

Escucha contradicciones. Si dicen “funcionó la semana pasada” pero también “nadie puede iniciar sesión”, ya tienes una prioridad: autenticación y acceso.

Ejemplo: un cliente necesita una demo el viernes, la app solo corre localmente y el último dev la “arregló” pegando secretos en el frontend. Eso no es un sprint de funciones. Es un trabajo corto de estabilización: conseguir build desplegable, asegurar los secretos y hacer fiable la ruta de demo.

Acceso y propiedad: consigue control antes de tocar código

Antes de abrir un repo o prometer un cronograma, asegúrate de que el cliente pueda otorgar control. Con código heredado de IA, el desorden a menudo no es solo el código. Son cuentas, tokens y despliegues a medio terminar que nadie posee.

Empieza con una pregunta directa: ¿dónde vive el código ahora mismo? Si la respuesta es “en el portátil de alguien” o “en una herramienta como Replit” sin dueño claro, trátalo como un riesgo real. Acceso primero, trabajo después.

Acceso mínimo que necesitas

Pide estos elementos desde el principio para poder trabajar de forma segura y evitar sorpresas más adelante:

• Ubicación del repo y un admin real (GitHub, GitLab u otro host)
• Acceso de despliegue (quién puede pushear a producción, si existe producción)
• Lista de entornos (dev, staging, prod) y si algo se comparte
• Método de almacenamiento de secretos (archivos env, variables de dashboard, secret manager) y quién puede rotar secretos
• Propiedad del dominio y del correo (quién controla DNS y ajustes de email transaccional)

Si el cliente no puede proporcionar al menos un admin y un lugar seguro para guardar secretos, pausa. Tocar código sin propiedad es como acabar con logins rotos, datos perdidos o una caída en producción.

Expectativas sobre secretos y despliegues

Los prototipos generados por IA a menudo tienen claves expuestas o contraseñas hardcodeadas. Incluso si la app “funciona”, asume que los secretos necesitan rotación.

Confirma quién puede cambiar:

• Contraseñas de la base de datos y llaves de API
• Ajustes del proveedor de auth (apps OAuth, secretos JWT)
• Variables de hosting y settings de build

Ejemplo: heredas un prototipo de Bolt que despliega desde una cuenta personal, con la contraseña de la base de datos pegada en el código. La acción correcta es transferir el repo, mover el despliegue a un workspace de la agencia y rotar secretos antes de cualquier trabajo de funcionalidad.

Flujos críticos para el negocio a confirmar (y qué preguntar)

Para evitar sorpresas, acordad los pocos flujos que deben funcionar sí o sí. Esto evita que arregles lo equivocado primero.

Empieza por identidad y permisos. “Login funciona” no es suficiente. Pregunta quién debe poder hacer qué y dónde se aplica esa regla. Si los permisos solo están ocultos en la UI, un usuario puede a veces saltárselos adivinando un ID o llamando a un endpoint directamente.

Pagos y facturación también necesitan una historia clara para fallos. Muchos prototipos solo manejan la ruta feliz. Confirma qué debe pasar cuando una tarjeta falla, una suscripción se cancela o se necesita un reembolso, y quién ejecuta esas acciones.

Define la sensibilidad de datos desde el día uno. Si la app maneja datos personales, de salud, financieros o sobre menores, tus elecciones de seguridad y logging cambian.

Mantén las preguntas prácticas:

• Auth: ¿Qué roles existen (usuario, admin, staff) y qué puede hacer cada rol?
• Pagos: ¿Qué cuenta como “pagado” y qué cambia cuando el pago falla o se reembolsa?
• Datos: ¿Qué campos son sensibles y debería eliminarse algún dato a petición?
• Integraciones: ¿Qué se conecta a email, CRM, almacenamiento, APIs de IA o webhooks, y qué se rompe si se cae?
• Acceso admin: ¿Existe algún panel admin “temporal”, contraseña compartida o puerta trasera en uso?

Ejemplo: un fundador dice “solo los admins pueden exportar datos de clientes”. En código heredado, esa regla a veces es solo un botón, no una comprobación de permiso.

Señales de riesgo que puedes detectar en la primera llamada

Algunos problemas aparecen antes de que veas el repo. Una buena primera llamada se trata menos de detalles y más de señales: ¿puede este código correr en algún lado, está el acceso limpio y puedes confiar en lo que te cuentan?

Atento a estas banderas rojas:

• Solo corre en el portátil de una persona, o dicen “ya no podemos desplegar”. Eso suele significar setup de env faltante, pasos de build rotos o servicios sin documentar.
• Los secretos se manejan de forma casual: claves de API pegadas en chat, tokens en un doc compartido o “usa esta contraseña admin”. Asume exposición hasta demostrar lo contrario.
• Auth inconsistente: “el login a veces funciona”, roles que no funcionan o un usuario puede ver los datos de otro.
• Los bugs parecen aleatorios y desaparecen al refrescar. Eso puede apuntar a estado frágil, problemas de caching o expectativas desajustadas entre frontend y backend.
• No hay tests, no hay logs y nadie sabe qué cambió último. Sin rastro de auditoría, cada arreglo es conjetura.

Cuando oigas una o más de estas, usa seguimientos calmados para convertir dolores vagos en alcance claro:

• “¿Dónde corre hoy y quién puede reiniciarlo si se rompe?”
• “¿Cómo se almacenan los secretos y quién tiene acceso ahora mismo?”
• “¿Qué acciones de usuario deben funcionar siempre para que el negocio funcione?”
• “¿Cuándo funcionó por última vez y qué pasó justo antes de que dejara de hacerlo?”

Ejemplo: la app se construyó en Replit, el despliegue falló la semana pasada y están compartiendo una key de Stripe en Slack. Eso basta para pausar peticiones de funciones y cambiar a un intake centrado en estabilización: control, seguridad y despliegue repetible.

Qué revisar una vez veas el repo (alto nivel, no técnico)

Una vez tengas acceso, no necesitas leer cada archivo para saber si el proyecto es seguro para estabilizar. Un escaneo rápido te dice si es un rescate pequeño o una reconstrucción más profunda.

Empieza por la capa de datos, porque las sorpresas ahí se propagan por todas partes. Busca conceptos duplicados (por ejemplo users y app_users), campos de “fuente de la verdad” poco claros y migraciones faltantes. Si el repo no puede explicar cómo cambia la base de datos con el tiempo, los releases se vuelven arriesgados rápido.

Luego haz una revisión básica de seguridad, aunque no seas un experto. Comprueba si la entrada de usuario se maneja con cuidado, si las subidas de archivos están restringidas y si algo parece aceptar SQL crudo o comandos no confiables. Busca secretos en el repo (llaves de API, contraseñas de BD). Si los ves, asume que se han filtrado.

Mira también la estructura. Los prototipos creados por IA suelen copiar la misma lógica en muchos sitios. Eso hace que los arreglos sean lentos y los bugs fáciles de reintroducir.

Un conjunto corto de comprobaciones que suele sacar a la luz los mayores riesgos:

• ¿Hay una separación clara backend vs frontend, o está todo mezclado?
• ¿Ves la misma lógica repetida en varios archivos?
• ¿La auth y permisos se gestionan en un lugar o están dispersos?
• ¿Hay reporting de errores, o falla de forma silenciosa?
• ¿Existen cosas básicas como backups, configs de entorno y una ruta de despliegue simple?

Finalmente, detecta trampas de rendimiento temprano. Si las páginas dependen de muchas llamadas API repetidas, o la app pide los mismos datos una y otra vez, verás cargas lentas y timeouts cuando lleguen usuarios reales.

Un plan simple de estabilización de 48-72 horas (paso a paso)

Una ventana de estabilización no es un sprint de funciones. El objetivo es hacer que la app funcione de forma fiable, parar la hemorragia y dar a todos una visión clara de lo que hará falta para mejorar después.

El plan de 5 pasos

1. Consigue acceso, ejecútalo y reproduce las peores fallas. Recopila acceso al repo, credenciales de hosting y variables de entorno. Luego ejecuta la app como lo hacen los usuarios. Elige las 3 fallas principales y repróductelas con notas claras.

2. Congela el alcance y define “hecho” para la estabilización. Acordad que las nuevas funciones esperan. “Hecho” debe ser específico: iniciar sesión funciona, el flujo principal se completa y el despliegue no depende de hacks manuales.

3. Arregla los bloqueadores primero. Prioriza lo que detiene a los usuarios o crea peligro inmediato: auth rota, secretos expuestos, páginas que se caen, builds que fallan y despliegues que solo funcionan en una máquina.

4. Añade salvaguardas básicas para que se mantenga estable. Añade logging simple, mensajes de error claros y algunas comprobaciones smoke que detecten la misma rotura otra vez.

5. Entrega un informe corto y la decisión siguiente. Resume lo que se arregló, qué sigue siendo riesgoso y qué recomiendas (refactorizar, endurecer seguridad o reconstruir).

Errores comunes en el intake que provocan explosiones después

La forma más rápida de que un proyecto heredado por IA se vaya al traste es tratarlo como una construcción normal. Un cliente puede pedir nuevas funciones el primer día, pero si la base es frágil, cada “cambio pequeño” puede romper tres cosas más.

Errores comunes:

• Prometer fechas de entrega antes de haber realizado una ventana de estabilización
• Esperar días por acceso (repo, hosting, BD) y luego tomar decisiones a la carrera
• Definir éxito como “sin bugs” en lugar de una pequeña lista de flujos de negocio
• Arreglar cuestiones superficiales sin rotar secretos expuestos
• Lanzar cambios en producción sin un plan de rollback

Ejemplo: un cliente pide “una opción de pago más” en un prototipo. La añades, los pagos funcionan, pero una key filtrada provoca fraude y la agencia recibe la culpa. Un intake sólido incluye un reset de seguridad (rotar llaves, revisar auth) y un plan de rollback antes del trabajo de funciones.

Checklist de intake para copiar y pegar (comprobaciones rápidas)

Usa esto cuando necesites confirmar lo básico rápido y evitar sorpresas más adelante. Está pensado para una llamada de traspaso de 10-15 minutos más un seguimiento corto.

[ ] Access confirmed: repo + hosting + database + domain/DNS (who has admin?)
[ ] Third-party accounts listed: auth/email/payments/storage/analytics (who owns each?)
[ ] Security baseline: where secrets live today, how they will be rotated, and what data is sensitive
[ ] User roles: who can do what (admin, staff, customer) and which role is highest risk
[ ] Top 3 broken flows written down with a "done" definition for each
[ ] Deploy plan: how releases happen today and who can press the button
[ ] Observability: logs exist, error tracking is on, and someone will watch it after release
[ ] Backups: database backup status + restore test (or date of last known good backup)
[ ] 48-72 hour stabilization: what’s included (fix critical breakages, stop data leaks) vs excluded (new features, redesign)
[ ] Sign-off: one decision-maker for tradeoffs, plus a fallback if they are unavailable

Una forma simple de fijar expectativas: estabilizar significa que la app deja de fallar en los puntos más importantes y se cierran agujeros de seguridad obvios. No significa que el código esté bonito, rápido o listo para escalar.

Ejemplo: si un cliente dice “el checkout está roto”, delimítalo a un flujo comprobable (página de producto a pago exitoso) y un responsable de la cuenta de pagos. Sin eso, puedes arreglar el código y seguir bloqueado por falta de acceso.

Escenario de ejemplo: de prototipo heredado a release estable

Un cliente llega con un prototipo de Bolt que usó para generar interés. La app luce bien en demos, pero los usuarios reales no pueden iniciar sesión. A veces el botón de login gira eternamente, otras crea cuentas sin guardarlas.

En la primera llamada, usa un intake centrado en estabilización. Mantén el tono neutral: no estás juzgando el build, estás averiguando qué hace falta para hacerlo fiable.

En la práctica, eso suele significar:

• Confirmar uno o dos flujos que deben funcionar esta semana.
• Conseguir acceso mientras todos están en la llamada: repo, hosting, base de datos, dominio y servicios terceros.
• Confirmar dónde viven los secretos y quién posee las cuentas.
• Anotar banderas de riesgo como múltiples proveedores de auth a medio cablear, keys hardcodeadas o un modelo de datos frágil.
• Fijar el objetivo de 48-72 horas: estabilizar, añadir guardarraíles básicos y lanzar una release pequeña y segura.

En 2-3 días, los equipos a menudo pueden estabilizar el login corrigiendo el manejo de sesiones, limpiando variables de entorno y añadiendo logging básico para que los fallos sean visibles. Problemas de seguridad obvios (como secretos expuestos) pueden parchearse, y las roturas “aleatorias” suelen desaparecer una vez que se simplifican algunas partes enredadas.

Lo que suele convertirse en propuesta de reconstrucción: arquitectura que bloquea cambios, propiedad poco clara de cuentas de terceros o un esquema de base de datos que no soporta uso real. Presenta el trade-off con claridad: “Podemos parchear para que funcione ahora, pero si quieres cambios más rápidos después, reconstruir será más barato que arreglos repetidos.”

Siguientes pasos: hacer el intake repetible y reducir sorpresas

Trata el intake como un pequeño producto. Cuando el proceso es el mismo cada vez, pasas menos tiempo persiguiendo detalles y más tiempo arreglando lo que importa.

Envía tu checklist antes del kickoff. Pide al cliente que lo devuelva con el acceso en su lugar. Si el acceso está “en camino”, el proyecto ya está retrasándose. Una regla práctica: no se empieza a trabajar hasta que puedas ver el repo y un entorno en ejecución.

Un ritmo práctico es reservar una ventana corta de estabilización antes de planear nuevas funciones. Pon 48-72 horas en el calendario para confirmar qué existe, qué está roto y qué es riesgoso. Después de eso, puedes estimar mejoras con menos sorpresas.

Escribe los riesgos en lenguaje claro y consigue firma en las prioridades. No se trata de papeleo, sino de prevenir confusiones cuando un “arreglo pequeño” se convierte en un problema de seguridad o una reconstrucción.

Si necesitas ayuda externa para código heredado generado por IA, FixMyMess (fixmymess.ai) hace diagnósticos y reparaciones de bases de código, incluyendo endurecimiento de seguridad, refactor y preparación para despliegue. También ofrecen una auditoría de código gratuita para sacar a la luz problemas antes de que te comprometas con un plan.