docs(course): добавлен продвинутый курс «Кликстрим на ClickHouse»
- Зачем: - превратить стенд в самостоятельный учебный материал (трек «со звёздочкой») для продвинутых менти. - Что: - docs/course/: PRD, LEARNING_PLAN, LESSON_STANDARD и README-индекс. - AGENTS.md: ссылка на курс в разделе навигации. - CLAUDE.md: @-include AGENTS.md для контекста агента. - Проверка: - открыть docs/course/README.md и пройти по ссылкам на PRD/план/стандарт.
This commit is contained in:
@@ -0,0 +1,65 @@
|
||||
# Стандарт уроков курса «Кликстрим на 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` для сброса и повтора.
|
||||
|
||||
В каждом уроке — маленькая табличка самопроверки в формате
|
||||
**действие → где смотреть → что ожидать**, а для управляемой правки — какой
|
||||
видимый результат должен появиться.
|
||||
Reference in New Issue
Block a user