Na emissão Sextas Ímpares #145, mostrei este processo com um caso concreto: uma aplicação de palpites para o Mundial de futebol de 2026, feita para brincar com amigos. Tem regras de pontuação, perfis públicos, um quiz e liga-se a dados externos sobre os jogos. As decisões que tomei ali servem de exemplo para qualquer ferramenta interna, seja um CRM, um painel de controlo ou uma aplicação de apoio a um evento.
Quando começamos a usar ferramentas de programação assistida, há uma tentação natural de ir logo para a consola e ver coisas a aparecer no ecrã. Mas programar sem primeiro pensar no que se quer construir costuma gerar retrabalho: percebes a meio que faltava uma regra, tens de reescrever partes inteiras e acabas a gastar mais tempo do que se tivesses parado cinco minutos antes.
Para quem quer ir além de perguntar coisas a um chatbot e começar a construir ferramentas próprias para o negócio, vale a pena olhar também para como usar a IA no negócio além do chatbot. Mas construir software interno com critério, e não só protótipos que ninguém usa, exige este passo de planeamento antes de tocar em código.
Define primeiro o funcionamento real do negócio
Antes de pensares em ecrãs ou botões, escreve com as tuas palavras o que a aplicação tem de fazer e que regras governam cada ação. Se pedires apenas "uma aplicação de gestão", o modelo vai preencher os vazios com suposições genéricas que não correspondem ao teu trabalho.
No projeto dos palpites, comecei por descrever a lógica de pontuação: se o utilizador acerta o resultado exato de um jogo, ganha seis pontos; se acerta a tendência e os golos de uma das equipas, ganha quatro; se acerta só a tendência, ganha três; se erra a tendência mas acerta os golos de uma equipa, ganha um ponto. Sem esta descrição detalhada, a ferramenta teria inventado uma lógica qualquer.
Havia ainda outras condições importantes de descrever:
- Prazos de bloqueio: as submissões fecham três horas antes do primeiro jogo de cada jornada, sem excepções;
- Mecânica de "Joker": cada participante escolhe um jogo por jornada onde os pontos ganhos contam a dobrar;
- Dados automáticos: os resultados e horários (em hora de Lisboa) vêm de uma pesquisa feita pela própria ferramenta, sem eu ter de inserir nada manualmente;
- Camadas de acesso: existe uma área de administração para gerir códigos de convite e publicar avisos, e uma área de membros mais limitada.
Se tentares resumir tudo isto numa única frase, o Claude Code vai esquecer regras ou calcular pontos de forma inconsistente. Uma forma simples de organizar as ideias é abrir um documento de texto corrido e escrever tudo o que tens em mente, em português normal, sem te preocupares com estar bem escrito. O importante é não deixar nenhuma regra de fora.
Deixa o assistente questionar a tua ideia
Depois de teres um rascunho escrito, submete-o a um modelo de conversação e pede-lhe explicitamente para encontrar falhas e perguntas que ainda não respondeste. Em vez de pedires código de imediato, usa esta fase para forçar decisões que talvez ainda não tivesses pensado. É aqui que se evitam muitas surpresas a meio do trabalho.
Na emissão, expliquei como faço estas perguntas antes de executar. Não é uma lista fechada de perguntas de uma vez só: o assistente vai fazendo blocos de cinco ou seis perguntas, tu respondes, e cada resposta pode gerar novas perguntas. Quando preparei a aplicação de apoio a uma formação presencial, este processo envolveu várias centenas de perguntas ao longo de algumas horas.
Um exemplo hipotético do tipo de perguntas que podem surgir: se estivesses a planear um CRM interno, o assistente poderia perguntar-te o que acontece quando um lead fica sem resposta há mais de uma semana, ou quem tem permissão para apagar registos. São exatamente este tipo de decisões que, se ficarem por responder, aparecem como bugs mais tarde.
Quando surgir uma questão técnica para a qual não tens resposta, não adivinhes. Explica o objetivo de negócio e pede duas ou três alternativas com vantagens e desvantagens. A decisão final continua a ser tua, mas fica sustentada em algo mais do que um palpite.
Junta as respostas num ficheiro de especificação e divide em fases
Todas as respostas recolhidas devem ficar consolidadas num único documento, muitas vezes chamado SPEC.md, que passa a servir de referência permanente para as ferramentas de desenvolvimento. Isto evita que requisitos importantes se percam ao longo do trabalho e ajuda a controlar o consumo de tokens, porque reduz tentativas falhadas.
Dedico uma parte significativa do trabalho ao planeamento. Isso ajuda-me a reduzir as idas e voltas durante a construção, embora continue a precisar de testar e corrigir erros antes de publicar.
O ficheiro de especificação deve conter, no mínimo:
- Objetivo e âmbito: o que a aplicação resolve e quem são os utilizadores;
- Estrutura de dados: que informação vai ser guardada e quem pode ler ou alterar cada parte;
- Arquitetura técnica: que tecnologias e serviços externos vão ser usados;
- Plano por fases: divisão do trabalho em blocos que consigas testar separadamente.
No caso da aplicação dos palpites, o plano ficou dividido em várias fases: primeiro a autenticação com códigos de convite, depois a estrutura da base de dados, só depois a lógica de pontuação e a apresentação dos jogos. Cada fase foi testada antes de avançar para a seguinte. Pedir tudo de uma vez tende a fazer com que o modelo perca o fio à meada a meio do processo.
Dá referências visuais concretas
Se não indicares nada sobre o aspeto que queres, a ferramenta tende a usar componentes visuais genéricos, do tipo que se vê em muitos projetos feitos com IA. Para evitar isso, mostra referências visuais concretas e pede que sejam analisadas e traduzidas em regras de estilo antes de começar a construir.
No projeto dos palpites, usei uma aplicação de resultados desportivos conhecida como referência. Em vez de tirar capturas de ecrã ao acaso, pedi ao assistente para inspecionar essa página e documentar os parâmetros de design num ficheiro próprio: paleta de cores, tipo de cantos usados nos cartões, hierarquia entre informação secundária e principal, e comportamento em telemóvel.
Esse trabalho foi depois convertido em regras de CSS que guiaram a construção dos componentes desde o início, sem ser preciso reescrever estilos a meio do processo. Vale sempre a pena ter presente que elementos como logótipos ou marcas registadas de organizações desportivas não devem ser copiados; o objetivo é inspirar-se na estrutura visual, não replicar propriedade de terceiros.
Constrói com um papel de construtor e outro de auditor
Ter dois modelos diferentes a editar o mesmo código em simultâneo tende a gerar conflitos e perda de trabalho. Uma forma mais estável de trabalhar é separar claramente os papéis: um assistente executa e programa, o outro lê o código e aponta problemas, sem autorização para o alterar.
No fluxo que descrevi na emissão, uso o Claude Code como construtor principal e abro uma segunda instância, com o Codex, só para auditar o que já existe. A instrução ao auditor tem de ser explícita: não pode editar nada em disco, só ler os ficheiros de contexto do projeto e devolver um relatório com sugestões ou problemas encontrados. Depois sou eu que decido o que passar ao construtor para aplicar.
Durante a sessão em live mostrei este fluxo a funcionar: pedi ao Codex sugestões de gamificação com base na estrutura existente, como distintivos de perfil para quem acertasse vários resultados seguidos. Surgiu também um pequeno problema, um vídeo do YouTube que não carregava por causa de uma política de segurança de conteúdo; ao passar a mensagem de erro exata ao Claude Code, este identificou a causa e corrigiu a configuração.
Protege credenciais antes de publicar
Colocar uma aplicação online sem verificar a segurança é um dos erros com consequências mais graves. Há sistemas automáticos que varrem repositórios públicos constantemente à procura de chaves de API expostas, e o facto de um repositório ter sido "só público por uns minutos" não elimina esse risco.
Antes de publicar, vale a pena confirmar:
- que o ficheiro .gitignore está a excluir ficheiros com chaves e variáveis de ambiente;
- que existem regras de permissão ao nível da base de dados, para que nenhum participante veja ou altere dados de outros fora do que é permitido;
- que os campos preenchidos por utilizadores são validados antes de serem guardados;
- que existem limites de consumo definidos nas contas de serviços externos, para evitar custos inesperados em caso de uso indevido.
Se uma chave de acesso ficou exposta, torná-la privada depois não resolve a exposição anterior. Revoga-a, cria uma substituta e verifica onde estava a ser usada. Trata os acessos e os segredos durante a construção, antes de colocares a aplicação na internet.
Para quem está a estruturar processos comerciais que dependem de dados fiáveis, vale a pena olhar também para como montar um funil de leads que a equipa comercial consegue trabalhar, porque a disciplina de organizar dados antes de automatizar é semelhante.
O que esperar de uma primeira versão
O planeamento deixa as decisões principais por escrito: quem usa a aplicação, que dados precisa e o que deve conseguir fazer. Quando encontrares um erro, volta a esse registo para perceber se falhou a execução ou se faltava esclarecer uma regra. Isso dá-te um ponto de partida concreto para corrigir.
Não esperes que a primeira versão de uma ferramenta interna substitua imediatamente processos já existentes na empresa. O caminho normal é ter uma base funcional, testá-la com quem vai usar no dia a dia e ir ajustando ao longo de semanas, corrigindo bugs e acrescentando funcionalidades conforme surgem necessidades reais.
Aprender a estruturar bem estes documentos de planeamento e a proteger o que constróis é uma das competências mais úteis nesta fase. No Laboratório da IA e nas minhas formações, trabalho este processo passo a passo, desde a ideia em bruto até à aplicação em produção.
Se estás a preparar um projeto interno agora, o próximo passo prático é simples: abre um documento em branco, escreve tudo o que a aplicação precisa de fazer sem te preocupares com a forma, e só depois passa isso a um assistente para te questionar antes de avançares para o código.
Como desenhar permissões por utilizador e testar acessos recusados
Desenhar permissões começa por listar quem usa a aplicação e o que cada um precisa de ver ou alterar. Depois de definires esses papéis, tens de testar diretamente se um utilizador sem permissão é mesmo bloqueado quando tenta aceder a algo que não é dele. Não basta assumir que a regra funciona porque foi escrita no pedido.
O primeiro passo é fazer uma lista simples dos papéis existentes. Numa aplicação hipotética de gestão de pedidos de clientes, podes ter três papéis: administrador, gestor de conta e cliente. O administrador vê tudo, o gestor de conta só vê os clientes que lhe foram atribuídos e o cliente só vê os seus próprios pedidos. Escrever isto numa frase por papel já ajuda a IA a construir as regras corretas desde o início.
Depois de definidos os papéis, tens de decidir onde essa permissão é aplicada. Não chega esconder um botão no ecrã. Se a regra só existir na parte visual, alguém com conhecimentos técnicos pode contornar essa barreira e aceder aos dados através de um pedido direto ao sistema. A permissão tem de ser verificada também no sítio onde os dados são guardados e entregues, não só no que aparece na tela.
No exemplo hipotético da aplicação de pedidos, isto significa que quando o gestor de conta pede a lista de pedidos, o sistema tem de filtrar automaticamente pelos clientes atribuídos a esse gestor, mesmo que ele tente pedir o pedido de outro cliente através de um link direto. Se o sistema devolver esse pedido só porque o link foi adivinhado, a permissão falhou, ainda que o ecrã normal escondesse essa opção.
Para testares isto na prática, cria contas de teste para cada papel antes de dares a aplicação como concluída. Entra com a conta de cliente e tenta abrir o pedido de outro cliente através do endereço direto, sem passar pelo menu normal. Entra com a conta de gestor de conta e tenta ver clientes que não estão atribuídos a ele. Se conseguires aceder a algo que não devias, encontraste uma falha antes de um utilizador real a encontrar por acidente ou por curiosidade.
Um critério simples para decidir se uma permissão está bem feita é perguntar: se eu copiar o endereço desta página e enviar a alguém sem essa permissão, o que acontece? A resposta correta é uma mensagem de acesso negado, não o conteúdo escondido apenas por não haver um link visível. Esta diferença é o que separa uma aplicação segura de uma aplicação que parece segura só porque ninguém tentou o caminho errado.
Quando pedires à IA para implementar estas regras, explica o resultado esperado para cada caso de acesso recusado. Em vez de dizeres apenas “só o dono pode ver o pedido”, pede que a tentativa de acesso de outro utilizador resulte numa mensagem clara e num registo do que aconteceu, para que possas confirmar depois que a regra foi respeitada. Pedir à IA uma lista dos pontos onde a permissão é verificada ajuda a confirmar que não ficou só no ecrã.
Vale a pena repetir este teste sempre que adicionares uma funcionalidade nova que toque em dados sensíveis, mesmo que a permissão já estivesse a funcionar antes. Uma alteração numa parte da aplicação pode, sem intenção, abrir um caminho novo que ignora a regra definida para outra parte. Este cuidado liga-se diretamente ao trabalho de planeamento e de revisão de segurança que descrevo antes de publicar qualquer projeto, incluindo o que mostrei nas Sextas Ímpares #145 e no trabalho que faço no Laboratório da IA e nas minhas formações.
Como organizar uma revisão de segurança sem confiar na opinião da própria IA
Uma revisão de segurança só serve se produzir uma lista de verificações concretas, feitas uma a uma, e não uma resposta genérica da IA a dizer que tudo está bem. Precisas de testar credenciais, permissões e acessos como se fosses alguém de fora a tentar entrar sem autorização.
O primeiro passo é separar o que é opinião do que é verificação. Se pedires à IA "está seguro?" e ela responder "sim, parece seguro", isso não te diz nada. Tens de pedir uma lista de pontos concretos: onde estão guardadas as credenciais, se aparecem no código ou em ficheiros que podem ficar públicos, que permissões tem cada utilizador na base de dados e o que acontece se alguém tentar aceder a um recurso que não devia.
Imagina uma aplicação interna para gerir pedidos de férias. Antes de a publicar, entra com contas de funcionários diferentes e tenta consultar pedidos de outra pessoa. Testa também as rotas diretamente e verifica onde ficam as credenciais. Um ecrã de administração escondido não demonstra que o acesso aos dados esteja protegido.
Depois de identificares essas perguntas, pede à IA para verificar cada uma isoladamente e mostrar o resultado, não uma conclusão resumida. Por exemplo, pede para listar todos os pontos do código onde se acede a dados de utilizadores e confirmar se cada um valida a identidade de quem faz o pedido. Se a resposta vier vaga, insiste em exemplos concretos do código, com o ficheiro e a linha em causa.
Um critério simples para decidir se uma verificação está completa é conseguires repetir o teste tu próprio, sem a IA. Se ela disser que as permissões da base de dados estão corretas, entra na plataforma onde a base de dados está alojada e confirma isso com os teus olhos. Se disser que as credenciais não aparecem no repositório, procura no histórico de ficheiros enviados, não só no estado atual.
Outro ponto a verificar é a separação entre informação pública e privada. Numa aplicação com área de administração, confirma que os ecrãs privados exigem autenticação antes de mostrar qualquer conteúdo, e que essa verificação acontece no servidor, não só no ecrã que o utilizador vê. Uma verificação só no lado visível pode ser contornada por alguém com conhecimentos básicos.
Também vale a pena testar o que acontece quando as coisas correm mal. O que devolve a aplicação quando alguém tenta aceder sem sessão iniciada? Aparece uma mensagem de erro que revela detalhes internos, como o tipo de base de dados ou a estrutura das tabelas? Erros demasiado detalhados podem ajudar alguém a encontrar falhas que de outra forma não veria.
Depois desta lista de verificações, faz uma segunda passagem com alguém que não tenha participado na construção, mesmo que seja informalmente. Uma pessoa de fora tende a tentar caminhos que quem construiu nem pensou em testar, precisamente porque não conhece as suposições que foram feitas durante o desenvolvimento.
Este tipo de revisão relaciona-se diretamente com o trabalho de planeamento feito antes de programar. Se as regras de permissões e acessos ficaram bem definidas no documento inicial, a revisão de segurança tem uma base clara para confirmar se foram respeitadas. Se ficaram por explicitar, a revisão acaba a descobrir decisões que deviam ter sido tomadas muito antes.
Planeia como se algo correr mal antes de publicares
Antes de colocares qualquer aplicação online, tens de decidir o que acontece quando alguma coisa falha. Isto inclui guardar cópias dos dados, saber como voltar atrás numa atualização e confirmar quem consegue agir se o sistema parar. Sem este plano, um problema pequeno pode transformar-se numa crise sem solução rápida.
Imagina, como exemplo hipotético, uma pequena empresa que usa uma aplicação interna para gerir pedidos de clientes, criada com apoio do Claude Code. Antes de publicar, alguém tem de responder a perguntas simples: onde ficam guardados os dados, com que frequência há cópias de segurança e quem tem acesso para as recuperar. Se estas respostas não existirem, a aplicação pode funcionar bem no dia a dia e falhar exatamente quando é preciso corrigir um erro grave.
O primeiro passo é definir a frequência das cópias de segurança de acordo com o ritmo do negócio. Uma aplicação que regista pedidos várias vezes por hora não pode depender de uma cópia feita uma vez por semana. Neste exemplo hipotético, faria sentido perguntar à equipa quantas horas de trabalho seriam aceitáveis perder num pior cenário, e usar essa resposta para decidir o intervalo entre cópias.
Depois de decidida a frequência, é preciso confirmar onde ficam guardadas essas cópias e quem consegue aceder a elas. Guardar tudo no mesmo sítio onde está a aplicação principal é um risco, porque um problema que afete o sistema pode afetar também a cópia. Separar o armazenamento das cópias do sistema em produção é uma decisão que deve ficar escrita no documento de planeamento, ao lado das outras regras do projeto.
A publicação em si também exige um plano de recuperação, não só de cópias. Se uma atualização introduzir um erro, a equipa precisa de saber como voltar à versão anterior sem depender de tentativa e erro no momento da crise. Isto pode ser tão simples como guardar versões anteriores do código antes de cada atualização importante, e testar previamente esse processo de reversão, para não descobrir problemas só quando já é urgente.
Outro ponto a decidir é quem é responsável por agir quando algo falha fora do horário normal de trabalho. Numa empresa pequena, isto pode ser uma única pessoa; numa equipa maior, pode ser necessário definir turnos ou pelo menos um contacto de emergência. O importante é que esta responsabilidade não fique implícita, porque em situações de stress ninguém quer perder tempo a descobrir quem deve tratar do assunto.
Vale a pena também testar o processo de recuperação antes de a aplicação estar em uso real, e não apenas confiar que vai funcionar quando for preciso. No exemplo hipotético da aplicação de gestão de pedidos, isto significaria simular a perda de dados num ambiente de testes e confirmar que a cópia de segurança consegue ser restaurada sem perdas inesperadas. Só depois desse teste é que a equipa pode confiar no plano.
Estas decisões devem ficar registadas no mesmo documento onde ficaram as regras de funcionamento e as permissões da aplicação, como referi antes. Separar o planeamento de segurança do resto do projeto aumenta o risco de ficar esquecido depois de a aplicação estar publicada e a funcionar sem problemas visíveis. É precisamente nesse período de calma que as equipas tendem a relaxar a atenção sobre cópias e recuperação.
Por fim, este cuidado não substitui a revisão de segurança que já mencionei antes, sobre credenciais, permissões na base de dados e separação entre informação pública e privada. São camadas diferentes do mesmo trabalho: uma protege contra acessos indevidos, a outra protege contra a perda ou corrupção de informação. Ambas precisam de existir antes de qualquer aplicação passar a ser usada em situações reais do negócio.