Воркшоп: «Готовим документацию для агентов»

И снова всем привет. Хорошего вечера пятницы. Мы продолжаем разбираться в том, как создавать новые продукты не руками, а с помощью агентов. И сегодня мы, собственно, продолжим говорить про такую вещь, как контекст-инжиниринг. Но в этот раз мы чуть-чуть отойдём от истории про File Agents MD, хотя сегодня про него тоже будет, но поговорим чуть шире. Мы поговорим про документацию и про то, как роль этой самой документации меняется буквально прямо сейчас. Потому что, ну, собственно, мир меняется, код больше человек не пишет, код теперь пишут агенты. Ну, и, соответственно, документация, которая раньше существовала как ээ такой инструмент объяснения проекта людям, потихоньку теряет свою актуальность, аа, в плане конкретно пользы для людей, потому что теперь документация уже управляет поведением агентов.

Ну и, собственно, что мы разберём в течение ближайшего получаса? Ну, во-первых, в чём, собственно, отличие, а почему Agent MD - это не Redmi и чем они должны отличаться? Поговорим о том, что такое, собственно, single TR, то есть, а, единый источник истины и что он из себя представляет. И самое главное, попробуем разобраться в том, почему это не один конкретный файл, как мы могли думать до этого. А затронем, чем хорошая документация отличается от хорошего промта, наконец, почему лишний контекст может не улучшить результат, а его ухудшить.

Ну и сразу главную идею, она довольно простая и звучит примерно как то, что документация больше не является описанием проекта. Документацию сегодня можно охарактеризовать гораздо шире. Это целая, ну, назовём это когнитивная среда, в которой агент принимает решение, а мы из разработчика потихоньку пере превращаемся в инженера этого пространства, в котором агент должен принимать те решения, которые нам нужны. Ну и, как я сказал, в ближайшие полчаса вы получите, во-первых, структуру а документации, которая а строится по принципам Agent First. Аа по завершению у вас будет минимальный шаблон для файлов политик. Тоже сейчас поговорим об этом. И наконец, самое главное - это чек-лист, по которому можно проверить готовность любого репозитория к агентной работе.

Ну и, собственно, давайте стартовать. И начнём, собственно, с самого главного вопроса. А что, собственно, в индустрии поменялось? Потому что изменилось, на самом деле, не просто то, что модели стали мощнее и стали выполнять больше задач. поменялась сама роль даже не разработчика, даже роль скорее инженера, который управляет процессом разработки. Если раньше инженер, собственно, писал код, а искусственный интеллект помогал там подсказками, автодополнением, в лучших случаях рефакторингом кода, и, соответственно, в этом мире документация была объяснением для команды, для онбординга новых разработчиков, да даже для самого себя, когда там проект открываешь месяц спустя и нужно разобраться, а что ты, собственно, там натворил. Ну вот сегодня ситуация полностью меняется с ног на голову, потому что всё чаще и чаще есть ситуация, когда инженеры у нас не пишут код напрямую.

Одна из, кстати, да, ещё после завершения будет в дополнительных материалах список ссылок. И это не просто список источников, это, на самом деле, ссылки, с которыми имеет смысл ознакомиться. Они довольно интересные. И вот одна из них - это буквально прошлонедельная запись в блоге AI, где они как раз рассказывали о том, что с августа 2025 года построили целый полноценный продукт там на 1,5 млн строчек кода. И важной спецификой этого продукта является то, что человек не написал ни одной строчки, а всё, чем занималась команда - это, собственно, настройкой среды, в которой агент должен работать. И, собственно, у нас сегодня разработчики как раз мигрируют, а, от простого инженера в проектировщика когнитивного пространства для агентов. А, и это важно, потому что агент, когда он работает с нашим кодом, он читает репозиторий, он читает документацию и на основе всего этого принимает какие-то решения. И здесь кроется ряд проблем, потому что если наша документация слишком расплывчата, ну, то и решения агента будут расплывчатые. Если правила не прописаны явно, то он будет вести себя нестабильно. Ну и, собственно, если нет какого-то чётко выверенного канона, на который можно сослаться, то агент будет оптимизировать код под то, что, по сути, увидит первым. И вот самый главный вывод сейчас из того, что аа документация превращается из описания в такой инструмент управления агентами. А, и прежде, чем погрузиться в то, как его выстраивать, давайте сначала разберёмся с тем, что произойдёт, если этого интерфейса не иметь. А, и тут начинаются проблемы, потому что агент без канона, а, работает не всегда плохо. Мы все прекрасно понимаем, что модели улучшаются, и написать конкретно нужную нам функцию агент сможет. Мы сейчас говорим не о силе самих кодинг-агентов, мы говорим именно о работе внутри какой-то инфраструктуры. А и вот если у агента нет какого-то чёткого канона, то он, как мы уже выяснили, начинает оптимизироваться под локальный контекст. То есть прочитал один файл, этот файл стал для него авторитетом. Увидел один пример в документации, этот пример стал правилом, которое будет применяться дальше. Если условно агент не видит ограничений, он выбирает свободу. И, соответственно, он предполагает, что то, что не запрещено, то разрешено. И отсюда вываливаются все типичные симптомы. И те, кто пробовал вайп-кодинг, думаю, должны увидеть а что-то знакомое. когда агент вдруг начинает менять не те модули, которые мы его попросили, а что-то очень похожее, но из совершенно другого края проекта, когда он вдруг начинает рефакторить архитектуру, которую вообще не надо было трогать или начинает игнорировать существующие паттерны в коде. То есть у нас всё написано так, а дальше он на это не обращает внимания, начинает писать сам. Он может начать создавать какие-то параллельные реализации, когда там один исполнительный код повторяется несколько раз или ещё хуже, когда одна функция у нас реализована и в одном, и в другом месте. А, и всё это ещё больше замусоривает кодовую базу. Ну и вся история с нарушением стиля, с нарушением внутреннего согласования, это всё отсюда. Это всё издержки слишком большой свободы. И самая большая проблема здесь - это даже не ошибка. Ошибки прекрасно исправляются. Самая дорогая проблема здесь - это, ну, собственно, и деньги и время. Потому что как только агент начинает исследовать репозитории чуть-чуть шире, он начинает, а, скажем так, он теряет уверенность, он начинает делать лишние шаги, он начинает проверять себя какими-нибудь дополнительными тестами и другими проверками. Ну а для нас каждый лишний шаг - это лишние 5 минут времени, лишнее несколько долларов токенов. Ну и самое главное - это неопределённость в самом процессе.

