ddmitry/clickstream-data-platform
1
0 Fork 0
Code Issues 5 Pull Requests Actions Packages Projects 1 Releases Wiki Activity

Переезд операторских разделов README в справочники #212

New Issue
Closed
opened 2026-09-01 22:05:25 +03:00 by ddmitry · 1 comment
ddmitry commented 2026-09-01 22:05:25 +03:00
Owner
Copy link
Copy source

Part of #206

Цель

Операторские разделы корневого README переезжают в справочники
docs/architecture/, и у двух зон, которые до сих пор жили только в README,
появляются свои файлы. README на месте каждого переехавшего раздела
оставляет абзац-ссылку. Знания не теряются: у каждого куска есть адрес.
Раскладка принята резолюцией #211, здесь только переезд; пересборка README
по новой раскладке идет следующим тикетом.

Карта переезда

Строки указаны по README на коммите 2588515.

В docs/architecture/testing.md (уже существует): строки 74–123 «Быстрого
старта». Что делает make up и сколько стоит подъем; устройство смоука: зачем
повторять healthcheck'и, почему keeper и Kafka спрашивают отдельно; что
проверяют make check-services, make check-clickhouse и make config-test.
Сливать с разделами «Карта целей» и «Устройство скриптов», не дублировать: там,
где testing.md уже говорит то же, абзац README умирает, а не переезжает.

В docs/architecture/world.md (новый, «Мир и его пульт»): разделы
«Стартовый мир» (138–176), «Как позвать генератор» (178–244) и «Пульт мира»
(246–286). Зона файла: модельное время стенда со стороны оператора. Что
делает make up с миром, повторный подъем, опись мира и кто ее спрашивает;
цели make generate-*, таблица переменных, сборка образа, файловый приемник,
умолчания; даги пульта таблицей, world_position, форма запуска, сокет
докера. Где текст пересекается с orders/start-world.md, orders/inventory.md,
ADR 0009 и ADR 0013, ставится ссылка, а не пересказ.

В docs/architecture/stand.md (новый, «Стенд: службы, доступ,
настройка»): раздел «Состав и доступ» (288–400) целиком, кроме строк 302–310
с адресами и паролями интерфейсов: они остаются в README. Список служб,
пользователи и роли ClickHouse, пересоздание нод после правки настроек,
оговорка о ненастоящих секретах, отсутствие балансировщика, закрепление
версий Airflow и Superset. Ледгер «Конфигурация сверена 30 июля 2026 года»
со ссылками на документацию идет в раздел «Что проверено» по образцу
storage.md и testing.md.

Остается в README без правок: шапка, требования и команды «Быстрого
старта» (28–72, 125–136), адреса и пароли, «Статус», «Что здесь будет»,
«Чем отличается от предшественника», «Документация». Их судьба решена
резолюцией #211 и исполняется следующим тикетом.

Одна фраза в остающейся части смотрит на переехавший раздел: строка 64,
«кроме пульта мира — о нём ниже». После переезда «ниже» пульта нет; слово
заменяется ссылкой на world.md.

Форма новых файлов

Жанр docs/architecture/ по AGENTS.md: текущее устройство зоны, один файл на
зону, правится по мере постройки. У каждого нового файла зачин в два-три
предложения: за что отвечает файл и где живут доводы (ADR 0001 и 0007 для
stand.md, ADR 0009 и 0013 для world.md). Заголовки разделов ставит Fable в
брифе исполнителю до переноса текста: они задают, куда какой абзац ложится.

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

  • docs/architecture/stand.md и docs/architecture/world.md существуют,
    у каждого зачин о зоне и ссылки на ADR с доводами.
  • testing.md принял доводы смоука и описания целей; ни один факт не
    записан в нем дважды.
  • На месте каждого переехавшего раздела README стоит абзац со ссылкой
    на новый адрес; ни один абзац не потерян и не переписан по смыслу.
  • Адреса и пароли интерфейсов остались в README.
  • docs/handbook/README.md ссылается на world.md вместо якоря
    README#пульт-мира.
  • Все относительные ссылки затронутых файлов ведут на существующие
    файлы или разделы (команда ниже дает пустой вывод).
  • В переехавшем тексте тире и елочки не тронуты; в новом тексте «ё»
    не пишется (правило репозитория с 2026-08-26).
  • Новая проза (зачины, связки) прошла ai-text-lint и оптику
    литературного русского.

