Claude Code + Excalidraw: виноват prompt

Excalidraw MCP бывает двух видов. Нужен правильный.

На этом спотыкаются еще до установки, потому что два проекта делят название и решают разные задачи.

Официальный Excalidraw+ MCP это чат-виджет. Пишете промпт, диаграмма прилетает прямо в переписку, у модели пара инструментов. Нужен API-ключ от аккаунта Excalidraw+. Годится для разовой картинки в чате.

Community-сервер, yctimlin/mcp_excalidraw, это верстак. Постоянный локальный холст, 26 инструментов для поэлементной работы и скриншот, чтобы агент мог посмотреть на собственный результат. Лицензия MIT, работает на вашей машине через Docker или Node, без аккаунта и без ключа.

Кодовому агенту нужен только второй, и причина именно в скриншоте. Агент, который не видит собственный холст, рисует вслепую и отдает вам что получилось. Агент, который умеет посмотреть, поймает свои наложения раньше, чем вы их увидите. Все дальше в посте про community-сервер.

Подключаем Claude Code к Excalidraw

Два контейнера делают разную работу, и путаница между ними это самая частая ошибка настройки. Канвас-сервер это сама доска: веб-интерфейс, REST API и синхронизация по вебсокету, работает постоянно. MCP-сервер это мост, с которым говорит Claude Code, и он одноразовый: поднимается на сессию и отправляет каждое изменение на холст.

Сначала канвас:

docker run -d -p 3000:3000 --name excalidraw-canvas \
  ghcr.io/yctimlin/mcp_excalidraw-canvas:latest

Откройте http://localhost:3000, там должна быть пустая доска Excalidraw. Оставьте вкладку открытой, дальше это пригодится.

Теперь регистрируем мост в Claude Code:

claude mcp add excalidraw -- docker run -i --rm \
  -e EXPRESS_SERVER_URL=http://host.docker.internal:3000 \
  -e ENABLE_CANVAS_SYNC=true \
  ghcr.io/yctimlin/mcp_excalidraw:latest

Именно ENABLE_CANVAS_SYNC=true делает так, что работа агента появляется на вашей доске, а не живет в памяти и исчезает.

Ловушка, стоившая мне двадцати минут. Если вы поставили Claude Code как расширение VS Code и отдельно CLI не ставили, вторая команда падает в любом шелле:

/usr/bin/bash: line 1: claude: command not found
claude : The term 'claude' is not recognized as the name of a cmdlet...

Глобального бинарника нет. CLI лежит внутри расширения, по пути вроде ...\extensions\anthropic.claude-code-2.1.226-win32-x64\resources\native-binary\claude.exe. Через полный путь claude mcp add отрабатывает сразу.

Два момента, прежде чем на этом что-то строить. В пути есть номер версии, поэтому следующее обновление расширения сломает все, что вы наскриптовали - если это идет в репозиторий, ставьте CLI нормально. И claude mcp add по умолчанию пишет в local scope: конфиг оказывается в ~/.claude.json только для этого проекта, а не в .mcp.json, который дает --scope project и который увидит команда.

Как понять, что MCP-сервер правда подключился?

"Added successfully" это не проверка. Есть три независимые вещи, каждая из которых может быть правдой или нет, и у меня две горели зеленым, пока третья тихо не работала.

Время я потерял на третьей. CLI говорил connected, холст отвечал, а /mcp в работающей сессии все равно показывал три сервера вместо четырех. Ничего не сломалось. Сессия загружает список инструментов на старте, поэтому сервер, добавленный позже, остается невидимым до перезапуска. Если вы посреди диалога и не хотите терять контекст, доделайте текущее и перезапуститесь до того, как начнете рисовать.

Еще одна поломка, которую стоит узнавать в лицо, потому что выглядит она как проблема сервера, а это не она. В середине сессии скриншоты начали падать по таймауту в 30 секунд, а количество элементов перестало обновляться. Сервер был в порядке, данные на месте: вкладка браузера тихо потеряла вебсокет. Отрисовка привязанных подписей и экспорт картинки живут во фронтенде, поэтому когда эта вкладка замолкает, встает и то и другое.

