docs(course): стандарт уроков фиксирует регистр, шапку и грабли
- Зачем:
- наработанный по урокам 0–2 мягкий регистр жил только в памяти и хендоффах;
стандарт его не требовал — следующий урок мог уехать обратно в сжатый стиль
и повторить уже пройденные ошибки.
- Что:
- добавлен §2 «Регистр и голос»: расшифровка терминов на первом употреблении,
###-подзаголовки, разбивка «стен», человеческий тон, house style, ai-text-lint;
- в §1 описана шапка урока (Формат / «О чём урок простыми словами»), старые
«Статус: черновик» и «Режим: руки» помечены как не возвращать;
- добавлен §5 «Грабли»: проверять на стенде, сверять имена с DDL, один паттерн
на урок, спорные API ClickHouse — через MCP Context7;
- перенумерованы разделы (качество кода → §3, самопроверка → §4) и ссылки на них.
- Проверка:
- прочитать LESSON_STANDARD.md сверху вниз: §1–§5 идут по порядку, ссылки
«(раздел 4)» указывают на «Самопроверку».
This commit is contained in:
@@ -1,6 +1,7 @@
|
|||||||
# Стандарт уроков курса «Кликстрим на ClickHouse»
|
# Стандарт уроков курса «Кликстрим на ClickHouse»
|
||||||
|
|
||||||
> Дата: 2026-06-01.
|
> Дата: 2026-06-01. Поправка: 2026-06-05 (по итогам уроков 0–2 — добавлены §2 «Регистр
|
||||||
|
> и голос», описание шапки урока и §5 «Грабли, на которые мы уже наступили»).
|
||||||
> Назначение: рабочий чеклист, по которому пишется **каждый** урок. Открывается при
|
> Назначение: рабочий чеклист, по которому пишется **каждый** урок. Открывается при
|
||||||
> создании урока. Рамка курса (зачем/что/скоуп) — в `PRD.md`; карта уроков и
|
> создании урока. Рамка курса (зачем/что/скоуп) — в `PRD.md`; карта уроков и
|
||||||
> маршрут — в `LEARNING_PLAN.md`.
|
> маршрут — в `LEARNING_PLAN.md`.
|
||||||
@@ -23,15 +24,60 @@
|
|||||||
состоянию (откатить изменение либо `make clean/up/ddl/data/transform`), чтобы
|
состоянию (откатить изменение либо `make clean/up/ddl/data/transform`), чтобы
|
||||||
самостоятельный менти не застрял со сломанным стендом без ментора.
|
самостоятельный менти не застрял со сломанным стендом без ментора.
|
||||||
(Урок 0 — без этого шага, только наблюдение.)
|
(Урок 0 — без этого шага, только наблюдение.)
|
||||||
5. **Проверь себя** — самопроверка (раздел 3).
|
5. **Проверь себя** — самопроверка (раздел 4).
|
||||||
6. **Что должно получиться** — **конкретный видимый результат**, который менти проверяет
|
6. **Что должно получиться** — **конкретный видимый результат**, который менти проверяет
|
||||||
сам: скрин эффекта правки (например, красный DAG или `+1` в таблице ошибок) плюс один
|
сам: скрин эффекта правки (например, красный DAG или `+1` в таблице ошибок) плюс один
|
||||||
абзац «своими словами» про паттерн урока или запрос, который пришлось написать. Это и
|
абзац «своими словами» про паттерн урока или запрос, который пришлось написать. Это и
|
||||||
есть самопроверка (раздел 3); те же вопросы «своими словами» менти разбирает с ментором
|
есть самопроверка (раздел 4); те же вопросы «своими словами» менти разбирает с ментором
|
||||||
на еженедельном созвоне. (Урок 0 — без правки, поэтому результат здесь — что менти
|
на еженедельном созвоне. (Урок 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`.
|
Вердикты аудита по конкретным путям — в `LEARNING_PLAN.md`.
|
||||||
|
|
||||||
## 3. Самопроверка (по-простому)
|
## 4. Самопроверка (по-простому)
|
||||||
|
|
||||||
Отдельный тест-фреймворк не строим. Опираемся на то, что в стенде уже есть:
|
Отдельный тест-фреймворк не строим. Опираемся на то, что в стенде уже есть:
|
||||||
- штатные быстрые проверки (smoke) из `docs/TEST_PLAN.md`;
|
- штатные быстрые проверки (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`), не полагайся на память: именно типы и поведение функций уже один раз подвели.
|
||||||
|
|||||||
Reference in New Issue
Block a user