Checklist de entrega do código-fonte para clientes e agências

O que uma entrega do código-fonte deve alcançar

Uma entrega do código-fonte é o momento em que o projeto deixa de ser “algo que a agência mantém” e passa a ser “algo que o cliente pode possuir”. Sem uma entrega clara, problemas comuns aparecem rápido: o app só compila em um laptop, a produção depende de um segredo que ninguém encontra, ou uma pequena atualização vira dias de tentativa e erro.

O objetivo de qualquer checklist de entrega do código-fonte é simples: depois da transferência, o cliente consegue compilar, rodar e implantar o produto sem precisar da agência de plantão. Isso não significa “sem suporte nunca”. Significa que o básico é repetível e documentado, para que a próxima pessoa consiga dar continuidade com confiança.

O que conta como entregáveis deve ser explícito. No mínimo, uma entrega completa normalmente inclui:

• O repositório completo (incluindo arquivos de deploy e scripts de migração)
• Documentação de setup que funcione em uma máquina limpa
• Transferência de acessos (contas, permissões e onde o sistema está hospedado)
• Um runbook para tarefas rotineiras (deploys, rollback, backups, logs)
• Uma tag ou snapshot final “conhecida como boa” que o cliente possa referenciar

O escopo importa tanto quanto o conteúdo. Algumas entregas cobrem apenas um ambiente (por exemplo, produção). Outras incluem dev, staging e produção com configurações e processos separados. Se você não nomear quais ambientes estão incluídos, as pessoas supõem coisas diferentes — e é aí que ocorrem as quedas.

Uma forma prática de definir sucesso é um teste de verificação: uma pessoa que não construiu o app consegue exportar o código (por exemplo, a partir de uma plataforma como Koder.ai), seguir a documentação, configurar variáveis de ambiente, rodar migrações, compilar e implantar no ambiente combinado.

Este checklist foca na prontidão técnica: variáveis de ambiente, rotação de segredos, migrações de banco, scripts de deploy e verificação de build. Não cobre termos legais, contratos, cláusulas de IP ou disputas de pagamento. Isso também importa, mas pertence a um acordo separado.

Antes de exportar: combine propriedade e prazos

Uma entrega limpa começa antes de qualquer exportação. Se você concorda sobre quem possui o quê e quando, evita surpresas de última hora como deploys quebrados, hospedagem não paga ou acessos faltantes.

Defina a data de entrega e uma janela de congelamento curta

Escolha uma data de entrega e defina uma janela de congelamento (frequentemente 24–72 horas) em que só correções urgentes são aceitas. Isso mantém o código exportado e o sistema em execução sincronizados. Se um hotfix for necessário durante o congelamento, registre exatamente o que mudou e garanta que esteja incluído na exportação final.

Esclareça propriedade de contas e faturamento

Decidam quem ficará com DNS, hospedagem na nuvem e quaisquer serviços pagos após a entrega. Isso não é só papelada. Se o faturamento permanecer no cartão da agência, serviços podem ser suspensos sem aviso.

Uma forma rápida de tornar isso concreto:

• Nomear o dono da conta para DNS, hospedagem e e-mail
• Confirmar quem paga cada fatura a partir da data de entrega
• Decidir se as contas são transferidas ou recriadas sob o cliente
• Registrar o contato de suporte de cada provedor

Escreva isso em linguagem simples para que ambos os lados possam seguir.

Liste ambientes e onde eles rodam

Combine quais ambientes existem (local, staging, produção) e onde cada um roda. Observe se o staging é um servidor separado, um banco de dados separado ou apenas uma flag de recurso. Se você usou uma plataforma como Koder.ai, confirme também o que está hospedado lá vs o que se espera rodar na infraestrutura do cliente após a exportação.

Colete acessos cedo

Não deixe para o último dia solicitar acessos. Garanta que as pessoas certas possam alcançar o que precisam: o repositório, CI, hospedagem, banco de dados e provedor de e-mail.

Combine também o teste final de aceitação e o processo de sign-off. Por exemplo: “O cliente consegue compilar a partir de uma máquina limpa, rodar migrações, implantar no staging e passar no smoke test. Então ambos assinam o aceite por escrito.”

Básicos do repositório e documentação a incluir

Um bom checklist de entrega do código-fonte começa com um repositório que uma nova equipe consegue abrir e entender em minutos. Confirme o que está incluído (código do app, templates de configuração, scripts) e o que está intencionalmente ausente (segredos reais, chaves privadas, arquivos grandes gerados). Se algo estiver excluído, diga onde fica e quem é o dono.

