claude code excalidraw: Vẽ Diagram Tự Động Trong 5 Phút (2026)

Bởi Ông Bố IT · DevOps engineer, dùng Claude Code hằng ngày cho automation · Cập nhật 04/2026

Diagram architecture trong team bạn trông như thế nào? Nếu câu trả lời là “không có” hoặc “có nhưng outdated từ 3 tháng trước,” bạn không phải ngoại lệ. claude code excalidraw (excalidraw-diagram skill) là skill cho phép Claude Code tự vẽ architecture diagram chất lượng cao từ mô tả text, với self-validating loop để tự phát hiện và sửa lỗi layout trước khi deliver. Cài một lần, dùng mãi.

Mình đã thử skill này trên một dự án microservices có 6 services. Trước đó mình mất 45 phút vẽ sơ đồ trên Figma mỗi khi kiến trúc thay đổi. Sau khi dùng excalidraw-diagram skill, cùng bản vẽ đó Claude Code tạo xong trong 90 giây, file .excalidraw editable hoàn toàn, và mình chỉ cần chỉnh màu cho đúng brand.

Tại Sao Diagram Architecture Của Bạn Luôn Lạc Hậu?

Theo IcePanel State of Software Architecture Survey 2025 (khảo sát 75 kỹ sư kiến trúc), 87% teams dùng diagramming tools để document kiến trúc. Quan trọng hơn, 44% architects đã dùng AI cho các tác vụ documentation. Đây chính là lý do claude code excalidraw trở thành một trong những skills được tải nhiều nhất trong hệ sinh thái Claude Code trong 6 tuần đầu.

Vấn đề không phải là developer lười. Friction quá cao mới là nguyên nhân thật sự. Mở Figma, kéo shape, căn chỉnh mũi tên, export, paste vào Confluence. Làm lại từ đầu mỗi khi có sprint mới. Với effort như vậy, việc bỏ qua bước vẽ sơ đồ trở thành quyết định hợp lý của mọi người trong team.

Con số 37% teams đang thực sự tích hợp AI vào architecture workflow là điểm mấu chốt. 63% còn lại vẫn vẽ tay hoặc không vẽ gì cả. Đây là gap mà claude code excalidraw lấp vào: biến việc tạo sơ đồ từ một task mất 30-45 phút thành một lệnh mất 90 giây.

Lưu ý: IcePanel là công cụ diagramming có tính phí, cạnh tranh với Excalidraw. Số liệu trên từ khảo sát do IcePanel tự thực hiện với mẫu n=75 (quy mô nhỏ). Mình không có quan hệ thương mại với họ và trích dẫn vì đây là dữ liệu ngành duy nhất công bố về chủ đề này.

excalidraw-diagram Skill Làm Được Gì Mà ChatGPT Không Làm Được?

Excalidraw là công cụ vẽ dạng hand-drawn với 89,000 GitHub stars và 850,000 monthly active users. Khi kết hợp với Claude Code, bộ đôi claude code excalidraw tạo ra workflow automation hoàn chỉnh ngay trong terminal. Khác với Mermaid.js (5.7 triệu lượt tải mỗi tuần trên npm tính đến tháng 4/2026) tạo visualization từ text syntax để embed vào Markdown, Excalidraw cho phép visual editing sau khi tạo xong và output là file JSON chỉnh được hoàn toàn.

excalidraw-diagram skill đạt 2,200 stars sau 6 tuần, nổi bật nhờ 4 tính năng mà ChatGPT hay Claude thuần không có:

• Argue visually, không chỉ display: Sơ đồ tốt truyền đạt argument bằng cấu trúc, không chỉ label boxes. Fan-out cho one-to-many, timeline cho sequence, convergence cho aggregation. Skill có bộ thiết kế methodology riêng để enforce nguyên tắc này.
• Evidence artifacts: Các bản vẽ kỹ thuật tự động include real code snippets, actual JSON payloads, tên API và event thật thay vì generic “Input → Process → Output.” Visualization trở thành tài liệu dạy được, không chỉ render text.
• Self-validating loop: Playwright render pipeline cho Claude Code xem output của chính nó, phát hiện overlapping text, misaligned arrows, rồi tự sửa trước khi deliver. ChatGPT không thể thấy và sửa bản vẽ của mình.
• Brand-customizable: Toàn bộ màu sắc nằm trong một file color-palette.md. Thay 5 dòng hex code, mọi sơ đồ trong dự án theo đúng brand của team bạn.

