Padrões de Engenharia Agentic

• Guia que organiza a forma de desenvolver na era de agentes de programação como Claude Code e Codex, apresentando novos padrões de engenharia para colaborar com agentes
• Explica, por meio de vários padrões, como mudar hábitos de desenvolvimento e fluxos de trabalho em um ambiente onde o custo de escrever código caiu drasticamente
• Organiza de forma estruturada as áreas centrais do desenvolvimento orientado por agentes, como princípios, testes, compreensão de código e design de prompts
• Cada padrão tem o formato de um documento prático voltado ao trabalho real, incluindo exemplos de código, formas de trabalhar e casos de uso de prompts
• Material de referência prático para que desenvolvedores na era dos agentes de programação estruturem sistematicamente ambientes de codificação baseados em agentes e mantenham a qualidade

---

Visão geral de Agentic Engineering Patterns

• Guia que reúne métodos eficazes de engenharia para desenvolvimento junto com agentes de programação (Claude Code, OpenAI Codex etc.)
• Veja o post de apresentação Writing about Agentic Engineering Patterns
  • Documento estruturado para adicionar continuamente vários padrões (chapters), no estilo clássico de “Design Patterns”
  • Tem como tema central a mudança no fluxo de trabalho e na forma de tomar decisões dos desenvolvedores em um ambiente onde o custo de escrever código caiu muito
  • É mantido como um guia atualizável, e não como um post de blog, com expansão contínua prevista

1. Princípios

• Writing code is cheap now

  • Com o surgimento de agentes de programação com IA, o custo inicial de escrever código caiu para algo próximo de zero
  • No passado, como escrever código era caro, o desenvolvimento era centrado em design e planejamento, mas agora é possível testar ideias diretamente em código
  • Embora o custo de gerar código tenha caído, código bom — com testes e manutenção adequada — continua tendo custo

• Hoard things you know how to do

  • Um ativo importante do desenvolvedor é o acúmulo de conhecimento sobre “o que é possível fazer”
  • Enfatiza o hábito de guardar e acumular, em formato reutilizável, vários casos de resolução de problemas e pequenos experimentos de código
  • Esses códigos e exemplos reunidos podem servir como material de entrada poderoso ao instruir agentes de programação a criar novos recursos

• Anti-patterns: things to avoid

  • Mesmo que o código tenha sido gerado por um agente, compartilhá-lo ou enviar um PR sem revisão é um antipadrão que deve ser evitado
  • A descrição de PR escrita pelo agente também precisa ser verificada e ajustada por uma pessoa
  • Para não desperdiçar o tempo de quem revisa código, é preciso fornecer junto testes, processo de validação e os motivos das escolhas de implementação

2. Testes e QA

• Red/green TDD

  • O desenvolvimento guiado por testes (TDD) é um padrão especialmente eficaz ao ser usado com agentes de programação
  • Ao escrever os testes primeiro, o agente pode gerar código orientado a satisfazer esses testes
  • Mesmo com prompts mínimos, isso ajuda a obter geração de código mais precisa e confiável

• First run the tests

  • Ao trabalhar com agentes de programação, testes automatizados não são opcionais, mas um elemento essencial
  • Em um ambiente onde o custo de escrever testes caiu, o agente pode gerar e ajustar testes rapidamente
  • Como não é possível garantir que o código funciona antes de executá-lo de fato, os testes são fundamentais

3. Entendendo o código

• Linear walkthroughs

  • Padrão de ler o código ou projeto criado pelo agente do começo ao fim, em sequência, para entender sua estrutura
  • Mesmo em projetos simples, é possível aprender novas tecnologias e estruturas acompanhando o fluxo do código
  • Em resposta à preocupação de que a geração de código por IA reduza a velocidade de aprendizado, mostra que explorar o código em si pode ser uma oportunidade de aprendizagem

• Interactive explanations

  • Método de pedir explicações ao agente em conversa para entender um código ou sistema
  • Ao repetir perguntas, é possível compreender gradualmente o funcionamento e a estrutura do código
  • Padrão que expande o processo de entendimento de código para um modelo de aprendizado interativo

4. Prompts anotados

• GIF optimization tool using WebAssembly and Gifsicle

  • Inclui um exemplo de prompt para criar uma ferramenta de otimização de GIF baseada em WebAssembly e Gifsicle
  • Apresenta uma forma de implementar uma ferramenta de página única com HTML, JavaScript e CSS
  • Explica maneiras de usar agentes de programação por meio de prompts reais e exemplos de código

5. Apêndice

• Prompts I use

  • Coletânea de exemplos de prompts para agentes de programação realmente usados
  • Organização de padrões de prompts práticos aplicáveis a vários tipos de trabalho
  • Fornece templates úteis para uso na colaboração com agentes

[GN⁺]

Comentários do Hacker News

