대부분의 웹 개발은 처음부터 시작되지 않습니다. 이는 수년간의 레거시 해결 방법, 폴리필, JavaScript 유틸리티(자동 크기 조정, 맞춤 체크박스 스타일 지정 해킹, scrollHeight 리스너)가 누적된 기존 코드베이스에서 발생하며, 이제 브라우저가 기본적으로 처리합니다. 하지만 문제는 기존 코드가 손상되지 않는다는 것입니다. 작동하므로 아무도 버그를 신고하지 않습니다. 또한 오래된 코드라도 작동하는 코드를 리팩터링하려면 신뢰가 필요하므로 개발자가 꺼리는 것은 당연합니다.
반면, 최신 웹 기능을 사용하도록 이전 코드를 리팩터링하지 않으면 번들 크기, 페이지 응답성, 접근성 측면에서 비용이 발생합니다. 더 나쁜 것은 이러한 프로젝트에서 코딩 에이전트를 사용하면 학습 데이터의 오래된 패턴과 함께 주변의 2015년 규칙을 복사한다는 것입니다.
새로운 것을 빌드할 때 Modern Web Guidance는 에이전트를 최신 Baseline 기능으로 안내합니다. 기존 코드의 경우 Modern Web Guidance 1.0은 프로젝트에서 기존 패턴을 스캔하고 에이전트가 이를 업그레이드하는 데 도움이 되는 현대화 워크플로를 추가합니다.
현대화 워크플로의 역할
에이전트에게 프로젝트를 현대화하도록 요청하거나 legacy-scan 명령어를 직접 실행하면 다음과 같이 작동합니다.
- 결정론적 로컬 스캔: HTML, CSS, JavaScript/TypeScript, 프레임워크별 구성요소,
package.json파일은 LLM 호출이나 토큰 비용 없이 로컬에서 추상 구문 트리(AST), DOM, CSS 파서로 빠르게 스캔됩니다. - 기존 규칙 카탈로그: 실행할 때마다 너무 많은 항목에 플래그를 지정하는 스캐너는 무시됩니다. Google은 약 45,000개의 오픈소스 저장소를 절반으로 나누어 후보 규칙을 테스트했습니다. 규칙은 규칙 작성 절반에서 작성 및 조정되었으며, 보이지 않는 보류된 절반에서 등급이 매겨졌습니다. Google은 유지한 규칙보다 더 많은 후보 규칙을 버렸으며, 기존 코드에 상응하는 기능이 없는 기능은 건너뛰고 실질적인 이점이 없는 문법 전용 교체(예: 작동하는
+또는~동위 선택자를:has()로 다시 작성)는 중단했습니다. 기본적으로 제공하려면 규칙이 보이지 않는 코드에서 정적 매처 정밀도가 80% 이상, 사후 검증 정밀도가 90% 이상이어야 합니다. - 컨텍스트 인식 거짓양성 필터링: 모든 규칙 일치에는 명시적인
keepWhen/dropWhen루브릭이 함께 제공됩니다. 이렇게 하면 에이전트가 주변 코드를 평가하고 의도적인 대체, CSS@supports가드 또는 유사 항목을 삭제한 후 결과를 표시합니다. - 신뢰도가 높은 기존 패턴으로 범위 지정(확장 중):
legacy-scan는 약 200개의 가이드 중 거짓양성 없이 기존 코드를 결정론적으로 발견할 수 있는 하위 집합(약 20%)을 확인하며, 시간이 지남에 따라 이 범위를 확장하고 있습니다. 카탈로그의 나머지 부분은 에이전트가 빌드하는 동안 가이드를 검색하고 가져옵니다.
현대화 워크플로를 호출하는 방법
Modern Web Guidance를 사용하여 코드를 현대화하려면 버전 1.0 이상이 필요합니다. npm 또는 에이전트의 플러그인 마켓플레이스를 사용하여 설치하거나 업데이트합니다.
# 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
현대화 워크플로는 핵심 기술 정의의 일부이므로 에이전트에게 저장소 또는 폴더에서 '기존 패턴'을 확인하거나 '현대화'하도록 요청하여 자연어로 스캐너를 트리거할 수 있습니다.
참고: 단일 구성요소의 이름을 지정하면 일반 가이드 조회가 실행됩니다.
예를 들어 다음은 전체 저장소를 스캔하는 프롬프트 예시입니다.
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.
특정 폴더를 가리킬 수도 있습니다.
Check src/components/forms for legacy web patterns that can be refactored to modern Baseline features.
현재 터미널에서 legacy-scan를 수동으로 실행할 수 있지만 자동화된 CI/CD 파이프라인 통합은 현재 개발 중입니다.
포착 및 수정하는 패턴 예시
검증된 규칙은 양식 및 UI, 대화상자 및 컨트롤, CSS 레이아웃, 서체, 시각적 디자인, 보안의 네 가지 도메인에서 일반적인 기존 안티패턴을 타겟팅합니다. 다음은 기존 패턴의 예시와 최신 대체 패턴을 보여주는 표입니다.
코드 변환 예시
프롬프트가 표시되면 코딩 에이전트는 현대화 워크플로를 사용하여 기존 안티패턴을 현대적인 안티패턴으로 변환할 수 있습니다. 예를 들면 다음과 같습니다.
자동 확장 <textarea> 요소
모든 input 이벤트에서 scrollHeight를 측정하는 기존 JavaScript는 레이아웃 스래싱을 강제합니다. 이로 인해 성능 문제, 특히 다음 페인트에 대한 상호작용(INP) 문제가 발생할 수 있습니다. 현대화 워크플로를 사용하면 에이전트가 이를 수정할 수 있습니다.
// Before: Imperative layout recalculation on every keystroke
textarea.addEventListener('input', () => {
textarea.style.height = 'auto';
textarea.style.height = `${textarea.scrollHeight}px`;
});
이 작업에는 JavaScript가 필요하지 않습니다. 현대화 워크플로는 상담사가 CSS로 대체하도록 안내합니다.
/* After: Native declarative field sizing */
textarea {
field-sizing: content;
min-block-size: 3lh;
max-block-size: 15lh;
}
선언적 팝오버
JavaScript 이벤트 리스너를 사용하는 맞춤 모달 및 팝업 로직은 표준 HTML 속성으로 대체할 수 있습니다.
<!-- 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>
IME-safe enter submission
보호되지 않은 Enter 키 리스너는 사용자가 일본어, 중국어 또는 한국어 입력 방식 편집기(IME)를 입력할 때 메시지 제출을 조기에 트리거합니다.
에이전트가 컴포지션 상태 가드를 추가합니다.
// 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();
}
});
작동 방식: 4단계 현대화 워크플로
기존 앱에서 작동하는 코드를 리팩터링하려면 신뢰가 필요합니다. 자동화된 이탈이나 미묘한 회귀를 원하는 사람은 아무도 없기 때문입니다. --fix 플래그가 없는 이유도 이 때문입니다. 간단해 보이는 현대화도 명령형 JS 리스너 또는 npm 패키지를 삭제하고 동작을 HTML 및 CSS로 이동하는 등 미묘한 동작과 브라우저 지원 문제가 있는 교차 레이어 리팩터링인 경우가 많습니다.
대신 현대화 워크플로는 코딩 에이전트와 함께 4단계 루프를 실행합니다.
- 스캔(
legacy-scan): 에이전트는npx modern-web-guidance legacy-scan <path> --json를 실행하여 관련 하위 문자열의 파일을 사전 선별하므로 후보 파일 및 규칙에서 AST, CSS, HTML 파서만 실행합니다. 발견 항목이 이 단계까지 도달하면 거짓양성이 아닐 확률이 이미 높습니다(약 92%). 모든 일치 항목에는 상담사를 위한 확인 체크리스트가 포함됩니다. - 컨텍스트 검증(
keepWhen/dropWhen): 코딩 에이전트가 저장소를 열어 두었으므로 해당 규칙의 검증 기준표에 따라 각 일치 항목을 둘러싼 코드를 검사합니다.scrollHeight읽기가<textarea>해킹이 아닌 가상화된 스크롤의 일부이거나@supports검사가 이미 속성을 보호하는 경우 발견 항목이 자동으로 삭제됩니다. - 보고서: 에이전트는 확인된 발견 사항을 요약합니다(
legacy-scan는 결정론적 규칙이 있는 가이드의 하위 집합과 수정하기 전에 계획을 검토하도록 요청한 경우 현대화 계획을 포함함). - 가이드 검색, 리팩터링, 테스트 검증: 현대화를 요청하면 에이전트가
npx modern-web-guidance retrieve <guide-id>를 실행하여 적절한 가이드를 가져옵니다. 가이드의 Baseline 호환성 패턴에 따라 코드 리팩터링을 실행하고 프로젝트의 테스트 모음과 함께 수정된 파일에서legacy-scan <path>를 다시 실행하여 해결을 확인합니다.
사용해 보기
터미널에서 일회성 legacy-scan를 실행하든 코딩 에이전트에게 이전 모듈을 현대화하도록 요청하든, 현대화 워크플로를 사용하면 기존 린터의 번거로움 없이 기존 웹 플랫폼 부채를 상환할 수 있습니다.
정적 코드 현대화에서 실시간 브라우저 확인, 벤치마킹, 디버깅으로 전환하려면 Modern Web Guidance를 에이전트용 Chrome DevTools와 페어링하세요.