Lista de verificación para la entrega de código fuente a clientes y agencias

Qué debe lograr una entrega de código fuente

Una entrega de código fuente es el momento en que el proyecto deja de ser “algo que la agencia puede ejecutar” y pasa a ser “algo que el cliente puede poseer”. Sin una entrega clara, los problemas comunes aparecen rápido: la app solo compila en un portátil, producción depende de un secreto que nadie encuentra, o una pequeña actualización se convierte en días de conjeturas.

El objetivo de cualquier lista de verificación de entrega es simple: después de la transferencia, el cliente puede compilar, ejecutar y desplegar el producto sin necesitar a la agencia de guardia. Esto no significa “nunca más apoyo”. Significa que lo básico es repetible y está documentado, de modo que la siguiente persona pueda retomarlo con confianza.

Qué se considera entregable debe ser explícito. Como mínimo, una entrega completa normalmente incluye:

• El repositorio completo (incluyendo archivos de despliegue y scripts de migración)
• Documentación de configuración que funcione en una máquina limpia
• Traspaso de accesos (cuentas, permisos y dónde vive el sistema)
• Un runbook para tareas rutinarias (despliegues, rollback, backups, logs)
• Una etiqueta o snapshot final “conocido bueno” que el cliente pueda referenciar

El alcance importa tanto como el contenido. Algunas entregas cubren solo un entorno (por ejemplo, producción). Otras incluyen dev, staging y producción con configuraciones y procesos separados. Si no nombras qué entornos están incluidos, la gente asume cosas distintas, y ahí es donde ocurren los fallos.

Una forma práctica de definir el éxito es una prueba de verificación: una persona que no construyó la app puede exportar el código (por ejemplo, desde una plataforma como Koder.ai), seguir la documentación, configurar variables de entorno, ejecutar migraciones, compilar y desplegar en el entorno acordado.

Esta lista se centra en la preparación técnica: variables de entorno, rotación de secretos, migraciones de base de datos, scripts de despliegue y verificación de builds. No cubre términos legales, contratos, cláusulas de propiedad intelectual o disputas de pago. Esos asuntos importan también, pero pertenecen a un acuerdo aparte.

Antes de exportar: acuerden propiedad y calendario

Una entrega limpia comienza antes de cualquier exportación. Si acuerdan quién posee qué y cuándo, evitan sorpresas de último minuto como despliegues rotos, hosting impago o accesos faltantes.

Fijen la fecha de entrega y una ventana de congelamiento corta

Elijan una fecha de entrega y definan una ventana de congelamiento (a menudo 24–72 horas) en la que solo se aceptan correcciones urgentes. Esto mantiene el código exportado y el sistema en producción sincronizados. Si se necesita un hotfix durante la congelación, anoten exactamente qué cambió y asegúrense de que esté incluido en la exportación final.

Aclaren la propiedad de cuentas y facturación

Decidan quién será el propietario de DNS, hosting en la nube y cualquier servicio de pago después de la entrega. Esto no es solo papeleo. Si la facturación queda en la tarjeta de la agencia, los servicios pueden pausarse después sin aviso.

Una forma rápida de concretarlo:

• Nombrar al propietario de la cuenta para DNS, hosting y correo
• Confirmar quién paga cada factura a partir de la fecha de entrega
• Decidir si las cuentas se transfieren o se recrean bajo el cliente
• Registrar el contacto de soporte para cada proveedor

Escriban esto en lenguaje claro para que ambas partes lo sigan.

Enumeren los entornos y dónde corren

Acordar qué entornos existen (local, staging, producción) y dónde se ejecuta cada uno. Indiquen si staging es un servidor separado, una base de datos distinta o solo una bandera de características. Si usaron una plataforma como Koder.ai, confirmen también qué está hospedado allí frente a lo que se espera que corra en la infraestructura del cliente después de la exportación.

Recojan accesos con antelación

