Ещё недавно на вопрос «как заставить агента вести документацию?» я отвечал: «Никак»)) Это был честный ответ из моего опыта, но с оговоркой, которую раньше я не делал. Модели меняются. Новые сильные модели заметно лучше следуют проектным правилам, реже теряют записи и, по моему наблюдению, тратят на работу меньше токенов, особенно если им надо разобраться в тысяче строк документов вместо десяти тысяч строк кода. Картина, в которой агент обязательно забывает обновить документы после каждой задачи, уже устарела.
Гарантии, впрочем, не появилось. И даже идеальная дисциплина в пределах одной задачи не решает второй проблемы: документы со временем начинают противоречить друг другу, старые указатели остаются на виду, а важное решение оказывается записано не там, где его будет искать следующий агент. Поэтому я разделяю ведение документов во время работы и ревизию всей системы. Для этого нужны разные проверки.
Что записывать после задачи
Когда я начинал Mango, мне понадобился файл для передачи дел между сессиями и агентами — op-exchange.md. Он нужен не для отчёта обо всём рабочем дне, а для незавершённого: где остановились, что уже проверили, какие попытки не сработали и какое действие следующее. Тогда агенты заполняли его по моей команде. Сейчас ведут его сами, но назначение файла от этого не изменилось.
Главный вопрос перед записью: что следующему агенту нужно знать, чтобы не перепутать состояние задачи? Ответ определяет и место записи:
- Изменённое поведение или завершённая правка — в истории изменений, со ссылкой на конкретный результат и проверку.
- Действующее решение или правило — в предметном документе рядом с тем, к чему оно относится; если решение заменило старое, указываются причина и граница применения.
- Незавершённая работа — в передаче дел: текущее состояние, уже пройденные попытки, следующий шаг и условие закрытия.
- Факт о живом сервере, версии или опубликованной странице — в датированной записи с источником проверки. Вчерашний отчёт сам по себе не подтверждает сегодняшнее состояние.
Это не универсальные названия файлов. У другого проекта набор может отличаться. Важна ответственность каждого документа: один отвечает за действующее правило, другой — за историю изменения, третий — за открытый хвост. Если всё складывать в один журнал, найти ответ трудно. Если копировать одно решение в три места, они со временем разойдутся.
Полезная запись отделяет действие от его проверки. У меня был ответ Клода после правки интерфейса: компиляция и автоматические проверки прошли, но экран на телефоне он не смотрел и попросил меня оценить расположение элементов. Такой ответ честнее, чем «интерфейс готов». В документе для следующей сессии я бы оставил примерно это:
Изменено расположение элементов на экране. Сборка и автоматические проверки прошли. На устройстве экран не проверен. Следующий шаг — посмотреть расположение и перекрытия на телефоне. Закрыть задачу после этой проверки и нужной правки, если она понадобится.
Это пример формата, не отчёт о том, что указанная проверка уже выполнена. В реальной записи нужны ещё ссылка на изменение и тот, кто отвечает за следующий шаг. Смысл в границах: сборка, проверка на устройстве и принятие результата — три разных состояния. Новый агент не должен угадывать их по слову «готово».
Если ошибка не исправлена, в передаче полезно оставить и отрицательный результат. «Пробовали ещё раз — не помогло» почти ничего не сообщает. «Проверили предположение о причине; ошибка воспроизводится тем же способом; дальше проверить другой участок» не позволит просто повторить вчерашний круг. Подробную стенограмму сессии переписывать не надо — достаточно причины, результата проверки и следующего действия.
Проверять на переходах
Я не собираюсь подтверждать каждое открытие файла. Даже слабый агент при таком подходе превратит владельца проекта в кнопку «Продолжить». Проверка записи нужна там, где цена пропуска возрастает: передать работу другому агенту, закончить длинную сессию, назвать задачу завершённой, выпустить изменение.
В этих точках я смотрю не на фразу «документы обновлены», а на маршрут. Какой файл теперь отвечает на вопрос? Попадёт ли в него новый агент из проектных инструкций? Отличает ли запись подтверждённое от гипотезы? Есть ли у открытого хвоста следующий шаг и критерий закрытия? Иногда достаточно открыть один раздел и сразу видно, что передача состоялась. Иногда обнаруживается красивый отчёт в чате и пустота в проекте.
Тогда не обязательно писать ещё одно правило заглавными буквами. Сначала надо понять причину: правила не было, агент не дошёл до него, выбрал не тот документ или понял статус неверно. Только в первом и последнем случаях может понадобиться правка инструкции. Если модель просто пропустила уже известный шаг, полезнее вернуть её к записи и проверить результат. Новая страница правил сама по себе не сделает старую модель внимательнее.
Модель — часть этого процесса
Здесь важна поправка к моему прежнему опыту. На нынешних сильных моделях соблюдать маршрут документов стало заметно проще. Они лучше удерживают указания, реже забывают оформить результат и способны выполнять более длинные задачи без постоянных напоминаний. Поэтому качество документации зависит не только от текста правил, но и от того, кому поручена работа.
По моему ощущению, когда выходит новый флагман, модели, которые были топовыми два поколения назад, иногда начинают работать хуже, чем я их помню. Похожие впечатления я встречал и у других пользователей. У меня даже возникало подозрение, что старым моделям сокращают вычислительный бюджет. Но доказательств этого нет: сравнить их на одинаковых задачах, настройках и контексте я не проводил.
Практический выбор у меня проще. Для серьёзной повседневной работы беру как минимум модель, которая была флагманом в предыдущем поколении. Для сложной архитектуры, конфликтующих правил или решения с высокой ценой ошибки — актуальную топовую. Это не значит запускать самый дорогой вариант на каждый поиск слова в файле.
Если сильная модель подключает субагентов, в правилах должно быть сказано прямо: выбрать модель для каждой подзадачи и указать её явно. Сверить несколько чисел или выписать совпадения из файлов может самая слабая доступная модель; там, где возможна точная проверка скриптом, результат лучше проверить и им. Разобраться в противоречии документов или принять рискованное проектное решение должен более сильный исполнитель. Основная модель затем сводит результаты и отвечает за итог. Иначе можно получить десять флагманов, занятых простой механической работой, и счёт за задачу вырастет быстрее, чем качество документации.
Для субагента полезно задать узкое поручение: какие файлы и вопрос он проверяет, какой результат возвращает и что считает доказательством. Тогда модель можно подобрать осмысленно. «Посмотри всю документацию и скажи, всё ли хорошо» — плохое задание даже для флагмана: оно не задаёт границы проверки, а значит, и ответ «всё хорошо» проверить почти невозможно.
Ревизия — отдельная задача
Даже когда каждый агент аккуратно обновляет свой участок, система в целом стареет. Новый документ забирает функцию старого; ссылка из инструкции ведёт в прежний раздел; два файла начинают отвечать на один вопрос. Рабочий агент может добросовестно записать результат по своему маршруту и не заметить, что сам маршрут пора менять.
Поэтому я периодически поручаю отдельные ревизии. Агент проходит по документам и связанному коду, ищет пропущенные записи, устаревшие указатели и противоречия, готовит предложения с основаниями. Обычно отчёт достаточно хорош, чтобы я его утвердил. Но запуск такой работы и решение о спорных изменениях остаются за мной. Не надо считать каждую завершённую задачу поводом перелопатить весь проект.
Такой проход можно разбить на конкретные шаги:
- Определить область: например, один рабочий процесс, его код, действующие документы и ссылки из проектного указателя.
- Для каждого утверждения, которое влияет на работу, установить статус: действует сейчас, осталось как история или ещё требует проверки. Сверять изменчивые факты с текущим состоянием, а не с датой старой заметки.
- Выписать расхождения с адресами источников и предложить правку: какой документ станет действующим, какие ссылки надо перенаправить, что сохранить как объяснение прежнего решения.
- После принятия правок обновить маршрут чтения и убедиться, что следующий агент попадёт в исправленный раздел, а незакрытые вопросы не исчезли из передачи дел.
Без последнего шага ревизия может сделать текст точнее, но оставить прежнюю ошибку на входе: агент продолжит открывать старый файл и никогда не увидит новый.
Формальные проверки здесь помогают, но не заменяют разбор. Скрипт может найти сломанную ссылку, проверить обязательные поля или показать, что файл стал слишком большим. Он не решит по одному названию, действительно ли задача закрыта, какое из двух правил действует и следует ли убрать старый документ. Для этого нужны содержание, история решения и иногда сверка с тем, как ведёт себя код.
Однажды мне показалось, что TODO и backlog в Mango конфликтуют. Я попросил Клода разобраться. В них смешались завершённый этап, исправление, которое ещё ждало выпуска backend, и идея без оценки. Названия файлов перестали отражать содержимое; в итоге мы объединили их и разнесли записи по разделам. Форматный линтер не объяснил бы, что делать с этими тремя разными статусами.
При этом агент не должен молча удалять прежний документ только потому, что работа переехала в новый. Старый может объяснять, почему решение было принято. Сначала нужно определить действующий источник, исправить маршрут и сохранить полезную историю. Что именно оставлять под рукой, а что отправлять в архив — тема для следующего разговора.
Современные модели уже снимают заметную часть ручных напоминаний. Оставшаяся задача владельца — задать понятные места записи, подобрать исполнителя по сложности работы и проверять важные переходы, а время от времени — отдельно пересматривать саму структуру. Тогда документация действительно помогает прогрессу работы, а не просто растёт вместе с проектом.