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 (сверху-вниз)

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]

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-слои.
• Схема вместо рассуждения — красивая картинка без обоснований. Схема следует за «почему».
• Всё сразу — рисует финальную сложную версию, минуя эволюцию. Веди от простого.
• Перегруз стрелками — нечитаемо. Скрывай неважное для текущего вопроса.

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

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

«Покажи на ней, где узкое место (bottleneck) при росте трафика в 100 раз, и что бы ты добавил». (связывает диаграмму с scalability_thinking)

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

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