No esperen hasta el último día para solicitar accesos. Asegúrense de que las personas correctas puedan llegar a lo que necesitan: el repo, CI, hosting, la base de datos y el proveedor de correo.

También acuerden la prueba de aceptación final y el proceso de sign-off. Por ejemplo: “El cliente puede compilar desde una máquina limpia, ejecutar migraciones, desplegar a staging y pasar la prueba de humo. Luego ambas partes firman la aceptación por escrito.”

Básicos del repositorio y la documentación a incluir

Una buena lista de verificación de entrega empieza con un repo que un equipo nuevo pueda abrir y entender en minutos. Confirmen qué está incluido (código de la app, plantillas de configuración, scripts) y qué está intencionalmente ausente (secretos reales, llaves privadas, archivos generados grandes). Si algo está excluido, indiquen dónde vive y quién lo gestiona.

Mantengan la estructura predecible. Apunten a carpetas de nivel superior claras como frontend/, backend/, mobile/, infra/, scripts/ y docs/. Si el proyecto es un monorepo, expliquen cómo se relacionan las piezas y cómo ejecutar cada una.

El README debe ser utilizable por alguien que no creó el proyecto. Debe cubrir los prerrequisitos y la ruta más rápida para una ejecución de desarrollo funcional, sin conjeturas.

Qué documentar (mínimo)

Incluyan una sección breve y humana en el README que responda:

• Qué contiene este repo y qué hace (un párrafo)
• Prerrequisitos con versiones exactas (runtime, gestor de paquetes, Docker si aplica)
• Pasos de inicio con un comando para desarrollo local (y qué significa “éxito”)
• Cómo ejecutar tests y cómo construir un artefacto de producción
• Dónde encontrar documentos clave: notas de arquitectura, migraciones, notas de despliegue

Añadan notas de arquitectura simples en lenguaje llano: qué se comunica con qué y por qué. Un pequeño diagrama es opcional, pero unas pocas frases suelen bastar. Ejemplo: “Frontend React llama a la API en Go. La API lee y escribe en PostgreSQL. Los jobs en background corren como procesos worker separados.”

Finalmente, incluyan un changelog versionado o notas de release para la build de entrega. Puede ser un CHANGELOG.md o un archivo corto de “release notes” de la entrega que indique el commit/etag exacto, qué se envió y problemas conocidos.

Si el código fue exportado desde una plataforma como Koder.ai, anoten el tipo de proyecto generado (web, servidor, móvil), la toolchain esperada (por ejemplo React, Go, PostgreSQL, Flutter) y las versiones de OS/herramientas que el cliente debe usar para reproducir la compilación.

Variables de entorno: inventario y documentación

Las variables de entorno suelen ser la razón por la que una “app que funciona” falla justo después de la entrega. Una buena lista trata las variables como parte del producto, no como un añadido.

Empiecen por escribir un inventario que un equipo nuevo pueda seguir sin adivinar. Manténganlo en lenguaje claro e incluyan un ejemplo de formato de valor (no secretos reales). Si una variable es opcional, expliquen qué pasa si falta y qué valor por defecto se usa.

Una forma simple de presentar el inventario es:

• Nombre de la variable, qué controla y un ejemplo de formato
• Requerida vs opcional, y el comportamiento por defecto
• Dónde se establece (CI, panel de hosting, archivo .env local)
• Qué entornos necesitan valores distintos (dev, staging, producción)
• Quién es el responsable de los cambios (cliente, agencia o compartido)

Resalten las diferencias por entorno claramente. Por ejemplo, staging puede apuntar a una base de datos de pruebas y a un proveedor de pagos sandbox, mientras producción usa servicios reales. También anoten valores que deben coincidir entre sistemas, como URLs de callback, orígenes permitidos o identificadores de bundle de apps móviles.

Documenten dónde vive cada valor hoy. Muchos equipos reparten valores por lugares: .env locales para desarrollo, variables de CI para builds y ajustes de hosting para runtime. Si usaron Koder.ai para exportar la app, incluyan un archivo .env.example y una nota corta sobre qué variables deben completarse antes del primer build.

Finalmente, prueben que no hay secretos escondidos en el repo. No se limiten a revisar los archivos actuales: examinen el historial de commits por llaves accidentales, .env antiguos o credenciales copiadas en configs de ejemplo.

Ejemplo concreto: un frontend React más una API en Go pueden necesitar API_BASE_URL para la web, y DATABASE_URL más JWT_SIGNING_KEY para el backend. Si staging usa un dominio distinto, escriban ambos valores y dónde cambiarlos, para que el nuevo equipo no despliegue ajustes de staging en producción.

Rotación de secretos: transferir con seguridad y luego demostrar que funciona

Una entrega no está completa hasta que el cliente controle todas las credenciales que la app necesita. Eso significa rotar secretos, no solo compartirlos. Si una agencia (o un contratista anterior) todavía tiene llaves activas, queda una puerta abierta que no pueden auditar.

Comiencen por hacer un inventario completo. No se detengan en contraseñas de BD: incluyan claves de APIs de terceros, secretos de clientes OAuth, secretos de firma de webhooks, claves de firma JWT, credenciales SMTP, llaves de acceso a almacenamiento y cualquier token “temporal” en CI.

Aquí hay una lista simple para el día de la rotación:

• Listar cada secreto, qué desbloquea y dónde está actualmente (archivos env locales, CI, panel de hosting, vault)
• Crear nuevas credenciales bajo las cuentas del cliente y asignar un responsable para cada una (persona y bandeja de equipo)
• Actualizar la configuración de la app para usar los nuevos valores y desplegar primero a staging o a un entorno de prueba
• Revocar las credenciales antiguas inmediatamente después de confirmar que las nuevas funcionan
• Documentar los pasos exactos de rotación para que la próxima vez sea rutinario y rápido

Tras la rotación, demuestren que nada se rompió. Ejecuten pruebas “de usuario real” rápidas en lugar de solo mirar logs.

Concéntrense en los flujos que dependen de secretos:

• Login, registro, reset de contraseña y refresh de tokens
• Pagos, envío de correos y subidas de archivo
• Webhooks (verificación de firma y reintentos)
• Jobs en background o tareas programadas que llaman APIs externas
• Acciones de administración que usan endpoints privilegiados

Ejemplo: si exportaron un proyecto desde Koder.ai y la app usa un proveedor de pagos y envío de correo, roten ambas llaves, redeplieguen, luego hagan una pequeña transacción de prueba y envíen un correo de prueba. Solo después de que eso funcione deben revocar las llaves que tenía la agencia.

Por último, documenten dónde vivirán los secretos en adelante (vault, variables de CI o ajustes de hosting), quién puede cambiarlos y cómo revertir con seguridad si una rotación causa errores.

Migraciones de base de datos y manejo de datos

Una entrega puede parecer “completa” mientras que la base de datos es la parte que falla primero. Traten las migraciones y los datos como un producto: versionados, repetibles y probados.

Empiecen por anotar la versión actual de la base de datos y dónde viven las migraciones en el repo. Sean específicos: la ruta de la carpeta, el patrón de nombres y el último ID de migración (o timestamp). Si usan PostgreSQL (común con backends en Go), también anoten extensiones requeridas.

Qué documentar (para que alguien más pueda ejecutarlo)

Incluyan un runbook corto que responda estas preguntas:

• Qué comando ejecuta las migraciones y en qué orden correr las cosas (crear DB, aplicar migraciones, luego seeds)
• Cómo difiere según el entorno (local, staging, producción), incluyendo flags de “modo seguro” si los hay
• Si las migraciones son automáticas en el deploy o se ejecutan manualmente, y quién puede correrlas
• Estrategia de seed de datos: ninguna, solo demo, o registros mínimos necesarios (usuario admin, configuraciones por defecto)
• Plan de rollback: qué puede revertirse y qué no (por ejemplo, eliminaciones destructivas de columnas)

