Como transformar um protótipo em tarefas pequenas de implementação

Tens uma primeira versão da aplicação. Os ecrãs parecem próximos do que imaginaste, mas um botão só muda de cor, os dados desaparecem quando atualizas a página e ainda não sabes o que acontece quando algo falha. «Acaba a aplicação» é um pedido demasiado aberto para orientar bem o passo seguinte.

Vamos usar um exemplo editorial: um gestor de pedidos internos. Uma pessoa cria um pedido, acompanha-o e vê o estado atualizado por quem tem essa responsabilidade. A aplicação é fictícia. O objetivo deste guia é mostrar como passas de uma demonstração visual para uma sequência de trabalho que consegues verificar.

O que deves observar no protótipo antes de criar tarefas?

Percorre a aplicação como utilizador e regista o que já funciona, o que está simulado e o que ainda não existe. Testa ações concretas, incluindo atualizar a página e voltar a abrir um registo. Uma captura mostra o aspeto do ecrã, mas não confirma persistência, permissões ou ligação aos serviços necessários.

No exemplo, começa por criar um pedido fictício. Confirma se recebe um identificador e se aparece na lista. Fecha o detalhe e volta a abri-lo. Depois atualiza a página. Se o pedido desaparecer, já tens uma diferença observável entre o que esperavas e o que aconteceu.

Regista essa diferença com precisão: «O pedido aparece durante a sessão, mas desaparece após atualizar.» Evita concluir imediatamente que falta uma base de dados. O projeto pode já ter armazenamento configurado e estar a usar dados de demonstração naquela vista. A investigação do código deve confirmar a causa antes de escolher a solução.

Se ainda estás a definir o problema que a aplicação resolve, começa pelo guia sobre como preparar o briefing de uma aplicação que vais construir com IA. Aqui partimos de uma versão existente e procuramos a próxima melhoria concreta.

Como descreves o percurso completo que falta construir?

Escreve a sequência desde a intenção do utilizador até ao resultado confirmado. Inclui os dados necessários, as decisões e os estados de erro que mudam o percurso. Esse mapa permite descobrir trabalho que não aparece no desenho dos ecrãs e evita tratar cada botão como uma funcionalidade independente.

Para um pedido interno, a sequência pode ser criar, consultar e acompanhar. Quem cria precisa de saber se o pedido ficou guardado. Quem o trata precisa de encontrar o registo certo e de alterar apenas os campos permitidos. Ambas as pessoas precisam de compreender o estado atual.

Acrescenta situações que alteram o comportamento: descrição vazia, tentativa repetida, pedido inexistente ou acesso sem permissão. Não precisas de inventariar todas as possibilidades do mundo. Começa pelas que afetam a entrega definida e pelo impacto de uma falha no teu processo.

Pede ao agente que confronte esse percurso com o projeto existente: «Mostra o que já está implementado, o que usa dados fictícios e o que falta verificar. Indica os ficheiros relevantes e não proponhas substituir serviços sem explicar a necessidade.» O diagnóstico passa a ter uma referência concreta, em vez de depender de uma impressão geral sobre o protótipo.

O que torna uma tarefa suficientemente pequena?

Uma tarefa é suficientemente pequena quando tem um resultado delimitado que consegues implementar, observar e avaliar sem depender de muitas decisões novas. O tamanho não corresponde obrigatoriamente a um ficheiro ou a um ecrã. Pode atravessar várias partes do código, desde que resolva um comportamento coerente e mantenha um critério claro.

«Construir o backend» é amplo demais para acompanhar como uma única entrega. «Criar um pedido e voltar a consultá-lo com os mesmos dados» descreve um resultado. Pode exigir interface, validação, armazenamento e leitura, mas sabes o que deves testar no fim.

O extremo oposto também atrapalha. Separar cada alteração de texto, campo e função em tarefas diferentes pode criar muita gestão sem melhorar a revisão. Agrupa mudanças que só fazem sentido juntas e divide quando existem resultados, riscos ou dependências distintos.

Pergunta: consigo explicar o que fica disponível quando esta tarefa termina? Consigo verificar isso com um exemplo? As decisões essenciais estão tomadas? Se a resposta continuar a ser «depende de várias coisas», cria primeiro uma investigação delimitada ou resolve a decisão que impede especificar o comportamento.

Que informação deve ter cada tarefa de implementação?

