Files

T

Dmitry Dementiev 8046e543d0 chore(repo): заложен репозиторий v2 — контракт, спека, исследование

- Зачем:
  - спека «Боевой реализм стенда» исполняется в новом репозитории:
    предшественник замораживается как стабильный учебный стенд,
    v2 стартует пустым и переносит только нужное
- Что:
  - README: что это, статус «строится по спеке», ссылки на спеку и на
    репозиторий-предшественник
  - AGENTS.md написан заново, а не скопирован: язык, uv, обязательная
    проверка API через MCP Context7, контракт трекера Gitea (спека —
    источник истины, корневой issue тонкий), метки триажа, новые доки в docs/
  - .gitignore: Python и uv, .env, секреты, IDE, логи
  - docs/specs/2026-07-30-stand-v2-realism.md перенесена из v1; содержание
    не менялось, поправлены только ссылки: добавлена строка о переезде,
    ссылка на generator-realism.md переведена на абсолютный URL v1
  - docs/research/2026-07-26-yandex-clickstream-format.md перенесено:
    источник истины по формату широкого события
  - лицензии у предшественника нет, переносить нечего
- Проверка:
  - git show --stat: 5 файлов
  - относительные ссылки спеки ведут на существующие файлы репозитория

2026-07-30 15:47:55 +03:00

4.8 KiB

Raw Blame History

AGENTS.md

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

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

Проект учебный: учебная ценность разработок — одна из его базовых ценностей. Стенд строится по спеке «Боевой реализм стенда (v2)».

Язык

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

Структура

Новые документы — в docs/ или в профильных подпапках, не в корне.
Состав доков v2 определяется по ходу этапов, набор предшественника не копируется (спека, раздел 12).

4.8 KiB Raw Blame History