ddadminandClaude Opus 4.8
d8c5e61a3a
- Зачем:
- середина пайплайна перегружала один урок тремя паттернами; нужны честный такт и разведённые слои.
- Что:
- середина расщеплена: ODS и DDS — отдельные уроки (один паттерн на урок), DM демотирован в поверхность потребления; всего 7 уроков.
- зафиксированы финальные вердикты аудита и список правок по урокам (LEARNING_PLAN §3/§3.1), включая гейт целостности DAG.
- в LESSON_STANDARD добавлены шаг отката «верни как было» и артефакт на сессию; в PRD обновлены скоуп и такт ~день на урок.
- Проверка:
- вычитка docs/course/{PRD,LEARNING_PLAN,LESSON_STANDARD}.md: номера уроков, скоуп и перекрёстные ссылки сходятся.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
72 lines
6.0 KiB
Markdown
72 lines
6.0 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`
|
|
и увидеть, как топик читается заново. Менти меняет — видит эффект — объясняет.
|
|
**Верни как было** — каждая правка завершается явным шагом отката к чистому
|
|
состоянию (откатить изменение либо `make clean/up/ddl/data/transform`), чтобы
|
|
самостоятельный менти не застрял со сломанным стендом без ментора.
|
|
(Урок 0 — без этого шага, только наблюдение.)
|
|
5. **Проверь себя** — самопроверка (раздел 3).
|
|
6. **Принеси на сессию** — **конкретный артефакт** плюс вопросы: скрин видимого
|
|
результата правки (например, красный DAG или `+1` в таблице ошибок), один абзац
|
|
«своими словами» про паттерн урока или запрос, который пришлось написать. Артефакт
|
|
делает самопроверку проверяемой, а сверку — предметной (критерий успеха `PRD` §5).
|
|
|
|
## 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` для сброса и повтора.
|
|
|
|
В каждом уроке — маленькая табличка самопроверки в формате
|
|
**действие → где смотреть → что ожидать**, а для управляемой правки — какой
|
|
видимый результат должен появиться.
|