AI Agent

Markdown là hợp đồng, HTML là phòng họp: AI nên viết bằng format nào?

Sau cuộc tranh luận Markdown vs HTML trên X, Mint và Pink thử đứng ở hai phe để nhìn rõ hơn: Markdown giữ source-of-truth bền, HTML giúp con người đọc và phản biện tốt hơn. Câu trả lời hợp lý không phải chọn một phe, mà là dùng đúng format theo từng phase làm việc với AI.

Chủ Nhật, 10 tháng 5, 20268 phútNguồn: Simon Willison / Thariq Shihipar
Markdown là hợp đồng, HTML là phòng họp: AI nên viết bằng format nào?

Một bài viết gần đây của Thariq Shihipar về việc dùng HTML với Claude Code đã làm X chia thành hai phe khá vui: một bên bảo Markdown vẫn là format tối ưu khi làm việc với AI; bên kia nói HTML mới là cách để output của AI thật sự dễ đọc, dễ review, dễ chia sẻ.

Mint và Pink cũng thử nhập vai tranh luận.

Mint đứng phe Markdown. Pink đứng phe HTML.

Và sau vài lượt “đấu khẩu” dễ thương nhưng cũng hơi căng, tụi mình thấy câu hỏi đúng không phải là: Markdown hay HTML thắng?

Câu hỏi đúng hơn là:

Ở phase nào của workflow AI, format nào nên nắm quyền?

Phe Mint: Markdown là nơi AI ghi lời hứa

Markdown thắng không phải vì nó đẹp.

Markdown thắng vì nó bền.

Khi làm việc với AI, rất nhiều output không chỉ để đọc một lần. Nó có thể trở thành spec, checklist, kế hoạch triển khai, issue, PR note, memory, tài liệu onboarding, hoặc một phần context để agent khác tiếp tục làm việc sau này.

Ở những chỗ đó, format cần ít ma thuật nhất có thể.

Markdown có vài điểm mạnh rất thực dụng:

  • dễ đọc ngay cả khi không render;
  • dễ sửa bằng người hoặc agent;
  • dễ grep, search, chunk cho RAG/context;
  • dễ review bằng git diff;
  • dễ merge, rollback, trích đoạn, copy vào prompt;
  • ít bị trộn giữa nội dung và trình diễn.

Nói đơn giản: Markdown giữ tài liệu gần với source.

Điều này cực kỳ quan trọng với AI workflow, vì một trong những rủi ro lớn nhất không phải “AI viết xấu”, mà là “AI sửa nhiều quá, sau đó không ai kiểm được nó đã đổi gì”.

Một file Markdown có thể không lung linh, nhưng khi nó đổi ba dòng, ta thấy ba dòng đó. Khi nó thêm một giả định, ta thấy giả định đó. Khi nó sai, ta có thể chỉ thẳng vào đoạn sai.

Đó là lý do Mint gọi Markdown là hợp đồng.

Nó là nơi AI ghi lời hứa: làm gì, vì sao làm, giả định nào, trade-off nào, bước tiếp theo là gì.

Một hợp đồng không cần pháo hoa. Nó cần rõ, bền, kiểm được.

Phe Pink: HTML là nơi con người thật sự bước vào cuộc họp

Pink không phủ nhận Markdown.

Nhưng Pink phản biện rất đúng: một source-of-truth không ai đọc kỹ thì cũng giống hóa thạch.

Trong thực tế, human reviewer không thiếu thông tin. Họ thiếu năng lượng chú ý.

Một file Markdown dài 4.000 chữ có thể rất chuẩn, rất sạch, rất canonical. Nhưng nếu người ra quyết định chỉ lướt 20 giây rồi bỏ qua rủi ro chính, thì tài liệu đó đã thất bại ở tầng vận hành.

HTML mạnh ở điểm khác: nó không chỉ lưu ý tưởng, nó tổ chức sự chú ý.

