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