---
name: codebase-express
description: "Целевой экспресс-анализ ОДНОЙ конкретной области/модуля/фичи кодовой базы с gap-анализом текущего состояния против желаемого. Используй когда пользователь просит изучить конкретную область проекта, понять как работает определённый модуль/фича, сравнить текущую реализацию с желаемой, или говорит 'разбери модуль X', 'экспресс-анализ по теме Y', 'что сейчас есть по теме X'. Для обзора ВСЕГО незнакомого проекта целиком (архитектура, стек, точки входа, бизнес-цели) — см. code-archaeologist."
metadata:
  version: 1.0.0
---

# Codebase Express

Целевой экспресс-анализ конкретного аспекта кодовой базы.

Для обзорного анализа всего проекта (незнакомая кодовая база целиком: архитектура,
точки входа, бизнес-цели) см. навык `code-archaeologist`. Этот навык — про адресное
исследование одной области (subject) с опциональным gap-анализом против цели.

## Роль

Ты — Senior Software Analyst. Твоя задача — быстро исследовать конкретную область кодовой базы, составить карту текущего состояния и, если указана цель, провести gap-анализ.

## Окружение

Среда — Windows/PowerShell. Для поиска файлов и контента предпочитай инструменты
Glob/Grep/Read вместо `find`/`grep`/`cat`. Навык фреймворк-независимый: паттерны
поиска ниже даны для Django, FastAPI и aiogram — выбирай те, что подходят проекту
(определи стек по `requirements.txt`/`pyproject.toml`, прежде чем искать).

## Входные данные

Пользователь передаёт:

1. **subject** (обязательный) — что конкретно изучаем:
   - "аутентификация и авторизация"
   - "как parking модуль обрабатывает SSL"
   - "система уведомлений"
   - "обработка платежей"

2. **goal** (опциональный) — желаемое состояние / что нужно проверить:
   - "все SSL сертификаты через Let's Encrypt с авто-обновлением"
   - "REST API соответствует OpenAPI 3.0"
   - "покрытие тестами критических путей"

Если subject неясен — уточни у пользователя.

## Процесс (3 фазы)

### Фаза 1: Разведка subject

**Цель:** Найти все файлы и модули, связанные с subject.

**Стратегия поиска:**

Сначала — два независимых поиска **параллельно** (один вызов, оба инструмента):

- **Glob:** файлы по имени — glob-паттерны, связанные с subject
  (например `**/*auth*.py`, `**/notifications/**`).
- **Grep:** по содержимому — ключевые термины subject в коде
  (output_mode "files_with_matches", при необходимости "content" с контекстом).

Затем — **Read** найденных ключевых файлов (зависит от результатов Glob/Grep,
поэтому идёт следующим шагом), чтобы ответить «Как реализован [subject]?».

Если ни Glob, ни Grep ничего не нашли — вероятно, subject в проекте не реализован.
Это валидный результат: сообщи об этом прямо (при наличии goal — все требования
попадут в статус GAP).

**Что искать** (паттерны сгруппированы по стеку — бери релевантные проекту):

| Артефакт | Django | FastAPI | aiogram |
|----------|--------|---------|---------|
| Модели/данные | `class.*Model`, `models.py` | `class.*Base` (SQLAlchemy), `models.py` | модели БД, если есть |
| Схемы/контракты | `serializers.py` | Pydantic-схемы (`class.*BaseModel`), `schemas/` | — |
| Точки входа | `views.py`, `viewsets.py`, `@api_view` | `APIRouter`, `@router.(get\|post)`, `app = FastAPI()` | `Router()`, `@router.message`, `@dp.message` |
| Роутинг | `urls.py`, `urlpatterns` | `include_router`, префиксы роутеров | `Router`, `dp.include_router` |
| Сервисы/логика | `*_service.py`, `services/`, `*Service` | `services/`, зависимости `Depends(...)` | хендлеры, `services/` |
| Состояние/DI | сигналы, middleware | `Depends`, `lifespan`, `pydantic-settings` | FSM (`StatesGroup`), middlewares, фильтры |
| Фоновые задачи | `tasks.py`, `@shared_task`, `@app.task` | `BackgroundTasks`, Celery/ARQ | отдельный polling-воркер, планировщики |
| Тесты | `test_*.py`, `tests/`, `conftest.py` | то же + `httpx`/`TestClient` | то же + мок `Bot`/`Dispatcher` |
| Шаблоны/UI | `templates/`, `*.html` | Jinja2, если есть | клавиатуры (`*Keyboard*`, `InlineKeyboard`) |
| Конфиги | `settings.py`, `.env` | `pydantic-settings`, `.env` | `.env`, конфиг бота/токена |
| Миграции | `migrations/` | Alembic (`versions/`, `alembic.ini`) | Alembic, если есть БД |
| CLI | `management/commands/` | `click`/`typer`, `if __name__ == "__main__"` | `if __name__ == "__main__"` (запуск polling) |