И вот к чему это всё приводит, точнее, из чего это всё вырастает, какой у всего этого есть единый корень. Это то, что в проекте нету приоритетного источника истины, нету учёт к прописанной явной иерархии, где у нас главные вещи, где второстепенные вещи, что у нас конкретно запрещено, ну и так далее. Соответственно, именно этим, э, источником истины мы и будем решать наши проблемы. Но сначала давайте формализуем, что это такое. Аа и здесь сразу же нужно убрать одно главное заблуждение. Несмотря на сам термин, что single source of аа единый источник истины, он на самом деле не один. А и логика, давайте сделаем один главный файл или возьмём agent MD и туда запишем всё, что только можно, она не работает, потому что на самом деле главное здесь - это иерархия. А причём иерархия, которая строится довольно специфически и на самом верху у неё то, что у нас называется enforcement. А в принципе, кстати, к документации никакого отношения не имеет, но просто сегодняшние технологии дают нам возможность управления проектами таким образом, что некоторые действия, особенно действия с кодом, становятся просто невозможны, потому что часть проверок выносится на уровень системы, на уровень кода, на уровень всего того, что мы называем continuous integration, C, а огромное количество различных решений, там, линтеров, фиксеров и так далее и тому подобное, которые в автомати ческом режиме проверяют, что код написан по правилам, длина строки соответствует рекомендуемому значению, а и тогда нужная кодировка, не используются там какие-то другие вещи. Ну, в общем, всё, что можно формализовать, оно, в принципе, на сегодня-то уже большей частью формализовано. Повторюсь, особенно если речь идёт о каком-то коде. А, и здесь для нас важный тезис звучит так, что если правило нельзя проверить автоматически, то истиной-то его особо считать нельзя. А здесь, правда, можете меня обвинить в слишком большом утрировании, потому что, ну, естественно, при различных форматах задачи не все правила можно проверить автоматически. Формальные там линтеры кода не применимы тогда, когда результатом нашей работы является там какой-нибудь контент. А, но а здесь есть две важные вещи. На самом деле формальная проверка возможна для любых данных, просто она будет не ээ алгоритмической. Мы можем включать проверки, можем даже делать эти проверки агентными, но всегда нужно чётко понимать, что в тот момент, когда мы взаимодействуем с кодом, код можно проверять формально. Всё, что выше, уже возникают вопросики по поводу того, насколько как бы эффективно эта оценка была проведена, и она будет требовать человеческого, а, контроля и так далее и тому подобное. Прелестью, как раз-таки кодового является то, что мы его не с ним вообще никак не взаимодействуем. И более того, здесь прелесть даже не в нас, опять же, а в агенте. А-а, кто смотрел наши прошлые записи про Agents MD, мы там как раз говорили, что использование вот таких средств en, оно очень сильно повышает качество, оно очень сильно повышает время, а, использования, оно очень сильно повышает расход токенов. А-э, потому что, ну, по сути, если агент не может как бы закоммитить, а, те данные, которые, э, формализованы, он будет делать это с э снова и снова и снова, до тех пор, пока результат не удовлетворит нашего, ну, на не будет удовлетворять нашим формальным критериям. Причём здесь даже кроется одна забавная вещь, что слабые модели, будучи поставлены в такие жёсткие условия, начинают работать чуть-чуть лучше. Именно из-за того, что по сути у них возникает огромное количество попыток, в рамках которых они могут таки исправить ошибку, протолкнуть свой результат через линтер и закрыть задачу. Но опять же здесь, прежде чем двинуться дальше, зафиксируем, что верхний уровень нашего источника истины кроется не в документации, он кроется в скриптах и ограничениях, которые формально проверяют тот код, который мы сделали. А-а, с формализацией разобрались. Двигаемся дальше.

