Topic 173 · HTML Companion Artifact

Markdown để nhớ. HTML để nhìn.

Bài @trq212 không nói “bỏ Markdown”. Ý đáng giữ là: khi agent tạo nhiều nội dung hơn con người, format tốt nhất là format giúp người thật đọc, hiểu, duyệt và phản hồi nhanh nhất.

Verdict cho Team Tam Quốc/Hermes: Markdown/Obsidian là source-of-truth. HTML là artifact trình bày hoặc tương tác khi có ROI rõ.

Claim/source matrix

Claim
Bằng chứng / nguồn
Trạng thái
Markdown đang là format phổ biến cho agent output nhưng bắt đầu chật với report/spec dài.
Raw X mirror ghi rõ luận điểm về Markdown dominant và hạn chế với file dài, spec, report, reference.
Đã kiểm
HTML hợp với artifact cần layout, diagram, bảng, form, slider, copy/export.
Raw liệt kê planning/exploration, code review, design/prototyping, reports/explainers, throwaway editors/data tools.
Đã kiểm
Claude Code phù hợp để tạo artifact HTML vì có thể làm việc với codebase, file, command, git/MCP.
Đối chiếu Claude Code docs, output styles docs, GitHub Anthropic Claude Code.
Đã kiểm
HTML tăng xác suất người thật đọc artifact dài.
Lý luận workflow: summary box, claim table, timeline, risk màu sắc giúp quyết định nhanh hơn Markdown dài.
Nhận định
HTML tạo lâu hơn 2–4x và khiến người đọc đọc nhiều hơn.
Kinh nghiệm cá nhân của tác giả; chưa có benchmark độc lập trong lượt này.
Chưa kiểm

Flow đề xuất cho Team Tam Quốc

1. Raw-firstLấy nguồn thật trước, lưu raw artifact. Không synthesize từ trí nhớ.
2. Markdown reportObsidian giữ bản canonical: dễ search, diff, link, sửa lâu dài.
3. Chọn mứcmarkdown-only, html-view, hoặc html-interactive.
4. HTML companionNếu giúp đọc/so sánh/quyết định nhanh hơn, tạo single-file no-CDN.
5. Export backNếu có tương tác, luôn có nút copy/export Markdown/JSON/prompt/diff.

Khi nào dùng HTML, khi nào giữ Markdown?

HTML hợp khi cần nhìn/chọn/chỉnh
  • Report dài cần executive summary, bảng nguồn, timeline.
  • PR/code review khó hiểu cần annotation và severity.
  • So sánh nhiều phương án bằng card/grid.
  • Prototype UI, dashboard, design system preview.
  • Throwaway editor cho backlog, config, prompt, annotate transcript.
Markdown hợp khi cần nhớ/diff/search
  • DECISIONS.md, SOP, README, project status.
  • Canonical report trong Obsidian.
  • Nội dung cần Git review rõ.
  • Checklist/plan ngắn, summary ngắn.
  • Tài liệu nhạy cảm không muốn mở JavaScript.

Rủi ro và guardrail

Rủi ro
  • HTML khó diff, nhiễu style/script.
  • Dễ trộn content với presentation.
  • JS tăng bề mặt bảo mật.
  • Upload public có thể lộ thông tin.
Guardrail
  • Không secret/token/API key.
  • Không CDN/network mặc định.
  • Single-file self-contained.
  • Header comment ghi nguồn, path, sensitivity.
Decision rule
  • HTML chỉ đáng làm nếu giảm ma sát đọc hoặc ra quyết định.
  • Nếu chỉ là text tuyến tính: markdown-only.
  • Nếu có interaction: phải export/copy được.

Action cụ thể

Ngay lập tức

Giữ report Markdown canonical, thêm link tới HTML companion này để thử nghiệm đọc nhanh.

Thử có kiểm soát

Chọn 3 report topic 173: technical architecture, market/product strategy, agent workflow/tooling để tạo HTML companion.

Đo ROI

Hỏi 4 câu: đọc nhanh hơn không, quyết định dễ hơn không, share dễ hơn không, có đáng thời gian generate thêm không.

Sources

Đã copy verdict Markdown.