clickstream-data-platform/AGENTS.md

# AGENTS.md

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

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

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

Отсюда следует, кому что поручать. Читатель здесь — не побочный потребитель,
а тот, ради кого стенд существует: код, комментарии и документы и есть
продукт. Поэтому всё, что человек будет читать и разбирать, пишет модель с
чувством меры — по умолчанию Opus. Кодексу остаётся техническая работа без
вкусовых решений: миграции, разбор журналов и объёмного вывода, обход
репозитория, повторяющиеся правки; там его больши́е лимиты работают на нас.
Ревью идёт наоборот: разбор реализации на уместность ведёт Opus, а Кодекс
даёт независимое второе мнение другой родословной — линии ревью всегда
разных родословных, кто бы ни был исполнителем.

Разрез проходит не по задаче целиком, а по подзадачам, и намечается при
планировании: вкусовое — Опусу, руки — Кодексу. Сначала идёт вкусовая часть:
она задаёт форму, имена и границы, под которые механическая потом
подстраивается. Писатель в дереве в каждый момент один — либо
последовательно, либо по непересекающимся файлам.

Экономить лимиты на том, что читает человек, — ложная экономия: переписывать
выйдет дороже, чем сразу написать хорошо.

## Язык

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

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

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

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

- Python — только через `uv`.
- Изменения держать минимальными и в границах задания.
- Секреты не коммитить: настройки — через `.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

### 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/adr/` — `NNNN-краткое-имя.md`: сквозной номер из четырёх
  цифр и слаг (`0001-stand-services.md`). Решения нумеруются подряд, дата
  в имени не нужна.