Следующее - это, собственно, политика управления или, как ещё можно назвать, governanceнance для агентов. А, и это, собственно, те самые файлы Agents MDE или Clot MD. Будем их всё-таки разделять, потому что опыт показывает, что адаптация под кодекс и под клод сильно различается, они не взаимозаменяемы. Аа разные модели совершенно по-разному воспринимают одинаковые директивы, указанные в этих файлах. И в зависимости от того, какой платформой вы пользуетесь, а, формат написания этих директив должен различаться. Я уже, по-моему, неоднократно говорил, что если мы пользуемся моделями от Open AI, то они, скажем так, более покладистые, и для них возможно писать прямо жёсткие формальные критерии. Так делай, так не делай, и для агента эти слова станут максимой. То есть, если написали: "Не запускай там такое-то предложение такое-то приложение", то сколько в чате его не проси, он а-а с очень, ну, то есть он будет отказываться от того, чтобы его запустить, ссылаясь, собственно, на полисе, которое было указано. Перескочить через него всё-таки можно. То есть там как-то сильно включив админский режим взаимодействия, можно его как бы попросить, но это всегда будет из ряда вон выходящее событие. В случае с Клодом ситуация совсем другая. Для него важнее, а, ну, то есть там запреты в принципе не работают, он будет задавать вопросы. Поэтому сама сам формат этих директив должен быть более мягким, но более дискриптивным, с большим количеством описаний. объяснений, почему так нельзя делать. Но опять же для нас этот файл является аа не столько объяснением, то есть как раз-таки объяснений в нём не должно быть, ну должно быть по минимуму. А это ограничения и governnance. То есть, по сути, AgentMD должен содержать в себе две вещи: маленькую инструкцию по использованию, три вещи: маленькую инструкцию по использованию, список ограничений и ссылки на другие документы. Про это коснёмся, пока двинемся дальше.

Аа следующий этап - это архитектура, как у нас проект устроен, где у нас границы модулей, в каком формате мы эти модули пишем, какие инварианты у нас приняты при разработке, какие принятые решения были сделаны. Здесь тоже важная штука про трейсинг всего изменения, которые происходят с проектом, потому что он здесь тоже как бы движется по двум направлениям. Первый формат изменений - это то, что у нас, собственно, агенты реализовали на уровне кода. Второй вариант изменений - это то, что мы, как создатели реализовали на уровне архитектуры, на уровне задачи, на уровне всего того, что находится над кодом. А, и вот все наши, так как агенты сохраняют данные, и, в принципе, мы худобедно можем как бы отследить, какие изменения были проведены, такие же изменения, ну, такое же отслеживание должно быть и для человеческих изменений. Соответственно, если мы вдруг в какой-то момент приняли решение что-то поменять, это должно быть зафиксировано. Аа должна быть отдельная папочка, там, например, с названием ADR, Architectural Decision. А репорт и, собственно, решение, ну, где мы текстом пишем о том, каким образом архитектура проекта меняется, для того, чтобы и мы, и агент могли в нужный момент времени просто взять и отследить эту историю, в какой момент, как у нас менялась сама архитектура. А вот, ну и дальше у нас находится в самом нижнем слое, назовём это операционной документацией, а точнее нет, до до самого нижнего слоя у нас ещё есть операционная документация, которая ближе всего к тому, что мы воспринимаем за документацию сегодня. Это разнообразные гайды, как писать проект, какие фреймворки использовать, как откатывать, если мы что-то не так сделали, как дебажить этот проект, наконец, как выстроен деплой и тому подобное. То есть здесь всё должно быть в виде достаточно простых и понятных гайдлайнов, которые универсальны в этом плане, и они должны быть понятны и агенту, и человеку. И, наконец, самый нижний уровень - это уровень примеров. Потому что, ну, собственно, примеры делают важную вещь. Примеры уменьшают это самое пространство неоднозначности, где агент может, а, ошибиться. Ну и таким образом истинной для нас здесь в первую очередь является не просто набор документов, это порядок приоритетов, а, которые агент может воспроизводить во всей этой работе. А, и, соответственно, теперь мы можем чётко разделить два контура. контур, который у нас остаётся человеческим, и контур, который у нас формируется сейчас для агента. Аа и тут тоже очень важно, потому что зачастую эти роли смешиваются, и я здесь предлагаю просто разделить их, э, параллельно и выделить одну вещь. стандартный знакомый нам файл Redmi.md, который не имеет смысла дополнять агентскими инструкциями, ровно потому, что этот файл изначально настроен на человека. А и поэтому он может быть очень свободным. Он, по сути, как бы задача Редмишки - это ответить на вопрос, типа, что это за проект, зачем он существует, как его запустить, куда смотреть дальше, если что-то происходит. То есть это нарративный формат, мы именно рассказываем. В нём может содержаться какой-то дополнительный контекст, в нём может содержаться, не знаю, мотивация разработчиков, почему они этот проект сделали, и даже историю его появления. Всё то, что с точки зрения непосредственной разработки год кода является мусором, но с точки зрения продукта может являться очень-очень важной вещью. И вот агента туда имеет смысл вообще особо-то не пускать, потому что всё, что ему важно, должно быть определено в совсем других местах. А и это не только Agenc MD. А потому что здесь, во-первых, самая важная штука, что это вообще, ну, то есть между ними нельзя ни в коем случае проводить знак равенства. Это не объяснение для агентов. Ну, то есть если Redmi MD - это объяснение для людей, то Agent MD - это не объяснение для агентов. А, но при всём при этом это и не глобальный системный пром для агента. Как раз вот от этой концепции надо потихоньку отходить. А позже тоже расскажу, в чём причины. Agents MD - это, как мы уже выяснили, policy layer, набор политик, которые не, ещё раз, не должны объяснять проект, но зато должны очень чётко объяснять, а какие команды выполнять, для чего, где у нас описана, ну, например, каноническая архитектура, что точно запрещено менять, какие критерии выполнения будут для нас и для агентов означать, что задача выполнена. Ну и всё такое. Если там попробовать сказать коротко, то Redmi - это такое добро пожаловать для, ну, человеческим языком. А Agent MD - это набор правил и ограничений. А-а, да, собственно, там чуть позже я коснусь, там буквально несколько дней назад вышло уже прогремевшее там везде исследование по поводу того, что файлы Agent MD не работают. А сейчас мы через несколько слайдов до него дойдём, обязательно коснёмся. Заранее только скажу, что не всё так однозначно. А-а, вот пока что вынесем просто важную здесь штуку, что Ag MD, повторюсь, не большой файл, он не должен быть огромным. Это шлюз, по сути, точка входа, которая описывает, где эти правила, правильные источники истины у нас находятся. И самое главное, как до них добраться. Вот.

