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.jsondipindai 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/dropWhenyang eksplisit. Hal ini memberi tahu agen untuk mengevaluasi kode di sekitarnya, dan menghapus fallback yang disengaja, guard@supportsCSS, atau yang mirip sebelum menyajikan temuannya. - Dicakupkan ke pola lama dengan keyakinan tinggi (dan terus bertambah):
legacy-scanmemeriksa 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:
- Pemindaian (
legacy-scan): Agen menjalankannpx 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. - Verifikasi kontekstual (
keepWhen/dropWhen): Karena agen coding membuka repositori, agen tersebut akan memeriksa kode di sekitar setiap kecocokan dengan rubrik verifikasi aturan tersebut. Jika pembacaanscrollHeightadalah bagian dari scrolling virtual, bukan peretasan<textarea>, atau jika pemeriksaan@supportssudah melindungi properti, temuan akan otomatis dihapus. - Laporan: Agen meringkas temuan yang diverifikasi (dengan catatan bahwa
legacy-scanmencakup subset panduan dengan aturan deterministik, ditambah rencana modernisasi jika Anda meminta untuk meninjau rencana sebelum melakukan pengeditan). - 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 ulanglegacy-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.