В корне блога лежат два файла контекста и один каталог. Двадцать семь строк, триста двенадцать строк и пакет из шестнадцати скиллов с двенадцатью агентами.
Пришёл я к этому не сразу. Промежуточная стадия была хуже, чем один большой файл: три файла с пересекающимся содержимым, которое разъезжалось со скоростью примерно одна ложь в месяц.
Кто что читает
Начну с неприятного: единого стандарта нет. Разные инструменты ищут контекст в разных местах, и с этим приходится жить.
CLAUDE.md короткий указатель, читается автоматически
AGENTS.md подробное руководство, читается по ссылке или по запросу
.ai/skills/ процедуры, подключаются по описанию
.ai/agents/ исполнители, выбираются по описанию
.claude/ часть скиллов и агентов, проброшенных симлинкамиРаскладка выглядит избыточной, пока не поймёшь принцип: один источник содержимого, несколько точек входа. Файлы не дублируют друг друга, они по-разному подробны.
Указатель и руководство
CLAUDE.md у меня двадцать семь строк. В нём стек, три команды и пять правил. Всё.
## Контекст
Laravel 13 + Filament 5 технический блог. PostgreSQL, Redis, Docker Compose.
## Команды
docker compose --env-file .local/.env -f .local/docker-compose.yml \
exec -T webserver php artisan test
## Правила
- Язык интерфейса и контента: русский
- Filament-ресурсы — каждый в отдельной папке
- Публичные Blade-шаблоны наследуют layouts/blog.blade.phpПервая строка файла — ссылка на подробное руководство. Это единственное, что связывает два файла, и этого достаточно.
AGENTS.md — триста двенадцать строк и восемнадцать разделов: автономность, базовые правила, дизайн, скиллы, обзор, архитектура, модели и связи, подсветка кода, обложки, безопасность, конвенции, окружение, общий модуль редактора, тесты, бэклог, частые задачи, маршрутизация, субагенты.
Да, это много, и я про это ещё скажу. Но принцип разделения работает: указатель нужен, чтобы начать работать не наврав, руководство — чтобы разобраться в конкретной области.
Что дублировать сознательно
Полного запрета на дублирование у меня нет, есть правило про два случая.
Дублируется то, что нужно постоянно и меняется редко. Команда запуска внутри контейнера стоит и в указателе, и в руководстве, и в телах пишущих агентов. Три копии, меняются раз в год, а нужны в каждой второй задаче.
Не дублируется то, что меняется вместе с кодом. Список моделей, описание связей, перечень ресурсов админки — это живёт в одном месте и по возможности вообще не описывается словами. Раздел с моделями у меня в руководстве есть, и он самый гнилой из всех: устаревает быстрее, чем я его правлю.
Между этими двумя случаями — ссылка. В руководстве стоит «дизайн — читай docs/DESIGN.md и общий контракт соседнего проекта». Пересказывать дизайн-систему в файле контекста бессмысленно: она длинная и живёт своей жизнью.
Разделы, которые окупились
Из восемнадцати разделов пользу приносят не все. Три окупились так, что я переношу их в каждый новый проект.
Автономность. Первый раздел файла, десять строк. Он говорит: выполняй задачу до конца, не спрашивай подтверждений на каждом шаге. И тут же перечисляет исключения — удаление того, что не создавал в этой сессии, отправка в удалённый репозиторий, действия вне рабочего каталога.
До этого раздела половина сессий уходила на диалог «продолжить? да, продолжить». После — не уходит. Исключения при этом соблюдаются, потому что они перечислены конкретно, а не описаны принципом.
Конвенции. То, чем проект отличается от типичного проекта на Laravel: раскладка ресурсов админки по папкам, передача списка рубрик во все публичные шаблоны, вывод пользовательского HTML только через очиститель. Три десятка строк, каждая — след правки после ревью.
Частые задачи. Пять-шесть типовых сценариев с порядком действий: добавить пост, завести рубрику, поменять настройки сайта. Раздел выглядит как документация для человека, а работает как маршрут: он называет затрагиваемые файлы, и по нему видно, что задача про контент — это сидер, а не админка.
Раздел «чего здесь нет» я упоминал в цикле про промпты и повторю: он бьёт по достройке недостающего из типичного проекта. У блога это «ролевой модели нет, есть флаг администратора» и «API наружу нет».
Каталог .ai/ как пакет
Скиллы и агенты я держу в отдельном каталоге, а не в корне и не в служебной папке конкретного инструмента.
.ai/
├── README.md что здесь лежит и чем скилл отличается от агента
├── skills/ шестнадцать процедур
└── agents/ двенадцать исполнителейПричин две. Первая: инструментов несколько, и привязка к одному из них означает переезд при смене. Вторая: каталог с индексом читается человеком. Я туда заглядываю сам, когда забываю, как называется нужный скилл.
Индекс — файл на пятнадцать строк, в котором таблица из двух строк и абзац про разницу между скиллом и агентом. Полные списки живут в руководстве, чтобы не иметь двух перечней.
Симлинки в служебный каталог инструмента — компромисс, который мне не нравится, но работает: часть скиллов подхватывается автоматически, при этом источник один.
Как это не разъезжается
Одна правка — один источник. Звучит банально, но у меня для этого есть три конкретных приёма.
Первый: перечни живут в одном месте. Список скиллов и агентов — только в руководстве. В индексе каталога — ссылка на этот раздел, а не копия.
Второй: содержимое ссылается вниз, а не вверх. Руководство ссылается на скиллы, скиллы на справочники. Обратных ссылок стараюсь не заводить: они устаревают первыми, потому что при переименовании о них не вспоминают.
Третий: правило перечитывания. Правлю тело агента — смотрю его фронтматтер. Правлю скилл — проверяю, не пересказан ли он в руководстве. Это ручная дисциплина, и она подводит: расхождение между телом одного агента и его правами я нашёл спустя месяцы.
Что осталось
Раскладка одинаковая в тринадцати репозиториях, и это её главная ценность: возврат к проекту через полгода не начинается с поиска, где что лежит.
Чего я не решил — размера руководства. Триста двенадцать строк для файла, который читается целиком, — много. Правильный размер, по моим ощущениям, сотня. Резать больно: каждый раздел когда-то появился по делу. Скорее всего, половина разделов должна стать скиллами, и это работа на вечер, который я откладываю с весны.
