Engenharia agêntica: guia prático para agentes de código confiáveis

O que é engenharia agêntica

Na definição do autor, é colocar agentes de código dentro de um sistema de engenharia que torna explícitos contexto, escopo, validação, evidências e revisão humana: o modelo pode planejar e escrever código, mas não decide que o próprio trabalho está correto. A distinção relevante não é se um LLM tocou o código, e sim onde vive a confiança. "Prompt, olhada, publicar e torcer" é vibe coding; requisitos revisáveis, acesso delimitado, checagens mecânicas, evidências registradas e um humano responsável pelo resultado definem engenharia com agentes.

O texto lembra que Andrej Karpathy ajudou a popularizar o termo no início de 2026, ao refletir sobre como programar com agentes tinha ido além do seu "vibe coding", e cita Simon Willison sobre os dois conceitos se aproximando conforme os modelos melhoram. O perigo apontado não é usar mais autonomia, e sim deixar sucessos repetidos removerem silenciosamente os controles que revelam quando a próxima execução está errada.

Os componentes do fluxo confiável

Tudo está implementado no my-pi, setup de agente de código do autor construído sobre Pi:

• Recuperar a fonte da verdade: inspecionar repositório e instruções locais, achar a implementação e seus testes, pesquisar fontes primárias e declarar premissas. Ferramentas como o pirecall (histórico pesquisável de sessões) e um sidecar SQLite para saídas longas de ferramentas tornam o contexto recuperável, não acumulado - arquivo gigante de instruções pode abafar a própria tarefa.
• Tornar conhecimento executável: um arquivo AGENTS.md ajuda nas regras estáveis, mas não é campo de força; regras importantes viram tipos, linters, testes, hooks ou comandos de CI, porque prosa não impede um atalho plausível de virar convenção local.
• Delimitar tarefas arriscadas fora da conversa: um harness externo registra caminhos permitidos, operações proibidas, comandos de validação, status e evidências, separando uma fronteira fixa de confiança de um andaime interno editável com auditoria. Envolver uma correção de grafia nesse esquema é cerimônia, não rigor.
• Devolver validação ao agente: erros de tipo, testes, lint, build e diagnósticos LSP durante o trabalho; a checagem final deve ser comando independente ou resultado observável, nunca "o agente disse que está bom" - teste verde que só valida mock não prova a função.
• Registrar rastros e avaliar resultados: telemetria local e evals focados respondem se o agente usou a ferramenta nova ou achou a fonte certa; avalia-se o estado do repositório e a jornada do usuário, não a confiança do resumo, como no exemplo da Anthropic do agente de reservas de voo, em que importa se a reserva existe.
• Tratar segredos e permissões como sistema: injeção de prompt pode chegar por páginas, issues, READMEs de dependências ou respostas de ferramentas; valem acesso mínimo e aprovação humana para ações destrutivas ou públicas. O nopeek permite rodar processos que dependem de credenciais sem imprimir o .env inteiro na conversa.
• Usar mais agentes só quando o trabalho for paralelo de verdade: cinco agentes disputando os mesmos arquivos criam problema de coordenação chamado de escala. No Team Mode do autor, o foco é propriedade, entregas duráveis e revisão explícita - delegação não transfere responsabilidade.

Uso real, números e fragilidades

Sem benchmark limpo para afirmar ganho de velocidade, o autor apresenta evidência operacional: entre 28 de junho e 25 de julho de 2026, agentes criaram 173 task harnesses registrados em 104 sessões e 10 projetos reais; 144 alcançaram estado concluído ao menos uma vez, 155 gravaram evidência de validação ou revisão, e o mecanismo de aplicação bloqueou ações 133 vezes em 69 sessões. Os números não provam que toda mudança concluída era boa, mas mostram uso fora de demonstração e fronteiras que capturaram comportamento real. Fragilidades expostas: padrões amplos demais de comandos proibidos, planos exigindo emendas legítimas mais do que o previsto, estado obsoleto de tarefas confundindo sessões seguintes, harnesses que falharam ainda demandando interpretação humana e tarefas de baixo risco ficando mais lentas com cerimônia excessiva.

O que não funciona

Repetir "tome cuidado" e "garanta que os testes passem" vale por um turno e não cria controle durável; carregar todo o contexto disponível torna o sinal relevante mais difícil de achar; autorevisão não é evidência independente, pois a mesma suposição errada pode atravessar planejamento, implementação e revisão que compartilham contexto; automatizar o ponto pouco claro rende mais saída, não mais clareza - às vezes o caminho é pesquisa, discussão e protótipo pequeno.

Começo pequeno e conclusão

O conselho é partir de uma falha recorrente: escrever a condição de sucesso observável, adicionar a checagem determinística mais barata, expô-la ao agente, manter instruções curtas, restringir acessos, registrar evidências e revisar o sistema após cada falha, somando maquinário só quando risco ou repetição justificarem. O objetivo não é automação máxima, e sim o menor fluxo que torna o resultado confiável. O melhor modelo de código vai mudar; o fluxo útil deve sobreviver à troca. O modelo é o trabalhador rápido e probabilístico; repositório, ferramentas, checagens e revisão formam o sistema de engenharia - a parte em que o autor diz confiar.