docs(agents): добавлен гайд по программному тестированию DAG

- Зачем:
  - AI-агенты пытались тестировать DAG через браузер вместо CLI/API,
    так как не было явных инструкций по программному подходу.
- Что:
  - добавлен docs/agent-dag-testing.md: CLI, REST API Airflow,
    проверка параллельности, запросы в Greenplum, E2E-тест, шпаргалка команд.
  - в AGENTS.md добавлена ссылка на новый гайд в раздел «Тестирование».
  - из docs/README.md убрана ссылка (файл для людей, не для агентов).
- Проверка:
  - cat docs/agent-dag-testing.md && grep agent-dag-testing AGENTS.md

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

AGENTS.md

@@ -35,7 +35,41 @@
 - **Код:** Переменные, функции, 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`.
+### Структура и нейминг 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` (пошаговый чек‑лист для студентов).
+- Для программной проверки DAG (без браузера) — см. `docs/agent-dag-testing.md`: CLI, REST API, проверка параллельности, запросы в Greenplum.
+
+## 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`.