ddmitry/clickstream-ch-kafka-superset-demo

Files

T

ddadmin 03de68e0c5 docs(docs): slim down AGENTS and split runbook sections

- Why:\n  - AGENTS.md became too large and mixed policy with operational details\n  - context7 requirement was easy to miss in long text\n- What:\n  - reduce AGENTS.md to a compact contributor contract\n  - add explicit mandatory MCP Context7 workflow block\n  - move runbook details to docs/OPERATIONS.md\n  - move artifact map to docs/REPO_MAP.md\n- Check:\n  - reviewed links and content after split\n  - ensured only documentation files are included in commit

2026-02-08 20:23:42 +03:00

3.0 KiB

Raw Blame History

AGENTS.md

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

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

Реализовать тестовое задание DE: поднять в docker compose стек Kafka + ClickHouse + Airflow + Superset + Prometheus/Grafana и получить витрины для первичного анализа.

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

Данные

Не загружать *.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.
Принятое решение фиксировать в коде и/или документации (кратко: что проверили и почему выбрали именно этот вариант).

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

README.md — пользовательский quick start и обзор.
docs/REPO_MAP.md — карта исполняемых артефактов и где что менять.
docs/OPERATIONS.md — запуск, DAG-параметры, проверки и troubleshooting.
docs/ARCHITECTURE.md — детали по слоям STG/ODS/DDS/DM.
docs/COMMIT_RULES.md — правила оформления коммитов.
plans/ — legacy-планы (использовать как исторический контекст, не как источник истины).

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

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

3.0 KiB Raw Blame History