Como preparar o briefing de uma aplicação que vais construir com IA

Pedir «faz uma aplicação para gerir o meu negócio» deixa demasiadas decisões por tomar. A IA pode construir ecrãs e botões que parecem plausíveis, mas continua sem saber qual é a dificuldade que queres resolver. Se essa dúvida só aparecer depois da implementação, vais ter de rever trabalho que podia ter sido evitado.

O briefing serve para tornar essas decisões explícitas. Não precisa de ser um documento extenso nem de usar linguagem técnica. Precisa de permitir que tu, outra pessoa da equipa e o agente entendam o mesmo resultado, consigam reconhecer o que falta e tenham uma forma de avaliar a primeira versão.

Começa pelo trabalho que queres melhorar

Descreve uma tarefa concreta que hoje exige esforço, cria atrasos ou dificulta uma decisão. Identifica quem a executa, como começa e o que considera concluído. Antes de pedir uma aplicação, verifica se consegues eliminar ou simplificar parte do processo. O projeto deve responder a uma necessidade observável e suficientemente delimitada para poderes testar a solução.

Vamos usar um exemplo fictício ao longo deste guia: uma pequena empresa de serviços recebe pedidos de orçamento por um formulário que já existe. Os pedidos chegam a uma caixa de email e alguém copia os dados para uma folha. A equipa perde tempo a descobrir quem está a tratar cada pedido e quais continuam sem resposta.

O problema inicial pode ser descrito assim: «A equipa comercial precisa de consultar os pedidos recebidos, atribuir um responsável e acompanhar o estado de resposta.» Esta frase já delimita um utilizador, uma tarefa e um resultado. Ainda não obriga a criar um CRM completo, um sistema de faturação ou um novo formulário público.

Acrescenta um exemplo do que acontece hoje. Um pedido entra de manhã, duas pessoas começam a preparar a resposta e só à tarde percebem que estavam a trabalhar no mesmo caso. Usa dados fictícios para explicar o percurso, conservando as regras reais que a aplicação precisa de respeitar.

Depois pergunta o que faria esse problema deixar de existir. Talvez baste mostrar quem assumiu o pedido e impedir que duas pessoas o assumam sem aviso. Essa definição é mais útil para a primeira versão do que uma lista de funcionalidades recolhida de várias aplicações que viste na internet.

Identifica quem usa e o que cada pessoa pode fazer

Define os tipos de utilizador pelas suas tarefas e permissões, com exemplos de ações permitidas e recusadas. Uma pessoa pode consultar os próprios pedidos, outra distribuir trabalho e outra configurar o sistema. Escreve essas diferenças no briefing antes de desenhares menus, porque a organização visual não determina quem pode realmente aceder aos dados.

No exemplo, podes começar com dois perfis: membro da equipa comercial e responsável comercial. O primeiro consulta e atualiza os pedidos que lhe foram atribuídos. O segundo distribui pedidos e consulta o conjunto da equipa. Se todos precisam de ver todos os pedidos, escreve essa regra e o motivo, em vez de assumir que a separação é obrigatória.

As permissões devem corresponder ao funcionamento pretendido. Um cargo hierárquico não explica, por si só, que operações a pessoa precisa de executar. Especifica se pode mudar o responsável, reabrir um pedido, exportar informação ou apagar um registo. São ações diferentes, mesmo quando aparecem no mesmo ecrã.

Inclui um caso de recusa. Por exemplo: «Uma pessoa sem acesso a este pedido não o consegue obter através de uma ligação direta.» Este critério obriga a verificar o comportamento para além do botão visível. A aplicação não deve confiar numa decisão de acesso enviada pelo navegador.

Não acrescentes contas de clientes só porque muitas aplicações as têm. Se o projeto serve apenas uma equipa interna, essa é a audiência inicial. Uma área de cliente acrescenta decisões sobre acesso, informação disponível e suporte que podem não contribuir para o problema que escolheste resolver.

Descreve o percurso completo antes de pedir ecrãs

Escreve o que desencadeia o trabalho, as ações que o utilizador realiza e o resultado que encontra no fim. Inclui a origem e o destino de cada passagem importante. Este percurso permite descobrir dependências e perguntas em falta antes de a IA criar uma interface que pressupõe serviços ou comportamentos que nunca pediste.

