a8f9aa0bc6
* feat: migrate .opencode/ config from opencode * refactor: rename repo refs and sanitize for public * docs(handoff): add pr-7 handoff + ADR-002 * docs(handoff): fix PR number * docs: update project map with .opencode/ structure --------- Co-authored-by: opencode-agent <agent@slaid098.dev>
128 lines
4.8 KiB
Markdown
128 lines
4.8 KiB
Markdown
---
|
||
name: get-project-map
|
||
description: Используй этот навык, когда тебе нужно увидеть или актуализировать текущую структуру папок и файлов проекта (особенно после создания/удаления файлов или переключения веток), либо понять расположение пакетов в воркспейсе. Также содержит шаблон для поддержки docs/project-map/.
|
||
---
|
||
|
||
# Навык получения карты проекта (Project Map)
|
||
|
||
Этот навык позволяет мгновенно получить актуальное дерево каталогов всего репозитория с учетом `.gitignore` без загрузки содержимого самих файлов в контекст.
|
||
|
||
## Команда для выполнения:
|
||
Запусти в терминале следующую команду:
|
||
`repomix --no-files --stdout`
|
||
|
||
## Твои действия:
|
||
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>
|
||
merged: <YYYY-MM-DD>
|
||
---
|
||
|
||
## Что сделано
|
||
<2-3 строки>
|
||
|
||
## Почему
|
||
<1-2 строки>
|
||
|
||
## Pending
|
||
<что осталось, или "—">
|
||
|
||
## Watch out
|
||
<gotchas, или "—">
|
||
```
|
||
|
||
## ADR файлы (docs/decisions/)
|
||
|
||
Архитектурные решения сохраняются в ADR (Architecture Decision Records).
|
||
|
||
### Структура
|
||
- `docs/decisions/<NN>-<title>.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
|