Mantenha a estrutura previsível. Busque pastas de topo claras como frontend/, backend/, mobile/, infra/, scripts/ e docs/. Se o projeto for um monorepo, explique como as partes se relacionam e como executar cada uma.

O README deve ser utilizável por alguém que não construiu o projeto. Deve cobrir pré-requisitos e o caminho mais rápido para um ambiente de desenvolvimento funcionando, sem adivinhações.

O que documentar (mínimo)

Inclua uma seção breve no README que responda:

• O que este repositório contém e para que serve (um parágrafo)
• Pré-requisitos com versões exatas (runtime, gerenciador de pacotes, Docker se necessário)
• Passos de start em um comando para dev local (e o que significa “sucesso”)
• Como rodar testes e gerar um artefato de produção
• Onde encontrar docs-chave: notas de arquitetura, migrações, notas de deploy

Adicione notas de arquitetura simples em linguagem comum: o que fala com o que e por quê. Um pequeno diagrama é opcional, mas algumas frases geralmente bastam. Exemplo: “Frontend React chama a API em Go. A API lê e grava no PostgreSQL. Jobs em background rodam como um processo worker separado.”

Por fim, inclua um changelog versionado ou notas de release para a build de entrega. Pode ser um CHANGELOG.md ou um arquivo curto de “release notes” que indique o commit/tag exato, o que foi entregue e problemas conhecidos.

Se o código foi exportado de uma plataforma como Koder.ai, registre o tipo de projeto gerado (web, server, mobile), a toolchain esperada (por exemplo React, Go, PostgreSQL, Flutter) e as versões de OS/ferramentas suportadas que o cliente deve usar para reproduzir o build.

Variáveis de ambiente: inventário e documentação

Variáveis de ambiente são frequentemente a razão de um “app funcionando” falhar logo após a entrega. Um bom checklist trata as variáveis como parte do produto, não como um detalhe.

Comece escrevendo um inventário que uma nova equipe possa seguir sem adivinhações. Mantenha em linguagem simples e inclua um exemplo de formato de valor (não segredos reais). Se uma variável for opcional, diga o que acontece quando está ausente e qual default é usado.

Uma forma simples de apresentar o inventário é:

• Nome da variável, o que controla e um exemplo de formato
• Obrigatória vs opcional, além de qualquer comportamento padrão
• Onde ela é definida (CI, dashboard de hospedagem, arquivo local .env)
• Quais ambientes precisam de valores diferentes (dev, staging, produção)
• Quem é o dono das mudanças (cliente, agência ou compartilhado)

Destaque diferenças específicas por ambiente. Por exemplo, o staging pode apontar para um banco de testes e um provedor de pagamento sandbox, enquanto produção usa serviços ao vivo. Também registre valores que precisam bater entre sistemas, como URLs de callback, origens permitidas ou identificadores de bundle mobile.

Documente onde cada valor vive hoje. Muitas equipes dividem valores entre lugares: .env locais para desenvolvimento, variáveis de CI para builds e configurações de hospedagem para runtime. Se você usou uma plataforma como Koder.ai para exportar o app, inclua um arquivo .env.example e uma nota curta sobre quais variáveis precisam ser preenchidas antes do primeiro build.

Por fim, prove que não há segredos escondidos no repositório. Não basta checar os arquivos atuais. Revise o histórico de commits em busca de chaves acidentais, .env antigos ou credenciais copiadas em configs de exemplo.

Exemplo concreto: um frontend React + uma API Go podem precisar de API_BASE_URL para o web app, e DATABASE_URL mais JWT_SIGNING_KEY para o backend. Se o staging usa um domínio diferente, escreva ambos os valores e diga onde alterá-los, para que a nova equipe não envie configurações de staging para produção.

Rotação de segredos: transferir com segurança e provar que funciona

Uma entrega não está completa até que o cliente controle todas as credenciais que o app precisa. Isso significa rotacionar segredos, não apenas compartilhá-los. Se uma agência (ou um ex-contratado) ainda tem chaves válidas, você mantém uma porta aberta que não pode auditar.

Comece fazendo um inventário completo. Não pare em senhas de banco. Inclua chaves de API de terceiros, segredos de clientes OAuth, segredos de assinatura de webhooks, chaves de assinatura JWT, credenciais SMTP, chaves de acesso a storage e quaisquer tokens “temporários” em CI.

