Files

T

ddadmin acdbb8be3e 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

2026-02-28 14:53:09 +03:00

4.8 KiB

Raw Blame History

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. Порядок работы Агента

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

4.8 KiB Raw Blame History