Claude Code + Excalidraw: səhv promptda idi

Excalidraw MCP adlanan iki şey var. Düzgününü seç.

Buna hələ heç nə quraşdırmamışdan büdrəyirlər, çünki iki layihə adı bölüşür və ayrı problemləri həll edir.

Rəsmi Excalidraw+ MCP chat widget-dir. Prompt yazırsan, diaqram söhbətin içinə axır, modelin bir neçə aləti olur. Excalidraw+ hesabından API açarı tələb edir. Söhbətdə birdəfəlik şəkil üçün yaxşıdır.

Community serveri, yctimlin/mcp_excalidraw, dəzgahdır. Daimi lokal canvas, elementləri tək-tək yaratmaq, oxumaq, yeniləmək və silmək üçün 26 alət və agentin öz nəticəsinə baxması üçün screenshot aləti. MIT lisenziyalı, öz maşınında Docker və ya Node üzərində işləyir, nə hesab, nə açar.

Kodlaşdırma agentinə yalnız ikincisi lazımdır, səbəb də məhz screenshot alətidir. Öz canvas-ını görməyən agent kor-koranə çəkir və nə çıxırsa sənə verir. Baxa bilən agent isə öz üst-üstə düşmələrini sən görməmişdən tutur. Yazının qalanı community serveri haqqındadır.

Claude Code-u Excalidraw-a qoşuruq

İki konteyner iki ayrı iş görür və onları qarışdırmaq ən çox rast gəlinən qurulum səhvidir. Canvas serveri lövhənin özüdür: veb interfeys, REST API və websocket sinxronizasiyası, daimi işləyir. MCP serveri Claude Code-un danışdığı körpüdür və birdəfəlikdir: sessiya üçün qalxır və hər dəyişikliyi canvas-a göndərir.

Əvvəlcə canvas:

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

http://localhost:3000 ünvanını aç, orada boş Excalidraw lövhəsi görünməlidir. Həmin sekmeni açıq saxla, sonra lazım olacaq.

İndi körpünü Claude Code-da qeydiyyata alırıq:

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

Agentin işinin yaddaşda qalıb yox olmaq əvəzinə sənin lövhəndə görünməsini məhz ENABLE_CANVAS_SYNC=true təmin edir.

Mənə iyirmi dəqiqəyə başa gələn tələ. Claude Code-u VS Code genişlənməsi kimi quraşdırıb CLI-ni ayrıca quraşdırmamısansa, ikinci əmr hər shell-də sınır:

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

Qlobal fayl yoxdur. CLI genişlənmənin içindədir, təxminən belə bir yolda: ...\extensions\anthropic.claude-code-2.1.226-win32-x64\resources\native-binary\claude.exe. Tam yol vasitəsilə claude mcp add dərhal işləyir.

Üzərinə nəsə qurmadan əvvəl iki məqam. Bu yolda versiya nömrəsi var, ona görə genişlənmənin növbəti yeniləməsi skript etdiyin hər şeyi sındıracaq - repozitoriyaya gedirsə, CLI-ni normal quraşdır. Və claude mcp add defolt olaraq local scope-a yazır: konfiq yalnız həmin layihə üçün ~/.claude.json-a düşür, --scope project verən və komandanın görəcəyi .mcp.json-a yox..

MCP serverinin həqiqətən qoşulduğunu haradan bilirsən?

"Added successfully" yoxlama deyil. Bir-birindən asılı olmayan üç şey var və hər biri doğru ya yanlış ola bilər. Məndə ikisi yaşıl yanırdı, üçüncüsü isə səssizcə işləmirdi.

Vaxtı üçüncüdə itirdim. CLI connected deyirdi, canvas cavab verirdi, işləyən sessiyada /mcp isə dörd yox, üç server göstərirdi. Heç nə xarab deyildi. Sessiya alət siyahısını başlanğıcda yükləyir, ona görə sonradan əlavə edilən server restart-a qədər görünməz qalır. Söhbətin ortasındasansa və konteksti itirmək istəmirsənsə, cari işi bitir və çəkməyə başlamazdan əvvəl restart et.

Tanımağa dəyən daha bir nasazlıq, çünki server problemi kimi görünür, amma deyil. Sessiyanın ortasında screenshot-lar 30 saniyədə timeout verməyə başladı, element sayı isə yenilənmədi. Server qaydasında idi, data yerində idi: brauzer sekmesi websocket bağlantısını səssizcə itirmişdi. Bağlı etiketlərin render olunması və şəkil ixracı frontend-də baş verir, ona görə həmin sekme susanda hər ikisi dayanır.