Para a empresa fictícia, o percurso pode começar com a entrada de um pedido na fonte existente. A aplicação apresenta esse pedido como «novo», o responsável atribui-o a uma pessoa e essa pessoa atualiza o estado depois de preparar a resposta. O ponto de conclusão precisa de ficar claro: resposta preparada, enviada ou orçamento aceite são momentos distintos.

Se a primeira versão não envia emails, escreve isso. Pode guardar o estado «resposta enviada» depois de uma confirmação manual, mas não deve mostrar esse estado como consequência de um envio que não executou. A forma de confirmar a ação tem de corresponder à realidade do processo.

Pensa também no que acontece quando faltam dados. Um pedido sem telefone deve poder ser recebido se o formulário não exigir esse campo. Um pedido sem forma de contacto pode precisar de um estado de revisão. A aplicação deve tornar essa situação compreensível, sem fabricar dados para completar a ficha.

Só depois passa aos ecrãs. A lista de pedidos, a ficha de um pedido e a distribuição de trabalho surgem como respostas ao percurso. Se um ecrã não ajuda nenhuma ação descrita, pergunta se é necessário na versão inicial. Essa revisão costuma ser mais simples antes de existir código e uma expectativa de manter tudo o que foi gerado.

Diz de onde vêm os dados e qual é a fonte válida

Identifica a origem, os campos necessários e a regra de atualização dos dados. Distingue informação importada, calculada e introduzida pela equipa. Indica qual o sistema que prevalece quando existem versões diferentes. Sem esta definição, a IA pode criar uma base de dados nova que duplica trabalho ou perde a ligação ao processo que já tens.

No exemplo, o formulário atual continua a recolher pedidos. O briefing deve indicar que o novo projeto aproveita essa entrada e explicar como pretende recebê-la: integração documentada, exportação de ficheiro ou outro percurso confirmado. A existência de uma API não garante que a operação necessária esteja disponível na tua conta.

Cria uma pequena amostra de dados fictícios com os mesmos campos e formatos que esperas receber. Inclui um pedido completo, outro com informação opcional em falta e um terceiro com um valor que precisa de revisão. Uma amostra só com registos perfeitos não revela como o projeto deve tratar os casos reais mais frequentes.

Define a identidade do pedido. O email de uma pessoa pode aparecer em vários pedidos e o nome pode repetir-se, por isso nenhum desses campos identifica necessariamente o registo. Conserva um identificador estável que permita reconhecer uma nova entrada e distinguir uma atualização de uma duplicação.

Esclarece que alterações regressam ao sistema de origem. Talvez a aplicação apenas leia os pedidos e mantenha internamente responsável e estado. Nesse caso, não deve alterar o formulário nem escrever noutro sistema por iniciativa própria. Esta separação torna o briefing mais concreto e reduz dependências que a primeira versão não precisa de ter.

Escolhe o que entra na primeira versão

Inclui apenas o necessário para executar e avaliar o percurso escolhido, conservando as outras ideias numa lista separada. Uma primeira versão deve permitir trabalho completo dentro de um âmbito pequeno. Define também o que fica por confirmar, para que uma dúvida não seja interpretada como autorização para acrescentar uma funcionalidade ou contratar um serviço.

Na aplicação de pedidos, o essencial pode ser receber os registos, consultar a lista, atribuir responsável, atualizar estado e encontrar pedidos pendentes. Um painel com gráficos, notificações em vários canais e geração automática de propostas pode ficar para depois. Não existe vantagem em implementar essas extensões antes de saberes se a equipa usa o percurso principal.

Se surgir uma ideia útil durante o trabalho, regista-a e pergunta que problema resolve. Pode justificar uma alteração imediata se desbloquear o percurso inicial. Se acrescentar uma capacidade independente, guarda-a para outra fase com um objetivo próprio. Assim consegues evoluir sem perder o critério de conclusão da versão atual.

Os Issues do GitHub permitem organizar tarefas, problemas e ideias. Podes usar essa estrutura para separar o trabalho da versão atual das melhorias futuras. Uma lista num documento também serve, desde que continue atual e seja consultada durante a implementação.

Acrescenta uma condição para voltar a avaliar cada melhoria. Por exemplo: rever notificações depois de observar como a equipa acompanha pedidos durante o piloto. Isso liga a decisão a uma necessidade que podes observar, em vez de acumular funcionalidades porque parecem interessantes numa demonstração.

Escreve critérios que permitem confirmar o resultado

