Зачем файл правил
В прошлом уроке был совет: писать поручение из трёх-пяти предложений, а всё лишнее выносить. Выносить — куда? В файл правил репозитория. Это обычный текстовый файл, который лежит в проекте и который агент читает сам, без напоминаний.
Общепринятое имя у него одно — AGENTS.md, и это не изобретение одного инструмента: тот же файл читают и другие агенты, включая редакторы и облачных помощников. Формат — обычная разметка, как у описания проекта. Никакой схемы, никаких обязательных полей.
Зачем он нужен, видно из простого наблюдения. Возьмите три своих последних поручения агенту и посмотрите, что в них повторяется. Почти наверняка найдётся что-нибудь вроде: «тесты запускай такой-то командой», «в этом проекте не используем такую-то библиотеку», «код на русском не комментируем», «перед готовностью прогони линтер».
Это и есть правила. Они не относятся к конкретной задаче и не меняются от неё к задаче. Повторять их каждый раз — значит каждый раз тратить и ваше внимание, и место в окне контекста, и рано или поздно один раз забыть.
Второе, что делает файл правил: он переносит знание из голов в проект. Пока договорённость «мы не трогаем формат выгрузки» живёт только в памяти команды, она действует ровно на тех, кто был на том совещании. Записанная в файл, она действует и на агента, и на нового человека, и на вас самих через полгода.
Третье, менее очевидное: файл правил едет вместе с репозиторием. Задача, запущенная в облаке, читает тот же файл, что и агент на вашей машине, потому что в контейнер забирается копия репозитория целиком. Никакой отдельной настройки для облака заводить не нужно — и это как раз тот случай, когда одно место лучше двух.
Есть и четвёртая причина, которую замечают позже прочих. Файл правил дисциплинирует команду. Пока договорённости живут в разговорах, они бывают взаимоисключающими и никто этого не замечает: каждый помнит свою половину. Попытка записать их в тридцать строк почти всегда вскрывает пару мест, где люди думали по-разному, — и это полезнее, чем сам файл.
Завести файл проще всего не с чистого листа. У агента есть команда, которая осматривает проект и пишет черновик: смотрит, чем проект собирается, какие есть тесты, какой стиль преобладает.
/initЧерновик получается неплохой, но неполный по определению: агент видит только то, что записано в коде. Договорённости, которых в коде нет, — «не обновляй библиотеки без обсуждения», «этот модуль переписывается, туда не лезь» — придётся дописать вам. Эти-то строки и приносят большую часть пользы.
Что туда пишут
Что конкретно писать. Разберём по разделам — не потому, что схема обязательна, а потому, что так проще ничего не забыть.
Как запустить и собрать. Самое полезное и самое пропускаемое. Какой командой ставятся зависимости, какой запускается проект, какой прогоняются тесты, какой проверяется стиль. Без этого агент угадывает — и угадывает по внешним признакам, которые не всегда верны.
## Команды
Установка: npm ci
Запуск: npm run dev
Тесты: npm test
Стиль: npm run lintКак устроен проект. Две-три строки о том, что где лежит: где серверная часть, где страницы, где тесты, где то, что трогать не надо. Не карта на страницу — ориентиры.
Соглашения. Всё, что в коде выражено неявно и что агент может нарушить, не заметив. Как называются файлы. Как оформляются ошибки. Пишем ли комментарии и на каком языке. Какие библиотеки приняты, а какие вытесняются.
Запреты. Самая ценная часть и самая короткая. «Не обновляй версии зависимостей.» «Не меняй структуру базы.» «Не трогай папку с выгрузками — её формат согласован снаружи.» «Не создавай новых зависимостей без причины в сообщении.»
Как проверяется готовность. Что должно проходить перед тем, как задача считается сделанной. Эта строка работает лучше, чем можно подумать: она превращает «я закончил» из мнения в проверку.
Полезно понимать и порядок, в котором эти разделы читаются. Агент читает файл целиком и целиком держит его в виду, но вес у разделов разный: конкретная команда работает надёжнее общего пожелания, а запрет — надёжнее предпочтения. Поэтому то, что действительно важно, формулируют как команду или как запрет, а не как описание желаемого.
Пример разницы. «Стараемся не плодить зависимости» — это описание намерения, и агент честно учтёт его как одно из соображений. «Новые зависимости не добавляем; если считаешь, что без неё никак, — скажи и не добавляй» — это запрет с понятным исходом, и он работает.
И одно правило формы: пишите коротко. Файл правил на три экрана перестаёт работать — не потому, что агент его не прочитает, а потому, что вы перестанете его поддерживать. Устаревшее правило хуже отсутствующего: оно уверенно ведёт не туда.
Практический ориентир — от тридцати до восьмидесяти строк. Если получается больше, значит, в файл поехало то, чему место в описании проекта: рассуждения, история решений, объяснения «почему мы так делаем». Правилу объяснение нужно ровно тогда, когда без него правило выглядит произволом, — и тогда это одна фраза, а не абзац.
Чего туда не пишут
Теперь о том, чего в файл правил класть не стоит. Этот список короче, но ошибки здесь дороже: лишнее в правилах не просто бесполезно, оно мешает.
Не кладите туда конкретные задачи. «Поправить расчёт скидки» — это поручение, а не правило. Записанное в файл, оно будет читаться агентом при каждой задаче, пока кто-нибудь не вспомнит его убрать.
Не кладите туда историю и обоснования. «Мы выбрали эту библиотеку в прошлом году, потому что альтернатива не поддерживала нужный формат, а переходить сейчас дорого» — прекрасный абзац для описания проекта и лишний для правил. В правилах от него остаётся одна строка: «библиотека такая-то, на другую не переводим».
Не кладите туда секреты. Ни ключей, ни паролей, ни адресов внутренних систем с доступом. Файл правил лежит в репозитории, а репозиторий рано или поздно оказывается там, где вы его не ждали. Про это отдельный урок, но правило стоит запомнить сразу.
Не кладите туда правила, которые вы не соблюдаете. Это самая тонкая ошибка. Если в файле написано «каждая функция сопровождается тестом», а в проекте тестов на четверть кода, агент окажется в противоречии: правило говорит одно, а код — другое. Разрешит он его непредсказуемо, и обычно в пользу того, что видит.
Иначе говоря, файл правил описывает то, что есть или к чему вы действительно ведёте, а не то, как было бы хорошо. Мечты в этот файл не пишут: они превращают его в текст, которому нельзя верить, — а весь смысл файла в том, чтобы ему верили без проверки.
И последнее из частого: не пишите туда того, что зависит от машины. «Запускать из папки, где стоит такая-то программа», «использовать порт 3000» — это про вашу настройку, а не про проект. Такие вещи ломают работу в облаке первыми, потому что там ни вашей папки, ни вашего порта нет.
И ещё одна ошибка, которую стоит назвать отдельно, потому что она выглядит как забота: не пишите в правила того, что уже проверяется автоматически. Если у вас настроен линтер, правило «соблюдай стиль» лишнее — стиль проверит линтер, и проверит точнее любой формулировки. Вместо него полезнее строка о том, какой командой этот линтер запускается: она превращает проверку из вашей обязанности в его.
Полезная привычка при правке файла: прежде чем добавить строку, спросите себя, что изменится, если её не будет. Если ответ «ничего» или «агент и так так делает», строку писать не надо. Файл правил ценен ровно теми строками, без которых что-то пошло бы иначе.
Вложенные правила и приоритет
Две вещи, которые надо знать про то, как правила уживаются друг с другом и с вашим поручением.
Первая: правил может быть несколько. В большом проекте, где под одной крышей живут серверная часть, интерфейс и, скажем, мобильное приложение, у каждой части свои команды и свои соглашения. Тогда рядом с каждой кладут свой файл правил, а в корне оставляют общее.
Работает это по принципу близости: действует тот файл, который ближе к правимому месту, а корневой при этом не отменяется — он остаётся общим фоном. Практически это значит, что в корень идёт то, что верно для всего проекта, а в подпапки — только отличия.
Вторая: ваше поручение сильнее файла. Если в правилах написано «не обновляй зависимости», а вы в задаче прямо говорите «обнови такую-то до последней версии, у неё поправили ошибку», — агент сделает то, что сказали вы. И это правильно: правила описывают обычный порядок, а вы принимаете решение по конкретному случаю.
Третья вещь, менее очевидная: правила стоит проверять на живых задачах. Написанный файл выглядит разумно всегда — а работает он или нет, видно только по тому, изменилось ли поведение агента.
Проверка простая. Возьмите задачу, на которой раньше приходилось что-то дописывать руками, и дайте её без этих дописок. Если агент сделал правильно — правило работает. Если нет — правило либо сформулировано как пожелание, либо противоречит тому, что он видит в коде.
И привычка, которая держит файл живым: дописывайте его по итогам неудач. Каждый раз, когда агент сделал не то и вы поняли почему, спросите себя, разовая это причина или повторяющаяся. Если повторяющаяся — это новая строка в правилах, и написать её стоит сразу, пока помните формулировку.
Две строки, дописанные после двух разборов. Каждая закрывает целый класс будущих неприятностей.
Сколько строк добавлять за раз — вопрос не праздный. Дописав пять правил разом после одного тяжёлого разбора, вы, скорее всего, добавите четыре лишних: в момент раздражения всё кажется важным. Полезнее одна строка, но точная, — та, без которой сегодняшняя неприятность не случилась бы.
И последнее наблюдение, которое стоит целой главы. Хороший файл правил читается как список того, обо что уже споткнулись. Плохой — как список того, что кажется правильным. Отличить их легко: возьмите любую строку и спросите, был ли случай, когда её отсутствие стоило времени. Строки без такого случая — это ваши предположения о будущем, и сбываются они примерно как любые предположения о будущем.
Так файл правил из разовой настройки превращается в накопленный опыт проекта — и это, пожалуй, его главная ценность. Через полгода он содержит всё, обо что вы спотыкались, и новый человек в команде получает это знание сразу, без года работы.