Aider: um agente de desenvolvimento em CLI

#O que é Aider e o que ele faz no seu repositório

Aider é um assistente de programação via linha de comando, open source, que se apresenta como programação em par com uma IA no terminal. Você executa o comando aider em um repositório Git, descreve uma alteração em linguagem natural e ele propõe modificações de arquivos, as aplica e as salva em um commit. Ele funciona com modelos hospedados (Claude, GPT, DeepSeek) assim como com modelos locais servidos por Ollama ou LM Studio, tornando-se um dos poucos agentes de código utilizáveis sem que uma linha do seu projeto saia da máquina. O repositório oficial ultrapassa 49.000 estrelas no GitHub.

Três coisas o diferenciam de um simples chat. Primeiro, ele mantém um mapa do repositório: a cada requisição, envia ao modelo uma lista dos arquivos com suas classes, funções e assinaturas principais, para que o modelo saiba onde procurar sem que você precise mostrar tudo. Em seguida, ele está integrado ao Git: cada alteração se torna um commit reversível. Por fim, ele executa repetidamente os comandos que você fornece, como linter e testes, e tenta corrigir o que falha. Ele não é um agente autônomo que explora a web ou inicia servidores: é um editor de código guiado pela conversa.

#Instalar Aider

O método oficial mais curto é o pacote aider-install, que instala o Aider em um ambiente Python isolado e, se necessário, baixa uma versão de Python compatível. O pré-requisito é um Python entre 3.8 e 3.13 para esse caminho. Existem instaladores em uma linha, baseados em uv, para macOS, Linux e Windows. A receita antiga com pipx continua funcionando, mas a documentação atual recomenda aider-install.

python -m pip install aider-install
aider-install

# Vérifier
aider --version

Em seguida, acesse o diretório raiz do seu projeto. Se o diretório não for um repositório Git, o Aider oferece a opção de criar um, mas é melhor inicializá-lo você mesmo: toda a rede de segurança descrita mais adiante depende do Git.

#Conectar ao Ollama sem se atrapalhar com o contexto