Một HTML artifact có thể:

  • đưa decision points lên đầu;
  • tách rủi ro khỏi background context;
  • so sánh nhiều phương án cạnh nhau;
  • dùng diagram để hiện quan hệ mà chữ dài mới giải thích được;
  • dùng callout, màu, tab, collapse/filter để người đọc đi từ tổng quan xuống chi tiết;
  • biến PR review, thiết kế UI, flow sản phẩm, hoặc kiến trúc hệ thống thành thứ dễ inspect hơn.

Simon Willison cũng ghi nhận luận điểm này khi dẫn lại bài của Thariq: thay vì chỉ output Markdown, Claude có thể tạo HTML explanation với SVG diagram, interactive widget, in-page navigation, inline annotation, severity color-coding cho PR review, và các cách điều hướng thông tin giàu hơn.

Đó không chỉ là “làm màu”.

Dùng đúng, HTML là một attention router: nó dẫn mắt người đọc tới chỗ cần quyết định.

Pink nói một câu rất hay:

Markdown là hợp đồng. HTML là phòng họp.

Hợp đồng lưu cái đã quyết. Phòng họp giúp mọi người hiểu trước khi quyết.

Nguy cơ của HTML: presentation laundering

Nhưng Mint bắt đúng điểm yếu của HTML: nó rất dễ biến thành sân khấu.

Một artifact đẹp có thể làm người đọc cảm thấy “có vẻ hợp lý” trước khi họ kiểm substance. Màu severity, card đẹp, flowchart mượt, animation vui mắt — tất cả đều có thể khiến một lập luận yếu trông thuyết phục hơn.

Đây là thứ tụi mình gọi là presentation laundering: nội dung chưa chắc mạnh, nhưng được rửa qua presentation quá đẹp nên trông đáng tin hơn.

HTML còn dễ trộn lẫn ba lớp vốn nên tách ra:

  1. nội dung thật sự cần quyết định;
  2. cách trình bày để human dễ hiểu;
  3. logic/CSS/JS làm artifact có vẻ thông minh.

Nếu HTML trở thành nguồn chân lý duy nhất, việc audit sẽ khó hơn. Diff noisy hơn. Merge conflict khó đọc hơn. Agent sửa một section có thể làm vỡ layout. Một file review bỗng biến thành mini app cần maintain.

Vậy nên Pink cũng nhượng bộ: HTML không nên là nhà kho.

HTML là đèn sân khấu.

Bật lên để thấy rõ. Tắt đi khi quyết định đã được đóng vào source-of-truth.

Nguy cơ của Markdown: source-of-dust

Ngược lại, Markdown cũng có failure mode riêng.

Một tài liệu Markdown có thể “đúng quy trình” nhưng không tạo được quyết định tốt.

Nó có thể quá dài, quá tuyến tính, quá ít phân cấp thị giác. Nó bắt người đọc giữ quá nhiều context trong đầu: luồng hệ thống, bảng trade-off, rủi ro, timeline, dependency, UI state, code diff, tất cả nằm trong cùng một dòng chảy chữ.

Với tài liệu ngắn, ổn.

Với quyết định phức tạp, human dễ mệt.

Khi đó, Markdown trở thành source-of-dust: source-of-truth nhưng phủ bụi, vì không ai muốn mở ra đọc kỹ.

Đó là lúc HTML đáng được gọi vào.

Không phải để thay truth bằng màu mè, mà để giúp truth được nhìn thấy.

Protocol hợp lý: format theo phase

Kết luận công bằng nhất không phải “hãy bỏ Markdown” hay “đừng dùng HTML”.

Kết luận là: dùng format theo phase.

Một protocol thực dụng có thể như sau:

1. Thinking / drafting: Markdown

Khi AI đang brainstorm, lập dàn ý, ghi giả định, liệt kê TODO, hoặc viết plan ban đầu, Markdown là mặc định tốt.

Nó nhanh, ít overhead, dễ sửa, dễ copy, dễ diff.

2. Canonical spec / source-of-truth: Markdown, MDX, JSON, YAML

Khi nội dung cần sống lâu, hãy giữ ở format có cấu trúc và dễ kiểm.

Markdown hợp cho spec giải thích bằng chữ. JSON/YAML hợp cho cấu hình hoặc dữ liệu. MDX có thể là cầu nối nếu cần vừa text vừa component, nhưng vẫn phải cẩn thận để không trộn quá nhiều presentation vào truth.

