Componentes de um agente de programação

• Agente de programação é um sistema composto por um loop de controle e um software harness centrados em um LLM, repetindo escrita de código, execução e feedback
• O agent harness é responsável por gerenciamento de contexto, acesso a ferramentas, composição de prompts e controle de estado; o coding harness, especializado em tarefas de programação, gerencia repositórios, testes e verificação de erros
• Um agente de programação opera com seis componentes: contexto do repositório em tempo real, cache de prompt, acesso a ferramentas, gerenciamento de contexto, memória de sessão e delegação a subagentes
• Mesmo com o mesmo LLM, o desempenho e a experiência do usuário variam muito conforme a qualidade do design do harness, e um harness bem projetado oferece um ambiente de desenvolvimento contínuo e sensível ao contexto
• Mini Coding Agent é um exemplo mínimo implementado em Python puro dessa estrutura, com diferenças em relação ao OpenClaw quanto à especialização em programação e ao escopo operacional

---

Componentes de um agente de programação

• Agente de programação é um sistema composto por um loop de controle centrado em LLM e pelo software harness que o envolve, com uma estrutura que repete escrita, modificação, execução e feedback de código
• LLM é um modelo básico de previsão do próximo token, enquanto um modelo de raciocínio (reasoning model) é um LLM treinado para realizar mais raciocínio intermediário e verificação
• Um agente é um loop de controle que repete chamadas ao modelo, uso de ferramentas, atualização de estado e decisão de encerramento para atingir um objetivo
• O agent harness é a estrutura de software que envolve esse loop, sendo responsável por gerenciamento de contexto, acesso a ferramentas, composição de prompts e controle de estado
• O coding harness é uma forma especializada para trabalho com código, gerenciando contexto de repositório, execução de código, testes e verificação de erros

Relação entre LLM, modelo de raciocínio e agente

• O LLM pode ser comparado ao motor, o modelo de raciocínio a um motor aprimorado, e o agent harness ao sistema que controla esse motor
• LLMs e modelos de raciocínio podem executar tarefas de programação sozinhos, mas em ambientes reais de desenvolvimento é necessário lidar com contextos complexos como exploração do repositório, busca de funções, execução de testes e análise de erros
• O coding harness maximiza o desempenho do modelo e oferece uma experiência de programação muito mais poderosa do que uma interface simples de chat

Papel do coding harness

• É a camada de software que envolve o modelo e realiza montagem de prompts, exposição de ferramentas, rastreamento do estado dos arquivos, execução de comandos, gerenciamento de permissões, cache e armazenamento de memória
• Mesmo com o mesmo LLM, o desempenho e a experiência do usuário mudam drasticamente dependendo do design do harness
• Por exemplo, até um modelo open-weight como o GLM-5 pode apresentar desempenho semelhante ao de Codex ou Claude Code quando integrado a um harness nesse nível
• Há casos em que a OpenAI manteve modelos de pós-processamento específicos por harness, como GPT-5.3 e GPT-5.3-Codex

6 componentes centrais de um agente de programação

• 1. Contexto do repositório em tempo real (Live Repo Context)

  • O agente precisa reconhecer o estado atual do repositório Git, branch, documentação e comandos de teste
  • Instruções como “corrigir testes” mudam conforme a estrutura e o contexto do repositório, por isso é preciso coletar antes um resumo do repositório
  • Isso evita começar sempre do zero e garante uma base de trabalho estável (stable facts)

• 2. Estrutura do prompt e reutilização de cache (Prompt Shape and Cache Reuse)

  • Como resumo do repositório, descrição das ferramentas e instruções gerais mudam pouco, eles podem ser armazenados em cache como “prefixo estável de prompt (stable prompt prefix)”
  • Em vez de remontar todo o prompt a cada solicitação, apenas as partes alteradas são atualizadas
  • Em sessões repetidas, isso reduz desperdício computacional e mantém a consistência das respostas

• 3. Acesso e uso de ferramentas (Tool Access and Use)

  • Em vez de apenas sugerir comandos, o modelo pode executar comandos reais por meio do conjunto de ferramentas definido pelo harness
  • Cada ferramenta possui formatos de entrada e saída claros e limites bem definidos, com validação e aprovação antes da execução
  • Ex.: “é uma ferramenta conhecida?”, “os argumentos são válidos?”, “o caminho de trabalho está dentro do workspace?”
  • Isso melhora segurança e confiabilidade; embora reduza a liberdade do modelo, aumenta a utilidade prática

• 4. Minimização do inchaço de contexto (Minimizing Context Bloat)

  • Em sessões longas, leituras repetidas de arquivos, logs e saídas de ferramentas podem causar problemas por excesso de tamanho do prompt
  • O harness administra isso com duas estratégias
    • Clipping: encurta textos longos, logs e anotações para um tamanho fixo
    • Summarization: comprime e resume o histórico antigo da conversa
  • Eventos recentes são mantidos em detalhe, enquanto informações antigas passam por remoção de redundâncias e compressão
  • Como resultado, a qualidade do contexto afeta mais o desempenho real do que a própria qualidade do modelo

