Do épico à produção: usando agentes para entregar features em sistemas reais
Este é o oitavo artigo da série sobre arquitetura AI friendly. Nos textos anteriores, falamos sobre contexto, documentação, observabilidade, skills, Context Skills, agentes, tools, MCP, guardrails e harnesses.
Agora vamos juntar essas peças em um fluxo completo de engenharia.
A ideia não é pedir para um agente “implementar uma feature” e esperar que ele descubra tudo sozinho. A proposta é mostrar como um agente pode participar de uma entrega desde o entendimento do épico até o acompanhamento da mudança em produção.
A implementação do código é apenas uma das etapas. Em muitos casos, nem é a parte mais complexa.
O épico
Vamos usar como exemplo este pedido:
Como cliente, quero solicitar um reembolso parcial de um pedido,
para que eu possa devolver apenas alguns itens da compra.
À primeira vista, parece uma alteração simples no serviço de pagamentos.
Mas antes de escrever código, precisamos entender várias coisas:
onde o pedido é criado;
quem calcula o valor total;
qual serviço é responsável pelo pagamento;
como os itens são relacionados à transação;
quais regras existem para cancelamento;
como o estoque é atualizado;
como o cliente é notificado;
quais dados precisam ser enviados para o provedor de pagamento.
Um agente que recebe apenas o texto do épico pode produzir uma solução plausível e ainda assim errada.
Questionar o épico
O primeiro trabalho do agente não deveria ser criar arquivos. Deveria ser transformar o épico em perguntas.
Algumas perguntas possíveis:
Qual problema de negócio estamos tentando resolver?
Quem pode solicitar o reembolso?
Quais itens são elegíveis?
Existe um prazo para solicitar o reembolso?
O pedido pode ter mais de um reembolso?
Como lidamos com um reembolso parcial já iniciado?
O valor devolvido é calculado pelo pedido ou pelo pagamento?
O que acontece se o provedor de pagamento aceitar o reembolso, mas a atualização interna falhar?
O estoque deve ser liberado imediatamente ou apenas depois da confirmação?
Como o cliente será informado?
O agente não precisa responder tudo sozinho. O objetivo é levar as perguntas certas para a pessoa responsável pelo produto e para as equipes envolvidas.
Questionar o épico não significa bloquear o trabalho. Significa transformar ambiguidades em decisões explícitas antes que elas apareçam como bugs ou retrabalho.
Uma skill de planejamento pode orientar a criação dessas perguntas. O agente pode consultar a documentação do domínio e usar uma tool para buscar épicos, requisitos e decisões anteriores.
Fazer a spike
Depois de esclarecer o objetivo, começa a investigação técnica.
O agente pode usar diferentes Context Skills para investigar o problema. Uma skill de pedidos ajuda a entender os itens e estados do pedido. Uma skill de pagamentos explica as regras do provedor. Uma skill de observabilidade mostra como investigar o comportamento atual.
O objetivo da spike não é produzir uma resposta bonita. É construir uma visão baseada em evidências.
O agente pode procurar:
código relacionado ao pedido;
fluxo atual de cancelamento;
integração com o provedor de pagamento;
testes de reembolso ou cancelamento;
eventos publicados depois de uma alteração de pagamento;
consumidores desses eventos;
ADRs e decisões anteriores;
métricas e traces do fluxo atual;
incidentes relacionados.
Uma investigação razoável poderia seguir esta ordem:
Encontrar o modelo ou contrato do pedido.
Encontrar o fluxo atual de cancelamento.
Encontrar a integração com o provedor de pagamento.
Encontrar testes de reembolso ou cancelamento.
Encontrar eventos publicados após uma alteração de pagamento.
Encontrar consumidores desses eventos.
Consultar sinais de produção para entender o comportamento atual.
O agente não deve apenas localizar arquivos com nomes parecidos. Ele precisa reconstruir o fluxo e explicar como as partes se conectam.
Registrar a decisão da spike
A saída da spike não deveria ficar apenas no histórico da conversa com o agente. Ela deve virar documentação que possa ser encontrada em investigações futuras.
Um documento de decisão pode registrar:
# Decisão: reembolso parcial
## Contexto
O pedido pode conter vários itens, mas o fluxo atual de reembolso
opera apenas sobre o valor total da transação.
## Alternativas consideradas
- criar um novo tipo de transação;
- permitir múltiplos reembolsos na transação existente;
- criar um serviço separado para reembolsos.
## Decisão
Usar a transação existente e controlar o valor acumulado dos reembolsos.
## Consequências
- o provedor externo precisa aceitar múltiplos reembolsos;
- o evento de reembolso precisa identificar os itens;
- a operação precisa ser idempotente;
- consumidores antigos precisam continuar funcionando.
## Riscos
- concorrência entre dois pedidos de reembolso;
- diferença entre a confirmação externa e o estado interno;
- consumidores que não conhecem o novo formato.
Essa documentação ajuda a equipe atual, mas também ajuda os próximos agentes e as próximas demandas.
Cada spike bem documentada adiciona uma nova fonte de contexto à arquitetura. Com o tempo, deixamos de depender apenas do código e começamos a construir um mapa de decisões, contratos e consequências.
Definir o que significa sucesso
Antes de criar tarefas, precisamos responder a uma pergunta simples:
Como saberemos que essa implementação resolveu o problema?
Para o reembolso parcial, sucesso pode significar:
o cliente consegue selecionar itens elegíveis;
o valor reembolsado nunca ultrapassa o valor pago;
uma mesma solicitação não é processada duas vezes;
o provedor recebe os dados corretos;
o estoque é atualizado no momento correto;
o cliente recebe uma notificação coerente;
consumidores antigos continuam funcionando;
a taxa de erro não aumenta;
a latência permanece dentro do limite esperado;
o volume de chamados relacionados a reembolsos parciais diminui;
a operação pode ser investigada depois.
Esses critérios são mais importantes do que a quantidade de arquivos alterados. Código implementado não é sinônimo de problema resolvido.
Também precisamos medir o impacto fora do sistema. Se o objetivo é permitir que o próprio cliente solicite um reembolso parcial, uma redução no número de chamados sobre esse processo pode ser uma métrica importante de sucesso.
Essa métrica pode ser combinada com os sinais técnicos. Uma queda nos chamados só representa sucesso se a taxa de erro não tiver aumentado e se os reembolsos estiverem sendo processados corretamente. Caso contrário, podemos apenas estar deixando o problema menos visível para o suporte.
Por isso, a definição de sucesso já precisa apontar para o trabalho de observabilidade. Na seção Definir a observabilidade antes do código, vamos transformar esses critérios em métricas, queries, dashboards e alertas.
Definir e criar as tarefas
Com as decisões e os critérios de sucesso definidos, o agente pode decompor a entrega:
adicionar o endpoint de reembolso parcial;
validar itens e valor acumulado dos reembolsos;
atualizar a integração com o provedor;
garantir idempotência e controle de concorrência;
versionar o evento de pagamento;
atualizar consumidores de estoque e notificações;
criar testes unitários e de integração;
configurar o ambiente de QA;
adicionar métricas e traces;
criar dashboards e alertas;
atualizar documentação e runbook.
Uma tool pode criar essas tarefas no sistema usado pela equipe. Uma skill de planejamento pode definir o formato mínimo de cada tarefa, incluindo contexto, critério de aceite, dependências e riscos.
O agente pode preparar as tarefas, mas a equipe ainda deve confirmar se a divisão representa corretamente o trabalho e o ownership de cada domínio.
Definir como testar
Antes da implementação, precisamos decidir como validar a mudança em um ambiente não produtivo.
Isso pode envolver:
dados de teste para pedidos com vários itens;
configuração de um provedor de pagamentos simulado;
feature flag para ativar o fluxo gradualmente;
ambiente de QA com os consumidores atualizados;
testes de contrato para eventos;
testes de concorrência;
testes de idempotência;
testes de falha depois da confirmação externa;
testes de rollback.
O agente pode criar cenários de teste a partir dos critérios de sucesso, mas a equipe precisa verificar se o ambiente consegue reproduzir as condições importantes do sistema real.
Uma boa pergunta é:
O que precisa estar configurado no ambiente de QA para que possamos confiar no resultado?
Se a resposta for “nada”, provavelmente ainda não definimos o teste de forma suficiente.
Definir a observabilidade antes do código
Antes da IA existir, já era uma boa prática definir como uma mudança seria observada depois de publicada.
Para cada feature, precisamos decidir:
quais logs serão emitidos;
quais métricas serão coletadas;
quais traces precisam existir;
quais queries serão usadas;
qual comportamento representa sucesso;
qual comportamento representa degradação;
qual sinal deve iniciar um rollback.
Para o reembolso parcial, poderíamos acompanhar:
quantidade de solicitações iniciadas;
quantidade de reembolsos confirmados;
quantidade de falhas no provedor;
valor total reembolsado;
tempo entre solicitação e confirmação;
divergências entre o estado externo e o interno;
quantidade de reprocessamentos;
falhas por tipo de provedor ou método de pagamento.
O agente pode ajudar a escrever as queries e configurar os painéis, mas a definição do que deve ser observado é uma decisão de engenharia. Sem isso, a equipe publica a mudança e fica sem evidência para saber se ela foi efetiva.
Implementar o código
Só agora começa a implementação.
O agente pode ajudar a:
criar ou alterar classes;
atualizar contratos;
escrever testes;
alterar schemas;
adicionar instrumentação;
atualizar configurações;
preparar um pull request.
Mas é importante perceber a proporção do trabalho. A implementação é apenas uma parte do ciclo.
Entender o problema, tomar decisões, definir o sucesso, preparar o ambiente, escolher os sinais e planejar a operação podem exigir mais raciocínio do que escrever o código em si.
O agente se torna mais útil quando participa de todas essas etapas, e não apenas quando recebe um arquivo para modificar.
Criar dashboards e alertas
Antes do deploy, precisamos preparar a operação da feature.
Isso pode incluir:
dashboard do novo fluxo;
taxa de sucesso;
taxa de erro;
latência;
volume de solicitações;
impacto por cliente ou região;
falhas por dependência;
alertas de divergência;
alertas de aumento de erro;
critérios de rollback.
Uma dashboard sem uma pergunta operacional clara também pode virar apenas decoração. Cada painel deve ajudar a responder algo como:
a feature está sendo usada?
está funcionando?
está mais lenta?
está afetando outro contexto?
precisamos interromper o rollout?
Fazer o deploy e acompanhar
O agente pode preparar o pull request, a GMUD e o plano de deploy. Ele pode resumir riscos, listar verificações e organizar o passo a passo.
A execução em produção deve continuar respeitando as políticas da organização. Dependendo do risco, uma pessoa pode precisar aprovar a GMUD, revisar o pull request e autorizar o merge.
Depois do deploy, o acompanhamento deve comparar o comportamento observado com o baseline anterior:
as métricas estão dentro do esperado?
a taxa de erro mudou?
o provedor está respondendo como esperado?
os eventos estão sendo consumidos?
os dashboards mostram o resultado definido no início?
algum alerta precisa ser acionado?
O agente pode consultar os sinais e organizar a análise. A decisão de continuar, pausar ou reverter a mudança deve respeitar os limites definidos pela equipe.
Finalizar a entrega com documentação
A entrega não termina quando o deploy é concluído.
O documento criado na spike deve ser atualizado com o resultado real da implementação:
o que foi implementado;
quais decisões mudaram;
quais contratos foram versionados;
quais métricas foram criadas;
quais alertas existem;
como operar a feature;
como investigar falhas;
quais limitações permanecem;
quais aprendizados podem ser reutilizados.
Esse fechamento cria um ciclo de aprendizado:
O épico gera perguntas.
A spike gera uma decisão.
A implementação gera novos comportamentos.
A operação gera evidências.
A documentação registra o que foi aprendido.
A próxima demanda começa com mais contexto.
É assim que a Context Architecture evolui de verdade. Não como um documento criado uma única vez, mas como um conjunto de conhecimento que cresce junto com o sistema.
Onde entram skills, tools e MCP?
Cada etapa pode usar uma combinação diferente:
Planning Skill: questiona o épico e decompõe o trabalho;
Architecture Skill: consulta decisões e identifica impactos;
Testing Skill: define cenários e estratégias de validação;
Observability Skill: cria queries, métricas e dashboards;
Delivery Skill: prepara pull request, GMUD e deploy;
Tools: executam ações específicas, como buscar documentos ou criar tarefas;
MCP: conecta o agente aos sistemas onde essas ações acontecem.
O agente coordena o fluxo, mas não precisa carregar todo o conhecimento de todos os contextos ao mesmo tempo. Cada skill oferece uma especialização e cada tool executa uma capacidade concreta.
O papel da revisão humana
O objetivo não é remover a equipe do processo de engenharia.
A equipe ainda precisa:
confirmar regras de negócio;
avaliar trade-offs;
aprovar mudanças de contrato;
decidir quais riscos são aceitáveis;
aprovar alterações de produção;
assumir a responsabilidade pela decisão.
O agente ajuda a tornar a preparação mais rápida e mais completa. Ele consegue percorrer fontes diferentes, encontrar relações que poderiam passar despercebidas e organizar as evidências em um formato mais fácil de revisar.
A decisão continua sendo responsabilidade da equipe.
Conclusão
Um agente pode participar de todo o ciclo de uma feature sem começar escrevendo código.
Ele pode questionar um épico, fazer uma spike, registrar decisões, definir critérios de sucesso, criar tarefas, planejar testes, preparar queries de observabilidade, implementar mudanças, abrir um pull request, acompanhar um deploy e atualizar a documentação.
Esse fluxo só funciona bem quando existe contexto disponível, conectado e confiável. Sem documentação, decisões, observabilidade e skills, o agente tende a preencher as lacunas com suposições.
Com uma arquitetura AI friendly, ele passa a trabalhar com evidências e deixa mais claro o que sabe, o que inferiu e o que ainda precisa ser decidido.
Esse é o ponto em que a conversa deixa de ser apenas sobre gerar código. O agente começa a participar do trabalho de engenharia que acontece antes, durante e depois da implementação.