The Isomorphism Test là cách kiểm tra nhanh skill áp dụng: nếu bỏ hết text trong sơ đồ, structure còn lại có communicate được concept không? Nếu không, skill sẽ redesign layout thay vì chỉ thay label khác nhau.

Bạn Cần Gì Trước Khi Bắt Đầu?

claude code excalidraw yêu cầu một số công cụ cơ bản. Nếu bạn chưa cài đặt Claude Code, làm bước đó trước. Skill chạy trong môi trường Claude Code local và cần thêm Python để xử lý render pipeline.

Yêu cầu:

• Claude Code đã cài và có API key Anthropic
• Python 3.8+ (để chạy Playwright renderer)
• uv (Python package manager của Astral), cài bằng pip install uv hoặc theo tài liệu uv (Astral)
• Git để clone repo
• ~130MB disk cho Chromium (Playwright tải về lần đầu)

Thời gian ước tính: Setup lần đầu 5-10 phút. Từ lần thứ hai trở đi, mỗi sơ đồ mất 90 giây đến 3 phút tùy độ phức tạp.

Cách Cài Đặt excalidraw-diagram Trong 5 Phút?

Bước 1: Clone Và Cài Skill

Cài đặt gồm 3 lệnh chạy tuần tự. Lệnh đầu clone repo, lệnh hai copy vào thư mục skills, lệnh ba setup render pipeline với Playwright.

1. Clone repository excalidraw-diagram-skill từ GitHub
2. Copy vào thư mục .claude/skills/ trong project hoặc home directory
3. Cài dependencies và download Chromium cho Playwright

# Lệnh 1: Clone skill repo
git clone https://github.com/coleam00/excalidraw-diagram-skill.git

# Lệnh 2: Copy vào ~/.claude/skills/ (personal scope, dùng mọi project)
cp -r excalidraw-diagram-skill ~/.claude/skills/excalidraw-diagram

# Lệnh 3: Cài dependencies và download Chromium
cd ~/.claude/skills/excalidraw-diagram/references
uv sync
uv run playwright install chromium

Bạn sẽ thấy: Sau khi chạy xong lệnh 3, terminal hiện thông báo “Chromium X.X.X downloaded to…” và thư mục ~/.claude/skills/excalidraw-diagram/ có file SKILL.md. Nếu thư mục .claude/skills/ chưa tồn tại, tạo thủ công bằng mkdir -p ~/.claude/skills trước.

Bước 2: Tùy Chỉnh Brand Colors Và Test Diagram Đầu Tiên

Trước khi gọi skill lần đầu, nên chỉnh brand colors để mọi sơ đồ sau này đúng màu của team. Toàn bộ màu sắc nằm trong một file duy nhất: references/color-palette.md. Đây là điểm thiết kế quan trọng của skill: bạn không cần sửa SKILL.md hay bất kỳ logic nào. Chỉ cần mở file đó và thay hex codes.

# Mở file color-palette.md trong editor
code ~/.claude/skills/excalidraw-diagram/references/color-palette.md

# Ví dụ thay primary color thành màu brand của team:
# Đổi dòng "Main: #6366f1" thành "Main: #4F6CF0"
# Không cần restart Claude Code, có hiệu lực ngay lệnh tiếp theo

Sau khi chỉnh màu, test skill lần đầu bằng lệnh đơn giản trong Claude Code:

# Mở Claude Code trong project của bạn
claude

# Test với sơ đồ đơn giản
/excalidraw-diagram Create a simple diagram showing a web app with frontend, backend, and database

Bạn sẽ thấy: Claude Code tạo file diagram.excalidraw và diagram.png trong thư mục hiện tại. Mở diagram.png để xem preview ngay, hoặc mở diagram.excalidraw tại excalidraw.com để chỉnh sửa bằng giao diện kéo thả. Màu primary trong sơ đồ sẽ theo brand color bạn vừa cài.

