Đo thật: HTML hay Markdown cho AI coding agent

1. Một video short hơn một triệu view và một thread không ai đo

Video mở đầu bằng một video short cũ của chính kênh DIY Smart Code, về luận điểm rằng HTML tốt hơn Markdown khi làm việc với coding agent. Video short đó đã vượt một triệu view. Comment đứng đầu có hơn 3.000 like và nói: "Simplicity is the feature, not a bug", tức sự đơn giản là tính năng chứ không phải lỗi. Một comment khác, khoảng 500 like, nói rằng Markdown tiết kiệm được rất nhiều token. Tác giả thừa nhận đó là một ý đúng (fair point).

Vấn đề là chẳng ai trong thread đó đo đạc gì cả, kể cả chính anh. Nên lần này anh đo. Cùng một nội dung, viết ra bằng bốn format, chạy thật bằng Claude Code trên model Opus 5.5, và mọi con số đều lấy từ usage report của chính Claude Code chứ không ước lượng.

Anh đưa luôn kết quả gây chú ý trước: với một status report đơn giản, HTML viết tự do (freeform HTML) tốn gấp 8 lần số token của Markdown. Với một board tương tác, con số đó là 21 lần. Rồi anh thay đổi đúng một thứ, và bản HTML có giá ngang bằng Markdown. Phần còn lại của video giải thích thay đổi đó là gì.

2. Bốn format, bốn việc, 72 lần chạy Claude Code

Bốn format được đưa vào thử nghiệm:

• A, Markdown thuần (plain Markdown).
• B, freeform HTML, đúng kiểu mà phần lớn mọi người vẫn prompt: một file tự chứa (self-contained) duy nhất, CSS viết inline, chart là SVG thật.
• C, HTML với template: phần design nằm trong một file script duy nhất, agent chỉ viết nội dung.
• D, Markdown kèm một renderer: agent viết Markdown, rồi renderer biến nó thành cùng một trang như bản HTML.

Mỗi format nhận bốn việc: một weekly status report gửi cho manager, một sơ đồ kiến trúc (architecture diagram), một triage board kéo thả (drag-and-drop), và một implementation plan mà agent thứ hai phải đọc để build theo.

Mỗi việc chạy ba lần cho mỗi format, trên một cấu hình Claude Code sạch: không skill, không plugin, không MCP server, để phần overhead cố định chỉ khoảng 3.000 token. Tổng cộng 72 lần chạy, và con số hiện trên màn hình luôn là lần chạy ở giữa (median) trong ba lần.

3. Status report: 883 token so với 7.200, và token đi đâu

Việc đầu tiên là status report. Markdown viết xong với 883 output token. Freeform HTML cần khoảng 7.200 (trên màn hình là 7.204). Tức gấp 8 lần số token, và mất 55 giây thay vì khoảng 7 giây.

Vậy token đi đâu? Anh tách các file freeform theo loại nội dung bên trong, tính theo số ký tự. Chỉ khoảng 14% ký tự là bản thân bản report. 38% là CSS. Thêm 14% là một chart vẽ tay bằng SVG. 11% là JavaScript cho tooltip và bộ lọc bảng mà anh chưa bao giờ yêu cầu. Còn các thẻ HTML chiếm khoảng 10%.

Kết luận của anh: token được tiêu vào việc thiết kế một trang web từ con số không, lặp lại trên từng file một.

4. Điểm yếu của Markdown: Mermaid và emoji

Nhưng Markdown cũng có điểm yếu riêng. Bảo nó vẽ chart thì bạn nhận về một block Mermaid: block đó render được trên GitHub, nhưng trong terminal của bạn thì nó vẫn chỉ là code thuần. Hỏi về trạng thái thì bạn nhận về emoji. Đó chính là phần mà phía HTML làm đúng.

Block chart mà bản Markdown viết ra trông như sau:

```mermaid
xychart-beta
    title "PRs merged per day (week 41)"
    x-axis [Mon, Tue, Wed, Thu, Fri]
    y-axis "PRs merged" 0 --> 8
    bar [3, 6, 4, 7, 3]
```

5. Sơ đồ kiến trúc: hai phút rưỡi để tính toạ độ SVG

Mọi chuyện tệ hơn khi trang cần hình ảnh thật. Sơ đồ kiến trúc tốn 1.600 token ở bản Markdown (màn hình ghi 1.672) và 17.000 token ở bản freeform HTML (17.314). Khoảng 5.000 trong số đó (5.091) là thinking token: model ngồi tính toạ độ SVG bằng tay. Hai phút rưỡi chỉ cho một sơ đồ.

