Если агент генерирует не то — не лезьте сразу в код. Чините намерение

Если AI-агент сгенерировал не то, первая реакция разработчика обычно простая: открыть файл и руками поправить код.

Логично. Мы так привыкли. Баг увидел — полез в реализацию. Компонент кривой — поправил компонент. API-контракт уехал — подкрутил метод. Текст не в том стиле — переписал текст.

Но в агентной разработке это часто лечение симптома, а не причины.

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

Неправильная генерация — это симптом

Когда агент делает не то, проблема не всегда в его «тупости». Часто проблема выше:

• ему не дали нормальный контекст проекта;
• правило существовало только в голове разработчика;
• спецификация была слишком общей;
• Definition of Done не был записан;
• workflow повторяется, но не оформлен как skill;
• устойчивые факты не сохранены в память.

В итоге агент не нарушает систему. Он честно работает внутри той каши, которую ему дали.

Если вход — туман, выход — уверенно оформленный туман.

Почему ручная правка кода не решает проблему

Ручная правка чинит один артефакт. Один файл. Один ответ. Один кусок результата.

Но если причина ошибки лежит в контексте, агент повторит её снова. В следующей задаче. В соседнем модуле. В другом формате. С новым выражением лица, но с тем же смысловым косяком.

Это как каждый раз вытирать воду с пола, но не чинить трубу.

Да, иногда код надо править руками. Но если агент системно делает не то — сначала надо чинить слой намерения.

Что такое слой намерения

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

• цель задачи;
• контекст проекта;
• архитектурные правила;
• стиль и формат ответа;
• запрещённые действия;
• критерии готовности;
• тесты и проверки;
• процедура выполнения.

В обычной разработке многое из этого живёт в голове команды. В агентной разработке так нельзя. Агент не читает мысли. Пока что. Жаль, конечно, но батарейка телепатии ещё не сертифицирована.

Поэтому намерение надо вытаскивать наружу и записывать.

Правильный порядок исправления

Когда агент ошибся, не начинайте сразу с кода. Пройдите цепочку сверху вниз:

1. Намерение. Что мы вообще хотели получить?
2. Спецификация. Как именно это должно работать?
3. Контекст проекта. Где это правило записано?
4. Skill. Повторяется ли этот workflow и надо ли оформить его как навык?
5. Память. Это устойчивый факт, который агент должен помнить дальше?
6. Исполнение. Только теперь — код, тесты, публикация.

Если чинить только шестой пункт, первые пять останутся дырявыми. Агент снова туда провалится. Не потому что злой. Потому что карта местности нарисована маркером на салфетке.

Пример: агент сделал не тот формат

Плохой сценарий:

Агент написал статью не в том стиле. Я руками переписал.

Что произойдёт дальше? Скорее всего, следующую статью он снова напишет не так. Потому что правильный стиль остался в вашей голове, а не в системе.

Нормальный сценарий:

• обновить style guide;
• добавить примеры хорошего и плохого текста;
• записать структуру статьи в проектный файл;
• оформить повторяемый workflow как skill;
• дать агенту сгенерировать заново.

Вот это уже не ручная заплатка. Это улучшение машины.

Пример: агент забыл тесты

Плохой сценарий:

Агент сделал фичу без тестов. Я сам дописал тесты.

Лучше:

• добавить в спецификацию: фича не считается готовой без тестов;
• описать минимальный набор проверок;
• зафиксировать это в Definition of Done;
• обновить skill разработки;
• попросить агента пройти задачу заново.

Теперь агент не просто «получил по рукам». Он получил правило.

Спецификация важнее разового промпта

Промпт — это кнопка запуска. Спецификация — это карта местности.

Можно каждый раз писать агенту: «сделай аккуратно, не забудь тесты, соблюдай стиль, проверь результат». Но это ручное шаманство.

Гораздо лучше держать правила в нормальных местах:

• PROJECT.md — цель, статус, правила проекта;
• AGENTS.md — инструкции для агентной работы;
• CLAUDE.md или аналог — проектные подсказки;
• issue/design doc — спецификация задачи;
• tests — формальная проверка результата;
• skills — повторяемые процедуры;
• memory — устойчивые факты.

Тогда агент работает не по настроению, а по системе.

Что превращать в skills

Skill нужен там, где задача повторяется.

Например:

• как писать статьи для блога;
• как публиковать в Telegram;
• как проверять SEO;
• как делать code review;
• как оформлять PR;
• как запускать тесты;
• как собирать контекст перед задачей;
• как работать с конкретным API.

Skill — это не «будь умным». Это рабочий регламент. Маленький производственный станок, который агент может запускать снова и снова.

Что класть в память

Память — не мусорный ящик. Туда не надо класть всё подряд.

В память идут устойчивые факты:

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

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

Главный сдвиг в мышлении

В старой модели разработки человек писал код, а документация часто была вторичной.

В агентной модели документация, спецификация и контекст становятся управляющим слоем. Потому что агент исполняет не вашу интуицию, а записанную систему правил.

И это меняет роль разработчика.

Разработчик становится не только автором кода, но и архитектором намерений:

• формулирует правильную задачу;
• описывает границы;
• фиксирует правила;
• создаёт проверку;
• закрепляет удачные workflows;
• даёт агенту исполнять.

Это не отменяет код. Это поднимает точку управления выше.

Вывод

Если AI-агент ошибся, не спешите чинить только код.

Сначала спросите:

• какое намерение он не понял?
• какой контекст ему не дали?
• какое правило не было записано?
• какой workflow надо превратить в skill?
• какой факт надо сохранить в память?

Агентная разработка — это не «AI пишет код, человек подтирает».

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

Если вы всё время правите только код — вы работаете как ручной костыль.

Если вы правите спецификацию — вы улучшаете машину, которая будет делать следующие задачи.

Вот там и начинается настоящая агентная разработка.