# Diagramming

> Рисование диаграмм — там, где схема является рабочим языком области. Триггерься, когда ученик решает задачу, в которой нужна схема, говорит "нарисуй", "покажи на схеме", "как это выглядит", "диаграмма", работает над задачей со структурой/потоком, или когда ты сам объясняешь устройство чего-либо и визуал помог бы. Связка Mermaid (текст-исходник) + Excalidraw MCP (рендер/whiteboard). Учит рисовать слоями (C4-модель), читаемо, показывая главное и скрывая лишнее. Схема — не украшение, а инструмент ведения разговора и мышления.

- Skill: `infinity-kim/diagramming` (Agent Skill)
- Install (CLI): `npx skillmds@latest add infinity-kim/diagramming`
- Raw SKILL.md: https://api.skillmd.com/api/skills/infinity-kim/diagramming/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: infinity-kim (https://skillmd.com/u/infinity-kim)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/infinity-kim/diagramming

---


# Диаграммы

> **Опциональный скилл.** Он нужен в областях, где схема — естественный язык
> рассуждения (архитектура, процессы, потоки данных, модели предметной
> области, графы зависимостей). В областях, где визуала нет, доменный слой
> может его не подключать. Сами инструменты (Mermaid, Excalidraw, C4)
> универсальны и подходят для схем любой природы.

**Диаграмма — это не результат, а инструмент разговора**: она визуализирует рассуждение, чтобы его можно было обсуждать и критиковать. Поэтому умение рисовать читаемо — отдельный навык, который мы тренируем сознательно.

Ключевой принцип: **схема следует за рассуждением, не наоборот**. Сначала ученик проговаривает поток словами, потом это становится схемой. Не давай рисовать молча — это убивает think-aloud (главный наблюдаемый сигнал в областях без оракула).

## Два инструмента: Mermaid + Excalidraw

- **Mermaid** — диаграмма **текстом**. Ученик пишет схему как код: версионируется в git, диффается, и — главное — **заставляет вербализовать структуру**. Это формат-исходник.
- **Excalidraw** — рендер и whiteboard. Hand-drawn стиль удобен для живого разбора. Через MCP можно превратить mermaid в визуал и получить картинку для разбора.

### Mermaid: базовый синтаксис

```
graph LR
    A[Узел A] --> B[Узел B]
    B --> C[Узел C]
    B --> D[Узел D]
    C --> S[(Хранилище)]
    C -.->|опционально| E[Внешний компонент]
```

Нотация (универсальная, подписи зависят от области):
- `[Прямоугольник]` — основной элемент/шаг/компонент
- `[(Цилиндр)]` — хранилище/данные
- `-->` сплошная стрелка — прямая/синхронная связь
- `-.->` пунктир — асинхронный / опциональный путь
- `|подпись|` — что передаётся по стрелке
- `graph LR` (слева-направо) или `graph TD` (сверху-вниз)

<!-- DOMAIN:examples -->
<!-- Пример схемы конкретной области (System Design). Доменный слой заменяет своей. -->
```
graph LR
    U[Пользователи] --> LB[Load Balancer]
    LB --> W1[Web Server 1]
    LB --> W2[Web Server 2]
    W1 --> C[(Redis Cache)]
    W1 --> DB[(Master DB)]
    DB --> R[(Read Replica)]
    W1 -.->|статика| CDN[CDN]
```
<!-- /DOMAIN:examples -->

### Excalidraw MCP

Когда нужен whiteboard-визуал (для разбора, для reference-схемы):

- `create_from_mermaid` — превращает mermaid-текст в Excalidraw элементы на canvas
- `get_canvas_screenshot` — снимок canvas как картинку (для визуального разбора)
- `export_to_image` — экспорт PNG (для уроков/сохранения reference-схем)
- `batch_create_elements` — точная ручная сборка, если mermaid не хватает

**ВАЖНЫЙ нюанс инфраструктуры:** Excalidraw MCP требует запущенного **canvas-сервера на порту 3055**. Если он не поднят, `create_from_mermaid` падает с `ECONNREFUSED 127.0.0.1:3055`. Тогда:
1. Подскажи ученику запустить сервер (см. `docs/setup.md`).
2. **Fallback:** работай с mermaid-текстом прямо в ответе/`.md` — он читается и версионируется и без рендера.

Не блокируй обучение из-за неподнятого сервера. Mermaid-текст самодостаточен.

## C4-модель: рисуй слоями

Главная ошибка новичка — рисовать всё на одном уровне детализации. C4 даёт уровни абстракции (Simon Brown). Хотя C4 родом из архитектуры ПО, идея «уровней масштабирования» переносится на любую схему:

1. **Context** — система/предмет как чёрный ящик + кто с ней взаимодействует.
2. **Container** — крупные блоки. **Уровень большинства задач.**
3. **Component** — что внутри блока. Только при deep dive.
4. **Code** — самый детальный уровень. Обычно не нужен.

Правило: **начни с верхнего значимого уровня, углубляйся только туда, где это важно для обсуждения**. Не детализируй всё подряд — только тот блок, в который делаешь deep dive.

## Как вести ученика

1. **Сначала слова, потом схема.** «Опиши поток словами» → потом «теперь нарисуем это».
2. **От простого к сложному.** Базовая версия → добавили элемент → добавили связь. Каждый шаг — новый блок/стрелка, проговаривая зачем.
3. **Показывай главное, скрывай лишнее.** Спроси: «что на этой схеме важно для нашего вопроса, а что можно не рисовать?» — это тренирует абстрагирование.
4. **Читаемость:** поток слева-направо или сверху-вниз, хранилища внизу/сбоку, минимум пересечений стрелок, подписи на стрелках где неочевидно.

## Reference-диаграммы

Для типовых задач области можно сгенерировать эталонные схемы через `create_from_mermaid` → `export_to_image` и сохранить в `diagrams/`. Используй их как worked examples: показать готовую схему ПЕРЕД тем, как ученик рисует свою (Sweller — worked example первым для новой темы).

Но: не показывай эталон, если ученик ещё решает сам и не застрял — это лишит его генерации. Эталон — после попытки или для разбора.

## Типичные ошибки новичков

- **Рисует молча** — теряется think-aloud. Проси проговаривать.
- **Один уровень детализации** — мешает крупное и мелкое. Используй C4-слои.
- **Схема вместо рассуждения** — красивая картинка без обоснований. Схема следует за «почему».
- **Всё сразу** — рисует финальную сложную версию, минуя эволюцию. Веди от простого.
- **Перегруз стрелками** — нечитаемо. Скрывай неважное для текущего вопроса.

## Вопрос для проверки

После того как ученик нарисовал схему, задай вопрос, связывающий диаграмму с компетенцией области — например, попроси показать на схеме слабое место и то, что он бы изменил. Это превращает рисунок в наблюдение.

<!-- DOMAIN:examples -->
<!-- Пример проверочного вопроса (System Design). Доменный слой заменяет. -->
> «Покажи на ней, где узкое место (bottleneck) при росте трафика в 100 раз, и что бы ты добавил». (связывает диаграмму с scalability_thinking)
<!-- /DOMAIN:examples -->

## Связь с другими скиллами

- **`diagnostics`** — рисование = источник наблюдений (вербализация рассуждения, мышление о структуре)
- **`practice`** — диаграммы в практических задачах
- **`scaffolding`** — на новой задаче можно дать каркас-схему с пробелами (уровень 2)
- контентные скиллы области — нотация и смысл конкретных элементов на схеме