Checklist de intake do cliente para código de IA herdado

Por que as agências precisam de um intake diferente para código de IA herdado

Muitos projetos gerados por IA parecem ótimos num demo. O caminho feliz funciona, a UI parece polida e ninguém percebe as falhas até os usuários reais chegarem. Aí o app começa a falhar de maneiras que parecem aleatórias: logins ficam em loop, pagamentos expiram e dados acabam no lugar errado.

Esse desalinho é previsível. Muitos protótipos gerados por IA são montados para parecer completos antes de serem seguros ou confiáveis. Ferramentas de IA costuram telas rapidamente, mas muitas vezes pulam o trabalho chato que mantém o software funcionando em produção.

Os pontos de falha tendem a se repetir entre projetos: autenticação pela metade ou remendada, segredos no repositório ou no ambiente errado, o modelo de dados mudando semana a semana, e deploys que dependem de passos manuais que só uma pessoa lembra. Se você fizer o intake como uma construção normal (lista de features, preferências de design, prazos), perde esses riscos e herda surpresas.

Um intake forte para código de IA herdado foca menos em "o que você quer adicionar?" e mais em "o que pode quebrar na próxima semana?" Obtenha respostas claras para:

• Onde usuários reais travam hoje (não o que está no roadmap)
• Quem controla o repositório, hospedagem e contas de terceiros
• Que dados são armazenados e o que precisa ser protegido
• O que precisa funcionar para o negócio rodar (login, checkout, e-mails)
• O que já foi “consertado” e por quem

Se seu objetivo é uma janela curta de estabilização (frequentemente 48–72 horas), o primeiro trabalho é estancar a hemorragia: tornar o app confiável, fechar falhas óbvias de segurança e obter um deploy repetível. Melhorias vêm depois que o básico estiver estável.

Um cenário comum: um fundador diz "está basicamente pronto" porque o signup no demo funciona. Seu intake deve confirmar o que acontece quando 50 usuários se cadastram, senhas são redefinidas e o app é implantado do zero.

Defina o objetivo: estabilizar primeiro, depois melhorar

Ao herdar código gerado por IA, a maneira mais rápida de perder confiança é prometer novas features antes do básico funcionar. Defina um primeiro objetivo claro: estabilização. Isso dá a todos uma definição compartilhada de "pronto" para as primeiras 48–72 horas e torna sua estimativa defensável.

Defina "estabilizado" em termos simples que o cliente possa testar. Para a maioria dos apps, significa:

• Login e cadastro funcionam de ponta a ponta (incluindo redefinição de senha, se usada)
• O fluxo principal do usuário completa sem travamentos ou erros confusos
• O app é implantado da mesma forma toda vez (sem passos misteriosos)
• Os dados não estão obviamente em risco (sem chaves expostas, sem acesso admin aberto)

Então trace uma linha clara entre estabilização, rebuild e novas features.

• Estabilização estanca a hemorragia.
• Um rebuild substitui fundações instáveis.
• Novas features esperam até o produto ser confiável.

Coloque essa linguagem no seu intake para que toda a equipe (e o cliente) use as mesmas definições.

Defina limites cedo: cronograma, fronteiras de orçamento e quem toma a decisão final quando surgirem trade-offs como "consertar rápido" vs "reescrever com qualidade". Nomeie um aprovador e um substituto, e concorde tempos de resposta para não ficar bloqueado durante a janela de estabilização.

Por fim, escolha um único lugar para decisões e requisitos. Pode ser um doc curto ou um quadro de tickets, mas precisa responder três perguntas: o que o app deve fazer hoje, o que conta como defeito e o que está fora de escopo até depois da estabilização.

Perguntas rápidas de triagem do projeto (10 minutos)

Uma chamada de triagem rápida evita surpresas. O objetivo não é entender cada detalhe. É descobrir o que você está herdando, o que está quebrado agora e se uma janela de estabilização de 48–72 horas é realista.

Use estas perguntas para obter o básico rapidamente:

• Quem construiu (pessoa ou fornecedor), e qual ferramenta de IA foi usada (Lovable, Bolt, v0, Cursor, Replit, etc.)? O que mudou desde a última vez que "funcionou"?
• Onde ele roda hoje: só no laptop de alguém, em um site de staging, produção ou em nenhum lugar? Quem tem acesso?
• Quem está usando agora (se alguém) e quais são os 1–2 fluxos principais que devem funcionar (signup, checkout, booking, edições admin)?
• O que está falhando agora, em termos simples? Peça um exemplo recente que um usuário enfrentou (mensagem de erro, página em branco, dado errado).
• Há prazos ligados a um demo de vendas, piloto, milestone de funding ou revisão de compliance? O que acontece se atrasar uma semana?

