В первой - путь от Tabnine до Claude. Во второй - CLAUDE.md и Obsidian как фундамент. Сегодня - про то, что на этом фундаменте строится: промпт-цикл, разведка и ревью.

Главное заблуждение

Когда люди слышат "AI-агент пишет код", они представляют: ты описываешь фичу, агент выдаёт готовый результат, ты коммитишь. Быстро, красиво, эффективно.

В реальности самое ценное, что делает агент в моём процессе - это не код. Это разведка перед кодом и ревью после. Код между ними - механическая часть. А вот найти подводный камень до того как ты написал 500 строк мимо, или поймать что коммит не попал в deploy-ветку - это то, что экономит дни.

Соло-разработчик без команды не может позвать коллегу на code review. У него нет QA, который прогонит smoke-тесты. Нет тимлида, который скажет "стой, ты решаешь не ту проблему". AI-агент закрывает все три роли - если правильно его использовать.

Разведка перед кодом

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

Разведка - это read-only промпт: "ничего не менять, только трассировать факты". Агент читает код, строит карту зависимостей, находит подводные камни. Ты принимаешь решение на основе фактов, а не догадок.

Как это выглядит

Недавний пример. Я проектировал онбординг - второй квест, где игрок должен построить определённое здание. Перед тем как писать квест, отправил агенту разведку:

"Read-only разведка механики build-objective. НЕ менять код, только трассировать. Найди: как считается завершение objective при постройке здания - по количеству или по наличию? Покажи обе ветки: checkTrigger (live-событие при постройке) и rescan (пересканирование при переходе между стейджами квеста). Вывод: можно ли сделать objective 'построй второй дом'?"

Агент прошёл по коду, нашёл обе ветки и вернул факт: rescan засчитывает objective по наличию типа здания (some(type)), а не по количеству. Это значит: если у игрока уже есть один дом, rescan сразу зачтёт objective - игрок даже не увидит задание.

Без разведки я бы написал квест, написал тесты, потом запустил play-test, увидел что квест засчитывается автоматически - и потерял полдня. С разведкой я узнал это за 5 минут и выбрал другое здание для objective.

Почему это работает

Разведка дешевле раунда потерянной работы. Всегда.

Агент читает код быстрее человека - он может за минуту пройти по цепочке вызовов через 10 файлов. Но он не принимает решений. Он трассирует факты и показывает тебе. Ты решаешь.

Ключевое слово в промпте - "НЕ менять код". Без этого агент начнёт "помогать": увидит проблему и тут же полезет её чинить. А ты хотел только узнать - есть ли проблема. Confirm-before-change: сначала пойми, потом делай.

Промпт-цикл: кто думает, а кто делает

После разведки начинается реализация. И здесь важно понимать распределение ролей.

В моём процессе три участника:

Я - формулирую задачу на человеческом языке. "Нужно сделать чтобы первый квест проходился за 2 минуты, а не за 2 часа. Таймеры ранних построек должны быть 10-30 секунд."

Tech Lead (Opus в чате) - переводит задачу в конкретный промпт для агента-исполнителя. Добавляет файлы, ограничения, порядок действий, acceptance criteria. Проверяет результат.

Агент-исполнитель (Sonnet в Claude Code) - реализует по промпту. Пишет код, запускает тесты, показывает diff.

Зачем прослойка? Потому что "сделай чтобы первый квест проходился за 2 минуты" - это задача для человека. Агент с таким промптом уйдёт в галлюцинации: начнёт менять экономику, переписывать квест-систему, трогать файлы которые трогать не нужно. Ему нужен узкий scope: какие файлы открыть, что именно изменить, какие тесты написать.

Вот как выглядит разница. Моя формулировка:

"Первый квест проходится за 2 часа, нужно за 2 минуты. Таймеры ранних построек слишком длинные."

Что из этого собирает Tech Lead для агента-исполнителя:

"Файлы: Buildings.ts (таймеры построек), Quests.ts (конфиг первого квеста). Задача: снизить таймеры ранних построек до 10-30 сек. Конкретно: power_plant 300-30s, house 600-60s, foodFarm 900-20s, gas_extractor 900-20s, mine 1200-30s, warehouse 600-30s. НЕ трогать: апгрейды, стоимость, поздние здания. Тесты: проверить что build-time assertions не сломались. Покажи план до кода."

Одна задача - но во втором варианте агент знает какие файлы открыть, какие значения менять, что не трогать и что проверить. Это и есть работа прослойки.

Правила промптинга

Несколько вещей, которые я усвоил через боль:

Один промпт = одна задача. Не "сделай квесты", а "сделай схему квеста в MongoDB". Не "почини аудио", а "найди почему music ducking не срабатывает при воспроизведении голосовых реплик".

Явный scope. Агент должен знать какие файлы трогать и какие не трогать. Без этого он "поможет" отрефакторить соседний сервис, который работал нормально.

Архитектурные вопросы перед реализацией. Перед реализацией агент должен задать вопросы. Блок в промпте: "Before implementing: list 2-3 alternatives with tradeoffs". Это заставляет его думать перед кодом, а не лезть сразу в реализацию.

Режим в начале. Bugfix, feature, refactor - агент ведёт себя по-разному. Bugfix: минимум изменений, не трогай что работает. Feature: можно добавлять файлы. Refactor: не меняй поведение.

Ревью: где тесты не спасают

Агент написал код. Тесты зелёные. Можно коммитить?

Нет. И вот почему.

Правило про production call site

