Python Project Audit

Проверка заявленной готовности против фактической: проект выглядит законченным — разобраться, так ли это. Полный pipeline: статический анализ → ручной review → отчёт с баллами и вердиктом.

Это статический аудит: код только читается и анализируется инструментами. НЕ запускай тесты, python manage.py или приложение — не нужно для аудита.

Шаг 0. Разведка

Собери контекст перед анализом. Используй инструменты Grep/Glob/Read вместо POSIX-утилит — они не зависят от оболочки на машине пользователя:

• Структура и размер: Glob по **/*.py — посчитай количество файлов.
• Фреймворк: Grep по fastapi|FastAPI, django|Django, flask|Flask (output_mode: files_with_matches).
• Зависимости: Read для requirements.txt, pyproject.toml или Pipfile.
• Инфраструктура: Glob по Dockerfile, docker-compose.yml, .github/workflows/*, .gitlab-ci.yml, Jenkinsfile.
• Тесты: Glob по **/test_*.py, **/conftest.py.
• Конфиги/ENV: Glob по .env*, *.ini, *.cfg, alembic.ini.

Определи: фреймворк (FastAPI / Django / Flask), размер (файлы, строки), зрелость (тесты, CI, Docker, миграции). Затем прочитай ключевые файлы: точка входа (main.py / app.py / manage.py), конфигурация, роутинг, модели.

Шаг 1. Автоматический статический анализ

Первичный стек — ruff (lint + format + security-правила S), pip-audit (уязвимости зависимостей) и типизатор по проекту (ty, mypy или pyright — что реально настроено; ничего — зафиксируй как находку). Каждый инструмент — отдельное «испытание».

Опциональная глубина — только если проект её уже ведёт или пользователь согласился: pylint (семантика поверх ruff), bandit (глубокий security-скан в дополнение к ruff check --select S), radon (сложность), vulture (мёртвый код). Не тащи эти инструменты в проект насильно.

Установка — только с согласия пользователя. Никогда не используй pip install --break-system-packages (ломает системный Python). Первый ряд — запуск без установки:

• uvx <tool> ... (uvx ruff check ., uvx pip-audit) — если есть uv;
• или pipx run <tool>;
• или установку в venv проекта (.venv), если он есть.

Подробные команды и разбор вывода каждого испытания — в references/static-analysis.md.

Если инструмент не установился или упал — не останавливайся, отметь в отчёте и двигайся дальше.

Шаг 2. Ручной review — 8 испытаний

Прочитай код и оцени каждую категорию по шкале 0-10. Для каждой находки указывай: файл, строку, что не так, как исправить.

Категории: Архитектура, Обработка ошибок, Безопасность, Производительность/Highload, Тестирование, Инфраструктура/деплой, Качество кода и стиль, Документация/DX.

Полный чек-лист по каждому испытанию с антипаттернами — в references/manual-review-checklist.md.

Для оценки тестового покрытия (Испытание 5) полезен связанный навык test-coverage-auditor.

Шаг 3. Подсчёт баллов

Градации

• 9-10 — Production-ready, можно деплоить под нагрузку
• 7-8 — Хороший проект, нужны точечные улучшения
• 5-6 — MVP-уровень, серьёзная доработка перед продом
• 3-4 — Прототип, много работы впереди
• 0-2 — Нужен рефакторинг с нуля

Шаг 4. Генерация отчёта

Сохрани в docs/audit-YYYY-MM-DD.md. Шаблон отчёта — в references/report-template.md.

Шаг 5. Презентация результатов

После генерации отчёта:

1. Покажи итоговый балл и таблицу прямо в чате.
2. Выдели топ-3 критичных проблемы с конкретными решениями.
3. Предложи: «Хочешь, чтобы я исправил критичные проблемы прямо сейчас?»

Адаптация под фреймворки

Дополнительные проверки для FastAPI / Django / Flask — в references/framework-specifics.md.

Важные принципы

• Конкретика: «В файле X, строка Y, вот проблема, вот решение» — не «улучшите безопасность».
• Приоритизация: критичное → важное → nice-to-have.
• Контекст: учитывай стадию проекта (MVP vs зрелый прод).
• Баланс: обязательно отмечай сильные стороны, не только проблемы.
• Actionable: каждая находка = конкретное действие, которое можно выполнить.