Làm Sao Viết Prompt Để AI Vẽ Đúng Sơ Đồ?

Khi dùng claude code excalidraw, skill phân biệt hai loại bản vẽ: Simple/Conceptual (giải thích concept trừu tượng) và Comprehensive/Technical (sơ đồ hệ thống thực tế với code examples). Cách viết prompt khác nhau rõ rệt cho từng loại.

Với Simple, mô tả concept là đủ:

/excalidraw-diagram Show the separation of concerns between UI, business logic, and data layer

Với Technical, bạn cần cung cấp context cụ thể. Pattern hiệu quả nhất là mô tả theo 3 phần: (1) các components và tên thật, (2) luồng data hoặc request giữa chúng, (3) loại bản vẽ muốn tạo:

/excalidraw-diagram Create a technical architecture diagram for a microservices system:
- API Gateway (Kong) routes to: User Service (Node.js), Order Service (Python), Payment Service (Go)
- All services connect to PostgreSQL
- Redis cache between API Gateway and services
- Show actual HTTP/gRPC protocol labels on arrows
- Include evidence artifact with sample API response JSON

Keyword “evidence artifact” trong prompt báo cho skill biết cần include code snippet hoặc JSON example bên cạnh components. Mình thấy đây là tính năng hữu ích nhất khi làm tài liệu onboarding cho team mới vào dự án.

Skill cũng có thể so sánh codebase với sơ đồ cũ để chỉ cập nhật phần thay đổi. Nếu bạn có file .excalidraw từ sprint trước, chỉ cần pass vào:

/excalidraw-diagram Compare current codebase against existing diagram at ./docs/architecture.excalidraw and update it

Tính năng incremental update này giải quyết chính xác vấn đề “diagram outdated” mà survey ghi nhận. Thay vì vẽ lại toàn bộ từ đầu, Claude Code đọc bản vẽ cũ, so sánh từng component với code hiện tại, chỉ thêm hoặc bớt những gì đã thay đổi.

Self-Validating Loop Hoạt Động Như Thế Nào?

Đây là tính năng kỹ thuật thú vị nhất của claude code excalidraw, và cũng là lý do output nhất quán hơn so với cách dùng Claude thuần hay các MCP alternatives hiện tại.

Flow hoạt động qua 4 bước tuần tự. Đầu tiên, Claude Code tạo Excalidraw JSON theo methodology của SKILL.md. Tiếp theo, Playwright renderer load JSON vào trình duyệt Chromium headless và render thành PNG. Sau đó, Claude Code đọc PNG đó và kiểm tra các lỗi layout phổ biến: text bị crop, mũi tên không thẳng, components chồng lên nhau, spacing không đều. Cuối cùng, nếu phát hiện lỗi, nó sửa JSON và render lại, lặp đến khi sơ đồ pass visual check.

Tại sao cần loop này? JSON generation của LLM không đảm bảo kết quả visual chính xác 100%. Một component có thể có width đúng trong JSON nhưng khi render cạnh component khác lại bị overlap. Self-validation bắt được những lỗi này trước khi bạn nhìn thấy. Cơ chế này tương tự cách sub-agents song song xử lý task phức tạp, nhưng ở đây là iterative loop thay vì parallel execution.

Cách debug nếu render pipeline không chạy:

# Kiểm tra Playwright hoạt động
cd ~/.claude/skills/excalidraw-diagram/references
uv run python render_excalidraw.py --test

# Nếu lỗi "chromium not found":
uv run playwright install chromium

Skill Hay MCP Server: Bạn Nên Chọn Gì?

Có 5 cách dùng AI để vẽ sơ đồ kiến trúc. Mỗi cách có trade-off khác nhau. Với claude code excalidraw, skill là lựa chọn phù hợp cho phần lớn developer cá nhân và team nhỏ vì setup đơn giản nhất và không cần infrastructure thêm.

MCP servers Claude Code là lựa chọn tốt hơn khi bạn cần sơ đồ tự cập nhật mỗi khi code commit. Nếu bạn muốn kết hợp excalidraw-diagram với claude-github skill để document kiến trúc ngay trong README của GitHub repo, hai skill này chạy hoàn toàn độc lập và có thể dùng tuần tự trong cùng một session.

