Как пользоваться Aider: пошаговое руководство

Чтобы пользоваться Aider, установите его через aider-install или однострочный скрипт, перейдите командой cd в git-репозиторий, запустите aider --model sonnet --api-key anthropic=<key> (или с другим провайдером), добавьте нужные файлы командой /add и опишите изменение обычными словами. Aider правит файлы и коммитит каждое изменение в git, поэтому /undo его откатывает.

Это весь основной цикл. В этом руководстве — то, что делает работу с Aider удобной: API-ключи и модели, какие файлы добавлять, режимы ask, code и architect, форматы правок, работа с git, .aider.conf.yml, интеграция линтеров и тестов и файл соглашений. Все команды и флаги взяты из официальной документации Aider на aider.chat по состоянию на октябрь 2026 года.

Что такое Aider

Aider — это ИИ-напарник для программирования в терминале. Это агент для программирования, который работает почти с любой LLM: Claude, GPT, Gemini, DeepSeek или локальной моделью. Две вещи отличают его от большинства CLI-агентов. Во-первых, он построен вокруг git: каждая правка становится коммитом. Во-вторых, он явно управляет контекстом: вы решаете, какие файлы находятся в чате, а карта репозитория даёт модели краткую сводку по остальному коду.

Если вы сравниваете его с другими терминальными агентами, как пользоваться opencode и как пользоваться GitHub Copilot CLI написаны в том же пошаговом формате.

Шаг 1: установите Aider

В документации Aider описано несколько способов установки. Выберите один.

aider-install ставит Aider в отдельное Python-окружение, чтобы он не конфликтовал с пакетами вашего проекта. Если ставите обычным pip, делайте это внутри виртуального окружения. Если после установки через pip команда aider не находится, то же самое запускает python -m aider.

Шаг 2: API-ключи и модели

Aider обращается к провайдерам моделей с вашими собственными ключами. Быстрее всего начать, передав модель и ключ в командной строке:

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>

Вводить ключ каждый раз быстро надоедает. Aider также читает привычные переменные окружения (ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY, DEEPSEEK_API_KEY и т. д.) и файл .env в проекте. --api-key provider=<key> работает для любого провайдера: --api-key gemini=xxx задаёт GEMINI_API_KEY.

Короткие имена вроде sonnet — встроенные алиасы. По состоянию на октябрь 2026 года документация связывает sonnet, opus и haiku с актуальными моделями Claude, gemini и flash — с моделями Gemini, deepseek и r1 — с DeepSeek chat и reasoner, а 4o — с GPT-4o. Можно задать свои:

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

Внутри сессии /model <name> меняет основную модель, /models <search> ищет доступные модели, а /reasoning-effort задаёт уровень рассуждений для моделей, которые это поддерживают. Для сообщений коммитов и сжатия истории чата Aider использует более дешёвую «слабую модель»; поменять её можно через --weak-model. Хотите работать на своём железе? Это описано в руководстве по локальным моделям для агентов.

Шаг 3: добавьте файлы в чат

Aider правит только те файлы, которые находятся в чате. Их можно назвать при запуске:

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

или добавить позже:

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

В документации Aider на этот счёт однозначный совет: добавляйте только те файлы, которые нужно изменить для задачи. Каждый файл стоит токенов, а слишком много файлов может запутать модель. Aider строит карту всего репозитория, поэтому модель и так знает, где лежат связанные функции и классы, без их добавления. Если вы ничего не добавили, Aider попробует сам определить, какие файлы нужно править.

Команды для управления контекстом:

• /add <files> добавляет файлы, которые Aider может править.
• /read-only <files> добавляет справочные файлы, которые он может читать, но не менять (документация, пример модуля).
• /drop <files> убирает файлы, чтобы освободить контекст; /drop без аргументов убирает все.
• /ls показывает файлы в чате и в репозитории.
• /tokens показывает, сколько токенов занимает текущий контекст.
• /map выводит карту репозитория, а /map-refresh перестраивает её.

Затем опишите изменение:

Добавь пагинацию в эндпоинт list_users: принимай query-параметры page
и page_size, по умолчанию 20 на страницу, и обнови тесты.

Шаг 4: режимы ask, code и architect

У Aider есть режимы чата, и правильный выбор режима — большая часть навыка.