Перезагрузка localhost:3000 снимает оба симптома мгновенно. Сначала поймите, какая сторона сломалась, потом чините.

Что я попросил и что получил

backend-architecture.md уже лежал в репозитории. Одиннадцать модулей с зависимостями: auth, multi-currency, e-commerce, возвраты и правки, безопасность, платежи, склад, уведомления, отчетность, админка. Тот самый планировочный документ, который есть почти у всех и который никто не перечитывает.

Я попросил очевидное:

Read backend-architecture.md and draw an architecture diagram of this backend,
showing the modules and how they connect.

Посмотрите, что вернулось. Все модули на месте. Все зависимости верные. Auth закрывает доступ, Refunds читает из E-commerce, линии отчетности идут в одну сторону. Как описание системы это точно.

А теперь попробуйте ответить по ней на вопрос. Что происходит при возврате? Глаз стартует на 4. Refunds & Amendments, уезжает по горизонтали в 3. E-commerce, потом ищет 2. Multi-currency где-то внизу, потом 7. Payments обратно справа, и все это время три оранжевые пунктирные линии режут этот путь, а серые линии отчетности пересекают вообще все по дороге в угол. authorized и approves стоят так близко, что читаются одной фразой.

Ошибок нет. Читать невозможно.

Открыть изображение

Почему ИИ рисует кашу вместо схемы?

Потому что промпт описывал содержание и молчал про форму, и агент оптимизировал единственное, о чем его спросили: включить все и правильно соединить. Это он сделал безупречно. Читаемости в задании не было.

Я какое-то время чинил симптомы: подвинуть подпись, сократить другую, сдвинуть блок. Стало чуть лучше и осталось нечитаемым, а это верный признак, что вы решаете не ту задачу.

Ситуацию изменил показ вместо описания. Я передал два референса картинками: карту архитектуры Netflix и доменно-ориентированную схему бэкенда с гейтвеем и сгруппированными доменными контейнерами. За один проход раскладка стала правильной, а принцип, общий для обоих референсов, оказался не в удачной трассировке:

Чистые схемы не прокладывают длинные стрелки хорошо. У них почти нет длинных стрелок.

Посчитайте стрелки на любой архитектурной схеме, которую вам приятно читать. В референсной схеме бэкенда было около восьми стрелок на двадцать пять блоков. У меня двадцать на одиннадцать. Вся разница в этом соотношении, а берется она из трех правил.

Вложенность заменяет стрелки. Блок внутри контейнера с подписью commerce domain уже говорит, что относится к коммерции. Стрелка, которая скажет то же самое, стоит линии через весь холст и не дает ничего.

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

Один поток на дорожку. Каждому сквозному пути своя горизонтальная полоса. Потоки в разных полосах не могут столкнуться структурно, сколько бы вы их ни добавили. Именно это правило масштабируется: первые два делают сегодняшнюю схему чище, а это держит ее чистой, когда появится двенадцатый модуль.

Промпт, который можно скопировать

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

Оставьте prompt на английском, даже если работаете на другом языке - агент обрабатывает его лучше, а названия ваших модулей и так наверняка английские.

Read <YOUR-ARCHITECTURE-DOC.md> and draw an architecture diagram of this system
on the Excalidraw canvas.

LAYOUT RULES - these matter more than completeness:

1. Group before you connect. Put related modules inside labelled containers
   (for example: commerce domain, money domain, platform domain). Nesting a box
   inside a container already expresses that it belongs there, so do not also
   draw an arrow saying the same thing. Cross-cutting concerns like security
   wrap everything as an outer dashed boundary rather than connecting to each
   module individually.

2. Every connector is orthogonal and short. Right angles only, no diagonals.
   If two things need a long connector, they are probably in the wrong place -
   move them closer instead of drawing a longer line.

3. One flow per lane. After the system overview, add a separate horizontal lane
   for each end-to-end path (checkout, refund, sign-in, admin action, webhook,
   reporting). Each lane reads left to right as one story. Flows in separate
   lanes cannot collide with each other.