Ну и дальше давайте тогда закопаемся, как этот, а, полисиш шлюз должен, в принципе, выглядеть и из чего он должен состоять. Аа ещё раз фиксируя, мы сейчас пишем контракт поведения агентов. И касательно там каких-то глобальных правил, помимо того, что уже сказано, а-а, максимально всё просто, стараемся, ну, как бы удалять оттуда всю философию, аа удаляем вообще какие-то длинные описания, они не всегда эффективно работают. Аа файлы должны быть только то, что непосредственно влияет на исполнение. Аа, ну, и в первую очередь это цель. Причём, опять же, это не документация, это буквально одна-две строчки, которые описывают, что система делает, аа зачем она нужна и, собственно, куда куда дальше из неё э выходить. Вот. Мм, да, второй набор. Второй набор - это тулинг. Это описание тех инструментов, которыми мы пользуемся. Причём под инструментами а-а подразумевается именно инструментарий разработки, то есть конкретные команды, как мы запускаем тесты, как там проверяем типизацию, как форматируем код, как эти самые линтеры запускаются. Аа причём это, ну, как бы на максимально широком уровне должно быть написано, потому что если эти команды не указаны, агент может их найти, и он сможет догадаться, как ему использовать тот или иной инструмент, но в крайнем случае задаст наводящий вопрос. Но, скорее всего, если он особенно в автономном цикле находится, он сможет а это всё разгадать. Просто сделает это не за несколько секунд и ограниченное количество токенов, а сделает это в пять раз дольше и в три раза дороже. Следующий слой - это архитектурные рамки. Что можно менять, что нельзя и самое главное, где хранятся описания архитектуры, которые мы при приняли за канон. Аа четвёртая часть - это безопасность. А важная штука, её во многих, кстати, э файлах прямо игнорируют. А описание того, как мы работаем с секретами, что можно комметить, что нельзя. Не только в том, что указано в файлике Gitgnore, а именно полноценное описание контура безопасности, в том числе какие-то критические зоны, где агент может ошибиться легче, чем в каких-то других вещах. Пятое. А критерии качества или definition of done, то есть когда задача считается завершённой, какие проверки должны пройти, что должно в принципе как бы мы отметить для того, чтобы поставить галочку в самой задаче. Вот. А-а, и только последним разделом после всех вот этих, а, идут ссылки на каноническую документацию. То есть, ещё раз, agd не про истину, а про скорее указание того, где она находится. То есть это такой маршрутизатор. А и если он маршрутизатор, который всю логику переносит на документацию, возникает логичный вопрос: что же тогда делать с документами и какоя документация должна в этом эть? А, и ответ довольно простой, на самом деле. документация должна писаться ровно так, а как если бы её читала изначально сама модель. Потому что, ну, как бы, если мы first подход используем, то документация должна изначально писаться как промт для этого самого агента, но при этом тоже с оговоркой, не как одноразовый промт, а как именно системный промт, который мы указываем один раз и надолго. Что для нас это означает? Означает это для нас три важных пункта. Первый пункт - это структура. То есть информация изначально должна быть организована таким образом, чтобы приоритеты были очевидны из самой иерархии. То есть разные уровни заголовков, разные уровни наследования, разные уровни вложенности. Это всё помогает чётко определить, что для нас главное, а что второстепенное. Вторая, пожалуй, самая сложная вещь в написании - это отсутствие двусмысленности. Все формулировки должны писаться так, чтобы в идеале не оставлять какого-то дополнительного пространства для интерпретации. Опять же, звучит очевидно. Более того, звучит очевидно при работе не только с егентами, но и, например, с любым джуном. Но тем не менее это очень-очень важно. Ну и, наконец, ещё раз заострю на этом внимание. Это проверяемость, потому что, ну, идеальный вариант, если наши правила проверяются автоматически, потому что, ну, опять же, это не ограничение, это нужно держать в голове, потому что если правило формально не проверяется, рано или поздно оно будет проигнорировано. А и наша задача сделать так, чтобы мы просто этот момент не профукали и смогли определить и вернуть агента в нужное русло. А вот, да, и подытоживая, пожалуй, этот слайд, документация, если мы говорим про Agent First, она не должна вообще говорить типа у нас так принято. Вместо этого она, как мы уже говорили, должна уменьшать пространство неопределённости, но делать это через конкретное э ограничение поведения, конкретные там прописанные инварианты и тому подобное. А, но при всём при этом всё, что мы там учили последние 2 года, всё, что было связано с промдизайном и всеми подобными историями, оно никуда не умерло, потому что, а, ну, несмотря на то, что мы сейчас это называем красивым словом инженеринг контекста, по факту-то команды всё равно нужно писать и их нужно писать довольно чётко. И здесь тоже есть важные вещи. Застрим на них просто ещё раз внимание. Как ээ правила промтинга здесь приземляются на правила написания документации. Ну, во-первых, самая главная штука, что как бы вы не старались, агент никогда ваши намерения не прочитает, а вот инструкцию он прочитает очень хорошо и с настойчивостью мотивированного джуна будет исполнять её ровно так, как она и написана. Поэтому стараемся не писать всё, где много воды, потому что, например, фраза: "Следуйте стандартам проекта", которую мы могли бы кинуть какому-нибудь разработчику в надежде, что он просто сам доберётся до документации, сам её прочитает и сам аа эти стандарты выделит. Но для агента это не работает, а эта фраза не содержит действия. И поэтому как бы что её выполнять, как её выполнять? вероятность того, что она будет хоть как-то рассмотрена, сильно невелика. То же самое фраза "Поддерживайте качество кода", например, она не содержит в какой-то проверке. Мы не сможем как бы оценить, насколько это качество кода должно быть поддержано. Ну и то же самое, если мы напишем что-то типа там: "Используйте существующую архитектуру". А опять же мы поймём примерно, ну, мы сможем по анализу догадаться, что это за архитектура худо-бедно, но будет гораздо эффективнее, если у нас просто будет прямая ссылка на то, где она описана. Соответственно, как у нас трансформируются правила хороших промтов? Мы не пишем абстрактные вещи, мы пишем максимально конкретные вещи, что, например, тесты, которые лежат в этой папке, должны быть зелёные. Аа после завершения задачи всегда запускай линт такой-то командой. Если добавляешь новые поинты, добавляй их конкретно в эту папку. Да, кажется, что это может быть немножко избыточно, и мы здесь делаем двойную работу. Нет, на самом деле мы здесь делаем ровно ту работу, которую и нужно сделать, потому что код для нас здесь аа становится как это производной от этой самой документации. А, и в дальнейшем это нам очень сильно позволит избежать головной боли. То есть задача здесь для нас в то, чтобы как бы эти описания могли чётко превращаться в действие. А чтобы это было с минимальным количеством ошибок, мы должны обрезать вот это самое пространство для возможных интерпретаций. А и это то, почему это ещё важно? Потому что агент будет оптимизировать свои действия под то, что он фактически может выполнить. Если в документации нету вот этих исполнимых указаний, то агент просто придумает эту процедуру сам, а, и дальше будет ейследовать. И проблема здесь только в том, что мы не узнаем о том, что это за процедура, и сможем о ней только догадываться по конечным артефактам. А, и опять же, чем больше степеней свободы, тем неважно, сколько ошибок. Ошибки исправляются и отслеживаются. Чем больше свобода и тем выше стоимость и тем ниже стабильность. А вот и здесь ещё один важный вывод о том, что пожелания обычно игнорируются, а вот ограничения всегда исполняются очень строго. LЛM вообще очень плохо реагирует на мягкие формулировки. Если написать хотелось бы придерживаться, желательно исполнить, рекомендуется выполнить, а по возможности избегайте. Вот опять же стопудов кто-то сейчас поймает себя на воспоминания о том, что так использовалась

