diff --git a/docs/course/LESSON_STANDARD.md b/docs/course/LESSON_STANDARD.md index 395b7af..04f0971 100644 --- a/docs/course/LESSON_STANDARD.md +++ b/docs/course/LESSON_STANDARD.md @@ -1,6 +1,7 @@ # Стандарт уроков курса «Кликстрим на ClickHouse» -> Дата: 2026-06-01. +> Дата: 2026-06-01. Поправка: 2026-06-05 (по итогам уроков 0–2 — добавлены §2 «Регистр +> и голос», описание шапки урока и §5 «Грабли, на которые мы уже наступили»). > Назначение: рабочий чеклист, по которому пишется **каждый** урок. Открывается при > создании урока. Рамка курса (зачем/что/скоуп) — в `PRD.md`; карта уроков и > маршрут — в `LEARNING_PLAN.md`. @@ -23,15 +24,60 @@ состоянию (откатить изменение либо `make clean/up/ddl/data/transform`), чтобы самостоятельный менти не застрял со сломанным стендом без ментора. (Урок 0 — без этого шага, только наблюдение.) -5. **Проверь себя** — самопроверка (раздел 3). +5. **Проверь себя** — самопроверка (раздел 4). 6. **Что должно получиться** — **конкретный видимый результат**, который менти проверяет сам: скрин эффекта правки (например, красный DAG или `+1` в таблице ошибок) плюс один абзац «своими словами» про паттерн урока или запрос, который пришлось написать. Это и - есть самопроверка (раздел 3); те же вопросы «своими словами» менти разбирает с ментором + есть самопроверка (раздел 4); те же вопросы «своими словами» менти разбирает с ментором на еженедельном созвоне. (Урок 0 — без правки, поэтому результат здесь — что менти увидел при наблюдении.) -## 2. Стандарт качества эталонного кода +### Шапка урока + +Кроме шести секций, каждый урок открывается единым блоком-цитатой (`>`) сверху — он задаёт +рамку до того, как менти дойдёт до первой секции: + +- **Формат:** одной фразой, что менти делает, — `**практика** — будешь сам запускать…` + или `**наблюдение** — ничего не запускаем и не меняем…`. Старые пометки «Статус: черновик» + и «Режим: руки» не возвращаем: менти читал их как «материал не готов» и «непонятно, как + понимать»; +- **Пререквизит:** какой урок пройден и что менти уже умеет; +- **Эталонный путь:** ссылка(и) на разбираемый файл; +- **Поток данных одной строкой:** та же стрелочная схема, что стоит в начале эталонного файла; +- **О чём урок простыми словами:** 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. Стандарт качества эталонного кода Эталонные пути полируем до **учебного качества**; остальной код стенда остаётся под капотом — его не трогаем. @@ -60,7 +106,7 @@ Вердикты аудита по конкретным путям — в `LEARNING_PLAN.md`. -## 3. Самопроверка (по-простому) +## 4. Самопроверка (по-простому) Отдельный тест-фреймворк не строим. Опираемся на то, что в стенде уже есть: - штатные быстрые проверки (smoke) из `docs/TEST_PLAN.md`; @@ -71,3 +117,20 @@ В каждом уроке — маленькая табличка самопроверки в формате **действие → где смотреть → что ожидать**, а для управляемой правки — какой видимый результат должен появиться. + +## 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`), не полагайся на память: именно типы и поведение функций уже один раз подвели.