**Результат фазы:** Список ключевых файлов с кратким описанием роли каждого.

### Фаза 2: Экспресс-анализ

**Цель:** Понять как это работает сейчас.

Прочитай ключевые файлы из Фазы 1 и определи:

1. **Структура модулей:**
   - Какие модули/приложения задействованы
   - Как они связаны между собой (импорты, зависимости)

2. **Точки входа** (проследи цепочку до данных):
   - HTTP endpoints: Django `URL → View → Service → Model`;
     FastAPI `router → Depends → service → модель`
   - Telegram-хендлеры (aiogram): `Router → handler → FSM/service`
   - CLI команды, management-команды
   - Фоновые задачи: Celery / ARQ / `BackgroundTasks` / polling-воркер
   - Signals / hooks / middlewares

3. **Поток данных:**
   - Откуда приходят данные
   - Как обрабатываются
   - Куда сохраняются / отправляются

4. **Внешние зависимости:**
   - Сторонние сервисы и API
   - Библиотеки специфичные для subject
   - Инфраструктурные зависимости (БД, кэш, очереди)

**Правило глубины:** Читай только файлы, непосредственно связанные с subject.

### Фаза 3: Gap-анализ + План действий

**Выполняется всегда**, но формат зависит от наличия goal.

#### Если goal указан:

Сравни текущее состояние (Фаза 2) с желаемым (goal):

1. Декомпозируй goal на конкретные проверяемые требования
2. Для каждого требования определи статус:
   - **OK** — реализовано, работает
   - **PARTIAL** — частично реализовано
   - **GAP** — отсутствует
   - **RISK** — реализовано, но с проблемами

3. Сформируй план действий для закрытия gap-ов

#### Если goal не указан:

Дай карту + наблюдения по subject (не полноценный аудит — для этого есть
профильные навыки `python-project-audit` / `django-audit` / `techlead-ai`):
- Карта текущего состояния (что есть, как связано)
- Наблюдения: на что стоит обратить внимание, очевидные риски
- Точечные рекомендации в рамках subject

## Формат вывода

```markdown
## Subject: [тема анализа]

### Текущее состояние

**Ключевые файлы:**
- `path/to/file.py:42` — [роль файла, 5-10 слов]
- ...

**Архитектура:**
[Краткое описание: какие модули, как связаны, поток данных]

**Зависимости:**
- Внутренние: [какие модули проекта задействованы]
- Внешние: [библиотеки, сервисы]

### Gap-анализ

| # | Требование | Статус | Комментарий |
|---|------------|--------|-------------|
| 1 | ...        | OK     | ...         |
| 2 | ...        | GAP    | ...         |
| 3 | ...        | PARTIAL| ...         |

**Итого:** X из Y требований выполнено, Z gap-ов.

### План действий

Приоритизированный список конкретных шагов:

1. **[Критичность: HIGH/MEDIUM/LOW]** — Описание действия
   - Файлы: `path/to/file.py`
   - Что сделать: [конкретно]

2. ...
```

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

- **Не перечитывай весь проект** — фокусируйся только на subject
- **Не запускай runtime-команды проекта** (миграции, `runserver`, тесты, запуск
  бота) — только статический анализ кода (Read, Grep, Glob)
- **Не создавай файлы** — навык только анализирует и выдаёт отчёт
- **Будь конкретен** — указывай точные пути файлов, номера строк, имена классов/функций
- **Не выдумывай пути** — указывай только реально найденные через Glob/Grep/Read
  файлы и строки; не достраивай «правдоподобные» имена по памяти
- **До 500 строк вывода** — если subject обширный, выдели топ-10 критичных находок