opencode-config/.opencode/skills/get-project-map/SKILL.md

name	description
get-project-map	Use when you need to view or update the current project folder/file structure (especially after creating/deleting files or switching branches), or understand package layout in the workspace. Also contains a template for maintaining docs/project-map/. Also when user says "структура проекта", "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-файла модуля

---
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

Шаблон

---
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)

Шаблон

# ADR-<NN>: <title>

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

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

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

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

Когда создавать ADR

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

Когда НЕ создавать ADR

• Bug fixes
• Refactoring without architectural change
• Documentation updates