Правило «Один-Три-Один»

Брифы 1-3-1: проблема, три варианта, один выбор.

Метаданные навыка

Справочник: полный SKILL.md

1-3-1 Communication Rule

Формат принятия решений для ситуаций, когда у задачи несколько жизнеспособных подходов и пользователю нужна чёткая рекомендация. Даёт сжатую формулировку проблемы, три варианта с компромиссами и конкретный план для рекомендованного пути.

Когда использовать

• Пользователь явно просит ответ в формате «1-3-1».
• Пользователь говорит «дай варианты» или «какие у меня есть пути» для технического решения.
• У задачи несколько жизнеспособных подходов со значимыми компромиссами (архитектура, инструментарий, стратегия миграции).
• Пользователю нужно предложение, которое можно передать команде или стейкхолдерам.

Не применять для простых вопросов с одним очевидным ответом, отладочных сессий и задач, где пользователь уже определился с подходом.

Процедура

1. Проблема (одно предложение)

   • Сформулируй суть решения или желаемый результат одним кратким предложением.
   • Фокус на что, не на как — без деталей реализации, названий инструментов и конкретных технологий.
   • Будь лаконичен. Если нужен союз «и» — скорее всего, описываешь две разные проблемы.

2. Варианты (ровно три)

   • Предложи три самостоятельных, жизнеспособных подхода с метками A, B, C.
   • Каждый вариант — краткое описание, плюсы и минусы.
   • Варианты должны представлять принципиально разные стратегии, а не мелкие вариации одного подхода.

3. Рекомендация (один вариант)

   • Укажи, какой вариант рекомендуешь и почему, опираясь на контекст и приоритеты пользователя.
   • Говори прямо — это профессиональное суждение, а не страховочная оговорка.

4. Критерии готовности

   • Перечисли конкретные критерии успеха для рекомендованного варианта.
   • Проверяемые, конкретные результаты — не расплывчатые пожелания.
   • Если пользователь выбирает другой вариант — пересмотри этот раздел соответственно.

5. План реализации

   • Конкретные шаги для выполнения рекомендованного варианта.
   • Где уместно — конкретные команды, инструменты или действия.
   • Если пользователь выбирает другой вариант — пересмотри этот раздел соответственно.

Проверка

• В ответе ровно одно предложение с формулировкой Проблемы.
• В ответе ровно три Варианта (A, B, C) — у каждого плюсы и минусы.
• В ответе одна Рекомендация: выбирает один вариант с обоснованием.
• Критерии готовности и план реализации соответствуют рекомендованному варианту.
• Если пользователь выбирает другой вариант — Рекомендация, критерии и план обновляются.

Пример

User: «Дай 1-3-1 по добавлению повторных попыток в наш API-клиент.»

Агент:

Проблема: Запросы к внешним сервисам под нагрузкой иногда падают, и нужна корректная обработка повторных попыток.

Варианты:

• Вариант A: экспоненциальная задержка с джиттером в общей утилите. Плюсы: простой, хорошо понятный паттерн; единая реализация для всех вызывающих сторон. Минусы: нет circuit-breaking; вызывающий код всё ещё блокируется во время повторов.

• Вариант B: библиотека повторов (tenacity) как декоратор на каждом вызове эндпоинта. Плюсы: настраивается отдельно для каждого эндпоинта; из коробки есть circuit breaker’ы и лимиты частоты запросов. Минусы: добавляет зависимость; декоратор может затемнять поток управления.

• Вариант C: асинхронные повторы через очередь с обработкой недоставленных сообщений (dead letter). Плюсы: неблокирующий; неудачные вызовы отслеживаются и могут быть повторены; хорошо масштабируется. Минусы: заметно усложняет систему; требует бэкенд очереди; избыточно для сервисов с низкой нагрузкой.

Рекомендация: Вариант A. Объём вызовов не оправдывает инфраструктуру очередей, а общая утилита с экспоненциальной задержкой и джиттером закрывает этот сценарий отказа чисто, без новых зависимостей.

Критерии готовности:

• Утилита api_retry() обрабатывает временные HTTP-ошибки (429, 502, 503, 504).
• Повторяет запрос до 3 раз с экспоненциальной задержкой и джиттером.
• Все внешние API-вызовы идут через утилиту повторов.
• Логирует каждую попытку повтора с указанием эндпоинта и номера попытки.
• Тесты покрывают исчерпание повторов, немедленный успех и сценарий «сначала сбой, потом успех».

План реализации:

1. Создать utils/api_retry.py с настраиваемым числом повторов, базовой задержкой и списком кодов статуса, при которых стоит повторять.
2. Добавить джиттер через random.uniform(0, base_delay), чтобы избежать одновременного всплеска повторов (thundering herd).
3. Обернуть существующие API-вызовы в api_client.py утилитой повторов.
4. Добавить unit-тесты, мокающие HTTP-ответы для каждого сценария повтора.
5. Проверить под нагрузкой простым стресс-тестом на моке нестабильного эндпоинта.