Aqui vai um checklist simples para o dia da rotação:

• Liste cada segredo, o que ele desbloqueia e onde está atualmente configurado (arquivos .env locais, CI, dashboard de hospedagem, vault)
• Crie novas credenciais nas contas do cliente e defina um responsável para cada (uma pessoa e uma caixa de entrada de equipe)
• Atualize a configuração do app para usar os novos valores e faça deploy primeiro em staging ou ambiente de teste
• Revogue as credenciais antigas imediatamente após confirmar que as novas funcionam
• Documente os passos exatos de rotação para que a próxima rotação seja rápida e sem surpresas

Após a rotação, prove que nada quebrou. Rode testes rápidos com “fluxos de usuário real” em vez de checar só logs.

Foque em fluxos que dependem de segredos:

• Login, cadastro, reset de senha e refresh de token
• Pagamentos, envio de e-mail e uploads de arquivos
• Webhooks (verificação de assinatura e re-tentativa)
• Jobs em background ou tarefas agendadas que chamam APIs externas
• Ações administrativas que atingem endpoints privilegiados

Exemplo: se você exportou um projeto de Koder.ai e o app usa um provedor de pagamento e envio de e-mail, rotacione ambas as chaves, redeploy em staging, então faça uma pequena transação de teste e envie um e-mail de teste. Só após o sucesso revogue as chaves da agência.

Por fim, documente onde os segredos ficarão daqui para frente (vault, variáveis de CI ou configurações de hospedagem), quem pode alterá-los e como reverter com segurança se uma rotação causar erros.

Migrações de banco e manipulação de dados

Uma entrega pode parecer “concluída” enquanto o banco de dados é a parte que quebra primeiro. Trate migrações e dados como um produto próprio: versionado, repetível e testado.

Comece anotando a versão atual do banco e onde as migrações ficam no repositório. Seja específico: o caminho da pasta, padrão de nomes e o último ID de migração (ou timestamp). Se você usa PostgreSQL (comum em backends Go), também anote extensões necessárias.

O que documentar (para que outro possa executar)

Inclua um runbook curto que responda a estas perguntas:

• Qual comando roda as migrações e em que ordem executar as etapas (criar banco, aplicar migrações, depois seeds)
• Como difere por ambiente (local, staging, produção), incluindo quaisquer flags de “modo seguro”
• Se as migrações são automáticas no deploy ou devem ser executadas manualmente, e quem tem permissão para rodá-las
• Estratégia de seed: nenhuma, demo-only ou registros mínimos obrigatórios (usuário admin, configurações padrão)
• Plano de rollback: o que pode ser revertido e o que não pode (por exemplo, drops destrutivos de colunas)

Rollbacks merecem honestidade. Algumas mudanças só são reversíveis com restauração de backup. Aponte isso em linguagem clara e associe a um passo de backup (snapshot antes do deploy, verificação do processo de restore).

Antes de concluir a entrega, execute migrações em uma cópia dos dados de produção se possível. Isso detecta queries lentas, índices ausentes e problemas de “funciona com dados vazios”. Um teste realista é exportar o código, configurar variáveis, restaurar um dump anonimizável e aplicar as migrações do zero. Esse exercício valida grande parte do checklist.

Se o app foi construído em uma plataforma como Koder.ai e depois exportado, verifique se arquivos de migração e scripts de seed estão incluídos na exportação e ainda são referenciados corretamente pelo processo de inicialização do backend.

Build e CI: torne repetível

A entrega só está completa quando outra pessoa consegue rebuildar o app do zero em uma máquina limpa. Seu checklist deve incluir os comandos exatos de build, versões necessárias e o output esperado (por exemplo: “bundle web em /dist”, “binário da API com nome X”, “APK do Flutter em local Y”).

Registre as ferramentas e os gerenciadores de pacotes que você realmente usa, não o que você acha que usa. Em stacks típicas isso pode ser Node.js (npm ou pnpm) para React, toolchain Go para o servidor, ferramentas do PostgreSQL para setup local e SDK do Flutter para mobile.

Torne a instalação de dependências previsível. Confirme que lockfiles estão comitados (package-lock.json, pnpm-lock.yaml, go.sum, pubspec.lock) e faça uma instalação limpa em um computador novo ou container limpo para provar que funciona.

Capture o que o CI faz, passo a passo, para que possa ser copiado para outro provedor de CI se necessário:

• Instalar dependências (com lockfiles)
• Rodar testes e lint
• Gerar artefatos de build (bundle web, binário do servidor, build mobile)
• Produzir artefatos (zip, imagem Docker, release bundle)
• Guardar logs e metadados do build (versão, commit, data)

Separe configuração de build da configuração de runtime. Configuração de build muda o que é compilado (por exemplo, uma API base URL embutida no bundle web). Configuração de runtime é injetada na inicialização (como URLs de banco, chaves de API e flags de recurso). Misturar os dois é uma causa comum de “funciona no CI” mas falha no deploy.

Forneça uma receita simples de verificação local. Mesmo um conjunto curto de comandos já é suficiente:

# Web
pnpm install
pnpm test
pnpm build

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

# Mobile
flutter pub get
flutter test
flutter build apk

Se você está exportando de uma plataforma como Koder.ai, inclua quaisquer arquivos de CI gerados ou presets de build usados durante o deploy para que o cliente reproduza o mesmo build fora da plataforma.

Scripts de deploy e processo de release

Um bom checklist de entrega não para em “aqui está o repositório”. Ele também explica como o app sai do código e vira um serviço em execução, e quem aperta o botão.

Comece anotando como os deploys acontecem hoje: totalmente manuais (alguém executa comandos em um servidor), acionados por CI (pipeline que builda e deploya) ou via plataforma hospedada. Inclua onde as configs ficam e quais ambientes existem (dev, staging, produção).

Torne os passos de release repetíveis. Se o processo depende de uma pessoa lembrando 12 comandos, transforme isso em scripts e registre as permissões necessárias.

O que incluir no pacote de deploy

Dê ao cliente o suficiente para implantar no primeiro dia:

• Comandos de build e run (e versões exatas de Node, Go, Flutter, etc.)
• Scripts de deploy (shell scripts, targets Makefile ou configs de pipeline)
• Acesso necessário: papéis em conta cloud, registro de container, DNS, admin do banco
• Notas de setup de ambiente: onde variáveis são definidas e como diferem por ambiente
• Nomeação de releases: tags/releases e como identificar o que está rodando

Entrem em acordo sobre expectativas de downtime. Se “zero downtime” é exigido, diga o que isso significa na prática (blue-green, rolling deploy, janela de leitura apenas para migrações). Se downtime é aceitável, defina uma janela clara.

Ativos estáticos e caches são pontos comuns de falha. Anote como os assets são gerados e servidos, quando invalidar caches e se há um CDN envolvido.

Rollback que você consegue executar de verdade

Um rollback deve ser uma receita curta e testada ligada a uma tag ou ID de release. Por exemplo: deployar a tag anterior, restaurar o snapshot do banco se necessário e invalidar caches.

Se o app foi criado no Koder.ai e depois exportado, mencione o último snapshot conhecido como bom e a versão exata da exportação para que o cliente correlacione código com uma release funcional rapidamente.

Passo a passo: verifique o build após a exportação

A verificação é o momento em que você descobre se a entrega é real. O objetivo é simples: alguém novo pega o código exportado, configura e obtém o mesmo app rodando sem adivinhações.

Antes de começar, registre o que significa “correto”: a versão do app em execução, o commit/tag atual (se houver) e uma ou duas telas ou respostas de API-chave para comparar. Se a exportação veio de uma plataforma como Koder.ai, note o timestamp do snapshot/export para provar que testou o estado mais recente.

1. Confirme que a exportação corresponde à produção: verifique o histórico de commits, notas de release ou metadados do build. Compare uma string de versão visível ou um comportamento específico (como um rótulo de UI) com o app em execução.
2. Configure variáveis de ambiente e segredos: crie a configuração do ambiente alvo (local e staging). Use o inventário de variáveis fornecido e garanta que nada esteja hard-coded no repositório.
3. Instale dependências e rode testes: faça uma instalação limpa (sem node_modules/vendedores em cache). Rode testes unitários e lint exatamente como documentado.
4. Rode migrações e inicie localmente: levante o banco, aplique migrações na ordem e inicie o app. Confirme que o app consegue ler/gravar dados básicos e que não há migrações pendentes.
5. Implemente em staging, faça smoke tests e então promova: faça o deploy usando os mesmos scripts/pipeline planejados para produção. Só promova quando o staging corresponder às expectativas.

Para smoke tests, mantenha curto e focado em risco:

• Login/logout (ou criar um usuário de teste)
• Um fluxo central ponta a ponta (criar-editar-salvar)
• Um email/webhook/pagamento de callback se aplicável
• Tratamento básico de erro (entrada inválida, registro ausente)
• Logs sem crashes repetidos ou erros relacionados a segredos

