Como usar o Aider: guia passo a passo

Para usar o Aider, instale-o com aider-install ou com o script de uma linha, entre com cd em um repositório git, inicie com aider --model sonnet --api-key anthropic=<key> (ou outro provedor), adicione com /add os arquivos que você quer mudar e descreva a mudança em linguagem natural. O Aider edita os arquivos e faz commit de cada mudança no git, então /undo desfaz.

Esse é o ciclo todo. Este guia cobre as partes que tornam o Aider agradável de usar: API keys e modelos, quais arquivos adicionar, os modos ask, code e architect, formatos de edição, comportamento no git, .aider.conf.yml, integração com lint e testes e um arquivo de convenções. Todos os comandos e flags aqui vêm da documentação oficial do Aider em aider.chat, de outubro de 2026.

O que é o Aider

O Aider é um programador em par com IA para o terminal. É um agente de código que funciona com quase qualquer LLM: Claude, GPT, Gemini, DeepSeek ou um modelo local. Duas coisas o diferenciam da maioria dos agentes de CLI. Primeiro, ele é construído em torno do git: toda edição vira um commit. Segundo, ele é explícito sobre o contexto: você decide quais arquivos estão no chat, e um mapa do repositório dá ao modelo um resumo do resto.

Se você está comparando com outros agentes de terminal, como usar o opencode e como usar o GitHub Copilot CLI seguem o mesmo formato passo a passo.

Passo 1: instale o Aider

A documentação do Aider lista vários caminhos de instalação. Escolha um.

O aider-install instala o Aider em um ambiente Python próprio, então ele não conflita com os pacotes do seu projeto. Se instalar com pip puro, faça isso dentro de um ambiente virtual. Quando o comando aider não é encontrado depois de uma instalação via pip, python -m aider roda a mesma coisa.

Passo 2: API keys e modelos

O Aider conversa com os provedores de modelo usando suas próprias keys. O jeito mais rápido de começar é passar o modelo e a key na linha de comando:

cd /to/your/project

# Anthropic
aider --model sonnet --api-key anthropic=<key>

# OpenAI
aider --model o3-mini --api-key openai=<key>

# DeepSeek
aider --model deepseek --api-key deepseek=<key>

Digitar a key toda vez cansa. O Aider também lê as variáveis de ambiente de sempre (ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY, DEEPSEEK_API_KEY e assim por diante) e um arquivo .env no seu projeto. --api-key provider=<key> funciona para qualquer provedor: --api-key gemini=xxx define GEMINI_API_KEY.

Nomes curtos como sonnet são aliases embutidos. Em outubro de 2026, a documentação associa sonnet, opus e haiku aos modelos Claude atuais, gemini e flash a modelos Gemini, deepseek e r1 ao DeepSeek chat e reasoner, e 4o ao GPT-4o. Você pode definir os seus:

aider --alias "fast:gpt-4o-mini" --model fast

Dentro de uma sessão, /model <name> troca o modelo principal, /models <search> lista os modelos disponíveis e /reasoning-effort define o esforço nos modelos que suportam isso. O Aider também usa um “weak model” mais barato para mensagens de commit e resumos do chat; --weak-model o altera. Quer rodar no seu próprio hardware? O guia de agente de código com LLM local cobre essa configuração.

Passo 3: adicione arquivos ao chat

O Aider só edita arquivos que estão no chat. Você pode citá-los ao iniciar:

aider src/api/users.py tests/test_users.py

ou adicioná-los depois:

/add src/api/users.py tests/test_users.py

A documentação do Aider é clara em um ponto: adicione só os arquivos que precisam ser editados para a tarefa. Cada arquivo adicionado custa tokens, e arquivos demais podem sobrecarregar o modelo. O Aider monta um mapa de todo o repositório, então o modelo já sabe onde ficam funções e classes relacionadas sem que você as adicione. Se você não adicionar nada, o Aider tenta descobrir quais arquivos precisam de edição.

Os comandos que gerenciam o contexto:

• /add <files> adiciona arquivos que o Aider pode editar.
• /read-only <files> adiciona arquivos de referência que ele pode ler mas não mudar (docs, um módulo de exemplo).
• /drop <files> remove arquivos para liberar contexto; /drop sozinho remove todos.
• /ls lista os arquivos no chat e no repositório.
• /tokens mostra quantos tokens o contexto atual usa.
• /map imprime o mapa do repositório, e /map-refresh o reconstrói.

Depois descreva a mudança:

Add pagination to the list_users endpoint: accept page and page_size
query parameters, default to 20 per page, and update the tests.

Passo 4: modos ask, code e architect

