Перейти к содержанию

Банк few-shot примеров для ИИ-ассистентов (Few-Shot Bank)

Этот каталог содержит эталонные примеры («Как надо») и антипаттерны («Как не надо») написания кода для проекта chutils. Эти примеры служат контекстом (few-shot prompting) для ИИ-ассистентов (например, Antigravity, Gemini CLI, Claude), помогая им мгновенно понимать архитектурные стандарты, соглашения по кодированию и правила безопасности проекта.

Структура каталога

Каждый кейс в банке примеров выделен в отдельную папку и состоит из трех обязательных компонентов:

  1. good_pattern.py — эталонный, идиоматичный код. Демонстрирует правильное использование модулей chutils, строгую типизацию, обработку исключений и правильное документирование.
  2. bad_pattern.py — код, содержащий распространенные ошибки проектирования, уязвимости, нарушение SOLID/DRY или небезопасное использование стандартных альтернатив.
  3. README.md — текстовое пояснение, описывающее разницу между паттернами, архитектурные трейдоффы, обоснование выбора подходов и рекомендации для ИИ.

Доступные паттерны

На данный момент в банке представлены следующие архитектурные примеры:

  • Обработка ошибок и исключения (error_handling) — правила создания кастомных исключений, предотвращение перехвата широких исключений (except Exception) и сохранение контекста ошибок.
  • Управление конфигурацией (configuration) — корректный маппинг настроек с валидацией через Pydantic-модели и многоуровневое слияние конфигураций вместо захардкоженных переменных окружения.
  • Практики логирования (logging) — использование структурированного логирования, настройка асинхронного вывода и маскирование персональных данных (PII) и секретов.
  • Управление секретами (secrets) — безопасное получение секретов через SecretManager со строгим режимом required=True и SecretNotFoundError вместо os.getenv (добавлено в v3.0.0).
  • Опциональные зависимости (optional_deps) — правильный перехват OptionalDependencyError (v3.0.0+) вместо устаревшего RuntimeError; использование e.hint для вывода команды установки; стратегии graceful degradation vs fail-fast (ломающее изменение v3.0.0).

Инструкция по добавлению новых примеров (Шаблон)

Если вы хотите добавить новый пример в банк, следуйте этой инструкции:

1. Создайте структуру директории

Создайте поддиректорию под вашу архитектурную тему:

docs/ai_examples/my_feature/
├── README.md
├── good_pattern.py
└── bad_pattern.py

2. Подготовьте bad_pattern.py

Напишите неидиоматичный код. Добавьте в docstring на уровне модуля краткое пояснение, какие антипаттерны здесь представлены. Ограничивайте размер кода (не более 30-50 строк), чтобы не перегружать контекст ИИ.

3. Подготовьте good_pattern.py

Напишите чистую реализацию той же задачи:

  • Используйте инструменты chutils (если применимо).
  • Соблюдайте строгую типизацию (Zero-Any Strategy).
  • Документируйте функции по стандарту Google Style (Args/Returns).
  • Добавьте поясняющие docstrings.

4. Напишите README.md

В файле README.md используйте следующую структуру:

  • Описание кейса: Какую задачу мы решаем.
  • Антипаттерны: Почему код в bad_pattern.py плох.
  • Решение: Почему код в good_pattern.py предпочтителен.
  • Трейдоффы: Какие компромиссы были сделаны (например, производительность vs читаемость).
  • Ключевой совет для ИИ: Четкое резюме одной фразой.