Building AI Coding Agents for the Terminal: Scaffolding, Harness, Context Engineering, and Lessons Learned

Este artigo apresenta o OPENDEV, um agente de codificação de linha de comando de código aberto que utiliza uma arquitetura composta com roteamento de modelos especializado, separação de planejamento e execução, e gerenciamento adaptativo de contexto para fornecer assistência autônoma segura e eficiente no terminal.

O essencial

Imagine que você tem um estagiário de programação extremamente inteligente, que lê livros inteiros em segundos e escreve código como um poeta. O problema é que esse estagiário tem uma memória de curto prazo muito curta: se a conversa ficar longa, ele esquece o que você pediu no início, se perde em detalhes e, às vezes, comete erros bobos porque não consegue "enxergar" o quadro todo.

O OPENDEV é a solução para esse problema. É um novo tipo de assistente de programação que vive no seu terminal (a tela preta de comandos), em vez de ficar preso dentro de um editor de código visual. O artigo descreve como eles construíram esse "estagiário" para que ele seja autônomo, seguro e capaz de trabalhar em projetos grandes sem ficar confuso.

Aqui está a explicação dos principais conceitos, usando analogias do dia a dia:

1. O Problema: A "Memória de Elefante" vs. A "Memória de Peixe"

Os modelos de IA atuais são como elefantes que lembram de tudo, mas têm uma "bolsa" (janela de contexto) limitada para carregar informações. Se você colocar muita coisa na bolsa, ela rasga.

• A analogia: Imagine que você está dando instruções para um cozinheiro. Se você der 500 receitas de uma vez, ele esquece a primeira. Se você der apenas a receita atual, ele não sabe o que já foi feito.
• A solução do OPENDEV: Eles criaram um sistema de "Compactação Adaptativa". É como se o assistente tivesse um organizador que, a cada 10 minutos, olha para a pilha de papéis na mesa e diz: "Ok, a receita antiga não é mais importante, vou transformá-la em um resumo de uma linha e guardar no arquivo morto". Assim, a mesa (a memória) fica sempre limpa, mas a informação crucial nunca é perdida.

2. A Arquitetura: Não é um Robô, é uma Equipe

Muitas pessoas acham que a IA é um único cérebro gigante. O OPENDEV é diferente: é uma empresa com departamentos especializados.

• O Arquiteto (Planejador): Antes de tocar em qualquer código, esse "sub-agente" apenas lê o projeto e desenha um plano. Ele não pode construir nada, só planejar. É como um arquiteto que desenha a casa antes de o pedreiro começar a colocar tijolos.
• O Explorador (Code Explorer): Se o projeto é grande, ele manda um "detetive" para ler os arquivos e entender como as coisas se conectam, sem mexer em nada.
• O Executor (Agente Principal): Só depois que o plano é aprovado e o detetive voltou com as informações, o executor principal entra em ação para escrever o código.
• Por que isso é legal? Se o executor errar, o Arquiteto não fica confuso. Cada um tem sua própria "caixa de ferramentas", o que evita que o sistema tente fazer tudo ao mesmo tempo e se perca.

3. Segurança: O "Cinto de Segurança" em 5 Camadas

Como esse assistente pode apagar arquivos ou rodar comandos perigosos no seu computador, eles não confiaram apenas em "pedir desculpas" se algo der errado. Eles criaram um sistema de segurança em camadas, como um castelo medieval:

1. O Portão (Sistema): O assistente nem vê as ferramentas perigosas se ele estiver apenas planejando. Se a ferramenta não está na lista dele, ele não sabe que ela existe.
2. O Guarda (Aprovação): Para coisas arriscadas (como apagar uma pasta), o sistema pausa e pergunta: "Ei, você tem certeza?".
3. O Validação (Ferramenta): Antes de executar, a ferramenta verifica se o comando não é um vírus (como rm -rf /).
4. O Backup (Git Sombra): Se o assistente apagar algo por engano, o sistema tem um "botão de desfazer" mágico que restaura o arquivo exatamente como estava antes, sem precisar que você saiba usar Git.
5. O Monitor (Hooks): Scripts externos podem vigiar o que está acontecendo e parar o assistente se ele fizer algo estranho.

4. O Segredo da Longa Duração: "Lembrar de Lembrar"

Um dos maiores problemas é que, após 30 minutos de conversa, a IA esquece a regra inicial: "Sempre teste o código antes de salvar".

• A analogia: É como se você estivesse dirigindo e, após 2 horas, começasse a ignorar a placa de "Pare".
• A solução: O OPENDEV usa "Lembretes do Sistema". Em vez de repetir a regra inteira o tempo todo (o que ocuparia espaço), o sistema injeta uma mensagem curta e direta no momento exato da decisão: "Ei, você esqueceu de testar antes de salvar!". Isso funciona como um lembrete de um colega de trabalho que passa por você e diz: "Não esqueça de trancar a porta!".

