System Note  AI Agent Communication

Markdown: người viết cho máy.
HTML: máy viết cho người.

Khi AI Agent tạo spec, plan, report dài hàng trăm dòng — Markdown không còn đủ. Bài này chuyển ý tưởng từ "The Unreasonable Effectiveness of HTML" thành một trang HTML đọc được, tương tác được, deploy được. Nó không chỉ nói HTML tốt hơn — chính nó là minh chứng.

Xem minh chứng Lệnh deploy
01 — Context

Vấn đề không phải Markdown dở. Vấn đề là AI đang viết quá dài.

Khi Agent trả lời ngắn, Markdown đủ. Nhưng khi Agent tạo spec, plan, report, PR dài hàng trăm dòng — định dạng tuyến tính kéo người đọc ra khỏi vòng kiểm soát.

1 Trước đây

Markdown là mặc định

Đơn giản, portable, dễ sửa tay, có heading, list, bold, code block. Với ghi chú ngắn hoặc docs kỹ thuật — Markdown vẫn hợp lý.

2 Bây giờ

Agent tạo sản phẩm tri thức

Claude Code đọc codebase, git history, Slack, Linear rồi tổng hợp thành plan hoặc báo cáo lớn. Output không còn là ghi chú — nó là sản phẩm.

3 Hệ quả

Người không còn đọc hết

Markdown hơn 100 dòng là tác giả không muốn đọc kỹ. Khó thuyết phục đồng đội hoặc quản lý đọc đầy đủ. Hệ quả: mất kết nối với output của AI.

"Markdown phù hợp để con người viết cho máy.
HTML phù hợp hơn để máy viết cho con người."
02 — Tại sao HTML

6 lý do HTML thắng Markdown trong kỷ nguyên AI Agent.

Không phải HTML "đẹp hơn". Nó là phương tiện băng thông cao để AI truyền tải thông tin phức tạp cho con người.

1 Density

Mật độ thông tin cao

HTML chứa bảng, CSS, SVG, canvas, ảnh, script, workflow, layout không gian. Cùng nội dung — HTML nén thành trải nghiệm giàu ngữ cảnh hơn.

2 Clarity

Trực quan, scan nhanh

Tabs, card, annotation, timeline, màu sắc, responsive layout. Người đọc scan nhanh rồi đào sâu đúng phần cần — không phải đọc tuyến tính từ đầu đến cuối.

3 Sharing

Chia sẻ bằng một link

Markdown phải gửi file hoặc mở bằng tool. HTML deploy lên Cloudflare, S3 — thành link ai cũng mở được trên browser.

4 Interface

Tài liệu → Giao diện

HTML không chỉ đọc. Nó có thể là mini tool: slider, toggle, editor, copy JSON, copy prompt, drag-drop, preview realtime. Tài liệu sống.

5 Context

Claude Code có ngữ cảnh rộng

Đọc local files, codebase, git history, MCP. HTML tạo ra bám sát dự án — không phải output generic từ prompt web đơn lẻ.

6 Joy

Cảm giác tham gia

Nhìn artifact đẹp, clickable, chỉnh được — cảm giác cùng AI định hình sản phẩm. Không phải bị giao một bức tường chữ.

03 — Thực dụng

Không phải HTML luôn thắng. Dùng đúng việc.

Diginno theo tư duy thực dụng: công cụ nào phù hợp việc đó. Không thần thánh hóa, không bài trừ.

Markdown vẫn có chỗ

  • ✓Token gọn, tạo nhanh, diff dễ review.
  • ✓Ghi chú ngắn, README, docs cần chỉnh tay thường xuyên.
  • ✓Dễ version control, merge, đọc raw trong terminal.

HTML khi cần tác động

  • ✓Tài liệu dài cần tăng khả năng đọc hết và hiểu nhanh.
  • ✓So sánh phương án, flowchart, mockup, report, code annotation.
  • ✓Chia sẻ cho khách hàng, team, quản lý bằng một đường link.
Nhược điểm

Tốn thời gian hơn

HTML có thể mất 2-4× thời gian tạo so với Markdown. Nhưng nếu nhiều người thực sự đọc hơn — chi phí này đáng.

Nhược điểm

Diff rối hơn Markdown

Nhiều markup, style, script nên git diff không sướng. Cách xử lý: review trên browser, giữ source idea riêng.

Nhược điểm

Streaming khó hơn

Stream HTML + CSS + JS phức tạp hơn stream Markdown. Cân nhắc nếu build tool realtime.

03.5 — Khung ra quyết định

Markdown hay HTML? Tùy 3 trục.

Không phải cái nào cũng HTML, cũng không phải cái nào cũng Markdown. Chọn theo nội dung, người xem, và mục đích.

A Nội dung

Ngắn hay dài?

Markdown

Ghi chú, README, changelog, prompt nhỏ, docs kỹ thuật dưới ~50 dòng.

HTML

Spec, plan, report, PR writeup, design exploration — trên 100 dòng, nhiều ngữ cảnh.

B Người xem

Ai sẽ đọc?

Markdown

Developer, người trong team quen đọc raw file, terminal, git diff.

HTML

Khách hàng, quản lý không code, team cross-functional, người cần scan nhanh.

C Mục đích

Để làm gì?

Markdown

Version control, merge, review code, lưu trữ lâu dài, source of truth.

HTML

Chia sẻ bằng link, thuyết trình, demo, tương tác, thuyết phục, sell idea.

Câu hỏi nhanh — 30 giây chọn định dạng

Q1: Tài liệu này có dài hơn ~100 dòng không?

Q2: Có ai không quen code sẽ đọc không?

Q3: Có cần chia sẻ bằng link, tương tác, hoặc thuyết phục không?