Se algo falhar, capture o comando exato, a saída de erro e as variáveis de ambiente usadas. Esse detalhe economiza horas quando a propriedade muda de mãos.

Erros comuns na entrega e como evitá-los

A forma mais rápida de transformar uma entrega em um incêndio é assumir “o código é suficiente”. Um bom checklist foca nos detalhes pequenos e chatos que decidem se o cliente consegue realmente rodar e modificar o app sem você.

Os erros que causam a maioria das dores de cabeça

A maior parte dos problemas segue alguns padrões:

• Segredos não são rotacionados, então senhas da agência, chaves de API ou tokens cloud ainda funcionam após a entrega.
• Variáveis de ambiente estão incompletas porque alguns valores existem só no CI ou no dashboard de hospedagem, não no repositório.
• Mudanças pontuais em produção são esquecidas, como um hotfix rápido, uma edição manual no BD ou uma flag configurada direto no servidor.
• Migrações de banco funcionam localmente, mas falham em produção por permissões ausentes, extensões ou ownership de schema.
• Não há plano de rollback e não há release tag (ou release note) para retornar quando o primeiro deploy der errado.

Como evitá-los (sem adicionar semanas)

Torne rotação e limpeza de acessos uma tarefa agendada, não um item “quando der tempo”. Defina uma data em que contas da agência são removidas, chaves de serviço são regeneradas e o cliente confirma que consegue implantar apenas com credenciais próprias.

Para variáveis de ambiente, faça um inventário simples em três lugares: repositório, sistema de CI e UI de hospedagem. Depois valide rodando um build limpo em uma máquina/container novo.

Para migrações, teste com o mesmo papel de banco que o deploy de produção usará. Se produção requer passos elevados (como habilitar uma extensão), documente-os e deixe claro quem é o responsável.

Um exemplo realista: após exportar um projeto de Koder.ai, o cliente faz deploy com sucesso mas jobs em background falham porque uma URL de fila estava só definida no dashboard de hospedagem. Uma auditoria rápida de variáveis teria detectado. Junte isso a uma release tag e um rollback documentado (por exemplo, “redeploy da tag v1.8.2 e restore do último snapshot”) para evitar downtime.

Checklist final, um exemplo simples e próximos passos

Se você só guardar uma página deste checklist de entrega do código-fonte, guarde esta. O objetivo é simples: um clone limpo deve rodar em uma máquina nova, com segredos novos, e um banco que possa evoluir com segurança.

Verificações rápidas (faça a partir de um clone limpo)

Execute estas verificações em um laptop que nunca viu o projeto (ou em um container/VM limpo). Essa é a forma mais rápida de achar arquivos faltantes, suposições ocultas e credenciais antigas.

• Build do zero: instale deps, rode testes (se houver) e gere um build de release sem edições manuais.
• Config funciona: defina as variáveis de ambiente documentadas e confirme que o app inicia com uma configuração nova.
• Segredos rotacionados: verifique que o app roda com as chaves novas, então revogue as antigas e confirme que nada quebra.
• Migrações rodam limpas: comece com um banco vazio, rode migrações, inicie o app e execute um fluxo básico.
• Caminho de deploy é real: execute o script de deploy ou workflow de CI uma vez e confirme que produz o mesmo output.

Um exemplo simples de entrega

Uma agência entrega um frontend React, uma API Go e um banco PostgreSQL. A equipe do cliente clona o repo, copia o .env.example para variáveis reais, e cria credenciais novas para o banco, provedor de e-mail e APIs de terceiros. Eles rodam go test (ou o comando de teste acordado), constroem o app React, aplicam migrações em uma instância Postgres limpa e iniciam ambos os serviços. Por fim, fazem o deploy usando o script documentado e confirmam que o mesmo commit pode ser rebuildado depois.

Próximos passos

Mantenha a entrega curta e com um responsável. Uma walkthrough de 30 a 60 minutos geralmente vale mais que um documento longo.

• Agende uma walkthrough e registre decisões (quem é dono dos deploys, segredos e mudanças no banco).
• Atribua um dono para o acesso de produção e um backup.
• Combine um commit hash de “aceitação final” e marque-o com tag.
• Se você construiu em Koder.ai, exporte o código-fonte e use snapshots/rollback durante o primeiro deploy feito pelo cliente para reduzir riscos.