Modern Web Guidance 1.0: dạy coding agent viết web hiện đại thay vì JavaScript kiểu 2019

Tuần trước mình nhờ Claude Code thêm một hộp thoại xác nhận vào trang quản trị: mở khi bấm nút xóa, đóng khi bấm Esc hoặc bấm ra ngoài, focus quay về đúng nút vừa bấm. Agent trả về gần 200 dòng JavaScript và CSS tự viết: quản lý trạng thái, bắt phím, tính z-index, khóa cuộn trang, focus trap viết tay. Nhưng trình duyệt đã có sẵn <dialog> làm đúng những việc đó.

Nhờ viết accordion hay tooltip cũng vậy, trong khi trình duyệt đã có <details> và Anchor Positioning. Agent chọn pattern phổ biến nhất trong dữ liệu huấn luyện, chứ không phải pattern tốt nhất hiện nay.

Modern Web Guidance 1.0, phát hành ngày 10/11/2026, sinh ra để sửa đúng điểm này. Nó là bộ skill kèm công cụ dòng lệnh, đưa guideline do chuyên gia biên soạn vào đúng lúc agent viết code, kèm một công cụ quét codebase cũ.

Modern Web Guidance là gì?

Nói gọn: Modern Web Guidance là bộ 203 guide theo từng use-case, bao phủ 250 tính năng của web platform, đóng gói thành skill cho coding agent kèm CLI tra cứu đúng lúc cần.

Phiên bản 1.0.0 ra khỏi preview vào ngày 10/11/2026, sau bản preview từ Google I/O tháng 5/2026. Dự án được stewarded bởi Google Chrome, Microsoft Edge, Mozilla Firefox và MDN, cùng cộng đồng phát triển web, với cơ cấu quản trị sáu ghế: Chrome hai, Edge một, Mozilla một, hai chuyên gia độc lập. Guide vì vậy là đồng thuận kèm dữ liệu tương thích, không phải ý kiến của một hãng.

Repo chính thức là GoogleChrome/modern-web-guidance, giấy phép Apache-2.0, 3.534 sao, 120 fork, một issue đang mở (11/11/2026). Lưu ý: source thật của các guide nằm ở repo sibling modern-web-guidance-src; repo này là repo phân phối và plugin, gửi issue nhầm chỗ sẽ lạc.

250 tính năng chia thành ba nhóm: 140 CSS và layout, 74 JavaScript và API, 36 HTML và DOM. Mỗi guide viết theo use-case — ví dụ “animate a dialog modal backdrop” — kèm code mẫu, dữ liệu Baseline về tương thích trình duyệt, và fallback khi trình duyệt mục tiêu chưa hỗ trợ.

Ai nên dùng

Ba nhóm hưởng lợi rõ nhất là lập trình viên dùng Claude Code, Codex, Cursor hay Gemini CLI hằng ngày; frontend developer review code do agent sinh ra; và người quản lý kỹ thuật quan tâm chất lượng code agent viết trong team. Ngược lại, nếu dự án chỉ làm backend hoặc team chưa dùng coding agent, thì công cụ này không mang lại gì đáng kể. Đọc thêm Hallmark và Taste.

Kiến trúc và cơ chế hoạt động

Hiểu đúng kiến trúc giúp tránh hai hiểu lầm: đây không phải model AI mới, và nó không nhồi toàn bộ 203 guide vào context window của agent.

Kho tri thức: 203 guide dạng Markdown theo từng use-case, kèm dữ liệu Baseline về tương thích trình duyệt và fallback khi trình duyệt mục tiêu chưa hỗ trợ.

CLI truy xuất: lệnh modern-web-guidance chạy qua npx, hoàn toàn offline, dùng BM25 kết hợp một embedding model không phụ thuộc bên ngoài để tìm guide khớp với ý định. Bản 1.0 bỏ TensorFlow.js, nhờ đó gói npm thu nhỏ từ 23,5 MB xuống 8,8 MB. Bốn lệnh chính là install, search, retrieve và legacy-scan.

