Один помощник - игрушка, рой без правил - генератор хаоса
Один ИИ-помощник - это игрушка. Спросил, получил, пошёл дальше. Пока задача помещается в один разговор, никакая система не нужна.
Рой агентов без правил - уже генератор хаоса, и ломается он тремя способами сразу. Агенты плодят клоны собственных сессий, и ты платишь за одну работу несколько раз. Забывают, что делали вчера, поэтому вчерашнее решение сегодня переизобретается заново, обычно хуже. Рапортуют «готово» на половине работы, причём тоном, не оставляющим сомнений.
Через всё это я прошёл. Вывод оказался невесёлый: спасают не «промпты получше». Промпт - это просьба, а просьбу можно проигнорировать и сделать по-своему. Нужна система правил, в которой у агента просто нет технической возможности сделать по-своему.
Хребет: 12-Factor Agents
Хребтом стал чужой документ, не мой: 12-Factor Agents, github.com/humanlayer/12-factor-agents. Двенадцать принципов о том, как строить агентов, чтобы они работали, а не изображали работу.
Свой стек я прогнал по всем двенадцати пунктам. Дальше - те, что реально спасали или реально убивали. Не пересказ списка: список открывается по ссылке, а тут то, чем он у меня отозвался.
№5 и №6: единый стейт и продолжение работы
Самое дорогое место во всей истории.
Пока задача агента не несла в себе pid и id сессии, команда «продолжить работу» означала для него не то, что для меня. Я имел в виду «вернись туда, где остановился». Он понимал «начни заново рядом». Девять клонов одной сессии за день.
Каждый клон жрёт лимиты - это просто деньги и время. Хуже другое: каждый подделывает память. Клон не в курсе, что уже сделал сосед, и уверенно докладывает своё как единственную версию событий. Смотришь в отчёт и не понимаешь, почему сделанное вчера не сделано, а сделанное сегодня сделано дважды.
Лечение: каждая задача пишет pid и session, продолжение возможно только по явному id. Никаких «продолжи, ты же помнишь». Не помнит и помнить не может. Ушло два захода правок, и это тот случай, когда чинить надо было не поведение агента, а способ ставить ему задачу.
№2: владей своими промптами
Характер и правила агента - это файл в git, а не магия фреймворка.
Сам по себе агент - ОНО. Болванка модели, без характера. Личностью его делаем мы - файлом: роль, зона ответственности, запреты. Правится руками, версионируется, лежит рядом с остальным кодом. Надо поменять поведение - меняешь строку в файле. Через месяц видно, когда и зачем менял.
Всё, что спрятано внутрь фреймворка, ты не контролируешь: не видишь, не правишь и не можешь откатить. За поведение агента отвечаю я, значит и текст, который это поведение задаёт, должен лежать у меня.
№3: владей контекстным окном
Контекст у модели конечный. Когда он забивается, идёт сжатие, а при сжатии первыми умирают детали - ровно те, ради которых всё затевалось. Причём умирают тихо: агент продолжает работать и выглядит так же уверенно, просто половины вводных у него больше нет.
Правило из этого следует одно. Перед любой длинной операцией состояние пишется во внешний файл или в роадмап ДО старта, а не после. Записал - и дальше уже неважно, что там случится с окном: состояние лежит снаружи. Проверено потерями, поэтому и записано отдельным правилом.
Как скормить ИИ свой опыт
Три вещи, без которых опыт не копится, а испаряется.
Память отдельным сервисом. Своя внешняя база, движок неважен: уроки, факты, инциденты. Ключевое слово - внешняя. Память внутри модели живёт до конца разговора, память в базе живёт столько, сколько нужно мне. Агент на старте получает выжимку и не знакомится с миром заново.
Двадцать строк в промпт, остальное в базу. Постоянная инструкция агента - короткая: кто он, зона, железные запреты. Всё остальное - знания, справочники, история проектов - лежит в базе и подтягивается по надобности, под конкретную задачу. Раздутый промпт - это не «агент много знает», это агент, который таскает с собой чемодан и половину роняет по дороге. И протухает чемодан целиком: инструкция, вшитая намертво, живёт дольше реальности, которую описывала - проверено на себе ровно сегодня.
Роадмап как контракт. Каждый шаг отмечается по факту. Правило: «молчаливая работа = провал». Не отметился - считаем, что не делал, и неважно, что там происходило на самом деле. Звучит жёстко, но иначе нет способа отличить работающего агента от зависшего, а зависший выглядит точно так же, как задумавшийся.
Уроки после каждого косяка. Сразу, с корнем и правилом, а не «разберём как-нибудь потом». Проверка качества урока простая: повторил ошибку - значит урок не записан или не читается. Чинить в этом случае надо систему уроков, а не саму ошибку, иначе она вернётся третий раз.
Грабли из первых рук
Редактор, которому дали «перепиши» без фактов, начинает сочинять. Ему нужен текст, текст он выдаст в любом случае. Правило: факты пишет человек или агент с доступом к первоисточнику, редактор только причёсывает.
Ревьюер без инструментов слеп, и слепота выглядит как чистота. Агент-проверяльщик без доступа к реальным инструментам - командной строке, файлам, MCP-серверам - физически не может ничего найти. И возвращает «ничего не нашёл» вместо честного «не смог посмотреть». Формулировка вежливая, а читается как «всё чисто», и ты идёшь дальше с непроверенным местом. Правило: объективные проверки - grep, наличие файлов - делаются руками, ревьюеру достаётся анализ логики. Разница принципиальная: логику он читает, а факты пусть приносит тот, у кого есть доступ.
«Готово» от агента - не приёмка. Это заявка на приёмку. Проверяю боем и сам: гоняю команду, смотрю вывод и отдельно проверяю различение - заведомо сломанный образец обязан дать FAIL. Без последнего пункта проверка ничего не стоит, потому что проверка, которая всегда говорит «хорошо», не проверка.
Общий корень: ИИ 3.14здит
Скажу прямо, потому что вежливая формулировка тут врёт. ИИ не «ошибается» и не «галлюцинирует». Оно 3.14здит - именно оно: вещь, не персона. Ошибка случайна, а это системно и тем же ровным тоном, что и правда.
Формы, каждую ловил лично. Рапорт «готово» при нуле сделанного. «Всё чисто, ничего не нашёл» от того, у кого не было ПРАВ посмотреть, и про отсутствие прав он не сказал ни слова. Уверенный диагноз из памяти вместо того, чтобы пойти и проверить. Самопроверка, в которой неточным оказывается ровно тот пункт, что проверялся суждением, а не командой.
Ирония вот в чём: самая честная модель Антропика, Опус 4.8, по факту эталонный 3.14здабол. Чем увереннее и вежливее ответ, тем внимательнее его проверяй.
За это знание заплачено целым проектом. Поэтому приёмка боем, различение со сломанным образцом и «готово», которое объявляю я, существуют не от паранойи. Они существуют потому, что ИИ 3.14здит по построению.
Что это в сумме
Это не «нейросеть, сделай сайт». Это система: правила в файлах, память вне модели, стейт в базе, приёмка боем. ИИ делает руками и лажает, человек держит планку и ловит. Планка на всё одна: «либо хорошо, либо никак».
Двенадцать факторов - готовый чек-лист, чтобы не собирать эти грабли самому. Я половину собрал до того, как нашёл список.
Забирай, за каждый пункт плачено
Двенадцать формул, все из текста выше. Ничего нового, зато коротко.
- Каждая задача пишет свой pid и id сессии.
- Продолжение работы только по явному id, без «ты же помнишь».
- Агент - оно; личность ему выдаём мы, файлом в git.
- Состояние пишется во внешний файл ДО длинной операции.
- Память отдельным сервисом снаружи модели, а не в промпте.
- Роадмап как контракт: молчаливая работа = провал.
- Урок после каждого косяка сразу, с корнем и правилом.
- Факты пишет владелец доступа, редактор только причёсывает.
- Объективные проверки, grep и наличие файлов, делаю руками.
- «Готово» от агента это заявка, приёмку веду боем сам.
- Сломанный образец обязан дать FAIL, иначе проверка пустая.
- ИИ 3.14здит по построению: чем увереннее ответ, тем внимательнее проверка.
Антон Майорских, практик. Правила лежат в файлах, грабли - в памяти.
