Mermaid Architect — Полный навык работы с диаграммами и документацией
Версия 2.0 — Иерархическая архитектура с интеллектуальной оркестровкой
Мощный навык Claude Code для создания диаграмм Mermaid и проектных документов с использованием загрузки руководств по требованию, преобразования кода в диаграммы и утилит на Python.
Установка
Установка в один клик через Skilz Marketplace
Установите этот навык мгновенно из Skilz Marketplace:
skilz install SpillwaveSolutions_design-doc-mermaid/design-doc-mermaid
Ручная установка
Клонируйте репозиторий прямо в директорию навыков Claude Code:
# Перейдите в директорию навыков
cd ~/.claude/skills
# Клонируйте репозиторий
git clone https://github.com/SpillwaveSolutions/design-doc-mermaid.git
Проверка установки
После установки убедитесь, что навык доступен:
# Список установленных навыков
ls ~/.claude/skills/design-doc-mermaid
# Или спросите Claude Code
# «Покажи установленные навыки»
Что умеет этот навык
Интеллектуальное создание диаграмм:
- Диаграммы деятельности (рабочие процессы, бизнес-логика)
- Диаграммы развертывания (облачная инфраструктура, K8s, serverless)
- Архитектурные диаграммы (компоненты системы, микросервисы)
- Диаграммы последовательности (потоки API, взаимодействие сервисов)
- Полноценные проектные документы с встроенными диаграммами
Преобразование кода в диаграммы:
- Извлечение архитектуры из приложений Spring Boot
- Генерация диаграмм развертывания из конфигурационных файлов
- Создание диаграмм последовательности из вызовов методов
- Документирование ETL-пайплайнов и потоков данных
Управление диаграммами:
- Извлечение диаграмм Mermaid из файлов Markdown
- Проверка синтаксиса диаграмм с помощью mermaid-cli
- Преобразование диаграмм в изображения PNG/SVG
- Пакетная обработка целых директорий
Быстрый старт
Создание диаграммы деятельности
Пользователь: «Создай диаграмму деятельности для регистрации пользователя с верификацией email»
Навык выполнит:
- Загрузит
references/guides/diagrams/activity-diagrams.md - Использует шаблон паттерна регистрации
- Добавит символы Unicode (🔐 для безопасности, 📧 для email, ✅ для успеха)
- Применит высококонтрастное стилевое оформление
- Выдаст готовую диаграмму Mermaid
Генерация из кода
Пользователь: «Вот мой application.yml для Spring Boot — сгенерируй диаграмму развертывания»
Навык выполнит:
- Проанализирует конфигурацию (datasource, cache, security)
- Загрузит
references/guides/diagrams/deployment-diagrams.md - Загрузит
examples/spring-boot/README.md - Сопоставит конфигурацию с облачными ресурсами
- Сгенерирует диаграмму развертывания с характеристиками ресурсов
Создание проектного документа
Пользователь: «Создай проектный документ для API контактов»
Навык выполнит:
- Загрузит
assets/api-design-template.md - Загрузит необходимые руководства по диаграммам (последовательности, ER, архитектуры)
- Сгенерирует полный документ со встроенными диаграммами
- Сохранит его как
docs/design/api-contacts-v1-2025-01-13.md
Структура
Иерархическая организация
mermaid-architect/
├── SKILL.md # Главный оркестратор с деревом решений
├── README.md # Этот файл
├── CLAUDE.md # Инструкции для Claude Code
│
├── references/ # Справочные материалы
│ ├── mermaid-diagram-guide.md # Устаревшее общее руководство
│ └── guides/ # Специализированные руководства (загружаются по требованию)
│ ├── diagrams/
│ │ ├── activity-diagrams.md # ✅ Готово
│ │ ├── deployment-diagrams.md # ✅ Готово
│ │ ├── architecture-diagrams.md # ✅ Готово
│ │ └── sequence-diagrams.md # ✅ Готово
│ ├── code-to-diagram/
│ │ └── README.md # ✅ Готово (мастер-руководство)
│ ├── unicode-symbols/
│ │ └── guide.md # ✅ Готово (более 100 символов)
│ └── troubleshooting.md # ✅ Готово (28 типовых ошибок)
│
├── scripts/ # Утилиты на Python
│ ├── extract_mermaid.py # ✅ Извлечение и проверка диаграмм
│ └── mermaid_to_image.py # ✅ Конвертация в PNG/SVG
│
├── examples/ # Примеры для конкретных языков
│ ├── spring-boot/ # ✅ Готово
│ ├── fastapi/ # ✅ Готово
│ ├── react/ # ✅ Готово
│ ├── python-etl/ # ✅ Готово
│ ├── node-webapp/ # ✅ Готово
│ └── java-webapp/ # ✅ Готово
│
└── assets/ # Шаблоны проектных документов
├── architecture-design-template.md
├── api-design-template.md
├── feature-design-template.md
├── database-design-template.md
└── system-design-template.md
Ключевые особенности
1. Семантические символы Unicode
Каждая диаграмма использует осмысленные символы Unicode:
graph TB
User[👤 Клиент] --> Gateway[🌐 API Gateway]
Gateway --> Auth[🔐 Сервис аутентификации]
Gateway --> API[⚙️ API-сервис]
API --> DB[(💾 База данных)]
API --> Cache[(⚡ Redis)]
API --> Queue[📬 Очередь сообщений]
Queue --> Worker[⚙️ Фоновый обработчик]
Категории символов:
- Инфраструктура: ☁️ 🌐 🔌 📡 🗄️
- Вычисления: ⚙️ ⚡ 🔄 🚀 💨
- Данные: 💾 📦 📊 📈 🗃️
- Обмен сообщениями: 📨 📬 📤 📥 🐰
- Безопасность: 🔐 🔑 🛡️ 🚪 👤
- Мониторинг: 📝 📊 🚨 ⚠️ ✅ ❌
2. Высококонтрастное стилевое оформление
Все диаграммы используют доступные высококонтрастные цвета — подробнее см. в SKILL.md.
3. Утилиты на Python
Извлечение диаграмм
# Вывести список всех диаграмм в файле
python scripts/extract_mermaid.py document.md --list-only
# Извлечь в отдельные файлы .mmd
python scripts/extract_mermaid.py document.md --output-dir diagrams/
# Проверить все диаграммы
python scripts/extract_mermaid.py document.md --validate
# Заменить диаграммы ссылками на изображения (для Confluence)
python scripts/extract_mermaid.py document.md --replace-with-images \
--image-format png --output-markdown output.md
Конвертация в изображения
# Один файл
python scripts/mermaid_to_image.py diagram.mmd output.png
# Пользовательская тема и размер
python scripts/mermaid_to_image.py diagram.mmd output.svg \
--theme dark --background white --width 1200
# Пакетная конвертация директории
python scripts/mermaid_to_image.py diagrams/ output/ \
--format png --recursive
# Из стандартного ввода
echo "graph TD; A-->B" | python scripts/mermaid_to_image.py - output.png
Требования
Для генерации диаграмм
- Система навыков Claude Code (автоматически)
- Руководства и шаблоны (включены в этот навык)
Для проверки и конвертации изображений
# Установить mermaid-cli глобально
npm install -g @mermaid-js/mermaid-cli
# Проверить установку
mmdc --version
Для скриптов на Python
- Python 3.7+
- Дополнительные пакеты не требуются (используется только stdlib)
Путь обучения
Впервые работаете с диаграммами Mermaid?
- Начните с диаграмм деятельности — Прочитайте
references/guides/diagrams/activity-diagrams.md - Изучите символы Unicode — Прочитайте
references/guides/unicode-symbols/guide.md - Попробуйте пример — Используйте паттерны из
examples/spring-boot/ - Проверьте свою работу — Запустите
python scripts/extract_mermaid.py --validate
Нужно задокументировать существующий код?
- Определите фреймворк — Spring Boot, FastAPI, React и т.д.
- Загрузите руководство с примером — Прочитайте
examples/{your-framework}/README.md - Сопоставьте паттерны — Найдите аналогичные паттерны кода в примерах
- Сгенерируйте диаграммы — Используйте шаблоны из руководств
- Проверьте — Используйте скрипты валидации
Создание проектных документов?
- Выберите тип шаблона — Архитектура, API, Функциональность, База данных или Система
- Загрузите шаблон — Прочитайте из
assets/{type}-design-template.md - Заполните разделы — Замените заполнители реальным содержимым
- Добавьте диаграммы — Загружайте руководства по диаграммам по мере необходимости для каждого раздела
- Используйте символы — Украсьте текст символами Unicode
- Сохраните — Поместите в
docs/design/с временной меткой
Как работает иерархическая система
Традиционный подход (неэффективный)
- Загружается вся документация навыка (~50 КБ)
- ИИ обрабатывает все шаблоны и примеры
- Высокий расход токенов
- Медленное время ответа
Иерархический подход (эффективный)
- Пользователь делает запрос → ИИ анализирует намерение
- Активируется дерево решений → Определяет необходимые руководства
- Загружается только нужное → Читается конкретное руководство (~2–5 КБ)
- Генерируется результат → Используются целевые шаблоны
- Экономия токенов → Требуется в 10 раз меньше контекста
Пример потока
Пользователь: «Создай диаграмму развертывания для моей установки Docker Compose»
Дерево решений:
1. Анализ: «диаграмма развертывания» + «Docker Compose»
2. Определение: нужен deployment-diagrams.md
3. Загрузка: references/guides/diagrams/deployment-diagrams.md (2 КБ)
4. Поиск паттерна: существует шаблон Docker Compose
5. Генерация: с использованием шаблона + символов Unicode
6. Вывод: готовая диаграмма менее чем за 30 секунд
Использовано токенов: ~2 000 (против ~10 000 при традиционном подходе)
Статус завершения
✅ Готово:
- Оркестратор с иерархическим деревом решений
- Руководство по диаграммам деятельности с шаблонами
- Руководство по диаграммам развертывания (AWS, GCP, K8s, serverless, Docker)
- Руководство по символам Unicode (более 100 символов)
- Скрипт извлечения Mermaid с валидацией
- Скрипт конвертации Mermaid в изображения
- Примеры преобразования кода в диаграммы для Spring Boot
- Шаблоны проектных документов (5 типов)
- Система высококонтрастного стилевого оформления
🚧 В процессе:
- Примеры для FastAPI
- Примеры архитектуры компонентов React
- Примеры ETL-пайплайнов на Python
📋 Запланировано:
- Руководство по архитектурным диаграммам
- Руководство по диаграммам последовательности
- Мастер-руководство по преобразованию кода в диаграммы
- Примеры для Node.js/Express
- Примеры веб-приложений на Java
Вклад в развитие
Чтобы добавить новое руководство по типу диаграммы:
- Создайте руководство в
references/guides/diagrams/{type}-diagrams.md - Укажите:
- Когда использовать
- Базовый синтаксис
- Типовые паттерны (3–5 шаблонов)
- Примеры символов Unicode
- Лучшие практики
- Обновите дерево решений в
SKILL.md - Добавьте примеры с отображением кода
Чтобы добавить новый языковой пример:
- Создайте директорию в
examples/{framework}/ - Добавьте
README.md, содержащий:- Обзор фреймворка
- Архитектурную диаграмму из структуры
- Диаграмму развертывания из конфигурации
- Диаграмму последовательности из кода
- Диаграмму деятельности из логики
- Обновите таблицу преобразования кода в диаграммы в
SKILL.md
Лицензия
Часть Claude Code Skills — лицензия MIT
Связанные навыки
- confluence — Загрузка диаграмм в Confluence
- plantuml — Альтернативный формат диаграмм
Ссылки
- Репозиторий на GitHub
- Страница на Skilz Marketplace
- Официальная документация Mermaid
Версия: 2.0.0 Обновлено: 2025-01-13 Поддерживается: SpillwaveSolutions