clickstream-data-platform/AGENTS.md

# AGENTS.md

Короткий контракт для работы в репозитории учебной дата-платформы кликстрима.

## Цель репозитория

Проект учебный: учебная ценность разработок — одна из его базовых ценностей.
Стенд строится по спеке
[«Боевой реализм стенда (v2)»](docs/specs/2026-07-30-stand-v2-realism.md).

Стенд рассчитан на начинающих инженеров данных. Они недавно изучили ClickHouse,
но почти не работали с ним руками. Здесь они разбирают и достраивают хранилище
небольшого интернет-магазина: проходят путь от загрузки данных до витрин и BI.
Программа дает практику общепринятых инженерных приемов. После нее участники
должны уметь построить похожее хранилище без готового образца. Состав и порядок
работы задает [программа учебных заданий](docs/specs/2026-09-01-labs-program.md).

Стенд существует только ради обучения. Его поддержка имеет смысл, когда
сохраняет возможность пройти программу или сама становится учебной задачей.
Отдельной эксплуатационной ценности у стенда нет.

Отсюда вопрос к любой доработке — коду, проверке, документу: **чему она
учит?** Ответ называется одной фразой до того, как писать. Не
складывается фраза — это вопрос владельцу, а не строчка кода: проверки в этом
репозитории однажды уже переросли продукт.

**Усложнение не бесплатно, и платит за него учебная ценность.** Чем сложнее
стенд, тем хуже он как учебный материал: внимание читателя конечно, и каждая
конструкция, которую он обязан расшифровать по дороге к уроку, списывается с
этого счёта. Поэтому вопрос выше имеет вторую половину: **что читатель платит,
чтобы это прочесть, и что получает взамен?** Ответ «вопрос — и ничего»
означает, что писать не нужно.

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

Ревью само по себе умеет только прибавлять: каждая находка просится в правку,
и за прогон их набираются десятки. Поэтому перед приёмкой заметной работы
идёт отдельный **проход на вычитание** — с правом только резать и с явным
списком неприкосновенного. Сомнение «резать или нет» решается в пользу
реза: вещь, которая себя не защитила, себя не защитила.

## Кому что поручать

Автор задачи сам пишет и редактирует код, комментарии и документы, если
владелец не задал другое распределение работы.

Делить работу стоит не целыми задачами, а подзадачами, и решать
это при планировании. Вкусовая часть идёт первой: она задаёт форму, имена и
границы, под которые механическая потом подстраивается.

Ревью держит две линии, и назначаются они по разным основаниям. Линию
дефектов ведёт тот, кто код не писал: здесь работает различие — разные
родословные промахиваются по-разному. Линию уместности назначает не
различие, а умение: её ведёт модель со вкусом, даже если она же писала код.
Отдать её «второму исполнителю» ради независимости заманчиво, но модель без
вкуса на этой линии бесполезна.

Плата у такого решения есть: общая слепота автора и ревьюера одной
родословной проходит дважды. Гасится она свежей сессией без общего контекста
и явно другой линзой, но не до конца — поэтому там, где цена ошибки этого не
терпит, линию уместности берёт третья модель.

## Язык

Пиши на ясном русском языке. Иностранные слова оставляй только там, где у
термина нет устоявшегося русского аналога: имена технологий (Kafka, ClickHouse,
Airflow) и названия из кода. Если для понятия есть обычное русское слово —
используй его, не выдумывай транслитерации.

Документы и комментарии держи короткими и понятными читателю, который их не
писал: простые слова, короткие фразы, сложную мысль поясняй при первом
упоминании. Если понятность и буквальная точность спорят — выбирай понятность.

