Раздутый AGENTS.md не делает ИИ-агента управляемым

ИИ-агент изменил лишний файл. В AGENTS.md добавили новый запрет. На следующей задаче агент не запустил тесты — появился ещё один обязательный пункт. Потом он уверенно додумал требования, и файл пополнился фразой «если не уверен, сначала спроси».

Через несколько недель AGENTS.md уже напоминает трудовой договор с приложениями. Но рядом с агентом всё равно сидит человек: объясняет контекст, следит за границами и перепроверяет слово «готово».

Мы называем это улучшением инструкций. Иногда честнее назвать это журналом прошлых аварий.

Промпт описывает конкретный запрос. AGENTS.md должен помогать агенту понять постоянные правила проекта: где источник истины, что нельзя менять, какие проверки обязательны и где нужен человек. Но один файл не заменяет саму систему работы. Здесь неожиданно полезна одна из базовых практик Канбана — явные правила.

Типичный цикл начинается просто. Мы просим агента добавить функцию, изменить интерфейс или починить тест. Он делает лишнее, пропускает проверку или уверенно сообщает о завершении. После этого в AGENTS.md появляется новое правило:

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

У агента остаются вопросы, на которые длинный AGENTS.md не отвечает однозначно. Какой документ актуальнее? Какое из двух противоречащих правил важнее? Можно ли изменить соседний модуль, если без этого тест не проходит? Что считать доказательством завершения? Когда продолжать поиск решения, а когда остановиться?

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

Когда говорят о Канбане в разработке, обычно вспоминают доску, WIP-лимиты и время прохождения задачи. Для работы с ИИ сейчас интереснее другое: Канбан предлагает сначала сделать текущий способ работы явным.

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

Минимальный набор правил отвечает на семь вопросов.

Вместе эти ответы образуют рабочую договорённость между человеком, агентом и системой проверок. Без неё агент вынужден угадывать правила организации по одному запросу. Иногда угадывает. На этом опасно строить процесс.

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

Проблема начинается, когда AGENTS.md пытаются сделать единственным контейнером для всего. Постоянные принципы и карта источников истины могут жить в нём. Архитектурные решения — в ADR. Требования конкретной задачи — в самой задаче. Проверяемые ограничения — в тестах, линтерах и CI. Хороший AGENTS.md не хранит всю организационную память. Он помогает быстро найти применимое правило и понять, какая проверка докажет его выполнение.

У такого подхода есть важное следствие: правило можно версионировать. В diff видно, что именно изменилось. В истории — после какого события. На следующей задаче — помогло ли изменение или мы просто добавили ещё один абзац, который никто не исполняет.

В одном из моих проектов AGENTS.md сначала представлял собой подробную карту продуктовых документов, реализации, проверок и доставки. После ретроспективы мы собрали правила вокруг одного пути изменения: от задачи и применимых принципов к решению, доказательствам, PR и production.

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

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

Фраза «добавим ещё одно правило в AGENTS.md» звучит разумно и сама по себе почти ничего не меняет. Она фиксирует последствие сбоя, но не отвечает, почему правило не сработало раньше и как проверить его в следующий раз.

Полезнее рассматривать ошибку как сигнал к небольшому инженерному эксперименту:

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

В первом случае мы усилили пожелание. Во втором — изменили систему.

Так же работает человеческое подтверждение. Фраза «не публиковать без согласования» становится реальным правилом, только когда между подготовкой материала и публикацией есть отдельный гейт. До него агент может создать черновик или предпросмотр, после него — выполнить публикацию. Одобрение текста и разрешение на внешнее действие не должны подразумевать друг друга.

Есть три уровня явности.

Текстовая договорённость помогает одинаково понять следующий шаг. Например: «При неясном источнике истины вернуть вопрос».

Исполняемая проверка ловит отклонение автоматически. Например: тест контракта, линтер, проверка схемы или запрет на попадание секретов в diff.

Человеческий гейт нужен там, где решение зависит от контекста или цена ошибки высока. Например: публикация, миграция production-данных, изменение прав доступа или необратимое удаление.

Не стоит превращать каждую договорённость в сложную автоматизацию. Но критичное правило, которое регулярно нарушается и допускает машинную проверку, не должно оставаться абзацем в AGENTS.md. Иначе оно украшает процесс, а не управляет им.

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

Цель: какое наблюдаемое поведение должно измениться. Границы: что можно и нельзя затрагивать. Источник истины: где проверять требования и текущее состояние. Проверка: какие команды или сценарии подтверждают результат. Остановка: когда завершить работу, а когда запросить решение человека.

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

Не нужно сразу описывать всю разработку. Возьмите последний повторяющийся сбой в работе с ИИ-агентом и задайте пять вопросов:

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

Главный вклад Канбана в работу с ИИ — не новая доска для агентов. Это видимый, обсуждаемый и изменяемый способ работы.

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

И последний неудобный вопрос: что в вашей разработке растёт быстрее — возможности ИИ-агента или AGENTS.md?