clickstream-ch-kafka-superset-demo/docs/course/LESSON_STANDARD.md

# Стандарт уроков курса «Кликстрим на ClickHouse»

> Дата: 2026-06-01. Поправка: 2026-06-05 (по итогам уроков 0–2 — добавлены §2 «Регистр
> и голос», описание шапки урока и §5 «Грабли, на которые мы уже наступили»).
> Назначение: рабочий чеклист, по которому пишется **каждый** урок. Открывается при
> создании урока. Рамка курса (зачем/что/скоуп) — в `PRD.md`; карта уроков и
> маршрут — в `LEARNING_PLAN.md`.

---

## 1. Шаблон урока

Каждый урок строится по единому шаблону:

1. **Зачем и где в проде** — что за паттерн и где он встречается в обычной
   кликстрим-аналитике (без привязки к конкретной компании).
2. **Руки** — что запустить и что понаблюдать (Kafka UI / ClickHouse / Grafana).
3. **Загляни внутрь** — чтение отполированного эталонного кода с пояснениями.
4. **Управляемая правка** — одно-два маленьких изменения с **видимым результатом**.
   Например: добавить поле в Materialized View и увидеть его в `*_raw`; «сломать»
   запись и увидеть `+1` в таблице ошибок `parse_errors`; сменить `kafka_group_name`
   и увидеть, как топик читается заново. Менти меняет — видит эффект — объясняет.
   **Верни как было** — каждая правка завершается явным шагом отката к чистому
   состоянию (откатить изменение либо `make clean/up/ddl/data/transform`), чтобы
   самостоятельный менти не застрял со сломанным стендом без ментора.
   (Урок 0 — без этого шага, только наблюдение.)
5. **Проверь себя** — самопроверка (раздел 4).
6. **Что должно получиться** — **конкретный видимый результат**, который менти проверяет
   сам: скрин эффекта правки (например, красный DAG или `+1` в таблице ошибок) плюс один
   абзац «своими словами» про паттерн урока или запрос, который пришлось написать. Это и
   есть самопроверка (раздел 4); те же вопросы «своими словами» менти разбирает с ментором
   на еженедельном созвоне. (Урок 0 — без правки, поэтому результат здесь — что менти
   увидел при наблюдении.)

### Шапка урока

Кроме шести секций, каждый урок открывается единым блоком-цитатой (`>`) сверху — он задаёт
рамку до того, как менти дойдёт до первой секции:

- **Формат:** одной фразой, что менти делает, — `**практика** — будешь сам запускать…`
  или `**наблюдение** — ничего не запускаем и не меняем…`. Старые пометки «Статус: черновик»
  и «Режим: руки» не возвращаем: менти читал их как «материал не готов» и «непонятно, как
  понимать»;
- **Пререквизит:** какой урок пройден и что менти уже умеет;
- **Эталонный путь:** ссылка(и) на разбираемый файл;
- **Поток данных одной строкой:** та же стрелочная схема, что стоит в начале эталонного файла;
- **О чём урок простыми словами:** 1–2 фразы совсем простым языком, без терминов, — чтобы
  менти с первой строки понял, о чём речь.

В конце урока — короткий **мост к следующему**: какой честный вопрос остаётся открытым и
как его закроет следующий урок.

## 2. Регистр и голос

Этот раздел — про то, *как* написан урок. Он появился по итогам уроков 0–2: мы начали со
сжатого регистра и переписывали — дешевле сразу писать мягко.

**Кто читатель.** Менти прошёл курсовую, уровень — «обзорно» (понять идею и потрогать, а не
стать экспертом). Поддержка — еженедельный созвон с ментором, а не «сессия»; на нём менти
разбирает вопросы «своими словами».

**Правила регистра:**
- **термин расшифровываем на первом употреблении** — коротко, своими словами (как `ODS`,
  `DQ-split`, `Materialized View`, `*OrNull` в уроках 1–2). Не оставляем слово голым;
- **человеческий тон, без жаргона ради жаргона** — короткие предложения, прямое обращение
  к менти («открой», «посмотри», «помнишь из урока 0»);