При создании или редактировании лабораторных следуй
[правилам учебного текста](docs/specs/2026-09-01-labs-program.md#как-писать-задания).

Внутренние рассуждения и промежуточные пометки по ходу работы веди на
английском — он экономнее по токенам. На русском остаётся всё, что видит и
хранит проект: итоговые ответы, документы, комментарии в коде и SQL, сообщения
коммитов.

## Код и данные

- Python — только через `uv`; проверка и формат — `ruff`. Цель `make lint`
  есть за двумя дверями и охватывает разное: в корне — код стенда, в
  `generator/` — код генератора. Правишь даги или Superset — зови корневую,
  правишь генератор — зови из `generator/`.
- Изменения держать минимальными и в границах задания.
- `make clean` полностью удаляет постоянное состояние стенда. Перед этой
  командой назови состояние вне прикладного мира, которое требуется удалить,
  и объясни, почему `make rebuild-storage` его не удаляет. При изменении DDL
  или проверке на чистых данных по умолчанию используй адресную очистку либо
  `make rebuild-storage`.
- Куда класть новую проверку, что утверждает каждая цель `make` и почему смоук
  обязан оставаться быстрым — [`docs/architecture/testing.md`](docs/architecture/testing.md).
- Секреты не коммитить: настройки — через `.env`, образец — `.env.example`.
- При изменении инфраструктуры или DDL обновлять документацию тем же PR.
- Коммиты — Conventional Commits: заголовок `type(scope): результат`, тело на
  русском по схеме Зачем / Что / Проверка.
- «Грязные» записи не должны валить пайплайн: ошибки разбора уходят в таблицы
  `*_errors`.
- Данные не читать целиком без необходимости: по умолчанию малый срез. Для
  демо и тестов быстрый повторяемый прогон важнее полноты данных.

## Проверка API через MCP Context7 (обязательно)

Для спорных или меняющихся API (Airflow и провайдеры, DDL ClickHouse) сначала
уточнять актуальную версию: `resolve-library-id` -> `query-docs`. Принятое
решение кратко фиксировать в коде или документации: что проверили и почему
выбрали этот вариант.

## Задачи

Трекер — Gitea на `git.dementev.space`, работа через CLI `tea` (логин по
умолчанию настроен, репозиторий определяется по git remote). Команды и
подводные камни — в [`docs/agents/issue-tracker.md`](docs/agents/issue-tracker.md).

- Спека фичи — файл в `docs/specs/`, источник истины, версионируется с кодом.
- Корневой issue фичи — тонкий: ссылка на спеку и чек-лист дочерних issues
  (`- [ ] #NN`). Содержание спеки в issue не дублируется.
- Дочерние issues — самодостаточные постановки: цель, критерии приёмки
  чекбоксами, границы, «сначала прочитать», команды проверки.
- Итоговые решения переносятся в спеку или ADR тем же PR.
- Метки триажа — пять ролей: `needs-triage`, `needs-info`, `ready-for-agent`,
  `ready-for-human`, `wontfix`. Карта и её тикеты — метки `wayfinder:*`.

## Agent skills

### Развилки решений

Существенные развилки — в грилинге, на тикетах wayfinder-карт и вне их —
вести через скилл `brainstorm-with-docs`: сначала веер вариантов, потом
конвергенция. Состав веера и запись отклонённых вариантов — в самом скилле.

### Issue tracker

Задачи — в Gitea на `git.dementev.space`, все операции через CLI `tea`.
См. [`docs/agents/issue-tracker.md`](docs/agents/issue-tracker.md).

### Triage labels

Пять канонических меток триажа без переименований, уже заведены в трекере.
См. [`docs/agents/triage-labels.md`](docs/agents/triage-labels.md).

### Domain docs

Один контекст: `CONTEXT.md` в корне и `docs/adr/`.
См. [`docs/agents/domain.md`](docs/agents/domain.md).

## Структура

- Новые документы — в `docs/` или в профильных подпапках, не в корне.
- Состав доков v2 определяется по ходу этапов, набор предшественника не
  копируется (спека, раздел 12).
- Имена файлов в `docs/specs/` и `docs/research/` — `ГГГГ-ММ-ДД-краткое-имя.md`:
  дата создания документа и слаг строчными латинскими буквами через дефис
  (`2026-07-30-stand-v2-realism.md`). Дата фиксирует, когда документ появился,
  и при правках не меняется: файлы сортируются по времени, а история живёт
  в git.
- Имена файлов в `docs/formats/` — слаг строчными латинскими буквами через
  дефис (`clickstream-event.md`). Ни даты, ни номера: документ не событие
  истории, а текущее описание живого формата — и собирается из кода, а не
  пишется руками.
- Имена файлов основной программы в `docs/labs/` — `S-N-slug.md`:
  номер ступени, номер задания внутри ступени и слаг строчными латинскими
  буквами через дефис (`1-2-top-pages-daily.md`). Здесь живут ТЗ
  учебных заданий. Номера повторяют порядок программы из `README.md`, чтобы
  папка читалась как оглавление; даты нет: задание — живой документ и
  правится вместе с тем, о чем говорит. Слаг называет предмет задания.
  Факультативы живут в `docs/labs/optional/`, без номеров, под одним слагом
  (`superset-dashboard.md`). Общий индекс обеих частей — `docs/labs/README.md`;
  отдельного индекса в `optional/` нет.
- Имена файлов в `docs/handbook/` — слаг строчными латинскими буквами через
  дефис, индекс папки — `README.md`. Здесь живет путеводитель по стенду:
  учебные главы для читателя. Ни дат, ни номеров: глава — живой документ и
  правится вместе с тем, что описывает. Исходники интерактивной карты лежат
  подпапкой `architecture-map/`, а ее рендер — файлом `architecture-map.html`
  рядом с главами.
- Имена файлов в `docs/adr/` — `NNNN-краткое-имя.md`: сквозной номер из четырёх
  цифр и слаг (`0001-stand-services.md`). Решения нумеруются подряд, дата
  в имени не нужна.
- Имена файлов в `docs/architecture/` — слаг строчными латинскими буквами через
  дефис (`storage.md`). Здесь живут рабочие справочники по зонам
  ответственности: не событие истории и не решение, а текущее устройство —
  один файл на зону, правится по мере постройки. Крупный компонент живёт
  подпапкой: индекс `README.md` и файл на каждую часть устройства
  (`architecture/orders/`), имена по тому же правилу
  ([ADR 0011](docs/adr/0011-component-docs.md)).