docs(context): сделать словарь понятным начинающему #248

New Issue

2026-09-13T20:32:35+03:00

ddmitry commented

2026-09-13 20:32:35 +03:00

Режим выполнения

Редактуру выполняет Codex самостоятельно, без субагентов. Рекомендуемый reasoning effort: high. Словарь рекомендуется выполнить первым: его определения станут опорой для остальных материалов.

Чему учит

Различать понятия стенда и понимать незнакомый термин без предварительного изучения устройства генератора.

Проблема

Сейчас определение часто сложнее самого термина: «ветвь дерева случайности», «день-функция», «единственный структурный шов модели». Читателю приходится разбирать несколько новых понятий ради одного. Общие понятия хранилища перемешаны с внутренними понятиями генератора.

Работа

Переработать CONTEXT.md как единый словарь проекта. Начать с понятий, которые нужны в учебной работе; подробности генератора сгруппировать так, чтобы они не мешали поиску. Не заводить второй словарь. Определение начинать с объяснения обычными словами; связь с кодом и ограничения давать следом. Добавлять короткий пример только там, где он проясняет различие.

Проверить фактические утверждения. В частности, фраза о наполнении стартовыми данными «при каждом make up» должна различать первый запуск и повторный подъем сохраненного стенда.

Критерии приемки

По определению понятно, что означает термин; для понимания не требуется цепочка переходов к другим незнакомым определениям.
Читатель может различить человека, посетителя с ClientID и пользователя магазина с user_id, а также модельное и реальное время.
Понятия генератора отделены от основного пути чтения без второго конкурирующего словаря и без потери нужных определений.
Описания первого и повторного запуска согласованы с кодом; названия из кода и значения терминов сохранены.
Ссылки на словарь и его разделы, в том числе якорь «Язык», работают.

Сначала прочитать

CONTEXT.md, docs/agents/domain.md, docs/handbook/README.md, docs/handbook/generator.md, docs/labs/README.md. Для фактов запуска — Makefile и dags/world_lifecycle.py.

Связанная задача о worker: #183 . Прочитать ее текущее описание и комментарии; не включать сюда массовое переименование по репозиторию.

Проверка

git diff --check; проверить входящие ссылки и якоря. Сверить определения с конкретными полями и командами в исходниках. Для редакторской правки запуск стенда не нужен.

Общие границы

Это продолжение редактуры материалов для начинающего инженера данных. Образцы языка — корневой README, главы docs/handbook/ и задания docs/labs/. Писать простым русским языком; термины объяснять при первом употреблении. Не упрощать технический смысл и не подменять объяснение образными оборотами.

Уже вычитанные лабораторные, handbook и карту не переписывать. Исторические спеки, ADR и внутренние инструкции не входят в задачу. Перед приемкой сделать проход на сокращение: убрать повторы и пояснения, которые не помогают пройти учебную программу. Имена объектов, технические условия и полезные примеры сохранить.

## Режим выполнения Редактуру выполняет Codex самостоятельно, без субагентов. Рекомендуемый reasoning effort: `high`. Словарь рекомендуется выполнить первым: его определения станут опорой для остальных материалов. ## Чему учит Различать понятия стенда и понимать незнакомый термин без предварительного изучения устройства генератора. ## Проблема Сейчас определение часто сложнее самого термина: «ветвь дерева случайности», «день-функция», «единственный структурный шов модели». Читателю приходится разбирать несколько новых понятий ради одного. Общие понятия хранилища перемешаны с внутренними понятиями генератора. ## Работа Переработать `CONTEXT.md` как единый словарь проекта. Начать с понятий, которые нужны в учебной работе; подробности генератора сгруппировать так, чтобы они не мешали поиску. Не заводить второй словарь. Определение начинать с объяснения обычными словами; связь с кодом и ограничения давать следом. Добавлять короткий пример только там, где он проясняет различие. Проверить фактические утверждения. В частности, фраза о наполнении стартовыми данными «при каждом make up» должна различать первый запуск и повторный подъем сохраненного стенда. ## Критерии приемки - [x] По определению понятно, что означает термин; для понимания не требуется цепочка переходов к другим незнакомым определениям. - [x] Читатель может различить человека, посетителя с ClientID и пользователя магазина с user_id, а также модельное и реальное время. - [x] Понятия генератора отделены от основного пути чтения без второго конкурирующего словаря и без потери нужных определений. - [x] Описания первого и повторного запуска согласованы с кодом; названия из кода и значения терминов сохранены. - [x] Ссылки на словарь и его разделы, в том числе якорь «Язык», работают. ## Сначала прочитать `CONTEXT.md`, `docs/agents/domain.md`, `docs/handbook/README.md`, `docs/handbook/generator.md`, `docs/labs/README.md`. Для фактов запуска — `Makefile` и `dags/world_lifecycle.py`. Связанная задача о worker: https://git.dementev.space/ddmitry/clickstream-data-platform/issues/183 . Прочитать ее текущее описание и комментарии; не включать сюда массовое переименование по репозиторию. ## Проверка `git diff --check`; проверить входящие ссылки и якоря. Сверить определения с конкретными полями и командами в исходниках. Для редакторской правки запуск стенда не нужен. ## Общие границы Это продолжение редактуры материалов для начинающего инженера данных. Образцы языка — корневой README, главы `docs/handbook/` и задания `docs/labs/`. Писать простым русским языком; термины объяснять при первом употреблении. Не упрощать технический смысл и не подменять объяснение образными оборотами. Уже вычитанные лабораторные, handbook и карту не переписывать. Исторические спеки, ADR и внутренние инструкции не входят в задачу. Перед приемкой сделать проход на сокращение: убрать повторы и пояснения, которые не помогают пройти учебную программу. Имена объектов, технические условия и полезные примеры сохранить.

ddmitry added the ready-for-agent label 2026-09-13 20:32:35 +03:00

ddmitry self-assigned this 2026-09-13 20:43:31 +03:00

ddmitry referenced a pull request that will close this issue

2026-09-13 20:59:51 +03:00

docs(context): упрощен словарь понятий для начинающего #252

ddmitry closed this issue

2026-09-13 21:00:14 +03:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: ddmitry/clickstream-data-platform#248