Performance Audit Feature

Аудит производительности отдельной фичи

Для проекта the-platform: микросервисная CRM-платформа — FastAPI + asyncpg + PostgreSQL + Redis + RabbitMQ бэкенд-сервисы, React/Vite/TS фронтенд (the-frontend), Docker/Kubernetes/Helm инфраструктура, нагрузочное тестирование на k6 в load-testing/.

Это точечная версия полного аудита репозитория (см. скилл performance-audit-full, если задача — весь репозиторий, а не одна фича). Принципы измерения те же, но периметр, находки и отчёт строго ограничены кодом, который относится к этой фиче и к тому, что она затрагивает.

ВХОДНЫЕ ДАННЫЕ

Фича: $ARGUMENTS

Промпт универсален по формату входа. В зависимости от того, что передано, сначала восстанови периметр фичи:

A. Директория/ветка/diff (например the-frontend/src/features/leads-import или "diff между dev и веткой feature/PROJ-XXXX"):

• Определи затронутые файлы через git diff --stat относительно базовой ветки (main/dev) либо прочитай содержимое директории целиком, если это самостоятельный модуль.
• Определи, какие сервисы/пакеты эти файлы затрагивают (services/, the-frontend, libs/) — это и есть периметр СРЕЗА 2 ниже.

B. Документ с требованиями (путь к .md/.txt/дизайн-доку и т.п.):

• Прочитай документ целиком, выпиши описанные use cases и ожидаемые эндпоинты/экраны/фоновые процессы.
• Найди реализующий эти use cases код в репозитории (grep по именам эндпоинтов, роутов, компонентов, названий из документа) — если реализация отсутствует или найдена лишь частично, зафиксируй это явно в отчёте отдельным пунктом ("не реализовано — тестирование невозможно"), не додумывай.

C. YouTrack issue (ID или ссылка):

• Получи текст issue (через доступный YouTrack MCP/API либо попроси пользователя вставить текст, если прямого доступа нет) — описание, критерии приёмки, связанные коммиты/PR.
• Если в issue или связанных коммитах указаны конкретные файлы/сервисы — это периметр; если нет, определи периметр по описанию, как в пункте B, и по git log --grep=<ID> на предмет связанных коммитов.

Если ни один из трёх источников не даёт однозначно определить периметр (неясно, какой код относится к фиче) — остановись и явно перечисли, что нужно уточнить у автора задачи, вместо того чтобы тестировать наугад весь сервис целиком.

КЛЮЧЕВОЙ ПРИНЦИП: ИЗМЕРЯЙ, А НЕ ДОГАДЫВАЙСЯ

Компания крайне чувствительна к расходу вычислительных ресурсов (CPU, RAM, сетевой трафик, стоимость инфраструктуры) — это приоритет первого класса. Для фичи, которая часто ещё не находилась под реальной нагрузкой, особенно важно не путать "выглядит нормально на dev-данных" с "выдержит прод-объём". Придерживайся тех же правил, что и при полном аудите:

1. Для каждой находки, где технически возможно, подтверждай воздействие измерением: EXPLAIN ANALYZE для новых/изменённых SQL-запросов, профилирование (py-spy/cProfile) для нового CPU-хотспота, реальный размер бандла/чанка для нового фронтенд-кода, k6-сценарий (новый или расширенный существующий) для нагрузочных характеристик нового/ изменённого API. Находка без числа — гипотеза; помечай явно как "не подтверждено измерением".
2. Не предлагай оптимизацию там, где нет доказанной проблемы — три одинаковых строки лучше преждевременной абстракции; тот же принцип для кэшей и мемоизации в новом коде.
3. Явно укажи, при каком объёме данных/нагрузки находка становится критичной, учитывая реалистичный рост именно для этой фичи (например: импорт лидов — тестируй не на 10 записях, а на объёме, сопоставимом с реальным экспортом клиента). Источник для оценки объёма — по приоритету: (а) прод-метрики/дашборды, если есть доступ; (б) порядок величины из существующих load-testing/reports для того же домена; (в) прямой вопрос автору задачи/PM о реальном объёме клиента. Если ни один источник недоступен — зафиксируй это как ограничение покрытия (см. "методология и ограничения покрытия" в формате отчёта), а не подставляй произвольное число.
4. Если фича заменяет/модифицирует существующий функционал — проверь, не деградировала ли производительность по сравнению с тем, что было (сравнение "до/после" обязательно там, где есть с чем сравнивать). Технически получи состояние "до": git worktree add (или переключение на копию базовой ветки) на коммите перед первым коммитом фичи — прогони тот же EXPLAIN ANALYZE/профилирование/сборку бандла на этой копии и сравни числа напрямую; для отдельного запроса/компонента без поднятия окружения достаточно git show <base-ref>:путь, чтобы прочитать прежнюю реализацию и сравнить её алгоритмически (число запросов, сложность) — такое сравнение явно помечай как "не измерено, оценка по коду", а не как измеренный результат.
5. Формулируй статус явно: "подтверждено измерением" / "правдоподобно, но не измерено" / "не является проблемой при текущем объёме данных" / "уже оптимизировано корректно".

МЕТОДОЛОГИЯ: ТРИ НЕЗАВИСИМЫХ СРЕЗА (в границах периметра фичи)

СРЕЗ 1 — Инструментальный анализ и профилирование нового/изменённого кода

• Backend: включи логирование SQL на сценариях именно этой фичи и найди N+1/запросы без LIMIT в новом коде; прогони EXPLAIN ANALYZE на новых/изменённых запросах; py-spy/cProfile на новых обработчиках, если есть подозрение на CPU-хотспот.
• База данных: проверь, что новые колонки/фильтры фичи покрыты индексами (сверь со схемой миграции, которая эту фичу вводит); если фича добавляет новую таблицу — оцени ожидаемый рост и паттерны доступа.
• Redis/очереди: если фича вводит новые ключи Redis — есть ли TTL; если вводит новую очередь/consumer — prefetch/QoS, DLQ, поведение при поллинге внешнего API.
• Frontend: если фича добавляет экран/компонент — собери прод-сборку и проверь прирост размера бандла/чанка именно от этой фичи (сравни размер до/после, если есть базовая точка); проверь наличие code-splitting для нового маршрута; прогони Lighthouse (или аналог) по новому экрану на предмет LCP/TBT, если можно поднять фронтенд локально.
• Нагрузочное тестирование: проверь, есть ли в load-testing/k6 сценарий, покрывающий новые/изменённые эндпоинты этой фичи. Если нет — по возможности напиши минимальный k6-сценарий под эту фичу и прогони его (если можно поднять окружение); если сценарий уже есть, прогони и сравни с baseline в load-testing/reports.
• Docker/Helm: только если фича меняет Dockerfile/values/чарт (новый сервис, новая зависимость, изменение resources) — иначе этот пункт не применим, явно отметь "не затронуто фичей".

СРЕЗ 2 — Ручной построчный разбор кода, затронутого фичей

Разбери построчно (не по диагонали) весь код, определённый на шаге "Входные данные" как периметр фичи: новые/изменённые файлы backend-сервиса(ов), фронтенд-компоненты, изменения в общих библиотеках (libs/shared_auth, libs/shared_metrics — если фича их трогает, это код, выполняющийся на каждом запросе каждого сервиса, отнесись с повышенным вниманием), фоновые обработчики, инфраструктурные конфиги. Используй детальный чек-лист ниже — выбери из него категории, применимые к типу фичи (не обязаны совпасть все 12 — например, у чисто фронтенд-фичи не будет находок по RabbitMQ).

СРЕЗ 3 — Влияние фичи на архитектуру и соседние сценарии

Независимо от построчного разбора оцени:

• Добавляет ли фича новые синхронные межсервисные хопы в существующие частые сценарии (логин, список сделок/лидов, отправка сообщения в чат) — посчитай цепочку вызовов до и после появления фичи.
• Если фича переиспользует/дублирует существующий функционал (ещё один поллинг того же внешнего API, ещё один кэш для тех же данных) — можно ли переиспользовать существующий механизм вместо добавления нового.
• Совместное потребление ресурсов: не создаёт ли фича конкуренцию за то же соединение с БД/тот же Redis-инстанс/ту же очередь, что и существующая горячая нагрузка.
• Соответствует ли фича общей стратегии кэширования/наблюдаемости проекта, или вводит точечное разовое решение в обход неё.

ДЕТАЛЬНЫЙ ЧЕК-ЛИСТ ПО КАТЕГОРИЯМ (применяй релевантные фиче пункты)

1. Асинхронный backend: синхронные HTTP-клиенты/I/O внутри async def, CPU-тяжёлые операции на event loop без ThreadPoolExecutor/ ProcessPoolExecutor, последовательные await там, где возможен asyncio.gather.
2. База данных: N+1 запросы, отсутствующие индексы на новых WHERE/JOIN/ORDER BY колонках (особенно user_id/tenant_id/integration_id), SELECT * там где нужно 2-3 поля, списковые эндпоинты без пагинации, размер пула соединений, долгие транзакции с внешними HTTP-вызовами внутри, повторяющиеся идентичные запросы в одном request-response цикле.
3. Кэширование (Redis): ключи без TTL, отсутствие кэша для дорогих часто повторяющихся вычислений, cache stampede, кэш без инвалидации при изменении исходных данных, KEYS/SCAN по всей базе в хот-пасе.
4. Межсервисное взаимодействие: отсутствие таймаутов на исходящих запросах, отсутствие retry с backoff (или retry без backoff), дублирующие вызовы одного сервиса вместо batched-вызова, полная пересылка тяжёлых payload там, где нужна часть данных.
5. Очереди (RabbitMQ) и фоновые обработчики: prefetch/QoS, poison message без DLQ, частота поллинга внешних API относительно реальной потребности, размер батча, обработка rate-limit.
6. Сериализация и размер payload: избыточные поля в ответах Pydantic-моделей, логирование целиком крупных объектов в hot path, отсутствие gzip/brotli для крупных JSON-ответов.
7. Frontend: прирост размера бандла/чанка, отсутствие code-splitting/lazy-loading, лишние ре-рендеры на больших списках (виртуализация), waterfall-загрузка данных вместо параллельной, слишком частый polling вместо WebSocket/SSE; если фича добавляет новый экран/маршрут — сними Lighthouse (или аналог) метрики LCP/TBT для него, если можно поднять фронтенд локально.
8. Docker-образы (только если фича меняет Dockerfile): размер финального образа, отсутствие multi-stage build, избыточный базовый образ.
9. Kubernetes/Helm (только если фича меняет чарты/values): resources requests/limits, интервалы liveness/readiness проб, replicaCount/ HPA-пороги.
10. Наблюдаемость: кардинальность новых метрик/лейблов (user_id/ request_id как label), сэмплирование трейсов для новых эндпоинтов, объём DEBUG-логирования, оставленный в новом коде.
11. Алгоритмическая эффективность: квадратичные операции над коллекциями, которые фича вводит и которые станут узким местом на реальных объёмах, повторный парсинг одних и тех же данных, ненужное глубокое копирование, отсутствие батчинга для массовых операций (импорт/синк), которые фича добавляет.
12. Нагрузочное тестирование: покрывает ли существующий/новый k6-сценарий именно эту фичу, зафиксирован ли для неё бюджет производительности (максимальная латентность p95, максимальный прирост размера бандла).

EDGE CASES, ХАРАКТЕРНЫЕ ДЛЯ ФИЧ (а не всего репозитория)

• Фича работает быстро на пустой/dev-таблице, но не тестировалась на объёме, сопоставимом с реальными данными клиента — всегда прикидывай реалистичный рост для конкретно этой фичи.
• Фича добавляет вызов уже существующего "дорогого" эндпоинта/запроса в новом месте — сама находка была не в фиче, а в том, что фича кратно увеличивает частоту вызова уже известной проблемы (проверь, есть ли она уже в load-testing/reports или в предыдущем аудите).
• Отладочные флаги/verbose-логирование, оставленные в коде фичи после разработки и не отключённые к моменту сдачи.
• Feature flag фичи, из-за которого старый и новый путь работают параллельно ("на время миграции") — удваивает нагрузку там, где это не единственный путь исполнения.
• Фича, реализованная в общей библиотеке (libs/shared_auth, libs/shared_metrics) — даже небольшая неэффективность умножается на все сервисы и все реплики, где библиотека подключена, а не только на сервис, где фича изначально задумывалась.
• Тесты/бенчмарки фичи гоняются только на happy path с маленьким payload, а не на худшем реалистичном случае (максимальный размер файла для загрузки, максимальное число элементов в батч-операции, которые фича формально допускает).

ФОРМАТ ОТЧЁТА

1. Executive summary (без технического жаргона): готова ли фича по производительности к продакшену при ожидаемой нагрузке, что расходует ресурсы заметнее всего, что можно исправить без риска для функциональности.
2. Вердикт: "готово" / "готово с оговорками (перечислить)" / "не готово — критичные находки перечислить" — сформулировать явно, это тестирование фичи перед выпуском, а не просто список наблюдений. Правило увязки с таблицей KPI (п.3 ниже): хотя бы одна находка severity critical, подтверждённая измерением, — вердикт не может быть "готово" (минимум "с оговорками", а при риске деградации горячего пути — "не готово"); критичные находки без подтверждения измерением фиксируй как блокер для повторной проверки перед мержем, не занижай severity задним числом, чтобы вердикт сошёлся с желаемым результатом.
3. Таблица KPI: число находок по severity (critical/high/medium/low), число находок, подтверждённых измерением, vs "правдоподобно, но не измерено".
4. Если фича заменяет существующий функционал — сравнение "до/после" по ключевым метрикам (латентность, число запросов к БД, размер payload/бандла).
5. Полный список находок с привязкой file:line, количественной оценкой воздействия (или пометкой "не измерено"), severity, условием при котором находка станет критичной, и конкретной рекомендацией по исправлению (не "оптимизировать запрос", а "добавить индекс на (tenant_id, created_at)").
6. Раздел "что сделано хорошо" в этой фиче — эффективные решения, которые стоит тиражировать.
7. План действий: быстрые точечные фиксы без риска регрессии — в первую очередь; изменения, требующие тестирования под нагрузкой — во вторую; вопросы уровня архитектуры/тимлида (например "не стоило вводить отдельный поллинг, есть общий механизм") — отдельным пунктом для обсуждения, не как блокер мержа, если явно не critical.
8. Раздел "методология и ограничения покрытия" — какие инструменты/ измерения использованы, что не удалось протестировать (нет доступа к прод-метрикам, нет возможности поднять окружение, нет реалистичного объёма тестовых данных) — явно, чтобы отсутствие находок не читалось как "всё оптимально".

ПРАВИЛА ОФОРМЛЕНИЯ НАХОДОК

Для каждой находки обязательны: путь к файлу и номер строки; название проблемы и категория (см. чек-лист); количественная оценка воздействия (измеренная либо явно помеченная как неизмеренная оценка с обоснованием); условие, при котором проблема становится критичной; severity с обоснованием; рекомендация по исправлению, сохраняющая текущее поведение системы (если оптимизация неизбежно меняет поведение — например, ужесточение лимита пагинации — отметь это отдельно и явно).

ЗАПУСК ТЕСТИРОВАНИЯ (практическая инструкция)

Делегируй инструментальный разбор и профилирование через Agent tool отдельному субагенту, а не веди его в основном потоке диалога, если у тебя есть доступ к Agent tool:

1. Сначала САМ (в основном потоке) выполни раздел "Входные данные" — определи и зафиксируй точный периметр фичи (список файлов/сервисов/ эндпоинтов). Не делегируй этот шаг: субагент стартует без контекста разговора и не знает, что имелось в виду под "фичей". Здесь же проверь load-testing/reports и load-testing/ANALYSIS_GUIDE.md на предмет уже задокументированных узких мест, которые затрагивает периметр фичи (те же эндпоинты/таблицы/сервисы) — это дешёвая проверка, и без неё субагент рискует не узнать про уже известную проблему, которую фича лишь усиливает частотой вызова (см. EDGE CASES выше), и расследовать её заново с нуля.
2. Запусти Agent tool (general-purpose, или Explore для чисто поискового под-этапа) с самодостаточным заданием, включающим: определённый на шаге 1 периметр (конкретные пути, а не "фича PROJ-XXXX" без расшифровки); разделы "Ключевой принцип", "Методология" и "Детальный чек-лист" из этого файла; требование вернуть находки в формате раздела "Правила оформления находок" и итоговый отчёт по разделу "Формат отчёта". Запускай в foreground (run_in_background: false), если результат нужен для дальнейшего решения в этом же диалоге (например, перед мержем) — не продолжай молча, пока агент работает.
3. Если периметр фичи большой (несколько сервисов + фронтенд), рассмотри параллельный запуск нескольких субагентов по независимым зонам (СРЕЗ 2 по backend-сервису(ам) отдельно от СРЕЗ 2 по фронтенду), а СРЕЗ 3 (архитектурный обзор) — отдельным агентом или самостоятельно, чтобы не дать одному агенту "срезать угол" по всему периметру сразу.
4. Если Agent tool недоступен в текущей среде — выполни те же шаги последовательно в основном потоке, явно отделяя СРЕЗ 1/2/3 друг от друга, и не позволяй результатам одного среза подменять проверку другого.
5. Сведи результаты субагента(ов) в единый отчёт по формату выше; если несколько субагентов независимо нашли одну и ту же находку — не дублируй её в отчёте, но усиль статус подтверждения.
6. Прежде чем объявить фичу готовой, явно проверь раздел "Edge cases, характерные для фич" — это типичные слепые зоны именно точечного, а не полного аудита.

Это тестирование, не имплементация: правки вносит разработчик по итогам отчёта, не ты в рамках этого скилла.