# Agent System Instructions & Repository Guidelines

Этот репозиторий — учебный DWH-стенд (Airflow, Greenplum, Postgres) для начинающих Data инженеров. 

## 1. Главное правило генерации кода (Баланс)
Создаваемый код должен иметь учебную ценность: быть эталоном для "боевого" применения, но без избыточного усложнения (over-engineering).
- **Production-ready:** Учитывайте идемпотентность DAG'ов, транзакционность, отсутствие хардкода секретов.
- **KISS:** Не используйте сложные ООП-паттерны, метапрограммирование или избыточные абстракции, если задачу решает стандартный оператор (например, `PostgresOperator`).
- **Фокус на «Почему»:** При использовании специфичных паттернов DWH (например, `delete + insert` для инкремента в Greenplum вместо `merge`) — добавляйте краткий комментарий, объясняющий этот выбор студентам.

## 2. Карта проекта (Навигация для Агента)
- `airflow/dags/` — DAG-файлы (напр. `csv_to_greenplum.py`).
- `sql/` — DDL и SQL-скрипты. Разделены на слои: src/ (исходные системы), stg/ (стейджинг), ods/ (операционное хранилище), dds/ (детальное хранилище), dm/ (слой витрин).
  - *Правило ИИ:* DDL таблиц хранится строго рядом с объектом (напр. `sql/stg/bookings_ddl.sql`).
- `docs/internal/naming_conventions.md` — Единый источник истины для нейминга служебных и SCD-полей. *Правило ИИ: Всегда сверяться с этим файлом при генерации новых DDL/SQL.*
- `tests/` — pytest-тесты (smoke-тесты DAG'ов и юнит-тесты).
- `.env` — Настройки окружения (все секреты `GP_*`, `AIRFLOW_*` берем только отсюда).

## 3. Среда и Инструменты (Терминал)
Мы используем **uv** для управления зависимостями и **make** для автоматизации.
- *Запрещено* использовать `pip install --user`. Только `uv`.
- Если нужно запустить команду в терминале, используйте `uv run ...`
- Доступные Make-таргеты (агент может вызывать их для проверок):
  - `make fmt`, `make lint` — форматирование (`black`, `isort`) и линтинг кода.
  - `make test` — запуск `pytest`.
  - `make up` / `make stop` / `make down` — управление контейнерами docker-compose.
  - `make ddl-gp` — накат DDL на Greenplum.

## 4. Airflow + SQL Специфика
- В учебных DAG'ах основная логика выносится в SQL. По умолчанию используйте `PostgresOperator` + Airflow Connections (`sql='sql/stg/bookings_load.sql'`).
- Сложную работу с соединениями (например, `psycopg2` напрямую в Python) используйте только там, где реально много Python-логики и это служит учебной цели.

## 5. Стиль и Оформление
- **Язык:** Комментарии, docstrings, тексты ошибок — на **русском** языке. Ошибки должны быть дружелюбными и подсказывать студенту, что делать дальше.
- **Код:** Переменные, функции, SQL-идентификаторы (`snake_case`) — на английском.
- **Коммиты:** Придерживайтесь Conventional Commits (`feat:`, `fix:`, `docs:`, `refactor:`). Если меняется логика DAG'а, в описании PR (или коммита) указывайте, что именно изменилось.

## 6. Порядок работы Агента
1. Держите изменения минимальными и локальными. Избегайте глобальных рефакторингов.
2. Перед завершением задачи обязательно валидируйте код: выполните `uv run make fmt` и `uv run make test`.
3. При изменении схемы БД — обязательно обновите `sql/ddl_gp.sql`.