Lỗi Nào Thường Gặp Và Cách Sửa?

Sau khi cài claude code excalidraw, có 5 lỗi phổ biến mà hầu hết developer gặp ít nhất một lần. Bảng dưới đây tổng hợp nguyên nhân và cách sửa nhanh nhất.

Nếu bạn muốn hiểu sâu hơn về cách SKILL.md hoạt động để có thể tự debug khi gặp lỗi ngoài danh sách trên, bài về tự tạo Claude Code skill giải thích cấu trúc và lifecycle của một skill từ đầu. Ngoài ra, xem bộ sưu tập skills tốt nhất để tìm các alternatives nếu workflow của bạn có nhu cầu khác.

Excalidraw Skill Liên Kết Với Ecosystem Claude Code Ra Sao?

Phần này giúp bạn hiểu rõ vị trí của excalidraw-diagram skill trong toàn bộ hệ sinh thái Claude Code năm 2026. Hiểu được mối liên kết giữa các thành phần giúp team tận dụng tối đa giá trị của skill này khi kết hợp với các tool khác trong workflow hằng ngày.

Trước khi cài skill chuyên dụng, người mới nên tham khảo Top 20 Claude Skills phổ biến nhất để hiểu vị trí của skill này trong hệ sinh thái rộng hơn. Excalidraw skill thường được liệt kê trong nhóm visual productivity, kết hợp tốt với các skill khác như tạo technical docs hoặc thiết kế system architecture. Pattern khôn ngoan là cài theo bộ skill có liên quan với nhau thay vì cài riêng lẻ từng skill, giúp team có workflow đồng bộ và hiệu quả hơn.

Đối với các task vẽ diagram định kỳ như cập nhật architecture diagram hằng tuần hoặc tạo overview diagram cho báo cáo định kỳ, kết hợp với Claude Code Routines mang lại hiệu quả cao. Cấu hình routine kích hoạt skill vào rạng sáng đầu tuần để có diagram mới nhất sẵn sàng cho buổi họp đầu tuần. Cách làm này tự động hóa hoàn toàn quá trình cập nhật visual docs, không phải nhớ chạy thủ công mỗi lần cần update.

Để tích hợp Excalidraw skill vào pipeline rộng hơn của Claude Code, bạn nên tham khảo các plugin chính thức của Claude Code. Một số plugin chính thức có khả năng tích hợp trực tiếp với Excalidraw skill, mang lại trải nghiệm liền mạch khi cần tạo nhiều loại visual docs khác nhau cho dự án. Đặc biệt hữu ích cho các team product muốn build pipeline documentation tự động hoàn chỉnh, từ ý tưởng ban đầu đến docs cuối cùng cho khách hàng.

Cuối cùng, để hiểu vị trí của skill này trong roadmap phát triển kỹ năng tổng thể, người mới nên đọc Claude Code Roadmap 8 cấp độ. Excalidraw skill thường được giới thiệu ở level 3-4 trong roadmap, sau khi bạn đã quen với các thao tác cơ bản và sẵn sàng cho các skill chuyên dụng hơn. Đầu tư 2-3 ngày làm quen với các skill cấp thấp hơn trước khi chuyển sang Excalidraw skill giúp người mới khai thác hiệu quả hơn các feature nâng cao.

Bài Học Vẽ Diagram Tự Động Cho Team VN?

Phần này tổng hợp 3 bài học quan trọng nhất rút ra từ 3 tháng vận hành Excalidraw skill cho nhiều dự án thực tế tại ongboit.com và một số khách hàng doanh nghiệp tại VN. Đây là kinh nghiệm thực chiến đáng được chia sẻ cho người mới bắt đầu áp dụng skill này vào workflow.

Bài học đầu tiên là về tầm quan trọng của việc cung cấp context đầy đủ cho Claude khi yêu cầu vẽ diagram. Nhiều người mới có xu hướng viết prompt quá ngắn gọn, dẫn đến diagram tạo ra không khớp với mong muốn thực tế. Pattern khôn ngoan là cung cấp đầy đủ thông tin về mục đích của diagram, audience, các yếu tố quan trọng cần làm nổi bật, visual style mong muốn. Đầu tư 10-15 phút viết prompt chi tiết ban đầu tiết kiệm hàng giờ chỉnh sửa thủ công về sau khi nhận được diagram không phù hợp.

