# 1. Установка Aider

Aider написан на Python и распространяется через PyPI. Доступно три способа установки: классический pip install, менеджер пакетов uv (рекомендуется для изоляции) и Docker для полностью контейнеризированного окружения. Перед установкой убедитесь, что у вас Python 3.10+ и git.

🔹 Способ 1: pip install (классика)

# Проверяем версию Python и git
python3 --version
git --version

# Установка Aider в текущее окружение
pip install aider-chat

# Проверяем, что установилось
aider --version
# → Aider v0.75.0

🔹 Способ 2: uv (рекомендуемый)

uv — сверхбыстрый менеджер пакетов от создателей Ruff. Создаёт изолированное виртуальное окружение для Aider, не затрагивая системный Python.

# Установка uv (если ещё нет)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Установка Aider через uv
uv tool install aider-chat

# Запуск
uvx aider

🔹 Способ 3: Docker

# Сборка образа из репозитория
git clone https://github.com/Aider-AI/aider.git
cd aider
docker build -t aider-image .

# Запуск контейнера с пробросом API-ключа и репозитория
docker run -it \
  -e OPENAI_API_KEY=$OPENAI_API_KEY \
  -v $(pwd):/app \
  aider-image

# 2. Первый запуск и конфигурация

При первом запуске Aider попросит указать API-ключ для выбранного провайдера. Можно использовать переменные окружения или конфигурационный файл .aider.conf.yml. Все настройки сохраняются и подхватываются автоматически при последующих запусках.

🔹 API-ключи через переменные окружения

# .bashrc или .zshrc
export ANTHROPIC_API_KEY="sk-ant-..."
export OPENAI_API_KEY="sk-..."
export DEEPSEEK_API_KEY="sk-..."
export GEMINI_API_KEY="AIza..."

🔹 Конфигурационный файл .aider.conf.yml

# .aider.conf.yml в корне проекта или ~/.aider.conf.yml
model: claude-sonnet-4-20250514
dark-mode: true
auto-commits: true
map-tokens: 4096
edit-format: diff
cache-prompts: true

🔹 Выбор модели при запуске

# Запуск с конкретной моделью
aider --model claude-sonnet-4-20250514

# Через OpenRouter для доступа к сотням моделей
aider --model openrouter/anthropic/claude-sonnet-4

# Локальная модель через Ollama
aider --model ollama/qwen2.5-coder:14b

# 3. Базовый рабочий процесс

Типичный флоу работы с Aider предельно прост: запускаете Aider в директории git-репозитория, описываете задачу на естественном языке, Aider вносит изменения в файлы и создаёт коммит. Всё происходит в одном терминальном окне — никаких переключений контекста.

🔹 Старт сессии

# Переходим в проект и запускаем Aider
cd ~/projects/my-fastapi-app
aider

─────────────────────────────────────────────────
Aider v0.75.0
Model: claude-sonnet-4-20250514 with diff edit format
Repo: my-fastapi-app — 23 files in repo
─────────────────────────────────────────────────
> 

🔹 Добавление файлов в контекст

Перед тем как дать задание, нужно указать Aider, с какими файлами работать. Это делается командой /add прямо в чате:

> /add src/models/user.py src/routes/auth.py
→ Added src/models/user.py to the chat
→ Added src/routes/auth.py to the chat

🔹 Постановка задачи и применение изменений

> Добавь в модель User поле email_verified типа bool с дефолтным
   значением False. В эндпоинте /auth/register после успешной
   регистрации создавай запись с email_verified=False и возвращай
   это поле в ответе.

# Aider анализирует, генерирует diff и применяет изменения
─────────────────────────────────────────────────
Applied edit to src/models/user.py
Applied edit to src/routes/auth.py
Commit 7f3a2b1: Added email_verified field to User model
  and updated /auth/register endpoint.
─────────────────────────────────────────────────

🔹 Результат в git log

