129 lines
4.8 KiB
Markdown
129 lines
4.8 KiB
Markdown
---
|
||
name: get-project-map
|
||
description: 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-файла модуля
|
||
|
||
```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
|