Ouça contradições. Se disserem "funcionou semana passada" e também "ninguém consegue logar", você já tem uma prioridade: autenticação e acesso.

Exemplo: um cliente precisa de um demo na sexta, o app só roda localmente e o último dev “consertou” colando segredos no frontend. Isso não é sprint de features. É trabalho de estabilização: obter uma build implantável, proteger segredos e tornar o caminho do demo confiável.

Acesso e propriedade: obtenha controle antes de mexer no código

Antes de abrir um repositório ou prometer um prazo, certifique-se de que o cliente realmente pode conceder controle. Com código de IA herdado, a bagunça muitas vezes não é só o código. São contas, tokens e deploys pela metade que ninguém possui.

Comece com uma pergunta direta: onde o código está agora? Se a resposta for "no laptop de alguém" ou "em uma ferramenta como Replit" sem dono claro, trate isso como um risco real. Acesso primeiro, trabalho depois.

Acesso mínimo que você precisa

Peça estes itens desde o início para poder trabalhar com segurança e evitar surpresas depois:

• Localização do repositório e um admin verdadeiro (GitHub, GitLab ou outro host)
• Acesso de deploy (quem pode enviar para produção, se existir produção)
• Lista de ambientes (dev, staging, prod) e se algo é compartilhado
• Método de armazenamento de segredos (arquivos .env, variáveis de painel, secret manager) e quem pode rotacionar segredos
• Propriedade de domínio e e-mail (quem controla DNS e configurações de e-mail transacional)

Se o cliente não pode fornecer pelo menos um admin e um local seguro para segredos, pause. Mexer no código sem propriedade é como acabar com logins quebrados, dados perdidos ou um outage em produção.

Expectativas sobre segredos e deploys

Protótipos gerados por IA frequentemente têm chaves expostas ou senhas hardcoded. Mesmo que o app "funcione", assuma que os segredos precisam ser rotacionados.

Confirme quem pode mudar:

• Senhas de banco e chaves de API
• Configurações do provedor de auth (apps OAuth, segredos JWT)
• Variáveis de hosting e settings de build

Exemplo: você herda um protótipo Bolt que deploya de uma conta pessoal, com a senha do banco colada no código. O movimento certo é transferir o repositório, mover o deploy para um workspace da agência e rotacionar segredos antes de qualquer trabalho de feature.

Fluxos críticos para o negócio a confirmar (e o que perguntar)

Para evitar surpresas, combine os poucos fluxos que devem funcionar aconteça o que acontecer. Isso evita que você conserte a coisa errada primeiro.

Comece com identidade e permissões. "Login funciona" não é suficiente. Pergunte quem deve poder fazer o quê e onde essa regra é aplicada. Se permissões estiverem apenas escondidas na UI, um usuário às vezes pode burlar adivinhando um ID ou chamando um endpoint direto.

Pagamentos e faturamento também precisam de uma história clara para falhas. Muitos protótipos só lidam com o caminho feliz. Confirme o que deve acontecer quando um cartão falha, uma assinatura é cancelada ou um reembolso é necessário, e quem aciona essas ações.

Defina a sensibilidade dos dados cedo. Se o app toca dados pessoais, informações de saúde, dados financeiros ou dados sobre menores, suas escolhas de segurança e logging mudam desde o primeiro dia.

Mantenha as perguntas práticas:

• Auth: quais roles existem (user, admin, staff) e o que cada role pode fazer?
• Pagamentos: o que conta como "pago" e o que muda quando o pagamento falha ou é reembolsado?
• Dados: que campos são sensíveis e algum dado deve ser apagado sob solicitação?
• Integrações: o que conecta a e-mail, CRM, armazenamento de arquivos, APIs de IA ou webhooks, e o que quebra se isso cair?
• Acesso admin: existe algum painel admin “temporário”, senha compartilhada ou backdoor ainda em uso?

Exemplo: um fundador diz "apenas admins podem exportar dados de clientes." Em código herdado, essa regra às vezes é só um botão, não uma checagem de permissão.

Sinais de risco que você pode identificar na primeira chamada

Alguns problemas aparecem antes de você ver o repositório. Uma boa primeira chamada é menos sobre detalhes e mais sobre sinais: esse código roda em algum lugar, o acesso está limpo e é possível confiar no que te contam?

Fique atento a estes sinais vermelhos:

• Roda só no laptop de uma pessoa, ou eles dizem "não conseguimos mais fazer deploy". Isso muitas vezes significa setup de ambiente faltando, passos de build quebrados ou serviços não documentados.
• Segredos tratados de forma casual: chaves de API coladas em chat, tokens num doc compartilhado ou "só use esta senha admin". Assuma exposição até provar o contrário.
• Auth inconsistente: "login funciona às vezes", roles não funcionam, ou um usuário vê dados de outro.
• Bugs parecem aleatórios e somem ao atualizar a página. Isso pode apontar para estado instável, problemas de caching ou expectativas desalinhadas entre frontend e backend.
• Sem testes, sem logs e ninguém sabe o que foi alterado por último. Sem trilha de auditoria, todo conserto vira tentativa e erro.

Quando ouvir um ou mais desses, use follow-ups calmos para transformar dor vaga em escopo claro:

• "Onde está rodando hoje e quem pode reiniciá-lo se quebrar?"
• "Como os segredos são armazenados e quem tem acesso agora?"
• "Quais ações de usuário precisam funcionar toda vez para o negócio operar?"
• "Quando funcionou por último e o que aconteceu logo antes de parar?"

Exemplo: o app foi construído em Replit, o deploy quebrou semana passada e estão compartilhando uma chave Stripe no Slack. Isso é suficiente para pausar pedidos de feature e mudar para um intake focado em estabilização: controle, segurança e deploy repetível.

O que verificar quando você vê o repositório (alto nível, não técnico)

Depois que tiver acesso, você não precisa ler cada arquivo para saber se o projeto é seguro de estabilizar. Uma varredura rápida mostra se é um resgate pequeno ou um rebuild profundo.

Comece pela camada de dados, porque surpresas ali se espalham por todo lugar. Procure conceitos duplicados (por exemplo, users e app_users), campos ambíguos de "fonte da verdade" e falta de arquivos de migração. Se o repositório não explica como o banco muda ao longo do tempo, releases ficam arriscados rápido.

Então faça uma varredura básica de segurança, mesmo que você não seja especialista. Verifique se entrada de usuário é tratada com cuidado, uploads de arquivo são restritos e se algo parece aceitar SQL cru ou comandos não confiáveis. Procure segredos no repositório (chaves de API, senhas de banco). Se os ver, assuma que vazaram.

Observe também a estrutura. Protótipos de IA frequentemente copiam a mesma lógica em muitos lugares. Isso torna correções lentas e bugs fáceis de reintroduzir.

Um conjunto curto de checagens que costuma revelar os maiores riscos:

• Existe uma divisão clara entre backend e frontend ou está tudo misturado?
• Você vê a mesma lógica repetida em vários arquivos?
• Auth e permissões são tratadas num único lugar ou espalhadas?
• Há algum reporte de erro ou falha silenciosa?
• Existem básicos como backups, configs de ambiente e um caminho simples de deploy?

Por fim, identifique armadilhas de performance cedo. Se páginas dependem de muitas chamadas de API repetidas, ou o app busca os mesmos dados várias vezes, você verá carregamentos lentos e timeouts quando usuários reais chegarem.

Um plano simples de estabilização de 48–72 horas (passo a passo)

Uma janela de estabilização não é um sprint de features. O objetivo é fazer o app rodar de forma confiável, estancar a hemorragia e dar a todos uma visão clara do que será necessário para melhorar depois.

O plano em 5 passos

1. Get access, run it, and reproduce the worst failures. Colete acesso ao repositório, credenciais de hospedagem e variáveis de ambiente. Depois rode o app do mesmo jeito que os usuários. Escolha as 3 falhas principais e reproduza com notas claras.

2. Freeze scope and define "done" for stabilization. Combine que novas features aguardam. "Pronto" deve ser específico: login funciona, o fluxo principal completa e o deploy não depende de gambiarras manuais.

3. Fix the blockers first. Priorize tudo que impede usuários ou cria perigo imediato: auth quebrada, segredos expostos, páginas que travam, builds que falham e deploys que funcionam só numa máquina.

4. Add basic safeguards so it stays stable. Adicione logging simples, mensagens de erro claras e alguns smoke checks que capturem a mesma quebra novamente.

5. Hand back a short report and the next decision. Resuma o que foi consertado, o que ainda é arriscado e o que você recomenda a seguir (refatoração, hardening de segurança ou rebuild).

Erros comuns no intake que causam grandes problemas depois

