Aider: Guia Prático de Configuração para Programação em Pares com IA de Código Aberto

Ajudante
1

Aider é a ferramenta de IA para codificação em terminal de código aberto que consistentemente ocupa os primeiros lugares em benchmarks de codificação. É agnóstica em relação a modelos, nativa de git e custa apenas o que você gasta em chamadas de API — sem assinatura. Este guia leva você da instalação a um fluxo de trabalho produtivo.

Instalação

# Recomendado: pipx (ambiente isolado)
pipx install aider-chat

# Alternativa: pip
pip install aider-chat

# Verificar
aider --version

Aider requer Python 3.9+ e git instalado no seu caminho.

Configurando Chaves de API

Aider funciona com praticamente qualquer LLM. Configure o(s) que você deseja:

# Anthropic (Claude)
export ANTHROPIC_API_KEY=sk-ant-xxxxx

# OpenAI (GPT-4o)
export OPENAI_API_KEY=sk-xxxxx

# Google (Gemini)
export GEMINI_API_KEY=xxxxx

# Para modelos locais via Ollama
# Nenhuma chave de API necessária — Aider se conecta a localhost:11434

Adicione estas ao seu .bashrc, .zshrc ou configuração de shell para que persistam.

Sua Primeira Sessão

cd your-project
aider

Aider inicia, indexa seu repositório e constrói um mapa do seu código. Você verá um prompt onde pode digitar comandos ou instruções em linguagem natural.

Adicione arquivos à conversa:

/add src/routes/users.ts src/services/userService.ts

Apenas arquivos adicionados podem ser editados pelo Aider. Outros arquivos no repositório são visíveis para referência (através do mapa do repositório), mas não serão modificados.

Descreva o que você quer:

Adicione validação de email ao endpoint de registro de usuário.
Use Zod para validação e retorne um erro 400 com uma mensagem clara
se o formato do email for inválido ou o domínio não tiver registros MX.

Aider edita os arquivos, mostra o diff e cria um commit git com uma mensagem descritiva. Cada mudança é um commit — seu histórico git permanece limpo.

Escolhendo o Modelo Certo

A flexibilidade de modelo do Aider é uma de suas maiores forças. Inicie com um modelo específico:

# Claude Sonnet (melhor para a maioria das tarefas)
aider --model claude-sonnet-4-20250514

# Claude Opus (raciocínio pesado, refatoração complexa)
aider --model claude-opus-4-20250514

# GPT-4o (rápido, bom para tarefas mais simples)
aider --model gpt-4o

# DeepSeek (modelo de codificação forte, custo menor)
aider --model deepseek/deepseek-coder

# Modelo local via Ollama
aider --model ollama/codellama:34b

Estratégia econômica: Use Claude Sonnet como padrão. Mude para Opus apenas para trabalho arquitetônico complexo. Use modelos locais para refatorações simples e trabalho exploratório onde a qualidade pode ser menor, mas você não quer custos de API.

Arquivo de Configuração

Crie .aider.conf.yml na raiz do seu projeto para configurações persistentes:

# Modelo padrão
model: claude-sonnet-4-20250514

# Auto-commit de mudanças (padrão: true)
auto-commits: true

# Mostrar diffs no chat
show-diffs: true

# Codificação para seus arquivos
encoding: utf-8

# Arquivos para sempre incluir
read:
  - README.md
  - ARCHITECTURE.md

# Modo escuro para a UI do terminal
dark-mode: true

# Estilo de mensagem de commit git
attribute-author: false
attribute-committer: false

Comandos Essenciais

Comandos começam com / no prompt do Aider:

/add file.ts          — adicionar arquivo ao contexto editável
/drop file.ts         — remover arquivo do contexto
/read-only file.ts    — adicionar como referência apenas (não editável)
/ls                   — listar arquivos no contexto
/tokens               — mostrar uso de tokens e custos
/undo                 — desfazer a última mudança (git reset)
/diff                 — mostrar mudanças não commitadas atuais
/test npm test        — executar testes e corrigir falhas
/lint npm run lint    — executar linter e corrigir problemas
/run <command>        — executar qualquer comando shell
/clear                — limpar histórico de conversa
/model <name>         — mudar modelo durante a sessão
/help                 — listar todos os comandos

O Fluxo de Trabalho Git Que Torna Aider Especial

Cada edição que Aider faz cria um commit git. Isso significa:

# Ver o que Aider fez
git log --oneline -10

# Não gostou da última mudança? Desfaça instantaneamente
/undo

# Quer revisar todas as mudanças geradas por IA?
git log --author="aider" --oneline

# Cherry-pick de mudanças específicas
git cherry-pick <commit-hash>

# Squash de múltiplos commits do Aider antes de fazer push
git rebase -i HEAD~5

Esta abordagem nativa de git significa que você nunca fica preso com saída de IA ruim. Rollback está sempre a um comando de distância.

Fluxos de Trabalho Avançados

Desenvolvimento Orientado por Testes com Aider

/test npm test

Aqui estão os testes falhando. Corrija a implementação em
src/services/orderService.ts para fazer todos os testes passarem.
Não modifique os arquivos de teste.

Aider lê as falhas de teste, entende o que é esperado e corrige a implementação. Se os testes ainda falharem, ele itera automaticamente.

Refatoração Multi-Arquivo

/add src/api/*.ts src/services/*.ts src/types/*.ts

Refatore todas as rotas de API para usar um padrão consistente de tratamento de erros:
1. Envolva cada handler em um utilitário tryCatch
2. Use classe AppError tipada para erros conhecidos
3. Registre erros inesperados em console.error com ID de requisição
4. Retorne { error: string, code: string, requestId: string }

Aplique isto a todos os arquivos de rota. Mantenha a lógica de negócio inalterada.

Aider processa cada arquivo sistematicamente, aplicando o mesmo padrão consistentemente.

Usando Contexto Web

/web https://supabase.com/docs/reference/javascript/auth-signup

Implemente registro de usuário usando esta abordagem de autenticação Supabase.
Siga o padrão de documentação oficial.

Aider raspa a página e a usa como contexto. Isto é útil para implementar recursos baseados em documentação atual em vez de dados de treinamento.

Codificação por Voz

aider --voice

Aider suporta entrada de voz. Descreva suas mudanças falando em vez de digitar. Útil para instruções complexas onde digitar é mais lento que falar.

Gerenciamento de Custos

Como você paga por chamada de API, monitorar custos é importante:

/tokens

Mostra uso de tokens da sessão atual e custo estimado. Estratégias para manter custos baixos:

  • Adicione apenas arquivos relevantes — não faça /add de todo o seu projeto
  • Use o mapa do repositório — Aider referencia outros arquivos automaticamente sem adicioná-los ao contexto editável
  • Mude para modelos mais baratos para tarefas simples
  • Use /clear para resetar contexto ao mudar de tarefas
  • Use modelos locais (Ollama) para trabalho exploratório e edições simples

Um dia típico de uso ativo do Aider com Claude Sonnet pode custar $2-5 em taxas de API. Muito menos que uma assinatura mensal do Cursor se você se importa com custos.

Fazendo Aider Funcionar para Equipes

Para uso em equipe:

  1. Faça commit de .aider.conf.yml no repositório para que todos usem as mesmas configurações
  2. Adicione ARCHITECTURE.md com documentação de sistema de alto nível que Aider possa referenciar
  3. Configure uma convenção para mensagens de commit do Aider para que sejam identificáveis no histórico git
  4. Use comandos /test e /lint para garantir que mudanças de IA atendam seus padrões de qualidade antes de fazer push

Quais combinações de modelo e fluxo de trabalho funcionam melhor para você? Compartilhe sua configuração do Aider. :backhand_index_pointing_down: