# Python Project Audit

> Проект выглядит законченным — проверить, так ли это, и выставить оценку: незавершённый код и заглушки, критические проблемы, мёртвые куски, слабые места перед выкаткой. Статанализ (pylint, bandit, mypy, radon, vulture) плюс ручной обход чек-листа; на выходе отчёт с баллами по разделам и вердиктом. FastAPI, Django, Flask. Используй когда пользователь просит «проверить готовность проекта к деплою», «отчёт о готовности к запуску в режиме MVP», «найти незавершённый код и критические проблемы», оценить законченность и целостность кодовой базы, или готовится к релизу. Уровень проекта, не диффа: одно изменение — change-review; Django-специфика по линзам — django-audit; понять устройство без оценки — codebase-recon.

- Skill: `goldenprofile/python-project-audit` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add goldenprofile/python-project-audit`
- Raw SKILL.md: https://api.skillmd.com/api/skills/goldenprofile/python-project-audit/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- Author: goldenprofile (https://skillmd.com/u/goldenprofile)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/goldenprofile/python-project-audit

---


# 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. Автоматический статический анализ

Запусти анализаторы: `pylint`, `bandit`, `mypy`, `radon`, `vulture`, `safety`.
Каждый инструмент — отдельное «испытание».

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

- запуск через `uvx` (`uvx pylint ...`, `uvx bandit -r .`) — без установки;
- или `pipx run <tool>`;
- или установку в venv проекта (`.venv`), если он есть.

Подробные команды (PowerShell + cross-platform) и разбор вывода — в
[references/static-analysis.md](references/static-analysis.md).

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

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

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

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

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

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

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

| Испытание | Вес | Баллы (0-10) | Взвешенный |
|-----------|-----|-------------|------------|
| Архитектура | 15% | ? | ? |
| Обработка ошибок | 10% | ? | ? |
| Безопасность | 20% | ? | ? |
| Производительность | 15% | ? | ? |
| Тестирование | 15% | ? | ? |
| Инфраструктура | 10% | ? | ? |
| Качество кода | 10% | ? | ? |
| Документация | 5% | ? | ? |
| **ИТОГО** | **100%** | | **?/10** |

### Градации

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

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

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

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

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

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

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

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

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