Engenharia de software com agentes: o que mudou depois de dois dias no workshop do TLC

English summary: After two days at Tech Leads Club's AI software engineering workshop, the main lesson was clear: faster code generation moves the bottleneck to context, architecture, verification, and technical judgment.

No fim de uma sessão com agentes, é possível ter centenas de linhas novas e ainda não saber se o problema certo foi resolvido. O código existe. A confiança, às vezes, não.

Passei os dias 12 e 13 de setembro de 2026 no workshop de engenharia de software com IA da Tech Leads Club. A programação reunia nomes da comunidade e convidados com experiências bem diferentes: Waldemar Neto, Felipe Adamoli, Felipe Rodrigues e William Calderipe, da TLC, além de Julio Santos, Staff Engineer no iFood, William Fernandes, Senior Software Engineer no PayPal, e Rogério Chaves, cofundador da LangWatch. Essa composição ajudou a tirar a conversa do campo dos prompts e levá-la para arquitetura, operação e qualidade. A página oficial do workshop lista os módulos e os profissionais convidados.

Minha tese depois desses dois dias é esta: quando agentes aceleram a implementação, o trabalho de engenharia se concentra ainda mais em contexto, decisões, arquitetura e verificação.

Este texto organiza os aprendizados que quero levar para o próximo projeto. Ele não é uma transcrição das aulas. É uma tentativa de transformar anotações em um modelo de trabalho que um time possa testar.

TL;DR

A velocidade do build deixa mais visíveis os gargalos de descoberta, design, revisão, testes e operação.
Contexto espalhado entre Slack, tickets, documentos e código é uma fonte direta de erro para agentes.
Uma spec bem escrita funciona como interface entre intenção humana e execução automática.
Autonomia precisa de limites, permissões e evidências proporcionais ao risco.
MCPs, skills, agentes, hooks e evals formam um sistema de trabalho. Uma coleção de prompts não forma.
O engenheiro ganha alavanca quando passa a liderar problema, arquitetura, decomposição e validação.

Um exemplo simples resume a diferença: "o agent terminou" é um status. "O agent implementou o comportamento, rodou os checks definidos, abriu a evidência e parou dentro dos limites" é um resultado auditável.

O workshop tornou o problema concreto

O material público do workshop descrevia sete módulos práticos em dois dias, com foco em IA-first, Spec-Driven Development, harness e o novo papel do dev. Os exemplos das aulas eram variados o bastante para mostrar que a discussão não cabe em uma ferramenta específica.

Julio Santos trouxe o contexto de sistemas frontend grandes no iFood. William Fernandes trouxe o custo de errar em automação de risco e fraude no PayPal. Felipe Rodrigues trabalha com skills, MCPs e engenharia de IA em produção e lidera o grupo de pesquisa de IA da TLC. William Calderipe conecta arquitetura pragmática, confiabilidade e experiência em sistemas de transação. Esses contextos não provam que existe uma receita única. Eles ajudam a enxergar a mesma pergunta em ambientes com restrições diferentes: como acelerar sem perder a capacidade de explicar por que uma entrega deve ser aceita?

As próximas seções são a minha síntese dessa pergunta.

1. Código mais rápido não significa engenharia mais rápida

O fluxo tradicional costuma ser resumido assim:

Plan → Design → Build → Test → Deploy → Maintain

Com agentes, o trecho de build pode encolher bastante em algumas tarefas. Os outros trechos continuam existindo. Em muitos casos, eles passam a ocupar a maior parte do ciclo.

Requisitos ambíguos continuam ambíguos. Uma decisão arquitetural ruim continua ruim. Um teste ausente continua ausente. A diferença é que o agente consegue transformar cada uma dessas lacunas em código antes que alguém perceba.

Por isso a pergunta de produtividade muda. Em vez de contar linhas geradas ou tarefas iniciadas, vale medir quanto trabalho correto chegou a um estado revisável. Isso inclui descoberta, decisão, implementação, checks, evidência e operação.

Uma equipe pode gerar menos código e entregar mais valor se reduzir retrabalho. Também pode gerar muito código e apenas aumentar a fila de revisão. A métrica precisa acompanhar o resultado, não o volume de atividade.

2. O próximo gargalo é o contexto

Uma frase voltou várias vezes durante o workshop: a decisão já foi tomada, mas não está no mesmo lugar que o trabalho.

Ela pode estar numa ata, em uma conversa do Slack, num ticket, numa RFC, em um ADR, no código ou na memória de alguém que não está disponível naquele momento. Um desenvolvedor consegue gastar horas reunindo esse material. Um agente pode simplesmente não encontrar a informação e seguir por outro caminho.

Esse é um erro traiçoeiro porque o resultado pode parecer competente. O código compila. O teste local passa. A implementação, porém, viola uma restrição que foi registrada em outro sistema.

