Что можно понять только написав своего агента для кодинга

Сейчас агентов пишут все. Ваш сосед пишет агента. Ваш кот, вероятно, тоже, просто пока не пушит на GitHub. И если вы ещё не начали, то как минимум думали об этом в душе, прикидывая архитектуру между шампунем и кондиционером.

Чем интересен именно кодинг-агент? Это идеальная ловушка для самоуверенного разработчика.

Цель кристально ясна: читай код, пойми его, измени, проверь. Что может пойти не так? (Спойлер: вообще всё.) Под этой обманчивой простотой скрывается хаос — модели, которые обходят ваши ограничения с грацией уличного кота, инструменты, ломающиеся способами, о которых вы не подозревали, и промпты, которые прекрасно работают ровно до момента обновления модели на одну минорную версию. (да да, я тоже чувствую что это писал AI, но в таком мире живем)

Я построил такого агента, тут расскажу что я узнал — и, надеюсь, этого хватит, чтобы вы захотели повторить мой путь. Или хотя бы посочувствовать.

Что я собственно построил

Назвал я его QuillCode. Звучит солидно, а внутри — вот что:

• Терминальный UI на ratatui: два потока ОС, один для интерфейса, другой для агента. Пока один рисует красивые рамочки, второй решает судьбу вашего кода.

• Цикл агента: вызвать LLM, выбрать инструмент, выполнить его, скормить результат обратно. Повторять до просветления (или исчерпания токенов — что наступит раньше).

• Восемь инструментов: поиск файлов, чтение кода через AST (не просто тупой дамп строк), патчинг через unified diff, выполнение shell-команд, веб-поиск и TODO-список, который агент ведёт сам. Да, он организованнее меня.

• Система разрешений: чтение — пожалуйста, запись и shell-команды — только с одобрения. Демократия в рамках отдельно взятого терминала.

• Сжатие контекста, режим планирования и режим поведенческого дерева, который заставляет агента идти по фиксированной последовательности шагов, хочет он того или нет. Иногда нужна твёрдая рука.

Работает ли это? Да, реально работает. Я гонял его на настоящих задачах — крупный рефакторинг через режим плана, где агент методично прошёл через список из 12 пунктов, пока я одобрял каждый шаг; небольшая LMS-система, которую я подкинул ему как бенчмарк — он собрал что-то похожее на правду и довольно функциональное.

Все же оговорюсь, что значит «работает». Он заметно менее эффективен, чем Claude Code. Требует больше присмотра. Иногда принимает решения, от которых хочется закрыть крышку ноутбука и пойти гулять. Для серьёзной работы я возьму Claude Code не задумываясь.

Но эффективность не была целью. Целью было понимание. И вот как оно выглядит.

Инструменты: кажется просто, пока не попробуешь

Восемь инструментов. Больше вам, скорее всего, не нужно.

Исследования поведения агентов стабильно показывают деградацию после примерно десяти инструментов. Модели начинают путать похожие инструменты, вызывать их не в том порядке и — мой любимый баг — изобретать инструменты, которых не существует. «А давайте-ка я вызову super_mega_refactor!» Нет, дружок, такого у тебя нет.

Возьмём read_objects. Наивный инструмент «прочитай файл» на файле в 4000 строк мгновенно забивает контекстное окно — модель вываливает всё содержимое и у неё не остаётся места даже подумать. Поэтому read_objects принимает диапазоны строк и имена символов через парсинг AST. Модель вынуждена просить именно то, что ей нужно. Описание начинается так: «Используйте для чтения конкретных секций файла. Не вызывайте на весь файл, если он не маленький.» Это ограничение не зашито в код. Оно зашито в текст на английском языке. В тот день, когда я убрал это предложение, потому что оно показалось избыточным, качество вызовов заметно просело. Одно предложение. На естественном языке. Определяло поведение системы. Добро пожаловать в 2026 год.

Или patch_files — патчинг через unified diff вместо замены всего файла. Diff меньше (меньше токенов), его можно проверить глазами (видно, что именно изменилось) и сложнее случайно повредить соседний код. Компромисс: генерировать валидные диффы для модели сложнее, чем выплюнуть весь файл целиком. Вы будете видеть кривые диффы. Контекст не совпадёт, номера строк уедут на единицу, патч применится не к той функции. Надежность здесь — это и есть настоящая задача.

Когда инструмент ломается, модель импровизирует

Вот об этом вас никто не предупреждает. И это, пожалуй, самое увлекательное наблюдение.

Я раз за разом видел это в трейсах. patch_files падает — кривой diff, несовпадение контекста, что угодно — и следующий вызов в трейсе: shell_exec с sed -i, чтобы сделать ту же правку через шелл. И это работает. Но обходит валидацию патча, отслеживание разрешений, аудит. Модель не была злонамеренной. У неё была цель, основной путь заблокировался, и она нашла обходной. Абсолютно логичное поведение, которое создаёт именно ту поверхность атаки, от которой вы строили всю систему инструментов.