Plugin tích hợp agent: có plugin cho Claude Code, Codex, Cursor, Gemini CLI, Grok và Kimi. Plugin chỉ là cầu nối: nó cho agent biết khi nào cần gọi search và retrieve, rồi nạp đúng guide đó vào context.

Luồng viết mới: prompt, agent gọi search, nhận guide kèm Baseline, sinh code dùng native API và kiểm tra fallback. Luồng codebase cũ: legacy-scan quét tĩnh, mỗi phát hiện map sang guide thay thế, rồi đi qua bốn bước scan, verify, report và modernize. CLI chỉ trả về guide khớp ý định, thay vì nhồi toàn bộ kho guide vào context window.

flowchart TD
    A["Prompt người dùng"] --> B["Coding agent<br/>Claude Code / Codex / Cursor / Gemini"]
    B --> C{"Có guidance?"}
    C -->|Không| D["Pattern cũ từ training data"]
    D --> E["Code JS thừa<br/>kém a11y / hiệu năng"]
    C -->|Có| F["search → guide + dữ liệu Baseline<br/>chạy offline, BM25 + embedding nhẹ"]
    F --> G["Code dùng native API<br/>dialog / Popover / Anchor Positioning"]
    G --> H["Đầu ra + fallback"]
    I["Codebase cũ"] --> J["legacy-scan<br/>quét tĩnh, rule xác định"]
    J --> K["Báo cáo map sang guide"]
    K --> L["Modernize"]
    L --> I
    J -.->|"chỉ cover ~20% guide có rule xác định"| K

Phụ thuộc và giới hạn

Yêu cầu duy nhất đáng chú ý là Node >= 22.0.0, ghi trong trường engines của package.json. Máy dùng Node cũ hơn sẽ lỗi ngay từ bước cài đặt.

Cấu hình nằm ở file .mwgrc. Guide cho tính năng volatile — chỉ chạy trên một engine, mới ra trong ba tháng gần nhất, hoặc chưa ổn định — vẫn tìm được bằng search, nhưng retrieve chặn lại trừ khi bạn bật opt-in bằng set-allow-volatile-features. Đây là van an toàn: ngăn agent đề xuất API chưa ổn định vào code production.

Hai giới hạn cần nhớ: legacy-scan mới cover khoảng 20% số guide có rule xác định, nên scan không thấy không có nghĩa là code đã hiện đại; và guide có thể lỗi thời khi Baseline thay đổi, skill không tự cập nhật.

Cài đặt cho Claude Code và các agent khác

Phần này mình đối chiếu với README và release notes chính thức ngày 11/11/2026. Mình chưa chạy cài đặt thực tế, nên các lệnh dưới đây là lệnh đã verify từ tài liệu. Bạn nên thử trên một repo không quan trọng trước.

Điều kiện tiên quyết

node -v
npx --version

Node phải từ 22.0.0 trở lên, coding agent đã được cài, và bạn có quyền ghi vào thư mục cấu hình của agent đó. Máy dùng Node cũ là lỗi thường gặp nhất; nâng cấp Node hoặc dùng Node 22+ qua version manager — không bypass kiểm tra engines.

Cài đặt bằng một lệnh

npx modern-web-guidance@latest install

Wizard tương tác sẽ hỏi bạn dùng agent nào và cài plugin tương ứng. Các route đã verify trong README:

Repo chứa sẵn các thư mục plugin: .claude-plugin, .codex-plugin, .cursor-plugin, .grok-plugin, cùng file gemini-extension.json và kimi.plugin.json. Sau khi cài, khởi động lại agent hoặc IDE. Telemetry có thể opt-out bằng DISABLE_TELEMETRY=1.

Thử không cần cài: search, retrieve, legacy-scan

npx modern-web-guidance@latest search "animate a dialog modal backdrop"
npx modern-web-guidance@latest retrieve "animate-to-from-top-layer"
npx modern-web-guidance@latest legacy-scan .