Такая терминология в промтах. Так нельзя делать. Это язык, чётко для людей, а для агента — это в лучшем случае излишний шум, а в худшем случае — возможность прийти к выбору того действия, о котором мы вообще ещё даже не догадываемся. Поэтому не стесняйтесь писать жёсткие инструкции. И опять же, здесь с оговоркой: если мы, э-э, работаем с моделями Open AI, то не стесняйтесь прямо по жести писать. Вот прямо выделите себе must, must not, only, don't modify, то есть прямо жёсткие конструкции, которые вы будете использовать по всему документу. И типа, если агент должен что-то сделать, значит, прямо так и пишем большими латинскими буквами: MUST, что независимо от языка документации.

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

Ну, то есть, например, нельзя добавлять новую зависимость в код между в, тьфу, без добавления нового документа в папку ADR, то есть не приняв человеческое решение по изменению архитектуры, мы не можем как бы эту архитектуру использовать. А почему это проверяемая штука? Ну, потому что как бы любой любая папка для нас — это Git-репозиторий. Git-репозиторий работает через пулреквесты. Соответственно, для того, чтобы там что-то внести, мы можем это зафиксировать и проверить, что как бы эта зависимость действительно добавляется с этим самым ADR-файлом, потому что мы это увидим в пулреквесте. Соответственно, это проверяется.

Дальше ограничение: например, не менять ядро проекта без обновления тестов. Опять же, это проверяемая история. Тесты — это отдельные утилиты, которые позволяют оценить покрытие кода и в случае чего просто формализованную цифру вытащить о том, что типа тесты на 70% так не подходят, повышает до 80, а и дальше уже с разъяснением, как конкретно эти тесты писать. Вот. То есть, ещё раз, ограничения должны быть проверяемыми, потому что, ну, может показаться, что это лишняя бюрократия, и на самом деле мы здесь всё усложняем. Нет, это как раз возможность сделать поведение наших агентов гораздо более, э, стабильным.

