O uso de agentes de IA no desenvolvimento de software muda a forma como as tarefas são executadas, mas também exige atenção à maneira como elas são especificadas.

Um ticket precisa comunicar o resultado esperado, delimitar o trabalho e apontar o contexto necessário para que o desenvolvedor possa executar ou delegar a implementação aos seus agentes.

Isso não significa escrever instruções detalhadas para cada etapa da programação. O objetivo é fornecer informações suficientes para orientar a execução, reduzir interpretações incorretas e permitir que a entrega seja avaliada.

Um bom ticket define o problema, as condições de sucesso e os limites da implementação, sem substituir as decisões técnicas do responsável.

1. O que precisa estar claro antes de começar?

Antes de criar o ticket, é importante definir quatro elementos:

  • Problema: o que precisa ser resolvido ou modificado?
  • Objetivo: qual resultado esperamos alcançar?
  • Escopo: quais funcionalidades, componentes ou comportamentos estão envolvidos?
  • Critérios de aceite: como saberemos que a entrega está correta?

Essas informações orientam tanto o desenvolvedor quanto os agentes utilizados durante a implementação.

Quando o requisito permite interpretações diferentes que afetam o comportamento da aplicação, a dúvida deve ser esclarecida antes da execução.

Por outro lado, não é necessário antecipar todas as decisões técnicas. O responsável pode investigar o projeto, identificar a abordagem apropriada e utilizar agentes para implementar a solução.

2. Quais informações incluir no ticket?

Nem todo ticket precisa conter todos os campos. Uma correção simples pode ser especificada em poucas linhas, enquanto uma funcionalidade que envolve várias integrações exige mais contexto.

A estrutura pode incluir:

Campo O que registrar
Objetivo Resultado esperado e motivo da alteração.
Contexto Comportamento atual, usuários afetados e informações relevantes.
Escopo e limites O que deve ser alterado e quais fronteiras precisam ser respeitadas.
Critérios de aceite Condições observáveis que determinam se a entrega está correta.
Referências Documentação, telas, contratos de API e decisões relacionadas.
Instruções de execução Orientações específicas que complementam os padrões existentes.
Recursos disponíveis Skills, ferramentas, MCPs e ambientes relevantes, quando necessários.
Dependências Outras entregas, decisões ou acessos necessários.
Estimativa Esforço ou prazo esperado, conforme a prática adotada pela equipe.
Testes e validações Cenários que precisam ser verificados e testes que devem ser criados ou atualizados.
Evidências Resultados, logs, capturas de tela ou outras informações necessárias para avaliar a entrega.

Informações essenciais e complementares

Objetivo, contexto relevante, escopo e critérios de aceite formam a base da especificação.

Os demais campos são utilizados conforme a necessidade.

Por exemplo, um ticket que altera uma integração externa pode exigir referências ao contrato da API, enquanto um ajuste visual pode precisar de um link para o design aprovado.

Também é importante distinguir três conceitos:

  • Critérios de aceite: descrevem o comportamento que deve ser entregue.
  • Testes: definem como esse comportamento será verificado.
  • Evidências: demonstram quais verificações foram realizadas e seus resultados.

Estimativas com agentes de IA

A utilização de agentes pode reduzir o tempo de implementação, mas não elimina investigação, supervisão, testes, revisão e ajustes.

Uma estimativa deve considerar o esforço total necessário para entregar o resultado, não apenas o tempo esperado para gerar código.

Quando existir incerteza significativa, uma faixa de esforço ou prazo pode ser mais adequada do que uma estimativa excessivamente precisa.

3. O que escrever no ticket e o que apenas referenciar?

Um erro comum é repetir no ticket instruções que deveriam fazer parte da documentação permanente do projeto.

Padrões de arquitetura, segurança, organização de arquivos, convenções de código e instruções gerais para agentes devem permanecer nas referências compartilhadas do projeto.

O ticket deve concentrar as particularidades da demanda.

Exemplo de instrução desnecessária:

Utilize TypeScript, siga as convenções de nomenclatura do projeto, respeite a arquitetura existente e execute o lint.

Se essas regras já fazem parte dos padrões do repositório, não precisam ser repetidas.

Exemplo de instrução específica:

Esta alteração deve preservar a compatibilidade com os clientes que ainda utilizam a versão anterior da API. Consulte o contrato de integração vinculado ao ticket.

A segunda instrução acrescenta uma restrição relevante para aquela entrega.

Isso também evita que tickets antigos perpetuem instruções desatualizadas ou conflitantes com os padrões atuais.

A organização dessas referências é aprofundada nos artigos Arquitetura, engenharia e documentação de contexto e Padronização de projetos para desenvolvimento com agentes de IA.

4. Como indicar skills, MCPs e outras ferramentas?

O ticket pode apontar recursos que ajudam o responsável e seus agentes a executar determinada atividade.

Entretanto, não é necessário listar ferramentas apenas porque estão disponíveis no projeto.

O ideal é indicar recursos quando existe uma necessidade específica.

Necessidade Orientação no ticket
Implementação visual Consultar o design aprovado por meio da integração com o Figma.
Alteração no banco Utilizar a skill de migração definida pelo projeto.
Validação de interface Executar os cenários indicados no ambiente de testes com o navegador automatizado.
Integração externa Consultar o contrato atualizado e as referências da API.

A escolha do modelo, da IDE, da CLI ou da estratégia de delegação normalmente permanece com o responsável pela execução, respeitando os padrões estabelecidos.

Credenciais e dados sensíveis não devem ser inseridos diretamente nos tickets. O acesso a serviços e ambientes precisa seguir os mecanismos autorizados pelo projeto.

O uso dessas tecnologias é aprofundado no artigo Harnesses, skills, ferramentas e MCP.

5. Quando utilizar checklists ou subtickets?

Checklists e subtickets ajudam a organizar entregas maiores, mas possuem finalidades diferentes.

Checklist é útil quando o trabalho possui etapas relacionadas que podem continuar sob um único responsável e uma única entrega.

Subtickets fazem sentido quando determinadas partes precisam de acompanhamento independente, possuem responsáveis diferentes ou apresentam dependências importantes.

Por exemplo, uma funcionalidade pode envolver:

  • Adaptação do contrato de API.
  • Implementação do backend.
  • Atualização do frontend.
  • Testes de integração.
  • Validação da funcionalidade completa.

Essas atividades podem compor um checklist ou ser distribuídas em subtickets, conforme a complexidade e a organização da equipe.

O ticket principal deve preservar o objetivo do conjunto, as dependências relevantes e os critérios que determinam quando a funcionalidade inteira está concluída.

O detalhamento das técnicas de divisão do trabalho é abordado em Decomposição e delegação de tarefas.

6. Como tratar dúvidas e mudanças durante a execução?

Mesmo um ticket bem especificado pode apresentar dúvidas durante a implementação.

É importante distinguir uma decisão técnica de uma indefinição de requisito.

O desenvolvedor pode decidir como organizar classes, funções ou componentes dentro dos padrões existentes. Entretanto, não deve presumir um comportamento de negócio que não foi definido.

Quando um agente identificar uma ambiguidade relevante, o responsável deve avaliar se consegue resolvê-la com as referências disponíveis ou se precisa consultar quem definiu a demanda.

Mudanças de escopo

Se uma decisão alterar o comportamento esperado, os critérios de aceite ou as dependências, ela deve ser registrada no ticket ou na documentação vinculada.

Isso mantém o histórico acessível para quem executa, revisa ou retoma o trabalho posteriormente.

O ticket não precisa registrar cada tentativa do agente. Deve preservar as decisões que influenciam o resultado da entrega.

7. Como fica um ticket na prática?

Os exemplos seguintes utilizam níveis diferentes de detalhamento. A estrutura pode ser adaptada ao Jira, GitHub Issues, Linear ou à ferramenta utilizada pela equipe.


Exemplo 1 — Nova funcionalidade

Ticket: Adicionar filtro por disponibilidade na listagem de produtos

Objetivo

Permitir que o usuário visualize apenas produtos disponíveis para compra.

Contexto

A listagem atual apresenta produtos disponíveis e indisponíveis. O usuário precisa identificar manualmente quais itens podem ser comprados.

Escopo

  • Adicionar um filtro de disponibilidade à listagem.
  • Aplicar o filtro em conjunto com os filtros existentes.
  • Preservar o comportamento atual quando o novo filtro estiver desativado.