search trả về danh sách ngắn các guide khớp với ý định, kèm ID. retrieve lấy toàn văn guide cho use-case animation với top layer — ID này là ví dụ thật trong README. legacy-scan quét tĩnh thư mục hiện tại, liệt kê các pattern cũ, mỗi phát hiện map sang guide thay thế. Nhớ rõ: scan báo không phát hiện không có nghĩa là codebase hiện đại.

Lỗi thường gặp

• Node nhỏ hơn 22: nâng cấp Node hoặc dùng Node 22+ qua version manager.
• Plugin không load: kiểm tra đã chạy marketplace add trước install chưa, rồi khởi động lại agent hoặc IDE.
• retrieve bị chặn với guide volatile: hành vi mặc định, không phải lỗi. Chỉ bật opt-in trong .mwgrc khi chấp nhận rủi ro API single-engine.
• Legacy-scan báo 0 phát hiện trên codebase rõ ràng cũ: đúng kỳ vọng, vì chỉ 20% guide có rule. Chuyển sang review bằng search và retrieve khi viết hoặc sửa code mới.
• Skill lỗi thời: chạy lại lệnh install hoặc cập nhật plugin theo release mới.

Đánh giá: ưu điểm, hạn chế, bảo mật

Ưu điểm. Tri thức đa vendor kèm dữ liệu Baseline: guide là đồng thuận của Chrome, Edge, Firefox và MDN. Truy xuất đúng lúc, offline, nhẹ: gói 8,8 MB, không nhồi toàn bộ kho tri thức vào context window nên tiết kiệm token và giảm nhiễu. Legacy-scan xác định, chạy được trong CI vì dùng rule tĩnh, không dùng LLM phán xét. Cài bằng một lệnh, hỗ trợ nhiều agent phổ biến.

Hạn chế cần nói thẳng. Số liệu eval là của chính dự án, và các snapshot mâu thuẫn nhau. Theo thông báo v1.0, dự án chạy khoảng 200 task với khoảng 1.700 assertion bằng Playwright và AST, kết quả unguided 55% và guided 92%. Nhưng Search Engine Journal ghi nhận 88% so với 56% cho bản preview, không phải v1.0. Bài này chỉ trình bày một con số có ghi nguồn — 55% lên 92% theo thông báo v1.0. Đừng đọc 92% như một benchmark độc lập; dashboard eval công khai cho phép bạn tự kiểm tra theo ngày.

Legacy-scan mới cover khoảng 20% guide — giới hạn cấu trúc, không phải bug. 80% còn lại vẫn phải dựa vào agent tự tra guide khi viết code mới và review tay.

Thông tin pilot là thứ cấp, chưa verify độc lập: theo Search Engine Journal, note inc. tại Nhật đã thử nghiệm với hai coding agent, sáu UI task và 180 lần chạy; MetaMask dùng guidance trong review PR tự động. Đọc chúng như tín hiệu thực tế, không phải bằng chứng chắc chắn.

Agent vẫn có thể áp guide sai ngữ cảnh: native API không có fallback, phá vỡ design system, hoặc chọn pattern không phù hợp với trình duyệt mục tiêu. Skill không thay thế review PR. Bài này cũng không đo tốc độ scan hay lượng token tiết kiệm được.

Bảo mật và vận hành. Skill chỉ đọc guide và quét tĩnh codebase cục bộ; không chạy code production, không có daemon. Rủi ro chính nằm ở đầu ra: agent áp sai guide gây lỗi chức năng hoặc accessibility. Giảm rủi ro bằng review PR và kiểm tra fallback cùng dữ liệu Baseline trước khi merge.

So sánh với các lựa chọn cùng phạm vi

Bảng dưới đây chỉ so sánh những lựa chọn cùng giải quyết bài toán “agent viết code web cũ”.