Traduz cada função importante num comportamento observável, indicando a situação inicial, a ação e o resultado esperado. Inclui casos incompletos, repetidos e sem permissão quando forem relevantes. Estes critérios ajudam a orientar a implementação e permitem verificar se a aplicação cumpre o pedido, em vez de aprovar apenas o aspeto dos ecrãs.

Para atribuir um pedido, o critério pode ser: «Quando o responsável escolhe uma pessoa da equipa, o pedido passa a mostrar essa pessoa e continua atribuído depois de atualizar a página.» Esta frase distingue uma alteração visual temporária de um resultado guardado. Também permite testar o comportamento sem conhecer o código que o produz.

Para a entrada de dados, podes definir: «Quando o mesmo pedido chega novamente com o mesmo identificador, a aplicação não cria um segundo pedido.» Acrescenta o comportamento esperado para uma atualização legítima, se a origem a puder enviar. Ignorar todas as repetições pode impedir a atualização de informação que realmente mudou.

Inclui a experiência perante uma falha. Se a origem não estiver disponível, o utilizador deve perceber que a lista pode estar desatualizada e ter uma forma de voltar a tentar. Mostrar uma lista vazia sem contexto pode levar a equipa a concluir que não existem pedidos.

Nas boas práticas oficiais do Claude Code, a Anthropic recomenda dar ao agente formas concretas de verificar o trabalho e explorar o projeto antes de implementar. No teu briefing, podes traduzir essa orientação em exemplos de entrada, resultados esperados e percursos que têm de continuar a funcionar depois de cada alteração.

Explica as restrições e o que já está decidido

Regista as ferramentas existentes, a identidade visual, os destinos dos botões e as decisões que o projeto deve preservar. Acrescenta limites de orçamento, dados e publicação quando forem relevantes. O agente consegue tomar melhores decisões quando conhece essas condições e não precisa de substituir componentes que já resolvem uma parte do teu processo.

Se já tens um checkout, indica o endereço e diz se a aplicação deve apenas encaminhar para ele. Se a informação de clientes vive noutro sistema, explica que essa fonte continua válida. Quando a marca tem fontes, cores e imagens aprovadas, fornece os ficheiros e indica onde devem ser usados.

Uma referência visual ajuda a explicar composição e hierarquia, mas não autoriza a copiar todos os conteúdos ou funcionalidades desse site. Diz o que queres aproveitar: a clareza da lista, a disposição dos filtros ou a forma de apresentar um estado. O pedido fica mais preciso quando separas a referência visual das regras do teu negócio.

Nos custos, identifica serviços já disponíveis e o que exigiria uma decisão adicional. Não assumes que uma subscrição de chat inclui qualquer utilização por API, alojamento ou serviço externo. O briefing deve permitir aproveitar o que existe e tornar visível uma dependência que acrescenta custo antes de ela passar a fazer parte do projeto.

Se o projeto for uma página de venda, tens um percurso diferente do exemplo de pedidos. Nesse caso, o guia para escrever páginas que ajudam a comparar a tua oferta ajuda a definir a informação comercial que o briefing deve preservar e a decisão que o visitante precisa de conseguir tomar.

Define a autonomia do agente e a forma de entrega

Indica que trabalho está autorizado, em que ambiente pode ser executado e como deve ser entregue. Se a publicação já faz parte do pedido, escreve essa decisão e o endereço previsto. Se a fase atual é apenas local, torna esse limite explícito. A distinção evita tanto alterações externas inesperadas como pedidos repetidos de confirmação sobre decisões já tomadas.

Um pedido de preparação pode dizer: «Analisa a pasta e propõe o plano, sem alterar o site publicado.» Um pedido de execução pode dizer: «Implementa, testa e publica a alteração neste projeto e domínio.» São âmbitos diferentes. A ferramenta precisa de saber qual deles corresponde ao trabalho atual.

Define o que esperas receber no fim: aplicação num endereço identificado, versão do código, resultados dos testes e limitações que ficaram por resolver. «Está feito» é insuficiente quando pode significar que existe apenas uma versão no computador. A entrega deve esclarecer o que foi implementado e o que foi realmente confirmado.

Guardar versões também faz parte do processo. O GitHub flow descreve um percurso de alterações, revisão e integração que permite acompanhar a evolução do código. Usa um método adequado ao teu projeto e conserva uma referência da versão que foi publicada, para poderes relacionar uma mudança com o comportamento observado.