localhost:3000-i yenidən yükləmək hər ikisini dərhal həll edir. Hansı tərəfin sındığını müəyyən et, sonra düzəlt.

Nə istədim və nə aldım

backend-architecture.md onsuz da repozitoriyada vardı. Asılılıqları ilə on bir modul: auth, çoxvalyutalılıq, e-commerce, geri qaytarma və dəyişikliklər, təhlükəsizlik, ödənişlər, anbar, bildirişlər, hesabat, admin paneli. Əksər komandada olan və heç kimin təkrar oxumadığı planlaşdırma sənədi.

Ona görə açıq-aydın olanı istədim:

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

Gələnə bax. Bütün modullar yerindədir. Bütün asılılıqlar düzgündür. Auth girişi bağlayır, Refunds E-commerce-dən oxuyur, hesabat xətləri tək istiqamətdə gedir. Sistemin təsviri kimi dəqiqdir.

İndi isə onunla bir suala cavab verməyə çalış. Geri qaytarma gələndə nə baş verir? Göz 4. Refunds & Amendments-dən başlayır, üfüqi oxla 3. E-commerce-ə keçir, sonra aşağıda haradasa 2. Multi-currency-ni axtarır, sonra sağda 7. Payments-ə qayıdır, bu vaxt üç narıncı punktir xətt həmin yolu kəsir, boz hesabat xətləri isə küncə gedərkən hər şeyin üstündən keçir. authorized və approves bir ifadə kimi oxunacaq qədər yaxın dayanıb.

Səhv yoxdur. Oxumaq mümkün deyil.

Şəkli böyüt

Süni intellekt arxitektura diaqramlarını niyə qarışıq çəkir?

Çünki prompt məzmunu təsvir edir, forma haqqında heç nə demirdi, agent də yalnız soruşulan şeyi optimallaşdırdı: hər şeyi daxil etmək və düzgün birləşdirmək. Bunu qüsursuz etdi. Oxunaqlılıq tapşırıqda ümumiyyətlə yox idi.

Bir müddət simptomları düzəltdim: bu etiketi tərpət, o birini qısalt, qutunu sürüşdür. Bir az yaxşılaşdı və oxunmaz qaldı, bu isə səhv məsələ üzərində işlədiyinin dəqiq əlamətidir.

Vəziyyəti təsvir etmək yox, göstərmək dəyişdi. İki referans diaqramı şəkil kimi verdim: Netflix arxitektura xəritəsi və gateway ilə qruplaşdırılmış domen konteynerləri olan domen yönümlü backend sxemi. Bir keçiddə düzülüş yerinə düşdü, hər iki referansın arxasındakı prinsip isə daha yaxşı marşrutlaşdırma deyildi:

Təmiz diaqramlar uzun oxları yaxşı marşrutlaşdırmır. Onların uzun oxu demək olar ki, yoxdur.

Oxumaqdan zövq aldığın istənilən arxitektura diaqramında oxları say. İstinad backend xəritəsində iyirmi beş qutuya səkkiz ox düşürdü. Məndə on birə iyirmi. Bütün fərq bu nisbətdədir və üç qaydadan çıxır.

Yuvalanma oxların yerini tutur. commerce domain adlı konteynerin içindəki qutu onsuz da kommersiyaya aid olduğunu deyir. Eyni şeyi deyən ox canvas boyu bir xəttə başa gəlir və heç nə qazandırmır.

Hər əlaqələndirici düz bucaqlıdır və qısa qalır. Diaqonal yoxdur. Diaqonal səhifənin dirsəkdən daha çox hissəsini kəsir, deməli daha çox şeylə toqquşur.

Hər zolaqda bir axın. Hər uçdan-uca yola öz üfüqi zolağını ver. Ayrı zolaqlardakı axınlar nə qədər əlavə etsən də struktur olaraq toqquşa bilmir. Miqyaslanan qayda budur: ilk ikisi bugünkü diaqramı təmizləyir, bu isə on ikinci modul gələndə də təmiz saxlayır.

Köçürə biləcəyin prompt

Agentini arxitektura sənədinə yönəlt və bunu yapışdır. Üç qayda artıq içindədir ki, sən onları mənim kimi kəşf etməli olmayasan.

Başqa dildə işləsən belə promptu ingiliscə saxla - agent onu daha yaxşı emal edir, modul adların da yəqin onsuz ingiliscədir.

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.

Buradakı iki sətir qalanlarından çox iş görür və hər ikisini atmaq asandır.