Context engineering, nesse cenário, é trabalho de organização. O conhecimento precisa ter um lugar confiável, um owner, uma data, uma versão e uma forma de consulta. Também precisa voltar ao sistema oficial quando uma decisão muda. Sem esse ciclo, cada execução começa com uma fotografia incompleta da empresa.

Não basta conectar um modelo ao repositório. O repositório é uma fonte importante, mas raramente contém sozinho as decisões de produto, as exceções operacionais e as políticas de segurança que definem o que pode ser alterado.

3. Spec-Driven Development vira uma interface de trabalho

Uma spec útil reduz a distância entre a intenção e a tarefa. Ela responde perguntas que um prompt curto normalmente deixa abertas:

qual problema será resolvido;
como saberemos que foi resolvido;
quais casos limite importam;
o que está fora do escopo;
quais restrições técnicas e de negócio precisam ser respeitadas;
que evidência o agente deve entregar.

O fluxo discutido no workshop pode ser representado assim:

flowchart LR
  A[Specify] --> B[Design]
  B --> C[Tasks]
  C --> D[Execute]
  D --> E[Verify]
  E --> F[Review]
  F --> G[Learn]
  G --> A

A spec captura o que deve acontecer. O design registra como o sistema pode fazer isso. As tarefas transformam a decisão em unidades que um agente consegue executar. A verificação fecha o circuito.

Pense na spec como uma API entre a intenção humana e a execução do agente. Uma API ruim permite chamadas ambíguas e devolve erros difíceis de localizar. Uma spec ruim faz algo parecido: deixa o agente adivinhar o contrato e empurra a descoberta do problema para a revisão.

Um contrato mínimo copiável

Este é um ponto de partida pequeno para uma tarefa. Design, revisão e testes de segurança continuam necessários. O template evita que a execução comece sem um critério de término.

# Tarefa: nome curto

## Problema
Descreva o comportamento ou a dor que precisa mudar.

## Escopo
- Inclua o que será alterado.
- Liste explicitamente o que ficará fora.

## Aceitação
- Given [contexto], when [ação], then [resultado observável].
- Given [caso limite], when [ação], then [resultado esperado].

## Restrições
- Não alterar [superfície protegida].
- Preservar [contrato, permissão ou compatibilidade].

## Evidências obrigatórias
- [ ] Check automatizado: [comando]
- [ ] Fluxo manual ou E2E: [passos]
- [ ] Artefato de saída: [path, screenshot ou log redigido]

## Parada
Pare e peça decisão humana se [condição de risco ou ambiguidade].

O valor do template não está na formatação. Está em tornar o final da tarefa verificável antes de o agente começar.

4. Quatro falhas que a velocidade amplifica

1. A implementação começa antes da decisão

O agente recebe um pedido curto, escolhe uma interpretação e implementa. Quando alguém questiona a direção, já existem arquivos alterados, testes escritos para a hipótese errada e uma explicação pronta para defendê-la.

Uma etapa de research e uma spec curta custam menos que desfazer uma decisão codificada em várias camadas.

2. O contexto existe, mas não é recuperável

O time tem documentação, porém ela está desatualizada ou espalhada. O agente não distingue a decisão atual de uma discussão antiga. A resposta parece razoável porque o material errado também era tecnicamente plausível.

Esse caso pede curadoria e rastreabilidade. Adicionar mais documentos sem definir fonte de verdade só aumenta o espaço de busca.

3. O agente declara sucesso sem provar o comportamento

Um typecheck verde não prova um fluxo de pagamento. Um teste unitário não prova uma integração. Uma resposta do modelo dizendo "validado" não substitui o check que o contrato da tarefa exigia.

O agente precisa carregar a tarefa até a evidência correspondente. Se ele não conseguiu executar o check, o estado correto é "não verificado".

4. A organização mede atividade como se fosse qualidade

Tokens, sessões, linhas alteradas e quantidade de tools ajudam a investigar custo e adoção. Isolados, não dizem se a entrega foi boa. Um loop longo pode indicar cuidado, contexto ruim ou falta de limites. Um loop curto pode ser eficiência ou omissão.

Qualidade exige ligar objetivo, decisão, ação, resultado e verificação. A unidade útil é uma tarefa cujo contrato foi cumprido.

5. O harness é parte do produto de engenharia

Um agent opera dentro de um harness. O harness combina:

Camada	Pergunta	Evidência mínima
Contexto	Com quais regras, arquivos e decisões começou?	versão e fontes consultadas
Modelo	Qual capacidade e limite foram usados?	provider, modelo e configuração
Tools	Que ações externas foram tentadas?	chamada, status, duração e erro
Permissões	O que foi permitido, bloqueado ou negado?	política e decisão
Ambiente	Onde a ação ocorreu?	repositório, branch e ambiente
Verificação	O resultado resistiu a um check?	comando, resultado e artefato
Observabilidade	É possível reconstruir o caminho?	correlação, owner e retenção