Bài học thứ hai là về việc tận dụng self-validating loop của skill để cải thiện chất lượng diagram tự động. Excalidraw skill hiện đại có khả năng tự đánh giá diagram vừa tạo ra và đề xuất các cải thiện trước khi trả về kết quả cuối cùng. Tận dụng feature này bằng cách cấu hình self-validating loop với số lần iterate tối đa hợp lý, thường là 3-5 lần. Cách làm này cải thiện đáng kể chất lượng diagram mà không cần tăng đáng kể thời gian xử lý. Đặc biệt hữu ích cho các architecture diagram phức tạp có nhiều component cần được sắp xếp hợp lý để dễ đọc.

Một góc nhìn bổ sung quan trọng từ thực tế triển khai cho khách hàng tại VN là về tầm quan trọng của việc train team về văn hóa visual documentation. Nhiều team product VN có thói quen làm việc chủ yếu qua văn bản, ít quan tâm đến việc tạo diagram cho các kiến trúc phức tạp. Pattern khôn ngoan là tổ chức session đào tạo nội bộ 2-3 giờ cho mọi thành viên team về tầm quan trọng của visual docs, kèm theo các ví dụ thực tế về cách diagram giúp giảm thời gian giải thích architecture cho thành viên mới gia nhập. Sau khi team hiểu được giá trị của visual docs, việc tận dụng Excalidraw skill trở nên tự nhiên hơn nhiều.

Bài học cuối cùng là về việc tích hợp diagram tự động vào pipeline technical documentation của team. Diagram chỉ thực sự có giá trị khi được tích hợp vào docs kỹ thuật chính thức của dự án, không phải tạo ra rồi để rời rạc không có hệ thống. Pattern khôn ngoan là thiết lập thư mục riêng cho diagram trong docs repo của dự án, kèm theo naming convention rõ ràng và version qua git. Cách làm này biến mỗi diagram tự động thành tài sản dài hạn cho dự án, có thể tra cứu và cập nhật dễ dàng khi system architecture thay đổi theo thời gian.

Honest Limitations: excalidraw-diagram KHÔNG Làm Được Gì?

Mình dùng skill này 3 tháng cho ongboit + 2 dự án freelance. Đây là 5 limitation thực tế:

1. Không phải design tool thay Figma. Skill generate functional architecture diagram, không phải design polished cho marketing material. Visual fidelity chỉ tới mức editable .excalidraw, không có animation/transition/interactive prototyping.
2. Layout complex diagram thường lệch. Diagram ≥10 nodes hoặc nested groups thường có overlapping arrows/labels. Self-validating loop catch được 60-70% cases, còn lại phải manual adjust trong Excalidraw editor (free, web-based).
3. Không có realtime collab. File .excalidraw chỉ một người edit. Team workflow phải share qua Git OR convert sang Excalidraw Plus ($6/user/mo) hoặc Lucidchart cho collab. Skill không tự xử lý merge conflict.
4. Brand colors customization limited. Skill chấp nhận 4-6 brand colors, không support full Tailwind palette. Gradient, shadow, custom fonts không export tốt sang .excalidraw format (Excalidraw chỉ support hand-drawn aesthetic).
5. Vietnamese diacritics trong diagram OK nhưng wrap weird. Label dài tiếng Việt có dấu thường bị cut hoặc wrap không đẹp. Workaround: dùng English labels trong diagram, tiếng Việt chỉ trong figcaption + body prose.

Bottom line: skill này tốt cho architecture + flow diagram tech-team-internal, không phải design tool replacement. Hybrid workflow tốt nhất: skill generate baseline → mở Excalidraw editor adjust visual → export PNG cho doc/blog.

Câu Hỏi Thường Gặp

Những câu hỏi phổ biến nhất từ developers khi bắt đầu dùng claude code excalidraw và Claude Code skills cho workflow vẽ sơ đồ.

excalidraw-diagram khác gì Mermaid.js khi dùng với Claude Code?

