docs(agents): реструктуризация инструкций, добавлено правило баланса сложности

- Зачем:
  - документ разросся и стал неструктурированным; нужно выделить ключевое правило про баланс production-ready и KISS для начинающих Data инженеров.
- Что:
  - реструктуризация: введена нумерация разделов (1-6), удалены дублирующиеся детали команд и стиля кода.
  - добавлен раздел 1 "Главное правило генерации кода (Баланс)" с принципами Production-ready, KISS и Фокус на «Почему».
  - расширена карта проекта: добавлены все слои DWH (src/, stg/, ods/, dds/, dm/) и naming conventions.
  - добавлен раздел 6 "Порядок работы Агента" с чек-листом валидации.
- Проверка:
  - cat AGENTS.md && git log -1

AGENTS.md

@@ -1,75 +1,41 @@
-# Repository Guidelines (для агентa и контрибьюторов)
+# Agent System Instructions & Repository Guidelines
 
-Эта репа — учебный стенд для студентов (менти), которые только начинают с Airflow/Greenplum и Python. Пожалуйста, держите решения простыми, стабильными и хорошо объяснёнными.
+Этот репозиторий — учебный DWH-стенд (Airflow, Greenplum, Postgres) для начинающих Data инженеров. 
 
-## Структура проекта
-- `airflow/dags/` — DAG-файлы (например, `csv_to_greenplum.py`, `csv_to_greenplum_dq.py`).
-- `airflow/requirements.txt` — зависимости, которые ставятся внутри контейнеров Airflow.
-- `sql/` — DDL и вспомогательные SQL (например, `sql/ddl_gp.sql`).
-- `docker-compose.yml` — Greenplum, Airflow, Postgres (мета-БД).
-- `Makefile` — удобные команды для локальной работы.
-- `.env(.example)` — настройки окружения (реальные секреты не коммитим).
+## 1. Главное правило генерации кода (Баланс)
+Создаваемый код должен иметь учебную ценность: быть эталоном для "боевого" применения, но без избыточного усложнения (over-engineering).
+- **Production-ready:** Учитывайте идемпотентность DAG'ов, транзакционность, отсутствие хардкода секретов.
+- **KISS:** Не используйте сложные ООП-паттерны, метапрограммирование или избыточные абстракции, если задачу решает стандартный оператор (например, `PostgresOperator`).
+- **Фокус на «Почему»:** При использовании специфичных паттернов DWH (например, `delete + insert` для инкремента в Greenplum вместо `merge`) — добавляйте краткий комментарий, объясняющий этот выбор студентам.
 
-## Команды (основные)
-- `make up` — поднять весь стек (Airflow инициализируется автоматически при первом старте).
-- `make stop` — остановить контейнеры, не трогая данные.
-- `make down` — остановить и удалить контейнеры/сети (тома сохраняются).
-- `make clean` — полный reset: остановить и удалить контейнеры/сети и тома (все данные будут потеряны).
-- `make airflow-init` — вручную переинициализировать мета-БД Airflow и создать пользователя (обычно не нужно).
-- `make logs` — логи webserver и scheduler.
-- `make ddl-gp` — применить DDL к Greenplum.
-- `make gp-psql` — открыть `psql` в контейнере Greenplum от `gpadmin`.
+## 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_*` берем только отсюда).
 
-Пример: `make up`, затем открыть `http://localhost:8080`.
+## 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.
 
-## Локальное Python‑окружение
-- Используем `uv`: достаточно `uv sync` (или `make dev-sync`) — подтянет Python, создаст `.venv`, установит зависимости.
-- `make dev-setup` полезен при смене версии Python (выполнит `uv python install` + `uv python pin` перед `uv sync`).
-- Проверки: `make test`, `make lint`, `make fmt` (выполняются через `uv run`).
-- Не используем `pip install --user`; если что‑то попало в user‑site — удалить `pip uninstall <package>` и проверить `pip list --user`.
-- В IDE выбираем интерпретатор из `.venv`.
+## 4. Airflow + SQL Специфика
+- В учебных DAG'ах основная логика выносится в SQL. По умолчанию используйте `PostgresOperator` + Airflow Connections (`sql='sql/stg/bookings_load.sql'`).
+- Сложную работу с соединениями (например, `psycopg2` напрямую в Python) используйте только там, где реально много Python-логики и это служит учебной цели.
 
