Aider: guía práctica para usarlo como agente de edición en la terminal

Aider es el agente de pair programming más directo que existe: no tiene IDE propio, no abre pestañas nuevas y no te pide aprobar cada cambio. Lo corres en la terminal, le pasas los archivos del ticket y edita el código por ti mientras commitea cada cambio con un mensaje descriptivo. Esa integración con git no es un extra: es la razón por la que puedes dejar que un modelo toque tu repo sin perder las manos.

Dónde encaja en tu caja de herramientas: si ya conoces Claude Code o Codex, Aider es la alternativa que funciona con cualquier modelo (Claude, DeepSeek, OpenAI, Gemini, modelos locales) y que hace de git su red de seguridad en lugar de un accesorio. Para empezar a construir agentes desde cero, la referencia es el hub de construcción; aquí el entregable es un flujo de terminal que puedes usar hoy mismo.

Qué instalar y en cuánto tiempo

La vía oficial recomendada es el instalador que se encarga solo de las dependencias de Python:

python -m pip install aider-install
aider-install

El instalador prepara un entorno separado para Aider, así no ensucia tu Python global. Si prefieres la vía directa y ya tienes Python 3.8–3.13:

python -m pip install aider-chat

También hay imágenes de Docker y soporte para GitHub Codespaces y Replit en la documentación oficial. Para el primer arranque basta con moverse al repo y lanzar el binario:

cd /tu/proyecto
aider

En el arranque verás el modelo por defecto, el tamaño del repo-map y un prompt > esperando tu primer pedido. La instalación completa toma menos de un minuto con el instalador; la versión directa, un pip install.

La regla de oro: agrega solo los archivos del ticket

Aider no escanea tu proyecto entero a ciegas. Solo puede ver y editar los archivos que agregas al chat, y el resto lo entiende a través de un mapa del repo (repo-map) que incluye las clases y funciones más relevantes. Por eso el flujo correcto es:

aider src/utils/tax.ts src/services/invoice.ts

Y dentro de la sesión puedes ajustar con /add y /drop. Si agregas veinte archivos “por si acaso”, el modelo se distrae, el contexto se infla y cada respuesta cuesta más tokens. Dos o tres archivos relevantes suelen ser suficientes; Aider solo necesita ver lo que va a tocar, y el repo-map le da el contexto del resto. Para archivos nuevos, /add <archivo> antes de pedir que lo cree, o Aider puede escribir la nueva lógica en un archivo existente.

Modos de chat: code, ask y architect

Aider tiene un solo prompt, pero cuatro modos que cambian el comportamiento:

Modo	Qué hace	Cuándo lo usas
code	Edita archivos para cumplir tu pedido	La mayoría del tiempo: pedir el cambio
ask	Responde y discute el código, sin editar nada	Planear antes de tocar, revisar enfoque
architect	Un modelo propone el plan y otro aplica los edits	Cambios grandes o multi-archivo
help	Explica config, opciones y troubleshooting de Aider	Aprender comandos, resolver errores

El flujo recomendado por la propia documentación es alternar /ask y /code: discutes el plan sin riesgo, y cuando el enfoque está claro pasas a code mode para que edite. Los cambios de modo con /ask, /code o /architect aplican solo al mensaje siguiente; con /chat-mode <modo> cambias el modo activo de forma permanente.

Git como red de seguridad

Aider está diseñado para repos con git, y usa el versionado para que un cambio malo no sea un drama:

• Autocommit por cambio: cada vez que edita, crea un commit con mensaje descriptivo (por defecto usa Conventional Commits).
• /undo: revierte el último cambio al instante, sin cirugía manual.
• /diff: muestra exactamente qué cambió desde tu último mensaje.
• Dirty files protegidos: antes de tocar un archivo con cambios sin commitear, Aider commitea primero tus cambios con un mensaje propio, para que nunca los pierda si hace un edit inapropiado.
• /git: ejecuta comandos git crudos desde el chat cuando necesitas hacer algo más complejo.

Si por alguna razón no quieres el autocommit (por ejemplo, para revisar edits antes de commitear), puedes desactivarlo con --no-auto-commits, pero es una excepción: dejarlo activo es lo que hace seguro probar un agente de edición. Si el repo tiene pre-commit hooks, --git-commit-verify los ejecuta antes de cada commit; por defecto Aider los salta con --no-verify para no bloquearse.

