Aprende a exportar el código fuente desde una plataforma de vibe-coding y conservar la propiedad: ejecutar localmente, configurar CI, gestionar secretos y preparar un repo listo para traspaso.
Poseer el código es más que recibir un zip desde una plataforma. Significa que puedes compilar, ejecutar, cambiar y enviar la app sin necesitar el workspace original, botones especiales o ajustes ocultos. Un proyecto que realmente posees se comporta como cualquier repo normal: un compañero puede clonarlo, arrancarlo en su portátil y desplegarlo mediante un pipeline estándar.
La mayoría de la ansiedad por lock-in viene de unos pocos huecos recurrentes:
Otra sorpresa común es que la app funcione bien en la versión alojada, pero falle localmente porque variables de entorno, configuración de la base de datos o secretos nunca se hicieron explícitos.
Una exportación limpia desde una plataforma de vibe-coding debería conducir a cuatro resultados:
Esto importa aunque nunca planees abandonar la plataforma. Una postura sólida de propiedad es un seguro: reduce riesgos, facilita auditorías y simplifica negociaciones si contratas una agencia, buscas financiación o cambias de equipo.
Si usaste Koder.ai, tu exportación puede incluir stacks comunes como una app web React, un backend en Go, PostgreSQL o una app móvil Flutter. El stack importa menos que el principio: todo lo necesario para ejecutar debe ser visible en el repositorio, no atrapado en un entorno alojado.
Imagina a un fundador entregando una app a un contratista. "Aquí está el repo" debería ser suficiente. El contratista no debería necesitar acceso al proyecto original de la plataforma para encontrar la URL base de la API, crear el esquema de la base de datos o aprender a compilar el frontend.
Después de exportar, deberías tener un repositorio normal que puedas abrir en un editor, ejecutar en tu portátil y entregar a otro equipo sin necesitar la plataforma original.
En proyectos de Koder.ai, las exportaciones suelen mapear a estructuras familiares: una app web React, un backend en Go y (si la construiste) una app móvil Flutter. Los nombres de carpetas varían, pero el repo debe dejar claro dónde vive cada parte y cómo se conectan.
Empieza ubicando los puntos de entrada y el flujo previsto. Quieres el primer archivo que arranca cada app, además de los scripts que muestran cómo desarrollar y ejecutarla.
Señales típicas:
package.json más una carpeta src/ (a menudo con main.tsx o similar)go.mod y una carpeta cmd/ o main.gopubspec.yaml de Flutter y lib/main.dartREADME o Makefile en el nivel superior que describa cómo ejecutar tododocker-compose.yml si la exportación está pensada para ejecutarse como un conjunto de serviciosLas dependencias deberían estar fijadas. Para JavaScript eso significa un lockfile (package-lock.json, yarn.lock o pnpm-lock.yaml). Para Go, go.mod y go.sum. La ausencia de pins no hace imposible ejecutar el proyecto, pero dificulta builds reproducibles.
La configuración debe estar separada del código. Busca ejemplos como .env.example o config.example.yaml. No deberías ver secretos reales (claves API, contraseñas de producción) comprometidos en la exportación. Si los ves, considéralos una filtración y rótalos.
Para trabajo con base de datos, localiza una carpeta de migraciones (migrations/, db/migrations/) o archivos SQL con marcas temporales. En una app Go + PostgreSQL también puedes encontrar un pequeño runner de migraciones o un script que aplica las migraciones.
Una comprobación rápida de sentido común: ubica primero los comandos de build y ejecución (npm run dev, go run, make y similares). Si un script depende de un comando exclusivo de la plataforma, reemplázalo por herramientas estándar antes de declarar el repo independiente.
Trata la exportación como un artefacto de release. Antes de ejecutar nada, haz un rápido pase de "¿está todo aquí?". Las piezas faltantes son más fáciles de detectar ahora que después de empezar a cambiar cosas.
Una comprobación práctica de completitud es buscar las “raíces” de cada parte: un package.json para una web React, un go.mod para un backend Go y archivos de migración/seed para PostgreSQL.
Crea un repositorio Git fresco desde la carpeta exportada y commitea exactamente lo que recibiste antes de arreglar nada. Eso te da una línea base limpia y facilita revisar los cambios posteriores.
git init
# Optional: set default branch name
# git branch -M main
git add -A
git commit -m "Initial export"
Ahora ejecuta localmente en pasos pequeños y verificables. Instala dependencias, crea la configuración local, arranca la base de datos primero, luego el backend y por último el frontend. Mientras lo haces, anota cada comando que realmente usas. Esas notas se convertirán en tu README.
Aquí hay una secuencia de comandos simple que puedes adaptar a tu estructura exportada:
# Frontend
cd web
npm install
npm run dev
# Backend
cd ../server
go mod download
go run ./cmd/server
Un servidor puede iniciar mientras la app sigue rota. Confirma que puede leer y escribir datos.
Elige comprobaciones rápidas que coincidan con el producto:
Una vez tengas una ejecución local funcional, convierte tus notas en un README.md real con pasos copy-paste: desde dónde ejecutar comandos, el orden para iniciar servicios y qué variables de entorno son necesarias.
Una exportación puede ejecutarse, pero aún parecer "generada" en lugar de propia. Un repo listo para el traspaso deja claro dónde viven las cosas, cómo ejecutar el proyecto y cómo mantenerlo consistente.
Comienza con un layout claro en el nivel superior. Los nombres importan menos que la consistencia.
apps/ para frontends orientados a usuarios (web, móvil)services/ para APIs, workers y jobsshared/ para tipos y utilidades compartidasinfra/ para plantillas de despliegue, scripts y ejemplos de entornodocs/ para notas de arquitectura y runbooksLuego añade un pequeño conjunto de archivos que reduzcan las adivinanzas:
README.md con prerrequisitos y comandos exactosCONTRIBUTING.md con unas reglas simples (branches, PRs, no secretos).gitignore para mantener archivos de entorno local y outputs fuera de GitMantén el README práctico. Si el repo incluye varias partes (frontend React, API Go, PostgreSQL), explica el orden para arrancarlas y dónde vive la configuración (por ejemplo, "copia .env.example a .env").
Haz una comprobación en máquina limpia: clona en una carpeta nueva y sigue tu propio README. Si exportaste desde Koder.ai, trata la exportación como el primer commit de un proyecto independiente y solo entonces invita a otros.
Un buen setup local responde a una pregunta rápidamente: ¿puede un nuevo desarrollador poner la app en marcha en menos de 15 minutos sin adivinar?
Elige un enfoque local por defecto y sé explícito. Las instalaciones nativas son rápidas para quienes ya tienen las herramientas correctas. Los contenedores son más consistentes entre máquinas pero añaden sobrecarga. Si soportas ambos, etiqueta uno como por defecto y el otro como opcional.
Un patrón simple que funciona bien: una página del README, un archivo de env de ejemplo y un comando bootstrap.
Commita un archivo de ejemplo con valores falsos para que la gente sepa qué rellenar sin filtrar secretos.
# .env.example (example values only)
APP_ENV=local
PORT=8080
DATABASE_URL=postgres://app_user:app_pass@localhost:5432/app_db?sslmode=disable
JWT_SECRET=change-me
API_BASE_URL=http://localhost:8080
En el README, explica dónde vive el archivo real (por ejemplo, "copia a .env") y qué variables son requeridas vs opcionales.
Añade un pequeño script que ejecute los pasos aburridos en el orden correcto. Manténlo legible.
#!/usr/bin/env bash
set -euo pipefail
cp -n .env.example .env || true
# Backend deps
cd backend
go mod download
# Database: create, migrate, seed
./scripts/db_create.sh
./scripts/db_migrate.sh
./scripts/db_seed.sh
# Frontend deps
cd ../web
npm install
Para el plan de base de datos, documenta tres cosas: cómo crear la BD, cómo se ejecutan migraciones y cómo obtener datos semilla para una primera ejecución realista.
Finalmente, añade un chequeo de salud rápido para que la gente confirme que la app funciona antes de navegarla. Un endpoint pequeño como GET /health que devuelva "ok" (y verifique la conectividad a la base de datos) suele ser suficiente.
Cuando exportas un proyecto, el código puede ser tuyo, pero los secretos deben permanecer privados. Asume que el repo se compartirá con nuevos compañeros.
Empieza listando lo que la app necesita para ejecutarse. No adivines. Revisa el código en busca de lecturas de configuración (variables de entorno, archivos de config) y verifica las integraciones que activaste.
Un inventario básico de secretos suele incluir credenciales de base de datos, claves de APIs de terceros, ajustes de auth (OAuth o JWT), credenciales de almacenamiento y secretos específicos de la app como claves de cifrado o firmas de webhooks.
Decide dónde vive cada secreto en cada entorno. Una regla por defecto útil es:
.env controlado por el desarrollador (no commiteado)Si exportaste desde una plataforma de vibe-coding como Koder.ai, asume que cualquier cosa mostrada en chat, logs o paneles de configuración pudo haber sido copiada. Mueve los secretos fuera del repositorio inmediatamente.
Un enfoque práctico es commitar una plantilla segura (como .env.example), mantener valores reales fuera de Git (añadir .env a .gitignore) e inyectar secretos de producción en tiempo de despliegue.
Si hay alguna posibilidad de que secretos se hayan expuesto durante la exportación, rótalos. Prioriza contraseñas de base de datos, secretos de clientes OAuth y claves de firma de webhooks.
Añade un par de guardarraíles para que esto no vuelva a ocurrir: un pre-commit que busque patrones obvios de secretos, un escaneo de secretos en CI, carga de configuración estricta que falle rápido cuando falten variables requeridas y credenciales separadas por entorno.
Un breve SECRETS.md ayuda en los traspasos. Mantenlo simple: variables requeridas, dónde se almacenan por entorno y quién puede rotarlas.
Una vez que tomas propiedad, CI es tu red de seguridad. Mantén la primera versión pequeña. Cada push debe demostrar que el proyecto aún se compila, las comprobaciones básicas pasan y las pruebas (si las hay) se ejecutan.
CI debería responder a una pregunta rápidamente: "¿Es seguro mergear este cambio?" Para la mayoría de repos, eso significa instalar dependencias, compilar, lint y ejecutar pruebas unitarias.
Divide jobs por parte de la app para que las fallas sean evidentes:
Usa caching, pero no dejes que oculte problemas. Cuando la caché falle, CI debe seguir funcionando, solo más lento.
Prefiere un comando único por paso (make test, npm run test, etc.) para que el mismo comando funcione localmente y en CI. Reduce confusión y mantiene los logs más cortos.
Ejemplo de forma (ajusta nombres a tu repo):
jobs:
web:
steps:
- run: npm ci
- run: npm run lint
- run: npm run build
api:
steps:
- run: go test ./...
- run: go build ./...
Después de estabilizar lo básico, añade un flujo de release sencillo: taggear releases, construir artefactos y guardarlos como artefactos de CI. Aunque hoy despliegues desde una plataforma, los artefactos repetibles facilitan mucho cambiar de host más adelante.
Exportar código es solo la mitad del trabajo. La otra mitad es asegurarte de que el proyecto se comporte igual fuera de la plataforma.
Las exportaciones a menudo dependen de variables de entorno, migraciones, datos semilla y pasos de build que la plataforma manejaba por ti. Una pantalla en blanco o un error de base de datos en la primera ejecución es normal.
Haz una ejecución base antes de cambiar nada: instala deps, configura variables, aplica migraciones y arranca servicios en orden. Arregla solo lo necesario para igualar el setup esperado.
El accidente más común es commitear claves API o contraseñas reales, normalmente por copiar un .env o por un config generado. Commita solo plantillas. Mantén valores reales en tu entorno local o en un almacén de secretos.
Actualizar paquetes u reorganizar carpetas de entrada hace difícil saber si los problemas vinieron de la exportación o de tus cambios.
Logra primero una ejecución funcional y luego mejora en commits pequeños y separados.
"Funciona en mi máquina" suele venir de versiones de herramientas sin fijar (Node, Go, Flutter, incluso gestores de paquetes).
Fija versiones de runtimes en un lugar claro (un archivo o el README), conserva lockfiles (package-lock, go.sum, pubspec.lock) y verifica el setup en una segunda máquina o en un contenedor limpio.
Los traspasos fallan porque nadie recuerda el paso raro necesario para iniciar la app. Escríbelo mientras está fresco: variables de entorno requeridas, cómo ejecutar migraciones, dónde van los logs y cómo resetear el estado local.
Un equipo de tres personas construye un portal de clientes en Koder.ai: una web React, una API en Go y una base PostgreSQL. Cuando llega el momento de entregarlo a un equipo externo, quieren que la exportación se sienta como un repo normal que alguien pueda ejecutar el primer día.
Día 1: exportan, crean un repo Git nuevo y ejecutan localmente. El frontend arranca, pero la API falla porque faltan variables de entorno. No adivinan. Revisan el código, identifican las claves exactas usadas y crean un .env.example con placeholders. Los valores reales quedan en un gestor de contraseñas y en .env locales.
También notan que puertos y ajustes de CORS iban bien en la plataforma pero necesitan defaults locales. Definen valores previsibles (por ejemplo, API en 8080 y web en 3000) para que máquinas nuevas se comporten igual.
Día 2: añaden migraciones y un pequeño script seed que crea un usuario demo y unas filas de ejemplo. Luego escriben un README corto que cubre prerrequisitos, comandos para ejecutar y cómo verificar que funciona (un endpoint de health para la API y un login de muestra para la UI).
Día 3: agregan un workflow CI básico que ejecuta tests, linting y builds para ambos servicios en cada pull request. Para staging, documentan un plan simple: construir contenedores, configurar secretos en el entorno, ejecutar migraciones en deploy y mantener una opción de rollback.
Un buen traspaso suele incluir un repo que funcione localmente desde un clone fresco, .env.example más notas sobre dónde viven los secretos, migraciones y datos seed, cheques de CI que fallen rápido y una nota corta de despliegue para staging y rollback.
Antes de dar por terminada la exportación, demuestra que el proyecto puede vivir fuera de la plataforma. Si otro desarrollador puede ejecutarlo sin adivinar, vas por buen camino.
Usa esta lista final:
Tras la comprobación técnica, haz la propiedad explícita. Decide quién se ocupa de actualizar dependencias, cambios de infraestructura (bases de datos, colas, DNS) y releases. Si nadie se responsabiliza, el repo se irá degradando aunque la app funcione hoy.
Planifica una ventana corta de estabilización antes de trabajo de features importantes. Dos a cinco días laborables suelen ser suficientes para arreglar las asperezas de la exportación, pulir el README y eliminar los problemas de "funciona en mi máquina".
Si usas Koder.ai (koder.ai), las exportaciones junto con funciones como snapshots y rollback facilitan iterar mientras endureces el repo. Una vez estable, mantén Git como fuente de la verdad y trata futuras exportaciones como checkpoints, no como el historial principal.
Define el siguiente hito de traspaso en lenguaje claro: "Cualquier desarrollador puede ejecutarlo en 30 minutos." Luego pruébalo pidiendo a alguien nuevo que siga el README en una máquina limpia. Sus preguntas se convertirán en tu lista final de pendientes.
Trata la propiedad como independencia: puedes compilar, ejecutar, modificar y desplegar la app desde un repositorio normal sin necesitar el proyecto original en la plataforma, ajustes especiales del UI o pasos de compilación ocultos.
Una buena prueba es: ¿puede un nuevo miembro clonar el repo y ponerlo en marcha usando solo el README?
Comienza con una comprobación rápida de completitud:
package.json, go.mod, pubspec.yaml).package-lock.json, yarn.lock, pnpm-lock.yaml, go.sum).migrations/ o similar).docker-compose.yml).Si algo necesario para ejecutar solo está descrito en la interfaz o en un chat, escríbelo y muévelo al repo.
Hazlo en pasos pequeños y verificables:
.env.example → .env.Porque el entorno alojado suele tener cosas que nunca dejaste explícitas:
Soluciona esto haciendo visible la configuración: .env.example, scripts de migración y un README con comandos exactos.
Un servidor puede arrancar y aun así estar roto. Verifica el flujo real de datos:
Si no puedes reproducir cambios de datos localmente, tu setup o migraciones están incompletas.
Enfoque por defecto:
.env.example con valores ficticios..env a .gitignore.Si encuentras claves reales en el repo, asúmelas comprometidas y rótalas. Prioriza credenciales de bases de datos, secretos OAuth y claves de firma de webhooks.
Mantén la primera versión de CI pequeña y coherente con los comandos locales:
go test ./... y compilar el backend.Haz que el CI invoque los mismos scripts que esperas que usen los desarrolladores (por ejemplo make test o ). Así reduces problemas de “funciona en local pero falla en CI”.
Sí—si quieres un traspaso predecible. Un buen conjunto mínimo es:
README.md top-level con comandos copy-paste..env.example que describa variables requeridas y opcionales.La meta es que un desarrollador nuevo pueda ejecutar la app en 15–30 minutos sin adivinar.
Una estructura común es:
apps/ para frontends (web, móvil).services/ para APIs y workers.shared/ para tipos y utilidades compartidas.infra/ para plantillas de despliegue y ejemplos de entorno.Los nombres importan menos que dejar claro qué se ejecuta dónde y cómo se conectan las piezas.
Secuencia práctica:
Una vez estable, trata a Git como fuente de la verdad y usa futuras exportaciones de la plataforma solo como puntos de control, no como historial principal.
No refactorices de inmediato: primero demuestra que funciona tal cual, y luego mejora en commits separados.
npm run build