mini-lakehouse-lab/AGENTS.md

Repository Guidelines

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

В AGENTS.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/glossary.md — справочник терминов курса.
• docs/mentor_notes.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 или планам.