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

Четыреста килобайт на полу выглядят как пачка, которую нельзя прочитать за один раз и неудобно унести в руках. Рядом лежит стопка потоньше, девятнадцать листов под скрепкой. Это правила, которые из инструкции убрали вчера. Я их не выбросила.

Чай стоит на подоконнике, потому что на полу ему места нет.

Сорок тысяч слов перед каждой задачей

Двадцать седьмого октября в main влили правку «ядро AGENTS.md и 30 справочников зон вместо CLAUDE.md» — 11 568 добавленных строк против 1 215 удалённых, номер PR в репозитории 2141.

Что было: один файл инструкции на 36 240 слов и 402 килобайта, который агент читал в начале любой задачи — в том числе задачи, где нужно поправить одну кнопку в биллинге. Что стало: ядро в 105 строк и около 17,7 килобайта, один вход для всех агентов, плюс тридцать справочников по зонам продукта. Агент, которому достался каталог биллинга, читает на старте 23 822 байта вместо 402 442 — в семнадцать раз меньше. Для каталога холста — 24 318.

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

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

Инфографика: до правки агент читал 402 442 байта при старте любой задачи, после — 23 822 байта в каталоге биллинга и 24 318 в каталоге холста
Цена чтения на старте одной задачи, байты. Замер сделан авторами изменения в описании PR 2141; я его не пересчитывала.

Девятнадцать правил, которых больше нет

В разборе прошли все 169 разделов и аварийных блоков старой инструкции. Сто пятьдесят ушли в справочники, а девятнадцать оказались в отдельной папке с пометкой «правила-компенсации для ранних агентов»: волны работы, шаблон задачи, «три попытки — стоп», ограничение контекста. У каждого в новой папке написана причина, по которой оно больше не нужно, и адрес, куда уехали полезные факты из него.

Раньше я думала про такой файл как про память. Теперь думаю как про склад заплаток. Каждая когда-то закрывала настоящую дыру: агент уходил в сторону, агент бросал задачу на третьей попытке, агент тонул в контексте. Через полгода агенты другие, а заплатки остались — и новые читают их как закон, а не как историю болезни.

Девятнадцать листов под скрепкой. Понимаю, почему их не выбросили: внутри каждой заплатки был полезный факт — какой-то адрес, какое-то имя файла. Выбросить целиком означало потерять, оставить как есть — зацементировать. Поэтому у них теперь есть причина и адрес.

За порядком следит код

Главное в этой правке не объём, а то, что за порядком больше не следит дисциплина. Есть генератор, который собирает выжимки в 95 вложенных файлов инструкции по каталогам и в 30 правил по путям. И есть проверка, которая стоит в претесте: расхождение между тем, что генерирует скрипт, и тем, что лежит в репозитории, валит прогон до тестов.

Проверка отказывает по списку: справочник не по шаблону, идентификатор зоны встречается дважды или не забран никуда, ядро длиннее 200 строк или 24 килобайт, блок «Обязательно» длиннее пятнадцати строк, зона числится и в покрытых, и в отброшенных. Это ровно те ограничения, которые человек соблюдает, пока помнит, и нарушает на третий месяц.

Сверка при переносе была отдельной работой: из 2 394 значений в обратных кавычках старого файла 99 не нашлись в новых справочниках — все вернули. Номера всех 59 упомянутых миграций сохранились. Это отчёт авторов изменения; такой сверки я сама не делала.

Бот, который сливал документацию сам

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

После этого решения бот слил девятнадцать PR и закрыл тринадцать, у закрытых удалив ветки. Четыре из слитых были не от док-ботов: их открывали сессии агентов, и единственным признаком ночного было слово docs в названии ветки. Среди них — спека тестового прода. Черновик не защищает: перед слиянием механизм сам снимает с PR статус черновика.

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

Двадцать седьмого его выключили руками. Открытый PR 2144 удаляет механизм целиком — workflow, ядро и тест: шестьдесят добавленных строк против 1 101 удалённой. В диффе только удаление и правка карты зон.

Две правки одного вечера, и обе про одно. То, что забыли выключить, работает дольше и громче того, что включили осознанно. Инструкция на четыреста килобайт выросла не потому, что кто-то писал лишнее, а потому, что её никто не разбирал. Бот сливал документацию не потому, что так хотели, а потому, что решение жило в плане, а не в репозитории.

Третье, что я записываю себе: у всего этого есть цена чтения, и её платит тот, кто ещё ничего не сделал. Девятнадцать заплаток, тридцать справочников, ядро в сто пять строк — это не про объём знания, а про то, в какую секунду оно приходит агенту.

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