Aprenda a exportar código-fonte de uma plataforma vibe-coding e assumir posse limpa: rodar localmente, configurar CI, gerenciar segredos e preparar um repositório pronto para handoff.
Possuir o código é mais do que receber um zip de uma plataforma. Significa que você consegue buildar, rodar, alterar e enviar o app sem precisar do workspace original, botões especiais ou configurações escondidas. Um projeto que você realmente possui se comporta como qualquer repositório normal: um novo colega pode cloná‑lo, iniciar no laptop e deployar por um pipeline padrão.
A maior parte da ansiedade com lock‑in vem dos mesmos gaps:
Outra surpresa comum é quando o app roda bem na versão hospedada, mas falha localmente porque variáveis de ambiente, setup do banco ou segredos nunca foram explicitados.
Uma exportação limpa de uma plataforma vibe‑coding deve levar a quatro resultados:
Isso importa mesmo se você nunca planeja sair da plataforma. Uma postura sólida de posse é uma apólice: reduz risco, facilita auditorias e torna negociações mais simples se você contratar uma agência, captar investimento ou mudar de time.
Se você usou Koder.ai, sua exportação pode incluir stacks comuns como uma web em React, um backend em Go, PostgreSQL ou um app móvel em Flutter. A stack importa menos que o princípio: tudo o que é necessário para rodar deve estar visível no repositório, não preso em um ambiente hospedado.
Imagine um fundador entregando um app a um contratado. “Aqui está o repo” deveria ser suficiente. O contratado não deveria precisar de acesso ao projeto original na plataforma para encontrar a URL base da API, criar o esquema do banco ou aprender como buildar o frontend.
Depois da exportação, você deve ter um repositório normal que dá para abrir num editor, rodar no seu laptop e entregar a outro time sem precisar da plataforma original.
Em projetos do Koder.ai, exports frequentemente mapeiam para estruturas familiares: um web em React, um backend em Go e (se você construiu) um app Flutter. Nomes de pastas variam, mas o repositório deve deixar óbvio onde cada parte vive e como elas se conectam.
Comece localizando os pontos de entrada e o fluxo pretendido. Você quer o primeiro arquivo que inicializa cada app, mais os scripts que mostram como desenvolver e rodar.
Sinais típicos:
package.json mais uma pasta src/ (frequentemente com main.tsx ou similar)go.mod e uma pasta cmd/ ou main.gopubspec.yaml do Flutter e lib/main.dartREADME no nível superior ou um Makefile que descreva como rodar tudodocker-compose.yml se a exportação se destina a rodar como conjunto de serviçosDependências devem estar travadas. Para JavaScript, isso significa um lockfile (package-lock.json, yarn.lock ou pnpm-lock.yaml). Para Go, go.mod e go.sum. Pins ausentes não tornam o projeto impossível de rodar, mas dificultam builds reprodutíveis.
Configuração deve estar separada do código. Procure por exemplos como .env.example ou config.example.yaml. Você não deve ver segredos reais (chaves de API, senhas de produção) commitados na exportação. Se vir, trate como vazamento e rotacione os segredos.
Para trabalho com banco, encontre uma pasta de migrações (migrations/, db/migrations/) ou arquivos SQL com timestamps. Em um app Go + PostgreSQL, você também pode ver um pequeno runner de migrações ou um script que aplica migrações.
Uma checagem rápida: localize primeiro os comandos de build e execução (npm run dev, go run, make e similares). Se um script depender de um comando exclusivo da plataforma, substitua por ferramentas padrão antes de declarar o repositório independente.
Trate a exportação como um artefato de release. Antes de rodar qualquer coisa, faça um rápido passe de “está tudo aqui?”. Peças faltantes são mais fáceis de achar agora do que depois de começar a mexer.
Uma checagem prática de completude é procurar as “raízes” de cada parte: um package.json para frontend React, um go.mod para backend Go e arquivos de migração/seed para PostgreSQL.
Crie um repositório Git novo a partir da pasta exportada, depois commite exatamente o que você recebeu antes de corrigir qualquer coisa. Isso dá uma linha de base limpa e facilita revisar mudanças posteriores.
git init
# Optional: set default branch name
# git branch -M main
git add -A
git commit -m "Initial export"
Agora rode localmente em passos pequenos e verificáveis. Instale dependências, crie a configuração local, inicie o banco primeiro, depois o backend, depois o frontend. Enquanto faz isso, anote cada comando que realmente usar. Essas notas viram seu README.
Aqui está uma sequência simples que você pode adaptar à sua estrutura exportada:
# Frontend
cd web
npm install
npm run dev
# Backend
cd ../server
go mod download
go run ./cmd/server
Um servidor pode subir enquanto o app ainda está quebrado. Confirme que ele consegue ler e gravar dados.
Escolha verificações rápidas que combinem com o produto:
Quando tiver uma execução local funcionando, transforme sua nota em um README.md real com passos copy‑paste: onde rodar cada comando, a ordem para iniciar serviços e quais variáveis de ambiente são necessárias.
Uma exportação pode até rodar, mas ainda parecer “gerada” em vez de pertencente a você. Um repositório pronto para handoff deixa óbvio onde as coisas vivem, como rodar o projeto e como mantê‑lo consistente.
Comece com um layout claro no topo. Nomes importam menos que consistência.
apps/ para frontends voltados ao usuário (web, mobile)services/ para APIs, workers e jobsshared/ para tipos e utilitários compartilhadosinfra/ para templates de deploy, scripts e exemplos de ambientedocs/ para notas de arquitetura e runbooksDepois adicione um pequeno conjunto de arquivos que reduzem adivinhações:
README.md com pré‑requisitos e comandos exatosCONTRIBUTING.md com algumas regras (branches, PRs, sem segredos).gitignore para manter arquivos de ambiente local e artefatos fora do GitMantenha o README prático. Se o repositório inclui múltiplas partes (frontend React, API Go, PostgreSQL), especifique a ordem de inicialização e onde a configuração vive (por exemplo, “copie .env.example para .env”).
Faça um teste em máquina limpa: clone em uma nova pasta e siga o seu próprio README. Se você exportou do Koder.ai, trate a exportação como o primeiro commit de um novo projeto independente, e só então convide outras pessoas.
Um bom setup local responde rápido a uma pergunta: um novo membro consegue rodar o app em menos de 15 minutos sem adivinhar?
Escolha uma abordagem local padrão e seja explícito. Instalações nativas são rápidas para quem já tem as ferramentas. Containers são mais consistentes entre máquinas, mas acrescentam overhead. Se suportar os dois, marque um como padrão e o outro como opcional.
Um padrão simples que funciona bem: uma página do README, um arquivo de exemplo de env e um comando bootstrap.
Commit um arquivo de exemplo com valores falsos para que as pessoas saibam o que configurar sem vazar segredos.
# .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
No README, explique onde o arquivo real fica (por exemplo, “copie para .env”) e quais variáveis são obrigatórias vs opcionais.
Adicione um script pequeno que rode os passos repetitivos na ordem correta. Mantenha legível.
#!/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 o plano de banco, documente três coisas: como criar o DB, como as migrações são aplicadas e como obter dados seed para uma primeira execução realista.
Por fim, adicione uma checagem de saúde rápida para confirmar que o app funciona antes de navegar. Um endpoint pequeno como GET /health retornando “ok” (e verificando conectividade com o banco) costuma ser suficiente.
Quando você exporta um projeto, o código pode ser seu, mas os segredos devem permanecer privados. Assuma que o repositório será compartilhado com novos colegas.
Comece listando o que o app precisa para rodar. Não adivinhe. Escaneie o código por leituras de configuração (variáveis de ambiente, arquivos de config) e cheque integrações que você habilitou.
Um inventário básico de segredos normalmente inclui credenciais do banco, chaves de terceiros, configurações de autenticação (OAuth ou JWT), credenciais de storage e segredos específicos do app como chaves de criptografia ou assinaturas de webhook.
Decida onde cada segredo vive em cada ambiente. Uma regra padrão útil é:
.env do desenvolvedor (não commitado)Se você exportou de uma plataforma vibe‑coding como Koder.ai, assuma que qualquer coisa mostrada em chat, logs ou painéis de settings pode ter sido copiada por aí. Mova segredos para fora do repositório imediatamente.
Uma abordagem prática é commitar um template seguro (como .env.example), manter valores reais fora do Git (adicione .env ao .gitignore) e injetar segredos de produção na hora do deploy.
Se houver qualquer chance de segredos terem sido expostos durante a exportação, rotacione‑os. Priorize senhas de banco, segredos de clientes OAuth e chaves de assinatura de webhooks.
Adicione alguns guardrails para evitar que isso volte a acontecer: um pre‑commit que detecte padrões óbvios de segredos, um scanner de segredos no CI, carregamento de configuração estrito que falhe rápido quando variáveis obrigatórias estiverem ausentes e credenciais separadas por ambiente.
Um SECRETS.md curto ajuda no handoff. Mantenha simples: variáveis necessárias, onde são armazenadas por ambiente e quem pode rotacioná‑las.
Uma vez que você assumir a posse, o CI é sua rede de segurança. Mantenha a primeira versão pequena. Todo push deve provar que o projeto ainda builda, checagens básicas passam e testes (se existirem) rodam.
CI deve responder uma pergunta rapidamente: “Essa mudança é segura para mergear?” Para a maioria dos repositórios isso significa instalar dependências, buildar, rodar lint e executar testes unitários.
Separe jobs por parte do app para que falhas fiquem óbvias:
Use cache, mas não deixe o cache esconder problemas. Quando o cache falhar, o CI deve continuar funcionando, apenas mais devagar.
Prefira um comando único por etapa (make test, npm run test, etc.) para que o mesmo comando funcione localmente e no CI. Isso reduz confusão e mantém logs menores.
Exemplo de forma (ajuste nomes para seu repositório):
jobs:
web:
steps:
- run: npm ci
- run: npm run lint
- run: npm run build
api:
steps:
- run: go test ./...
- run: go build ./...
Depois que o básico estiver estável, adicione um fluxo simples de release: tagueie releases, gere artefatos e os guarde como artifacts do CI. Mesmo que você ainda deploye pela plataforma hoje, artefatos reprodutíveis facilitam muito mudar de host depois.
Exportar código é só metade do trabalho. A outra metade é garantir que o projeto se comporte da mesma forma fora da plataforma.
Exportações frequentemente dependem de variáveis de ambiente, migrações, dados seed e passos de build que foram cuidados para você. Uma tela em branco ou erro de banco na primeira execução é normal.
Faça uma execução baseline antes de mudar qualquer coisa: instale dependências, configure env vars, rode migrações, inicie serviços na ordem correta. Corrija apenas o necessário para igualar o setup esperado.
O acidente mais comum é commitar chaves reais, normalmente por copiar um .env ou um config gerado por ferramentas.
Commite apenas templates. Mantenha valores reais no ambiente local ou em um segredo gerenciado.
Atualizar pacotes ou reorganizar pastas imediatamente dificulta identificar se um problema veio da exportação ou das suas mudanças.
Consiga uma execução funcional primeiro, depois faça melhorias em commits pequenos e separados.
“Funciona na minha máquina” muitas vezes vem de versões de ferramentas não travadas (Node, Go, Flutter, até gerenciadores de pacote).
Trave versões de runtime em um lugar claro (um arquivo ou no README), mantenha lockfiles (package-lock, go.sum, pubspec.lock) e verifique o setup em uma segunda máquina ou em um container limpo.
Handoffs falham porque ninguém lembra daquele passo esquisito necessário para iniciar o app. Escreva enquanto está fresco: variáveis obrigatórias, como rodar migrações, onde ficam logs e como resetar o estado local.
Um time de três pessoas constrói um portal de clientes no Koder.ai: um web em React, uma API em Go e um banco PostgreSQL. Na hora de entregar a um time externo, eles querem que a exportação se pareça com um repositório normal que alguém consiga rodar no dia um.
Dia 1: eles exportam, criam um repo Git novo e tentam rodar localmente. O frontend sobe, mas a API falha porque faltam variáveis de ambiente. Eles não adivinham. Leem o código, identificam as chaves exatas usadas e criam um .env.example com placeholders. Valores reais ficam no gerenciador de senhas e em .env locais.
Eles também percebem que portas e CORS funcionavam na plataforma, mas precisam de defaults locais. Definem padrões previsíveis (por exemplo, API na 8080 e web na 3000) para que máquinas novas se comportem do mesmo modo.
Dia 2: adicionam migrações e um pequeno script seed que cria um usuário demo e algumas linhas. Depois escrevem um README curto cobrindo pré‑requisitos, comandos para rodar e como verificar (um endpoint de health para a API e um login de exemplo para a UI).
Dia 3: adicionam um workflow básico de CI que roda testes, lint e builds para ambos serviços em cada pull request. Para staging, documentam um plano simples: buildar containers, setar segredos no ambiente, rodar migrações no deploy e manter uma opção de rollback.
Um bom handoff normalmente inclui um repositório que roda localmente a partir de um clone fresco, .env.example mais notas sobre onde os segredos vivem, migrações e seed data, checagens de CI que falham rápido e uma nota curta de deploy para staging e rollback.
Antes de declarar a exportação concluída, prove que o projeto pode viver fora da plataforma. Se outro desenvolvedor consegue rodá‑lo sem adivinhar, você está em boa forma.
Use esta checklist final:
Depois da checagem técnica, torne a posse explícita. Decida quem responde por atualizações de dependências, alterações de infraestrutura (bancos, filas, DNS) e releases. Se ninguém for dono disso, o repositório envelhece mesmo que o app funcione hoje.
Planeje uma janela curta de estabilização antes de trabalho de features major: dois a cinco dias úteis costumam bastar para corrigir arestas da exportação, ajustar o README e eliminar problemas de “funciona na minha máquina”.
Se você está usando Koder.ai (koder.ai), exports junto com recursos como snapshots e rollback tornam mais fácil iterar enquanto você fortalece o repositório. Uma vez estável, mantenha o Git como fonte de verdade e trate futuras exportações como checkpoints, não como o histórico principal.
Defina a próxima meta de handoff em linguagem simples: “Qualquer desenvolvedor consegue rodar em 30 minutos.” Então teste pedindo para alguém novo seguir o README em uma máquina limpa. As dúvidas dessa pessoa viram sua lista final de tarefas.
Trate posse como independência: você consegue buildar, executar, modificar e implantar o app a partir de um repositório comum sem precisar do projeto original na plataforma, de configurações especiais na UI ou de passos de build ocultos.
Um bom teste é: um novo integrante consegue clonar o repositório e fazê-lo rodar usando apenas o README?
Comece com uma checagem rápida de completude:
package.json, go.mod, pubspec.yaml).package-lock.json, yarn.lock, pnpm-lock.yaml, go.sum).migrations/ ou similar).docker-compose.yml).Se algo necessário para rodar só estiver descrito na UI ou em chats, documente e mova para o repositório.
Faça em passos pequenos e verificáveis:
.env local usando .env.example → .env.Porque o ambiente hospedado frequentemente tinha coisas que você não deixou explícitas:
Resolva tornando o setup visível: .env.example, scripts de migração e um README com comandos exatos.
Um “server iniciado” não é suficiente—verifique o fluxo real de dados:
Se você não consegue reproduzir mudanças de dados localmente, o setup ou as migrações estão incompletos.
Abordagem padrão:
.env.example com valores fictícios..env ao .gitignore.Se encontrar chaves reais no repositório, considere-as comprometidas e rotacione-as. Priorize credenciais de banco, segredos de OAuth e chaves de assinatura de webhooks.
Mantenha o primeiro CI simples e consistente com os comandos locais:
go test ./... e faça o build do backend.Faça o CI chamar os mesmos scripts que os devs usam localmente (por exemplo make test ou npm run build). Isso reduz casos de “funciona na máquina, mas não no CI”.
Sim—se você quer um handoff previsível. Um bom padrão é:
README.md no topo com comandos copy-paste..env.example descrevendo variáveis obrigatórias e opcionais.O objetivo é que um novo desenvolvedor consiga rodar o app em 15–30 minutos sem adivinhar.
Uma estrutura comum:
apps/ para frontends (web, mobile).services/ para APIs e workers.shared/ para tipos e utilitários compartilhados.infra/ para templates de deploy e exemplos de ambiente.O nome exato importa menos do que tornar óbvio o que roda onde e como as peças se conectam.
Sequência prática:
Quando estiver estável, trate o Git como fonte de verdade e use futuras exportações da plataforma como checkpoints, não como o histórico principal.
Não refatore imediatamente—primeiro prove que roda como está e depois melhore em commits separados.