- **`###`-подзаголовки внутри длинных секций** — особенно в «Загляни внутрь»: каждый
  смысловой кусок под своим заголовком, а не сплошной стеной;
- **плотные абзацы-«стены» бьём на пункты** с конкретикой;
- **разжёвывать, а не сжимать.** Урок может выйти заметно длиннее первого черновика — для
  «обзорно» это норма, а не повод резать.

**House style (оставляем осознанно, `ai-text-lint` на это не правим):** тире «—», буква «ё»,
жирные зачины абзацев, двоеточие перед списком.

**Перед финалом** — прогнать текст урока через `/ai-text-lint` (контекст `article`) и убрать
настоящие AI-маркеры (например, слова вроде «ключевой», «является»), но house style выше
не снимать.

## 3. Стандарт качества эталонного кода

Эталонные пути полируем до **учебного качества**; остальной код стенда остаётся под
капотом — его не трогаем.

**Чеклист (минимум).** Файл доведён, если:
1. комментарии на русском объясняют **зачем**, а не пересказывают код;
2. шаги явные и названы своими именами, без неочевидных трюков;
3. в начале файла — поток данных одной строкой (как в STG:
   `Kafka → kafka_*_raw → MV → *_raw`);
4. ошибки и проверки качества данных видны — понятно, куда смотреть;
5. нет мусора: мёртвого кода, закомментированных экспериментов, разнобоя в именах.

**Тест одного прохода (главный критерий и защита от громоздкости).**
> Менти читает файл один раз сверху вниз и может пересказать своими словами,
> *что* происходит и *зачем* — не прыгая по файлу, не гугля, не расшифровывая трюки.

Если тест не проходит — правим строго одним из трёх способов: (1) упростить код;
(2) добавить ровно одну строку «зачем» там, где код честно неочевиден; (3) убрать
лишнее под капот или в короткую пометку. **Добавить ещё комментариев — не способ.**

**Две защиты от раздувания:**
- комментируем только неочевидное «зачем» (очевидную строку комментировать нельзя —
  лишний текст сам по себе мешает понимать);
- «близко к проду» ≠ «вся прод-сложность прямо в коде урока»: один прод-паттерн на
  урок показываем чисто, остальные прод-заботы — короткой пометкой «в проде иначе: …».

Вердикты аудита по конкретным путям — в `LEARNING_PLAN.md`.

## 4. Самопроверка (по-простому)

Отдельный тест-фреймворк не строим. Опираемся на то, что в стенде уже есть:
- штатные быстрые проверки (smoke) из `docs/TEST_PLAN.md`;
- встроенные проверки в `etl_pipeline_dag.py` (DAG падает на пустой витрине или
  нарушении целостности);
- `make clean/up/ddl/data/transform` для сброса и повтора.

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

## 5. Грабли, на которые мы уже наступили

Короткий список ошибок из уроков 0–2 — чтобы следующий урок их не повторил.

- **Проверяй на стенде, а не «на глаз».** Любой категоричный claim про числа или целостность
  подтверждай командой на стенде. Так нашёлся баг с `kafka_ts` в уроке 1 (значение типа
  `DateTime64` молча резалось через `toInt64`, и время по всему стенду уехало в `1970`) и
  подтвердилось, что «26 из 50» в уроке 2 — это схлопывание повторов по `click_id` (проверено
  `uniqExact`), а не потеря данных.
- **Имена таблиц и колонок в тексте сверяй с реальным DDL.** То, что написано в уроке, должно
  совпадать с `sql/ddl/...`, иначе менти запутается, когда выполнит запрос на стенде.
- **Один паттерн на урок; будущие темы только анонсируй.** Не раскрывай то, что относится к
  следующим урокам (пример: жёсткий гейт на «сирот» — это урок 4, в уроке 3 мы их только
  вводим как понятие).
- **Спорные API ClickHouse сверяй через MCP Context7** (зачем и в каком порядке — в
  `AGENTS.md`), не полагайся на память: именно типы и поведение функций уже один раз подвели.