diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..3d7d3c7
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,65 @@
+# AGENTS.md
+
+Инструкции для работы с репозиторием мини‑демо хранилища кликстрима.
+
+## Цель репозитория
+
+Развернуть в `docker compose` минимальный аналитический стек:
+
+- Kafka (источник событий, 1 JSON message = 1 event)
+- ClickHouse (STG → ODS → DDS → DM)
+- Superset (BI поверх витрин)
+- Prometheus + Grafana (мониторинг)
+- простой инструмент/скрипт, который читает `.jsonl` и пишет события в Kafka
+
+## Ключевые артефакты
+
+- `plans/clickhouse_ddl.md` — основной документ со схемой слоёв, DDL/MV и витринами DM.
+- `data/DE-task.md` — текст задания.
+- `data/*.jsonl` — исходные данные (могут быть грязными).
+- `configs/` — конфиги ClickHouse/Prometheus/Grafana (по мере развития).
+
+## Правила по данным (важно)
+
+- Не загружать исходные `*.jsonl` целиком: используйте `head -n 20..50`.
+- Для тестов/демо предпочтительнее “малый срез”, чем “идеальная полнота”.
+- Данные могут быть с ошибками — пайплайн должен быть устойчивым (в ODS фиксировать ошибки парсинга, а не падать).
+
+## Как запускать (локально)
+
+Базовые команды:
+
+- `docker compose up -d`
+- `docker compose ps`
+- `docker compose logs -f --tail=200 <service>`
+- `docker compose down -v` (удалит volumes; используйте осознанно)
+
+Порты (см. `docker-compose.yml`):
+
+- ClickHouse native: `localhost:8002`
+- ClickHouse HTTP: `localhost:9123`
+- Kafka: `localhost:9092`
+- Kafka UI: `http://localhost:8082`
+- Prometheus: `http://localhost:9090`
+- Grafana: `http://localhost:3000`
+
+## ClickHouse: применение DDL и загрузка сэмпла
+
+- DDL/пайплайн описаны в `plans/clickhouse_ddl.md`.
+- Для быстрой загрузки “первых N строк” используйте команды из раздела “Практические заметки для демо”.
+
+## Конвенции по изменениям
+
+- Держать изменения минимальными и по теме задания (инфра, схема, ingest, витрины).
+- Не коммитить секреты. Если требуется пароль/ключи — использовать `.env` и примеры `.env.example`.
+- README/планы обновлять вместе с изменениями инфраструктуры/DDL.
+
+## Быстрые проверки
+
+- Kafka ingest: наличие данных в `stg.*` и типизированных строк в `ods.*`.
+- Мониторинг: доступность `/metrics` у ClickHouse и скрейп в Prometheus.
+- BI: витрина `dm.v_events_enriched` должна отвечать за разумное время при фильтре по дате.
+
+## Примечания по текущему состоянию (если что-то “не встаёт”)
+
+Репозиторий развивается итеративно; если `docker compose` не стартует из‑за отсутствующих путей/сетей/сервисов, правьте аккуратно и фиксируйте это в `docker-compose.yml` и/или `configs/`.