6. Triage board: việc Markdown không làm được, và cái giá 21 lần

Triage board là việc Markdown hoàn toàn không làm được. Bạn chỉ nhận được các danh sách dưới từng heading, và muốn chuyển một ticket thì phải cắt dòng đó rồi dán sang chỗ khác.

Freeform HTML thì build ra một board thật, có kéo thả và một nút export, với giá khoảng 17.000 token (16.987). Đó là gấp 21 lần giá của Markdown, và hơn một nửa file là JavaScript.

Anh nói rõ một điều về cách thử: anh đã yêu cầu các lần chạy freeform làm trang cho chỉn chu (polished), vì đó chính là lý do người ta chọn HTML ngay từ đầu. Một trang HTML trơn thì tốn ít hơn, nhưng nó cũng trông y như Markdown.

7. Một thay đổi duy nhất: đưa design ra khỏi việc của agent

Thay đổi duy nhất là chuyển phần design ra khỏi công việc của agent. Một file, kit.js, chứa toàn bộ style, các chart, cách bố trí sơ đồ, và cả board. Agent chỉ viết một component cùng dữ liệu của nó, ví dụ một thẻ chart với năm dòng kiểu "Mon: 3", "Tue: 6".

Trong README của repo, một trang dùng kit bắt đầu bằng một dòng nạp script, rồi tới nội dung, ví dụ:

<!doctype html><meta charset="utf-8"><script src="kit/kit.js" defer></script>
<rk-header title="Weekly Engineering Status" sub="Team Checkout, week 41"></rk-header>
<rk-stats>
23 | PRs merged | +5 vs last week
</rk-stats>
<rk-chart type="bar" title="PRs merged per day">
Mon: 3
Tue: 6
</rk-chart>

8. Kết quả với kit: bằng hoặc rẻ hơn Markdown, và một cái giá đoán trước được

Anh chạy lại cùng bốn việc với kit. Report tốn 726 token. Sơ đồ khoảng 1.000. Board tốn 615, mà vẫn kéo thả chạy được thật. Trên cả ba việc có phần hình ảnh, kết quả bằng hoặc thấp hơn Markdown thuần, với 0 thinking token, vì chẳng còn gì để thiết kế nữa.

Về thời gian, report mất 6 giây thay vì 55, còn board mất 5 giây thay vì 2 phút 17 giây.

Đây cũng là một cái giá có thể lên kế hoạch được. Ba lần chạy board freeform rơi vào đâu đó từ khoảng 11.000 tới 17.500 token. Ba board dùng kit thì nằm gọn trong khoảng 573 đến 625.

Thanh trạng thái phía trên bảng và đường trung bình trên chart hoàn toàn không do agent viết. Kit tự đếm các status pill rồi vẽ chúng ra.

Agent vẫn cần danh sách các component, phần này thêm khoảng 600 input token cho mỗi lần gọi. Nhưng input là phía rẻ, và nó được cache.

9. Markdown cộng renderer: rẻ nhất trong cả bốn

Bản Markdown đi kèm renderer rơi vào cùng khoảng giá đó, và ở việc report, nó còn là rẻ nhất trong cả bốn format, chỉ 569 token.

Phần agent viết trong bản D, như trên màn hình:

stats: 23 PRs merged | 2 incidents | 412 ms p95 checkout
latency (was 530 ms) | 78% test coverage

## PRs merged per day

