Este é o oitavo artigo da série sobre arquitetura amigável à IA. Nos artigos anteriores, falamos sobre contexto, documentação, observabilidade, skills, Context Skills, agentes, ferramentas, MCP, guardrails e harnesses.
Agora vamos reunir essas peças em um fluxo completo de engenharia.
A ideia não é pedir a um agente para “implementar uma funcionalidade” e esperar que ele descubra tudo sozinho. O objetivo é mostrar como um agente pode ajudar em uma entrega desde o momento em que entendemos o épico até monitorarmos a mudança em produção.
Escrever o código é apenas uma etapa. Em muitos casos, nem é a mais difícil.
O épico
Vamos usar esta solicitação como exemplo:
As a customer, I want to request a partial refund for an order,
so I can return only some of the items I bought.À primeira vista, isso parece uma pequena mudança 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 vinculados à transação;
quais regras de cancelamento existem;
como o estoque é atualizado;
como o cliente é notificado;
quais dados precisam ser enviados ao provedor de pagamentos.
Um agente que recebe apenas o épico pode produzir uma solução plausível, mas ainda assim errada.
Questione o épico
A primeira tarefa do agente não deve ser criar arquivos. Deve ser transformar o épico em perguntas.
As perguntas podem incluir:
Qual problema de negócio estamos tentando resolver?
Quem pode solicitar um reembolso?
Quais itens são elegíveis?
Existe um prazo para solicitar um reembolso?
Um pedido pode ter mais de um reembolso?
Como lidamos com um reembolso parcial que já foi iniciado?
O valor do reembolso é calculado a partir do pedido ou do pagamento?
O que acontece se o provedor aceitar o reembolso, mas a atualização interna falhar?
O estoque deve ser liberado imediatamente ou somente após a confirmação?
Como o cliente será informado?
O agente não precisa responder tudo sozinho. Seu trabalho é levar as perguntas certas ao responsável pelo produto e às equipes envolvidas.
Questionar o épico não bloqueia o trabalho. Transforma pontos pouco claros em decisões explícitas antes que se tornem 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 ferramenta para encontrar épicos, requisitos e decisões anteriores.
Execute o spike
Depois que o objetivo está claro, 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 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 do spike não é produzir uma resposta bonita. É construir uma visão baseada em evidências.
O agente pode procurar:
código relacionado ao pedido;
o fluxo atual de cancelamento;
a integração com o provedor de pagamentos;
testes de reembolso ou cancelamento;
eventos publicados após uma mudança no 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:
Encontre o modelo ou contrato do pedido.
Encontre o fluxo atual de cancelamento.
Encontre a integração com o provedor de pagamentos.
Encontre testes de reembolso ou cancelamento.
Encontre eventos publicados após uma mudança no pagamento.
Encontre os consumidores desses eventos.
Verifique os sinais de produção para entender o comportamento atual.
O agente não deve apenas encontrar arquivos com nomes semelhantes. Ele precisa reconstruir o fluxo e explicar como as partes estão conectadas.
Registre a decisão do spike
O resultado do spike não deve permanecer apenas no histórico da conversa. Ele deve se tornar uma documentação que possa ser encontrada em investigações futuras.
Um documento de decisão poderia ser assim:
# Decision: partial refunds
## Context
An order can contain several items, but the current refund flow
works only with the total transaction amount.
## Options considered
- create a new transaction type;
- allow multiple refunds on the existing transaction;
- create a separate refund service.
## Decision
Use the existing transaction and track the total refunded amount.
## Consequences
- the external provider must support multiple refunds;
- the refund event must identify the items;
- the operation must be idempotent;
- old consumers must keep working.
## Risks
- two refund requests may run at the same time;
- the external and internal states may become different;
- some consumers may not know the new format.Essa documentação ajuda a equipe atual, mas também ajuda agentes e trabalhos futuros.
Cada spike bem documentado adiciona uma nova fonte de contexto à arquitetura. Com o tempo, deixamos de depender apenas do código e construímos um mapa de decisões, contratos e consequências.
Defina o que significa sucesso
Antes de criar tarefas, precisamos responder a uma pergunta simples:
Como saberemos que esta implementação resolveu o problema?
Para um reembolso parcial, sucesso pode significar:
o cliente pode selecionar itens elegíveis;
o valor do reembolso nunca excede o valor pago;
a mesma solicitação nunca é processada duas vezes;
o provedor recebe os dados corretos;
o estoque é atualizado no momento certo;
o cliente recebe uma notificação clara;
os consumidores antigos continuam funcionando;
a taxa de erros não aumenta;
a latência permanece dentro do limite esperado;
o número de solicitações de suporte sobre reembolsos parciais diminui;
a operação pode ser investigada posteriormente.
Esses critérios importam mais do que o número de arquivos alterados. Código implementado não significa automaticamente que o problema foi resolvido.
Também precisamos medir o impacto fora do sistema. Se o objetivo é permitir que os clientes solicitem reembolsos parciais sozinhos, menos solicitações de suporte sobre esse processo pode ser uma métrica importante de sucesso.
Essa métrica deve ser combinada com sinais técnicos. Menos solicitações de suporte só representam sucesso se a taxa de erros não tiver aumentado e os reembolsos estiverem sendo processados corretamente. Caso contrário, podemos apenas estar tornando o problema menos visível para o suporte.
Por isso, a definição de sucesso já deve apontar para o trabalho de observabilidade. Esses critérios precisam se transformar em métricas, consultas, dashboards e alertas.
Defina e crie as tarefas
Com as decisões e os critérios de sucesso definidos, o agente pode dividir a entrega em tarefas:
adicionar o endpoint de reembolso parcial;
validar os itens e o valor total reembolsado;
atualizar a integração com o provedor;
garantir idempotência e controle de concorrência;
versionar o evento de pagamento;
atualizar os 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 a documentação e o runbook.
Uma ferramenta 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érios de aceitação, dependências e riscos.
O agente pode preparar as tarefas, mas a equipe ainda precisa confirmar se a divisão representa corretamente o trabalho e a responsabilidade de cada domínio.
Defina como testar
Antes da implementação, precisamos decidir como validar a mudança em um ambiente que não seja de produção.
Isso pode envolver:
dados de teste para pedidos com vários itens;
um provedor de pagamentos simulado;
uma feature flag para lançamento gradual;
um ambiente de QA com consumidores atualizados;
testes de contrato para eventos;
testes de concorrência;
testes de idempotência;
testes de falha após a confirmação externa;
testes de rollback.
O agente pode criar cenários de teste a partir dos critérios de sucesso, mas a equipe deve verificar se o ambiente consegue reproduzir as condições importantes do sistema real.
Uma boa pergunta é:
O que precisa ser configurado em QA para confiarmos no resultado?
Se a resposta for “nada”, o teste provavelmente não foi definido com detalhes suficientes.
Defina a observabilidade antes do código
Mesmo antes de existirem ferramentas de IA, era uma boa prática decidir como uma mudança seria observada após o lançamento.
Para cada funcionalidade, precisamos decidir:
quais logs serão emitidos;
quais métricas serão coletadas;
quais traces precisam existir;
quais consultas serão usadas;
qual comportamento significa sucesso;
qual comportamento significa degradação;
qual sinal deve iniciar um rollback.
Para reembolsos parciais, poderíamos acompanhar:
o número de solicitações iniciadas;
o número de reembolsos confirmados;
o número de falhas do provedor;
o valor total reembolsado;
o tempo entre a solicitação e a confirmação;
diferenças entre o estado externo e o interno;
o número de novas tentativas;
falhas por provedor ou método de pagamento.
O agente pode ajudar a escrever consultas e configurar dashboards, mas decidir o que observar é uma decisão de engenharia. Sem esse trabalho, a equipe pode lançar a mudança sem ter evidências de que ela funcionou.
Implemente o código
Somente 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 entender o tamanho dessa etapa. A implementação é apenas uma parte do ciclo.
Entender o problema, tomar decisões, definir sucesso, preparar o ambiente, escolher sinais e planejar a operação pode exigir mais raciocínio do que escrever o próprio código.
O agente se torna mais útil quando participa de todas essas etapas, não apenas quando recebe um arquivo para modificar.
Crie dashboards e alertas
Antes da implantação, precisamos preparar a operação da funcionalidade.
Isso pode incluir:
um dashboard para o novo fluxo;
taxa de sucesso;
taxa de erros;
latência;
volume de solicitações;
impacto por cliente ou região;
falhas por dependência;
alertas de divergência de estado;
alertas de aumento de erros;
critérios de rollback.
Um dashboard sem uma pergunta operacional clara pode virar decoração. Cada painel deve ajudar a responder a uma pergunta como:
A funcionalidade está sendo usada?
Ela está funcionando?
Ela está mais lenta?
Ela está afetando outro contexto?
Precisamos interromper o lançamento?
Implante e monitore
O agente pode preparar o pull request, o registro da mudança e o plano de implantação. Ele pode resumir riscos, listar verificações e organizar as etapas.
A execução em produção ainda deve seguir as políticas da organização. Dependendo do risco, uma pessoa pode precisar aprovar o registro da mudança, revisar o pull request e autorizar o merge.
Após a implantação, o monitoramento deve comparar o comportamento observado com a linha de base anterior:
As métricas estão dentro do intervalo esperado?
A taxa de erros 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 verificar os sinais e organizar a análise. A decisão de continuar, pausar ou reverter a mudança deve seguir os limites definidos pela equipe.
Finalize a entrega com documentação
A entrega não termina quando a implantação é concluída.
O documento criado durante o 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 funcionalidade;
como investigar falhas;
quais limitações permanecem;
quais aprendizados podem ser reutilizados.
Essa etapa final cria um ciclo de aprendizado:
O épico cria perguntas.
O spike cria uma decisão.
A implementação cria um novo comportamento.
A operação cria evidências.
A documentação registra o que foi aprendido.
A próxima solicitação começa com mais contexto.
É assim que uma Arquitetura de Contexto realmente cresce. Ela não é um documento criado uma única vez. É um corpo de conhecimento que cresce com o sistema.
Onde entram as skills, as ferramentas e o MCP?
Cada etapa pode usar uma combinação diferente:
Planning Skill: questiona o épico e divide o trabalho;
Architecture Skill: verifica decisões e identifica impactos;
Testing Skill: define cenários e estratégias de validação;
Observability Skill: cria consultas, métricas e dashboards;
Delivery Skill: prepara o pull request, o registro da mudança e a implantação;
Tools: executam ações específicas, como encontrar 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 fornece uma especialização, e cada ferramenta 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 as regras de negócio;
avaliar os trade-offs;
aprovar mudanças de contrato;
decidir quais riscos são aceitáveis;
aprovar mudanças em produção;
assumir a responsabilidade pela decisão.
O agente ajuda a tornar a preparação mais rápida e completa. Ele pode percorrer diferentes fontes, encontrar relações que poderiam passar despercebidas e organizar 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 vida de uma funcionalidade sem começar escrevendo código.
Ele pode questionar um épico, executar um spike, registrar decisões, definir critérios de sucesso, criar tarefas, planejar testes, preparar consultas de observabilidade, implementar mudanças, abrir um pull request, monitorar uma implantação e atualizar a documentação.
Esse fluxo funciona bem somente quando o contexto está disponível, conectado e confiável. Sem documentação, decisões, observabilidade e skills, o agente tende a preencher lacunas com suposições.
Com uma arquitetura amigável à IA, o agente pode trabalhar com evidências e deixar claro o que sabe, o que inferiu e o que ainda precisa ser decidido.
É nesse ponto 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.
Comentários