Превращая тексты в схемы с помощью ИИ: полевые заметки по документированию побочного проекта

#Превращение текста в диаграммы с помощью ИИ: полевые заметки из документирования побочного проекта.

Диаграммы — очень удобный способ быстро показать архитектуру системы, но на практике их гораздо легче нарисовать один раз, чем поддерживать в актуальном состоянии. Когда сервис переезжает, очередь переименовывается или API‑шлюз заменяется очередной «лямбдой в трубочку», картинка в README или конференции начинает медленно лгать.

Так повторяется раз за разом: вы снова открываете Canvas-редактор или кондуитную доску в Notion, таскаете прямоугольники и стрелки, пока всё снова не выглядит прилично. И уже через пару спринтов история повторяется.

Эта статья — полевые заметки о том, как я попытался перестать перерисовывать диаграммы руками и переложил эту работу на AI‑инструменты, превращающие текст в картинки.

---

Что не так с ручными диаграммами в реальной жизни

Проблема №1: короткий срок жизни

У диаграммы, лежащей в файле README или в дизайн‑документе, есть «полураспад» примерно в два спринта. Как только начинаются изменения в архитектуре или инфраструктуре — переименование очереди, новый шард базы данных, новый ревизионный сервис — картинка перестаёт соответствовать реальности.

Приходится выбирать из двух плохих вариантов:

• постоянно перерисовывать — тратить время на ручную правку в визуальном редакторе;
• дать диаграмме загнить — и тогда она не только не помогает, но и дезинформирует новичков в команде.

Оба варианта дорого обходятся в долгосрочной перспективе.

Проблема №2: дорогостоящие изменения

Вручную правленная картинка не живёт рядом с кодом и конфигурацией. Это значит, что:

• изменения в архитектуре не отражаются в README автоматически;
• ревьюверы в пулл‑реквесте не видят разметки системы «как будет после слияния»;
• приходится синхронизировать изменения между кодом и документацией вручную.

Именно поэтому текстово‑ориентированные подходы (вроде Mermaid и ему подобных) набирают популярность в инженерных командах.

---

Как текстово‑диаграммные инструменты меняют расклад

Основная идея текстово‑диаграммных инструментов — сделать источником истины текстовое описание, а картинку считать производным артефактом.

Если архитектура описана в тексте:

• пересоздать картинку стоит секунды;
• текст лежит рядом с кодом — в том же репозитории, в том же файле README или /docs;
• картинку можно ревьюить как часть пулл‑реквеста: изменения в структуре системы видны в виде diff‑a текста, а не бинарной картинки.

В этом контексте AI‑инструменты выступают как помошник-переводчик: берут человеческое описание архитектуры или процесса и превращают его либо в текстовую нотацию (например, Mermaid), либо в готовую визуализацию.

---

Связка LLM + Mermaid: почти инженерный дефолт

Почему Mermaid

Mermaid — это текстовый формат описания диаграмм, который умеет рисовать схемы последовательностей, графы потоков данных, архитектурные схемы и т.п. Его ключевые плюсы в контексте код‑базы и дока:

• GitHub поддерживает его нативно в Markdown-файлах;
• он диффовый и ревьюемый в пулл‑риквесте;
• текст описания диаграмм можно версионировать и хранить в системе контроля версий.

Что я делал на LLM‑связке

Например, я описывал LLM примерно следующее текстом:

Запрос от клиента приходит через API‑шлюз в сервис авторизации,
затем проходит в основной backend‑сервис, который ходит в базу данных Postgres
и отправляет задачи в очередь задач Kafka. Отдельный воркер забирает задачи
из Kafka и пишет результат в лог‑сервис и кэш Redis.

И просил сгенерировать Mermaid‑разметку. В ответ получал что‑то вроде этого:

flowchart LR
    Client[\\\\\\\"Клиент (web/mobile)\\\\\\\"]
    Gateway[\\\\\\\"API-шлюз\\\\\\\"]
    Auth[\\\\\\\"Сервис авторизации\\\\\\\"]
    Backend[\\\\\\\"Основной бекенд\\\\\\\"]
    DB[\\\\\\\"Postgres\\\\\\\"]
    Q[\\\\\\\"Очередь задач Kafka\\\\\\\"]
    Worker[\\\\\\\"Воркер\\\\\\\"]
    Log[\\\\\\\"Лог-сервис\\\\\\\"]
    Cache[\\\\\\\"Redis\\\\\\\"]

    Client --> Gateway
    Gateway --> Auth
    Auth --> Backend
    Backend --> DB
    Backend --> Q
    Q --> Worker
    Worker --> Log
    Worker --> Cache

Этот код можно просто вставить в файл README.md или, например, docs/architecture.md и GitHub автоматически его отрендерит.

---

Что хорошо работает в этой связке

• Скорость изменения картинки:
  поменял текст в диаграмме — получил новую картинку при следующем просмотре.

• Диффы и ревью в пулл‑риквестах:
  если изменения в архитектуре требуют переименовать или удалить сервис — это видно прямо в diff-е как текстовые изменения.

• Интеграция с doc‑as‑code:
  диаграммы живут в том же репозитории и системе сборки документации, что и код.

Что ограничивает Mermaid

• Layout — не всегда предсказуем:
  Mermaid сам решает, где разместить блоки; при более чем десяти узлах схема легко может превратиться в «спагетти‑диаграмму».

• Не все типы диаграмм поддерживаются одинаково хорошо:
  например, для сложных UML‑диаграмм или высокоуровневых архитектурных views иногда нужно кастомизировать CSS‑семантику или использовать другие инструменты.

• Нужно знать базовый синтаксис:
  хотя LLM сильно помогает, иногда нужно подправить результат вручную или хотя бы понимать структуру разметки.

---

Napkin AI: когда нужна концепция, а не точная схема

Ещё один инструмент из экспериментов этого квартала — Napkin AI. Суть очень похожа на «запрос к дизайнеру»: пишешь абзацем, что хочешь показать на картинке, а он предлагает несколько вариантов визуализации.

Например, можно описать аналогичную архитектуру‑в‑одном абзаце:

Frontend отправляет запросы через API‑шлюз в backend‑сервис,
который ходит в базу данных и отправляет фоновые задачи в очередь.
Воркер асинхронно обрабатывает задачи и пишет результат в лог‑сервис и кэш.

На выходе получишь несколько вариантов картинки: например, как линейный поток, как сравнение двух подходов или даже временную шкалу выполнения задачи.

Что особенно хорошо работает в Napkin

• Для дизайн‑документов и концепций
  Когда нужно не столько точное соответствие схемы реальной архитектуре, сколько иллюстрация идеи (например, сравнение двух вариантов интеграции или эволюции архитектуры во времени).

• Несколько готовых стилистик
  Можно получить одну и ту же логику в виде разных визуализаций и выбрать тот вариант, который лучше ложится на текст документа.

---

Что не получилось и где не хватает точности

Из опыта этого эксперимента можно выделить несколько типичных ограничений текстово‑диаграммных инструментов:

• Сложность композиции
  В реальной проектной документации часто нужны не одна картинка, а несколько связанных схем (например, общая архитектура системы + детальный граф вызовов между сервисами). Переключаться между «общей картиной» и «детализацией по конкретной подсистеме» текстовыми инструментами не всегда удобно.

• Не‑идеальный автомат lay‑outа
  Как Mermaid, так и генеративные модели иногда не могут оптимально расставить элементы на схеме при большом количестве узлов или сложных связях.

• Не для всех типов диаграмм
  Например, для схемы инфраструктуры контейнеров кластера (Kubernetes, namespaces, ресурсы и т.п.) текстового описания «в абзаце» может быть недостаточно — лучше подходят специализированные инструменты или DSL‑подходы.

---

Практические рекомендации: как начать использовать связку текст → AI → диаграммы в своей проектной документации

Ниже — несколько конкретных шагов, которые можно попробовать уже на следующем проекте или сайд‑проекте.

1. Описать архитектуру простыми предложениями на русском или английском языке

Начните с текста «без синтаксиса», просто:

• кто от кого зависит,
• куда идут запросы,
• какие хранилища и очереди задействованы.

Примерно так:

Клиентское приложение (web) отправляет запросы через API‑шлюз в основной сервис,
который ходит в базу данных PostgreSQL и отправляет фоновые задачи в очередь Kafka.
Воркер забирает задачи из очереди и отправляет нотификации через внешний сервис уведомлений.

2. Использовать LLM‑модель как переводчик в текстовую нотацию диаграмм

Например, запросить:

> «Сгенерируй на основе текста ниже Mermaid‑разметку для диаграммы потока данных:»

и скопировать результат в код‑базу или в документацию.

---

3. Хранить диаграммы как код в отдельном файле или внутри README

Если диаграмма отдельно:

docs/
  architecture.md
README.md

Внутри docs/architecture.md можно хранить несколько диаграмм для разных уровней детализации:

## 1. Общая архитектура

```mermaid
flowchart LR
    Web[\\\\\\\"Web фронтенд\\\\\\\"] --> Gateway[\\\\\\\"API шлюз\\\\\\\"]
    Gateway --> Backend[\\\\\\\"Основной сервис\\\\\\\"]
    Backend --> DB[\\\\\\\"Postgres\\\\\\\"]
    Backend --> Q[\\\\\\\"Kafka\\\\\\\"]
    Q --> Worker[\\\\\\\"Воркер\\\\\\\"]
    Worker --> Notify[\\\\\\\"Сервис уведомлений\\\\\\\"]

...

---

### 4. Использовать Napkin‑подобные инструменты для концептуальной иллюстрации в дизайн‑документах

Если вы пишете дизайн‑док или прототипируете подход, разумно:

- нарисовать концептуальную иллюстрацию в Napkin‑подобном инструменте для быстрой картинки‑иллюстрации идеи;
- после реализации и утверждения архитектуры вывести каноническую схему уже текстовой нотацией в Mermaid и зафиксировать её в репозитории.

---