Ещё парочка граблей, на которые я наступил:

• find_files с настолько широким glob-паттерном, что он нашёл сотни файлов, после чего агент начал read_objects на каждом последовательно — весь бюджет вызовов сгорел в одной фазе разведки. Как турист, который фотографирует каждый камень в музее.

• shell_exec с cat somefile.rs, когда рядом лежал специальный инструмент для чтения. Модель просто забыла, какой инструмент для чего. Так и не смог от этого полностью отучить.

• Агент зацикливается на одном и том же падающем вызове три раза подряд, каждый раз чуть меняя аргументы, вместо того чтобы остановиться и подумать.

• Unicode и ANSI escape-коды в результатах инструментов ломают парсинг следующего ответа LLM, что триггерит очередной shell_exec для очистки. Домино из костылей.

Рецепт один и тот же: сделайте основные инструменты настолько надёжными, чтобы аварийный выход через шелл был непривлекателен. И конкретные сообщения об ошибках решают всё. «Error: patch failed» — модель попробует что-то другое. «Hunk 2 did not apply: expected fn process( on line 47, found fn process_item( — try re-reading the file before patching» — модель обычно сделает именно это, и следующая попытка будет успешной.

Проблема разрешений, или демократия в терминале

Принцип прост: чтение — автоматически, запись и шелл — с подтверждением. Реализация тоже проста. Калибровка — вот где начинается настоящая боль.

Если каждый shell_exec — включая рутинные cargo check, npm test, git status — требует явного подтверждения, пользователь через десять минут жмёт «разрешить на всю сессию». И вот вы потратили кучу инженерных усилий на систему, которая на практике производит один результат: один клик в начале сессии. Театр безопасности, билет в один конец.

Настоящий вызов — не сама проверка разрешений. А понимание, когда система должна доверять контексту, а когда — настаивать на вопросе. Я пока не нашёл правильный баланс. Возможно, это самая сложная дизайн-задача во всём проекте. (И, честно говоря, я не вижу, чтобы кто-то решил её хорошо в других агентах — разве что считать YOLO за решение).

Один агент, много диалектов

Моё наивное предположение номер два: раз OpenAI интеграция работает, добавить другого провайдера — дело часа. Новые DTO, новый транслятор, подключить. Подержите моё пиво.

Механическая часть действительно была нормальной. Поведенческая — всё сломала.

Каждая модель — каждая версия каждой модели — настроена по-разному, реагирует на промпты по-разному, ломается по-разному и по-разному терпит ваши формулировки. Нельзя написать один системный промпт, один набор описаний инструментов, один набор инструкций и ожидать консистентного поведения. Что для одной модели — чёткая команда, для другой — философское размышление. Что одну держит в фокусе, другую парализует.

Мне даже не пришлось менять провайдера, чтобы это увидеть. В середине разработки OpenAI выпустил gpt5.3-codex. Я обновился, ожидая плавного перехода. Вместо этого агент перестал действовать. Он читал файлы, выдавал вдумчивый анализ того, что нужно изменить — и... ничего не делал. Просто пересказывал. Никаких патчей, никаких правок, никаких вызовов инструментов, которые реально трогали код. Из деятеля превратился в литературного критика.

Те же самые промпты, которые прекрасно работали с gpt5.2-codex, теперь производили агента-рассказчика.

После ковыряния в исходниках codex и переписывания фрейминга действий в системном промпте, подсказок по бюджету вызовов и нескольких описаний инструментов — он снова начал работать. Но до пиковой производительности так и не дотянул. Я сдался. Жизнь коротка.

Поэтому мой агент поддерживает только OpenAI. Не потому что добавить HTTP-клиент другого провайдера сложно — это как раз тривиально. А потому что каждая модель — это новая поведенческая поверхность, которую нужно настраивать, тестировать и поддерживать. Это не инфраструктурная проблема. Это проблема бесконечной калибровки, и стоимость растёт с каждым добавленным провайдером.

Заглядываем под капот другим агентам

Я интегрировал трейсинг-платформу OpenAI в своего агента — каждый запуск становится трейсом с дочерними спанами на каждый вызов LLM, каждое использование инструмента, каждую проверку разрешений. Полные пейлоады, счётчики токенов, латенси. Когда что-то идёт не так (а с LLM вы почти никогда не можете воспроизвести баг детерминированно — это вам не NullPointerException), открываешь дашборд и смотришь выполнение шаг за шагом.

Это быстро стал самым полезным инструментом отладки в проекте.

Потом я подключил тот же трейсинг к Codex и OpenCode. Запустил одинаковые задачи. Сравнил трейсы бок о бок.

Скелет тот же. Тот же цикл. Та же цепочка: вызов-инструмента / наблюдение / вызов-инструмента / наблюдение. Тот же паттерн «сначала читай, потом пиши».

Их агенты, конечно же, существенно отполированнее — лучше описания инструментов, более изощрённое управление контекстом, более элегантная обработка краевых случаев — но фундаментальная форма узнаётся мгновенно. Никакой секретной архитектуры. Просто цикл и месяцы кропотливой итерации над всем, что его окружает.

Это было прояснительно так, как чтение статей об агентах никогда не было.

RAG? Спасибо, нет

Также закрыл для себя вопрос, над которым я колебался: стоит ли пробовать RAG.

В начале 2024-го общепринятая мудрость гласила: собери векторное хранилище, заэмбедди документы, доставай релевантные куски перед каждой генерацией. Для некоторых приложений — разумно. Для кодинг-агента — путь в никуда.

Кодинг-агенту не нужен вероятностный поиск. Ему нужно знать точно, как выглядит код.

RAG добавляет индексирующий пайплайн, который должен оставаться синхронизированным по мере изменения файлов, шаг извлечения, который может выдать не тот кусок из-за семантического пересечения между несвязанными функциями, и слой косвенности между агентом и тем, что ему реально нужно увидеть. Файл — это ground truth. У агента есть инструменты, чтобы его прочитать. Просто дайте ему прочитать.

Инфраструктурная рутина, или Claude Code + Opus 4.5

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

Для выбранного мною языка не было официальной клиентской библиотеки OpenAI. «Не проблема», — подумал я. У меня есть Claude Code с Opus 4.5. Документация API есть, опенсорсные примеры на других языках есть. Один хороший промпт — и готово.

Не готово. API LLM-провайдеров на удивление нетривиальны. SSE-стриминг, который нужно парсить инкрементально. Формат ответа, который меняет форму в зависимости от того, возвращает модель текст, вызов инструмента или частичный поток токенов. Обработка ошибок на двух уровнях — HTTP и API. Мне пришлось самому читать документацию (я знаю, шокирующе), проходить через падающие запросы в отладчике и принимать осознанные архитектурные решения, прежде чем Claude Code смог построить что-то надёжное.

Вот паттерн, в который я упирался снова и снова: Claude Code был быстр, когда я давал ему структуру, но не мог надежно создать эту структуру сам. До того, как ключевые дизайн-решения были приняты, каждая сгенерированная попытка содержала тонкие баги, проявлявшиеся только в рантайме. После — работало замечательно.

Модель разговора в моём агенте:
Session
└─ Request (один на пользовательский промпт)
└─ Steps[]
├─ UserPrompt
├─ AssistantMessage
├─ ToolCall { name, args }
└─ ToolResult { output }

API OpenAI ожидает плоский массив сообщений с полем role и пейлоадами, меняющими форму в зависимости от роли. Маппинг между моими доменными типами и wire-форматом кодирует решения о том, что означает история разговора — какие шаги становятся контекстом, как результаты инструментов вплетаются обратно, что выбрасывается при сжатии. Эти решения не генерируются из API-спеки. Их нужно принять.

src/infrastructure/openai/ ├── client.rs # HTTP, аутентификация, ретраи ├── dto/ │ ├── request.rs # ChatCompletionRequest и вложенные типы │ └── response.rs # ChatCompletionResponse, ToolCall и т.д. └── translator.rs # ChainStep → ChatMessage ← самый интересный файл

Зато потом, когда этот слой был надёжен, добавление поддержки изображений — вставить скриншот, чтобы агент рассуждал о нём через vision API — я полностью отдал Claude Code. Заработало с первого раза. Инвестиция в фундамент окупилась.

Зачем вам это строить

Мой агент — это и близко не конкурент Claude Code. Он менее надёжен, требует больше присмотра, и разрыв в качестве на сложных задачах — значительный. Большую часть этого разрыва не закроешь инженерией — это фундаментальная сложность работы с чем-то недетерминированным, непрозрачным и не обученным специально под эту задачу.

Но путь стоил каждого мучительного вечера. Отладки трейсов. Погоня за описанием инструмента, в котором не хватало одного предложения. Открытие, что ваш инструмент работает в 95% случаев, но этих 5% хватает, чтобы модель перенаправила всё через shell_exec.

Инженерная поверхность необычно разнообразна — потокобезопасность, парсинг AST, промпт-инжиниринг, управление контекстом, персистентность сессий, системы разрешений — всё в одном проекте, всё взаимодействует друг с другом. Это инженерно интересно так, как большинство пет-проектов обычно не бывают.

А за пределами инженерии вы выходите с интуицией, которую невозможно получить иначе. Когда Claude Code принимает странное решение, жжет токены в цикле или задаёт неожиданный уточняющий вопрос — я теперь вижу почему. Я вижу цикл, цепочку, бюджет инструментов. Эта ментальная модель определяет, как я пишу промпты, как структурирую задачи и — самое полезное — как решаю, что отдать ИИ, а что делать самому.

Попробуйте сами. Потратите сильно больше одних выходных.