Modern Web Guidance thắng ở tri thức biên soạn theo use-case và truy xuất đúng lúc; thua lint ở độ bao phủ quét tĩnh. Theo mình, cách dùng hợp lý là kết hợp cả hai.

Use case thực tế

Doanh nghiệp — review PR do agent sinh ra. Guidance làm checklist review: agent viết code mới phải qua guide, reviewer đối chiếu Baseline và fallback trước khi merge.

Frontend developer — workflow hằng ngày. Prompt cho agent, agent tự search guide, code dùng native API, developer kiểm tra fallback. Bốn pattern thường gặp: modal sang <dialog>; accordion sang <details>; tooltip sang Anchor Positioning; animation cho modal sang guide animate-to-from-top-layer.

DevOps — đưa legacy-scan vào CI. Đưa legacy-scan vào CI như một cổng kiểm tra cho các pattern đã biết, cấu hình fail hoặc warn theo policy của team, kết hợp review tay cho 80% guide chưa có rule.

Sao lưu và rollback

Không có runtime hay daemon, không chạm vào dữ liệu production, nên rollback rẻ. Trước khi cài, sao lưu file cấu hình của agent và file .mwgrc nếu đã tạo. Nếu không phù hợp, gỡ plugin, xóa file .mwgrc, rồi chạy lại legacy-scan trên một repo mẫu để xác nhận. Code đã modernize thì chỉ revert qua git sau khi review.

Kết luận

Nên dùng: frontend developer dùng coding agent hằng ngày; team review nhiều code do agent sinh ra; codebase web cũ cần hiện đại hóa từng phần. Chưa nên dùng: dự án chỉ làm backend hoặc không chạm tới web platform; dự án bắt buộc hỗ trợ trình duyệt rất cũ mà không chấp nhận fallback phức tạp; team cần quét tĩnh bao phủ toàn bộ codebase — legacy-scan mới cover 20%.

Bốn bước tiếp theo trong 30 phút: chạy npx modern-web-guidance@latest install (Node từ 22 trở lên); chạy legacy-scan trên một repo thật; thử search và retrieve cho một task frontend sắp làm; quyết định có đưa scan vào CI không.

Bài học rút ra

1. Agent viết code cũ vì training data chứa nhiều legacy code — sửa bằng tri thức đúng lúc, không phải bằng prompt dài hơn.
2. Truy xuất đúng lúc thắng nhồi context: một guide đúng quan trọng hơn cả kho 203 guide.
3. Legacy-scan báo sạch không có nghĩa là codebase hiện đại — 20% coverage là giới hạn cấu trúc.
4. Đừng tin một con số eval duy nhất: 55% lên 92% là số liệu của chính dự án, các snapshot khác nhau cho ra số khác nhau.
5. Native API chỉ tốt khi kèm fallback và dữ liệu Baseline.
6. Rollback rẻ vì không có runtime: gỡ plugin và xóa config là xong.

Phạm vi kiểm chứng

Ngày kiểm tra: 11/11/2026. Đã verify: repo, số sao, giấy phép, ngày và nội dung release v1.0.0, lệnh cài đặt, search, retrieve và legacy-scan, route plugin, Node từ 22 trở lên, 203 guide bao phủ 250 tính năng, legacy-scan cover khoảng 20% guide, gói npm 23,5 MB xuống 8,8 MB, stewardship của Chrome, Edge, Firefox và MDN. Chưa test: mình chưa cài đặt hay chạy thực tế các lệnh trong quá trình chuẩn bị bài này, chưa đo tốc độ scan hay tiết kiệm token. Số liệu eval và pilot là của chính dự án hoặc qua báo cáo thứ cấp. Volatile mặc định bị chặn ở retrieve, chỉ mở khi opt-in qua .mwgrc; rule của legacy-scan là xác định, không phải phán xét của LLM.

Tài liệu tham khảo

• GitHub
• Release v1.0.0
• Chrome Docs
• Chrome Blog
• Eval Dashboard
• Search Engine Journal