• Parece que vamos repetir a mesma coisa de novo
  Conceitos simples e razoáveis — por exemplo “escreva os testes primeiro”, “faça módulos pequenos e combináveis” — acabam sendo embalados com nomes complexos, e disso nasce toda uma indústria de consultoria
  Só que, desta vez, o alvo são “máquinas que falam”. Seria um mundo em que basta dizer em palavras o que se quer

  • COBOL prometia algo parecido. Diziam que era uma linguagem fácil para humanos lerem, então programadores não seriam mais necessários, mas no fim, para decompor e resolver problemas, a pessoa ainda precisava pensar como programador. Em outras palavras, só porque a linguagem é amigável para humanos não significa que os programadores desaparecem
  • Desta vez também parece que o ciclo do boom de IA vai se repetir. Agora, se você critica, a resposta é que “você não entendeu”, mas logo os problemas vão aparecer. Em especial, deve surgir uma situação em que “a IA gera tanto código que nem humanos nem a própria IA conseguem dar conta”. Quando isso acontecer, vão surgir de novo padrões e antipadrões, e consultores dizendo que resolvem isso
  • Como a IA fala e entende inglês, a clareza da interface diminui. É poderosa como uma CLI, mas não está claro que tipo de abordagem funciona melhor. Por isso, é importante documentar e compartilhar “o que pedir e como pedir para obter bons resultados”. Só não podemos deixar isso degenerar de novo numa indústria de coaching de OOP
  • Exato. E vai acontecer de novo, só que muito mais rápido desta vez. O ciclo de 10 anos de blogueiro → palestrante → livro → consultor → órgão certificador vai aparecer comprimido em poucos anos
  • Não concordo com a crítica de que o título do texto é complicado. Mas o problema é o mal-entendido de que “basta pedir em linguagem natural”. Na prática, o resultado varia enormemente de pessoa para pessoa. No fim, a lição que está surgindo é que “bons hábitos de desenvolvimento para humanos também são bons para a IA”. A IA parece humana, mas não é humana. Por isso, precisa de mais explicação

• Eu queria perguntar ao Simon — “como deve ser o code review num mundo em que código é barato?”
  Os membros do time abordam as coisas no estilo “se funciona, está bom”, sem entender a estrutura. Os reviews ficam cada vez maiores, e eu viro o gargalo. Pensei até em usar um revisor de IA como substituto, mas não gosto da ideia de perder a sensibilidade humana

  • É um tema realmente interessante. Se a velocidade de geração de código aumenta, o review vira o gargalo. Se código é barato, talvez seja possível baixar o padrão de revisão, mas eu, ao contrário, quero qualidade melhor. Em especial, revisão de segurança é algo que nunca pode ser omitido. Talvez seja necessário um processo mais sistemático, como o de times de segurança em organizações grandes
  • Para usar review baseado em agentes, configurar bem o contexto é importante. Se você roda um loop de planejamento → execução → teste/correção → review/refatoração → geração de guia de QA, evoluem junto não só o código, mas também a documentação e as instruções de teste
  • “Se funciona, está bom” não é um problema técnico, é um problema de cultura organizacional. Algumas empresas ainda valorizam código fácil de ler. Isso pode até virar vantagem competitiva
  • Eu invisto em automação de análise estática e dinâmica. Uso ativamente ferramentas de qualidade como regras de lint customizadas, verificação forte de tipos e mutation testing. Como review sozinho é lento e ineficiente, o essencial é a automação de feedback precoce
  • Esse tipo de postura não muda facilmente. Talvez seja melhor ir para um time que valorize qualidade de software

• Eu uso IA principalmente para código boilerplate ou para resolver problemas de documentação
  Já experimentei trabalho com agentes, mas ainda é difícil confiar no resultado. Mesmo assim, algumas pessoas dizem que “agora quase não escrevem mais código”. Essa diferença é interessante

  • Para mim, muitas vezes codar diretamente é mais rápido do que usar IA. O processo de planejar, mandar executar e validar acaba sendo mais lento. Mas, para refatorações em grande escala, a IA é muito mais rápida
  • Nos últimos meses, o desempenho dos agentes disparou. Agora já vai além de simples autocompletar e chega a implementar funcionalidades inteiras
  • Talvez isso possa ser explicado pela diferença entre os desenvolvedores que sentem um “estranhamento (eww)” ao ver código de IA e os que não sentem
  • No fim, fica claro que, dependendo do tipo de tarefa, há casos em que a IA se encaixa muito bem e outros em que não
  • Eu também não gosto do primeiro resultado, mas rodando o loop de review várias vezes a qualidade sobe de forma clara. Se fizer IAs revisarem umas às outras ou deixar os critérios de teste bem explícitos, melhora bastante