Modelos y keys: el .env manda

Aider funciona con muchos proveedores y la config de keys es pareja para todos:

# En .env del proyecto o en tu shell
ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...
GEMINI_API_KEY=...
DEEPSEEK_API_KEY=...

Para seleccionar modelo en el arranque:

aider --model sonnet            # Claude Sonnet, el recomendado por la doc
aider --model deepseek          # razonamiento barato
aider --model o3-mini           # OpenAI
aider --list-models sonnet      # ver qué variantes existen

La documentación oficial señala que Aider funciona especialmente bien con Claude Sonnet y DeepSeek. La key se puede pasar también con --openai-api-key / --anthropic-api-key, o con --api-key proveedor=<key> para el resto; pero el .env del proyecto es el lugar natural y evita que la key quede en el historial de shell. Con modelos de razonamiento, --reasoning-effort y --thinking-tokens ajustan cuánto “piensa” antes de editar.

Lint y tests automáticos: el agente se autocorrige

Aider incluye linters para la mayoría de lenguajes y corre el linter sobre cada archivo que edita. Si hay errores, el modelo recibe el output y los arregla en el siguiente paso. Puedes apuntar a otro linter con --lint-cmd, o definir linters por lenguaje con --lint "lenguaje: cmd". Para tests, el comando /test <comando> ejecuta la suite sobre tu proyecto y Aider vuelve a intentar si algo falla. Esto convierte el ciclo editar→fallar→reparar en algo automático, sin que tengas que mirar cada diff.

Un flujo de 30 minutos para un ticket real

1. Arranca acotado: aider src/api/orders.ts src/api/orders.test.ts
2. Planea con /ask: “¿Qué necesito cambiar para agregar el endpoint de cancelación?” Ajusta el plan en el chat.
3. Ejecuta en /code: “Agrega el endpoint con validación del estado y test”.
4. Déjalo autolintar: Aider pasa el linter y corrige lo que falte.
5. Revisa el diff acumulado con /diff antes de seguir.
6. Si algo se rompió: /undo y pide el cambio de otra forma.
7. Cierra la sesión y revisa los commits con git log, porque cada paso quedó versionado con su mensaje.

Este flujo es el mismo para un hotfix de una línea y para una feature de varios archivos: la diferencia es el tiempo que pasas en /ask antes de pasar a /code.

Checklist antes de usarlo en tu repo

• Tienes el repo con git (Aider lo inicializa si no existe).
• Agregaste solo los archivos del ticket, no la mitad del proyecto.
• Las keys están en .env o variables de entorno, no en el prompt.
• No pegaste secretos de clientes en el chat; el historial de Aider es texto plano.
• Arrancaste en code mode y usaste /ask para cambios grandes.
• Revisaste /diff antes de cerrar la sesión.
• Dejaste el autocommit activo salvo motivo real.
• No lanzaste /git destructivo (reset --hard, push -f) desde el chat sin revisarlo.
• Probaste en una rama o worktree si el cambio toca producción: trabajar con worktrees te da un checkout aislado por tarea.
• Piensas en los límites de reintentos y rate limits si lo vas a usar como agente dentro de un script.

FAQ

¿Aider puede romper mi código? Puede, como cualquier agente. La diferencia es que cada edit es un commit y /undo revierte el último cambio al instante; por eso el git integrado no es opcional sino la red de seguridad principal.

¿Puedo usarlo sin git? Técnicamente sí, con --no-git, pero pierdes /undo y el versionado por cambio. No lo recomiendan ni para explorar; es mejor usarlo en un repo aunque sea un borrador.

¿Qué modelo uso si no tengo presupuesto? DeepSeek tiene buena relación calidad/precio y funciona nativo con --model deepseek; también sirven proveedores compatibles con OpenAI vía --api-key openrouter=<key> y modelos locales con Ollama o LM Studio.

¿Aider sirve para algo que no sea código? Tiene modos para trabajar con imágenes, páginas web y config; pero su punto fuerte es editar archivos en repos git. Para agentes de propósito general, mejor revisa el hub de construcción de agentes.