• 5. Memória de sessão estruturada (Structured Session Memory)

  • O agente separa o estado entre memória de trabalho (working memory) e transcrição completa da conversa (full transcript)
  • O registro completo inclui todas as requisições, respostas e saídas de ferramentas, permitindo retomar a sessão
  • A memória de trabalho armazena em forma resumida as informações importantes do momento, como tarefa atual, arquivos principais e notas recentes
  • A transcrição compactada (compact transcript) serve para reconstruir o prompt do modelo, enquanto a memória de trabalho mantém a continuidade da tarefa

• 6. Delegação com subagentes limitados (Delegation With Bounded Subagents)

  • O agente principal cria subagentes para processar tarefas auxiliares em paralelo
  • Ex.: separar em subtarefas a localização da definição de um símbolo, o conteúdo de um arquivo de configuração ou a causa da falha de um teste
  • Os subagentes herdam apenas o contexto necessário e operam com restrições como somente leitura e limite de profundidade recursiva
  • Tanto Claude Code quanto Codex oferecem suporte a subagentes, definindo limites por escopo da tarefa e profundidade de contexto

Resumo dos componentes

• Os seis componentes estão fortemente conectados entre si, e a qualidade do design do harness determina a eficiência do uso do modelo
• Um coding harness bem projetado oferece um ambiente de suporte ao desenvolvimento muito mais contínuo e sensível ao contexto do que um simples chat com LLM
• Mini Coding Agent (https://github.com/rasbt/mini-coding-agent) é um exemplo mínimo implementado em Python puro dessa estrutura

Comparação com OpenClaw

• OpenClaw está mais próximo de uma plataforma geral de agentes do que de um assistente dedicado exclusivamente à programação
• Pontos em comum:
  • Uso de arquivos de prompt e instruções no workspace (AGENTS.md, TOOLS.md etc.)
  • Inclusão de arquivos de sessão em JSONL, compressão de conversa e gerenciamento de sessão
  • Possibilidade de criar sessões auxiliares e subagentes
• Diferenças:
  • Agentes de programação são otimizados para exploração de repositório, edição de código e execução de ferramentas locais
  • OpenClaw prioriza operação de agentes de longo prazo entre múltiplos canais e workspaces

Apêndice: anúncio de novo livro

• Concluída a escrita de Build A Reasoning Model (From Scratch), com acesso antecipado (Early Access) já disponível
• A editora está trabalhando no layout com meta de publicação no verão
• O livro é estruturado em torno de uma abordagem para compreender mecanismos de raciocínio de LLMs por meio de implementação direta

[GN⁺]

Comentários do Hacker News

• context longo continua sendo caro, e se houver muita informação desnecessária, isso vira ruído
  Por isso, acho que geração baseada em spec é melhor do que programação conversacional
  O Ossature que eu fiz segue a abordagem oposta. Primeiro você escreve uma spec descrevendo o comportamento; antes de gerar código, ele audita lacunas ou contradições e gera um build plan em TOML especificando quais seções da spec e quais arquivos cada tarefa referencia
  O LLM vê só o necessário, sem acúmulo de histórico de conversa. Todos os prompts e respostas são salvos em disco, então a rastreabilidade fica garantida automaticamente
  Recentemente, construí um emulador de CHIP-8 inteiramente só com spec dessa forma, e também há projetos de exemplo

  • Tenho pensado bastante que os agentes de programação de hoje não têm uma fonte central de verdade
    Antes, todos em uma equipe sabiam o que estava sendo construído, mas agora o agente recomeça do zero toda vez
    Por isso, vejo o fluxo chat → spec → code como o futuro. A etapa spec → code precisa rodar sem intervenção humana
    Se a especificação estiver ambígua, ele deve perguntar claramente ao humano e então gerar o código com base nisso
    Hoje, pedidos ambíguos só se repetem, e o humano também não aprende por que isso acontece. “memory” ou arquivos de agente são apenas paliativos
  • Também estou construindo algo parecido. Ainda não está público, mas é um motor de workflow centrado em spec
    Em vez de conversa, forneço ao LLM um context projetado a partir do código e da spec, e componho esse context de forma diferente em cada etapa
    Isso evita drift causado por context acumulado, e meu código, não o LLM, controla o workflow
    Achei interessante a ideia de usar TOML como artifact de passagem entre etapas e pretendo me inspirar nela
  • Penso da mesma forma. O Agent A modifica apenas a spec, e o Agent B faz o build olhando apenas para a spec
    O usuário pode revisar o diff criado pelo Agent A e se livra da validação repetitiva de código
    O ponto central é sempre preservar a intenção (intent). É preciso armazenar a especificação e o contexto como estão
    O custo deve ser 2 a 3 vezes maior, mas no longo prazo parece mais eficiente
  • Workflows baseados em chat são cansativos e perdem muita informação
    Acho a abordagem baseada em spec muito melhor. Fiquei curioso sobre como entra a participação humana — se você edita spec e audit em paralelo, qual é a taxa de sucesso na geração de código e se pretende aplicar isso também a código existente
  • Também estou tentando começar pela spec e depois iterar o código com a combinação Claude Code + Cucumber
    Fiquei curioso para saber como o Ossature difere dessa abordagem

• É surpreendente ter extraído o potencial dos LLMs só com uma state machine simples e uma abordagem em bash

  • Por isso estou montando eu mesmo um agente de programação isolado
    O ecossistema de agentes hoje está cheio de recursos excessivos e decisões ruins
    Há 10 anos se dizia que ferramentas assim exigiam responsabilidade; agora estamos num período confuso, misturando medo e hype
  • No fim, o essencial é engenharia de prompt/context
    O modelo já tem o conhecimento, mas para levá-lo a agir de forma prática, o desenho do context é crucial
    Traduzir a solicitação do usuário para o nível de um desenvolvedor experiente e conectar as ferramentas necessárias parece um caminho promissor
    Mesmo modelos open source, com um agente bem otimizado e um pouco de tuning, podem competir muito bem
  • Se você olhar o vazamento do Claude Code, verá que a estrutura não é simples
    É preciso um harness complexo, mas é isso que faz o LLM funcionar de forma determinística como ferramenta
  • Muitos agentes CLI acham que só acesso a bash não basta, então estão enfiando à força todo tipo de recurso numa JavaScript TUI
  • Em vez de bash, usar Python foi mais útil
    Dá para montar livremente a lógica que você quiser, em vez de depender de pipelines

• O exemplo é conciso e claro
  Não uso agentes de programação, mas este texto ajuda a entender a essência dos agentes de programação
  Mostra bem como até um código útil de apenas 1k LOC pode virar uma bagunça de 500k LOC

• Muita gente já está conectando modelos abertos como GLM-5 ao Claude Code ou ao Codex CLI
  A documentação oficial do GLM também recomenda isso

  • Não chega ao nível do Opus, mas a combinação de GLM e Qwen3.5-plus é excelente o bastante para projetos pessoais

• O texto foi impressionante. Eu criei um agente não voltado a código baseado em email, e o princípio é parecido
  Em cada loop de email, o context recomeça do zero, o que resolve naturalmente o problema de acúmulo de context
  É importante equilibrar o context que entra no prompt inicial e o context separado em ferramentas
  Também é preciso considerar caching e custo de tokens
  Escrevi os detalhes neste post do meu blog

• Não gosto da palavra “harness”. Fico pensando se não haveria um termo melhor

  • Ela é usada com frequência no sentido de shim para controlar um programa, como em “test harness” ou “fuzzing harness”
  • Ironicamente, hoje tudo virou “app”, mas o app para executar LLMs não é chamado de “app”
  • No fim, “harness” é só uma forma elegante de dizer scaffolding
  • Aí também houve a reação de pedir que sugerissem uma palavra alternativa

• tool output truncation é muito eficaz para reduzir o inchaço do context
  Eu monto o context com base em SQLite e, quando necessário, restauro chamadas de ferramenta truncadas por ID de mensagem
  Os experimentos relacionados estão documentados aqui

• Rodar o Claude Code com outros modelos é algo comum
  Também aparece na documentação de exemplo
  Mas, pela minha experiência, ainda não alcança o nível dos modelos da Anthropic

  • Dependendo do projeto, até modelos baratos como MiMo V2 Pro dão conta de 70% a 80%, mas em muitos casos o Sonnet é muito melhor
    O Opus só vale o custo em cerca de 5% dos casos
    Achei o OpenCode muito melhor que o Claude Code, então comprei créditos de API no OpenRouter
    O OpenCode já é suficientemente poderoso apenas com comandos customizados e definições simples de agente
    Se você definir o workflow com AGENTS.md, ROADMAP.md etc., isso basta para a maioria dos projetos
    Em vez de um harness complexo, acho que uma estrutura flexível responde melhor às mudanças dos modelos mais novos
  • Fico curioso se os modelos da Anthropic são melhores apenas por causa da qualidade do modelo em si, ou também por causa da otimização do harness

• O avanço dos agentes de programação vem mais da melhora da estrutura ao redor (scaffolding) do que do modelo em si
  Quando você tem ferramentas, context do repositório e uma máquina de estados simples, o gargalo passa a ser a qualidade do context

• O texto foi impactante. Eu também costumo explicar agentes de programação com a analogia de motor/carro
  Se quiser experimentar os componentes básicos, vale conferir o OpenHands software-agent-sdk