-## Стиль кода
-- Python: PEP 8, 4 пробела, `snake_case`; `dag_id` — `lower_snake_case`.
-- Импорты: stdlib → third‑party → local, по одному модулю в строке.
-- SQL: ключевые слова UPPERCASE, идентификаторы `snake_case`, завершаем `;`.
-- Форматирование: `black` (88 cols) и `isort`. Если не уверены — запустите `make fmt`.
-- Язык: комментарии, docstring и документацию — на русском; имена идентификаторов — на английском.
+## 5. Стиль и Оформление
+- **Язык:** Комментарии, docstrings, тексты ошибок — на **русском** языке. Ошибки должны быть дружелюбными и подсказывать студенту, что делать дальше.
+- **Код:** Переменные, функции, SQL-идентификаторы (`snake_case`) — на английском.
+- **Коммиты:** Придерживайтесь Conventional Commits (`feat:`, `fix:`, `docs:`, `refactor:`). Если меняется логика DAG'а, в описании PR (или коммита) указывайте, что именно изменилось.
 
-### Структура и нейминг SQL (слои DWH)
-- В каталоге `sql/` придерживаемся слоёв DWH:
-  - `sql/src/` — скрипты, работающие с исходными системами (например, `bookings_generate_day_if_missing.sql`);
-  - `sql/stg/` — скрипты для стейджинга (`bookings_ddl.sql`, `bookings_load.sql`, `bookings_dq.sql`);
-  - в будущем можно добавить `sql/ods/`, `sql/dds/`, `sql/dm/` по мере роста стенда.
-- Именование файлов: `{объект}_{роль}.sql`, где:
-  - `объект` — логическое имя сущности (`bookings`, `orders`, и т.п.);
-  - `роль` — `ddl` (создание/изменение объектов), `load` (загрузка/инкремент), `dq` (проверки качества данных) и т.п.
-- Общие DDL-скрипты (например, `sql/ddl_gp.sql`) могут подключать файловые DDL через `\i`, но сами определения таблиц живут рядом с объектом (`sql/stg/bookings_ddl.sql` и т.п.).
-
-### Airflow + SQL
-- В учебных DAG’ах, где основная логика — в SQL, по умолчанию используем `PostgresOperator` + Airflow Connections:
-  - DAG оркестрирует шаги и подключение к БД;
-  - SQL-скрипты лежат в `sql/...` и подключаются по пути (`sql='sql/stg/bookings_load.sql'`).
-- Сложную ручную работу с подключениями (`psycopg2`, ENV-фоллбеки) используем только там, где реально много Python-логики и это помогает учебной цели.
-
-## Тестирование
-- Тесты лежат в `tests/` (pytest). Запуск: `make test`.
-- Есть юнит‑тесты для `helpers/greenplum.py` и smoke‑тесты DAG‑структуры (`tests/test_dags_smoke.py`).
-- Smoke‑тесты DAG автоматически пропускаются, если Airflow не установлен в venv.
-- Для ручного прогона стенда см. `TESTING.md` (пошаговый чек‑лист для студентов).
-
-## Pull Requests
-- Conventional Commits: `feat:`, `fix:`, `docs:`, `chore:`, `refactor:`. Пример: `feat(dags): load orders to Greenplum`.
-- Держите изменения минимальными и локальными. Не переименовывайте Make‑таргеты без обновления документации.
-- В описании PR добавляйте скрин DAG‑графа или логи задач, если менялась логика.
-- При изменении схемы/поведения — обновляйте `README.md` и `sql/ddl_gp.sql`.
-
-## Безопасность и конфигурация
-- Все настройки — через `.env`; креды в коде не хардкодим. Частые переменные: `GP_*`, `PG_*`, `AIRFLOW_*`, `CSV_*`.
-- `make clean` удаляет тома — предупреждайте студентов, что данные пропадут.
-
-## Для агента (особенности аудитории)
-- Пишите простыми словами. Добавляйте короткие комментарии к нетривиальной логике.
-- Избегайте больших рефакторингов и сложных паттернов — студенты только начинают.
-- Ошибки и логи — дружелюбные и понятные (лучше с подсказкой «что сделать дальше»).
-- Перед релевантными правками валидируйте локально: `make up`, затем откройте DAG в UI и/или прогоните `make test`.
+## 6. Порядок работы Агента
+1. Держите изменения минимальными и локальными. Избегайте глобальных рефакторингов.
+2. Перед завершением задачи обязательно валидируйте код: выполните `uv run make fmt` и `uv run make test`.
+3. При изменении схемы БД — обязательно обновите `sql/ddl_gp.sql`.