Границы

  • README не пересобирать: промо-блок, DBeaver, адресация читателя, удаление
    мертвых разделов идут следующим тикетом.
  • Смысл переехавшего текста не править: только сшивка и ссылки. Найденная
    по дороге неточность оформляется отдельным issue.
  • Главы путеводителя не писать, интерактивную карту не начинать.
  • Код, DDL, Makefile не трогать.

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

  • Резолюция #211 (комментарий) — принятая раскладка.
  • README.md целиком.
  • docs/architecture/testing.md, особенно «Карта целей» и «Устройство скриптов».
  • docs/architecture/storage.md, раздел «Что проверено» — образец ледгера.
  • docs/architecture/orders/start-world.md и orders/inventory.md — что о
    стартовом мире и описи уже сказано.
  • ADR 0009 и 0013 — доводы пульта и жизненного цикла мира.
  • AGENTS.md, раздел «Структура» — правило имен docs/architecture/.

Кто пишет

Структура файлов и заголовки — Fable в брифе. Перенос текста, сшивка,
правка ссылок — Codex. Зачины новых файлов и связующие абзацы — Sol.
Приемка — оркестратор: ai-text-lint, оптика литературного русского,
проверка ссылок своими глазами.

Проверка

Ссылки, из корня репозитория (пусто — все цели на месте):

for f in README.md docs/handbook/README.md docs/architecture/testing.md \
         docs/architecture/stand.md docs/architecture/world.md; do
  d=$(dirname "$f")
  grep -oE '\]\([^)]+\)' "$f" | sed -E 's/^\]\(//; s/\)$//; s/#.*$//' \
    | grep -vE '^(https?:|$)' | sort -u \
    | while read -r p; do [ -e "$d/$p" ] || echo "$f -> $p MISSING"; done
done

Пробельные ошибки в diff ловит make config-test; стенд не нужен.