После одного из багов (конкретный кейс - ниже, в разделе "Wire format gap") у меня появилось правило: "Каждый stateful endpoint или handler - reviewer обязан проверить что production call site существует." Не "тесты проходят?", а "где это вызывается в проде?". Два разных вопроса. Тесты проверяют что код работает правильно. Они не проверяют что код вообще участвует в реальном потоке.

Merge audit: коммит - не в deploy-ветке

Самый показательный кейс. Мы делали аватарную систему - avatarId в game-server, рендер в Unity, выбор на веб-форуме.

Агент написал серверную часть: avatarId в UserSchema, миграция, PUT /auth endpoint. Код на локальной feature-ветке, тесты зелёные. Параллельно другой агент готовил Unity-клиента с новым payload-форматом под этот avatarId.

Мой Unity-агент при ревью проверил: а серверная часть вообще в develop? Оказалось - нет. Коммит был, но не запушен в origin. Без этого аудита мы бы выкатили Unity-клиента с новым форматом payload на прод-сервер, где серверный код с avatarId ещё не появился - клиент ожидает поле, сервер его не отдаёт, результат: плейсхолдеры вместо аватаров у всех игроков.

Тесты были зелёные. CI был зелёный. Локально всё работало. Проблема была не в коде - а в том, что серверный код остался на локальной ветке и не доехал до deploy-ветки.

Урок: "коммит" - не "в deploy-ветке". Перед деплоем проверяй что каждый коммит фактически в develop/main, а не остался на feature-ветке локально.

Где агенты стабильно проваливаются

За полгода я собрал карту провалов. Не абстрактных "LLM плохо считают" - а конкретных мест, где агент делает ошибку, которую ты не ждёшь.

Wire format gap

Один из ранних циклов. Агент реализовал систему доставки квестовых диалогов. Написал структуру данных, написал тесты, всё прошло. Функция getNarrativeForState была экспортирована, покрыта unit-тестами.

Проблема: функция нигде не вызывалась в delivery path. Она была написана, протестирована в изоляции - и не подключена к реальному потоку доставки реплик. Unit-тесты не видят такие разрывы: они тестируют что функция работает правильно, но не что она вообще участвует в процессе.

Вывод: acceptance criteria должна включать "how does this reach the client", а не только data structure tests. Pure function exported но не вызванный = invisible gap для unit tests.

Multi-consumer format

Тикет на аватарную систему. Аватары хранятся на S3, отдаются через CDN. Потребители: веб-форум (Nuxt) и игровой клиент (Unity).

Агент при реализации конвертировал картинки в WebP - "для оптимизации". Разумный дефолт для веба. Проблема: Unity не декодит WebP. Поймали только на pre-deploy smoke-тесте (правило про production call site в действии).

Цена: два хотфикса (WebP - PNG - JPG), три перезаливки в S3. Если бы не pre-deploy audit - ушло бы на прод, и все аватары сломались бы в игре.

Вывод: при инфраструктурном тикете с несколькими потребителями - явно прописывать в промпте требования ВСЕХ потребителей, не только основного.

Probability ranking fail

Аудио-тикет. Музыка в игре звучала замедленно. Агент проанализировал проблему и выдал probability ranking: AudioMixer pitch - 50%, какой-то float bug - 30%, ещё что-то - 20%.

Начали с AudioMixer. Потратили время. Корень оказался в другом: dev-режим ускорял игровое время, WaitForSeconds использовал scaled time, и музыка растягивалась. Вообще не AudioMixer.

Вывод: probability ranking агента - это имитация диагностики, а не диагностика. Агент выдаёт уверенные проценты (50/30/20), которые выглядят как анализ, но это паттерн-матчинг по похожим случаям из обучающих данных, а не реальное исследование причины. Цифры имитируют уверенность, которой у агента нет. Не доверяй ranking'у - проверяй сам. В данном случае простой чек dev-флагов и Time.timeScale закрыл бы вопрос за минуту, а мы потратили время на ложный след.

Чеклист: что проверять в diff review

После полугода работы с агентами мой чеклист ревью выглядит так:

1. Production call site. Где этот код вызывается в проде? Не "есть ли тесты", а "встроен ли в реальный поток".

2. Merge audit. Коммит в git - не в deploy-ветке. Проверь что feature-ветка запушена и смержена.

3. Multi-consumer check. Если у фичи больше одного потребителя - все ли учтены? Формат, протокол, совместимость.

4. Off-scope changes. Агент не залез ли в файлы, которые не должен был трогать? Не "помог ли" отрефакторить что-то по пути?

5. Dev-mode masking. Нет ли в изменениях поведения, которое работает в dev-режиме но сломается на проде? Scaled time, dev-длины, тестовые конфиги.

Главная мысль

Агент может написать 500 строк кода за минуту. Проблема в том, что 200 из них будут не те - если ты не провёл разведку, не сузил scope и не проверил diff.

Ценность AI-агента для соло-разработчика не в скорости написания кода. Она в двух вещах: разведка ловит подводные камни до того как ты написал код, а ревью ловит проблемы до того как они ушли на прод. Вместе они заменяют команду, которой у тебя нет.

Промпт-разведка и diff-review с production-verification - вот что реально работает в соло-разработке, где нет коллег для code review.

Что дальше

Разведка и ревью ловят проблемы заранее. Но некоторые баги проскальзывают - и учат больше, чем все правила вместе взятые. В следующей статье - конкретные production-инциденты и паттерны, которые из них выросли.

Серия «Соло-разработка с AI-агентами». Подписывайтесь на блог в Telegram, чтобы не пропустить.