/ask, /code и /architect с текстом после них действуют только на это одно сообщение. Без текста они переключают режим, пока вы не смените его снова; то же делает /chat-mode <mode>. --chat-mode <mode> выбирает режим при запуске, а --architect — короткий вариант.

Документация советует чередовать режимы. Сначала спросите, уточните план, затем дайте агенту писать код:

/ask Как добавить ограничение частоты запросов для маршрута логина, не
трогая другие эндпоинты? Пока ничего не меняй.

Когда план вас устраивает, введите /ok. Это сокращение для «/code Ok, please go ahead and make those changes.» («хорошо, вноси эти изменения»).

Режим architect делит работу между двумя моделями. Основная модель описывает, как решить задачу, а модель-редактор, заданная через --editor-model, превращает это в правки файлов. Если вы её не укажете, Aider подберёт подходящую модель-редактор для каждой основной модели. Это часто помогает с рассуждающими моделями, которые хорошо планируют, но менее надёжно выдают точные правки. Цена: architect отправляет два запроса на одно изменение, поэтому работает медленнее и стоит дороже.

Шаг 5: форматы правок

Формат правок — это то, как модель сообщает Aider, что менять. Трогать его приходится редко, потому что Aider сам выбирает лучший формат для каждой модели, но полезно понимать, что вы видите:

Переопределить можно через --edit-format <format>, а формат модели-редактора — через --editor-edit-format. Если модель всё время выдаёт правки, которые не применяются, для небольших файлов разумно попробовать whole.

Шаг 6: git, автокоммиты и /undo

Лучше всего Aider работает внутри git-репозитория. По умолчанию:

• Каждая правка Aider коммитится с понятным сообщением, которое пишет слабая модель в стиле Conventional Commits.
• Если в файлах были незакоммиченные изменения до того, как Aider их тронет, он сначала коммитит их, чтобы ваша работа и его работа были в разных коммитах.
• К имени автора и коммиттера в его коммитах добавляется «(aider)».

Поэтому страховка простая:

• /diff показывает изменения с момента вашего последнего сообщения.
• /undo откатывает последний коммит, если его сделал Aider.
• /commit коммитит правки, которые вы сделали сами вне чата.
• /git <command> выполняет любую команду git, не выходя из чата.

Части этого поведения можно отключить: --no-auto-commits оставляет правки незакоммиченными для вашей проверки, --no-dirty-commits пропускает предварительный коммит, а --no-git полностью отключает git (документация этого не советует). По умолчанию Aider коммитит с --no-verify, поэтому ваши pre-commit-хуки не запускаются; добавьте --git-commit-verify, если они нужны. Если хотите держать изменения Aider подальше от основной рабочей копии, запускайте его в отдельном git worktree.

Шаг 7: настройте .aider.conf.yml

Флаги, которые вы используете каждый раз, удобно хранить в YAML-файле. Aider загружает .aider.conf.yml из домашней папки, затем из корня git-репозитория, затем из текущей папки; более поздние файлы имеют приоритет. --config <file> загружает только указанный файл.

# .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]

Ключи в файле совпадают с длинными именами флагов без дефисов в начале. API-ключи тоже можно хранить здесь (anthropic-api-key:, openai-api-key: или список api-key: вроде - gemini=xxx), но тогда не кладите этот файл в git. По умолчанию Aider добавляет .aider* в .gitignore, чтобы его файлы истории не попадали в коммиты.

Шаг 8: интеграция линтеров и тестов

Aider проверяет линтером файлы, которые он правит, сразу после каждого изменения, используя встроенные линтеры для большинства популярных языков. Если линтер находит проблемы, Aider пытается их исправить. Можно подключить свой линтер:

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

Команда должна печатать ошибки и завершаться с ненулевым кодом, если что-то нашла. --no-auto-lint отключает проверку.

Тесты работают так же, но по умолчанию выключены. Задайте команду через --test-cmd и включите --auto-test — тогда Aider запускает тесты после каждого изменения и пытается исправить падения (любой ненулевой код возврата). В чате:

• /lint проверяет и исправляет файлы в чате или все изменённые файлы, если в чате ничего нет.
• /test <command> запускает команду и при ошибке добавляет её вывод в чат.
• /run <command> (или !<command>) запускает команду оболочки и позволяет поделиться её выводом.