Critérios de aceite

  • [ ] O usuário consegue ativar e desativar o filtro.
  • [ ] Com o filtro ativado, a listagem apresenta apenas produtos disponíveis.
  • [ ] Os demais filtros continuam funcionando em conjunto.
  • [ ] O estado vazio é apresentado quando nenhum produto corresponde aos filtros selecionados.

Referências

  • Página atual de listagem.
  • Contrato da API de produtos.
  • Design aprovado, se aplicável.

Testes e evidências

  • Verificar os cenários com filtro ativado e desativado.
  • Validar a combinação com outros filtros.
  • Apresentar os resultados dos testes e evidências visuais da interface.

Estimativa

A ser definida pelo responsável após avaliação da implementação e dos pontos de integração.


Exemplo 2 — Correção de bug

Ticket: Corrigir duplicação de itens ao carregar a próxima página da listagem

Problema

Em determinadas situações, produtos já apresentados aparecem novamente após o carregamento da página seguinte.

Como reproduzir

  1. Abrir a listagem de produtos.
  2. Aplicar um filtro.
  3. Carregar mais resultados.
  4. Verificar os itens apresentados após a atualização.

Comportamento atual

Alguns produtos aparecem mais de uma vez na listagem.

Comportamento esperado

Cada produto deve aparecer uma única vez, respeitando a ordenação e os filtros aplicados.

Escopo

Investigar a paginação e corrigir a causa da duplicação, preservando os comportamentos existentes da listagem.

Critérios de aceite

  • [ ] A navegação entre páginas não apresenta produtos duplicados.
  • [ ] A ordenação e os filtros continuam funcionando.
  • [ ] A correção não provoca perda de resultados válidos.

Testes e evidências

  • Reproduzir o problema antes da correção, quando possível.
  • Adicionar ou atualizar um teste de regressão apropriado.
  • Registrar o resultado antes e depois da alteração.

Exemplo 3 — Entrega abrangente com subtickets

Ticket: Implementar gerenciamento de endereços na conta do cliente

Objetivo

Permitir que clientes autenticados cadastrem, consultem, editem e removam seus endereços.

Contexto

Atualmente, os dados de endereço são informados apenas durante determinadas operações. A nova funcionalidade permitirá gerenciá-los antecipadamente na área da conta.

Escopo

  • Criar os endpoints necessários.
  • Implementar a persistência dos endereços.
  • Construir a interface de gerenciamento.
  • Aplicar validações e regras de autorização.
  • Integrar frontend e backend.

Dependências

  • Definição dos campos obrigatórios.
  • Contrato da API.
  • Design das telas.
  • Regras para remoção ou alteração de endereços associados a operações existentes.

Subtickets sugeridos

Subticket Entrega
1 Contrato e persistência dos endereços
2 Endpoints e regras de autorização
3 Interface de gerenciamento
4 Integração e validação funcional

Critérios de aceite do ticket principal

  • [ ] O cliente consegue cadastrar, editar e remover endereços conforme as regras definidas.
  • [ ] Os endereços são associados exclusivamente à conta autenticada.
  • [ ] O sistema rejeita dados inválidos.
  • [ ] A interface apresenta mensagens apropriadas para sucesso e erro.
  • [ ] A funcionalidade completa passa pelas verificações estabelecidas.

Testes e evidências

Cada subticket deve apresentar as verificações relacionadas ao próprio escopo. O ticket principal exige uma validação integrada da funcionalidade.

Estimativa

Definida após avaliar as dependências e os subtickets, incluindo integração e validação final.


Conclusão

Tickets continuam sendo instrumentos para comunicar necessidades, organizar entregas e acompanhar resultados.

A utilização de agentes de IA torna ainda mais importante especificar objetivos, limites, referências e critérios de aceite, porque uma interpretação incorreta pode ser rapidamente transformada em código.

Isso não exige tickets excessivamente detalhados nem instruções que antecipem todas as decisões de implementação.

O objetivo é fornecer ao desenvolvedor e aos seus agentes o contexto necessário para executar o trabalho com autonomia, preservando a responsabilidade humana sobre a interpretação dos requisitos e a qualidade da entrega.