Inclui o problema observado, o comportamento esperado, as regras aplicáveis, os limites da alteração e a forma de verificar o resultado. Liga a tarefa ao contexto e aos ficheiros relevantes, quando já os conheces. Mantém informação suficiente para executar sem transformar a descrição numa cópia de toda a conversa do projeto.

Para o nosso exemplo, uma tarefa pode chamar-se «Guardar e reabrir um pedido». A descrição explica que os dados desaparecem ao atualizar, que a solução deve respeitar o armazenamento existente e que um pedido válido precisa de continuar disponível para a conta autorizada.

Os limites devem proteger decisões reais. Não escrevas proibições extensas sobre cenários que o projeto nem contém. Se a tarefa só trata armazenamento, podes adiar a criação de notificações porque não é necessária para verificar essa entrega. Se a autorização já inclui publicação, regista-a para não reabrir a mesma decisão em cada passo.

Como escreves critérios de conclusão que o agente consegue testar?

Descreve resultados observáveis para o caso principal e para as falhas relevantes. Evita critérios como «ficar robusto» ou «funcionar bem», porque não dizem o que verificar. Associa cada resultado ao tipo de prova adequado, distinguindo comportamento, apresentação visual, dados guardados e permissões de acesso.

Um critério útil é: «Depois de criar o pedido, atualizar a página mantém o mesmo identificador, título e descrição.» Outro é: «Um título vazio produz uma mensagem compreensível e não cria um registo.» São verificações que permitem localizar uma falha, em vez de discutir se a aplicação parece pronta.

A documentação de boas práticas do Claude Code recomenda dar ao agente formas concretas de verificar o trabalho, como testes, build ou comparação visual. Escolhe a prova em função da alteração. Uma captura pode confirmar o layout; não prova que os dados ficaram guardados no servidor.

Para uma aplicação com informação privada, verifica o isolamento com contas de teste limitadas. Um botão escondido não é prova de autorização. O servidor deve impedir a operação indevida mesmo quando alguém tenta aceder diretamente ao registo. Regista o resultado e o limite do teste, sem expor dados reais ou credenciais.

Como ordenas tarefas sem bloquear todo o projeto?

Identifica as dependências que alteram a execução e começa pelo que reduz a incerteza mais importante. Distingue trabalho que exige uma decisão anterior de trabalho que apenas preferes fazer depois. Mantém uma sequência compreensível e evita abrir várias alterações sobre a mesma parte do projeto sem necessidade.

No gestor de pedidos, definir quem pode criar, consultar e alterar estados precede uma implementação segura dessas ações. Já o texto de uma mensagem vazia pode ser revisto sem esperar por todas as integrações. Nem tudo precisa de estar concluído para começares uma parte útil.

Uma tarefa de investigação deve terminar com uma decisão ou evidência. «Confirmar se a API existente permite atualizar o estado e testar essa operação num ambiente autorizado» é mais útil do que «investigar integrações». Se a operação não existir, a descoberta muda o plano antes de investires numa interface que depende dela.

Se usas GitHub, podes representar bloqueios com dependências entre issues. A ferramenta mostra a relação, mas és tu que tens de justificar por que uma tarefa depende da outra. Acrescentar setas ao plano não resolve uma decisão em falta.

Como entregas uma tarefa ao Claude Code sem perder contexto?

Aponta para a descrição da tarefa, para as decisões do projeto e para a versão atual que deve ser alterada. Explica o resultado e os limites da execução, deixando o agente inspecionar a implementação existente. Pede evidência do que mudou e dos testes relevantes, em vez de uma declaração genérica de sucesso.

Podes usar este pedido: «Implementa a tarefa de guardar e reabrir um pedido. Lê primeiro as regras de acesso e o fluxo atual. Preserva o layout e o armazenamento escolhidos. Confirma os critérios descritos com dados fictícios e regista o que ficou verificado, o que falhou e qualquer dependência que não conseguiste resolver.»

Se o plano ainda contém uma dúvida essencial, pede uma proposta concreta antes da alteração dependente. As restantes verificações podem continuar. Evita parar todo o trabalho por uma preferência visual pequena, mas também não deixes o agente inventar uma regra de negócio só para concluir a tarefa.

O guia sobre como criar instruções de projeto que um agente consegue seguir ajuda a guardar as regras duradouras. A tarefa contém o objetivo daquela alteração; as instruções do projeto conservam as decisões que se aplicam a várias tarefas. Atualiza ambos quando houver uma correção relevante, sem duplicar a conversa inteira.

Onde guardas o plano e como acompanhas o estado?

Usa um local que a equipa e o agente consigam consultar, com descrições, dependências e evidência de conclusão. Mantém estados que representem o trabalho real e distingue implementação, revisão e publicação. O plano deve permitir retomar a próxima tarefa sem depender da memória de uma conversa longa.

Uma lista num documento pode chegar para um projeto pequeno. Se já trabalhas no GitHub, as issues permitem acompanhar pedidos e problemas. Para uma funcionalidade maior, as sub-issues relacionam tarefas com um item principal. Não precisas de mudar de ferramenta só para reproduzir o exemplo.

Regista na tarefa concluída a versão alterada, a verificação executada e as limitações que importam para a seguinte. «Testado localmente com dois pedidos fictícios» descreve uma evidência concreta. «Tudo feito» não permite saber se houve teste no domínio publicado ou se falta configurar um serviço.

Quando retomas o trabalho, compara o registo com o estado atual do projeto. Outra alteração pode ter mudado o comportamento desde a última revisão. Usa os documentos para orientar a leitura, sem tratar um estado antigo como prova de que a aplicação continua igual.

Como revês uma entrega e dás feedback útil?

Executa o percurso definido na tarefa e compara o resultado com os critérios aceites. Quando houver diferença, descreve entrada, passos, resultado observado e resultado esperado. Se surgir uma nova ideia, identifica-a como alteração de âmbito, para não confundir uma funcionalidade adicional com um defeito da entrega original.

No exemplo, se o pedido fica guardado mas abre com o título de outro registo, tens um erro de comportamento para corrigir. Se entretanto decides acrescentar anexos, tens um novo pedido. As duas situações podem ser importantes, mas exigem descrições e avaliações diferentes.

O feedback pode ser: «Criei o pedido A, abri o pedido B e voltei ao A. O detalhe continuou a mostrar o título de B. Esperava ver os dados associados ao identificador de A.» O agente recebe um caso reproduzível e pode procurar a causa no estado, na consulta ou no mapeamento.

Depois da correção, repete o caso afetado e os percursos relacionados que possam ter mudado. Não é necessário repetir verificações sem ligação à alteração só para aumentar a lista. O artigo sobre como começar um projeto com Claude Code sem perder o controlo aprofunda esta forma de observar, corrigir e validar.

Quando podes considerar a funcionalidade pronta para usar?

Confirma o percurso completo na versão que vai ser utilizada, com as integrações e permissões necessárias. Revê também os estados vazios e de falha, a forma de recuperar erros e as condições de publicação. Tarefas individuais concluídas ajudam a acompanhar o trabalho, mas não substituem a verificação conjunta da funcionalidade.

No gestor de pedidos, percorre criação, consulta e mudança de estado. Confirma que cada pessoa vê e executa apenas o que lhe compete. Se uma etapa ainda usa dados simulados, identifica-a. A existência de vários testes locais não transforma uma integração ausente numa capacidade operacional.

Guarda a versão do código e prepara a recuperação adequada ao projeto. Reverter ficheiros não desfaz necessariamente dados alterados ou mensagens enviadas. Se a publicação inclui mudanças desse tipo, o plano precisa de tratar esses efeitos com o mesmo cuidado que dedica ao código.

Por fim, confirma o endereço e a versão publicados quando essa fase está autorizada. Um commit guardado e um deploy concluído são estados distintos. A entrega fica mais clara quando consegues mostrar o comportamento a funcionar e explicar o que foi verificado, sem confundir a demonstração inicial com a aplicação que já podes usar.

Como podes aprender isto no Laboratório da IA?

No Laboratório da IA podes aprender a planear, construir e rever projetos com Claude Code e outros agentes. Tens aulas semanais, gravações e materiais para praticar. Nos Zooms de acompanhamento semanais podes trazer o protótipo, uma tarefa concreta e os comportamentos que ainda não correspondem ao que precisas.

Começa por um percurso pequeno e descreve a prova que demonstrará a sua conclusão. Essa prática ajuda-te a dar instruções mais claras, a avaliar o que o agente entrega e a continuar o projeto com decisões registadas. O objetivo é conseguires conduzir a construção, mesmo quando não escreves o código.