Como transformar uma ideia em uma tarefa clara para um agente

Você abre o projeto, percebe algo que poderia funcionar melhor e escreve para o agente: “Melhore a busca”. Alguns minutos depois, recebe uma interface diferente, uma biblioteca nova e uma solução para um problema que não era exatamente o seu.

Esse desencontro começa antes do código. “Melhorar” pode significar encontrar resultados mais relevantes, diminuir o tempo de resposta, deixar o campo mais visível ou corrigir uma falha de navegação. O agente precisa escolher um caminho se você não disser qual resultado procura.

Uma tarefa clara transforma essa intenção em uma entrega que alguém consegue executar e você consegue avaliar. Neste artigo da trilha IA aplicada à rotina de desenvolvimento, vamos construir essa passagem usando um exemplo: a busca de artigos de um site. Os nomes de arquivos e comportamentos apresentados são fictícios; adapte-os ao seu projeto.

Uma ideia aponta uma direção; uma tarefa define uma chegada

Uma ideia pode continuar aberta: “Quero facilitar a descoberta de conteúdo”. Ela é útil para conversar sobre possibilidades. Uma tarefa precisa delimitar uma mudança: “Na página de artigos, permitir que o leitor filtre os títulos por um termo e compartilhe a busca pela URL”.

Essa segunda frase ainda deixa decisões pendentes, mas já permite investigar o código certo e discutir um comportamento concreto. Antes de escrever o prompt, tente completar: “Quando a pessoa fizer X, o sistema deverá fazer Y”.

Se você ainda não consegue preencher essa frase, pode delegar uma investigação. Peça ao agente que examine o fluxo atual, descreva os problemas encontrados e proponha alternativas. Informe que essa etapa deve produzir um diagnóstico, sem implementar mudanças. Assim, a primeira entrega resolve a incerteza necessária para definir a próxima.

As seis peças de uma tarefa executável

Uma tarefa pequena pode caber em um parágrafo. Uma mudança que afeta mais partes do produto merece um briefing. A estrutura abaixo é uma proposta prática para organizar o pedido; não depende de um modelo ou ferramenta específica.

1. Objetivo: descreva o resultado para quem usa

Comece pelo comportamento desejado e pelo motivo da mudança. Em vez de “adicione um input”, escreva: “Permita que o leitor encontre um artigo pelo título sem percorrer toda a listagem”. O campo de texto é uma possível parte da implementação; encontrar o artigo é o resultado.

Evite prometer efeitos que a tarefa não mede. “Aumentar o engajamento” pode ser uma intenção de produto, mas não é um critério de conclusão de uma busca sem uma métrica, um período de observação e uma referência de comparação.

2. Contexto: ofereça pistas que o agente possa conferir

Informe onde o problema aparece, como o fluxo funciona hoje e quais referências ajudam a entender o projeto. Pode ser uma rota, um componente parecido, uma captura de tela, um contrato de API ou uma sequência para reproduzir um bug.

Não é necessário colar o repositório inteiro no pedido. Aponte os lugares relevantes e permita que o agente confira suas hipóteses. Se você não sabe qual arquivo controla a busca, diga isso. Um caminho inventado torna a investigação mais confusa.

Para o nosso exemplo: “A listagem fica em /artigos. O site já tem paginação e lê os filtros da URL. Examine o fluxo existente antes de propor alterações”.

3. Escopo: diga o que esta entrega precisa abranger

Defina a menor mudança que resolve o problema atual. Nossa primeira versão pode buscar apenas no título. Busca no corpo do artigo, sugestões enquanto a pessoa digita e correção de palavras ficam para outra tarefa.

O escopo também preserva decisões existentes: manter o visual da listagem, reaproveitar os componentes do projeto e conservar os parâmetros de filtro já suportados. Essas informações evitam que um pedido localizado vire uma reforma da aplicação.

4. Restrições: registre os limites reais

Restrições úteis nascem do projeto. Exemplos: usar a infraestrutura de consulta existente; não adicionar dependências para esta mudança; manter o formato público das URLs; não modificar o schema do CMS.

Explique quando um limite pode ser discutido. “Se a solução exigir alterar o contrato da API, apresente o motivo e o impacto antes de implementar” oferece um caminho para lidar com um impedimento sem autorizar uma mudança silenciosa.

5. Critérios de aceite: transforme adjetivos em comportamentos

“Intuitivo”, “robusto” e “bem feito” são difíceis de verificar sozinhos. Troque essas palavras por situações observáveis. Ao enviar um termo, quais resultados aparecem? O que acontece quando nenhum artigo corresponde? E quando o campo fica vazio?

