Cara Modern Web Guidance memodernisasi codebase Anda—dan alasan Anda harus melakukannya

Sebagian besar pengembangan web tidak dilakukan dari awal. Hal ini terjadi di codebase yang ada yang telah mengumpulkan solusi lama, polyfill, dan utilitas JavaScript (ukuran otomatis, peretasan gaya kotak centang kustom, pemroses scrollHeight) selama bertahun-tahun untuk hal-hal yang kini ditangani browser secara native. Namun, masalahnya adalah: Kode lama tidak rusak. Fitur ini berfungsi, jadi tidak ada yang melaporkan bug. Kepercayaan juga diperlukan untuk merefaktorisasi kode yang berfungsi—meskipun sudah lama—sehingga developer enggan melakukannya.

Di sisi lain, tidak melakukan refaktorisasi kode lama untuk menggunakan fitur web modern akan secara diam-diam merugikan Anda dalam ukuran paket, responsivitas halaman, dan aksesibilitas. Lebih buruk lagi, saat Anda menggunakan agen coding dalam project ini, agen tersebut akan menyalin konvensi tahun 2015 di sekitarnya beserta pola usang dari data pelatihannya.

Saat Anda membangun sesuatu yang baru, Modern Web Guidance akan mengarahkan agen Anda ke fitur Baseline modern. Untuk kode yang sudah ada, Modern Web Guidance 1.0 menambahkan alur kerja modernisasi yang memindai project Anda untuk mencari pola lama dan membantu agen Anda mengupgradenya.

Fungsi alur kerja modernisasi

Saat Anda meminta agen untuk memodernisasi project (atau dengan menjalankan perintah legacy-scan secara langsung), berikut cara kerjanya:

• Pemindaian lokal deterministik: HTML, CSS, JavaScript/TypeScript, komponen khusus framework, dan file package.json dipindai dengan cepat menggunakan parser Abstract Syntax Tree (AST), DOM, dan CSS secara lokal tanpa panggilan LLM atau biaya token.
• Katalog aturan lama: Pemindai yang menandai terlalu banyak hal pada setiap operasi akan diabaikan. Kami menguji aturan kandidat di sekitar 45.000 repositori open source yang dibagi menjadi dua: Aturan ditulis dan disesuaikan pada setengah bagian penulisan aturan, dan dinilai pada setengah bagian yang tidak terlihat. Kami membuang lebih banyak aturan kandidat daripada yang kami pertahankan, melewati fitur yang tidak memiliki kode lama yang setara dan menghentikan pertukaran khusus sintaksis tanpa hasil nyata (seperti menulis ulang pemilih seinduk + atau ~ yang berfungsi menjadi :has()). Untuk dikirim secara default, aturan harus mencapai setidaknya 80% presisi pencocokan statis dan 90% presisi pasca-verifikasi pada kode yang tidak terlihat.
• Pemfilteran positif palsu (PP) berbasis konteks: Setiap kecocokan aturan disertai dengan rubrik keepWhen/dropWhen yang eksplisit. Hal ini memberi tahu agen untuk mengevaluasi kode di sekitarnya, dan menghapus fallback yang disengaja, guard @supports CSS, atau yang mirip sebelum menyajikan temuannya.
• Dicakupkan ke pola lama dengan keyakinan tinggi (dan terus bertambah): legacy-scan memeriksa subset dari sekitar 200 panduan kami (sekitar 20%) yang kode lamanya dapat ditemukan secara deterministik tanpa positif palsu, dan kami memperluas cakupan tersebut seiring waktu. Untuk katalog lainnya, agen Anda akan menelusuri dan mengambil panduan saat Anda membangun.

Cara memanggil alur kerja modernisasi

Modernisasi kode dengan Modern Web Guidance memerlukan versi 1.0 atau yang lebih tinggi. Instal atau update dengan npm, atau marketplace plugin agen Anda:

# Install Modern Web Guidance 1.0 in your project
npx modern-web-guidance@latest install

# Or update an existing installation
npx modern-web-guidance@latest update

Karena alur kerja modernisasi adalah bagian dari definisi keterampilan inti, Anda dapat memicu pemindai dengan bahasa alami dengan meminta agen memeriksa "pola lama" atau "memodernisasi" di seluruh repositori atau folder.

Catatan: Menamai satu komponen akan melakukan pencarian panduan reguler.

Sebagai contoh, berikut adalah contoh perintah untuk memindai seluruh repositori:

Modernize this repository using Modern Web Guidance. Scan our frontend files for legacy patterns, verify the findings, and propose a modernization plan before making any code edits.

Anda juga dapat mengarahkannya ke folder tertentu:

Check src/components/forms for legacy web patterns that can be refactored to modern Baseline features.

Meskipun saat ini Anda dapat menjalankan legacy-scan secara manual di terminal, integrasi pipeline CI/CD otomatis saat ini sedang dalam pengembangan.

Contoh pola yang ditemukan dan diperbaiki

Aturan yang memenuhi syarat menargetkan antipola lama yang umum di empat domain: Formulir dan UI, dialog dan kontrol, tata letak CSS, tipografi, dan desain visual, serta Keamanan. Berikut adalah tabel contoh pola lama, dan pengganti modernnya:

Contoh transformasi kode

Saat diminta, agen coding Anda dapat mengubah antipola lama menjadi modern dengan alur kerja modernisasi. Berikut adalah beberapa contohnya:

Elemen <textarea> yang bertambah otomatis

JavaScript lama yang mengukur scrollHeight pada setiap peristiwa input akan memaksa thrashing tata letak. Hal ini dapat menyebabkan masalah performa—khususnya dengan Interaction to Next Paint (INP). Dengan menggunakan alur kerja modernisasi, agen Anda dapat memperbaikinya:

// Before: Imperative layout recalculation on every keystroke
textarea.addEventListener('input', () => {
  textarea.style.height = 'auto';
  textarea.style.height = `${textarea.scrollHeight}px`;
});

Anda tidak memerlukan JavaScript untuk hal ini sekarang. Alur kerja modernisasi memandu agen Anda untuk menggantinya dengan CSS:

/* After: Native declarative field sizing */
textarea {
  field-sizing: content;
  min-block-size: 3lh;
  max-block-size: 15lh;
}

Popover deklaratif

Logika modal dan pop-up kustom yang menggunakan pemroses peristiwa JavaScript dapat diganti dengan atribut HTML standar:

<!-- Before: a click listener that only calls showPopover() -->
<button id="openBtn">Open Menu</button>
<div id="menu" popover>Menu Content</div>
<script>
  openBtn.addEventListener('click', () => menu.showPopover());
</script>

<!-- After: declarative control, no JavaScript -->
<button popovertarget="menu">Open Menu</button>
<div id="menu" popover>Menu Content</div>

Pengiriman enter yang aman untuk IME

Pemroses tombol enter yang tidak dilindungi akan memicu pengiriman pesan sebelum waktunya saat pengguna mengetik di Editor Metode Input (IME) bahasa Jepang, China, atau Korea.

Agen Anda menambahkan guard status komposisi:

// Before: Fires mid-composition when confirming kanji/hanzi characters
textarea.addEventListener('keydown', (e) => {
  if (e.key === 'Enter' && !e.shiftKey) {
    e.preventDefault();
    sendMessage();
  }
});


// After: Accurately checks IME composition state
textarea.addEventListener('keydown', (e) => {
  if (e.key === 'Enter' && !e.shiftKey) {
    e.preventDefault();
    if (e.isComposing || e.keyCode === 229) return;
    sendMessage();
  }
});

Cara kerjanya: Alur kerja modernisasi empat langkah

Melakukan refaktorisasi kode yang berfungsi di aplikasi yang ada memerlukan kepercayaan, karena tidak ada yang menginginkan churn otomatis atau regresi yang tidak kentara. Itulah sebabnya tidak ada flag --fix: Bahkan modernisasi yang tampaknya mudah sering kali ternyata merupakan pemfaktoran ulang lintas lapisan—seperti menghapus pemroses JS imperatif atau paket npm dan memindahkan perilaku ke HTML dan CSS—dengan perilaku yang tidak kentara dan tantangan dukungan browser.

Sebagai gantinya, alur kerja modernisasi menjalankan loop empat langkah dengan agen coding Anda:

1. Pemindaian (legacy-scan): Agen menjalankan npx modern-web-guidance legacy-scan <path> --json, yang melakukan pra-penyaringan file untuk substring yang relevan, sehingga hanya menjalankan parser AST, CSS, dan HTML pada file dan aturan kandidat. Jika temuan mencapai tahap ini, kemungkinan besar (sekitar 92%) temuan tersebut bukan positif palsu. Setiap kecocokan menyertakan checklist verifikasi untuk agen.
2. Verifikasi kontekstual (keepWhen/dropWhen): Karena agen coding membuka repositori, agen tersebut akan memeriksa kode di sekitar setiap kecocokan dengan rubrik verifikasi aturan tersebut. Jika pembacaan scrollHeight adalah bagian dari scrolling virtual, bukan peretasan <textarea>, atau jika pemeriksaan @supports sudah melindungi properti, temuan akan otomatis dihapus.
3. Laporan: Agen meringkas temuan yang diverifikasi (dengan catatan bahwa legacy-scan mencakup subset panduan dengan aturan deterministik, ditambah rencana modernisasi jika Anda meminta untuk meninjau rencana sebelum melakukan pengeditan).
4. Pengambilan panduan, refaktorisasi, dan verifikasi pengujian: Saat diminta untuk melakukan modernisasi, agen akan menjalankan npx modern-web-guidance retrieve <guide-id> untuk mengambil panduan yang sesuai. Agen akan menjalankan refaktorisasi kode sesuai dengan pola kompatibilitas Baseline panduan, dan menjalankan ulang legacy-scan <path> pada file yang dimodifikasi bersama dengan suite pengujian project untuk mengonfirmasi penyelesaian.

Cobalah

Baik menjalankan legacy-scan satu kali di terminal, atau meminta agen coding Anda untuk memodernisasi modul lama, alur kerja modernisasi membantu Anda melunasi utang platform web lama tanpa gangguan linter tradisional.

Gabungkan Modern Web Guidance dengan Chrome DevTools untuk agen jika Anda ingin beralih dari modernisasi kode statis ke verifikasi, tolok ukur, dan proses debug browser langsung.

Langkah selanjutnya dan sumber daya

• Dokumentasi
• Katalog Panduan
• Dasbor Evaluasi Publik
• Repositori GitHub
• Chrome DevTools untuk agen