• Recentemente estou experimentando um loop de coding com agentes
  Por exemplo, no projeto fesh, o objetivo era “comprimir ainda mais um binário Linux”. Era um problema com testes claros, então servia bem para um loop de IA
  O que aprendi foi o seguinte:

  • O test harness é tudo. Sem um loop de validação, a direção se perde
  • É importante deixar a IA tentar coisas de forma experimental
  • É preciso manter um scratchpad em .md entre sessões para que o aprendizado continue
  • Testes são realmente importantes. A IA falha de maneiras estranhas, então é preciso usar ativamente geração automática de testes
  • Sem testes, não dá para confiar no resultado do loop. Um procedimento de verificação determinístico é indispensável
  • Foi útil registrar separadamente o log de decisões e o log de rejeições. Em especial, o rejections.md foi ainda mais valioso. É preciso deixar registrado “por que essa abordagem foi descartada” para a IA não repetir o mesmo erro
  • Em automação de navegador é parecido. Além da validação funcional, é preciso adicionar validação comportamental (parece humano?) para que se torne útil. E os logs em .md elevam muito a qualidade da sessão seguinte

• Seria bom que a seção sobre testes abordasse o problema dos “testes autoindulgentes” criados por LLMs
  Há casos em que o teste, na prática, não verifica nada, ou até passa com valores hardcoded. O ser humano precisa conduzir a IA para hábitos rigorosos de teste

  • Fiquei curioso sobre exemplos concretos. Parece não ser um simples erro de lógica, mas testes que à primeira vista parecem bons, porém na prática não significam nada
  • Teste ruim é mais perigoso do que não ter teste nenhum. Quando a confiança quebra uma vez, a fé em toda a suíte de testes desmorona
  • Por isso mutation testing é importante. Se o código é alterado e o teste ainda passa, então é um teste ruim
  • Basta pedir à IA para mudar de propósito parte do código e verificar se o teste falha. Se não falhar, é um teste inútil
  • Claro, nem com humanos é fácil fazer esse tipo de disciplina de teste acontecer

• Sempre que sai uma nova geração de LLM, dá a sensação de que todas as lições anteriores se tornam inválidas
  Estruturas complexas criadas para contornar limitações de modelos antigos, como o LangChain, ficaram desnecessárias depois do GPT-3.5. Em breve, talvez um agente único já seja suficiente para dar conta de tudo

  • Por isso, eu tento organizar padrões que não dependam da versão do modelo. Por exemplo, TDD red/green talvez logo passe a ser feito automaticamente pelo próprio modelo, mas o conceito em si continua útil
  • No fim, talvez tudo acabe convergindo para algo como ClaudeVM
    Ver artigo relacionado

• Há um ponto que costuma faltar nessas discussões sobre agent engineering
  Muitas lições são apresentadas como se fossem verdades universais, mas, na prática, elas variam de acordo com o tamanho do time, a maturidade da base de código, o nível de testes e a tolerância a risco. O importante é deixar claro “em que situações esse padrão funciona”

  • Por isso, em vez de um livro, eu organizei os padrões em formato de site. Pretendo atualizar continuamente e explicitar o escopo de aplicação
  • Quando você lida com várias codebases como consultor, percebe que o desempenho do Claude Code varia de forma extrema conforme a qualidade da codebase. Em projetos com tipagem forte e testes, ele funciona quase perfeitamente, mas em ambientes JavaScript frouxos, nem tanto
  • Ainda assim, alguns padrões são universais. Por exemplo, manter uma fonte da verdade independente (harness) vale em qualquer lugar. Ferramentas como showboat e rodney ajudam nisso

• Hoje em dia surgem dezenas de “frameworks de time de agentes” por dia
  É um período caótico de experimentação, como o começo da engenharia de software. Mas, no fim, alguns padrões vão acabar se estabelecendo como padrão.
  No nosso time, funcionou bem abordar isso como um time humano — primeiro escrever a especificação do produto (spec), refiná-la com IA e, a partir disso, passar para um fluxo de agentes com papéis separados

• Hoje dei uma aula de graduação sobre a evolução das arquiteturas de CPU e GPU
  No passado, a Lei de Moore fazia o hardware resolver tudo, mas agora a paralelização é o ponto central.
  A ideia do Simon de que “código é barato” é uma mudança de paradigma parecida com isso.
  Assim como o código eficiente mudou completamente na era do hardware paralelo, na era da IA o próprio processo de desenvolvimento vai mudar. Quem entender isso primeiro vai obter uma vantagem de 10x a 100x

• No nosso time, o mais prático foi um “loop com validações humanas no meio do caminho”
  Agentes totalmente autônomos muitas vezes passam nos testes, mas quebram invariantes implícitas.
  Por isso, fazemos o humano intervir logo antes de decisões irreversíveis.
  Mas fazer a IA entender “o que é irreversível” já é outro desafio.
  Além de documentos como CLAUDE.md, estamos procurando uma forma sistemática de transmitir regras implícitas da codebase