O Aider tem modos de chat, e escolher o certo é a maior parte da habilidade.

/ask, /code e /architect seguidos de uma mensagem valem só para aquela mensagem. Digitados sozinhos, trocam o modo até você mudar de novo; /chat-mode <mode> faz o mesmo. --chat-mode <mode> escolhe o modo na inicialização, e --architect é um atalho.

O fluxo que a documentação recomenda é alternar. Pergunte primeiro, refine o plano e depois deixe ele codar:

/ask How should I add rate limiting to the login route without touching
the other endpoints? Don't change anything yet.

Quando o plano parecer certo, digite /ok. É um atalho para “/code Ok, please go ahead and make those changes.”

O modo architect divide o trabalho entre dois modelos. O modelo principal descreve como resolver o problema, e um modelo editor, definido com --editor-model, transforma isso em edições de arquivo. Se você não escolher, o Aider escolhe um modelo editor adequado para cada modelo principal. Isso costuma ajudar com modelos de raciocínio que são bons em planejar, mas menos confiáveis para produzir edições exatas. A contrapartida: o modo architect envia duas requisições por mudança, então é mais lento e custa mais.

Passo 5: formatos de edição

Um formato de edição é como o modelo diz ao Aider o que mudar. Você raramente precisa mexer nisso, porque o Aider escolhe o melhor formato para cada modelo, mas ajuda saber o que você está vendo:

Substitua com --edit-format <format>, e defina o formato do modelo editor com --editor-edit-format. Se um modelo continua produzindo edições que não se aplicam, mudar para whole é um teste razoável em arquivos pequenos.

Passo 6: git, commits automáticos e /undo

O Aider funciona melhor dentro de um repositório git. Por padrão:

• Toda edição que o Aider faz recebe um commit com uma mensagem descritiva, escrita pelo weak model no estilo Conventional Commits.
• Se você tinha mudanças sem commit nos arquivos antes de o Aider editá-los, ele faz commit delas primeiro, assim o seu trabalho e o dele ficam em commits separados.
• “(aider)” é adicionado ao nome de autor e committer do git nos commits dele.

Isso torna a rede de segurança simples:

• /diff mostra as mudanças desde a sua última mensagem.
• /undo reverte o último commit se foi o Aider que o fez.
• /commit faz commit das edições externas que você mesmo fez.
• /git <command> roda qualquer comando git sem sair do chat.

Você pode desligar partes disso: --no-auto-commits deixa as edições sem commit para você revisar, --no-dirty-commits pula o commit antes da edição e --no-git desativa o git completamente (a documentação desaconselha). O Aider faz commits com --no-verify por padrão, então seus hooks de pre-commit não rodam; adicione --git-commit-verify se quiser que rodem. Se preferir manter as mudanças do Aider longe do seu checkout principal, rode-o em um git worktree separado.

Passo 7: configure o .aider.conf.yml

Flags que você usa sempre ficam melhor em um arquivo YAML. O Aider carrega .aider.conf.yml do seu diretório home, depois da raiz do repositório git, depois do diretório atual; os arquivos posteriores prevalecem. --config <file> carrega só aquele arquivo.

# .aider.conf.yml
model: sonnet
weak-model: haiku
auto-commits: true
dirty-commits: true
lint-cmd: "python: ruff check --fix"
test-cmd: pytest -q
auto-test: false
read: [CONVENTIONS.md]

As chaves no arquivo correspondem aos nomes longos das flags sem os traços iniciais. API keys também podem ir aqui (anthropic-api-key:, openai-api-key: ou uma lista api-key: como - gemini=xxx), mas nesse caso mantenha o arquivo fora do git. Por padrão, o Aider adiciona .aider* ao .gitignore para que seus arquivos de histórico não acabem em commits.

Passo 8: integração com lint e testes

O Aider roda o lint nos arquivos que edita logo depois de cada mudança, usando linters embutidos para as linguagens mais populares. Se o linter reportar problemas, o Aider tenta corrigi-los. Você pode trazer seu próprio linter:

aider --lint-cmd "python: ruff check --fix" --lint-cmd "javascript: npx eslint --fix"

O comando precisa imprimir os erros e sair com código diferente de zero quando encontra problemas. --no-auto-lint desliga o lint.

Os testes funcionam do mesmo jeito, mas vêm desligados por padrão. Defina um comando com --test-cmd e ligue --auto-test, e o Aider roda os testes depois de cada mudança e tenta corrigir as falhas (qualquer exit code diferente de zero). No chat:

• /lint roda o lint e corrige os arquivos no chat, ou todos os arquivos modificados se nenhum foi adicionado.
• /test <command> roda um comando e, se ele falhar, adiciona a saída ao chat.
• /run <command> (ou !<command>) roda um comando de shell e permite compartilhar a saída.

Passo 9: um arquivo de convenções

O Aider não tem um arquivo de instruções de projeto embutido que carregue sozinho. A abordagem documentada é um arquivo Markdown simples que você carrega como somente leitura:

# CONVENTIONS.md
- Prefer httpx over requests for making http requests.
- Use types everywhere possible.
- Every new endpoint needs a test in tests/api/.

aider --read CONVENTIONS.md

ou /read-only CONVENTIONS.md durante uma sessão, ou read: CONVENTIONS.md no .aider.conf.yml para carregar sempre. Arquivos somente leitura entram no cache quando o prompt caching está ligado, então o custo fica baixo. Se você já mantém um AGENTS.md para outros agentes, pode carregar esse; CLAUDE.md e AGENTS.md tem dicas para escrever regras que os agentes realmente seguem.

Mais dois recursos que vale conhecer

Scripts. --message (ou -m) envia uma instrução, aplica as edições e sai, o que facilita rodar o Aider em loop sobre arquivos:

for FILE in *.py ; do
  aider --message "add descriptive docstrings to all the functions" $FILE
done

Adicione --yes-always para aceitar confirmações automaticamente e --message-file para ler a instrução de um arquivo.

Modo watch. Inicie o Aider com --watch-files e continue trabalhando no seu editor. Escreva um comentário terminado em AI! e o Aider faz a mudança; termine com AI? e o Aider responde a pergunta. Funciona com comentários #, // e --.

Armadilhas comuns

• Adicionar o repositório inteiro. Mais arquivos significam custo maior e edições piores. Adicione o que muda, use /read-only para referências e confie no mapa do repositório.
• Esquecer o comportamento de dirty-commit. O Aider faz commit das suas edições pendentes antes de mexer em um arquivo. Se isso te surpreende, faça commit ou stash antes, ou use --no-dirty-commits.
• Esperar que os hooks rodem. Os commits pulam os hooks de pre-commit, a menos que você passe --git-commit-verify.
• Modo architect para tudo. Ele dobra as requisições. Use para mudanças complicadas; o modo code comum serve para edições pequenas.
• Keys em uma configuração com commit. Se o .aider.conf.yml guarda API keys, mantenha-o no seu diretório home ou fora do git.
• Chats longos. Mensagens antigas custam tokens em toda requisição. /clear apaga o histórico do chat e /reset também remove os arquivos.

Rodando o Aider no AgentVera

O AgentVera é um app desktop para macOS, Windows e Linux que roda agentes de CLI lado a lado em terminais reais, usando suas próprias instalações e keys. O Aider é um dos agentes suportados; a página Aider no AgentVera lista os detalhes:

• Suas keys, sua configuração. O Aider lê as keys dos provedores de variáveis de ambiente ou do .aider.conf.yml, como sempre. Um modelo que você escolhe no AgentVera é passado com --model, e esforço baixo, médio ou alto com --reasoning-effort.
• Histórico separado por agente. Cada agente Aider mantém seu próprio arquivo de histórico de chat em ~/.aider/agentvera/ e o continua com --restore-chat-history quando o app reabre, então vários agentes Aider nunca misturam seus históricos.
• Papéis como arquivo somente leitura. O Aider não permite estender seu system prompt, então o papel do agente é passado com --read, o mesmo mecanismo de um arquivo de convenções.
• Painéis ao lado de outros agentes. Rode o Aider na grade do workspace ao lado do Claude Code ou do Codex, e inicie agentes em seus próprios worktrees pelo painel Git.
• Revisão e flows. Agentes Aider recebem revisão automática de código quando um turno termina, e funcionam em flows (Pro e Team), broadcasts e tarefas agendadas.

Uma limitação para saber: os servidores MCP que você configura no AgentVera não são passados para o Aider. A grade, os worktrees e a revisão de código estão no plano gratuito. Baixe o AgentVera para experimentar.

Concluindo

Instale o Aider, entre com cd em um repositório git, inicie com um modelo e uma key e adicione só os arquivos de que a mudança precisa. Use /ask para planejar e /ok ou /code para aplicar, experimente /architect em problemas mais difíceis e conte com /diff e /undo, porque toda edição é um commit. Coloque seus padrões no .aider.conf.yml, suas regras no CONVENTIONS.md e deixe --lint-cmd e --test-cmd pegarem os erros antes de você. Se você também usa o agente do GitHub, como usar o GitHub Copilot CLI é o mesmo guia para essa ferramenta.