Não precisas de definir todos os detalhes técnicos no briefing. Podes pedir ao agente que proponha a implementação e explique escolhas que afetem manutenção, acessos ou custos. O essencial é distinguir essas propostas das decisões já fechadas e avaliar as consequências antes de as tratar como parte do produto.

Usa um modelo de briefing que consigas preencher

Organiza o briefing por objetivo, utilizadores, percurso, dados, âmbito e validação. Preenche cada parte com informação do teu processo e assinala o que ainda não sabes. Um modelo é útil quando revela lacunas concretas; deve permitir avançar com as decisões suficientes para a fase atual, sem fingir que todas as respostas já existem.

Podes começar com estes campos e adaptar a linguagem à tua equipa:

• Objetivo: que tarefa fica mais simples e para quem.
• Situação atual: como o trabalho começa, circula e termina hoje.
• Utilizadores: quem consulta, cria, altera e decide.
• Percurso principal: ações do início ao resultado utilizável.
• Dados: origens, campos, identificadores e regra de atualização.
• Primeira versão: funções indispensáveis e ideias que ficam para depois.
• Restrições: ferramentas, identidade, orçamento e decisões preservadas.
• Validação: exemplos, resultados esperados e comportamentos de recusa.
• Entrega: ambiente, endereço, versão e evidência pretendida.
• Dúvidas: decisões em falta e quem as pode esclarecer.

Depois escreve um pedido inicial que dê ao agente uma ordem de trabalho. Por exemplo: «Lê o briefing e os ficheiros existentes. Identifica contradições e perguntas que bloqueiam a primeira versão. Propõe o percurso e os critérios de validação antes de implementar. Preserva os serviços e decisões indicados.» Ajusta a última parte ao âmbito que já autorizaste.

Evita preencher o documento com adjetivos que não consegues verificar. «Rápido», «intuitivo» e «profissional» podem expressar uma intenção, mas precisam de exemplos de utilização para orientar decisões. Explica qual a tarefa, em que dispositivo será feita e que dificuldade o utilizador não deve encontrar.

Quando essas decisões estiverem claras, podes passar ao guia para começar um projeto com Claude Code. O briefing continua útil mesmo que escolhas outro agente, porque descreve o produto e os critérios de entrega, em vez de depender apenas da forma de pedir de uma ferramenta.

Revê o briefing com um caso completo

Percorre um exemplo desde a entrada até ao resultado e verifica se o documento permite explicar todas as decisões importantes. Faz o mesmo com uma exceção relevante, como dados em falta ou uma pessoa sem acesso. As perguntas que surgirem mostram onde o briefing ainda precisa de informação antes de orientar uma implementação fiável.

No exemplo de pedidos, acompanha um registo desde o formulário existente até à confirmação de resposta. Consegues dizer quem o vê, como é atribuído, quem muda o estado e onde fica guardada a informação? Se uma resposta depende de «a IA depois decide», avalia se estás perante uma escolha técnica reversível ou uma regra de negócio que deves definir.

Pede a alguém que conheça o processo para fazer a mesma leitura. Essa pessoa pode identificar uma exceção que não aparece no percurso ideal, como um pedido reaberto ou uma pessoa temporariamente ausente. Regista a necessidade e decide se entra no piloto, em vez de acrescentar automaticamente uma nova funcionalidade.

Mantém o briefing atualizado quando uma decisão mudar. O objetivo é conservar uma referência útil para continuar o projeto, não produzir um documento que fica desatualizado assim que começa o código. Uma alteração relevante deve refletir-se também nos critérios de validação e nas tarefas que dependem dela.

Como podes aprender a construir isto no Laboratório da IA?

No Laboratório da IA, as aulas de Claude Code trabalham a passagem de uma necessidade para um projeto, a preparação do contexto, a implementação e a revisão antes de publicar. Podes usar esse percurso para transformar o teu briefing num primeiro resultado e perceber as decisões que precisas de tomar durante a construção.

Este guia organiza princípios presentes nesses conteúdos e acrescenta um exemplo fictício para os aplicares. O exemplo da empresa de serviços não representa um projeto de aluno nem um resultado comercial observado. As integrações e permissões da tua aplicação precisam de ser confirmadas no teu ambiente.

Leva um processo que conheças, um briefing preenchido e uma dúvida concreta. Com aulas semanais, replay, materiais e Zooms de acompanhamento semanais, tens uma forma de continuar a aprender enquanto desenvolves o projeto. Consulta o que inclui o acesso ao Laboratório da IA e escolhe um primeiro resultado que consigas construir e verificar.