Mermaid.js (5.7 triệu lượt tải mỗi tuần trên npm) tạo sơ đồ từ text syntax đơn giản, phù hợp để embed vào Markdown và tự render trong GitHub mà không cần cài thêm công cụ nào. claude code excalidraw tạo file JSON visual có thể chỉnh sửa sau khi tạo và share dưới dạng ảnh hoặc file editable. Chọn Mermaid khi cần embed vào README và không muốn sửa thêm. Chọn claude code excalidraw khi cần presentation-quality visualization hoặc khi team muốn chỉnh sửa sau khi AI tạo xong.

Cần biết JSON hay code Excalidraw để dùng skill này không?

Không cần. Skill xử lý toàn bộ JSON generation bên trong. Bạn chỉ cần mô tả sơ đồ bằng tiếng Anh hoặc tiếng Việt, skill tạo JSON, render thành PNG để validate layout, rồi deliver file .excalidraw và .png. Nếu muốn customize thêm, mở file .excalidraw trên excalidraw.com và chỉnh trực tiếp bằng UI kéo thả.

File diagram AI tạo ra có edit được không?

Được, hoàn toàn. File .excalidraw output là file editable bình thường, mở trên excalidraw.com hoặc Excalidraw desktop app. Bạn có thể thêm, bớt, di chuyển components, thay màu, thêm text, export thành PNG hoặc SVG. AI tạo draft, bạn fine-tune. Đây là lý do Excalidraw được chọn thay vì Mermaid: kết quả là artefact editable, không chỉ là ảnh tĩnh.

Windows có cài và chạy được không?

Có. Repo có install.ps1 riêng cho Windows và hướng dẫn cài uv trên Windows. Claude Code native support Windows 10+. Playwright và Chromium cũng chạy được trên Windows. Nếu gặp lỗi permission với PowerShell: chạy Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser trước, sau đó chạy lại install.ps1.

Skill có tự update sơ đồ khi code thay đổi không?

Không tự động, trừ khi bạn setup git hook hoặc MCP file-watcher riêng. Với skill, bạn chủ động gọi /excalidraw-diagram khi muốn update. Nhưng vì skill có tính năng incremental update (pass file .excalidraw cũ vào để so sánh với codebase hiện tại), quá trình cập nhật mất dưới 2 phút thay vì vẽ lại từ đầu. Nếu muốn automation hoàn toàn, xem GitHub Actions với Claude Code để setup pipeline tự động.

Có skill nào tương tự không?

Có 3 alternatives chính. ooiyeefei/ccc là skill do Yee Fei viết, tập trung vào Terraform và IaC codebase. Cách tiếp cận MCP (không phải skill) của DevelopersIO dùng Excalidraw MCP server thay vì file skill. Coleam00’s skill là lựa chọn tốt nhất về tính năng và documentation cho use case general-purpose.

Kết Luận

claude code excalidraw giải quyết một friction point cụ thể: sơ đồ kiến trúc luôn lạc hậu vì việc tạo mới có friction quá cao. Khi thời gian tạo sơ đồ giảm từ 45 phút xuống 90 giây, nó trở thành thứ bạn làm mỗi sprint thay vì bỏ qua mỗi quarter.

Điều mình thích nhất ở workflow này là tính minh bạch: bạn thấy rõ từng bước Claude Code thực hiện, từ lúc viết JSON đến lúc render PNG để tự kiểm tra. Không có black box. Nếu output chưa đúng ý, bạn có thể điều chỉnh prompt hoặc chỉnh thẳng vào file .excalidraw bằng giao diện kéo thả. Đây là sự khác biệt lớn so với các giải pháp AI khác mà kết quả là ảnh tĩnh không chỉnh được.

Bắt đầu với 3 lệnh: git clone, cp -r, uv sync. Sau đó gọi /excalidraw-diagram với mô tả hệ thống của bạn. Lần đầu mất 10 phút setup, lần sau mất 90 giây. Nếu bạn muốn hệ thống hóa toàn bộ workflow và tự tạo skill riêng cho team, tự tạo Claude Code skill là bước tiếp theo phù hợp để customize theo đúng nhu cầu của team bạn.