Part of #206 ## Цель Операторские разделы корневого README переезжают в справочники docs/architecture/, и у двух зон, которые до сих пор жили только в README, появляются свои файлы. README на месте каждого переехавшего раздела оставляет абзац-ссылку. Знания не теряются: у каждого куска есть адрес. Раскладка принята резолюцией #211, здесь только переезд; пересборка README по новой раскладке идет следующим тикетом. ## Карта переезда Строки указаны по README на коммите 2588515. **В docs/architecture/testing.md** (уже существует): строки 74–123 «Быстрого старта». Что делает make up и сколько стоит подъем; устройство смоука: зачем повторять healthcheck'и, почему keeper и Kafka спрашивают отдельно; что проверяют make check-services, make check-clickhouse и make config-test. Сливать с разделами «Карта целей» и «Устройство скриптов», не дублировать: там, где testing.md уже говорит то же, абзац README умирает, а не переезжает. **В docs/architecture/world.md** (новый, «Мир и его пульт»): разделы «Стартовый мир» (138–176), «Как позвать генератор» (178–244) и «Пульт мира» (246–286). Зона файла: модельное время стенда со стороны оператора. Что делает make up с миром, повторный подъем, опись мира и кто ее спрашивает; цели make generate-*, таблица переменных, сборка образа, файловый приемник, умолчания; даги пульта таблицей, world_position, форма запуска, сокет докера. Где текст пересекается с orders/start-world.md, orders/inventory.md, ADR 0009 и ADR 0013, ставится ссылка, а не пересказ. **В docs/architecture/stand.md** (новый, «Стенд: службы, доступ, настройка»): раздел «Состав и доступ» (288–400) целиком, кроме строк 302–310 с адресами и паролями интерфейсов: они остаются в README. Список служб, пользователи и роли ClickHouse, пересоздание нод после правки настроек, оговорка о ненастоящих секретах, отсутствие балансировщика, закрепление версий Airflow и Superset. Ледгер «Конфигурация сверена 30 июля 2026 года» со ссылками на документацию идет в раздел «Что проверено» по образцу storage.md и testing.md. **Остается в README без правок**: шапка, требования и команды «Быстрого старта» (28–72, 125–136), адреса и пароли, «Статус», «Что здесь будет», «Чем отличается от предшественника», «Документация». Их судьба решена резолюцией #211 и исполняется следующим тикетом. Одна фраза в остающейся части смотрит на переехавший раздел: строка 64, «кроме пульта мира — о нём ниже». После переезда «ниже» пульта нет; слово заменяется ссылкой на world.md. ## Форма новых файлов Жанр docs/architecture/ по AGENTS.md: текущее устройство зоны, один файл на зону, правится по мере постройки. У каждого нового файла зачин в два-три предложения: за что отвечает файл и где живут доводы (ADR 0001 и 0007 для stand.md, ADR 0009 и 0013 для world.md). Заголовки разделов ставит Fable в брифе исполнителю до переноса текста: они задают, куда какой абзац ложится. ## Критерии приемки - [x] docs/architecture/stand.md и docs/architecture/world.md существуют, у каждого зачин о зоне и ссылки на ADR с доводами. - [x] testing.md принял доводы смоука и описания целей; ни один факт не записан в нем дважды. - [x] На месте каждого переехавшего раздела README стоит абзац со ссылкой на новый адрес; ни один абзац не потерян и не переписан по смыслу. - [x] Адреса и пароли интерфейсов остались в README. - [x] docs/handbook/README.md ссылается на world.md вместо якоря README#пульт-мира. - [x] Все относительные ссылки затронутых файлов ведут на существующие файлы или разделы (команда ниже дает пустой вывод). - [x] В переехавшем тексте тире и елочки не тронуты; в новом тексте «ё» не пишется (правило репозитория с 2026-08-26). - [x] Новая проза (зачины, связки) прошла ai-text-lint и оптику литературного русского. ## Границы - README не пересобирать: промо-блок, DBeaver, адресация читателя, удаление мертвых разделов идут следующим тикетом. - Смысл переехавшего текста не править: только сшивка и ссылки. Найденная по дороге неточность оформляется отдельным issue. - Главы путеводителя не писать, интерактивную карту не начинать. - Код, DDL, Makefile не трогать. ## Сначала прочитать - Резолюция #211 (комментарий) — принятая раскладка. - README.md целиком. - docs/architecture/testing.md, особенно «Карта целей» и «Устройство скриптов». - docs/architecture/storage.md, раздел «Что проверено» — образец ледгера. - docs/architecture/orders/start-world.md и orders/inventory.md — что о стартовом мире и описи уже сказано. - ADR 0009 и 0013 — доводы пульта и жизненного цикла мира. - AGENTS.md, раздел «Структура» — правило имен docs/architecture/. ## Кто пишет Структура файлов и заголовки — Fable в брифе. Перенос текста, сшивка, правка ссылок — Codex. Зачины новых файлов и связующие абзацы — Sol. Приемка — оркестратор: ai-text-lint, оптика литературного русского, проверка ссылок своими глазами. ## Проверка Ссылки, из корня репозитория (пусто — все цели на месте): for f in README.md docs/handbook/README.md docs/architecture/testing.md \ docs/architecture/stand.md docs/architecture/world.md; do d=$(dirname "$f") grep -oE '\]\([^)]+\)' "$f" | sed -E 's/^\]\(//; s/\)$//; s/#.*$//' \ | grep -vE '^(https?:|$)' | sort -u \ | while read -r p; do [ -e "$d/$p" ] || echo "$f -> $p MISSING"; done done Пробельные ошибки в diff ловит make config-test; стенд не нужен.
ddmitry added the wayfinder:task label 2026-09-01 22:06:09 +03:00
ddmitry self-assigned this 2026-09-01 22:21:34 +03:00
ddmitry commented 2026-09-01 22:50:43 +03:00
Author
Owner
Copy link
Copy source

Сделано в PR #213 (ждет слияния владельцем: слияние из сессии агента заблокировал классификатор авторежима).

Новые справочники. docs/architecture/stand.md — «Стенд: службы, доступ, настройка»: службы, пользователи и роли ClickHouse, применение настроек, ненастоящие секреты, одна реплика на шард, ледгер «Что проверено» с сверкой 30 июля 2026 года. docs/architecture/world.md — «Мир и его пульт»: стартовый мир, опись мира, как позвать генератор, пульт мира. Зачины ведут к ADR 0001/0007 и 0009/0013, world.md — еще к orders/start-world.md и orders/inventory.md.

