С чего начать, шаг 3: минимальный файл контекста
Двадцать строк, написанных по промахам, работают лучше трёх сгенерированных страниц.

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

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

Откуда берётся содержимое

Из первой недели. Каждый раз, когда пришлось поправлять результат из-за незнания проекта, — это кандидат в файл.

В блоге первые строки появились так:

запустили php artisan на хосте        → строка про контейнер
положили ресурс админки одним файлом  → строка про раскладку по папкам
захардкодили текст в шаблоне          → строка про сидеры как источник
забыли передать рубрики в шаблон      → строка про navCategories

Четыре промаха — четыре строки. Ни одну из них я бы не написал заранее: они неочевидны именно потому, что для меня привычны.

Отсюда порядок: сначала неделя работы, потом файл. Не наоборот.

Три обязательных раздела

Команды. Как запустить, как прогнать тесты, как собрать. Это первое, что делают неправильно.

## Команды

docker compose --env-file .local/.env -f .local/docker-compose.yml \
  exec -T webserver php artisan test

npm run build

Пишите полностью, с флагами и путями. Сокращённая форма вида «тесты запускаются в контейнере» не помогает: команду всё равно придётся собирать по кускам.

Конвенции. То, чем проект отличается от типичного на этом стеке. Не «пишите чистый код», а конкретные решения:

## Правила

- Язык интерфейса и контента — русский.
- Ресурсы админки — каждый в своей папке: Resource.php, Schemas/, Tables/, Pages/.
- Публичные шаблоны наследуют layouts/blog.blade.php, им нужен список рубрик.
- Пользовательский HTML печатается только через очиститель.

Проверка каждой строки: происходит ли ошибка, если строки нет. Если не происходит — строка лишняя.

Чего здесь нет. Раздел, который экономит больше остальных, и его почти никогда не пишут.

## Чего здесь нет

- Ролевой модели. Есть один флаг администратора.
- API наружу. Только веб-маршруты.
- Хранения статей в файлах. Контент — HTML в базе.

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

Двадцать строк, а не триста

Файл контекста читается целиком и на каждой задаче. Это его сила и его ограничение: длинный файл конкурирует за внимание с самой задачей.

Мой рабочий размер для короткого указателя — двадцать-тридцать строк. Для подробного руководства, которое читается по ссылке, — до сотни.

Что не идёт в файл ни в каком объёме: описание архитектуры, перечень моделей, пересказ фреймворка. Первое устаревает, второе есть в коде, третье известно и так.

Как понять, что файл распух: если вы сами перестали его перечитывать перед правкой — он уже слишком длинный.

Как проверить, что файл работает

Способ простой и немного жестокий: дать задачу, которую до появления файла делали неправильно, и посмотреть.

Я так проверял строку про сидеры. Задача была «поменяй текст на странице „Об авторе“». До строки — правка приходила в шаблоне. После — в сидере, как надо.

Второй способ — читать первые действия. Если работа начинается с попытки запустить команду не так, как записано, — строка про команды либо отсутствует, либо утонула в середине файла.

Третий, самый честный: считать, сколько раз за неделю вы дописывали в задачу то, что и так есть в файле. Каждое такое дописывание означает, что строка не работает.

Что делать дальше

Файл контекста растёт медленно и это нормально. Три-четыре строки в месяц на активном проекте.

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

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

Отклонения

Монорепо. Один файл на весь репозиторий не работает: команды и конвенции разные в каждом пакете. Раскладка — короткий общий файл в корне (что это за монорепо, где что лежит) и свой файл в каждом пакете. Общие строки не дублируйте: в корневом файле оставьте ссылку.

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

Проект, где вы не можете добавить файл. Заводите тот же файл у себя локально и подставляйте его содержимое в задачи. Неудобно, но три раздела остаются теми же.

Проект, где файл уже есть и он плохой. Сгенерированное описание на три страницы встречается часто. Не переписывайте с нуля: пройдите по нему и вычеркните всё, что не является командой, конвенцией или отрицанием. Обычно остаётся строк пятнадцать, и они неплохие.