# Como usar o Aider: guia passo a passo URL: https://agentvera.dev/pt/blog/how-to-use-aider/ · Publicado: 2026-10-27 Como usar o Aider: instalar, configurar API keys, escolher modelo, adicionar arquivos, usar os modos ask, code e architect, desfazer commits e .aider.conf.yml. **Resumo:** - Instale o Aider com aider-install, o script de uma linha, uv ou pipx, e depois rode aider --model sonnet --api-key anthropic= dentro de um repositório git. - Adicione com /add só os arquivos de que a mudança precisa, deixe arquivos de referência como somente leitura e alterne entre /ask, /code e /architect conforme a tarefa. - O Aider faz commit de cada edição no git, então /undo reverte o último commit dele; .aider.conf.yml, --lint-cmd, --test-cmd e um arquivo CONVENTIONS.md definem seus padrões. 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=` (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](/pt/glossary/coding-agent/ "O que é 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](/pt/blog/how-to-use-opencode/ "Como usar o opencode") e [como usar o GitHub Copilot CLI](/pt/blog/how-to-use-copilot-cli/ "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. | Método | Comando | | --- | --- | | aider-install (recomendado) | `python -m pip install aider-install` e depois `aider-install` | | Uma linha, macOS e Linux | `curl -LsSf https://aider.chat/install.sh \| sh` | | Uma linha, Windows | `powershell -ExecutionPolicy ByPass -c "irm https://aider.chat/install.ps1 \| iex"` | | uv | `uv tool install --force --python python3.12 --with pip aider-chat@latest` | | pipx | `pipx install aider-chat` | 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: ```bash cd /to/your/project # Anthropic aider --model sonnet --api-key anthropic= # OpenAI aider --model o3-mini --api-key openai= # DeepSeek aider --model deepseek --api-key deepseek= ``` 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=` 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: ```bash aider --alias "fast:gpt-4o-mini" --model fast ``` Dentro de uma sessão, `/model ` troca o modelo principal, `/models ` 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](/pt/blog/local-llm-coding-agent/ "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: ```bash aider src/api/users.py tests/test_users.py ``` ou adicioná-los depois: ```text /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 ` adiciona arquivos que o Aider pode editar. - `/read-only ` adiciona arquivos de referência que ele pode ler mas não mudar (docs, um módulo de exemplo). - `/drop ` 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: ```text 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. | Modo | O que faz | Prompt | | --- | --- | --- | | code | O padrão. O Aider edita arquivos para fazer a mudança. | `>` | | ask | Discute o código e responde perguntas. Nunca edita. | `ask>` | | architect | Um modelo propõe a mudança, um modelo editor escreve as edições. | `architect>` | | help | Responde perguntas sobre o próprio Aider. | `help>` | `/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 ` faz o mesmo. `--chat-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: ```text /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: | Formato | Como as edições são enviadas | | --- | --- | | whole | O modelo devolve o arquivo inteiro atualizado. Simples, mas caro para arquivos grandes. | | diff | Blocos de busca/substituição: as linhas antigas e a substituição. | | diff-fenced | Como o diff, com o caminho do arquivo dentro do bloco de código. Principalmente para modelos Gemini. | | udiff | Um unified diff simplificado. | | editor-diff, editor-whole | Versões enxutas usadas pelo modelo editor no modo architect. | Substitua com `--edit-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 ` 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](/pt/blog/git-worktree-parallel-agents/ "Git worktrees para agentes em paralelo") 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 ` carrega só aquele arquivo. ```yaml # .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: ```bash 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 ` roda um comando e, se ele falhar, adiciona a saída ao chat. - `/run ` (ou `!`) 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: ```markdown # CONVENTIONS.md - Prefer httpx over requests for making http requests. - Use types everywhere possible. - Every new endpoint needs a test in tests/api/. ``` ```bash 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](/pt/blog/claude-md-agents-md/ "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: ```bash 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](/pt/agents/aider/ "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](/pt/features/workspace/ "Workspace") ao lado do Claude Code ou do Codex, e inicie agentes em seus próprios worktrees pelo [painel Git](/pt/features/git-and-github/ "Git e GitHub"). - **Revisão e flows.** Agentes Aider recebem [revisão automática de código](/pt/features/code-review/ "Revisão 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](/pt/download/ "Baixar 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](/pt/blog/how-to-use-copilot-cli/ "Como usar o GitHub Copilot CLI") é o mesmo guia para essa ferramenta. ## Perguntas frequentes **O Aider é gratuito?** Instalar o Aider não custa nada. Você paga ao provedor do modelo pelos tokens que usa com sua própria API key, ou nada se apontar o Aider para um modelo local. O custo depende do modelo e de quantos arquivos você adiciona ao chat. **Qual modelo devo usar com o Aider?** Qualquer modelo que o Aider suporte funciona. A documentação usa sonnet, deepseek e o3-mini no quick start, e também existem aliases como opus, gemini e flash. Modelos mais fortes seguem os formatos de edição com mais confiabilidade; você pode combinar um modelo architect forte com um modelo editor mais barato. **Como desfazer uma mudança feita pelo Aider?** Digite /undo. O Aider faz commit de cada edição no git com uma mensagem descritiva, e /undo reverte o último commit se foi o Aider que o fez. /diff mostra o que mudou desde a última mensagem, e comandos git comuns também funcionam, porque toda mudança é um commit normal. **O Aider funciona sem git?** Sim, com --no-git, mas você perde os commits automáticos, o /undo e o /diff. A documentação do Aider recomenda manter o git ligado. Se não quiser um commit depois de cada edição, use --no-auto-commits e faça os commits você mesmo. **Como fazer o Aider seguir meu estilo de código?** Escreva as regras em um CONVENTIONS.md curto e carregue com aider --read CONVENTIONS.md, ou adicione read: CONVENTIONS.md ao .aider.conf.yml para carregar sempre. O arquivo é somente leitura, então o Aider o usa como orientação e nunca o edita. --- **Sobre o AgentVera.** AgentVera é um app desktop para macOS, Windows e Linux, desenvolvido pela Solviera Teknoloji. Ele roda 18 agentes de programação com IA (Claude Code, Codex, Gemini CLI, Copilot, Cursor, Antigravity, opencode, Hermes, Qwen Code, Kimi Code, Kiro, Amp, Droid, Goose, Vibe, Crush, Aider, Cline) lado a lado, por projeto, em terminais reais com as instalações e logins de CLI do próprio usuário. O plano gratuito tem agentes ilimitados. Baixar: https://agentvera.dev/pt/download/ · Preços: https://agentvera.dev/pt/pricing/