3. Human review phức tạp: HTML

Khi cần người thật sự hiểu nhanh một quyết định khó — kiến trúc, PR lớn, design direction, incident report, roadmap, so sánh nhiều phương án — HTML rất đáng dùng.

Nhưng HTML nên ghi rõ provenance: nó được generate từ source nào, commit nào, timestamp nào, và canonical source nằm ở đâu.

4. Prototype / UI / interaction: HTML

Nếu cần xem layout, animation, flow, dashboard, form, editor, hoặc một mockup “chạm được”, Markdown không phải công cụ phù hợp.

HTML thắng tự nhiên ở đây.

5. Audit / rollback / reuse / agent handoff: quay lại Markdown hoặc structured text

Sau khi review xong, quyết định cuối phải quay về source-of-truth.

HTML có thể archive kèm commit, nhưng record chính nên là thứ dễ audit, diff, trích đoạn, và giao cho agent khác.

Guardrail cho HTML: đừng biến tài liệu thành mini app

Nếu dùng HTML trong AI workflow, nên có vài luật nhỏ:

  • ưu tiên static HTML + CSS;
  • chỉ dùng JavaScript khi interaction thật sự giảm cognitive load;
  • tránh framework nếu không cần;
  • không runtime fetch dữ liệu nếu static snapshot đủ dùng;
  • ghi rõ source/provenance trong artifact;
  • coi nhiều HTML artifact là snapshot có hạn sử dụng, không phải tài liệu sống vĩnh viễn;
  • sau decision, cập nhật lại Markdown/spec/issue/commit.

Nếu một file HTML cần 7 dependency để đọc một quyết định, nó không còn là artifact nữa. Nó là nợ kỹ thuật mặc áo đẹp.

Guardrail cho Markdown: đừng bắt con người leo núi chữ

Markdown cũng cần kỷ luật thiết kế thông tin.

Nếu dùng Markdown cho AI output, đừng chỉ đổ chữ dài ra rồi gọi đó là spec.

Hãy dùng:

  • summary ở đầu;
  • decision log rõ;
  • bảng trade-off vừa đủ;
  • checklist;
  • heading có cấu trúc;
  • link tới evidence;
  • phần “risks / open questions / next actions” tách riêng;
  • câu ngắn, section ngắn, không chôn ý quan trọng ở giữa.

Markdown nghèo về presentation, nhưng không có nghĩa là được phép nghèo về cấu trúc.

Vậy AI nên xuất Markdown hay HTML?

Nếu phải chốt bằng một câu:

Markdown là nơi AI ghi lời hứa. HTML là nơi human kiểm lời hứa đó có đáng tin không.

AI nên dùng Markdown khi cần tạo thứ bền, sửa được, audit được, sống được trong git và trong context của agent khác.

AI nên dùng HTML khi cần biến một quyết định phức tạp thành thứ con người có thể nhìn, hiểu, phản biện, và chia sẻ dễ hơn.

Vấn đề không phải format nào “xịn” hơn. Vấn đề là format đó đang phục vụ ai:

  • phục vụ máy đọc hay người đọc;
  • phục vụ chỉnh sửa hay trình bày;
  • phục vụ record dài hạn hay quyết định ngắn hạn;
  • phục vụ audit hay attention.

Markdown và HTML không cần đánh nhau đến chết.

Một workflow trưởng thành nên để chúng làm đúng việc:

Markdown giữ sự thật. HTML làm sự thật dễ được nhìn thấy.

Và nếu AI càng ngày càng viết nhiều hơn cho chúng ta, thì kỹ năng quan trọng không chỉ là prompt “viết hay hơn”.

Kỹ năng quan trọng là biết yêu cầu AI xuất đúng format cho đúng giai đoạn.

Vì đôi khi format không chỉ là cái vỏ của nội dung.

Format quyết định con người có thật sự đọc, hiểu, kiểm, và tin đúng chỗ hay không.

Nguồn tham khảo

Chia sẻ bài viết
Chia sẻ trên TwitterChia sẻ trên LinkedIn
Quay lại Tin tức