5. Economia e Eficiência: "Não leve o elefante inteiro para a festa"

Usar IA custa dinheiro e tempo. O OPENDEV é esperto sobre o que mostra para a IA.

• Ferramentas Preguiçosas (Lazy Loading): Em vez de mostrar para a IA uma lista de 100 ferramentas possíveis (o que ocuparia metade da memória), o sistema mostra apenas as 5 que ele acha que você vai usar. Se você precisar de mais, ele "busca" as outras na hora. É como ter um menu de restaurante onde só aparecem os pratos que você pediu, em vez de mostrar o cardápio inteiro de 500 páginas.
• Múltiplos Cérebros: O sistema pode usar um cérebro "rápido e barato" para tarefas simples (como listar arquivos) e um cérebro "lento e caro" apenas para o raciocínio complexo. Isso economiza muito dinheiro.

Resumo Final

O OPENDEV não é apenas um "chatbot de código". É uma plataforma de engenharia de software autônoma que:

1. Planeja antes de agir (para não quebrar coisas).
2. Limpa sua memória constantemente (para não se perder em projetos longos).
3. Tem segurança em camadas (para você não perder seus dados).
4. Trabalha no terminal (onde os desenvolvedores realmente vivem).

A lição principal do artigo é que, para criar uma IA que trabalha sozinha por horas, não basta ter um modelo de linguagem inteligente; é preciso construir um sistema de gestão ao redor dele que cuide da memória, da segurança e do foco, exatamente como um gerente de projeto faria com uma equipe humana.

Resumo técnico

Título: Construindo Agentes de Codificação com IA para o Terminal: Scaffolding, Harness, Engenharia de Contexto e Lições Aprendidas

1. O Problema

O cenário de assistência de codificação com IA está passando de plugins complexos de IDE para agentes nativos de terminal (CLI). Embora os agentes autônomos tenham potencial para tarefas de desenvolvimento de longo prazo, a implementação prática enfrenta três desafios de engenharia fundamentais que os modelos de ponta (frontier models) ainda lutam para resolver em benchmarks como Terminal-Bench e LongCLI-Bench:

1. Gestão de Janela de Contexto Finita: Sessões de desenvolvimento reais frequentemente excedem o orçamento de tokens do modelo, levando à degradação do raciocínio e ao "esquecimento" de instruções iniciais (fade-out).
2. Segurança em Execução Arbitrária: Agentes que executam comandos de shell e modificam arquivos podem realizar operações destrutivas. Mecanismos de segurança simples (como verificações de permissão em tempo de execução) são insuficientes contra modelos que podem "argumentar" para contornar regras.
3. Escalabilidade e Descoberta de Ferramentas: Adicionar novas capacidades (ferramentas externas) sem sobrecarregar o orçamento de tokens do prompt inicial é difícil. A maioria dos sistemas existentes é de código fechado ou focada em benchmarks automatizados, carecendo de relatórios técnicos sobre decisões de design para uso interativo diário.

2. Metodologia e Arquitetura (OPENDEV)

O artigo apresenta o OPENDEV, um agente de linha de comando de código aberto projetado especificamente para este novo paradigma. A arquitetura é baseada no conceito de Sistemas de IA Compostos (Compound AI Systems), onde o desempenho é alcançado pela orquestração de múltiplos modelos, recuperadores e ferramentas, em vez de depender de uma única chamada de LLM.

A arquitetura do OPENDEV é organizada em quatro camadas principais:

• Camada de Entrada e UI: Suporta interfaces TUI (Terminal) e Web, gerenciando entrada de usuário e aprovações.
• Camada de Agente (Core):
  • Scaffolding (Andaime): Construção pré-execução do agente, compilando prompts de sistema, esquemas de ferramentas e registrando subagentes antes da primeira interação.
  • Harness (Armadilha/Orquestrador): Camada de orquestração em tempo de execução que gerencia o ciclo de raciocínio, despacho de ferramentas, gestão de contexto e segurança.
  • Ciclo ReAct Estendido: O agente opera em um loop que inclui fases opcionais de Pensamento (raciocínio sem acesso a ferramentas) e Auto-crítica, separando a deliberação da ação para evitar ações prematuras.
  • Arquitetura Multi-Modelo: Diferentes fases (ação, pensamento, crítica, visão, compactação) podem usar modelos LLM diferentes, otimizando custo e latência.
• Camada de Ferramentas e Contexto:
  • Registro de Ferramentas: 35 ferramentas internas (arquivos, shell, web, LSP) mais descoberta dinâmica via MCP (Model Context Protocol) com carregamento preguiçoso (lazy loading).
  • Engenharia de Contexto: Inclui compactação adaptativa, memória dual (episódica e de trabalho) e lembretes do sistema baseados em eventos.
• Camada de Persistência: Armazena histórico de conversas, configurações e logs de operações para reversão (undo).

3. Contribuições Principais