И, наконец, здесь ещё есть один важный принцип, который тоже очень сильно всю эту неоднозначность снижает. А и этот принцип — это примеры. На то, что мы говорили, у нас в самом конце находится нашей документации. Это, на самом деле, очень-очень важная штука, потому что она позволяет, а, агенту опять же более эффективно понимать, что мы от него хотим. Потому что, опять же, если мы напишем в промте: "Тесты должны быть полными и аккуратными", ну, прекрасно, абсолютно абстрактная штука. А если мы напишем кусочек кода, дадим какой-нибудь там один эталонный юнит-тест и напишем, что вот тебе шаблон поведения, как всё должно быть, это уже будет лучше. То же самое, если мы описываем там, как должен выглядеть правильный пулреквест, это наше пожелание, на него можно в случае чего положить. А если мы как бы покажем шаблон документа, в котором уже заложена правильная структура, в котором прописано там сообщение, с которым его нужно отправлять и тому подобное, это уже будет примером структуры, это будет паттерном, который можно реиспользовать.

И самое главное, что здесь всё это работает ровно, ещё раз, потому что мы снижаем потенциальное вот это пространство для ошибок. А важная вещь: примеры не должны быть просто случайными примерами из головы. Это не должен быть абы какой юнит-тест. Мы должны вот это, к сожалению, работа, которая пока ещё у людей не будет отринута, потому что здесь мы должны предоставить примеры, которые будут эталонными. Мы вот сейчас должны придумать канон того, как у нас будут реализованы какие-то вещи. И на самом деле, чем больше мы этих вещей здесь придумаем, тем лучше и эффективнее будет конечная работа. А-а, но тут тоже опять же есть один риск, э, который звучит как замусоривание контекста, потому что чем больше документации, несмотря на то, что даже если это хорошая документация, тем больше контекста. А чем больше контекста, тем, на самом деле, далеко не всегда лучше.

А, собственно, ещё одно исследование, на которое тоже очень рекомендую ознакомиться. Ссылочка будет и в описании, в материалах, которые можно будет забрать в боте. А, но я его пока просто кратко перескажу. А там группа исследователей взяла и сравнила три режима работы кодинг-агентов: а, без файла `agents.md`, когда, ну, просто транслировалось, что нужно сделать через обычный чат с контекстом, который был специально образом написан специально обученным человеком, а, и с файлом `agents.md`, который сгенерировала LLM. И вот, казалось бы, а всё должно быть достаточно очевидно, но результат оказался не очень очевидным. Ну, во-первых, оказалось то, что, э, контекстные файлы, которые сгенерировал LLM, в целом, в среднем, точнее, снижали процент успешного решения. А, но при этом использование файла `agents.md` практически всегда приводит к примерно двадцатипроцентному увеличению потребления токенов и времени работы. Хотя, казалось бы, аа, то есть удивительным образом без файла `agents.md` агенты работают, ну, очевидно, с меньшим количеством шагов, с более дешёвым исполнением, но и более качественно, чем если использовать абы какой контекст от LLM.

Всё немножко менялось, если `agents.md` писал человек. В этом случае success rate иногда даже повышался. Но если что, чтобы вы понимали размерность, сгенерированный LLM файл приводил к снижению примерно на 4% теста. Человеческий контекст на эти же тесты там 3-4% эффективность увеличивал, что опять же может показаться не очень много, но на самом деле это весьма показательная вещь, особенно когда мы говорим про то, что с помощью агентов в принципе скорость разработки очень сильно растёт. Вот.

А с чем вообще это может быть связано? Ну, в первую очередь с тем, что, как мы уже говорили раньше, агент начинает следовать этим инструкциям буквально: больше проверок, больше файлов для исследования, больше тестов для запуска, пространство требований начинает расходиться, расходиться, расходиться. И если эти требования избыточные, то агент тратит бюджет, время, когнитивную мощность. И в результате это приводит к тому, что конечное качество начинает снижаться. Но тем не менее вывод здесь далеко не в том, что файл `agents.md` не нужен. Наоборот, нужен, просто немножко в другом контексте. А точнее, контекст, содержащийся внутри самого файла, должен быть вот минимально достаточным. То есть это не В чём ещё большое различие от `README.md`? В том, что это не обзор репозитория. Это место для самых-самых критичных правил. И чем короче и точнее у нас будут наши политики описаны, тем выше будет предсказуемость работы нашего агента. И как результат, тем ниже стоимость.

Ну и давайте теперь закрепим это всё. Э, как же, собственно, должна выглядеть "agent first" документация? А, и ответ будет достаточно простой: она должна быть слоистой. А, и мы, причём видим развитие той схемы, о которой говорили в начале. А просто повторим её и углубим, так сказать.

Самый верхний уровень — enforcement, принудительные проверки. А, повторюсь, если правило нельзя проверить через там CI или linter или там какой-нибудь тест, ну, громко говорить о том, что это не является правилом, я не буду, но это будет тем правилом, через которое можно в случае чего перешагнуть. Поэтому стараемся здесь не обязательно загоняем всё под формальную верификацию, но там, где это возможно, это сильно облегчит работу.

Следующее — policy gateway, о котором мы говорили, `agents.md`, `cloud.md`, который должен быть максимально коротким, который не должен ни в коем случае дублировать или вообще описывать архитектуру проекта. Вместо этого он должен указывать на неё, направлять к ней, а, и в принципе содержать в себе все ссылки на важные документы. Причём, опять же, мы говорили чуть выше про иерархию, что документация — это тоже, это не плоское количество файлов, это тоже вложенные документы. И вот здесь тоже важно: индекс `agents.md` — это именно индекс, это оглавление. Оно не должно содержать в себе ссылки на все абсолютно документы. Здесь должна быть иерархия. То есть мы указываем здесь верхнеуровневые разделы. Дальше из этих верхнеуровневых разделов там содержится оглавление на более низкого уровня разделы. Ну и так далее. А, то есть это такое дерево должно быть.

Дальше под этим файлом как раз непосредственно документация. Причём документация, разделённая на две большие части. Аа, первая часть — это архитектурная документация. Как мы всё это строим? Где границы модулей, какие решения по изменению мы принимаем. То есть более такая верхнеуровневая история. Под ней находится операционная документация, где мы описываем гайдами, что делать, как деплоить, как реагировать на инциденты, как там выполнять какие-то известные сценарии и тому подобное. Всё то, что мы бы написали там для онбординга новому сотруднику, а, если бы у него не было возможности разбираться в коде.

И в основе всего этого дела, под практически каждый из этих сценариев, если возможно, пишем референсные примеры. Опять же, не в формате "как можно", а в формате эталона: "как нужно это сделать". А ровно по той причине, что эти примеры по сути стабилизируют поведение вот этой всей логики, которую мы до этого выстроили. И ещё раз подчеркну эту историю, что файлик `agents.md` для агентов у нас перестаёт быть центром системы, перестаёт быть крупным файлом, превращаясь в указатель с минимальной инструкцией. И здесь для себя можно такой чек-лист сделать, что если открываем `agents.md`, он у нас там типа около 500 строк, то всё, это не шлюз документации, это такой же архитектурный шум, который будет сильно мешать нам работать. Вот.

Ну и что ещё важно для документации? А-а, ну, во-первых, разобраться с тем, как это должно практически реализовываться, потому что хорошо рассуждать о том, как оно должно быть, но гораздо сложнее пытаться это всё интегрировать. Собственно, давайте про практику тоже чуть-чуть поговорим. А-а, самая большая, наверное, ошибка здесь — это написать документацию один раз и считать, что всё готово. Как вот раньше было, там типа white paper написали и больше мы его никак не трогаем, он остаётся, а, единственным за зафиксированным источником. Но в "agent first" мире документация превращается тоже в живой механизм. А, причём работающий примерно следующим образом: если агент у нас совершает какую-то повторяющуюся ошибку, мы не пытаемся написать какое-нибудь длинное объяснение того, из-за чего это произошло. Мы наоборот, мы формулируем максимально короткое правило, как сделать так, чтобы этого не было. И в идеале добавляем тот самый пример, который показывает: "А как лучше? А как надо? А как сделать так, чтобы так больше не происходило?" И, наконец, третья вещь — это, если опять же это возможно, если это кодовая история, мы добавляем проверку в наш интеграционный контур. И всё. После этого любая ошибка, которая вот таким образом может быть формализована, она перестаёт быть просто ошибкой. Она становится техническим огрехом, который элементарным образом не просто исправляется, но и фиксируется в памяти так, чтобы больше такого не происходило.

И это очень важный, на самом деле, переход, если задуматься, потому что изначально, как бы, мы воспринимали документацию как описание культуры кода, а теперь вместо этого она становится динамическим инструментом для стабилизации поведения агентов. То есть, подытоживая, каждое повторяющееся отклонение, оно должно превращаться вот в три вещи: короткое правило, пример и проверку. Если этого нету, то наша документация неизбежно начнёт устаревать или, например, даже отходить от того кода, который она описывает. Но если вот это принято за правило, то документация становится такой самоподдерживающейся системой, которая, особенно будучи замкнутой на непосредственно кодовую базу, будет жить вместе с ней, а постоянно являться как бы единственным источником правды и чётко отражать то, что у нас происходит в коде. Самое главное, при всём при этом она особо-то и не потеряет человекочитаемость. Просто "agent first" подход сделает её более эффективной.

Ну и, а, давайте уже под конец маленький короткий чек-лист. То есть, если у вас есть там свой репозиторий с проектами, посмотрите на эти 10 пунктов. Если на каждый из них можете ответить "да", значит у вас, а, проект можно считать "agent ready" и можно задумываться о том, чтобы переставать писать код руками. Ну и, собственно, вопросы-то максимально простые и по сути подытоживают всё то, о чём мы говорили.

То есть, есть ли явная иерархия между источниками истины? Там вот здесь у нас главный источник, дальше это у нас, а, уже строится иерархия. Нет ли в `README` каких-то дополнительных ограничений и политик, которых там быть не должно? Потому что, ещё раз напомню, `README` для агентов вообще не должен писаться. Достаточно ли короткий у нас `agents.md` или вдруг он разросся до простыни и его надо самого рефакторить? Есть ли у нас какие-то фиксированные команды для тестов, для там линтеров и тому подобное? А дальше, если у нас чётко записанные критерии разрешения, неразрешения и тому подобное. А если нет, это значит надо сделать. Понимает ли в принципе у нас агент, когда задача завершена? Есть ли у нас описание этих критериев приёмки? А и чётко ли мы понимаем, что у нас происходит? Причём понимаем на всех уровнях, потому что архитектурные границы у нас тоже должны быть задокументированы и чётко должна быть понимание того, где мы что строим и где самая главная граница, за которой мы не должны выходить. А и выяснить это мы можем по тем самым эталонным примерам того, как и должно быть сделано. Дальше, есть ли вообще у вас интеграционный контур и есть ли в нём правила, которые как раз делают вот этот enforcement живым и дают ли возможность эти правила зафиксировать? Ну и самый, пожалуй, главный вопрос — это является ли документация мёртвым файлом или она реактивно обновляется после того, как агент совершил какую-то ошибку.

Если ответили "нет" хотя бы на один из пунктов, это не означает, что ваша документация плохая. Это означает то, что вы продолжаете писать её для людей. А вот если вы собрали 10 "окей" здесь, то можете смело называть себя не просто разработчиком, а проектировщиком когнитивной среды для агентов, потому что именно это, пожалуй, и является на сегодня самой важной историей. А и что здесь ещё важно? А, судя по тому, как развивается индустрия, вот этот смена парадигмы на вот осознание того, что те артефакты, которые мы видим в компьютере, уже не только код, а вообще практически всё, что угодно, с ними в первую очередь будут взаимодействовать и агенты, и уж только во вторую очередь будем взаимодействовать мы с вами. Это очень важная вещь, которую нужно переключить в голове. Если вам это удаётся, то дальше а те потрясения, которые нас всех ждут, будут проходить гораздо более приятно. Вот.

Ну и в завершении, повторюсь, у нас маленькая обновка: дополнительные материалы, о которых я говорил в течение там сегодняшней встречи, собственно, презентация, которую вы видите, примеры файлов `agents.md` и маленький такой, а, маленькая выжимка самых ценных вещей, которые сегодня прозвучали. Вы можете их совершенно спокойно, совершенно бесплатно загрузить через Telegram-бота. Ссылочку видите на экране, можно просто перейти, ткнуться, зарегистрироваться. Дальше этот бот будет, а, позволять более легко регистрироваться на события. Это будет такой маленький бот-афиша, и он же будет в дальнейшем распространять вот, а, разные полезняшки, которые есть. Поэтому заходите, подписывайтесь. Спамить он у вас не будет, будет только полезностями делиться. Вот. А, ну на этом у меня всё. Если есть вопросы, я буду очень рад на них ответить. А если вопросов нету, я только что осознал, что в начале всех поздравил с пятницей, но сегодня четверг, поэтому завтра ещё один рабочий день, поэтому не будем расслабляться. Вот. Так что, если а вопросы есть, welcome. Если вопросов нету, то всем хорошего вечера.

И >> Слушайте, вопрос один есть. Здравствуйте, меня зовут Максим. Я в написании кода и вообще работе с моделями — новичок. Хотел бы уточнить: вот всё, что касается документирования, документации, единой точки истины — можно ли это всё создавать с помощью моделей или надо писать, нужно писать руками? То есть вот какой подход наиболее правильный или доступный, возможный?

Есть хорошая фраза, причём, которую меня ещё научили на курсе по типографике, которая звучит как: то, что правила, любые правила можно нарушать, но эти правила нужно сначала знать. Мне кажется, здесь она тоже очень хорошо подходит, потому что, да, ответ на вопрос: можно генерить это всё и моделями. А, но в чём здесь важная штука? В чём была разница между исследованием, э, в котором файлы писались человеком или нечеловеком? Именно тем, что если мы это отдаём полностью на откуп модели, то без дополнительного контроля, то туда попадает очень много ненужного мусора. Поэтому человекочитаемый, ну, человеческий файл подразумевает то, что его человек, ну, как минимум вычитал и выкинул оттуда всё ненужное. Поэтому генерировать, да, конечно, можно. А, но просто нужно понимать, что после этой генерации файлик нужно будет открыть руками, пройтись по нему и как бы чётко осознавать, какие именно директивы в него пошли. А чётко убедиться самому, что в файле там есть только ограничения, причём в строго необходимом количестве. Ну и всё такое. То есть вот здесь вот этот объём ручной работы, он, к сожалению, никуда сейчас не уйдёт. А более того, он становится гораздо более ценным, потому что проверять всё равно нужно. Но да, немножко спасает то, что не нужно всё писать на 100%. Но вот проверка самих документов здесь становится гораздо более важной. Вот. Надеюсь, ответил.

>> Понял. Спасибо огромное. Сначала научись играть по правилам, потом придумывай свои.

>> Точно.

>> Да.

>> Спасибо.

>> А-а, о, классный вопрос. А, спасибо. Очень интересно. Какая часть из обязательного документирования описана правилами в Agent Plane? Agent Plane, если что, это маленький фреймворк, который мы разработали для того, чтобы более эффективно взаимодействовать с агентами. Можно ли ожидать, что там появится опция, где агент помогает оформить документацию и обвязку, задавая правильные вопросы?

Отвечу по двум вещам. На текущий момент — нет. Больше того, вся работа с документацией на данный момент времени, она как раз переложена на плечи самого разработчика. Но а ожидать о том, что в будущем появится такой функционал, не только можно, но и нужно, он есть в планах. Он добавится через одну версию после того, как будут реализованы история с рецептами. Поэтому, да, можно будет и декомпозицию делать, и документацию писать. И в общем, логика как раз в том, чтобы в будущем, а, оптимизировать максимальное количество головной боли, ээ, оставив разработчику только вот как раз инжеринг когнитивного пространства, скажем так. Поэтому, да, будет. А, о релизах объявлю дополнительно. Вот. А большое спасибо.

Ну что, если вопросов нету, то могу лишь распрощаться. Надеюсь, это было полезно. Забирайте, а, дополнительные материалы и до встречи на следующей неделе.

>> Денис, спасибо огромное за семинар, за встречу. На самом деле очень полезный материал.

>> Благодарю вам тоже. Хорошего окончания недели. До свидания.

>> Супер. Спасибо и всем пока-пока.