Шаг 9: файл соглашений

У Aider нет встроенного файла инструкций проекта, который он загружал бы сам. Документированный способ — обычный Markdown-файл, загруженный только для чтения:

# 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

или /read-only CONVENTIONS.md во время сессии, или read: CONVENTIONS.md в .aider.conf.yml, чтобы он загружался всегда. Файлы только для чтения кэшируются, когда включено кэширование промптов, поэтому стоимость остаётся низкой. Если у вас уже есть AGENTS.md для других агентов, можно загрузить его. В статье CLAUDE.md и AGENTS.md есть советы, как писать правила, которым агенты действительно следуют.

Ещё две полезные возможности

Скрипты. --message (или -m) отправляет одну инструкцию, применяет правки и завершает работу, поэтому Aider легко запускать в цикле по файлам:

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

Добавьте --yes-always, чтобы автоматически принимать подтверждения, и --message-file, чтобы читать инструкцию из файла.

Режим наблюдения. Запустите Aider с --watch-files и продолжайте работать в своём редакторе. Напишите комментарий, который заканчивается на AI!, и Aider внесёт изменение; закончите его на AI? — и Aider ответит на вопрос. Работает с комментариями #, // и --.

Частые ошибки

• Добавлять весь репозиторий. Больше файлов — выше стоимость и хуже правки. Добавляйте то, что меняется, используйте /read-only для справочных файлов и доверьтесь карте репозитория.
• Забыть про коммит незакоммиченных правок. Aider коммитит ваши незавершённые изменения, прежде чем тронуть файл. Если это неожиданно, сначала сделайте commit или stash, либо используйте --no-dirty-commits.
• Ждать срабатывания хуков. Коммиты пропускают pre-commit-хуки, если не передать --git-commit-verify.
• Architect для всего подряд. Он удваивает число запросов. Используйте его для сложных изменений; для мелких правок хватит обычного режима code.
• Ключи в закоммиченном конфиге. Если в .aider.conf.yml есть API-ключи, держите его в домашней папке или вне git.
• Слишком длинные чаты. Старые сообщения стоят токенов в каждом запросе. /clear очищает историю чата, а /reset ещё и убирает файлы.

Aider в AgentVera

AgentVera — десктопное приложение для macOS, Windows и Linux, которое запускает CLI-агентов рядом друг с другом в настоящих терминалах, с вашими собственными установками и ключами. Aider — один из поддерживаемых агентов; подробности — на странице Aider в AgentVera:

• Ваши ключи, ваш конфиг. Aider, как обычно, читает ключи провайдеров из переменных окружения или .aider.conf.yml. Модель, выбранная в AgentVera, передаётся через --model, а уровень low, medium или high — через --reasoning-effort.
• Отдельная история у каждого агента. Каждый агент Aider хранит свой файл истории чата в ~/.aider/agentvera/ и продолжает его с --restore-chat-history после перезапуска приложения, поэтому истории нескольких агентов Aider не смешиваются.
• Роль как файл только для чтения. Aider не позволяет расширять свой системный промпт, поэтому роль агента передаётся через --read — тем же механизмом, что и файл соглашений.
• Панели рядом с другими агентами. Запускайте Aider в сетке Workspace рядом с Claude Code или Codex и стартуйте агентов в отдельных worktree из панели Git.
• Ревью и потоки. Агенты Aider получают автоматическое код-ревью по завершении хода и работают в потоках (Pro и Team), рассылках и задачах по расписанию.

Одно ограничение: MCP-серверы, настроенные в AgentVera, в Aider не передаются. Сетка, worktree и код-ревью доступны на бесплатном плане. Скачайте AgentVera и попробуйте.

Итоги

Установите Aider, перейдите в git-репозиторий, запустите его с моделью и ключом и добавляйте только те файлы, которые нужны для изменения. Планируйте через /ask, применяйте через /ok или /code, пробуйте /architect для сложных задач и опирайтесь на /diff и /undo, ведь каждая правка — это коммит. Настройки по умолчанию храните в .aider.conf.yml, правила — в CONVENTIONS.md, а --lint-cmd и --test-cmd пусть ловят ошибки раньше вас. Если вы пользуетесь и агентом GitHub, как пользоваться GitHub Copilot CLI — такое же руководство для него.