Ghi chú của người dịch: Bài này lược dịch và biên tập từ Using Claude Code: The Unreasonable Effectiveness of HTML của Thariq Shihipar (Claude Code team). Mình giữ ngôi thứ nhất của tác giả và chỉ chỉnh lại tone cho người đọc Việt.
Markdown đang là định dạng mặc định mà các agent dùng để giao tiếp với mình. Nó đơn giản, đâu cũng đọc được, có hỗ trợ chút ít định dạng văn bản, và bạn ngồi sửa tay cũng dễ. Claude thậm chí còn khá giỏi vẽ sơ đồ bằng ký tự ASCII trong file markdown.
Nhưng càng dùng các agent mạnh hơn, mình càng thấy markdown gò bó. File markdown dài hơn 100 dòng là mình đọc không vào. Mình muốn trực quan hơn, có màu, có sơ đồ, và muốn chia sẻ cho người khác cũng dễ.
Mình cũng dần không còn tự sửa mấy file này nữa — chúng dần trở thành bản mô tả, tài liệu tham khảo, hay bản nháp brainstorm. Khi cần sửa, mình bảo Claude sửa hộ — và đến đây thì lợi thế lớn nhất của markdown coi như mất.
Mấy tháng nay mình chuyển hẳn sang HTML làm định dạng đầu ra, và thấy nhiều người trong Claude Code team cũng vậy. Lý do bên dưới.
Nếu muốn xem ví dụ trước, đây là một loạt artifact HTML mình tổng hợp lại — coi xong nhớ quay lại đọc tiếp nhé.
Vì sao là HTML?
Mật độ thông tin
HTML thể hiện được nhiều loại thông tin hơn markdown rất nhiều. Cấu trúc cơ bản như tiêu đề, đoạn văn, định dạng thì không phải bàn — quan trọng là HTML còn diễn đạt được:
- Bảng dữ liệu bằng
<table> - Thiết kế bằng CSS
- Hình minh hoạ bằng SVG
- Đoạn code bằng
<script> - Tương tác bằng HTML kết hợp JavaScript và CSS
- Quy trình bằng SVG ghép HTML
- Dữ liệu không gian bằng vị trí tuyệt đối và canvas
- Hình ảnh bằng
<img>
Nói thẳng: hầu như mọi loại thông tin Claude đọc được đều thể hiện được khá hiệu quả bằng HTML. Nhờ vậy, model truyền tải thông tin chi tiết cho bạn rất gọn, và bạn cũng dễ rà lại.
Khi không có HTML, model phải xoay sở bằng những cách kém hơn — vẽ sơ đồ bằng ký tự ASCII, hoặc buồn cười nhất là giả lập màu bằng ký tự Unicode như screenshot này từ Claude Code:
Claude Code đang cố thể hiện màu trong markdown.
Dễ đọc hơn
Claude càng làm việc phức tạp thì bản mô tả và kế hoạch nó viết ra càng dài. Thực tế: file markdown dài quá 100 dòng là mình ít khi đọc hết — và kéo đồng nghiệp đọc giúp lại càng khó.
HTML thì dễ đọc hơn nhiều. Claude tổ chức được layout có tab, có hình minh hoạ, có link — mở trong trình duyệt là thấy thoải mái ngay. Chưa kể còn responsive được trên mobile.
Dễ chia sẻ
Markdown khó chia sẻ vì hầu hết trình duyệt không tự render được. Thường phải đính kèm file vào email hoặc tin nhắn.
Với HTML, chỉ cần upload file lên đâu đó (ví dụ S3) là có link để gửi. Đồng nghiệp mở ở đâu cũng được, dễ tham chiếu.
Khả năng người ta thực sự đọc bản mô tả, ghi chú PR hay báo cáo của bạn cao hơn nhiều khi nó là HTML.
Tương tác hai chiều
HTML cho phép bạn tương tác với tài liệu. Ví dụ thêm thanh trượt hoặc nút xoay để chỉnh thiết kế, hay cho bạn thử thay đổi tham số trong thuật toán xem kết quả khác nhau ra sao. Bạn cũng có thể bảo nó thêm một nút copy để dán những thay đổi đó trở lại vào Claude Code. Mình có một bài riêng về cái mình gọi là "playground" với nhiều ví dụ — đọc thêm ở đây .
Đọc được nhiều ngữ cảnh
Vì sao dùng Claude Code để tạo HTML thay vì ClaudeAI hay Claude Design? Lý do lớn nhất là lượng ngữ cảnh Claude Code đọc được. Khi viết bài này, mình bảo Claude Code đọc qua thư mục code của mình, tìm tất cả file HTML mình từng tạo, gom thành nhóm, rồi sinh một file HTML duy nhất chứa sơ đồ đại diện cho từng nhóm. Mấy sơ đồ trong bài này là kết quả trực tiếp của việc đó.
Ngoài file system, Claude Code còn lấy được thêm ngữ cảnh qua MCP (Slack, Linear…), trình duyệt (Claude in Chrome), git history, v.v.
Vui hơn
Làm tài liệu HTML với Claude vui hơn thật. Mình thấy mình tham gia vào việc tạo ra nó nhiều hơn — và chỉ riêng lý do đó cũng đủ rồi.
Bắt đầu thế nào
Mình hơi sợ là sẽ có người đọc bài này xong đi build hẳn một skill /html hay gì đó tương tự. Cái đó có thể có giá trị, nhưng mình muốn nhấn: bạn không cần làm gì nhiều. Cứ bảo Claude "tạo cho mình một file HTML" hoặc "làm artifact HTML" là được.
Phần khó là biết bạn muốn artifact đó làm gì và bạn dùng nó ra sao. Sau này có thể bạn sẽ tự build skill, nhưng giờ cứ prompt trực tiếp để quen tay đã.
Vài trường hợp cụ thể
Cho dễ hình dung, mình đã làm khá nhiều file HTML cho các mục đích khác nhau. Xem hết ở thariqs.github.io/html-effectiveness , còn dưới đây là tóm lược.
Bản mô tả, kế hoạch và khám phá ý tưởng
HTML là một không gian đủ rộng để Claude đào sâu một bài toán. Khi bắt đầu một vấn đề mới, mình không còn viết một plan markdown đơn thuần nữa — mình kỳ vọng tạo ra cả một loạt file HTML liên kết với nhau. Ví dụ: bảo Claude Code tìm ý và phác ra vài hướng đi khác nhau. Sau đó chọn một hướng và bảo nó mở rộng — có thể kèm bản phác thảo giao diện hoặc đoạn code mẫu. Khi thấy ổn, mình bảo nó viết kế hoạch triển khai. Plan ưng ý thì mình mở phiên mới, đưa toàn bộ các file đó vào để Claude triển khai.
Lúc kiểm tra, mình cũng đưa các file đó cho agent kiểm tra đọc — agent có ngữ cảnh đầy đủ hơn nhiều.
Ví dụ prompt:
- Mình chưa quyết hướng cho màn hình onboarding. Sinh 6 hướng tiếp cận khác hẳn nhau — thay đổi cả layout, giọng và mật độ thông tin — và xếp vào một file HTML dạng grid để mình so song song. Ghi rõ điểm đánh đổi của mỗi hướng.
- Tạo một kế hoạch triển khai chi tiết trong một file HTML, có bản phác thảo giao diện, có sơ đồ luồng dữ liệu, có đoạn code quan trọng để mình review. Trình bày sao cho dễ đọc, dễ tiêu hoá.
Dùng cho:
- Khám phá nhiều cách triển khai trong code
- Khám phá nhiều phương án thiết kế
Code review và đọc hiểu code
Code đọc trong markdown thì khó. Nhưng với HTML, bạn hiển thị được diff, chú thích, sơ đồ luồng, module… Dùng để hiểu code Claude vừa viết, để code review, hoặc để giải thích PR cho người review. Mình thấy cách này thường tốt hơn diff mặc định của GitHub — và giờ mình đính một file HTML giải thích code vào mọi PR mình mở.
Ví dụ prompt:
Giúp mình review PR này bằng cách tạo một artifact HTML mô tả nó. Mình chưa rành phần streaming/backpressure nên tập trung vào đó. Hiển thị diff thật, kèm chú thích bên lề, tô màu các phát hiện theo mức độ nghiêm trọng, và bất cứ thứ gì giúp truyền tải khái niệm rõ hơn.
Dùng cho:
- Mở một PR
- Review một PR
- Hiểu một chủ đề trong code
Thiết kế và mẫu thử
Claude Design dựa trên HTML vì HTML cực mạnh ở mảng thiết kế — kể cả khi sản phẩm cuối không phải HTML. Claude phác thảo thiết kế bằng HTML rồi viết lại bằng React, Swift, hay gì cũng được.
Bạn cũng dựng được mẫu thử cho các tương tác — animation, action… Thử bảo Claude làm thanh trượt, nút xoay để chỉnh đúng cảm giác bạn muốn.
Ví dụ prompt:
Mình muốn dựng thử một nút checkout mới: khi bấm thì chạy animation rồi đổi sang màu tím nhanh. Tạo một file HTML có vài thanh trượt và lựa chọn để mình thử các kiểu animation khác nhau, kèm một nút copy để chép tham số nào ưng nhất.
Dùng cho:
- Tạo các artifact của design system
- Tinh chỉnh component
- Trực quan hoá thư viện component
- Dựng thử animation cho vui
Báo cáo, nghiên cứu và học
Claude Code rất giỏi tổng hợp thông tin từ nhiều nguồn và biến thành báo cáo dễ đọc. Bạn prompt cho nó tìm trong Slack, codebase, git history, internet… rồi sinh báo cáo cực dễ đọc — cho bạn đọc, cho leadership đọc, cho team đọc.
Có thể đóng gói thành tài liệu HTML dài, một trang giải thích tương tác, hay thậm chí slideshow. Bảo Claude dùng SVG vẽ sơ đồ để trực quan hoá. Ví dụ, cho bài về prompt caching của mình, mình bảo Claude chuẩn bị một file nghiên cứu HTML chi tiết, đọc qua git history và ghi lại tất cả thay đổi liên quan đến prompt caching.
Ví dụ prompt: Mình không hiểu rate limiter của tụi mình thực sự hoạt động ra sao. Đọc code liên quan và sinh một trang HTML giải thích duy nhất: sơ đồ dòng chảy của thuật toán token-bucket, 3-4 đoạn code quan trọng kèm chú thích, và một mục "gotcha" ở cuối. Tối ưu cho người chỉ đọc một lần là hiểu.
Dùng cho:
- Tóm tắt một tính năng hoạt động ra sao
- Giải thích một khái niệm
- Báo cáo trạng thái hằng tuần cho sếp
- Báo cáo sự cố cho leadership
- Vẽ minh hoạ SVG, sơ đồ luồng, sơ đồ kỹ thuật
Tự tạo công cụ chỉnh sửa cho một lần dùng
Đôi khi mô tả thứ bạn muốn bằng text rất khó. Lúc đó mình bảo Claude dựng cho một công cụ chỉnh sửa dùng đúng một lần, cho đúng việc mình đang làm. Không phải sản phẩm, không phải tool dùng lại — chỉ một file HTML duy nhất, làm cho đúng một mảnh dữ liệu.
Mẹo: luôn kết thúc bằng một nút export — "copy as JSON" hoặc "copy as prompt" — biến thứ mình vừa làm trong UI thành thứ dán lại được vào Claude Code.
Ví dụ prompt:
- Mình cần xếp lại độ ưu tiên cho 30 ticket Linear. Tạo một file HTML, mỗi ticket là một thẻ kéo thả được giữa các cột Now / Next / Later / Cut. Sắp xếp sẵn theo phán đoán tốt nhất của Claude. Thêm nút "copy as markdown" để xuất thứ tự cuối cùng kèm một dòng lý do cho mỗi cột.
- Đây là cấu hình feature flag của tụi mình. Dựng cho mình một editor dạng form, gom flag theo nhóm chức năng, hiển thị các flag phụ thuộc vào nhau, cảnh báo khi mình bật một flag mà điều kiện tiên quyết của nó đang tắt. Thêm nút "copy diff" để chỉ xuất ra những key đã đổi.
- Đang tinh chỉnh system prompt này. Tạo cho mình một editor song song hai cột: bên trái là prompt sửa được với các vị trí biến được tô sáng, bên phải là ba ví dụ đầu vào, render template đã điền sẵn theo thời gian thực. Thêm bộ đếm ký tự / token và một nút copy.
Dùng cho:
- Sắp xếp / phân loại / chia nhóm bất cứ thứ gì (ticket, test case, phản hồi)
- Sửa cấu hình có cấu trúc (feature flag, biến môi trường, JSON / YAML có ràng buộc)
- Tinh chỉnh prompt, template, copy với xem trước trực tiếp
- Lọc tập dữ liệu, duyệt / loại từng dòng, gắn nhãn ví dụ, xuất phần đã chọn
- Chú thích tài liệu / bản ghi / diff rồi xuất ra phần chú thích
- Chọn các giá trị khó tả bằng text: màu sắc, đường cong easing, vùng cắt ảnh, lịch cron, regex
Câu hỏi thường gặp
Mình có nói chuyện với khá nhiều người về việc đổi sang HTML, và lặp đi lặp lại mấy câu hỏi này.
Vậy có tốn token hơn không? Markdown thường ít token hơn thật, nhưng HTML diễn đạt được nhiều thứ hơn — và xác suất mình thực sự đọc nó cũng cao hơn hẳn. Bù qua sớt lại, kết quả tốt hơn. Với context window 1MM ở Opus 4.7, phần token tăng thêm gần như không đáng kể.
Khi nào vẫn dùng markdown? Mình gần như đã bỏ markdown hoàn toàn cho hầu hết mọi thứ — nhưng mình thuộc dạng HTML maximalist, đừng tin mình hoàn toàn.
Xem file HTML thế nào? Mình mở thẳng trong trình duyệt local (bạn có thể bảo Claude mở luôn), hoặc upload S3 nếu cần link để gửi.
Sinh HTML có lâu hơn markdown không? Có. HTML có thể lâu hơn markdown 2-4 lần — nhưng kết quả xứng đáng.
Còn version control thì sao? Đây thật sự là điểm yếu lớn nhất của HTML — diff HTML rối và khó review hơn markdown rất nhiều.
Làm sao để Claude làm theo gu của mình, không bị xấu? Plugin frontend design giúp Claude làm HTML đỡ xấu. Còn để theo style của công ty bạn, hãy tạo một file HTML design system bằng cách trỏ Claude vào codebase. Sau đó dùng file đó làm tham chiếu cho các file HTML khác.
Giữ mình trong vòng lặp
Tất cả những gì kể trên gói lại thành một thứ: dùng HTML khiến mình cảm thấy mình ở trong vòng lặp với Claude hơn. Mình từng lo rằng vì không còn đọc plan kỹ nữa, mình sẽ phải để Claude tự quyết.
Nhưng giờ thì ngược lại — mình ở trong vòng lặp đó nhiều hơn bao giờ hết khi dùng HTML. Mong là bạn cũng vậy.
---
Bài gốc tiếng Anh: Thariq Shihipar — Using Claude Code: The Unreasonable Effectiveness of HTML.
Note: This is the English source for the Vietnamese adaptation above. Original post by Thariq Shihipar (Claude Code team) — Using Claude Code: The Unreasonable Effectiveness of HTML.
Markdown is the default format agents use to communicate with me. It's simple, readable everywhere, supports a bit of text formatting, and it's easy to hand-edit. Claude is even pretty good at drawing ASCII diagrams inside markdown files.
But as agents get stronger, markdown feels more constraining. Anything past 100 lines and I stop reading. I want something more visual — colors, diagrams — and easier to share with other people.
I've also stopped hand-editing these files. They're becoming specs, reference docs, brainstorming drafts. When I need a change, I ask Claude to do it — and at that point, markdown's biggest advantage is gone.
For the past few months I've switched entirely to HTML as my output format, and a lot of folks on the Claude Code team have done the same. Reasons below.
If you want to see examples first, here's a collection of HTML artifacts I put together — come back after.
Why HTML?
Information density
HTML expresses far more kinds of information than markdown. The basics — headings, paragraphs, formatting — are a given. The point is that HTML can also express:
- Tabular data with
<table> - Visual design with CSS
- Illustrations with SVG
- Code with
<script> - Interactivity with HTML + JavaScript + CSS
- Process flows with SVG combined with HTML
- Spatial data with absolute positioning and canvas
- Images with
<img>
Bluntly: almost any kind of information Claude can read can be expressed effectively in HTML. That lets the model communicate detailed information to you densely, and lets you scan it back easily.
Without HTML, the model has to fall back on weaker workarounds — ASCII diagrams, or, most absurdly, simulating colors with Unicode characters as in this Claude Code screenshot:
Claude Code trying to express color in markdown.
Easier to read
The more complex the work Claude does, the longer the specs and plans it writes. In practice: I rarely read past 100 lines of markdown — and getting a coworker to read it is even harder.
HTML is much easier to read. Claude can lay things out with tabs, illustrations, and links — open it in a browser and you're comfortable immediately. It's also responsive on mobile.
Easier to share
Markdown is hard to share because most browsers don't render it natively. You usually end up attaching the file to an email or a message.
With HTML, just upload the file somewhere (S3, for example) and you've got a link to send. People can open it anywhere, and it's easy to reference.
The odds that someone actually reads your spec, PR notes, or report are much higher when it's HTML.
Two-way interactivity
HTML lets you interact with the document. Add sliders or knobs to tune a design, or let yourself change algorithm parameters and see the result shift. You can even ask for a copy button that pastes those changes back into Claude Code. I have a separate post on what I call the "playground" pattern with more examples — read more here .
Reads more context
Why use Claude Code to make HTML instead of ClaudeAI or Claude Design? The biggest reason is the amount of context Claude Code can read. While writing this post, I told Claude Code to walk through my code directories, find every HTML file I'd ever made, group them, and produce a single HTML file containing a representative diagram per group. The diagrams in this post are a direct result of that.
Beyond the file system, Claude Code can pull in more context through MCP (Slack, Linear…), the browser (Claude in Chrome), git history, and so on.
It's more fun
Making HTML documents with Claude is genuinely more fun. I find myself participating more in the act of making them — and that alone is enough.
How to start
I worry someone will read this and go build a /html skill or something similar. That can be valuable, but I want to underline: you don't need to do much. Just tell Claude "make me an HTML file" or "make an HTML artifact".
The hard part is knowing what you want the artifact to do and how you'll use it. Eventually you may build a skill for yourself, but for now, prompt directly until your hands are familiar with it.
A few concrete cases
To make this tangible, I've made a lot of HTML files for different purposes. See them all at thariqs.github.io/html-effectiveness ; a summary follows.
Specs, plans, and idea exploration
HTML gives Claude enough room to dig into a problem. When I start something new, I no longer write a plain markdown plan — I expect to produce a series of linked HTML files. Example: ask Claude Code to brainstorm and sketch a few different directions. Pick one and ask it to expand — possibly with UI sketches and sample code. When something looks right, ask for an implementation plan. When the plan is good, I open a fresh session, hand it all those files, and have Claude implement.
For checks, I also hand those files to a reviewer agent — it has much more complete context.
Example prompts:
- I'm undecided on the onboarding screen. Generate 6 distinctly different approaches — varying layout, voice, and information density — and lay them out in a single HTML grid for side-by-side comparison. Note the trade-offs of each.
- Generate a detailed implementation plan in one HTML file: UI sketches, data flow diagrams, key code excerpts I can review. Lay it out so it's easy to read and digest.
Use for:
- Exploring multiple implementation directions in code
- Exploring multiple design directions
Code review and code understanding
Code is hard to read in markdown. With HTML, you can render diffs, annotations, flow diagrams, modules. Use it to understand code Claude just wrote, to do code review, or to explain a PR to your reviewer. I find this is often better than the default GitHub diff — and I now attach an HTML explainer to every PR I open.
Example prompt:
Help me review this PR by generating an HTML artifact describing it. I'm rusty on the streaming/backpressure parts so focus there. Show the actual diff with margin annotations, color findings by severity, and add anything that helps convey the concept.
Use for:
- Opening a PR
- Reviewing a PR
- Understanding a topic in code
Design and prototypes
Claude Design is built on HTML because HTML is extremely strong for design — even when the final product isn't HTML. Claude can sketch a design in HTML and then translate it into React, Swift, or anything else.
You can also prototype interactions — animations, actions. Try asking Claude to build sliders and knobs to dial in the exact feel you want.
Example prompt:
I want to prototype a new checkout button: on click, run an animation, then snap to a fast purple. Make me an HTML file with a few sliders and dropdowns so I can try different animation styles, plus a copy button to grab the parameters of whichever feels right.
Use for:
- Producing design system artifacts
- Tuning components
- Visualizing a component library
- Prototyping animations for fun
Reports, research, and learning
Claude Code is very good at synthesizing information from multiple sources into something readable. Prompt it to search Slack, the codebase, git history, the internet — and produce extremely readable reports for you, leadership, or your team.
It can be a long-form HTML document, a single-page interactive explainer, or even a slideshow. Have Claude use SVG to draw diagrams. For my prompt-caching post, for example, I told Claude to prepare a detailed HTML research file by walking the git history and recording every change related to prompt caching.
Example prompt: I don't understand how our rate limiter actually works. Read the relevant code and produce a single HTML explainer page: a flow diagram of the token-bucket algorithm, 3–4 key code excerpts with annotations, and a "gotchas" section at the end. Optimize for someone who reads it once and gets it.
Use for:
- Summarizing how a feature works
- Explaining a concept
- Weekly status reports for your manager
- Incident reports for leadership
- SVG illustrations, flow diagrams, technical diagrams
Build your own one-shot editing tools
Sometimes describing what you want in text is hard. When that happens, I ask Claude to spin up a one-shot editing tool, just for the task at hand. Not a product, not a reusable tool — just a single HTML file aimed at one piece of data.
Tip: always end with an export button — "copy as JSON" or "copy as prompt" — turning whatever you just did in the UI back into something you can paste into Claude Code.
Example prompts:
- I need to re-prioritize 30 Linear tickets. Build me an HTML file where each ticket is a card I can drag between Now / Next / Later / Cut columns. Pre-sort by your best guess. Add a "copy as markdown" button that exports the final order with a one-line reason per column.
- Here's our feature flag config. Build me a form-style editor that groups flags by feature, shows dependent flags, and warns when I enable a flag whose prerequisites are off. Add a "copy diff" button that exports only changed keys.
- I'm tuning this system prompt. Make me a two-pane editor: left side is the editable prompt with variable slots highlighted; right side is three example inputs that render the filled template in real time. Add character/token counts and a copy button.
Use for:
- Sorting / categorizing / clustering anything (tickets, test cases, feedback)
- Editing structured config (feature flags, env vars, constrained JSON / YAML)
- Tuning prompts, templates, copy with live previews
- Filtering datasets, walking row-by-row, labeling examples, exporting selections
- Annotating documents / transcripts / diffs and exporting just the annotations
- Picking values that are awkward to describe in text: colors, easing curves, image crops, cron schedules, regex
FAQ
I've talked to a lot of people about switching to HTML, and the same questions keep coming up.
Doesn't this use more tokens? Markdown is usually fewer tokens, true, but HTML expresses more — and the odds I actually read it are much higher. Net-net, the result is better. With Opus 4.7's 1M context window, the token overhead is essentially negligible.
When do you still use markdown? I've nearly dropped markdown for almost everything — but I'm an HTML maximalist, take that with a grain of salt.
How do you view HTML files? I open them directly in my local browser (you can have Claude open them too), or upload to S3 if I need a shareable link.
Is HTML slower to generate than markdown? Yes. HTML can be 2–4× slower than markdown — but the result is worth it.
What about version control? This is genuinely HTML's biggest weakness — HTML diffs are noisier and harder to review than markdown.
How do I get Claude to match my style and not look ugly? The frontend design plugin helps Claude make less ugly HTML. To match your company's style, build an HTML design-system file by pointing Claude at your codebase, then use that file as the reference for every other HTML file.
Staying in the loop
All of this rolls up into one thing: using HTML makes me feel in the loop with Claude in a way I wasn't before. I worried that since I no longer read plans line by line, I'd have to defer decisions to Claude.
It's the opposite. I'm more in the loop than ever when I use HTML. I hope it's the same for you.
---
Original post in English: Thariq Shihipar — Using Claude Code: The Unreasonable Effectiveness of HTML.
> **Ghi chú của người dịch:** Bài này lược dịch và biên tập từ _Using Claude Code: The Unreasonable Effectiveness of HTML_ của Thariq Shihipar (Claude Code team). Mình giữ ngôi thứ nhất của tác giả và chỉ chỉnh lại tone cho người đọc Việt.
Markdown đang là định dạng mặc định mà các agent dùng để giao tiếp với mình. Nó đơn giản, đâu cũng đọc được, có hỗ trợ chút ít định dạng văn bản, và bạn ngồi sửa tay cũng dễ. Claude thậm chí còn khá giỏi vẽ sơ đồ bằng ký tự ASCII trong file markdown.
Nhưng càng dùng các agent mạnh hơn, mình càng thấy markdown gò bó. File markdown dài hơn 100 dòng là mình đọc không vào. Mình muốn trực quan hơn, có màu, có sơ đồ, và muốn chia sẻ cho người khác cũng dễ.
Mình cũng dần không còn tự sửa mấy file này nữa — chúng dần trở thành bản mô tả, tài liệu tham khảo, hay bản nháp brainstorm. Khi cần sửa, mình bảo Claude sửa hộ — và đến đây thì lợi thế lớn nhất của markdown coi như mất.
Mấy tháng nay mình chuyển hẳn sang HTML làm định dạng đầu ra, và thấy nhiều người trong Claude Code team cũng vậy. Lý do bên dưới.
> Nếu muốn xem ví dụ trước, [đây là một loạt artifact HTML mình tổng hợp lại](https://thariqs.github.io/html-effectiveness/) — coi xong nhớ quay lại đọc tiếp nhé.
## Vì sao là HTML?
### Mật độ thông tin
HTML thể hiện được nhiều loại thông tin hơn markdown rất nhiều. Cấu trúc cơ bản như tiêu đề, đoạn văn, định dạng thì không phải bàn — quan trọng là HTML còn diễn đạt được:
- Bảng dữ liệu bằng `<table>`
- Thiết kế bằng CSS
- Hình minh hoạ bằng SVG
- Đoạn code bằng `<script>`
- Tương tác bằng HTML kết hợp JavaScript và CSS
- Quy trình bằng SVG ghép HTML
- Dữ liệu không gian bằng vị trí tuyệt đối và canvas
- Hình ảnh bằng `<img>`
Nói thẳng: hầu như mọi loại thông tin Claude đọc được đều thể hiện được khá hiệu quả bằng HTML. Nhờ vậy, model truyền tải thông tin chi tiết cho bạn rất gọn, và bạn cũng dễ rà lại.
Khi không có HTML, model phải xoay sở bằng những cách kém hơn — vẽ sơ đồ bằng ký tự ASCII, hoặc buồn cười nhất là _giả lập màu_ bằng ký tự Unicode như screenshot này từ Claude Code:
_Claude Code đang cố thể hiện màu trong markdown._
### Dễ đọc hơn
Claude càng làm việc phức tạp thì bản mô tả và kế hoạch nó viết ra càng dài. Thực tế: file markdown dài quá 100 dòng là mình ít khi đọc hết — và kéo đồng nghiệp đọc giúp lại càng khó.
HTML thì dễ đọc hơn nhiều. Claude tổ chức được layout có tab, có hình minh hoạ, có link — mở trong trình duyệt là thấy thoải mái ngay. Chưa kể còn responsive được trên mobile.
### Dễ chia sẻ
Markdown khó chia sẻ vì hầu hết trình duyệt không tự render được. Thường phải đính kèm file vào email hoặc tin nhắn.
Với HTML, chỉ cần upload file lên đâu đó (ví dụ S3) là có link để gửi. Đồng nghiệp mở ở đâu cũng được, dễ tham chiếu.
Khả năng người ta thực sự đọc bản mô tả, ghi chú PR hay báo cáo của bạn cao hơn nhiều khi nó là HTML.
### Tương tác hai chiều
HTML cho phép bạn _tương tác_ với tài liệu. Ví dụ thêm thanh trượt hoặc nút xoay để chỉnh thiết kế, hay cho bạn thử thay đổi tham số trong thuật toán xem kết quả khác nhau ra sao. Bạn cũng có thể bảo nó thêm một nút copy để dán những thay đổi đó trở lại vào Claude Code. Mình có một bài riêng về cái mình gọi là "playground" với nhiều ví dụ — đọc thêm ở [đây](https://x.com/trq212/status/2017024445244924382).
### Đọc được nhiều ngữ cảnh
Vì sao dùng Claude Code để tạo HTML thay vì ClaudeAI hay Claude Design? Lý do lớn nhất là lượng ngữ cảnh Claude Code đọc được. Khi viết bài này, mình bảo Claude Code đọc qua thư mục code của mình, tìm tất cả file HTML mình từng tạo, gom thành nhóm, rồi sinh một file HTML duy nhất chứa sơ đồ đại diện cho từng nhóm. Mấy sơ đồ trong bài này là kết quả trực tiếp của việc đó.
Ngoài file system, Claude Code còn lấy được thêm ngữ cảnh qua MCP (Slack, Linear…), trình duyệt (Claude in Chrome), git history, v.v.
### Vui hơn
Làm tài liệu HTML với Claude vui hơn thật. Mình thấy mình tham gia vào việc tạo ra nó nhiều hơn — và chỉ riêng lý do đó cũng đủ rồi.
## Bắt đầu thế nào
Mình hơi sợ là sẽ có người đọc bài này xong đi build hẳn một skill `/html` hay gì đó tương tự. Cái đó có thể có giá trị, nhưng mình muốn nhấn: bạn không cần làm gì nhiều. Cứ bảo Claude _"tạo cho mình một file HTML"_ hoặc _"làm artifact HTML"_ là được.
Phần khó là biết bạn muốn artifact đó làm gì và bạn dùng nó ra sao. Sau này có thể bạn sẽ tự build skill, nhưng giờ cứ prompt trực tiếp để quen tay đã.
## Vài trường hợp cụ thể
Cho dễ hình dung, mình đã làm khá nhiều file HTML cho các mục đích khác nhau. Xem hết ở [thariqs.github.io/html-effectiveness](https://thariqs.github.io/html-effectiveness/), còn dưới đây là tóm lược.
### Bản mô tả, kế hoạch và khám phá ý tưởng
HTML là một không gian đủ rộng để Claude đào sâu một bài toán. Khi bắt đầu một vấn đề mới, mình không còn viết một plan markdown đơn thuần nữa — mình kỳ vọng tạo ra cả _một loạt_ file HTML liên kết với nhau. Ví dụ: bảo Claude Code tìm ý và phác ra vài hướng đi khác nhau. Sau đó chọn một hướng và bảo nó mở rộng — có thể kèm bản phác thảo giao diện hoặc đoạn code mẫu. Khi thấy ổn, mình bảo nó viết kế hoạch triển khai. Plan ưng ý thì mình mở phiên mới, đưa toàn bộ các file đó vào để Claude triển khai.
Lúc kiểm tra, mình cũng đưa các file đó cho agent kiểm tra đọc — agent có ngữ cảnh đầy đủ hơn nhiều.
**Ví dụ prompt:**
- _Mình chưa quyết hướng cho màn hình onboarding. Sinh 6 hướng tiếp cận khác hẳn nhau — thay đổi cả layout, giọng và mật độ thông tin — và xếp vào một file HTML dạng grid để mình so song song. Ghi rõ điểm đánh đổi của mỗi hướng._
- _Tạo một kế hoạch triển khai chi tiết trong một file HTML, có bản phác thảo giao diện, có sơ đồ luồng dữ liệu, có đoạn code quan trọng để mình review. Trình bày sao cho dễ đọc, dễ tiêu hoá._
**Dùng cho:**
- Khám phá nhiều cách triển khai trong code
- Khám phá nhiều phương án thiết kế
### Code review và đọc hiểu code
Code đọc trong markdown thì khó. Nhưng với HTML, bạn hiển thị được diff, chú thích, sơ đồ luồng, module… Dùng để hiểu code Claude vừa viết, để code review, hoặc để giải thích PR cho người review. Mình thấy cách này thường tốt hơn diff mặc định của GitHub — và giờ mình đính một file HTML giải thích code vào mọi PR mình mở.
**Ví dụ prompt:**
_Giúp mình review PR này bằng cách tạo một artifact HTML mô tả nó. Mình chưa rành phần streaming/backpressure nên tập trung vào đó. Hiển thị diff thật, kèm chú thích bên lề, tô màu các phát hiện theo mức độ nghiêm trọng, và bất cứ thứ gì giúp truyền tải khái niệm rõ hơn._
**Dùng cho:**
- Mở một PR
- Review một PR
- Hiểu một chủ đề trong code
### Thiết kế và mẫu thử
Claude Design dựa trên HTML vì HTML cực mạnh ở mảng thiết kế — kể cả khi sản phẩm cuối không phải HTML. Claude phác thảo thiết kế bằng HTML rồi viết lại bằng React, Swift, hay gì cũng được.
Bạn cũng dựng được mẫu thử cho các tương tác — animation, action… Thử bảo Claude làm thanh trượt, nút xoay để chỉnh đúng cảm giác bạn muốn.
**Ví dụ prompt:**
_Mình muốn dựng thử một nút checkout mới: khi bấm thì chạy animation rồi đổi sang màu tím nhanh. Tạo một file HTML có vài thanh trượt và lựa chọn để mình thử các kiểu animation khác nhau, kèm một nút copy để chép tham số nào ưng nhất._
**Dùng cho:**
- Tạo các artifact của design system
- Tinh chỉnh component
- Trực quan hoá thư viện component
- Dựng thử animation cho vui
### Báo cáo, nghiên cứu và học
Claude Code rất giỏi tổng hợp thông tin từ nhiều nguồn và biến thành báo cáo dễ đọc. Bạn prompt cho nó tìm trong Slack, codebase, git history, internet… rồi sinh báo cáo cực dễ đọc — cho bạn đọc, cho leadership đọc, cho team đọc.
Có thể đóng gói thành tài liệu HTML dài, một trang giải thích tương tác, hay thậm chí slideshow. Bảo Claude dùng SVG vẽ sơ đồ để trực quan hoá. Ví dụ, cho bài về prompt caching của mình, mình bảo Claude chuẩn bị một file nghiên cứu HTML chi tiết, đọc qua git history và ghi lại tất cả thay đổi liên quan đến prompt caching.
**Ví dụ prompt:** _Mình không hiểu rate limiter của tụi mình thực sự hoạt động ra sao. Đọc code liên quan và sinh một trang HTML giải thích duy nhất: sơ đồ dòng chảy của thuật toán token-bucket, 3-4 đoạn code quan trọng kèm chú thích, và một mục "gotcha" ở cuối. Tối ưu cho người chỉ đọc một lần là hiểu._
**Dùng cho:**
- Tóm tắt một tính năng hoạt động ra sao
- Giải thích một khái niệm
- Báo cáo trạng thái hằng tuần cho sếp
- Báo cáo sự cố cho leadership
- Vẽ minh hoạ SVG, sơ đồ luồng, sơ đồ kỹ thuật
## Tự tạo công cụ chỉnh sửa cho một lần dùng
Đôi khi mô tả thứ bạn muốn bằng text rất khó. Lúc đó mình bảo Claude dựng cho một công cụ chỉnh sửa dùng đúng một lần, cho đúng việc mình đang làm. Không phải sản phẩm, không phải tool dùng lại — chỉ một file HTML duy nhất, làm cho đúng một mảnh dữ liệu.
Mẹo: luôn kết thúc bằng một nút export — _"copy as JSON"_ hoặc _"copy as prompt"_ — biến thứ mình vừa làm trong UI thành thứ dán lại được vào Claude Code.
**Ví dụ prompt:**
- _Mình cần xếp lại độ ưu tiên cho 30 ticket Linear. Tạo một file HTML, mỗi ticket là một thẻ kéo thả được giữa các cột Now / Next / Later / Cut. Sắp xếp sẵn theo phán đoán tốt nhất của Claude. Thêm nút "copy as markdown" để xuất thứ tự cuối cùng kèm một dòng lý do cho mỗi cột._
- _Đây là cấu hình feature flag của tụi mình. Dựng cho mình một editor dạng form, gom flag theo nhóm chức năng, hiển thị các flag phụ thuộc vào nhau, cảnh báo khi mình bật một flag mà điều kiện tiên quyết của nó đang tắt. Thêm nút "copy diff" để chỉ xuất ra những key đã đổi._
- _Đang tinh chỉnh system prompt này. Tạo cho mình một editor song song hai cột: bên trái là prompt sửa được với các vị trí biến được tô sáng, bên phải là ba ví dụ đầu vào, render template đã điền sẵn theo thời gian thực. Thêm bộ đếm ký tự / token và một nút copy._
**Dùng cho:**
- Sắp xếp / phân loại / chia nhóm bất cứ thứ gì (ticket, test case, phản hồi)
- Sửa cấu hình có cấu trúc (feature flag, biến môi trường, JSON / YAML có ràng buộc)
- Tinh chỉnh prompt, template, copy với xem trước trực tiếp
- Lọc tập dữ liệu, duyệt / loại từng dòng, gắn nhãn ví dụ, xuất phần đã chọn
- Chú thích tài liệu / bản ghi / diff rồi xuất ra phần chú thích
- Chọn các giá trị khó tả bằng text: màu sắc, đường cong easing, vùng cắt ảnh, lịch cron, regex
## Câu hỏi thường gặp
Mình có nói chuyện với khá nhiều người về việc đổi sang HTML, và lặp đi lặp lại mấy câu hỏi này.
**Vậy có tốn token hơn không?** Markdown thường ít token hơn thật, nhưng HTML diễn đạt được nhiều thứ hơn — và xác suất mình thực sự đọc nó cũng cao hơn hẳn. Bù qua sớt lại, kết quả tốt hơn. Với context window 1MM ở Opus 4.7, phần token tăng thêm gần như không đáng kể.
**Khi nào vẫn dùng markdown?** Mình gần như đã bỏ markdown hoàn toàn cho hầu hết mọi thứ — nhưng mình thuộc dạng HTML maximalist, đừng tin mình hoàn toàn.
**Xem file HTML thế nào?** Mình mở thẳng trong trình duyệt local (bạn có thể bảo Claude mở luôn), hoặc upload S3 nếu cần link để gửi.
**Sinh HTML có lâu hơn markdown không?** Có. HTML có thể lâu hơn markdown 2-4 lần — nhưng kết quả xứng đáng.
**Còn version control thì sao?** Đây thật sự là điểm yếu lớn nhất của HTML — diff HTML rối và khó review hơn markdown rất nhiều.
**Làm sao để Claude làm theo gu của mình, không bị xấu?** Plugin frontend design giúp Claude làm HTML đỡ xấu. Còn để theo style của công ty bạn, hãy tạo một file HTML design system bằng cách trỏ Claude vào codebase. Sau đó dùng file đó làm tham chiếu cho các file HTML khác.
## Giữ mình trong vòng lặp
Tất cả những gì kể trên gói lại thành một thứ: dùng HTML khiến mình cảm thấy mình _ở trong vòng lặp_ với Claude hơn. Mình từng lo rằng vì không còn đọc plan kỹ nữa, mình sẽ phải để Claude tự quyết.
Nhưng giờ thì ngược lại — mình ở trong vòng lặp đó nhiều hơn bao giờ hết khi dùng HTML. Mong là bạn cũng vậy.
---
_Bài gốc tiếng Anh: Thariq Shihipar — Using Claude Code: The Unreasonable Effectiveness of HTML._> **Note:** This is the English source for the Vietnamese adaptation above. Original post by Thariq Shihipar (Claude Code team) — _Using Claude Code: The Unreasonable Effectiveness of HTML_.
Markdown is the default format agents use to communicate with me. It's simple, readable everywhere, supports a bit of text formatting, and it's easy to hand-edit. Claude is even pretty good at drawing ASCII diagrams inside markdown files.
But as agents get stronger, markdown feels more constraining. Anything past 100 lines and I stop reading. I want something more visual — colors, diagrams — and easier to share with other people.
I've also stopped hand-editing these files. They're becoming specs, reference docs, brainstorming drafts. When I need a change, I ask Claude to do it — and at that point, markdown's biggest advantage is gone.
For the past few months I've switched entirely to HTML as my output format, and a lot of folks on the Claude Code team have done the same. Reasons below.
> If you want to see examples first, [here's a collection of HTML artifacts I put together](https://thariqs.github.io/html-effectiveness/) — come back after.
## Why HTML?
### Information density
HTML expresses far more kinds of information than markdown. The basics — headings, paragraphs, formatting — are a given. The point is that HTML can also express:
- Tabular data with `<table>`
- Visual design with CSS
- Illustrations with SVG
- Code with `<script>`
- Interactivity with HTML + JavaScript + CSS
- Process flows with SVG combined with HTML
- Spatial data with absolute positioning and canvas
- Images with `<img>`
Bluntly: almost any kind of information Claude can read can be expressed effectively in HTML. That lets the model communicate detailed information to you densely, and lets you scan it back easily.
Without HTML, the model has to fall back on weaker workarounds — ASCII diagrams, or, most absurdly, _simulating colors_ with Unicode characters as in this Claude Code screenshot:
_Claude Code trying to express color in markdown._
### Easier to read
The more complex the work Claude does, the longer the specs and plans it writes. In practice: I rarely read past 100 lines of markdown — and getting a coworker to read it is even harder.
HTML is much easier to read. Claude can lay things out with tabs, illustrations, and links — open it in a browser and you're comfortable immediately. It's also responsive on mobile.
### Easier to share
Markdown is hard to share because most browsers don't render it natively. You usually end up attaching the file to an email or a message.
With HTML, just upload the file somewhere (S3, for example) and you've got a link to send. People can open it anywhere, and it's easy to reference.
The odds that someone actually reads your spec, PR notes, or report are much higher when it's HTML.
### Two-way interactivity
HTML lets you _interact_ with the document. Add sliders or knobs to tune a design, or let yourself change algorithm parameters and see the result shift. You can even ask for a copy button that pastes those changes back into Claude Code. I have a separate post on what I call the "playground" pattern with more examples — read more [here](https://x.com/trq212/status/2017024445244924382).
### Reads more context
Why use Claude Code to make HTML instead of ClaudeAI or Claude Design? The biggest reason is the amount of context Claude Code can read. While writing this post, I told Claude Code to walk through my code directories, find every HTML file I'd ever made, group them, and produce a single HTML file containing a representative diagram per group. The diagrams in this post are a direct result of that.
Beyond the file system, Claude Code can pull in more context through MCP (Slack, Linear…), the browser (Claude in Chrome), git history, and so on.
### It's more fun
Making HTML documents with Claude is genuinely more fun. I find myself participating more in the act of making them — and that alone is enough.
## How to start
I worry someone will read this and go build a `/html` skill or something similar. That can be valuable, but I want to underline: you don't need to do much. Just tell Claude _"make me an HTML file"_ or _"make an HTML artifact"_.
The hard part is knowing what you want the artifact to do and how you'll use it. Eventually you may build a skill for yourself, but for now, prompt directly until your hands are familiar with it.
## A few concrete cases
To make this tangible, I've made a lot of HTML files for different purposes. See them all at [thariqs.github.io/html-effectiveness](https://thariqs.github.io/html-effectiveness/); a summary follows.
### Specs, plans, and idea exploration
HTML gives Claude enough room to dig into a problem. When I start something new, I no longer write a plain markdown plan — I expect to produce _a series_ of linked HTML files. Example: ask Claude Code to brainstorm and sketch a few different directions. Pick one and ask it to expand — possibly with UI sketches and sample code. When something looks right, ask for an implementation plan. When the plan is good, I open a fresh session, hand it all those files, and have Claude implement.
For checks, I also hand those files to a reviewer agent — it has much more complete context.
**Example prompts:**
- _I'm undecided on the onboarding screen. Generate 6 distinctly different approaches — varying layout, voice, and information density — and lay them out in a single HTML grid for side-by-side comparison. Note the trade-offs of each._
- _Generate a detailed implementation plan in one HTML file: UI sketches, data flow diagrams, key code excerpts I can review. Lay it out so it's easy to read and digest._
**Use for:**
- Exploring multiple implementation directions in code
- Exploring multiple design directions
### Code review and code understanding
Code is hard to read in markdown. With HTML, you can render diffs, annotations, flow diagrams, modules. Use it to understand code Claude just wrote, to do code review, or to explain a PR to your reviewer. I find this is often better than the default GitHub diff — and I now attach an HTML explainer to every PR I open.
**Example prompt:**
_Help me review this PR by generating an HTML artifact describing it. I'm rusty on the streaming/backpressure parts so focus there. Show the actual diff with margin annotations, color findings by severity, and add anything that helps convey the concept._
**Use for:**
- Opening a PR
- Reviewing a PR
- Understanding a topic in code
### Design and prototypes
Claude Design is built on HTML because HTML is extremely strong for design — even when the final product isn't HTML. Claude can sketch a design in HTML and then translate it into React, Swift, or anything else.
You can also prototype interactions — animations, actions. Try asking Claude to build sliders and knobs to dial in the exact feel you want.
**Example prompt:**
_I want to prototype a new checkout button: on click, run an animation, then snap to a fast purple. Make me an HTML file with a few sliders and dropdowns so I can try different animation styles, plus a copy button to grab the parameters of whichever feels right._
**Use for:**
- Producing design system artifacts
- Tuning components
- Visualizing a component library
- Prototyping animations for fun
### Reports, research, and learning
Claude Code is very good at synthesizing information from multiple sources into something readable. Prompt it to search Slack, the codebase, git history, the internet — and produce extremely readable reports for you, leadership, or your team.
It can be a long-form HTML document, a single-page interactive explainer, or even a slideshow. Have Claude use SVG to draw diagrams. For my prompt-caching post, for example, I told Claude to prepare a detailed HTML research file by walking the git history and recording every change related to prompt caching.
**Example prompt:** _I don't understand how our rate limiter actually works. Read the relevant code and produce a single HTML explainer page: a flow diagram of the token-bucket algorithm, 3–4 key code excerpts with annotations, and a "gotchas" section at the end. Optimize for someone who reads it once and gets it._
**Use for:**
- Summarizing how a feature works
- Explaining a concept
- Weekly status reports for your manager
- Incident reports for leadership
- SVG illustrations, flow diagrams, technical diagrams
## Build your own one-shot editing tools
Sometimes describing what you want in text is hard. When that happens, I ask Claude to spin up a one-shot editing tool, just for the task at hand. Not a product, not a reusable tool — just a single HTML file aimed at one piece of data.
Tip: always end with an export button — _"copy as JSON"_ or _"copy as prompt"_ — turning whatever you just did in the UI back into something you can paste into Claude Code.
**Example prompts:**
- _I need to re-prioritize 30 Linear tickets. Build me an HTML file where each ticket is a card I can drag between Now / Next / Later / Cut columns. Pre-sort by your best guess. Add a "copy as markdown" button that exports the final order with a one-line reason per column._
- _Here's our feature flag config. Build me a form-style editor that groups flags by feature, shows dependent flags, and warns when I enable a flag whose prerequisites are off. Add a "copy diff" button that exports only changed keys._
- _I'm tuning this system prompt. Make me a two-pane editor: left side is the editable prompt with variable slots highlighted; right side is three example inputs that render the filled template in real time. Add character/token counts and a copy button._
**Use for:**
- Sorting / categorizing / clustering anything (tickets, test cases, feedback)
- Editing structured config (feature flags, env vars, constrained JSON / YAML)
- Tuning prompts, templates, copy with live previews
- Filtering datasets, walking row-by-row, labeling examples, exporting selections
- Annotating documents / transcripts / diffs and exporting just the annotations
- Picking values that are awkward to describe in text: colors, easing curves, image crops, cron schedules, regex
## FAQ
I've talked to a lot of people about switching to HTML, and the same questions keep coming up.
**Doesn't this use more tokens?** Markdown is usually fewer tokens, true, but HTML expresses more — and the odds I actually read it are much higher. Net-net, the result is better. With Opus 4.7's 1M context window, the token overhead is essentially negligible.
**When do you still use markdown?** I've nearly dropped markdown for almost everything — but I'm an HTML maximalist, take that with a grain of salt.
**How do you view HTML files?** I open them directly in my local browser (you can have Claude open them too), or upload to S3 if I need a shareable link.
**Is HTML slower to generate than markdown?** Yes. HTML can be 2–4× slower than markdown — but the result is worth it.
**What about version control?** This is genuinely HTML's biggest weakness — HTML diffs are noisier and harder to review than markdown.
**How do I get Claude to match my style and not look ugly?** The frontend design plugin helps Claude make less ugly HTML. To match your company's style, build an HTML design-system file by pointing Claude at your codebase, then use that file as the reference for every other HTML file.
## Staying in the loop
All of this rolls up into one thing: using HTML makes me feel _in the loop_ with Claude in a way I wasn't before. I worried that since I no longer read plans line by line, I'd have to defer decisions to Claude.
It's the opposite. I'm more in the loop than ever when I use HTML. I hope it's the same for you.
---
_Original post in English: Thariq Shihipar — Using Claude Code: The Unreasonable Effectiveness of HTML._
No comments yet