read_diagram_guide serverin öz stil bələdçisini qaytaran alətidir: hex dəyərləri ilə palitra, minimum forma ölçüləri, ox bağlama qaydaları, anti-pattern siyahısı. Pulsuz keyfiyyətdir, amma sən istəməsən agent onu çağırmayacaq.

Screenshot təlimatı ona görə vacibdir ki, agent öz canvas-ını görə bilir. Ona baxdır. Mənimki gözümdən qaçacaq iki üst-üstə düşməni tutdu və mənə heç nə göstərməmişdən əvvəl düzəltdi.

İlk nəticə hələ də çox sıxdırsa, işə yarayan davamı marşrutlaşdırma xahişi deyil, həcm xahişidir: bunu sistem icmalına və ayrı axın diaqramlarına böl.

What is this duo actually good for?

Eyni markdown faylı, eyni modullar, eyni alət. Bir diaqram yerinə iki.

Sistem icmalı hörümçək torundan çıxdı. Punktir Security sərhədi backend-i əhatə edir, çünki təhlükəsizlik kəsişən məsələdir və ondan on bir ox çəkmək həmişə səhv şəkil idi. Auth giriş sütununda dayanır. Üç konteyner - commerce domain, money domain, platform domain - öz modullarını saxlayır, mənsubiyyət isə bir ox belə xərcləmir. Xarici ödəniş provayderləri təhlükəsizlik sərhədinin kənarındadır, tam yerində, və içəri bir düzbucaqlı oxla girir.

Sonra altı axın zolağı, hər uçdan-uca yola bir dənə: baxış və checkout, geri qaytarma və dəyişiklik, MFA ilə giriş, işçi əməliyyatı, provayder webhook-u, hesabat. Hər biri soldan sağa bir hekayə kimi oxunur.

Addımların altındakı qeydlər gözlədiyimdən vacib çıxdı. 2. Multi-currency yazılmış qutu sənə yeni heç nə demir. Eyni qutu geri qaytarma zolağında, altında alış zamanı götürülmüş məzənnə snapshot-unu yenidən istifadə edir qeydi ilə, artıq görünən dizayn qərarıdır. Həmin zolağı oxuyan hər kəs indi bilir ki, biz bugünkü deyil, ilkin məzənnə ilə qaytarırıq. Belə şeylər adətən bir mühəndisin başında yaşayır, o məzuniyyətə çıxan həftəyə qədər.

Sistemin şəkli ilə sistem haqqında sənəd arasındakı fərq elə budur.

Şəkli böyüt

Şəkli böyüt

Bu tandem əslində nəyə lazımdır?

Üç şey, və yalnız birini gözləyirdim.

Onboarding. Yeni backend mühəndisi geri qaytarma yolunu repozitoriya boyu səpələnmiş fayllardan yığmaq əvəzinə bir dəqiqəyə izləyir. Açıq-aydın, real və ən böyüyü deyil.

Dizayn müzakirəsi. Məni təəccübləndirən bu oldu. Geri qaytarma zolağı başdan-sona düzüləndə addımların altındakı qeydlər heç vaxt dilə gətirmədiyim bağlılığı aydın etdi: geri qaytarmalar alış zamanı götürülən məzənnə snapshot-undan asılıdır, deməli həmin snapshot geri qaytarma pəncərəsi açıq qaldığı müddətdə yaşamalıdır. Sistemdə bu həmişə belə idi. Sadəcə ondan asılı olan şeyin yanında yazılmış halda heç görməmişdim. Səni öz dizaynınla mübahisə etməyə vadar edən diaqram, onu sənədləşdirəndən dəyərlidir.

Backend mühəndisi olmayanlarla danışmaq. Frontend, məhsul, imza atan adam. Əl ilə çəkilmiş üslub burada real iş görür: cilalanmış korporativ diaqram hər qutunun dəqiqliyinə irad tutmağa çağırır, eskiz isə dizayn haqqında söhbətə. Eyni məlumat, tamamilə fərqli görüş.

Dürüst qiymət odur ki, ilk cəhd uğursuz olacaq və on dəqiqə yox, bir axşam ayırmaq lazımdır. Əvəzində .excalidraw faylı kodun yanında yaşayır və agent onu yeniləyə bilir, əlimlə çəkdiyim heç bir diaqram haqqında bunu deyə bilmərəm. Onlar çəkdiyim gün dəqiq idi və elə həmin gündən köhnəlməyə başlayırdı.

Növbəti sınamaq istədiyim: main-ə hər merge-də diaqramı CI-da yenidən yaratmaq və commit olunmuş versiya ilə diff etmək ki, arxitektura sənədi arxitekturadan səssizcə uzaqlaşa bilməsin.