1. Arquitetura de IA Composta com Roteamento por Fluxo de Trabalho:

   • Cada fase cognitiva (planejamento, execução, pensamento, crítica) pode ser vinculada a um modelo LLM específico configurável pelo usuário. Isso permite usar modelos baratos e rápidos para resumos e modelos avançados para raciocínio complexo, sem alterar o código.

2. Pipeline de Execução ReAct Estendido:

   • Introdução de uma fase explícita de Pensamento (sem ferramentas) antes da ação, permitindo raciocínio estratégico profundo.
   • Implementação de Auto-crítica seletiva para tarefas complexas.
   • Detecção de "Doom-Loop" (loops de falha) baseada em hash de ferramentas e argumentos, interrompendo ciclos repetitivos antes que consumam recursos.

3. Engenharia de Contexto como Prioridade (Context Engineering):

   • Compactação Adaptativa de Contexto (ACC): Em vez de uma compactação de emergência única, o sistema usa um pipeline de 5 estágios (de 70% a 99% de uso de tokens), variando de mascaramento de observações antigas até compactação total baseada em LLM.
   • Memória Dual: Separa o contexto de longo prazo (resumo episódico) do contexto de curto prazo (últimas trocas literais) para manter a precisão operacional e a estratégia.
   • Lembretes do Sistema (System Reminders): Em vez de depender apenas do prompt inicial, o sistema injeta mensagens curtas e direcionadas (como mensagens de usuário) no momento exato da decisão para combater a degradação da atenção em sessões longas.

4. Segurança em Profundidade (Defense-in-Depth):

   • Gating de Esquema (Schema Gating): A principal inovação de segurança. Ferramentas perigosas (como escrita de arquivos) são removidas do esquema do agente de planejamento. O agente não pode tentar o que não vê.
   • Camadas Múltiplas: Inclui guardrails no prompt, restrições de esquema, sistema de aprovação em tempo de execução, validação de ferramentas e hooks de ciclo de vida.
   • Reversibilidade: Sistema de "undo" baseado em snapshots de Git (shadow git) para reverter alterações de arquivo passo a passo.

5. Descoberta Preguiçosa de Ferramentas (Lazy Discovery):

   • Uso do protocolo MCP para descobrir ferramentas externas apenas quando necessário, evitando que o contexto inicial seja inundado com definições de ferramentas não utilizadas (redução de overhead de tokens de ~40% para <5%).

4. Resultados e Lições Aprendidas

O artigo não foca em métricas de benchmark quantitativo (como taxa de resolução no SWE-bench), mas sim em lições de engenharia transferíveis derivadas da construção de um sistema de produção:

• Contexto é um Orçamento, não um Buffer: A redução de contexto deve ser graduada. Compactar agressivamente apenas quando o limite é atingido causa perda de informação. O uso de "mascaramento" e "pruning" rápido é mais eficiente.
• Separar Pensamento de Ação: Modelos tendem a agir rapidamente quando têm ferramentas disponíveis. Remover o acesso a ferramentas durante a fase de pensamento melhora significativamente a qualidade do raciocínio.
• Segurança Estrutural vs. Runtime: Tornar ferramentas inseguras invisíveis (removendo-as do esquema) é mais robusto do que tentar bloquear chamadas em tempo de execução, pois o modelo não pode "raciocinar" sobre contornar algo que não sabe que existe.
• Design para Imprecisão: Ferramentas devem absorver a imprecisão dos LLMs (ex: o editor de arquivos usa correspondência fuzzy de 9 etapas para lidar com diferenças de indentação ou espaços em branco, em vez de falhar em correspondências exatas).
• Lembretes no Ponto de Decisão: Instruções no início do prompt são esquecidas. Lembretes injetados como mensagens de usuário no momento da decisão são mais eficazes para manter o comportamento desejado.

5. Significado e Impacto

O OPENDEV serve como um blueprint técnico para a próxima geração de agentes de codificação autônomos. Ao documentar decisões de design que muitas vezes são proprietárias em sistemas comerciais (como o Claude Code), o artigo preenche a lacuna entre a pesquisa acadêmica e a prática industrial.

• Mudança de Paradigma: Valida a transição de assistentes reativos em IDEs para agentes autônomos nativos de terminal, onde o agente tem controle total sobre o ambiente de desenvolvimento.
• Sustentabilidade de Longo Prazo: As técnicas de engenharia de contexto (compactação adaptativa, memória dual, lembretes) são essenciais para permitir que agentes operem em tarefas de desenvolvimento complexas que duram horas ou dias, superando as limitações atuais de janelas de contexto.
• Segurança Prática: A abordagem de "segurança por design" (schema gating) oferece um modelo para como permitir autonomia sem comprometer a segurança do código e dos dados do usuário.

Em resumo, o papel argumenta que a construção de agentes de IA eficazes não depende apenas de modelos LLM maiores, mas de arquiteturas compostas inteligentes que gerenciam rigorosamente o contexto, separam o raciocínio da ação e impõem segurança através de restrições estruturais.