У нас дома живёт пёс. Он с нами уже больше восьми лет, давно стал полноценным членом семьи и, как любой уважающий себя член семьи, считает нашу кровать своей. Каждый вечер мы с А. устраиваем шуточный спор, с кем он будет спать: «Моя собака!» — «Нет, моя!» Но у меня есть железный аргумент: в ветеринарном паспорте владельцем записан я. С документом не поспоришь.
Пёс, к сожалению для моего аргумента, паспорт не читает и спит там, где ему вздумается))
В прошлой статье мы подготовили документы проекта и даже проверили, сможет ли новый агент по ним продолжить работу. Казалось бы, теперь достаточно сказать «прочитай доки». Но если бы этого хватало, я бы не повторял эту фразу так часто.
С чего агент вообще начинает
Напомню маршрут, который мы начали собирать ещё в шестой статье. Рабочая жизнь новой сессии начинается с короткой инструкции в собственной системной папке агента: у Кодекса это глобальный AGENTS.md, у Клода — CLAUDE.md. Они объясняют, что проектные знания не надо складывать в личный блокнотик, и направляют агента в документы того проекта, где он сейчас работает. Это указатель на дверь в проект.
За этой дверью агент находит проектный AGENTS.md, краткую память проекта и карту документов. Они ведут дальше: к замыслу, текущей задаче, принятому решению или процедуре выпуска — смотря что ему поручено. Получается цепочка: внутренний вход агента → текущий проект → нужный документ задачи → проверка текущего состояния. После работы результат возвращается в проект. Ни одна из стрелок не требует, чтобы я заново пересказывал историю в чате.
Но довести агента до нужного файла — только половина маршрута. У большого документа тоже должна быть инструкция на входе: для чего он нужен, как устроены разделы, где искать действующую запись, куда добавлять новую и что лежит в соседних документах. В седьмой статье я уже говорил об этом как о порядке ведения файлов. Теперь обнаруживается более неприятная причина: без такой шапки агент может вообще не добраться до нужного места.
Он редко будет читать даже 100 строк подряд. Обычно ищет слово через grep или rg, смотрит первые N строк и несколько совпадений. Это нормальные инструменты, если после поиска открыть найденный раздел и понять его место в документе. Но если шапка не велит сделать именно это, агент легко хватает первую подходящую строку. Нашёл «релизная папка» в записи годичной давности — и уже уверен, что знает действующий путь. А ниже, в разделе текущего выпуска, написано другое.
Поэтому в начале рабочего документа мне нужна не торжественная фраза «здесь хранятся важные сведения», а короткая карта внутри файла. Например: действующие пути — в разделе текущего выпуска; старые записи ниже оставлены для истории; при поиске по ключевому слову читай заголовок и всю соответствующую секцию, сверяй дату и статус; новый результат записывай туда-то, с проверкой и оставшимся вопросом. Такое требование должно стоять в шапке самого документа, а не быть спрятано где-то в общем AGENTS.md: агенту не приходится угадывать, что находится за первыми строками, а мне — объяснять это в каждой новой сессии.
Если такой внутренней маршрутизации нет, файл может быть набит правильными ответами и всё равно оказаться для агента почти бесполезным. Проектная карта честно привела его к документу, а документ не объяснил, как пройти дальше. Поиск здесь не виноват: виновата привычка принимать найденное совпадение за прочитанный контекст. Шапка не гарантирует, что агент выполнит указание, но хотя бы даёт ему следующий шаг прямо в том фрагменте, который он почти наверняка откроет.
Короткая команда «прочитай доки» для агента означает пройти именно этот маршрут. Сначала определить, в какой рабочей папке находишься, затем взять правила оттуда, а не подхватить первую знакомую заметку о похожем проекте. В длинной сессии это полезно сделать снова при смене области работы: маршрут к редакционному черновику и маршрут к выпуску сайта пересекаются, но приводят к разным решениям.
Схема не волшебная. Ни одна стрелка сама себя не нажмёт: агент может остаться в своей старой заметке, перескочить через проектную инструкцию или открыть правильный файл, но неверно понять, к какой части поручения он относится. Два таких случая для примера:
Ответ был написан
Однажды я попросил агента разобраться с готовой сборкой приложения. Он поискал её в старой папке, не нашёл и довольно уверенно сообщил, что нужного файла нет. Актуальный путь уже был записан в документации проекта. Не требовалось гадать, где я спрятал сборку: надо было открыть действующий документ и проверить указанное место.
Когда я указал на это, агент не сразу вернулся к документу — сперва попытался защитить свой вывод. Вот что меня раздражает больше самой ошибки. Не нашёл файл? Бывает. Но «я проверил не там» и «файла нет» — совершенно разные утверждения.
Можно написать ещё одно правило заглавными буквами. Только оно попадёт в ту же папку, которую агент уже пропустил. Проблема здесь не в том, что ответ негде хранить. Проблема в том, что агент успел заменить проверку уверенным предположением.
Пока мы разбирались, выяснилась неприятная вещь: агент всё-таки откуда-то взял старый путь. Не придумал его из воздуха, а опёрся на вторичную заметку, которая когда-то была полезной и со временем устарела. Получается, он даже что-то прочитал. Только выбрал не тот источник и не сверил его с действующими правилами проекта.
И есть ещё один вариант: агент правило прочитал, но понял его так, что стало только хуже.
Прочитал — и всё равно остановился не там
Этот пример случился буквально при подготовке нынешней статьи. После одного моего замечания в общих правилах появилось ограничение: без прямой команды нельзя заходить в папки других проектов и на их серверы. Смысл был конкретный. Если мы работаем над сайтом, не надо из любопытства идти в репозиторий живого приложения или диагностировать его сервер просто потому, что название похоже и доступ под рукой.
Я попросил подготовить восьмую статью. Агент открыл общую папку сайтов и редакции, увидел, что текст лежит в редакционном подпроекте, а сайт — в соседнем подпроекте того же рабочего пространства, и остановился. Объявил их «другими проектами» и попросил у меня отдельного разрешения на каждый переход. Пришлось спросить: а ты сам-то в какой папке сейчас работаешь?
Это противоположность истории со сборкой. Там агент не дошёл до действующего правила. Здесь дошёл, но выдернул из него одно слово и применил запрет к самому поручению. Задача уже определяла рабочую область: подготовить статью для этого сайта. Открыть редакционный текст и исходники сайта было необходимой частью работы. Правило о чужих проектах ограничивало самовольные вылазки за её пределы.
Парадокс получился красивый, но времени он не сэкономил. Агент остановил меня ради разрешения на работу, которую я только что поручил. И если бы я просто дописал в правило ещё три уточняющих абзаца, следующая модель могла бы столь же старательно запутаться уже в них. Иногда надо исправлять документ. Но иногда надо честно признать: документ был понятен, а исполнитель неверно определил, где проходит граница задачи.
Когда надо вернуться к документу
У меня в Mango уже больше ста тысяч строк документации. На таком объёме вместо «прочитай всё» нужен точный вопрос: где сейчас лежит релизная сборка? Какая редакция текста утверждена? Кто работает над этим изменением? Какое условие ещё не выполнено?
Я не хочу, чтобы агент приносил мне отчёт «прочитал 137 файлов». Мне полезнее услышать: «Для этой задачи открыл действующий документ выпуска, там указан такой-то порядок. Проверил актуальную папку; нужный файл есть, но ещё не проверена установка на устройство». Или: «Редакционная версия есть, но её статус — черновик. Подготовил страницу локально, публиковать пока нельзя». Тут сразу видно, какой необходим следующий шаг.
Конечно, агент может красиво написать и неправду. Ссылка на файл сама по себе ещё не доказательство, что он его понял, а перечисление проверок не заменяет сами проверки. Но такой ответ хотя бы можно сверить. С фразой «всё готово, можете не беспокоиться» спорить гораздо труднее: непонятно, что именно агент сделал и на каком основании он предлагает мне расслабиться.
Ответ найден — отлично. Но сверяться с ним полезно не один раз в начале сессии. Перед выводом «сборки нет» надо проверить действующий путь. Перед публикацией статьи — её статус и версию, а не только наличие Markdown-файла. Перед передачей работы другому агенту — узнать, что уже сделано и что ещё открыто. В этих точках цена ошибки меняется, поэтому я хочу видеть, на какую конкретную запись агент опирается.
Ещё один тонкий момент — слово «сейчас». Если в старом отчёте написано, что доступ к сайту не работал месяц назад, это хороший след истории, но плохое основание утверждать, что он не работает сегодня. Если в журнале задача числится открытой, это повод проверить её нынешнее состояние, а не автоматически переделывать чужую работу. Документы помогают искать, но некоторые факты живут своей жизнью: ветка меняется, сборку перекладывают, статью утверждают, сервер перезапускают. Перед выводом о текущем состоянии агенту приходится смотреть и на текущее состояние.
Это особенно важно в длинных задачах. Начинаешь с одного вопроса, по дороге обнаруживаешь смежную проблему, открываешь ещё два файла, и к вечеру уже легко забыть, какой из них был источником, а какой — старой подсказкой. В такой момент я предпочту короткое «нашёл расхождение, сверяю действующую запись» уверенной истории, построенной по первой попавшейся заметке. Не надо останавливаться на каждом шаге; надо замедляться там, где ошибочный вывод потянет за собой следующую ошибку.
При этом я не собираюсь подтверждать каждый его переход по собственной папке проекта. Если агент понял правило слишком широко, остановился посреди обычной работы и спрашивает разрешения открыть нужный файл, он опять применил документ без понимания задачи. Чтение инструкций должно помогать двигаться, а не превращать меня в кнопку «Продолжить». Но в таких случаях полезно снова дать команду "Перечитай доки" с указанием конкретного документа, поэтому их структуру придется помнить.
Что исправлять после промаха
После таких историй есть соблазн сделать правила ещё строже. Один агент полез в старую папку — добавим пять предупреждений. Другой побоялся открыть нужный подпроект — перечислим все папки, куда можно заходить при каждом варианте задачи. Потом кто-нибудь поменяет название проекта, а новое правило тихо устареет. Через полгода агент прочитает именно его и снова будет очень убедительно неправ.
Я разбираю сбои по причине. Не было ответа в документах? Тогда его действительно надо записать, указав, когда он действует. Ответ был только в моей голове? Значит, передать его проекту, а не ещё раз рассказать в чате. Две записи противоречат друг другу? Выяснить, какая актуальна, и обозначить историю как историю. Агент не открыл нужный файл? Вернуть его к маршруту работы и проверить результат, прежде чем редактировать правила. Агент открыл и неверно применил? Показать границу на конкретной задаче и посмотреть, нужно ли уточнение в тексте или достаточно исправить его вывод.
Это не попытка снять с агента ответственность и переложить всё на качество документации. Наоборот: если я каждый раз меняю файл, когда агент просто не сделал свою часть, причина ошибки остаётся на месте. Растёт только количество инструкций, мимо которых он сможет пройти и в следующий раз.
И мой контроль здесь тоже не сводится к тому, чтобы сидеть рядом и нажимать «да» после каждого прочитанного абзаца. Я смотрю на важные переходы: агент сделал вывод по действующему источнику или по воспоминанию? Он выполнил проверку или только написал, что выполнил? Он встретил настоящий конфликт полномочий или придумал его, забыв, где находится? Чем яснее ответ на эти вопросы, тем реже мне приходится восстанавливать картину работы по обрывкам переписки.
И ответ на вопрос «как заставить агента всегда читать документы?» у меня по-прежнему короткий: никак. Я могу сделать путь к нужному решению ясным, попросить назвать источник перед важным выводом и заметить, когда агент вместо проверки пересказывает догадку. Но если он уверенно прошёл мимо написанного, сам факт существования файла его не остановит.
С ветеринарным паспортом ничего переделывать не будем. Я там записан владельцем, А. может со мной спорить, а пёс вечером опять выберет место сам. Ему можно. Агенту, который собрался делать вывод по устаревшей папке или публиковать неутверждённый текст, сначала придётся всё-таки прочитать документы))