04 — Kịch bản giá trị cao

Dùng HTML ở đâu để có lợi ngay?

Specs, planning, exploration

Thay vì một plan Markdown dài — tạo mạng file HTML: so sánh option → mở rộng option thắng → thêm mockup, data flow, code snippet → chốt implementation plan. Verification agent đọc HTML có context phong phú hơn.

Code review & understanding

HTML render diff, margin annotation, flowchart module, risk severity. Tác giả bài gốc đính kèm HTML code explainer vào mọi PR — đôi khi dễ đọc hơn GitHub diff.

Design & prototypes

HTML phác thảo UI — kể cả sản phẩm cuối là React, Swift hay mobile. Thêm slider chỉnh animation, trạng thái, màu, easing rồi copy thông số.

Reports, research, learning

Một report HTML gom Slack, git history, codebase, internet thành explainer một trang. Người đọc nắm vấn đề trong một lần — không lục qua 5 file Markdown.

One-off editing interfaces

Kéo ticket vào Now/Next/Later/Cut, sửa feature flags có dependency, tune prompt với live preview, annotate transcript rồi export. Nơi HTML vượt xa tài liệu tĩnh.

05 — Tín hiệu thị trường

Phản ứng cộng đồng: ủng hộ, mở rộng, và hoài nghi.

Nik, Johnny Silverhand, Joe Fernandez Ủng hộ

Đồng ý Markdown giới hạn khả năng tùy biến. Một số đã dùng: Markdown phác thảo nhanh → HTML khi làm sâu với AI. Nếu Agent có styleguide, output càng nhất quán.

Jon Kurtis Mở rộng

Liên hệ xu hướng quay về web primitives — ít build tool hơn, vì LLM ngày càng giỏi sinh HTML/CSS/JS trực tiếp. Interactive planning docs có thể là use case tự nhiên.

Brennan McEachran, leo Hoài nghi

Stream HTML + CSS + JS khó hơn stream Markdown. Có người chất vấn: liệu tôn vinh HTML có phải là cách né việc tối ưu Markdown? Phản biện đáng giữ để không thần thánh hóa.

06 — Minh chứng

Trang này đang chứng minh chính luận điểm của nó.

Nếu để ở Markdown — hàng trăm dòng tuyến tính. Ở đây, cùng nội dung thành tài sản: mở browser, đọc theo section, tương tác tab, copy lệnh deploy, chia sẻ bằng link.

5 điều trang này chứng minh

  • ✓Một file duy nhất — không build step, không CDN, không external asset.
  • ✓Biến input Markdown dài thành layout: hero, card, tabs, so sánh, FAQ.
  • ✓Interaction thật: tab switching, reading progress, copy command.
  • ✓Deploy ngay lên Cloudflare — thành content link.
  • ✓Giữ người đọc bằng thị giác — không bắt đọc wall of text.
Anatomy
<!doctype html>
<html lang="vi">
  <head>
    <style>
      /* Brand: Diginno Pixel UI */
      /* --brand-dark: #111827 */
      /* --brand-green: #00E599 */
      /* --brand-blue:  #7DD3FC */
    </style>
  </head>
  <body>
    <main>
      content + SVG + tabs + deploy guide
    </main>
    <script>
      /* interactions only */
    </script>
  </body>
</html>
07 — FAQ

Câu hỏi phản biện cần trả lời trước.

HTML có tốn token hơn không?
Có. Markdown token-efficient hơn. Nhưng nếu HTML làm người đọc hiểu nhanh hơn, đọc hết nhiều hơn, tương tác nhiều hơn — chất lượng output tổng thể cao hơn chi phí token tăng. Context window lớn hiện nay, token tăng không phải bottleneck chính.
Khi nào vẫn nên dùng Markdown?
Ghi chú ngắn, README, docs cần sửa tay thường xuyên, changelog, prompt nhỏ, hoặc nơi version control quan trọng hơn trải nghiệm đọc.
Làm sao để HTML không xấu?
Cần design system hoặc styleguide. Trang này dùng Diginno Pixel UI — palette, typography, card, tabs, sharp corners, pixel shadow — chuẩn hóa để tránh output ngẫu nhiên.
HTML có thay thế blog/CMS không?
Không. Phù hợp nhất cho artifact cụ thể: explainer, report, proposal, planning doc, prototype. Cần hệ thống publishing lớn — CMS vẫn có vai trò.
HTML có thay thế Markdown hoàn toàn?
Tác giả bài gốc gần như bỏ Markdown hoàn toàn — nhưng đó là lập trường cực đoan. Diginno khuyên: dùng đúng việc. Markdown cho notes. HTML cho content cần tác động.
08 — Deployment

Deploy lên Cloudflare bằng Wrangler CLI.

Cloudflare Pages là đường ngắn nhất: đặt file trong folder public, deploy folder. Không cần framework nếu mỗi artifact là một file hoàn chỉnh.

Wrangler Pages commands
# Bước 1: Tạo folder dist
mkdir -p dist

# Bước 2: Copy file HTML thành index.html
cp docs/raw/md2html-content.html dist/index.html

# Bước 3: Tạo project trên Cloudflare Pages
npx wrangler pages project create md2html-artifact

# Bước 4: Deploy
npx wrangler pages deploy dist --project-name=md2html-artifact

# Done → Access tại: https://md2html-artifact.pages.dev
09 — Kết luận

Linh hoạt là từ khóa.

Markdown không chết. HTML không thay thế mọi thứ. Bài học lớn nhất là: chọn định dạng dựa trên nội dung, người xem, và mục đích — không phải dựa trên trend hay cảm xúc.

Markdown: người viết cho máy.
HTML: máy viết cho người.
Nhưng người thông minh — dùng cả hai.