A forma mais rápida de um projeto de IA herdado ir por água abaixo é tratá‑lo como uma build normal. Um cliente pode pedir novas features no primeiro dia, mas se a fundação é frágil, cada "pequena mudança" pode quebrar três outras coisas.

Erros comuns incluem:

• Prometer datas de entrega antes de ter rodado uma janela de estabilização
• Esperar dias por acesso (repositório, hosting, banco) e depois tomar decisões apressadas
• Definir sucesso como "sem bugs" em vez de uma pequena lista de fluxos de negócio
• Consertar problemas superficiais sem rotacionar segredos expostos
• Enviar mudanças em produção sem um caminho de rollback

Exemplo: um cliente pede "mais uma opção de pagamento" num protótipo. Você adiciona, pagamentos funcionam, mas uma chave vazada depois causa fraude e a agência é responsabilizada. Um intake sólido inclui um reset de segurança (rotacionar chaves, revisar auth) e um plano de rollback antes do trabalho de feature.

Checklist de intake para copiar e colar (checagens rápidas)

Use isto quando precisar confirmar o básico rápido e evitar surpresas depois. Foi desenhado para uma chamada de handover de 10–15 minutos mais um follow-up curto.

[ ] 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

Uma forma simples de definir expectativas: estabilização significa que o app para de falhar nos pontos mais importantes e buracos de segurança óbvios são fechados. Não significa que o código está bonito, rápido ou pronto para escalar.

Exemplo: se um cliente diz "checkout está quebrado", detalhe até um fluxo testável (da página do produto ao pagamento bem‑sucedido) e um dono para a conta de pagamentos. Sem isso, você pode consertar o código e ainda ficar bloqueado por falta de acesso.

Cenário de exemplo: protótipo herdado para release estável

Um cliente chega na sua agência com um protótipo Bolt que usaram para gerar interesse. O app parece bem no demo, mas usuários reais não conseguem logar. Às vezes o botão de login roda para sempre, outras vezes cria contas sem salvá‑las.

Na primeira chamada, use um intake com prioridade na estabilização. Mantenha o tom neutro: você não está julgando a construção, está descobrindo o que é preciso para torná‑la confiável.

Na prática, isso normalmente significa:

• Confirmar o 1–2 fluxos que precisam funcionar nesta semana.
• Obter acesso enquanto todos estão na chamada: repositório, hospedagem, banco, domínio, serviços de terceiros.
• Confirmar onde os segredos vivem e quem possui as contas.
• Anotar flags de risco como múltiplos provedores de auth pela metade, chaves hardcoded ou um modelo de dados instável.
• Definir a meta de 48–72 horas: estabilizar, adicionar guardrails básicos e lançar uma pequena release segura.

Em 2–3 dias, times frequentemente conseguem estabilizar login ao corrigir handling de sessão, limpar variáveis de ambiente e adicionar logging básico para que falhas fiquem visíveis. Problemas óbvios de segurança (como segredos expostos) podem ser corrigidos e a maioria das "quebras aleatórias" desaparece quando algumas partes emaranhadas são simplificadas.

O que normalmente vira proposta de rebuild: arquitetura que impede mudanças, propriedade de contas de terceiros pouco clara, ou um esquema de banco que não suporta uso real. Apresente o trade-off de forma direta: "Podemos consertar para funcionar agora, mas se quiser mudanças mais rápidas depois, um rebuild será mais barato do que reparos repetidos."

Próximos passos: tornar o intake repetível e reduzir surpresas

Trate o intake como um pequeno produto. Quando o processo é igual sempre, você gasta menos tempo correndo atrás de detalhes e mais tempo consertando o que importa.

Envie seu checklist antes do kickoff. Peça ao cliente que o devolva com acesso pronto. Se o acesso está "a caminho", o projeto já está atrasado. Uma regra simples ajuda: nenhum trabalho começa até você ver o repositório e um ambiente rodando.

Um ritmo prático é reservar uma janela curta de estabilização antes de planejar novas features. Coloque 48–72 horas no calendário para confirmar o que existe, o que está quebrado e o que é arriscado. Depois disso, você pode estimar melhorias com menos surpresas.

Escreva riscos em linguagem simples e obtenha sign-off nas prioridades. Não é sobre papelada. É para evitar confusão depois, quando um "conserto pequeno" vira um problema de segurança ou um rebuild.

Se precisar de ajuda externa para código gerado por IA herdado, FixMyMess (fixmymess.ai) faz diagnóstico e reparo de codebases, incluindo hardening de segurança, refatoração e preparação para deploy. Eles também oferecem uma auditoria de código grátis para expor problemas antes de você se comprometer com um plano.