ddadmin
dc0e6f9452
- Зачем: - превратить стенд в самостоятельный учебный материал (трек «со звёздочкой») для продвинутых менти. - Что: - docs/course/: PRD, LEARNING_PLAN, LESSON_STANDARD и README-индекс. - AGENTS.md: ссылка на курс в разделе навигации. - CLAUDE.md: @-include AGENTS.md для контекста агента. - Проверка: - открыть docs/course/README.md и пройти по ссылкам на PRD/план/стандарт.
66 lines
5.1 KiB
Markdown
66 lines
5.1 KiB
Markdown
# Стандарт уроков курса «Кликстрим на ClickHouse»
|
|
|
|
> Статус: черновик. Дата: 2026-06-01.
|
|
> Назначение: рабочий чеклист, по которому пишется **каждый** урок. Открывается при
|
|
> создании урока. Рамка курса (зачем/что/скоуп) — в `PRD.md`; карта уроков и
|
|
> маршрут — в `LEARNING_PLAN.md`.
|
|
|
|
---
|
|
|
|
## 1. Шаблон урока
|
|
|
|
Каждый урок строится по единому шаблону:
|
|
|
|
1. **Зачем и где в проде** — что за паттерн и где он встречается в обычной
|
|
кликстрим-аналитике (без привязки к конкретной компании).
|
|
2. **Руки** — что запустить и что понаблюдать (Kafka UI / ClickHouse / Grafana).
|
|
3. **Загляни внутрь** — чтение отполированного эталонного кода с пояснениями.
|
|
4. **Управляемая правка** — одно-два маленьких изменения с **видимым результатом**.
|
|
Например: добавить поле в Materialized View и увидеть его в `*_raw`; «сломать»
|
|
запись и увидеть `+1` в таблице ошибок `parse_errors`; сменить `kafka_group_name`
|
|
и увидеть, как топик читается заново. Менти меняет — видит эффект — объясняет.
|
|
(Урок 0 — без этого шага, только наблюдение.)
|
|
5. **Проверь себя** — самопроверка (раздел 3).
|
|
6. **Принеси на сессию** — что доложить ментору и какие вопросы задать.
|
|
|
|
## 2. Стандарт качества эталонного кода
|
|
|
|
Эталонные пути полируем до **учебного качества**; остальной код стенда остаётся под
|
|
капотом — его не трогаем.
|
|
|
|
**Чеклист (минимум).** Файл доведён, если:
|
|
1. комментарии на русском объясняют **зачем**, а не пересказывают код;
|
|
2. шаги явные и названы своими именами, без неочевидных трюков;
|
|
3. в начале файла — поток данных одной строкой (как в STG:
|
|
`Kafka → kafka_*_raw → MV → *_raw`);
|
|
4. ошибки и проверки качества данных видны — понятно, куда смотреть;
|
|
5. нет мусора: мёртвого кода, закомментированных экспериментов, разнобоя в именах.
|
|
|
|
**Тест одного прохода (главный критерий и защита от громоздкости).**
|
|
> Менти читает файл один раз сверху вниз и может пересказать своими словами,
|
|
> *что* происходит и *зачем* — не прыгая по файлу, не гугля, не расшифровывая трюки.
|
|
|
|
Если тест не проходит — правим строго одним из трёх способов: (1) упростить код;
|
|
(2) добавить ровно одну строку «зачем» там, где код честно неочевиден; (3) убрать
|
|
лишнее под капот или в короткую пометку. **Добавить ещё комментариев — не способ.**
|
|
|
|
**Две защиты от раздувания:**
|
|
- комментируем только неочевидное «зачем» (очевидную строку комментировать нельзя —
|
|
лишний текст сам по себе мешает понимать);
|
|
- «близко к проду» ≠ «вся прод-сложность прямо в коде урока»: один прод-паттерн на
|
|
урок показываем чисто, остальные прод-заботы — короткой пометкой «в проде иначе: …».
|
|
|
|
Вердикты аудита по конкретным путям — в `LEARNING_PLAN.md`.
|
|
|
|
## 3. Самопроверка (по-простому)
|
|
|
|
Отдельный тест-фреймворк не строим. Опираемся на то, что в стенде уже есть:
|
|
- штатные быстрые проверки (smoke) из `docs/TEST_PLAN.md`;
|
|
- встроенные проверки в `etl_pipeline_dag.py` (DAG падает на пустой витрине или
|
|
нарушении целостности);
|
|
- `make clean/up/ddl/data/transform` для сброса и повтора.
|
|
|
|
В каждом уроке — маленькая табличка самопроверки в формате
|
|
**действие → где смотреть → что ожидать**, а для управляемой правки — какой
|
|
видимый результат должен появиться.
|