Essa visão também ajuda a escolher quando não usar um agent. Formatar arquivos alterados e rodar um linter é um ótimo job determinístico. Investigar uma codebase desconhecida, comparar decisões e escolher o próximo passo pode justificar autonomia controlada.

Autonomia precisa de boundaries

Autonomia significa definir um espaço em que o agente pode operar e um ponto claro de parada, mantendo ações de maior risco sob aprovação humana.

Algumas fronteiras práticas:

leitura ampla e escrita restrita;
comandos permitidos por tipo de tarefa;
branch ou workspace isolado;
arquivos protegidos declarados na spec;
aprovação humana antes de produção, dados sensíveis ou mudança irreversível;
evidência obrigatória para cada afirmação de conclusão.

O desenho correto depende do risco. Uma mudança de copy não precisa da mesma política de uma migração de dados. O contrato deve mostrar essa diferença.

6. "Me prova": dogfooding entra no fluxo

Se o agente diz que uma aplicação web funciona, ele deve abrir o browser e seguir o fluxo. Se diz que uma CLI funciona, deve executar o comando e registrar a saída relevante. Se diz que uma API respeita um contrato, deve fazer a requisição e verificar a resposta.

Esse hábito é dogfooding aplicado à engenharia. Ele aproxima a validação do uso real e deixa uma evidência que outra pessoa consegue revisar.

Uma sequência mínima pode ser:

Implementar
   ↓
Executar o fluxo real
   ↓
Capturar resultado redigido
   ↓
Comparar com a aceitação
   ↓
Parar, corrigir ou pedir decisão

Screenshot, stdout, resposta HTTP e relatório de teste não são decoração. Cada artefato deve responder a uma pergunta do contrato. Evidência excessiva cria ruído e risco de vazamento; evidência insuficiente deixa a conclusão sem suporte.

7. Instrumentação também é system design

Logs, traces e eventos costumam entrar depois que o sistema já está em produção. Para fluxos com agentes, isso torna a investigação mais cara.

Desde o design, vale decidir:

qual ID conecta tarefa, sessão, subagent e verificação;
quais estados uma tool pode assumir;
onde ficam retries e esperas por permissão;
que dados precisam de redaction;
por quanto tempo os eventos serão retidos;
quem pode consultar detalhes;
que métrica indica qualidade e que métrica só indica atividade.

Observabilidade começa com os dados necessários para explicar uma execução. Argumentos de comandos, prompts, caminhos e respostas de MCP podem conter segredos, dados de clientes ou propriedade intelectual. Metadados costumam ser um ponto de partida mais seguro: tipo da tool, duração, status, código de erro, decisão de permissão e uma correlação sem conteúdo sensível.

Quando o detalhe for necessário, ele precisa de acesso controlado, retenção definida e revisão de privacidade. A telemetria deve explicar o resultado sem transformar o sistema num arquivo permanente de dados que ninguém sabe governar.

8. Conhecimento, MCP, skills e entregas

Uma arquitetura interna de trabalho com IA pode ser vista como uma cadeia:

Conhecimento → MCPs → Agente + skills → Entrega → Conhecimento atualizado

Conhecimento

Notion, Confluence, Slack, Linear, Jira, GitHub, ADRs, RFCs, dashboards e código podem participar. A fonte de verdade precisa ter dono e data. Sem isso, o conector só torna a confusão mais acessível.

MCPs

O Model Context Protocol fornece uma forma padronizada de conectar modelos a ferramentas e fontes externas. Na prática, um MCP pode ajudar o agente a consultar uma decisão, criar uma issue, ler um arquivo ou atualizar um documento. Cada ação ainda precisa de autenticação, escopo e política.

Skills

Uma skill deve ter uma responsabilidade reconhecível. discover, plan, implement, verify e reconcile podem compor uma sequência. Quando uma skill tenta pesquisar, editar, publicar e aprovar tudo ao mesmo tempo, fica difícil saber qual parte falhou.

Entregas

O resultado precisa voltar ao sistema oficial: uma issue, uma ADR, uma PR, uma documentação ou uma decisão registrada. O chat pode ser a interface, mas não deve ser o único lugar onde a organização consegue encontrar o trabalho.

Uma skill, uma tarefa. Essa separação facilita testes, observabilidade e substituição de componentes. Também reduz o custo de descobrir se uma falha veio do contexto, da tool, do prompt, da permissão ou da verificação.

9. LLMOps e token economics entram na arquitetura

