ddadmin
acdbb8be3e
- Зачем: - документ разросся и стал неструктурированным; нужно выделить ключевое правило про баланс 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
42 lines
4.8 KiB
Markdown
42 lines
4.8 KiB
Markdown
# 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`.
|