Files

T

ddadminandClaude Opus 5 bbbe17cfb0 refactor(smoke): цели проверки по назначению — смоук, ClickHouse, службы

- Зачем:
  - смоук перестал быть быстрым: 42 секунды из 48 съедали шесть проверок,
    которые ждут службу — запуск DAG, вход в Superset, Kafka с машины.
  - имена целей врали: смоуком звались и глубокая проверка кластера, и
    интеграционные проверки; префикс достался им от общего происхождения.
  - нигде не было записано, зачем в репозитории каждая цель и куда класть
    новую проверку, — без записи скрипт дорастёт снова.
- Что:
  - ось деления — кого спрашивают, а не сколько стоит: make smoke (стенд
    собран), make check-clickhouse (спрашивают у ClickHouse), новая
    make check-services (службы работают).
  - шесть тяжёлых проверок переехали в scripts/stand-services.sh; общее —
    счёт, обращение к Compose, зависимости машины и check_containers_survived
    — вынесено в scripts/stand-common.sh, копипасты нет.
  - smoke-cluster переименована в check-clickhouse; имя файла скрипта не
    тронуто (в него встраивается проверка договора со схемой), расхождение
    названо в карте.
  - смоук и check-services печатают своё время в строке ИТОГ; порога по
    времени нет — по доводу ADR 0004.
  - docs/architecture/testing.md: карта всех семи целей, правило быстрого
    смоука словами, лесенка по частоте и правило про краснеющую проверку,
    переехавшее из README; указатель из AGENTS.md.
  - README: описания целей сокращены, карта не дублируется; быстрый старт
    показывает работающий стенд, а не только собранный.
  - планка приёмки этапа в спеке названа поимённо: три цели вместо
    «smoke-проверки».
- Проверка:
  - make config-test, make smoke (19 проверок, 6 с), make check-clickhouse
    (8 проверок, 7 с), make check-services (7 проверок, 44 с) — зелёные.
  - 19 + 7 = 25 разных проверок, как и до деления: check_containers_survived
    считается дважды намеренно.
  - краснеют обе разделённые цели: со снятым prometheus смоук дал три ошибки,
    с подменённым UUID подключения Superset покраснел check-services.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

2026-08-06 14:34:02 +03:00

10 KiB

Raw Blame History

AGENTS.md

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

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

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

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

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

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

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

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

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

Язык

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

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

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

Код и данные

Python — только через uv; проверка и формат — ruff (make lint).
Изменения держать минимальными и в границах задания.
Куда класть новую проверку, что утверждает каждая цель make и почему смоук обязан оставаться быстрым — 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/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.

Triage labels

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

Domain docs

Один контекст: CONTEXT.md в корне и docs/adr/. См. 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/adr/ — NNNN-краткое-имя.md: сквозной номер из четырёх цифр и слаг (0001-stand-services.md). Решения нумеруются подряд, дата в имени не нужна.
Имена файлов в docs/architecture/ — слаг строчными латинскими буквами через дефис (storage.md). Здесь живут рабочие справочники по зонам ответственности: не событие истории и не решение, а текущее устройство — один файл на зону, правится по мере постройки.

10 KiB Raw Blame History