Quando um time roda vários agentes em paralelo, o custo deixa de ser um detalhe da ferramenta. Passa a participar da decisão arquitetural.

Algumas perguntas que antes raramente apareciam no design agora precisam de resposta:

quanto custa uma tarefa completa, incluindo retries e subagents;
qual modelo atende cada tipo de workload;
quanto contexto é realmente necessário;
em que ponto a compactação reduz custo e em que ponto cria overhead;
como qualidade e latência mudam entre providers;
que limite impede uma tarefa mal especificada de consumir orçamento indefinidamente.

O mesmo vale para a qualidade. Evals, tracking de execução, comparação de modelos, latência, custo e taxa de conclusão formam um conjunto de LLMOps. Escolher um modelo "melhor" em abstrato não resolve a operação. O modelo precisa ser adequado à tarefa, ao risco, ao tempo e ao orçamento.

Contexto também é recurso finito. Uma sessão grande pode carregar informação útil, mas também aumenta custo e ruído. Compactar cedo demais pode apagar uma decisão; compactar tarde demais pode tornar cada próxima ação mais cara. A equipe precisa observar esse comportamento no próprio workload em vez de transformar uma regra de outra equipe em dogma.

10. A arquitetura precisa ser amigável para agentes

O workshop apresentou exemplos de mudanças arquiteturais feitas para permitir que vários agentes trabalhem em paralelo. Entre as ideias discutidas estavam pacotes menores, boundaries mais claros, migrações de stack em partes do sistema e redução do tempo de typecheck.

Isso adiciona perguntas ao system design:

um agente consegue localizar o ponto certo para mudar;
o pacote tem uma responsabilidade que cabe no contexto;
a validação termina em tempo razoável;
dois agentes conseguem trabalhar sem disputar os mesmos arquivos;
a observabilidade explica a mudança;
o rollback é simples;
as dependências deixam o contrato visível.

Uma arquitetura agent-friendly reduz ambiguidade e acoplamento para qualquer executor, humano ou automatizado.

O risco oposto também é real. Se um agente consegue escrever muito mais rápido, ele consegue espalhar um Big Ball of Mud na mesma velocidade. Microsserviços continuam trazendo CI/CD, logging, monitoramento, alertas, deploy e ownership. A IA reduz o custo de algumas tarefas; não remove a complexidade distribuída.

11. O papel do engenheiro está mudando

Uma ideia forte do workshop foi o engenheiro assumir um épico como product engineer. Essa função exige entender o problema, negociar escopo, escolher arquitetura, decompor o trabalho, conduzir agentes e responder pela validação.

O código continua sendo uma habilidade central. Ela divide espaço com entendimento de negócio, system design, comunicação, liderança, segurança e julgamento técnico.

Esse deslocamento também explica por que fundamentos voltam a aparecer. Quem não consegue avaliar uma decisão de arquitetura pode delegar a implementação, mas não consegue avaliar se a direção era boa. Quem não sabe definir um teste de aceitação também não consegue saber se o agente concluiu.

O agente amplia a capacidade de execução. A responsabilidade pela decisão continua com alguém que conhece o problema e aceita responder pelo resultado.

12. O loop de engenharia que ficou depois dos dois dias

Minha versão do loop ficou assim:

Problema
  ↓
Research
  ↓
Spec
  ↓
Design
  ↓
Plan
  ↓
Agents
  ↓
Implement
  ↓
Verify
  ↓
Review
  ↓
Deploy
  ↓
Observe
  ↓
Learn
  ↓
Atualizar contexto, skills e specs
  ↺

O último passo muda a qualidade do sistema com o tempo. Se o agente falhou porque faltava uma decisão, a correção não deve ficar apenas naquela PR. A base de conhecimento precisa melhorar. Se faltou um check, o contrato de verificação precisa mudar. Se o agente encontrou um boundary confuso, a arquitetura ou a documentação precisam registrar a lição.

O aprendizado de uma execução só escala quando volta para o sistema que produzirá as próximas execuções.

Tabela de decisão: agent ou workflow determinístico?

Situação	Caminho recomendado	Checkpoint humano
Formatar arquivos e rodar linter	Job determinístico	Revisar falhas do CI
Criar uma feature com critérios claros	Agent em workspace isolado	Aprovar spec e PR
Investigar uma codebase desconhecida	Agent com research e limites de leitura	Validar hipótese antes de editar
Migrar dados ou alterar produção	Workflow protegido, com automação parcial	Aprovação explícita e rollback testado
Atualizar documentação a partir de decisão	Agent com fonte citável	Confirmar fonte e owner
Operar vários agentes em paralelo	Orquestração com tasks independentes	Revisar conflitos, custo e evidências

A tabela ajuda o time a discutir a escolha antes de uma falha cara, inclusive quando o caminho correto é um workflow determinístico.