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»
|
||||
|
||||
> Дата: 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`), не полагайся на память: именно типы и поведение функций уже один раз подвели.
|
||||
|
||||
Reference in New Issue
Block a user