4. Annotate every step. Under each module box in a flow lane, add a short note
   saying what that module does IN THAT FLOW - not what the module is. Write
   "locks the exchange rate at purchase", not "handles currency".

5. Nothing overlaps. No two boxes, no label on top of another label, no
   connector passing through a box, no panel straddling the edge of a container.

BEFORE YOU START: call read_diagram_guide and follow its conventions.

WHEN YOU ARE DONE: take a screenshot of the canvas and look at it. Check for
overlapping labels, connectors crossing each other, and any path a reader
cannot follow from start to finish. Fix what you find, then show me the result.

Две строчки здесь работают больше остальных, и обе легко выкинуть.

read_diagram_guide это инструмент сервера, который отдает его собственный стайлгайд: палитру с hex-значениями, минимальные размеры фигур, правила привязки стрелок, список антипаттернов. Бесплатное качество, но сам агент его не вызовет, пока не попросишь.

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

Если первый результат все равно слишком плотный, работает не просьба про routing, а просьба про объем: раздели на обзор системы плюс отдельные диаграммы потоков.

Что вернулось со второго раза

Тот же markdown-файл, те же модули, тот же инструмент. Две диаграммы вместо одной.

Обзор системы перестал быть паутиной. Пунктирная граница Security оборачивает бэкенд, потому что безопасность это сквозная забота и одиннадцать стрелок из нее всегда были неправильной картинкой. Auth стоит на входной колонке. Три контейнера - commerce domain, money domain, platform domain - держат свои модули, и принадлежность не стоит ни одной стрелки. Внешние платежные провайдеры вынесены за границу безопасности, ровно туда, где им и место, и заходят внутрь одной прямоугольной стрелкой.

Дальше шесть дорожек потоков, по одной на сквозной путь: просмотр и чекаут, возврат и правка заказа, вход с MFA, действие сотрудника, вебхук провайдера, отчетность. Каждая читается слева направо как одна история.

Подписи под шагами оказались важнее, чем я рассчитывал. Блок с надписью 2. Multi-currency не сообщает ничего нового. Тот же блок в дорожке возврата с пометкой переиспользует снапшот курса, взятый при покупке это уже видимое проектное решение. Любой, кто прочитал эту дорожку, теперь знает, что возвращаем мы по исходному курсу, а не по сегодняшнему. Обычно такие вещи живут в голове одного инженера ровно до недели, когда он уходит в отпуск.

В этом и разница между картинкой системы и документом о ней.

Открыть изображение

Открыть изображение

Зачем эта связка на самом деле нужна?

Три вещи, и только одну из них я ожидал.

Onboarding. Новый backender трассирует путь возврата за минуту вместо того, чтобы собирать его из файлов по всему репозиторию. Очевидно, реально и не главное.

Ревью архитектуры. Вот это меня удивило. Когда дорожка возврата разложена от начала до конца, подписи под шагами сделали очевидной связность, которую я никогда не проговаривал: возвраты зависят от snapshot курса, взятого при покупке, а значит этот snapshot обязан жить столько же, сколько открыто окно возврата. В системе это всегда было так. Просто я ни разу не видел это записанным рядом с тем, что от него зависит. Схема, которая заставляет вас спорить с собственным дизайном, стоит больше, чем схема, которая его документирует.

Разговор с теми, кто не backender. Фронтенд, продукт, тот, кто подписывает. Рисованный стиль тут реально работает: вылизанная корпоративная диаграмма провоцирует придирки, все ли квадратики верные, а набросок провоцирует разговор про дизайн. Та же информация, совершенно другая встреча.

Честная цена в том, что первая попытка будет неудачной и закладывать надо вечер, а не десять минут. Зато файл .excalidraw лежит рядом с кодом и агент умеет его обновлять, чего я не могу сказать ни про одну схему, которую рисовал руками. Те были точными в день рисования и начинали протухать сразу же.

Что хочу попробовать дальше: пересобирать схему в CI на каждый merge в main и диффать с закоммиченной версией, чтобы документ об архитектуре не мог тихо разойтись с самой архитектурой.