git log --oneline -3
7f3a2b1 Added email_verified field to User model...
a1b2c3d Previous commit message
e4f5g6h Even earlier commit

# 4. Флаги и продвинутые настройки

Aider предлагает десятки флагов для тонкой настройки поведения. Разберём самые важные из них: выбор модели, управление контекстным окном, форматы редактирования и архитектурный режим.

🔹 Основные флаги

🔹 Режим архитектора (Architect Mode)

Самая мощная фича Aider. В этом режиме работают две модели одновременно: «архитектор» (сильная reasoning-модель, например Claude Opus) обдумывает структуру решения, а «редактор» (быстрая модель, например Claude Haiku или DeepSeek) применяет изменения. Это даёт качество Opus по цене Haiku.

# Запуск в режиме архитектора
aider --architect \
  --model claude-sonnet-4-20250514 \
  --editor-model claude-haiku-4-20250514

> Реализуй rate-limiter middleware для FastAPI с
   использованием Redis. 100 запросов в минуту на IP.

# Архитектор (Sonnet) продумывает дизайн:
→ Architect: проектирую middleware с Redis sliding window...
# Редактор (Haiku) пишет код:
→ Editor: применяю изменения в src/middleware/rate_limit.py

🔹 Форматы редактирования

--edit-format определяет, как модель возвращает изменения. Доступны: diff (unified diff — самый надёжный), search/replace (замена по точному совпадению), whole (модель возвращает файл целиком — подходит для маленьких файлов и слабых моделей).

# Diff-формат (рекомендуется для Claude/GPT-4)
aider --edit-format diff

# Search/Replace для моделей, плохо работающих с diff
aider --edit-format search_replace

# Whole-file для маленьких проектов / локальных моделей
aider --edit-format whole

# 5. Интеграция с git и Code Review

Глубокая интеграция с git — ключевая фича Aider. Инструмент не просто редактирует файлы, а работает как полноценный участник команды: создаёт осмысленные коммиты, уважает .gitignore и позволяет делать code review изменений перед коммитом.

🔹 Автоматические коммиты

По умолчанию после каждого успешного изменения Aider делает git commit с содержательным сообщением на английском языке. Если вы не хотите автоматических коммитов, используйте флаг --no-auto-commits.

# Отключаем авто-коммиты — все изменения остаются в working tree
aider --no-auto-commits

> Переименуй переменную user_list в users во всех файлах

# Aider вносит изменения, но НЕ делает коммит
→ Applied edit to 5 files. No commit created (--no-auto-commits).

# Теперь вы сами ревьюите изменения:
git diff
git add -A
git commit -m "refactor: rename user_list to users"

🔹 Работа с Git-ветками

Лучшая практика — запускать Aider в отдельной feature-ветке. Это сохраняет main в чистоте и позволяет легко сравнить изменения.

# Создаём feature-ветку
git checkout -b feature/add-pagination

# Запускаем Aider
aider

> Добавь пагинацию в эндпоинт GET /api/users:
   параметры page и per_page, возвращай мета-информацию
   (total, pages, next/prev links)

# После завершения — смотрим diff всей ветки
git diff main...feature/add-pagination

# Если всё устраивает — мёржим
git checkout main
git merge feature/add-pagination

🔹 Откат изменений

# Откат последнего коммита Aider
git reset --hard HEAD~1

# Откат нескольких коммитов
git reset --hard HEAD~3

# Просмотр лога коммитов Aider
git log --oneline --author="aider"

🔹 Aider в CI/CD и pre-commit хуках

Поскольку Aider создаёт обычные git-коммиты, все ваши pre-commit хуки (линтеры, форматтеры, тесты) срабатывают как обычно. Это значит, что код от AI проходит тот же уровень контроля качества, что и код от человека. Aider даже можно запускать в CI для автоматического исправления багов — например, при падении тестов он может предложить фикс.

# 6. Промпт-инжиниринг и советы по эффективной работе

