---
name: get-project-map
description: Используй этот навык, когда тебе нужно увидеть или актуализировать текущую структуру папок и файлов проекта (особенно после создания/удаления файлов или переключения веток), либо понять расположение пакетов в воркспейсе. Также содержит шаблон для поддержки docs/project-map/.
---

# Навык получения карты проекта (Project Map)

Этот навык позволяет мгновенно получить актуальное дерево каталогов всего репозитория с учетом `.gitignore` без загрузки содержимого самих файлов в контекст.

## Команда для выполнения:
Запусти в терминале следующую команду:
`repomix --no-files --stdout`

> **Prerequisite:** `repomix` должен быть установлен (`npm i -g repomix` или через Dockerfile). Если не установлен — установи перед использованием.

## Твои действия:
1. Запусти указанную команду в терминале. Она выведет дерево каталогов и список файлов с их размерами прямо в stdout.
2. Изучи полученную структуру воркспейсов, чтобы точно знать расположение файлов и пакетов.
3. Не сохраняй вывод в файлы на диск — читай его напрямую из вывода терминала.

## Персистентная карта проекта (docs/project-map/)

Помимо живого дерева через `repomix`, в репозитории может быть персистентная карта в `docs/project-map/`. Эта карта обновляется docs-reviewer агентом перед каждым code review.

### Структура
- `docs/project-map/README.md` — индекс, общая структура, список модулей
- `docs/project-map/<module>.md` — один файл на модуль/директорию верхнего уровня

### Шаблон MD-файла модуля

```markdown
---
module: <путь к модулю>
purpose: <назначение в одну строку>
key_files:
  - <путь> — <роль>
  - <путь> — <роль>
dependencies: [<зависимости>]
last_updated: <YYYY-MM-DD>
---

# <имя модуля>

## Структура
- `<файл>` — <описание>
- `<файл>` — <описание>

## Паттерны
- <используемые паттерны/конвенции>
```

### Что включать
- Структуру директорий (дерево модуля)
- Назначение модуля/директории
- Ключевые файлы и их роли
- Зависимости между модулями

### Что НЕ включать
- Implementation details
- API signatures
- Внутреннюю логику

### Когда обновлять
- Добавлены новые файлы или директории
- Удалены файлы или директории
- Переименованы файлы или директории
- Новые модули верхнего уровня

## Handoff файлы (docs/handoff/)

Контекст передаётся между сессиями через handoff-файлы — один файл на PR.

### Структура
- `docs/handoff/pr-<N>-<slug>.md` — handoff для PR #N

### Шаблон
```markdown
---
pr: <N>
title: <PR title>
---

## Что сделано
<2-3 строки>

## Почему
<1-2 строки>

## Pending
<что осталось, или "—">

## Watch out
<gotchas, или "—">
```

## ADR файлы (docs/decisions/)

Архитектурные решения сохраняются в ADR (Architecture Decision Records).

### Структура
- `docs/decisions/<NN>-pr-<N>-<slug>.md` — один файл на решение
- Numbering: `001`, `002`, `003`, ... (zero-padded, sequential)

### Шаблон
```markdown
# ADR-<NN>: <title>

## Статус
Accepted (<YYYY-MM-DD>)

## Контекст
<почему нужно было решение>

## Решение
<что решили>

## Альтернативы
- <вариант>: <почему не подошёл>
```

### Когда создавать ADR
- Новый паттерн или конвенция
- Архитектурное изменение (новый модуль, изменённые зависимости)
- Неочевидное решение (почему X, а не Y)

### Когда НЕ создавать ADR
- Bug fixes
- Refactoring without architectural change
- Documentation updates