Nota do autor: este artigo é voltado a desenvolvedores que já usam Agents no trabalho. Ele mostra quais contextos, materiais de referência e critérios de aceitação verificáveis preparar antes de delegar uma tarefa, além de distinguir os pontos que ainda precisam de avaliação humana.
Depois que você começa a usar Agents, a produção realmente aumenta, mas o cansaço também. Em 3 de novembro de 2026, um desenvolvedor descreveu essa situação em uma publicação no V2EX: com uma pessoa no circuito, é preciso conferir os resultados e corrigir a qualquer momento desvios na execução e problemas de design. Assim, fica difícil realmente deixar o Agent trabalhar sozinho. A publicação menciona uma lição já conhecida: fornecer mais contexto e materiais de referência ajuda o Agent a entender a tarefa e melhorar a qualidade da entrega. Mas o post não explica o que, na prática, significa fornecer contexto “mais completo”.
Este não é mais um artigo genérico sobre como escrever bons comandos. O foco aqui é a preparação antes de delegar uma tarefa: transformar necessidades vagas em objetivos, restrições, materiais de referência e critérios de conclusão verificáveis. Assim, o Agent pode conferir o próprio trabalho, e você só precisa intervir em alguns pontos decisivos. Vale esclarecer que ainda não há dados comparativos públicos que quantifiquem os efeitos de diferentes formas de preparação. Os exemplos deste artigo resumem situações comuns; teste os resultados nas suas próprias tarefas.
O que você vai levar deste artigo: uma estrutura reutilizável para descrever tarefas a um Agent e escrever critérios de aceitação, além de orientação para decidir o que o próprio Agent pode verificar e onde uma pessoa precisa dar a palavra final.
Pontos essenciais sobre contexto e critérios de aceitação para Agentes
Antes de escrever a descrição de uma tarefa, vale entender o quadro geral: na maioria das vezes, um Agente sai do rumo porque entende de forma diferente o que deve fazer, até onde deve ir e no que não pode mexer. A tabela abaixo reúne os cinco elementos de uma boa descrição de tarefa.
| Elemento | Descrição | Problema que resolve |
|---|---|---|
| Objetivo | Explicar em uma frase o que deve ser entregue e para quem | Evita que o Agente amplie os requisitos por conta própria ou siga na direção errada |
| Contexto | Situação atual do projeto, módulos envolvidos e tentativas já feitas | Evita reinventar a roda ou descartar decisões de design existentes |
| Restrições | Arquivos que não podem ser alterados, stack obrigatória e requisitos de desempenho ou compatibilidade | Evita soluções que funcionam, mas não podem ser usadas |
| Referências | Exemplos de código existentes, documentação de interfaces e modelos de estilo | Ajuda a manter o estilo e a estrutura alinhados ao projeto |
| Critérios de aceitação | Condições de conclusão verificáveis uma a uma, de preferência de forma automática | Permite que o Agente confira o próprio trabalho e reduz a necessidade de revisão linha por linha |
Sinais comuns de que um Agente saiu do rumo
A publicação original não trouxe exemplos específicos. Aqui reunimos alguns casos comuns em Agentes de programação e execução de tarefas. Embora pareçam diferentes, a causa geralmente é a ausência de algum elemento na descrição da tarefa.
| Sinal | Causa comum | Como prevenir |
|---|---|---|
| Corrige um bug e aproveita para refatorar metade de um módulo | Objetivo pouco delimitado, sem especificar o alcance das alterações | Nas restrições, indique quais arquivos ou funções podem ser modificados |
| Introduz uma dependência que não existe no projeto | Falta de conhecimento sobre a stack existente | Liste no contexto as dependências disponíveis e as regras que proíbem novas dependências |
| O estilo do código destoa do restante do projeto | Falta de exemplos de referência | Inclua uma ou duas implementações semelhantes como referência |
| Diz que concluiu a tarefa, mas não cobre cenários importantes | Critérios de conclusão vagos | Escreva critérios de aceitação como itens de verificação executáveis |
| A solução é tecnicamente viável, mas não atende à intenção do produto | Decisões de design não foram esclarecidas de antemão | Uma pessoa toma as decisões de design antes de passar a implementação ao Agente |
O último caso merece atenção especial. O problema não é a falta de contexto: as próprias escolhas de design precisam ser feitas por uma pessoa. Vamos abordar isso separadamente mais adiante.
Como preparar uma especificação de tarefa para o Agent: estrutura em cinco partes
Reunir os cinco elementos acima em um documento resulta em uma especificação que o Agent consegue entender e usar para verificar o próprio trabalho. A recomendação é mantê-la em Markdown no repositório do projeto, por exemplo, com o nome TASK.md. Outra opção é colocar as restrições gerais em um arquivo de instruções do projeto, como AGENTS.md, e os objetivos específicos no documento de cada tarefa.
Primeira parte: como escrever o objetivo da tarefa
O objetivo deve explicar em uma frase qual é a entrega, para quem ela se destina e em que situação será usada. Uma descrição como “otimizar o módulo de login” pode levar o Agent a pensar em melhoria de desempenho, refatoração do código ou reformulação da interface. Uma forma melhor seria: “Fazer com que a API de login retorne um código de erro padronizado quando a senha estiver incorreta, para que o front-end exiba uma mensagem, sem alterar o fluxo de login bem-sucedido”.
Se a tarefa for grande, vale acrescentar abaixo do objetivo uma frase explicando o que não será feito desta vez. Exclusões explícitas costumam ser mais eficazes para evitar que o Agent amplie o escopo por conta própria.
Segunda parte: como fornecer contexto ao Agent
O importante no contexto não é a quantidade, mas a relevância. Entregar o repositório inteiro ao Agent não significa fornecer contexto suficiente: ele ainda precisa saber quais partes estão relacionadas à tarefa. Organize as informações nesta ordem:
- Módulos relevantes: liste os arquivos ou diretórios diretamente ligados à tarefa, como a lógica de login em
src/auth/e os arquivos de teste correspondentes. - Decisões já tomadas: explique por que algo foi implementado de determinada forma, por exemplo: “Os códigos de erro são definidos de forma centralizada no módulo
errors, não diretamente no código de negócio”. - Soluções já tentadas: se uma abordagem foi testada e abandonada, explique o motivo para evitar que o Agent repita o trabalho.
- Explicação de termos: esclareça termos de negócio internos que o Agent não consiga deduzir com segurança a partir do código.
Terceira parte: lista de restrições para o Agent
As restrições são essenciais para evitar resultados que “funcionam, mas não servem”. Você pode listar as mais comuns para que o Agent as confira antes de começar e depois de concluir a tarefa:
- O que pode ser modificado e quais arquivos não podem ser alterados, como scripts de migração do banco de dados e definições de interfaces públicas.
- Limitações da stack, como “não adicionar dependências de terceiros” e “usar apenas a biblioteca de logs já presente no projeto”.
- Requisitos de compatibilidade e desempenho, como “manter inalteradas as assinaturas das interfaces existentes”.
- Como lidar com situações incertas, por exemplo: “Se for necessário alterar uma interface pública, pare e explique o motivo; não faça a mudança por conta própria”.
O último item é especialmente importante. Definir claramente quando o Agent deve parar e pedir orientação dá muito menos trabalho do que descobrir depois que ele tomou decisões por conta própria.
Quarta parte: como escolher referências para o Agent
As referências ajudam o Agent a seguir práticas já existentes, em vez de criar uma solução do zero. As mais úteis costumam ser implementações semelhantes no mesmo projeto, como: “Ao criar uma interface, siga o padrão de src/user/, incluindo a validação de parâmetros e o tratamento de erros”. Para documentação externa, forneça apenas as seções relevantes para a tarefa e informe a versão, evitando que o Agent escreva código com base em uma interface antiga.
Como escrever critérios de aceitação verificáveis para um Agente
Os critérios de aceitação são a parte da descrição da tarefa em que é mais fácil ser vago — e em que mais vale a pena investir tempo. A regra é simples: se o Agente não consegue verificar por conta própria se um critério foi atendido, ele é apenas um desejo, não um critério.
| Formulação vaga | Formulação verificável | Forma de verificação |
|---|---|---|
| O código deve ter boa qualidade | Passar pela verificação de lint existente no projeto, sem novos avisos | O Agente executa o comando de verificação e informa o resultado |
| A funcionalidade deve funcionar | Adicionar testes unitários para senha incorreta, conta inexistente e login bem-sucedido; todos devem passar | Executar os testes e apresentar um resumo dos resultados |
| Não afetar outras funcionalidades | Todos os testes existentes devem passar, e nenhum arquivo proibido pelas restrições deve ser alterado | Executar todos os testes e listar os arquivos alterados |
| A documentação deve ser completa | Adicionar à documentação da API uma descrição dos códigos de erro, seguindo o formato das entradas existentes | Comparar cada item com o exemplo de referência |
| O desempenho não pode piorar | Não adicionar consultas ao banco de dados no caminho crítico | Informar no resumo como mudou a quantidade de consultas |
Depois de escrever os critérios, peça ao Agente, no fim da descrição da tarefa, que informe o status de cada um: se foi atendido, qual é a evidência e, caso não tenha sido atendido, por quê. Assim, você pode conferir a tabela de verificação sem precisar examinar todas as alterações desde o início.
Guia rápido de contexto e critérios de aceitação para Agents
A seguir, reunimos o conteúdo anterior em um processo que você pode colocar em prática imediatamente. Não é preciso usar ferramentas adicionais: um documento Markdown já basta para começar.
5 passos para preparar uma descrição de tarefa para o Agent
- Escreva os critérios de aceitação antes do objetivo: começar pelo fim ajuda você a definir como é uma tarefa concluída e evita que o objetivo fique amplo demais.
- Complete o contexto: liste apenas os módulos, as decisões já tomadas e as tentativas malsucedidas que sejam relevantes para a tarefa. Seja conciso.
- Liste as restrições e as condições de parada: deixe claro o que não pode ser alterado e em quais situações o Agent deve parar e pedir orientação.
- Escolha um ou dois exemplos de referência: priorize implementações semelhantes no próprio projeto e, no caso de documentação externa, indique apenas as seções relevantes.
- Peça um relatório estruturado: ao concluir, o Agent deve relatar o resultado de cada critério de aceitação e incluir a lista de arquivos alterados e os problemas não resolvidos.
Exemplo de instruções para um Agent (correção de mensagens de erro no login)
Este é um modelo de instruções para um cenário hipotético, apresentado em forma de lista. Basta substituir o conteúdo pelo da sua tarefa:
- Objetivo: fazer com que a API de login retorne o mesmo código de erro quando a senha estiver incorreta ou a conta não existir, para que o frontend exiba a mensagem correspondente. Não alterar o fluxo de login bem-sucedido nem o estilo da página.
- Contexto: os códigos de erro são definidos de forma centralizada no módulo
errors. Já foi feita uma tentativa de verificar o texto do erro no frontend, mas a abordagem foi abandonada por problemas com vários idiomas. - Restrições: modificar apenas
src/auth/e os testes correspondentes; não adicionar dependências; se for necessário alterar a definição de uma interface pública, parar e explicar antes de prosseguir. - Referências: o tratamento de erros da API de cadastro em
src/user/. - Critérios de aceitação: adicionar testes unitários para três cenários e garantir que todos passem; garantir que todos os testes existentes passem; não introduzir novos avisos de lint; adicionar à documentação da API a descrição de dois códigos de erro.
- Formato do relatório: conferir cada critério de aceitação, listar os arquivos alterados e explicar os problemas pendentes.
🚀 Dica para começar: você pode entregar as mesmas instruções a modelos diferentes e comparar qual respeita melhor as restrições e as condições de parada. Com uma plataforma agregadora como a APIYI, em apiyi.com, é possível alternar entre modelos de diferentes fornecedores usando a mesma interface e a mesma chave, sem precisar registrar e configurar várias contas. Assim, fica mais fácil comparar os modelos em tarefas reais.
Revisão cruzada de soluções de agentes com modelos de diferentes fornecedores
O autor da publicação original também levantou uma preocupação: modelos do mesmo fornecedor podem ter pontos cegos semelhantes. Por isso, ele gostaria que agentes de fornecedores diferentes revisassem o trabalho uns dos outros, mas, por enquanto, só consegue trocar informações por documentos Markdown ou copiando e colando conteúdo, o que exige bastante coordenação. Essa ideia pode ser combinada com o método deste artigo: a descrição da tarefa e os critérios de aceitação são a melhor base comum para a revisão cruzada. Quem revisa não precisa entender todas as suas intenções: basta questionar cada ponto com base nos mesmos critérios.
Uma abordagem mais simples é atribuir papéis diferentes aos modelos e fornecer a todos a mesma descrição da tarefa:
| Papel | Entrada | Responsabilidade | Como usar |
|---|---|---|---|
| Executor | Descrição da tarefa | Implementar a solução e verificar o próprio trabalho com base nos critérios de aceitação | Seu agente de programação habitual |
| Revisor A | Descrição da tarefa + resumo das alterações | Conferir cada critério de aceitação e apontar cenários não cobertos | Modelo de outro fornecedor, que pode ser invocado pela interface unificada da APIYI |
| Revisor B | Descrição da tarefa + resumo das alterações | Verificar especificamente se há violações das restrições e condições de parada | Modelo de um terceiro fornecedor; basta trocar o nome do modelo na mesma interface |
| Pessoa | Resumo dos pareceres | Cuidar apenas das divergências entre os revisores e das questões de design | Não se aplica |
Se você quiser escrever um pequeno script para encadear “resultado da execução → envio aos modelos revisores → consolidação dos pareceres”, poderá eliminar boa parte do trabalho manual de copiar e colar. A APIYI oferece uma interface unificada compatível com os principais SDKs: basta trocar o nome do modelo no script para invocar um modelo de outro fornecedor. Isso facilita justamente a etapa de integração, uma das mais trabalhosas ao usar agentes de fornecedores diferentes. Mas atenção: o que é automatizado é a troca de informações; a decisão final ainda deve ficar com uma pessoa.
Quais problemas o contexto do Agent resolve e quais exigem avaliação humana
Um contexto bem preparado reduz bastante a necessidade de corrigir o rumo, mas não elimina toda a intervenção humana. No post original, “desvio da tarefa” e “problemas de design” aparecem lado a lado, mas são problemas de naturezas diferentes: o primeiro geralmente resulta da falta de informação; o segundo costuma envolver decisões entre alternativas.
| Tipo de problema | O contexto resolve? | Motivo | Papel das pessoas |
|---|---|---|---|
| Alterações fora do escopo | Em geral, sim | Com restrições claras, o Agent consegue conferir o próprio trabalho | Conferir a lista de alterações por amostragem |
| Inconsistência de estilo e formatação | Em geral, sim | Exemplos de referência bastam para orientar a imitação | Verificar ocasionalmente |
| Cobertura de testes incompleta | Na maioria dos casos, sim | Basta especificar os cenários nos critérios de aceitação | Avaliar se a lista de cenários está completa |
| Decisões de arquitetura e design | Dificilmente | Exigem julgamento entre várias alternativas razoáveis | Decidir antes e registrar na descrição da tarefa |
| Intenção do produto e experiência do usuário | Dificilmente | Dependem dos objetivos de negócio e da compreensão dos usuários | Definir antes e validar depois |
| Correção dos próprios critérios de aceitação | Não | O Agent só consegue comparar o resultado com os critérios, sem questionar suas premissas | Deve ser responsabilidade humana |
É difícil deixar as decisões de design inteiramente nas mãos do Agent porque, em geral, elas não têm uma única resposta correta. Por exemplo: “Os códigos de erro devem ficar no módulo comum ou no módulo de negócio?” As duas opções funcionam. A escolha depende dos planos de expansão da equipe e de seus hábitos de manutenção — informações que muitas vezes fazem parte do julgamento das pessoas e são difíceis de registrar por completo.
Por isso, uma estratégia mais prática é antecipar a intervenção humana: tome as decisões de design antes de iniciar a tarefa e registre-as nas restrições. Assim, você não precisa acompanhar o Agent durante toda a execução. Ao final, basta conferir a lista de critérios de aceitação e os pontos de divergência entre os revisores. O papel das pessoas no ciclo deixa de ser “acompanhar cada passo” e passa a ser “definir a direção no início e validar o resultado no fim”.
Perguntas frequentes (FAQ)
Q1: O que são critérios de aceitação para um agente?
São condições que precisam ser atendidas para considerar a tarefa concluída e que podem ser verificadas uma a uma, como “todos os testes especificados passaram” ou “nenhum arquivo protegido foi alterado”. Elas permitem que o agente confira o próprio trabalho e que uma pessoa avalie rapidamente o resultado, sem precisar ler toda a saída linha por linha.
Q2: Quanto mais contexto, melhor?
Não. Informações irrelevantes podem tirar o foco da tarefa e até levar o agente a modificar partes que não deveria. Selecione o contexto de acordo com a tarefa: módulos relevantes, decisões já tomadas, tentativas que falharam e termos necessários. Se não souber se uma informação é útil, use a APIYI apiyi.com para invocar modelos diferentes e testar versões resumidas e completas da descrição da tarefa, comparando qual delas gera menos desvios.
Q3: Preciso escrever uma descrição tão completa para cada tarefa pequena?
Não. As restrições gerais e o contexto do projeto podem ficar em um arquivo de instruções do projeto para serem reutilizados. Em cada tarefa, basta acrescentar o objetivo, os materiais de referência e os critérios de aceitação. Para alterações que levam poucos minutos, uma frase com o objetivo e dois ou três critérios de aceitação costumam ser suficientes.
Q4: Para quais agentes e tipos de tarefa esse método funciona?
Ele é mais indicado para agentes de programação e agentes voltados a tarefas com entregas bem definidas, como corrigir erros, implementar interfaces, gerar documentação e organizar dados. Em tarefas muito exploratórias, cujo objetivo ainda não está definido, é difícil estabelecer critérios de aceitação de antemão. Nesses casos, é melhor que a pessoa e o agente discutam primeiro uma direção antes de começar a execução.
Q5: Como fazer uma revisão cruzada com modelos de diferentes fornecedores sem ficar copiando e colando?
Você pode criar um pequeno script para enviar o resultado da execução e a descrição da tarefa a modelos de revisão e depois reunir os pareceres. Com a interface unificada da APIYI apiyi.com, basta trocar o nome do modelo no script para invocar modelos de diferentes fornecedores, sem precisar integrar separadamente o SDK e a conta de cada um. Isso facilita a criação de um protótipo de fluxo de “execução + revisão por múltiplos modelos”.
Q6: Quais são as limitações desse método?
Primeiro, ele não substitui o julgamento de design: as escolhas de arquitetura e a intenção do produto ainda precisam ser definidas por pessoas. Além disso, se os critérios de aceitação estiverem errados, o agente seguirá fielmente esses critérios incorretos. Por fim, ainda faltam dados públicos que quantifiquem as diferenças de resultado entre as formas de preparação. Por isso, vale fazer comparações em pequena escala nas suas próprias tarefas e registrar o número de correções de rumo como referência.
Contexto e critérios de aceitação para Agents: pontos principais
- Desvios geralmente resultam de informações incompletas: a falta de objetivos, restrições ou materiais de referência pode causar retrabalho.
- Cinco elementos da descrição da tarefa: objetivo, contexto, restrições, materiais de referência e critérios de aceitação são indispensáveis.
- Critérios de aceitação precisam ser verificáveis: critérios que o Agent não consegue verificar por conta própria são apenas desejos.
- Defina condições de parada: indicar quando o Agent deve parar e perguntar poupa mais esforço do que corrigir depois.
- Antecipe as decisões de design: uma pessoa define primeiro as escolhas de arquitetura e produto e as registra como restrições.
- Use os mesmos critérios na revisão cruzada: é possível usar a interface unificada da APIYI para invocar modelos de diferentes fornecedores e comparar suas avaliações.
Conclusão
O trabalho de acompanhar todo o ciclo do Agent costuma ser cansativo porque a tarefa é passada com informações incompletas. Isso obriga você a monitorar o processo e corrigir desvios a todo momento. Para preparar melhor a tarefa desde o início, foque em três pontos:
- Estruture a descrição da tarefa em cinco partes: objetivo, contexto, restrições, materiais de referência e critérios de aceitação. Assim, o Agent sabe o que fazer, qual resultado alcançar e no que não deve mexer.
- Transforme os critérios de aceitação em itens verificáveis: peça ao Agent que relate a verificação de cada item. Assim, você só precisa conferir a tabela de verificação e as pendências.
- Separe o que pode ser resolvido com contexto do que exige supervisão humana: decisões de design devem ser tomadas antes, e os próprios critérios de aceitação ficam sob responsabilidade de uma pessoa.
Comece pela próxima tarefa real: escreva primeiro os critérios de aceitação, complete as outras partes e registre quantas vezes precisou intervir durante o processo. Use esse número como referência para melhorar. Se você também estiver experimentando a revisão cruzada com modelos de diferentes fornecedores, pode usar a APIYI em apiyi.com para acessá-los por uma interface unificada e testar, em tarefas reais, qual combinação reduz mais a necessidade de intervenção.
📚 Referências
- Discussão no V2EX – Como reduzir a intervenção humana, permitir que agentes trabalhem de forma independente e melhorar a qualidade das entregas: fonte do tema deste artigo
- Link:
v2ex.com/t/1254207 - Descrição: aborda o cansaço causado pela participação humana no ciclo de trabalho dos agentes, o papel do contexto e a ideia de revisão cruzada entre agentes de diferentes fornecedores
Autor: Equipe técnica da APIYI
Troca de experiências: Entre em contato conosco pela página inicial da APIYI, em apiyi.com, para conversar sobre instruções de tarefas para agentes e colaboração entre modelos.