Качество результата Aider напрямую зависит от качества промпта. В отличие от чат-интерфейсов, здесь модель видит код и структуру проекта — используйте это преимущество.

🔹 Как писать эффективные промпты

1. Будьте конкретны. Вместо «добавь авторизацию» напишите «добавь JWT-авторизацию через middleware, проверяй токен в заголовке Authorization: Bearer, возвращай 401 при невалидном токене».
2. Указывайте файлы. Используйте /add чтобы явно задать контекст. Не заставляйте модель гадать, какие файлы трогать.
3. Описывайте ожидаемое поведение. «Функция должна принимать X и возвращать Y. При ошибке бросать исключение Z.»
4. Используйте чекпоинты. Разбивайте большие задачи на мелкие шаги — по одному коммиту на шаг. Это облегчает откат и code review.

🔹 Работа с большими проектами

# Увеличиваем бюджет токенов для repo-map
aider --map-tokens 16384

# Добавляем только релевантные файлы
> /add src/services/payment.py src/models/order.py

# Используем /read-only для файлов, которые нужны
# только для контекста, но не для редактирования
> /read-only src/config.py src/types.py

🔹 Контроль расходов (Costs)

Типичная сессия из 10–15 запросов обходится в $0.50–$3.00 на Claude Sonnet. DeepSeek V3 снижает эту цифру до центов. Используйте /tokens в чате Aider, чтобы видеть текущий расход токенов.

🔹 Дополнительные встроенные команды

> /help          # Показать все доступные команды
> /tokens        # Статистика использования токенов
> /clear         # Очистить историю чата
> /drop          # Убрать файлы из контекста
> /diff          # Показать diff последнего изменения
> /undo          # Откатить последнее изменение
> /voice         # Голосовой ввод (требует настройки)
> /web           # Поиск в интернете (требует API-ключ)
> /lint          # Прогнать линтер по изменённым файлам
> /test          # Запустить тесты

# 7. Реальный сквозной пример

Покажем полный цикл создания фичи с нуля. Задача: добавить в FastAPI-приложение эндпоинт для поиска пользователей с кешированием в Redis и пагинацией.

🔹 Шаг 1: Запуск и добавление файлов

cd ~/projects/user-service
aider --model claude-sonnet-4-20250514

> /add src/main.py src/models/user.py src/db.py src/config.py
> /read-only src/config.py src/db.py

🔹 Шаг 2: Описание фичи

> Создай новый роутер src/routes/search.py с эндпоинтом
   GET /api/users/search.
   Параметры: q (поисковый запрос по полям name и email),
   page (int, default=1), per_page (int, default=20, max=100).
   Используй ILIKE для регистронезависимого поиска в PostgreSQL.
   Добавь кеширование результатов в Redis (ключ формируется
   из параметров запроса), TTL 60 секунд.
   Ответ должен содержать: items, total, page, per_page, pages.
   Зарегистрируй роутер в main.py.

─────────────────────────────────────────────────
Created src/routes/search.py
Applied edit to src/main.py
Commit a4f8e2c: Added user search endpoint with Redis
  caching and pagination.
─────────────────────────────────────────────────

🔹 Шаг 3: Проверка результата

git show --stat HEAD
 src/main.py            | 4 ++++
 src/routes/search.py   | 68 +++++++++++++++++++++++++
 2 files changed, 72 insertions(+)

python -m pytest src/tests/ -v -k search
=== 3 passed in 1.23s ===

🔹 Шаг 4: Рефакторинг в той же сессии

> Вынеси логику кеширования в декоратор @cached(ttl),
   чтобы переиспользовать в других эндпоинтах.
   Положи в src/utils/cache.py.

─────────────────────────────────────────────────
Created src/utils/cache.py
Applied edit to src/routes/search.py
Commit b9c1d5f: Extracted caching logic into reusable
  @cached decorator in utils/cache.py
─────────────────────────────────────────────────