Escolha critérios que expressem decisões do produto, sem prescrever cada função interna. Buscar sem diferenciar maiúsculas de minúsculas é uma decisão de comportamento. Escolher o nome de uma variável costuma ser uma decisão que o agente pode tomar.

6. Validação e entrega: combine como a conclusão será demonstrada

Informe as verificações relevantes e o que você espera receber ao final: resumo da mudança, arquivos alterados, critérios atendidos, verificações executadas e limitações encontradas.

Uma execução de build ajuda a identificar problemas de compilação, mas não demonstra, sozinha, que uma URL compartilhada reproduz a busca. Para esse requisito, é preciso conferir o fluxo correspondente. A documentação do Claude Code recomenda oferecer uma forma concreta de verificar o trabalho, como testes ou comparação visual. Boas práticas do Claude Code.

Exemplo completo: de “melhore a busca” a uma tarefa clara

Vamos assumir que a página de artigos já possui categorias e paginação, mas ainda não permite filtrar os títulos. A busca será enviada por um formulário, sem consultas a cada tecla. Essa decisão reduz a quantidade de comportamentos que precisamos definir nesta primeira entrega.

O pedido que deixa decisões demais em aberto

Melhore a busca dos artigos e deixe a experiência mais moderna.

O agente não sabe se há um defeito para corrigir, quais campos pesquisar, se deve mudar o visual ou como você avaliará a entrega. Ele pode apresentar algo coerente com essa frase e ainda assim frustrar sua expectativa.

O pedido pronto para execução

## Objetivo
Permitir que o leitor encontre artigos pelo título na página /artigos
e compartilhe uma URL que reproduza a busca.

## Contexto
A página já tem filtro de categoria e paginação.
Examine o fluxo atual de consulta, URLs e componentes antes de editar.
Use o padrão visual e a infraestrutura de dados existentes.

## Escopo
Adicionar um formulário de busca com campo rotulado e botão de envio.
Nesta entrega, pesquisar somente no título.
Manter a categoria selecionada ao enviar ou limpar a busca.
Não incluir sugestões, busca no corpo ou uma reformulação visual.

## Comportamentos e critérios de aceite
1. Ao enviar o formulário, registrar o termo no parâmetro q da URL.
2. Encontrar títulos que contenham o termo completo, sem diferenciar
   maiúsculas de minúsculas. Acentos continuam significativos.
3. Remover espaços no início e no fim do termo antes de consultar.
4. Ao iniciar outra busca, voltar à primeira página de resultados.
5. Aplicar busca e categoria em conjunto; manter o termo na paginação.
6. Ao abrir uma URL com q, preencher o campo e exibir seus resultados.
7. Ao limpar a busca, remover q e voltar à primeira página,
   preservando a categoria.
8. Para termo vazio ou só com espaços, exibir a listagem sem busca.
9. Sem correspondências, mostrar uma mensagem e uma ação para limpar.
10. Em falha de consulta, mostrar um estado de erro distinto
    do estado sem resultados.
11. Permitir envio por Enter e uso do formulário por teclado,
    com rótulo acessível e foco visível.

## Limites
Não adicionar dependências, modificar o schema do CMS ou alterar
o comportamento público dos outros filtros.
Se o contrato atual impedir algum critério, explique o impedimento
e proponha uma alternativa antes de alterar esse contrato.

## Validação
Confira os casos acima, incluindo URL compartilhada, categoria,
paginação, termo vazio, ausência de resultados e erro de consulta.
Execute os checks exigidos pelo projeto para os arquivos alterados.
Adicione ou ajuste testes relevantes para a lógica modificada,
conforme a estrutura de testes existente.
Se não puder executar uma verificação, informe qual e por quê.

## Entrega
Implemente a mudança e apresente um resumo com arquivos alterados,
verificações e resultados, além de eventuais limitações.
Não faça deploy nem publique alterações nesta tarefa.

Esse briefing não exige que o agente adivinhe como a busca deve funcionar. Ele ainda tem liberdade para escolher uma implementação adequada ao repositório, mas a chegada está definida.

Repare na decisão sobre acentos. Poderíamos escolher uma busca que tratasse “programacao” e “programação” como equivalentes. Isso acrescentaria um requisito que a infraestrutura precisaria suportar. O importante é decidir conscientemente e escrever o comportamento esperado.

Como revisar os critérios antes de delegar

Leia o pedido como se você fosse avaliar a entrega amanhã. Para cada critério, pergunte: “Que ação eu faria e que resultado deveria observar?”. Se a resposta continuar vaga, o requisito precisa de outra frase.

Também procure contradições. “Não mudar a URL” e “permitir compartilhar os filtros pela URL” podem entrar em conflito se esse suporte ainda não existe. Resolver isso antes da execução economiza uma rodada de trabalho.

Quando dividir a ideia em mais de uma tarefa

Se o pedido envolve redesenhar a página, trocar o mecanismo de busca, migrar dados e criar métricas, há várias decisões e entregas misturadas. Divida o trabalho em partes que tenham um resultado próprio e uma forma de verificação.

1. Investigar a consulta atual e confirmar quais comportamentos ela suporta.
2. Implementar a busca por título com URL e estados definidos.
3. Avaliar a relevância dos resultados com exemplos reais e decidir a próxima melhoria.

Cada etapa deve deixar contexto suficiente para a próxima. O diagnóstico pode registrar os arquivos relevantes e limitações encontradas; a implementação pode documentar o comportamento adotado. Evite separar tão pouco que tudo continue num pedido enorme, ou tanto que nenhuma tarefa produza algo útil.

Autonomia funciona melhor com decisões explícitas

Você não precisa escolher cada linha de código para orientar um agente. Precisa dizer quais decisões ele pode tomar e quais consequências merecem voltar para você.

No exemplo, o agente pode reutilizar componentes, organizar a lógica e corrigir falhas introduzidas pela própria mudança. Uma alteração de contrato, uma dependência nova ou uma ampliação da busca pede outra discussão, porque ultrapassa o combinado.

Essa distinção também vale para o destino do trabalho. “Implemente localmente”, “abra uma proposta de alteração” e “publique em produção” são entregas diferentes. Escreva a que você quer. Disponibilidade de uma ferramenta não significa autorização para qualquer ação que ela permita.

Quando você ainda não sabe o que pedir

Uma dúvida legítima pode ser o ponto de partida. Em vez de inventar uma especificação para parecer preparado, transforme a dúvida na tarefa inicial:

Quero facilitar a descoberta de artigos, mas ainda não sei se o
problema está na busca, nos filtros ou na organização da página.

Examine o fluxo atual e os componentes relevantes. Não edite arquivos
nesta etapa. Descreva os comportamentos observados, separe fatos de
hipóteses e proponha até três melhorias, com impacto e limitações.

Ao final, recomende uma primeira entrega pequena e liste as decisões
de produto que preciso responder para autorizar a implementação.

Essa investigação tem objetivo, escopo e formato de entrega. Ela é uma tarefa clara mesmo sem pedir código. A documentação do GitHub também orienta a fornecer descrições bem delimitadas para tarefas delegadas ao agente. Boas práticas para tarefas com o agente do GitHub Copilot.

Um modelo para usar no próximo pedido

Use os campos abaixo como perguntas, não como burocracia. Remova o que não se aplica. Para corrigir um texto, o trecho, a redação desejada e o local podem ser suficientes. Para mudar um fluxo com dados e navegação, vale detalhar os cenários.

## Resultado esperado
Quem será beneficiado? O que deverá conseguir fazer?

## Contexto
Onde acontece? Como funciona hoje? Quais arquivos, exemplos,
documentos ou passos de reprodução ajudam a entender?

## Escopo e limites
O que faz parte desta entrega? O que fica para depois?
Quais padrões e contratos precisam ser preservados?

## Critérios de aceite
- Dada uma situação, quando ocorrer uma ação, qual resultado espero?
- Quais estados vazios, erros e limites são relevantes?

## Autonomia
Quais decisões o agente pode tomar?
Que descoberta exige esclarecimento antes de continuar?

## Validação e entrega
Como conferir os critérios? Quais checks do projeto se aplicam?
Que evidências e artefatos devem acompanhar o resultado?
A entrega termina localmente, numa proposta ou em produção?

Antes de apertar Enter

Faça uma última leitura. O agente consegue identificar o problema, encontrar o contexto, entender os limites e verificar o resultado? Você conseguirá reconhecer uma entrega correta sem depender de “parece bom”?

Se alguma resposta for não, ajuste o pedido ou comece por uma investigação. Clareza não exige prever tudo. Exige tornar visível o que você já decidiu e nomear o que ainda precisa descobrir.

Na próxima ideia que surgir durante o desenvolvimento, reserve alguns minutos para escrever o comportamento esperado e os casos que demonstram que ele funciona. Esse pequeno briefing vira uma referência durante a execução, a revisão e a conversa sobre o que vem depois.