# Repository Guidelines

Этот репозиторий теперь представляет собой не только локальный Lakehouse-стенд, но и каркас учебного курса `Lakehouse без магии`.

В `AGENTS.md` держим только стабильные правила для автоматизированных правок. Изменчивый контекст проекта, карта репозитория и правила синхронизации вынесены в [docs/maintainer_guide.md](docs/maintainer_guide.md).

## Канонические документы

- `README.md` — верхнеуровневое описание репозитория, архитектуры и точек входа.
- `START_HERE.md` — первый маршрут для студента до запуска ноутбуков.
- `docs/stack_reference.md` — технический reference по сервисам, портам, доступу и smoke-тестам.
- `docs/course_prd.md` — рамки курса, learning outcomes, scope и out of scope.
- `docs/course_program.md` — модульная структура курса и состав учебных материалов.
- `docs/maintainer_guide.md` — карта репозитория и правила синхронизации изменений.
- `plans/` — внутренние living docs; не источник истины для студентского маршрута.
- `docs/archive/` — архивные материалы; не использовать как актуальную документацию без явного запроса.

## Структура репозитория

- `docker-compose.yml`, `spark/`, `trino/`, `jupyter/` — исполняемый стенд.
- `notebooks/`, `src/` — учебные материалы и вспомогательные примеры.
- `docs/`, `START_HERE.md`, `README.md` — входная и методическая документация.
- `plans/` — внутреннее планирование.

Новые учебные примеры держи в `src/` или `notebooks/`, а конфигурацию стенда не смешивай с учебным контентом.

## Правила изменений

- Сначала меняй канонический документ для соответствующего слоя, потом синхронизируй связанные ссылки и упоминания.
- Если меняются сервисы, порты, имена контейнеров, образы или команды запуска, обновляй как минимум `README.md`, `START_HERE.md`, `docs/stack_reference.md` и затронутые примеры.
- Если меняются scope курса, learning outcomes или модульная структура, обновляй `docs/course_prd.md` и `docs/course_program.md`, а не только `plans/`.
- Поддерживай согласованный маршрут `README -> START_HERE -> docs/course_program.md -> notebooks/src`.
- Не дублируй крупные фрагменты между документами, если можно сослаться на канонический файл.
- Legacy-материалы явно помечай как архивные и не возвращай их в основной маршрут без явного запроса.

## Стиль и содержание

- Сохраняй русский язык в student-facing документации, если задача не про перевод.
- Предпочитай небольшие, сфокусированные примеры и не усложняй стенд без явного запроса.
- Держи ноутбуки понятными для самостоятельного прохождения; переиспользуемую логику выноси в `src/`.
- Не добавляй обязательные шаги со скачиванием данных прямо из ноутбуков, если это можно оформить через onboarding-документацию.

## Проверка изменений

- Для изменений только в документации проверь согласованность ссылок, терминов и маршрута прохождения.
- Для изменений стенда сначала используй лёгкую валидацию вроде `docker compose config`.
- Если меняется поведение стенда или учебных примеров, по возможности проверь сценарии из `src/spark/cluster_smoke.py`, `src/spark/iceberg_smoke.py`, `src/trino/iceberg_smoke.sql` или `notebooks/01_environment_and_smoke_test.ipynb`.
- Если полная проверка не выполнялась, укажи это явно.

## Commit & PR Notes

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

## Agent-Specific Instructions

- Уважай существующие изменения пользователя и не откатывай их без запроса.
- Предпочитай минимальные изменения, которые делают курс проще и устойчивее для новичка.
- Если непонятно, какой маршрут сейчас актуален, доверяй `START_HERE.md` и `docs/course_program.md`, а не старым HOWTO или планам.