testing.md. Абзац про make up встал в «Карту целей» рядом с ценой подъема; устройство смоука и глубоких проверок — двумя подразделами в «Устройстве скриптов». Умерли как дубли: фраза о том, что смоук спрашивает Docker про убитые контейнеры (уже есть в check_containers_survived), абзац про make config-test (целиком в таблице) и хвост абзаца про check-clickhouse о сверке с описью (уже есть в «Интеграционная проверка…»).

README. Заголовки переехавших разделов оставлены ради якорей, под каждым абзац-ссылка; адреса и пароли на месте; строка 64 ссылается на world.md#пульт-мира. Путеводитель и generator/README.md (не был в тикете, но ссылался на уезжающий раздел) ведут на world.md.

Ревью. Codex (gpt-5.6-sol) переносил и писал зачины, саморевью 1/1; слепое ревью Claude (craftsman): 0 блокеров, 4 minor, 4 nit — семь закрыто, одно отклонено (два замера цены make up в testing.md названы каждый со своими условиями). Внешнее ревью постановки пропущено: тикет — срез по принятой резолюции #211.

Хвосты следующему тикету (пересборка README). Раздел «Документация» не знает о stand.md и world.md; два соседних абзаца README ведут в testing.md. В переехавшем тексте оставлена как есть фраза «так генератор позовёт даг этапа 5» (world.md, «Как позвать генератор») — даги уже есть, фраза устарела; неточность не правилась по границам тикета.

Сделано в PR #213 (ждет слияния владельцем: слияние из сессии агента заблокировал классификатор авторежима). **Новые справочники.** `docs/architecture/stand.md` — «Стенд: службы, доступ, настройка»: службы, пользователи и роли ClickHouse, применение настроек, ненастоящие секреты, одна реплика на шард, ледгер «Что проверено» с сверкой 30 июля 2026 года. `docs/architecture/world.md` — «Мир и его пульт»: стартовый мир, опись мира, как позвать генератор, пульт мира. Зачины ведут к ADR 0001/0007 и 0009/0013, world.md — еще к `orders/start-world.md` и `orders/inventory.md`. **testing.md.** Абзац про `make up` встал в «Карту целей» рядом с ценой подъема; устройство смоука и глубоких проверок — двумя подразделами в «Устройстве скриптов». Умерли как дубли: фраза о том, что смоук спрашивает Docker про убитые контейнеры (уже есть в `check_containers_survived`), абзац про `make config-test` (целиком в таблице) и хвост абзаца про `check-clickhouse` о сверке с описью (уже есть в «Интеграционная проверка…»). **README.** Заголовки переехавших разделов оставлены ради якорей, под каждым абзац-ссылка; адреса и пароли на месте; строка 64 ссылается на `world.md#пульт-мира`. Путеводитель и `generator/README.md` (не был в тикете, но ссылался на уезжающий раздел) ведут на `world.md`. **Ревью.** Codex (gpt-5.6-sol) переносил и писал зачины, саморевью 1/1; слепое ревью Claude (craftsman): 0 блокеров, 4 minor, 4 nit — семь закрыто, одно отклонено (два замера цены `make up` в testing.md названы каждый со своими условиями). Внешнее ревью постановки пропущено: тикет — срез по принятой резолюции #211. **Хвосты следующему тикету (пересборка README).** Раздел «Документация» не знает о `stand.md` и `world.md`; два соседних абзаца README ведут в `testing.md`. В переехавшем тексте оставлена как есть фраза «так генератор позовёт даг этапа 5» (world.md, «Как позвать генератор») — даги уже есть, фраза устарела; неточность не правилась по границам тикета.
Sign in to join this conversation.
No Branch/Tag Specified
Labels
Clear labels
needs-info
needs-triage
ready-for-agent
ready-for-human
wayfinder:grilling
wayfinder:map
wayfinder:prototype
wayfinder:research
wayfinder:task
wontfix
No labels wayfinder:task
Milestone
No items
No Milestone
Projects
Clear projects
No projects
Assignees
Clear assignees
ddmitry (Dmitry Dementiev)
No Assignees ddmitry
1 Participants
Notifications
Due Date
No due date set.
Blocks
#214 Словарь справочников world.md и stand.md: термины и кальки
ddmitry/clickstream-data-platform
Reference: ddmitry/clickstream-data-platform#212