ddadminandClaude Opus 4.6
0ae83cecdb
- Зачем: - закрыты 3 вспомогательных артефакта из course_program.md §3.3: glossary, cheat sheet, mentor notes. - README переписан с фокусом на ценность для студента. - Что: - создан docs/glossary.md (16 терминов, сгруппированных по темам с параллелями к DWH). - создан docs/mentor_notes.md (тайминг, типичные вопросы, checkpoint-ы, формат «менти работает сам»). - добавлена секция «Краткая шпаргалка» в docs/stack_reference.md (S3-пути, таблицы, SQL-команды, маунты). - README.md переписан: лид с навыками, убрано дублирование со stack_reference. - обновлены перекрёстные ссылки в AGENTS.md, course_program.md, maintainer_guide.md. - Проверка: - все ссылки между документами валидны (glossary.md, mentor_notes.md существуют). - термины glossary и команды шпаргалки верифицированы по содержимому ноутбуков. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
63 lines
6.2 KiB
Markdown
Executable File
63 lines
6.2 KiB
Markdown
Executable File
# 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/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 или планам.
|