# Codebase Recon

> Разведка кодовой базы, только чтение, два режима: whole — незнакомый проект целиком (стек, архитектурный стиль, точки входа, поток данных, бизнес-цель, карта-отчёт); subject — одна область, модуль или фича адресно, с gap-анализом текущего против желаемого (OK/PARTIAL/GAP/RISK и план закрытия). Используй когда пользователь говорит «нужна экспресс-диагностика кодовой базы», «изучи кодовую базу и составь план улучшения», «что это за проект», «как он устроен», «с чего начать изучение», «разбери модуль X», «что сейчас есть по теме Y». Оценка качества и поиск дефектов — python-project-audit / django-audit; ревью одного диффа — change-review.

- Skill: `goldenprofile/codebase-recon` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add goldenprofile/codebase-recon`
- Raw SKILL.md: https://api.skillmd.com/api/skills/goldenprofile/codebase-recon/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/codebase-recon

---


# Codebase Recon

Разведка чужого или подзабытого кода: понять, как устроено, до того как что-то
менять. Навык **только читает** — не правит файлы, не запускает миграции,
`runserver`, тесты и ботов.

## Шаг 0. Выбери режим

| Режим | Когда | Куда дальше |
|---|---|---|
| **whole** | проект незнаком целиком: «что это», «как устроено», «с чего начать» | [references/whole-project.md](references/whole-project.md) |
| **subject** | известно, что именно интересует: модуль, фича, тема | [references/subject-scan.md](references/subject-scan.md) |

Признак режима — есть ли у запроса **subject**. «Разберись в проекте» — whole.
«Как здесь работает авторизация» — subject. Если запрос звучит как whole, но
проект знаком и вопрос узкий, уточни у пользователя, а не читай всё подряд.

В режиме subject пользователь может дать **goal** — желаемое состояние
(«все сертификаты через Let's Encrypt с авто-обновлением»). Тогда к карте
добавляется gap-анализ. Если subject неясен — уточни, это дешевле, чем
исследовать не то.

## Окружение

Для поиска используй Glob/Grep/Read, а не `find`/`grep`/`cat`: оболочка на машине
пользователя заранее не известна. Git-команды запускай тем терминальным инструментом,
который даёт среда. Стек определяй по
`requirements.txt`/`pyproject.toml`/`package.json` до того, как искать паттерны.

## Правило 20/80 для больших кодовых баз (500+ файлов)

Не пытайся прочитать всё:

1. **Поверхность сначала:** README → конфиги зависимостей → структура верхнего уровня.
2. **Горячие файлы из git** — наибольшее число изменений обычно и есть ядро проекта.
3. **Точки входа, а не весь код:** роутеры и контроллеры дают карту API.
4. **Тесты вместо реализации:** тест описывает поведение без деталей.
5. **Игнорируй сгенерированное:** `migrations/`, `dist/`, `generated/`, `vendor/`, `node_modules/`.

20% файлов дают 80% понимания — задача найти эти 20%, а не прочитать 100%.

## Ограничения

- **Не делай поспешных выводов** — сначала проверь зависимости и конфиги.
- **Нет документации** — это уже вывод о состоянии проекта; дальше опирайся
  только на код (имена, структура, тесты).
- **Не выдумывай пути** — указывай только реально найденные файлы и строки,
  не достраивай правдоподобные имена по памяти.
- **Не превращайся в аудитора** — задача карта и понимание, а не список
  дефектов с оценкой. Нашёл проблемы — назови, но глубокий разбор передай
  профильному навыку.
- **Объём вывода** — до ~500 строк; если тема обширна, выдели топ-10 находок.

## Связь с библиотекой навыков

- `python-project-audit` — оценка готовности к проду с баллами (фреймворк-независимо).
- `django-audit` — Django-разбор по линзам: ORM/N+1, Celery, шаблоны, settings.
- `change-review` — ревью конкретного диффа или файла, а не карта проекта.
- `spec-writer` — превратить найденное в спеку или план работ.
- `docs-generator` — зафиксировать восстановленное устройство в README/ARCHITECTURE.md.
- `session-catchup` — восстановить контекст своей же прерванной работы (это не разведка).

## Справочники

- [references/whole-project.md](references/whole-project.md) — режим whole:
  фазы разведки от README и git-истории до синтеза; таблица определения
  архитектурного стиля, точки входа по типам проектов, поток данных.
- [references/subject-scan.md](references/subject-scan.md) — режим subject:
  стратегия поиска (параллельные Glob+Grep), таблица артефактов по стекам
  (Django / FastAPI / aiogram), gap-анализ и формат вывода.
- [references/whole-report.md](references/whole-report.md) — шаблон отчёта
  режима whole.