Los rollbacks merecen honestidad. Algunos cambios solo son reversibles con una restauración desde backup. Indíquenlo en lenguaje claro y acómpáñenlo con un paso de backup (snapshot antes del deploy, verificar proceso de restauración).

Antes de que la entrega esté completa, ejecuten migraciones sobre una copia de datos de producción si es posible. Esto detecta consultas lentas, índices faltantes y problemas de “funciona con datos vacíos”. Una prueba realista es exportar el código, configurar variables, restaurar un volcado anonimizado y aplicar las migraciones desde cero. Ese ejercicio valida gran parte de la entrega.

Si la app se generó en una plataforma como Koder.ai y luego se exportó, verifiquen que los archivos de migración y cualquier script de seed estén incluidos en la exportación y sigan siendo referenciados correctamente por el proceso de arranque del backend.

Build y CI: que sea repetible

Una entrega solo está completa cuando otra persona puede reconstruir la app desde cero en una máquina limpia. Su lista de verificación debe incluir los comandos exactos de build, versiones requeridas y el resultado esperado (por ejemplo: “bundle web en /dist”, “binario de API con nombre”, “ubicación del APK de Flutter”).

Anoten las herramientas y gestores de paquetes que realmente usan, no lo que creen que usan. En una pila típica esto puede ser Node.js (y npm o pnpm) para un frontend React, la toolchain de Go para el servidor, herramientas cliente de PostgreSQL para configuración local y el SDK de Flutter para móvil.

Hagan predecible la instalación de dependencias. Confirmen que los lockfiles estén comiteados (package-lock.json, pnpm-lock.yaml, go.sum, pubspec.lock) y hagan una instalación desde cero en un equipo nuevo o contenedor limpio para probar que funciona.

Describan qué hace el CI, paso a paso, para que pueda copiarse a otro proveedor de CI si hace falta:

• Instalar dependencias (con lockfiles)
• Ejecutar tests y checks de lint
• Construir salidas (bundle web, binario del servidor, build móvil)
• Producir artefactos (zip, imagen Docker, bundle de release)
• Guardar logs y metadatos de build (versión, commit, fecha)

Separar configuración de build de la configuración de runtime. La configuración en build cambia lo que se compila (por ejemplo una API base URL embebida en el bundle web). La configuración de runtime se inyecta al iniciar la app (URL de DB, claves API y feature flags). Mezclar ambas es una causa común de “funciona en CI” pero falla tras el despliegue.

Proporcionen una receta de verificación local simple. Incluso un conjunto corto de comandos es suficiente:

# Web
pnpm install
pnpm test
pnpm build

# API
go test ./...
go build ./cmd/server

# Móvil
flutter pub get
flutter test
flutter build apk

Si están exportando desde una plataforma como Koder.ai, incluyan cualquier archivo CI generado o presets de build que se usaron durante el despliegue para que el cliente pueda reproducir la misma build fuera de la plataforma.

Scripts de despliegue y proceso de release

Una buena lista de verificación no se queda en “aquí está el repo”. También explica cómo el código llega a ser un servicio en ejecución y quién aprieta el botón.

Empiecen por anotar cómo ocurren los despliegues hoy: totalmente manual (alguien ejecuta comandos en un servidor), impulsados por CI (una pipeline construye y despliega) o a través de una plataforma hospedada. Incluyan dónde viven las configuraciones y qué entornos existen (dev, staging, producción).

Hagan repetibles los pasos de release. Si el proceso depende de una persona que recuerda 12 comandos, conviertan eso en scripts y anoten los permisos necesarios.

Qué incluir con el paquete de despliegue

Den al cliente lo suficiente para desplegar el primer día:

• Comandos de build y run (y versiones exactas de Node, Go, Flutter, etc.)
• Scripts de despliegue (scripts shell, objetivos de Makefile o configs de pipeline)
• Accesos requeridos: roles en la cuenta cloud, registry de contenedores, DNS, admin de base de datos
• Notas de configuración por entorno: dónde se establecen las env vars y cómo difieren por entorno
• Nomenclatura de releases: tags/releases y cómo identificar qué está ejecutándose

Acordar expectativas de downtime. Si se requiere “cero downtime”, definan qué significa en la práctica (blue-green, rolling deploy, ventana de solo lectura para migraciones). Si el downtime es aceptable, definan una ventana clara.

Los assets estáticos y caches son puntos comunes de fallo. Anoten cómo se construyen y sirven los assets, cuándo invalidar caches y si interviene una CDN.

Un rollback que realmente puedas ejecutar

Un rollback debe ser una receta corta y probada ligada a un tag o ID de release. Por ejemplo: desplegar el tag previo, restaurar el snapshot de base de datos anterior si hace falta e invalidar caches.

Si la app fue creada en Koder.ai y luego exportada, mencionen el último snapshot conocido bueno y la versión exacta de la exportación para que el cliente pueda emparejar código con una release funcional rápidamente.

Paso a paso: verificar la build tras la exportación

La verificación es el momento en que se aprende si la entrega es real. El objetivo es simple: alguien nuevo puede tomar el código exportado, configurarlo y obtener la misma app en funcionamiento sin adivinar.

Antes de empezar, registren qué significa “correcto”: la versión de la app en ejecución, el commit/tag actual (si lo tienen) y una o dos pantallas o respuestas de la API para comparar. Si la exportación vino de una plataforma como Koder.ai, anoten el snapshot o el timestamp de exportación para probar que testearon el estado más reciente.

1. Confirmar que la exportación coincide con producción: revisen el historial de commits, las notas de release o metadatos de build. Comparen una cadena de versión visible o un comportamiento pequeño (como una etiqueta de UI) con la app en ejecución.
2. Configurar variables de entorno y secretos: crear la configuración del entorno objetivo (local y staging). Usen el inventario de env vars y asegúrense de que no haya valores hardcodeados en el repo.
3. Instalar dependencias y ejecutar tests: hagan una instalación limpia (sin node_modules/ ni carpetas vendor cacheadas). Ejecuten los tests unitarios y checks de lint exactamente como está documentado.
4. Ejecutar migraciones e iniciar localmente: levanten la base de datos, apliquen migraciones en orden e inicien la app. Confirmen que la app puede leer/escribir datos básicos y que no hay migraciones pendientes.
5. Desplegar a staging, hacer smoke tests y luego promover: desplieguen usando los mismos scripts/pipeline que planearon usar en producción. Solo promuevan cuando staging coincida con las expectativas.

Para las pruebas de humo, manténganlas cortas y ligadas al riesgo:

• Iniciar sesión/cerrar sesión (o crear un usuario de prueba)
• Un flujo central de extremo a extremo (crear-editar-guardar)
• Un callback de email/webhook/pago si aplica
• Manejo básico de errores (entrada inválida, registro faltante)
• Los logs no muestran crashes repetidos ni errores relacionados con secretos

Si algo falla, capturen el comando exacto, la salida de error y las env vars usadas. Ese detalle ahorra horas cuando la propiedad cambia de manos.

Errores comunes en las entregas y cómo evitarlos

La forma más rápida de convertir una entrega en una alarma es asumir “el código es suficiente”. Una buena lista se enfoca en los detalles pequeños y aburridos que definen si el cliente puede ejecutar y cambiar la app sin ustedes.

Los errores que causan la mayoría de los dolores de cabeza

La mayoría de los problemas entra en unos pocos patrones:

• Los secretos no se rotan, así que contraseñas antiguas de la agencia, claves API o tokens cloud siguen funcionando después del traspaso.
• Las variables de entorno están incompletas porque algunos valores solo existen en el CI o en el panel de hosting, no en el repo.
• Cambios puntuales en producción se olvidan, como un hotfix rápido, una edición manual de la BD o un toggle de configuración puesto directamente en el servidor.
• Las migraciones funcionan localmente pero fallan en producción por permisos faltantes, extensiones o propiedad del esquema.
• No hay plan de rollback, y no hay una release etiquetada (o nota de release) a la que regresar cuando el primer despliegue salga mal.

Cómo prevenirlos (sin añadir semanas)

Hagan de la rotación y la limpieza de accesos una tarea programada, no un ítem “cuando tengamos tiempo”. Fijen una fecha en la que las cuentas de la agencia se eliminan, las claves de servicio se regeneran y el cliente confirma que puede desplegar solo con sus credenciales.

Para las env vars, hagan un inventario simple en tres lugares: el repo, el sistema de CI y la UI del hosting. Luego validen con una compilación limpia desde una máquina o contenedor fresco.

Para las migraciones, prueben con el mismo rol de base de datos que usará el despliegue en producción. Si producción requiere pasos elevados (como habilitar una extensión), escríbanlos y dejen clara la responsabilidad.

Un ejemplo realista: tras exportar un proyecto desde Koder.ai, el cliente despliega con éxito pero los jobs en background fallan porque una URL de cola solo estaba configurada en el panel de hosting. Una auditoría rápida de env vars lo habría atrapado. Combinen eso con un tag de release y un rollback documentado (por ejemplo, “redeploy tag v1.8.2 y restaurar el último snapshot”) y el equipo evita downtime.

Checklist final, un ejemplo simple y siguientes pasos

Si solo se quedan con una página de esta lista, guárdense esta. El objetivo es simple: un clone limpio debe ejecutarse en una máquina nueva, con secretos nuevos y una base de datos que pueda avanzar con seguridad.

Verificaciones rápidas (háganlas desde un clone limpio)

Ejecuten estas comprobaciones en un portátil que nunca haya visto el proyecto (o en un contenedor/VM limpio). Es la forma más rápida de detectar archivos faltantes, suposiciones ocultas y credenciales antiguas.

• Compilar desde cero: instalar deps, ejecutar tests (si los hay) y producir una build de release sin ediciones manuales.
• La configuración funciona: establezcan las variables de entorno documentadas y confirmen que la app arranca con una configuración fresca.
• Los secretos están rotados: verifiquen que la app funciona con las llaves nuevas, luego revoquen las antiguas y confirmen que nada se rompe.
• Las migraciones corren limpias: empiecen con una BD vacía, ejecuten migraciones y luego inicien la app y prueben un flujo básico.
• La ruta de despliegue es real: ejecuten el script de despliegue o la workflow de CI una vez y confirmen que produce la misma salida.

Un ejemplo simple de entrega

Una agencia entrega un frontend React, una API en Go y una base de datos PostgreSQL. El equipo del cliente clona el repo, copia el .env.example proporcionado a variables reales, y crea credenciales nuevas para la base de datos, el proveedor de correo y las APIs de terceros. Ejecutan go test (o el comando de tests acordado), construyen la app React, aplican migraciones a una instancia Postgres nueva y arrancan ambos servicios. Finalmente, despliegan usando el script documentado y confirman que el mismo commit puede reconstruirse más adelante.

Siguientes pasos

Mantengan la entrega breve y con un responsable. Una walkthrough de 30 a 60 minutos suele vencer a un documento largo.

• Programen una walkthrough y registren decisiones (quién administra despliegues, secretos y cambios de BD).
• Asignen un responsable para el acceso a producción y un backup.
• Acordar un commit hash de “build de aceptación” final y etiquetarlo.
• Si construyeron en Koder.ai, exporten el código fuente y luego usen snapshots y rollback durante el primer despliegue hecho por el cliente para reducir el riesgo.