Tác giả bài gốc: Thariq Shihipar (Member of Technical Staff). Đăng ngày 20/05/2026 trên claude.dev.
Markdown đã trở thành định dạng file chủ đạo mà agent dùng để giao tiếp với con người. Nó đơn giản, dễ dùng ở nhiều nơi, hỗ trợ một số cách định dạng văn bản và dễ chỉnh sửa. Claude thậm chí còn dùng ASCII để vẽ sơ đồ trong file Markdown tốt đến bất ngờ.
Nhưng khi agent ngày càng mạnh hơn, mình nhận thấy Markdown đang trở thành một định dạng ngày càng gò bó. Cụ thể, mình thấy khó đọc một file Markdown dài hơn một trăm dòng; mình muốn dùng Claude để tạo những hình ảnh trực quan, màu sắc và sơ đồ phong phú hơn; và mình muốn chia sẻ những đầu ra này dễ dàng hơn.
Mình cũng ngày càng ít tự chỉnh sửa các file này, mà dùng chúng làm bản đặc tả (spec) và tài liệu tham khảo. Khi cần chỉnh sửa, mình thường yêu cầu Claude sửa, nên một trong những lợi ích lớn nhất của Markdown không còn nữa.
Thay vào đó, mình bắt đầu ưu tiên HTML làm định dạng đầu ra hơn Markdown và ngày càng thấy những người khác trong nhóm Claude Code cũng áp dụng cách này. Trong bài viết này, mình chia sẻ vì sao và cách nhóm chúng tôi dùng HTML để tạo đầu ra Claude Code phong phú hơn, dễ đọc hơn. Nếu muốn làm theo, bạn cũng có thể bắt đầu dùng những mẫu file HTML này cho các trường hợp sử dụng phổ biến.
Vì sao dùng HTML?
Có một vài điều khiến HTML phù hợp hơn Markdown với kiểu công việc mình đang làm bằng Claude Code, bao gồm các tác vụ cần hoặc liên quan đến:
Mật độ thông tin
HTML có thể truyền tải thông tin phong phú hơn nhiều so với Markdown. Tất nhiên, nó có thể tạo cấu trúc tài liệu đơn giản như tiêu đề và định dạng, nhưng cũng có thể biểu diễn đủ loại thông tin khác như:
- Dữ liệu dạng bảng bằng các bảng
- Dữ liệu thiết kế bằng CSS
- Hình minh họa bằng SVG
- Các đoạn code bằng thẻ script
- Tương tác bằng các phần tử HTML với JavaScript + CSS
- Workflow bằng SVG và HTML
- Dữ liệu không gian bằng vị trí tuyệt đối và canvas
- Hình ảnh bằng thẻ ảnh
Theo mình, gần như không có tập thông tin nào Claude đọc được mà bạn lại không thể biểu diễn hiệu quả bằng HTML. Điều này biến HTML thành một cách rất hiệu quả để model truyền đạt thông tin chuyên sâu cho bạn và để bạn xem xét thông tin đó.
Mình nhận thấy khi không thể làm như vậy, model có thể làm những việc kém hiệu quả hơn trong Markdown, như vẽ sơ đồ ASCII hoặc — ví dụ mình thích nhất — mô phỏng màu sắc bằng ký tự Unicode.
Bảng màu trông như thế này khi Markdown là lựa chọn duy nhất.
Trực quan rõ ràng và dễ đọc
Khi Claude có thể xử lý công việc phức tạp hơn, nó cũng có thể viết những spec và kế hoạch ngày càng dài. Mình nhận thấy bản thân thường không thực sự đọc một file Markdown dài hơn 100 dòng, và chắc chắn mình cũng không thể khiến người khác trong tổ chức đọc nó.
Nhưng tài liệu HTML dễ đọc hơn nhiều, vì Claude có thể tổ chức cấu trúc một cách trực quan để bạn dễ điều hướng bằng tab, hình minh họa và liên kết. Tài liệu thậm chí có thể responsive trên thiết bị di động để bạn đọc theo cách phù hợp với loại thiết bị mình dùng.
Dễ chia sẻ
File Markdown khá khó chia sẻ vì phần lớn trình duyệt không tự hiển thị chúng tốt. Bạn thường phải đính kèm chúng vào email hoặc tin nhắn.
Chỉ cần tải file HTML lên, bạn có thể chia sẻ liên kết dễ dàng. Đồng nghiệp có thể mở nó ở bất cứ đâu họ muốn và dễ dàng tham khảo.
Khả năng ai đó thực sự đọc spec, báo cáo hoặc phần mô tả PR của bạn sẽ cao hơn nhiều nếu chúng ở dạng HTML.
Tương tác hai chiều
HTML cũng có thể cho phép bạn tương tác với tài liệu; chẳng hạn, bạn có thể yêu cầu thêm thanh trượt hoặc núm điều chỉnh để tinh chỉnh một thiết kế, hoặc cho phép thay đổi những tùy chọn khác nhau của thuật toán để xem điều gì xảy ra. Bạn cũng có thể yêu cầu nó cho phép sao chép những thay đổi này thành một prompt để dán lại vào Claude Code.
Khi phù hợp, cách này cho phép bạn tạo những môi trường chỉnh sửa riêng cho vấn đề cụ thể đang xử lý.
Tiếp nhận dữ liệu
Một trong những lý do lớn nhất để dùng Claude Code tạo file HTML thay vì Claude.ai hay Claude Design là toàn bộ context mà Claude Code có thể tiếp nhận. Chẳng hạn, khi viết bài này, mình yêu cầu Claude Code đọc thư mục code của mình, tìm tất cả file HTML mình đã tạo, nhóm và phân loại chúng, rồi tạo một file HTML có các sơ đồ biểu diễn từng loại. Những sơ đồ bạn thấy trong bài này là kết quả trực tiếp của việc đó.
Ngoài hệ thống file, Claude Code còn có thể tìm thêm context qua các MCP của bạn (như Slack, Linear, v.v.), trình duyệt web (với Claude in Chrome) và lịch sử git.
Bắt đầu
Một điều đáng lưu ý: bạn không cần làm nhiều để Claude tạo HTML như thế này. Bạn chỉ cần yêu cầu nó “tạo một file HTML” hoặc “tạo một sản phẩm đầu ra HTML (artifact)”. Điều quan trọng là biết bạn muốn artifact làm gì và có thể dùng nó như thế nào. Theo thời gian, việc xây dựng một skill cho những mẫu lặp lại có thể hữu ích, nhưng bắt đầu bằng cách viết prompt từ đầu là một cách tốt để cảm nhận cách nó hoạt động trong những trường hợp sử dụng khác nhau.
Các trường hợp sử dụng
Để cách tiếp cận này cụ thể hơn, dưới đây là một số ví dụ về trường hợp sử dụng mà mình cho rằng dùng file HTML hợp lý hơn Markdown. Bạn cũng có thể xem bộ sưu tập những trường hợp này trên GitHub tại đây.
Spec, lập kế hoạch và khám phá
HTML là một không gian biểu đạt phong phú để Claude đi sâu vào một vấn đề. Khi bắt đầu xử lý một vấn đề, thay vì một kế hoạch Markdown đơn giản, mình dự kiến sẽ tạo một mạng lưới các file HTML. Chẳng hạn, mình có thể bắt đầu bằng việc yêu cầu Claude Code brainstorm và khám phá một số phương án khác nhau. Sau đó, mình sẽ yêu cầu nó đào sâu hơn một phương án, có thể tạo mockup hoặc ví dụ về các interface kiểu dữ liệu. Cuối cùng, khi thấy ổn, mình sẽ yêu cầu nó viết kế hoạch triển khai. Khi hài lòng với kế hoạch, mình tạo một session mới và đưa tất cả các file này vào để nó triển khai.
Khi kiểm chứng, mình cũng yêu cầu agent kiểm chứng đọc các file đó, nhờ vậy nó có context rộng hơn nhiều về những gì cần làm.
Khám phá: nhiều cách tiếp cận đặt cạnh nhau cùng những đánh đổi, trên một trang.
Ví dụ prompt:
- Mình chưa chắc nên đi theo hướng nào cho màn hình onboarding. Tạo 6 cách tiếp cận khác biệt rõ rệt — thay đổi bố cục, sắc thái và mật độ thông tin — rồi trình bày chúng dưới dạng lưới trong một file HTML để mình so sánh cạnh nhau. Gắn nhãn cho từng phương án để chỉ rõ đánh đổi của nó.
- Tạo một kế hoạch triển khai chi tiết trong file HTML, nhớ làm một số mockup, thể hiện luồng dữ liệu và thêm những đoạn code quan trọng mà mình có thể muốn review. Làm sao để dễ đọc và dễ nắm bắt.
Dùng cho:
- Khám phá những cách khác để triển khai một thứ trong code
- Thử nghiệm nhiều thiết kế trực quan cùng lúc
Code review và tìm hiểu code
Code có thể khó đọc trong file Markdown, nhưng với HTML, chúng tôi có thể hiển thị diff, chú thích, lưu đồ và module. Dùng HTML để hiểu code mà agent đã viết, review code hoặc giải thích một PR cho người đang review code của bạn.
Code review: diff được hiển thị cùng ghi chú ở lề có nhãn mức độ nghiêm trọng.
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 không quen lắm với logic streaming/backpressure, nên hãy tập trung vào phần đó. Hiển thị diff thực tế với chú thích ở lề gắn vào từng dòng, tô màu các phát hiện theo mức độ nghiêm trọng và thêm bất cứ thứ gì cần thiết để truyền tải rõ khái niệm.
Dùng cho:
- Tạo PR
- Review PR
- Tìm hiểu một chủ đề trong code
Thiết kế và prototype
Claude Design dựa trên HTML vì HTML có khả năng biểu đạt thiết kế cực kỳ phong phú, ngay cả khi giao diện cuối cùng của bạn không phải HTML. Claude có thể phác thảo thiết kế bằng HTML rồi viết nó bằng ngôn ngữ bạn chọn, dù là React, Swift, v.v.
Bạn cũng có thể tạo prototype cho các tương tác, như animation, hành động, v.v. Hãy cân nhắc yêu cầu Claude làm thanh trượt, núm điều chỉnh, v.v. để tinh chỉnh đúng những gì bạn đang tìm kiếm.
Thiết kế: token và component được hiển thị đúng như hình thức thực tế của chúng.
Ví dụ prompt:
Mình muốn tạo prototype cho một nút checkout mới, khi bấm thì nó chạy animation rồi nhanh chóng chuyển sang màu tím. Tạo một file HTML với vài thanh trượt và tùy chọn để mình thử các phương án khác nhau cho animation này, thêm nút sao chép để mình sao chép những tham số phù hợp.
Dùng cho:
- Tạo artifact cho design system
- Điều chỉnh component
- Trực quan hóa thư viện component
- Tạo prototype cho animation
Báo cáo, nghiên cứu và học tập
Claude Code rất hiệu quả trong việc tổng hợp thông tin từ nhiều nguồn dữ liệu rồi chuyển thành báo cáo dễ đọc. Bạn có thể yêu cầu Claude tìm kiếm trong Slack, codebase, lịch sử git hoặc trên internet rồi dùng kết quả để tạo các báo cáo dễ đọc.
Bạn có thể tập hợp thông tin dưới dạng một tài liệu HTML dài, một trang giải thích có tương tác hoặc thậm chí một bộ slide thuyết trình. Hãy yêu cầu Claude dùng SVG để vẽ sơ đồ giúp trực quan hóa nội dung.
Báo cáo: một trang giải thích có điều hướng, các bước có thể thu gọn và các đoạn code chia theo tab.
Ví dụ prompt:
Mình không hiểu rate limiter của chúng tôi thực sự hoạt động như thế nào. Đọc code liên quan và tạo một trang HTML giải thích duy nhất: một sơ đồ về luồng token-bucket, 3–4 đoạn code then chốt có chú thích và một mục “những điểm dễ vấp” ở cuối. Tối ưu cho người chỉ đọc một lần.
Dùng cho:
- Viết tóm tắt tính năng
- Tạo nội dung giải thích
- Soạn báo cáo tình hình hằng tuần
- Tạo báo cáo sự cố
- Tạo hình minh họa SVG, lưu đồ và sơ đồ kỹ thuật
Giao diện chỉnh sửa tùy chỉnh
Đôi khi rất khó mô tả điều bạn muốn chỉ bằng một ô nhập văn bản. Với trường hợp này, mình thường yêu cầu Claude dựng một trình chỉnh sửa dùng một lần cho đúng thứ mình đang xử lý: không phải sản phẩm hay tool tái sử dụng, mà là một file HTML duy nhất, được xây dựng riêng cho dữ liệu cụ thể đó.
Mấu chốt là luôn kết thúc bằng chức năng xuất: một nút “sao chép thành JSON” hoặc “sao chép thành prompt” biến những gì mình đã làm trên UI thành thứ có thể dán vào Claude Code hoặc commit vào file. Bạn vẫn tham gia vào vòng lặp, nhưng vòng lặp trở nên chặt chẽ hơn nhiều.
Ví dụ prompt:
- Mình cần sắp xếp lại mức độ ưu tiên của 30 ticket Linear này. Tạo một file HTML với mỗi ticket là một thẻ có thể kéo thả giữa các cột Bây giờ / Tiếp theo / Để sau / Loại bỏ. Sắp xếp trước theo phán đoán tốt nhất của bạn. Thêm nút “sao chép thành Markdown” để xuất thứ tự cuối cùng, kèm một dòng giải thích cho mỗi nhóm.
- Đây là config feature flag của chúng tôi. Dựng một trình chỉnh sửa dựa trên form, nhóm các flag theo khu vực, thể hiện dependency giữa chúng và cảnh báo nếu mình bật một flag trong khi flag tiên quyết của nó đang tắt. Thêm nút “sao chép diff” chỉ trả về những key đã thay đổi.
- Mình đang tinh chỉnh system prompt này. Tạo một trình chỉnh sửa hai phần đặt cạnh nhau: prompt có thể sửa ở bên trái với các vị trí biến được tô nổi bật, ba đầu vào mẫu ở bên phải cập nhật trực tiếp bản mẫu đã điền. Thêm bộ đếm ký tự/token và nút sao chép.
Dùng cho:
- Sắp xếp lại, phân loại xử lý hoặc chia nhóm bất cứ thứ gì (ticket, test case, phản hồi)
- Chỉnh sửa config có cấu trúc (feature flag, biến môi trường, JSON/YAML có ràng buộc)
- Tinh chỉnh prompt, mẫu hoặc nội dung chữ với bản xem trước trực tiếp
- Tuyển chọn dataset — duyệt/từ chối dòng, gắn nhãn ví dụ, xuất phần đã chọn
- Chú thích tài liệu, bản ghi hội thoại hoặc diff rồi xuất các chú thích
- Chọn những giá trị khó diễn đạt bằng văn bản: màu sắc, đường cong easing, vùng cắt ảnh, lịch cron, regex
Câu hỏi thường gặp
Đây là những câu hỏi mình thường được hỏi nhất về việc dùng HTML với Claude Code, cùng các thói quen thực tế hằng ngày mà mình đã chọn áp dụng:
Như vậy không kém hiệu quả hơn sao?
Dù Markdown thường dùng ít token hơn, mình thấy khả năng biểu đạt phong phú hơn của HTML và việc mình có khả năng thực sự đọc nó cao hơn nhiều giúp mình có đầu ra tốt hơn về tổng thể. Với context window 1MM trong Opus 4.7, lượng token tăng thêm không thực sự đáng kể trong context window.
Hiện tại bạn dùng Markdown khi nào?
Thật lòng thì mình đã ngừng dùng Markdown cho gần như mọi thứ, nhưng có lẽ mình thuộc phe cực kỳ chuộng HTML.
Đây có phải cách bạn thay thế việc lập kế hoạch không?
Mình nhận thấy thay vì có một kế hoạch duy nhất, mình thường có vài file HTML khác nhau cho những phần/giai đoạn khác nhau của kế hoạch. Chẳng hạn, mình có thể tạo một kế hoạch triển khai bằng HTML, rồi làm một file khác để khám phá UI và cuối cùng tạo một component HTML liệt kê mọi thiết kế. Mình thường giữ lại các file này để tham khảo về sau, cũng như dùng cho việc kiểm chứng.
Tiếp tục tham gia vào vòng lặp cùng Claude
Tất cả những điều trên nhằm nói rằng lý do thực sự mình dùng HTML thay vì Markdown là nó giúp mình cảm thấy được tham gia vào vòng lặp cùng Claude nhiều hơn. Khi Claude đảm nhận nhiều việc hơn, mình nhận ra bản thân đọc kế hoạch ít kỹ hơn, và mình muốn tìm cách tiếp tục tham gia vào những lựa chọn của nó thay vì chỉ giao phó mọi thứ. HTML hóa ra chính là cách đó. Giờ mình cảm thấy tham gia sát sao hơn bất kỳ lúc nào trước đây.
Bắt đầu với Claude Code.
Bài viết này được viết bởi Thariq Shihipar, thành viên đội ngũ kỹ thuật, và thể hiện quan điểm cá nhân — cùng sự yêu thích — của anh đối với việc dùng file HTML với Claude Code.