Codebase Recon
Разведка чужого или подзабытого кода: понять, как устроено, до того как что-то
менять. Навык только читает — не правит файлы, не запускает миграции,
runserver, тесты и ботов.
Шаг 0. Выбери режим
| Режим |
Когда |
Куда дальше |
| whole |
проект незнаком целиком: «что это», «как устроено», «с чего начать» |
references/whole-project.md |
| subject |
известно, что именно интересует: модуль, фича, тема |
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+ файлов)
Не пытайся прочитать всё:
- Поверхность сначала: README → конфиги зависимостей → структура верхнего уровня.
- Горячие файлы из git — наибольшее число изменений обычно и есть ядро проекта.
- Точки входа, а не весь код: роутеры и контроллеры дают карту API.
- Тесты вместо реализации: тест описывает поведение без деталей.
- Игнорируй сгенерированное:
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 — режим whole:
фазы разведки от README и git-истории до синтеза; таблица определения
архитектурного стиля, точки входа по типам проектов, поток данных.
- references/subject-scan.md — режим subject:
стратегия поиска (параллельные Glob+Grep), таблица артефактов по стекам
(Django / FastAPI / aiogram), gap-анализ и формат вывода.
- references/whole-report.md — шаблон отчёта
режима whole.
1---2name: codebase-recon3description: Разведка кодовой базы, только чтение, два режима: whole — незнакомый проект целиком (стек, архитектурный стиль, точки входа, поток данных, бизнес-цель, карта-отчёт); subject — одна область, модуль или фича адресно, с gap-анализом текущего против желаемого (OK/PARTIAL/GAP/RISK и план закрытия). Используй когда пользователь говорит «нужна экспресс-диагностика кодовой базы», «изучи кодовую базу и составь план улучшения», «что это за проект», «как он устроен», «с чего начать изучение», «разбери модуль X», «что сейчас есть по теме Y». Оценка качества и поиск дефектов — python-project-audit / django-audit; ревью одного диффа — change-review.4---56# Codebase Recon78Разведка чужого или подзабытого кода: понять, как устроено, до того как что-то9менять. Навык **только читает** — не правит файлы, не запускает миграции,10`runserver`, тесты и ботов.1112## Шаг 0. Выбери режим1314| Режим | Когда | Куда дальше |15|---|---|---|16| **whole** | проект незнаком целиком: «что это», «как устроено», «с чего начать» | [references/whole-project.md](references/whole-project.md) |17| **subject** | известно, что именно интересует: модуль, фича, тема | [references/subject-scan.md](references/subject-scan.md) |1819Признак режима — есть ли у запроса **subject**. «Разберись в проекте» — whole.20«Как здесь работает авторизация» — subject. Если запрос звучит как whole, но21проект знаком и вопрос узкий, уточни у пользователя, а не читай всё подряд.2223В режиме subject пользователь может дать **goal** — желаемое состояние24(«все сертификаты через Let's Encrypt с авто-обновлением»). Тогда к карте25добавляется gap-анализ. Если subject неясен — уточни, это дешевле, чем26исследовать не то.2728## Окружение2930Для поиска используй Glob/Grep/Read, а не `find`/`grep`/`cat`: оболочка на машине31пользователя заранее не известна. Git-команды запускай тем терминальным инструментом,32который даёт среда. Стек определяй по33`requirements.txt`/`pyproject.toml`/`package.json` до того, как искать паттерны.3435## Правило 20/80 для больших кодовых баз (500+ файлов)3637Не пытайся прочитать всё:38391. **Поверхность сначала:** README → конфиги зависимостей → структура верхнего уровня.402. **Горячие файлы из git** — наибольшее число изменений обычно и есть ядро проекта.413. **Точки входа, а не весь код:** роутеры и контроллеры дают карту API.424. **Тесты вместо реализации:** тест описывает поведение без деталей.435. **Игнорируй сгенерированное:** `migrations/`, `dist/`, `generated/`, `vendor/`, `node_modules/`.444520% файлов дают 80% понимания — задача найти эти 20%, а не прочитать 100%.4647## Ограничения4849- **Не делай поспешных выводов** — сначала проверь зависимости и конфиги.50- **Нет документации** — это уже вывод о состоянии проекта; дальше опирайся51 только на код (имена, структура, тесты).52- **Не выдумывай пути** — указывай только реально найденные файлы и строки,53 не достраивай правдоподобные имена по памяти.54- **Не превращайся в аудитора** — задача карта и понимание, а не список55 дефектов с оценкой. Нашёл проблемы — назови, но глубокий разбор передай56 профильному навыку.57- **Объём вывода** — до ~500 строк; если тема обширна, выдели топ-10 находок.5859## Связь с библиотекой навыков6061- `python-project-audit` — оценка готовности к проду с баллами (фреймворк-независимо).62- `django-audit` — Django-разбор по линзам: ORM/N+1, Celery, шаблоны, settings.63- `change-review` — ревью конкретного диффа или файла, а не карта проекта.64- `spec-writer` — превратить найденное в спеку или план работ.65- `docs-generator` — зафиксировать восстановленное устройство в README/ARCHITECTURE.md.66- `session-catchup` — восстановить контекст своей же прерванной работы (это не разведка).6768## Справочники6970- [references/whole-project.md](references/whole-project.md) — режим whole:71 фазы разведки от README и git-истории до синтеза; таблица определения72 архитектурного стиля, точки входа по типам проектов, поток данных.73- [references/subject-scan.md](references/subject-scan.md) — режим subject:74 стратегия поиска (параллельные Glob+Grep), таблица артефактов по стекам75 (Django / FastAPI / aiogram), gap-анализ и формат вывода.76- [references/whole-report.md](references/whole-report.md) — шаблон отчёта77 режима whole.
goldenprofile