A documentação oficial do Aider para Ollama se resume a quatro passos: definir a variável OLLAMA_API_BASE (o endereço habitual é http://127.0.0.1:11434), baixar o modelo com ollama pull, iniciar o servidor e então executar aider com o prefixo ollama_chat/ antes do nome do modelo. O prefixo ollama_chat/ é explicitamente recomendado em vez de ollama/.

export OLLAMA_API_BASE=http://127.0.0.1:11434
ollama pull devstral:24b
OLLAMA_CONTEXT_LENGTH=8192 ollama serve

# Dans un autre terminal, à la racine du projet
aider --model ollama_chat/devstral:24b

A armadilha mais custosa é a janela de contexto. O Ollama usa, por padrão, 2.000 tokens de contexto, o que é minúsculo para um agente de código, e, ponto decisivo, descarta silenciosamente o que ultrapassa esse limite. Sem saber, você pode estar conversando com um modelo que só recebeu o início dos seus arquivos. O Aider limita o problema: por padrão, ele próprio ajusta a janela do Ollama ao tamanho de cada requisição mais 8.000 tokens para a resposta. Se você preferir um tamanho fixo, precisa usar um arquivo de configurações de modelo, e não o arquivo principal de configuração.

- name: ollama_chat/devstral:24b
  extra_params:
    num_ctx: 32768

O contexto tem um custo em memória: o cache KV aumenta com a janela, e um modelo de 24 bilhões de parâmetros que já ocupa cerca de 14 GB em Q4 deixa pouca margem em uma placa de 16 GB. Os guias sobre a janela de contexto e sobre a quantização do cache KV fornecem as ordens de grandeza.

#Qual modelo local para Aider

Aider é tão bom quanto o modelo que o controla, e a dificuldade é dupla: o modelo precisa raciocinar sobre o código e respeitar um formato de edição rígido. Um modelo que não segue esse formato gera alterações que a ferramenta não consegue aplicar. O ranking público do Aider, baseado em 225 exercícios do Exercism em seis linguagens, mede justamente essa dupla capacidade; ele é dominado por modelos hospedados muito grandes, e os modelos que cabem em um computador pessoal têm posições consideravelmente inferiores. Consulte esse ranking antes de esperar um resultado de nível de nuvem.

Para uma máquina local, o Devstral 24B, publicado pela Mistral AI e pela All Hands AI, é um ponto de partida coerente: foi projetado para agentes de código, pesa 14 GB na biblioteca Ollama e anuncia uma janela de 128.000 tokens. Em uma GPU de 12 GB ou menos, é necessário recorrer a um modelo menor e aceitar mais erros de formato. O guia "Melhor LLM local para programar" compara os candidatos atuais; este guia não estabelece um ranking fixo, pois ele muda rápido demais.

#Uma primeira alteração, do prompt ao commit

1. 01
   Adicionar os arquivos corretos

   Execute aider passando os arquivos a serem modificados, por exemplo, aider src/api.py src/models.py. Os arquivos adicionados são aqueles que ele pode editar; ele conhece o restante do repositório por meio do mapa.
2. 02
   Descrever a alteração com precisão

   Escreva uma solicitação completa: «Adicione um endpoint GET /users/:id que retorne o usuário, ou um erro 404 se ele não existir». Uma solicitação vaga produz um diff vago.
3. 03
   Reler o diff

   Aider exibe as alterações e as aplica. Veja com /diff antes de continuar: é o momento de recusar, não depois de mais três solicitações.
4. 04
   Verificar o commit

   Cada edição é registrada com uma mensagem descritiva. Se o resultado for ruim, /undo anula o último commit feito por Aider.
5. 05
   Avançar em pequenas etapas

   Peça em seguida os testes, o tratamento do caso-limite e o registro de logs, uma etapa de cada vez. Etapas pequenas mantêm o contexto curto e o diff legível.

#Os comandos de chat que importam

Aider oferece dezenas de comandos que começam com uma barra oblíqua; poucos deles bastam para trabalhar. A regra geral: o que você não adicionou ao chat não pode ser modificado, mas o mapa do repositório permite que o modelo saiba que outros arquivos existem.

/add et /drop

Adicionam ou removem arquivos do chat. Remover os arquivos que deixaram de ser necessários libera contexto, o que é muito importante com um modelo local.

/read-only

Adiciona um arquivo apenas como referência: o modelo pode lê-lo, mas não editá-lo. Útil para um arquivo de convenções ou um contrato de interface.

/ask, /code, /architect

Alteram o modo de chat para uma mensagem ou de forma persistente com /chat-mode.

/run et /test

/run executa um comando shell e pode enviar a saída para o chat; /test executa o comando de teste e adiciona a saída ao chat se ele falhar, o que dispara uma correção.

/diff et /undo

/diff mostra as alterações desde sua última mensagem; /undo desfaz o último commit, se ele tiver sido feito pelo Aider.

/tokens

Informa o número de tokens usados pelo contexto atual: um hábito a adotar para entender por que um modelo local "esquece".

/map

Exibe o mapa do repositório enviado ao modelo.

#Os modos de chat: code, ask, architect

Aider distingue quatro modos de chat. O modo code, o padrão, modifica seus arquivos. O modo ask discute o código sem nunca modificá-lo. O modo architect usa dois modelos: um modelo arquiteto propõe a solução, depois um modelo editor a traduz em modificações precisas nos arquivos. O modo help responde a perguntas sobre o próprio Aider. Não existe um modo intermediário chamado "paired"; a combinação de um modelo forte e um modelo rápido é configurada com as opções --model e --editor-model.

O fluxo recomendado pela documentação consiste em alternar entre /ask e /code: você discute a abordagem no modo ask e depois passa para o modo code, em que um simples “go ahead” basta para executar o plano acordado. É uma versão mais fluida do modo architect com um único modelo. Para um modelo local de tamanho médio, esse costuma ser o melhor equilíbrio: você evita carregar dois modelos na memória e mantém o controle sobre o plano.

O modo architect se justifica para modelos que raciocinam bem, mas editam mal. Ele exige duas requisições em vez de uma: só o ative se o modo code produzir diffs inválidos regularmente.

#Git, sua rede de segurança

Aider se baseia no Git para tornar cada erro reversível. A cada edição, ele faz um commit das alterações com uma mensagem descritiva, gerada pelo modelo fraco a partir do diff e da conversa, no estilo dos commits convencionais. Antes de tocar em um arquivo com alterações ainda não registradas em um commit, ele primeiro faz um commit das alterações existentes: seu trabalho e o da IA permanecem separados no histórico. Os commits que ele cria incluem a indicação “(aider)” no nome do autor, o que permite encontrá-los.

O corolário é que surgem muitos commits pequenos. A boa prática é fazer o Aider trabalhar em uma branch dedicada, revisar e depois consolidar os commits (squash) antes de fazer o merge. Duas opções merecem ser conhecidas: --no-auto-commits desativa o commit automático e --git-commit-verify reativa os hooks pre-commit, que a ferramenta contorna por padrão com --no-verify. Se sua equipe depende desses hooks, a opção muda tudo.

git switch -c ai/endpoint-users
aider src/api.py
# ... relire, tester, puis :
git rebase -i main

#Executar seus testes dentro do ciclo de trabalho

É esta configuração que transforma Aider de um gerador de código em uma ferramenta que se corrige. Com --test-cmd e --auto-test, ele executa sua suíte de testes após cada modificação; se o comando retornar um código de saída diferente de zero, ele lê a saída e tenta corrigir o problema. O princípio é o mesmo para o linter, com --lint-cmd, e Aider faz o lint por padrão nos arquivos que edita.

aider --test-cmd "pytest -x -q" --auto-test --lint-cmd "ruff check"

Duas precauções. O comando de teste deve ser rápido: com um modelo local, cada ciclo já custa algumas dezenas de segundos de geração. E deve exibir erros com código de saída não nulo, caso contrário, o Aider acredita que tudo está bem.

#O que falha com um modelo local e como contornar esses problemas

Erros no formato das edições

O modelo retorna uma modificação que a ferramenta não consegue aplicar. Mude para um modelo maior ou teste o modo architect. A documentação do Aider dedica uma página de solução de problemas a esses erros.

Perda de contexto

Sintoma: o modelo ignora um arquivo que acabou de ser adicionado. Causa provável: janela muito pequena ou contexto saturado. Solução: /tokens, /drop de arquivos desnecessários, depois contexto maior.

Arquivos longos demais

Um arquivo com milhares de linhas satura o contexto local. Divida-o ou solicite uma alteração em uma função específica.

Solicitações vagas

'Melhore este código' gera diffs imprevisíveis. Nomeie o arquivo, a função, o comportamento esperado.

Erro de limite de tokens

Aider avisa quando um modelo ultrapassa seus limites e sugere ações: pedir mudanças menores, dividir os arquivos, mudar de modelo.

#Aider ou um agente no editor

O Aider se destina a quem trabalha no terminal e quer um histórico Git limpo. Se preferir ficar no VS Code, o Cline oferece uma experiência equivalente com validação passo a passo; se quiser um agente de terminal mais autônomo, o OpenCode é uma opção. A escolha não depende da qualidade do modelo, que é a mesma, mas do local onde você quer revisar as diferenças.

• Aider + Ollama: o fluxo completo no terminal
• Melhor LLM local para programar
• Compreender a janela de contexto
• Cline + Ollama no VS Code
• OpenCode + Ollama no terminal
• Releia o código com um LLM local antes do commit

• Fonte: documentação do Aider para Ollama
• Fonte: os modos de chat do Aider
• Fonte: integração Git do Aider
• Fonte: lint e testes no Aider
• Fonte: Devstral na biblioteca Ollama