explain-me

Files (2)

• SKILL.md
• visual.md

SKILL.md (first lines)

# Explain Me

Аудит-обзор проекта одним заходом: понять суть, как оно устроено и какого качества. Читатель отчёта видит проект впервые и хочет вывод, а не протокол.

Отчёт всегда на русском; имена файлов, код, цитаты и термины остаются в оригинале.

Общение в стиле `/set-voice` Skill tool: прямой, конкретный, каждая оценка привязана к файлу:строке. «Зона роста» без координаты не попадает в отчёт.

Для визуального представления используй инструкции из visual.md
Помещай каждый визуальный элемент рядом с коротким текстом, который он поддерживает. Оставляй только те вызовы, файлы, свойства, состояния и границы, которые нужны для иллюстрации текущей ситуации или для вариантов решения текущей дискуссии.
Ты можешь использовать один или несколько типов визуальных элементов из visual.md, в зависимости от того, что лучше иллюстрирует текущую ситуацию. И не перегружай отчёт визуальными элементами без необходимости.
Используй продуктовые цвета, типографику, отступы и компоненты; используй реальные метки и данные.


## Процесс

### 1. Цель

Корень проекта: аргумент команды или cwd. При `--focus подсистема` суб-агенты копают её глубоко, остальное обзорно.

Завершение: корень существует и содержит исходники.

### 2. Разведка

Быстрый осмотр корня (манифесты, README, верх дерева каталогов), чтобы узнать:

- стек и точки входа;
- есть ли значимый UI (роутер, `pages/`, `components/`, экраны);
- есть ли тесты и CI (`.github/workflows/`, конфиги);
- какие доки существуют: README, `docs/`, ADR, CHANGELOG, AGENTS.md/CLAUDE.md.

Завершение: известны стек, наличие UI, тестов и список док-файлов. Это вход для брифов суб-агентов.

### 3. Четыре суб-агента

Запусти четыре суб-агента параллельно (одним сообщением), чтобы они не пачкали контекст друг друга. Каждый возвращает сжатый отчёт на русском.

1. **Суть и архитектура.** Что за проект, какую задачу решает, как устроено: слои, ключевые модули, потоки данных, точки входа. Верни: абзац сути, архитектуру с путями файлов, 1-2 Mermaid-диаграммы (поток данных или слои).
2. **Зависимости и UI-путь.** Рантайм- и дев-зависимости: что критично, что подозрительно (заброшено, дублирует соседа, тянет половину экосистемы). Если разведка нашла значимый UI: основные пользовательские сценарии от входа до результата, с роутами и экранами. Верни: список зависимостей с пометками, сценарии пошагово.
3. **Качество и проблемы.** Тесты (есть ли, что реально покрывают), CI, обработка ошибок на доверенных границах, гигиена (линтер, secrets в репо, lock-файлы). Плюс архитектурные промахи и переусложнения по чеклисту 12 smells Фаулера (_Refactoring_, гл. 3): Mysterious Name, Duplicated Code, Feature Envy, Data Clumps, Primitive Obsession, Repeated Switches, Shotgun Surgery, Divergent Change, Speculative Generality, Message Chains, Middle Man, Refused Bequest. Чеклист это фильтр внимания, не протокол: находка попадает в ответ, только когда у неё есть влияние на проект, а не «где-то пахнет». Верни до 10 находок, каждая: файл:строка, что не так, чем грозит, Severity (`критично` / `важно` / `косметика`).
4. **Доки vs код.** Сверь всё, что заявляет поведение (README, `docs/`, ADR, CHANGELOG, docstrings, AGENTS.md/CLAUDE.md), с имплементацией. Правило находки: «док обещает X, код делает Y». Устаревшие команды установки, несуществующие фичи, конфиги, которых нет, считаются. Верни: каждая нестыковка с цитатой дока и путём к коду.

Завершение: четыре отчёта получены, у каждой находки агент 3 есть файл:строка и Severity.

### 4. Отчёт в чат

Агрегируй в Markdown с фиксированным скелетом:

1. **Что это за проект** — суть в одном абзаце.
2. **Архитектура** — high-level с визуалами: Mermaid для потоков, дерево файлов с комментарием ответственности у каталога, call-дерево для ключевого сценария.
3. **Зависимости** — с пометками из отчёта агента 2.
4. **Пользовательский путь** — если есть значимый UI; если нет, одна строка, почему секции нет.
5. **Качество и проблемы** — сигналы (тесты, CI, гигиена) коротко, затем находки по убыванию Severity.
6. **Документация vs код** — таблица или список: док → код → в чём разрыв.
7. **Вердикт** — 3-5 предложений: общая оценка качества проекта и топ-3 риска. Прямо: «ядро здоровое, периметр гниёт» полезнее сорока пунктов без ответа.

Завершение: все семь секций на месте, у каждой находки файл:строка и Severity.

### 5. HTML-версия

Собери тот же отчёт в self-contained HTML (Mermaid via CDN, Tailwind via CDN) и запиши в temp: `$TMPDIR` или `/tmp`, файл `explain-me-<имя-проекта>.html`. Открой (`xdg-open` / `open` / `start`) и назови абсолютный путь.

Завершение: файл записан, путь назван пользователю.

### 6. После отчёта

Предложи: опубликовать HTML через `/pubhup-publish` skill (только по явному согласию) и куда копнуть дальше. Копание идёт обычным диалогом, скилл на этом закончен.

From yet-an-other/skills, MIT.

More from yet-an-other/skills