ddmitry/clickstream-ch-kafka-superset-demo

Files

T

ddadmin 6c9d986114 docs(agents): контракт трекера переведён на Gitea и CLI tea

- Зачем:
  - GitHub-аккаунт заблокирован, работа идёт в Gitea на git.dementev.space,
    а инструкции для агентов всё ещё описывали GitHub Issues и gh.
- Что:
  - docs/agents/issue-tracker.md переписан под Gitea и tea 0.15.0: установка,
    вход, скоупы токена, обход прокси, команды для issues/комментариев/меток;
  - блокировки переведены на нативные зависимости Gitea через tea api,
    текстовые строки Blocked by из тел тикетов убраны;
  - GitHub ушёл одной строкой в раздел «Архив»;
  - docs/agents/triage-labels.md и блок «Agent skills» в AGENTS.md
    переобвязаны на Gitea.
- Проверка:
  - tea issues list, tea labels list — читают трекер;
  - граф блокировок карты #10 собран заново и прочитан обратно через
    tea api repos/{owner}/{repo}/issues/<n>/dependencies.

2026-07-29 21:32:05 +03:00

6.1 KiB

Raw Permalink Blame History

AGENTS.md

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

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

Данный проект - учебный для менти. Учебная ценность разработок - одна из его базовых ценностей.

Обязательные правила

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

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

Внутренние рассуждения и промежуточные пометки по ходу работы веди на английском — он экономнее по токенам (кириллица занимает примерно в 1,5–2 раза больше). На русском остаётся всё, что видит и хранит проект: итоговые ответы пользователю, документы, комментарии в коде и сообщения коммитов.

Для работы с python использовать uv.

Данные

Не загружать *.jsonl целиком без необходимости: по умолчанию использовать малый срез (head -n 20..50).
Для демо и тестов важнее быстрый и повторяемый прогон, чем полнота данных.
"Грязные" записи не должны валить пайплайн: ошибки парсинга фиксируются в ODS.

Изменения в коде

Изменения держать минимальными и в скоупе задания (инфра, ingest, трансформации, витрины, мониторинг).
Не коммитить секреты. Использовать .env и .env.example.
При изменении инфраструктуры или DDL обновлять документацию в этом же PR.
Комментарии в SQL и Bash писать на русском языке.

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

Для спорных или меняющихся API (особенно Airflow/operators/providers) сначала уточнять актуальную версию через MCP Context7.
Минимальный порядок: resolve-library-id -> query-docs.
Принятое решение фиксировать в коде и/или документации (кратко: что проверили и почему выбрали именно этот вариант).

Agent skills

Конфигурация для инженерных скиллов (набор Matt Pocock). Подробности — в docs/agents/.

Issue tracker

Gitea на git.dementev.space (через CLI tea). Спека фичи — файлом в docs/specs/ (источник истины), корневой issue — тонкий, со ссылкой на спеку и чек-листом дочерних issues. См. docs/agents/issue-tracker.md.

Triage labels

Пять канонических ролей как метки Gitea, имена совпадают (needs-triage, needs-info, ready-for-agent, ready-for-human, wontfix). См. docs/agents/triage-labels.md.

Domain docs

Single-context: CONTEXT.md и docs/adr/ в корне репозитория. См. docs/agents/domain.md.

Навигация по документации

README.md — пользовательский quick start и обзор.
docs/REPO_MAP.md — карта исполняемых артефактов и где что менять.
docs/OPERATIONS.md — запуск, DAG-параметры, проверки и troubleshooting.
docs/ARCHITECTURE.md — детали по слоям STG/ODS/DDS/DM.
docs/COMMIT_RULES.md — правила оформления коммитов.
docs/course/ — продвинутый учебный курс «со звёздочкой» на базе стенда (PRD, план обучения, стандарт уроков); начинать с docs/course/README.md.
plans/ — legacy-планы (использовать как исторический контекст, не как источник истины).
.scratch/handoffs/YYYYMMDD-HHMM-<slug>.md — handoff'ы для продолжения работы в новой сессии (одноразовые, коммитятся, уборка best-effort; скилл handoff пишет сюда). См. docs/adr/0003-handoffs-in-scratch.md.

Ограничения по структуре

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

6.1 KiB Raw Permalink Blame History