```chart
title: PRs merged per day
type: bar
Mon: 3
Tue: 6

Một reply khoảng 600 like dưới video short nói rằng Markdown vốn được thiết kế như một lựa chọn nhẹ thay cho HTML. Có renderer thì đó chính xác là điều nó làm ở đây. Mermaid và MDX cũng cùng một ý tưởng: viết nhẹ, render giàu (write it light, render it rich).

Nhưng tất cả những con số trên mới là chi phí viết ra một file. Một plan thì được mở lại ở mỗi bước mà một agent khác thực hiện, và đó là nơi hoá đơn lớn nhất của bài test này xuất hiện. Trước khi cho xem, anh hỏi người xem: bạn nghĩ các plan HTML có giúp build ra code tốt hơn không, có hay không? Anh mời mọi người để lại dự đoán trong phần comment.

Video có một đoạn quảng cáo cho Dynamous AI.

10. Plan cho agent khác đọc: cùng pass test, khác hoá đơn

Plan là một loại việc khác hẳn, vì người đọc là một agent khác. Mỗi plan được giao cho một agent thứ hai, agent này phải viết một pricing module chỉ dựa vào plan, rồi 19 test ẩn kiểm tra kết quả: coupon, làm tròn thuế, gift card, đủ mọi edge case. Cả 12 lần build đều pass đủ 19 test.

Format không tạo ra khác biệt nào về độ đúng. Nó tạo khác biệt trên hoá đơn. Các plan freeform dài khoảng 22.000 token HTML (màn hình ghi 22.217 so với 6.756, tức 3,3 lần), gấp ba lần plan Markdown. Và mỗi bước sau khi agent mở file đó đều gửi lại toàn bộ file. Kết quả: 234.000 input token cho mỗi lần build, so với 86.000 từ một plan Markdown, tức tốn thêm khoảng hai phần ba chi phí cho cùng những test đã pass.

11. Một lần sửa nhỏ, và một bug trong bản freeform

Bài test cuối cùng là một thay đổi nhỏ: ticket CHK-102 đã xong, hãy cập nhật report. Mọi format đều làm đúng, nhưng hãy nhìn xem mỗi format phải chạm vào những gì.

Ở bản kit, agent sửa đúng hai dòng: trạng thái của ticket và danh sách việc tuần sau. Trang freeform trên màn hình thì có số đếm được hard-code ở sáu chỗ: độ rộng các đoạn trên progress bar, chú thích (legend), các nút lọc, chính dòng của ticket đó, và hơn thế. Mỗi chỗ trong số đó là một điểm mà lần sửa tiếp theo có thể bỏ sót.

Lần sửa đó cũng tốn hơn. Gần 30.000 input token cho trang freeform (màn hình ghi 29.843 so với 16.001), gần gấp đôi lần sửa trên bản Markdown.

Các lần chạy freeform còn ship kèm một bug: một trong ba plan có checklist bị hỏng, do lỗi JavaScript, trên một trang vốn chẳng bao giờ cần tới JavaScript.

12. Giới hạn của bài test và phép tính tiền

Anh nêu rõ giới hạn: mỗi ô (cell) chạy ba lần, trên một model duy nhất là Opus 5.5. Số tiền đô la là theo list price của Claude Code. Một nghìn board tốn khoảng 360 đô với freeform, và 39 đô với kit.

Nếu dùng subscription thì bạn trả bằng usage limit thay vì tiền, và một nghìn board freeform đó lấy đi của bạn nhiều hơn khoảng 16 triệu token so với một nghìn board dùng kit.

Anh cũng không gửi screenshot của các trang ngược lại cho agent. Nếu vòng lặp của bạn có làm vậy, image token sẽ cộng thêm lên trên mọi con số ở đây.

Viết một kit như thế này tốn khoảng 20.000 token, một lần. So với khoảng 6.000 token mà mỗi report freeform tốn thêm, kit tự hoàn vốn ở report thứ tư. Và kit chỉ biết những component nó có. Một trang mà kit không mô tả được sẽ tốn giá freeform cho tới khi bạn thêm component đó vào.

13. Khi nào HTML hợp lý: hỏi ai sẽ mở file

Vậy khi nào HTML hợp lý? Anh bắt đầu bằng câu hỏi: ai sẽ mở file này?

Nếu người mở là một agent khác, như một plan, một spec hay một ticket, hãy viết Markdown. Bài test plan đã chốt điều đó. Điều tương tự áp cho mọi thứ nằm trong terminal hoặc được sửa hàng tuần.

Nếu người mở là một con người, HTML xứng đáng có chỗ, nhất là khi trang phải làm được việc mà Markdown không làm được, như cái board kia. Bất cứ thứ gì bạn generate nhiều hơn một lần thì nên đi qua một template. Nếu team của bạn vốn đã viết Markdown, hãy thêm một renderer và không cần đổi gì khác.

Freeform cũng có chỗ dùng thật. Khi design chính là công việc, như một landing page hay một bản pitch bạn chỉ mở một lần, hãy để model tự thiết kế và trả cái giá gấp tám lần đó một lần. Như vậy vẫn hơn là viết cả một kit cho một trang duy nhất. Với mọi thứ còn lại, bỏ qua bản freeform.

14. Repo để tự chạy lại, và ai thắng thread

Kit, file skill cho Claude Code và toàn bộ benchmark nằm trong một repo được link dưới video (leex279/agent-html-kit), để bạn có thể tự chạy cả 72 lần trên setup của mình.

Anh quay lại thread ban đầu. Comment đứng đầu dưới video short nói rằng sự đơn giản là tính năng. Với plan, các con số ủng hộ câu đó. Với trang cho người đọc, một template đã làm HTML rẻ ngang Markdown. Vậy ai thắng thread đó: Markdown, hay HTML với template? Anh để câu hỏi đó lại cho người xem.