GoogleChrome Modern Web Guidance: 코딩 에이전트의 낡은 웹 구현을 modern-api로 대체하는 CLI

코딩 에이전트가 웹 페이지를 생성할 때 종종 발생하는 문제가 있다. LLM 훈련 데이터에 방대한 레거시 코스가 포함되어 있어, 에이전트는 이미 네이티브 브라우저 API로 해결할 수 있는 문제에 무거운 JavaScript 라이브러리나 polyfill을 사용하는 패턴을 생성한다. Google Chrome, Microsoft Edge, Mozilla Firefox, MDN 팀이 함께 관리하는 Modern Web Guidance는 이 격차를 메우기 위해 설계된 CLI다.

3,400개 이상의 star를 얻은 이 프로젝트는 250개 modern web feature와 203개 real-world developer use case를ロー컬 임베딩과 BM25 검색으로 처리한다. 네트워크 호출 없이, npm 패키지가 자체적으로 완결되어 있어 공급망 보안 위험도 없다.

왜 필요한가: 레거시 패턴에서 modern API로

LLM은 방대한 훈련 데이터를 기반으로 코드를 생성하지만, 그 데이터에는 수십 년 된 패턴이 포함되어 있다. 예를 들어 "모달 백드롭을 애니메이션한다"는 요청에 대해, 에이전트는 CSS View Transitions이나 Popover API 대신 전체 애니메이션 라이브러리를 로드하거나, canvas로 직접 그리거나, jQuery-style DOM 조작을 생성할 수 있다.

Modern Web Guidance는 에이전트의 컨텍스트 윈도우에 타겟된 가이드를 주입한다. 6개 핵심 영역을 다룬다.

특히 "Responsible Fallbacks" 개념이 중요하다. 순수하게 추가적인 향상(speculative preloading 등)은 이전 브라우저에서 silently ignored되지만, 다이얼로그 제어나 네트워크 비콘 같은 핵심 동작에는 고려到低은 경량 폴백(<50 LOC)을 작성한다. 무거운 서드파티 번들을 피한다.

작동 방식: 검색 → 조회 → 컨텍스트 주입

사용자는 세 가지 CLI 명령으로 작업한다.

# 관련 가이드 검색
npx modern-web-guidance@latest search "animate a dialog modal backdrop"

# 가이드 ID로 상세 조회
npx modern-web-guidance@latest retrieve "animate-to-from-top-layer"

# 레거시 패턴 스캔
npx modern-web-guidance@latest legacy-scan .

search는 오프라인 임베딩 모델과 BM25 검색 엔진으로 쿼리를 가장 적합한 가이드에 매칭한다. retrieve는 가이드 ID로 코드 패턴, gotcha, fallback을 컨텍스트 윈도우에 주입한다. legacy-scan은 전체 코드베이스에서 modernize할 레거시 패턴을 스캔한다.

npx으로 실행하면 최신 콘텐츠가 항상 제공되지만, 패키지는 오프라인에서 완전히 동작하며 네트워크 호출이나 API 키가 필요 없다.

평가: unguided vs guided, 얼마나 다른가

프로젝트는 자체 eval 하네스를 개발해 내용을 empirically 검증했다고 한다. 실제 웹 앱에 대한 simulated developer tasks를 정의하고, Playwright grader로 구현 요구사항을 확인하는 구조다.

최근 eval 결과 스냅샷:

antigravity_cli(gemini-4-argon)가 +36pp로 가장 큰 상승을 기록했다. Codex(gpt-6.1-sol)와 Claude Code(opus-5-5)도 +28~34pp의 일관된 상승을 보였다. 전체적으로 guided 모드에서 82~96%의 pass rate를 기록한다.

이 수치는 프로젝트가 공개한 것이다. CodeBridge는 동일한 eval 하네스로 재현하지 않았다. "opportunity" (100% − unguided pass rate)와 "uplift" (guided − unguided pass rate)가 핵심 지표다.

설정: .mwgrc로 Origin Trial과 volatile feature 관리

저장소 단위로 Origin Trial과 volatile feature에 대한 opt-in을 .mwgrc JSON 파일로 관리한다.

{
  "allowOriginTrials": true,
  "allowVolatileFeatures": true
}

Origin Trial API는 search로 discoverable하지만 retrieve에는 명시적 opt-in이 필요하다. volatile feature(단일 엔진 기능으로 최근 3개월 내 출시되거나 안정화 중인 기능)도 동일하게 처리된다. 이는 불안정한 API를 에이전트가 무작정 채택하는 것을 방지한다.

개인정보 수집과 옵트아웃

Google은 설치 횟수, 호출 에이전트 이름, 가이드 조회 ID, CLI 검색 쿼리(예: "dark mode scrollbar color-scheme")를 익명으로 수집한다. Raw user prompt는 수집하지 않는다.

옵트아웃은 환경 변수로 설정한다.

export DISABLE_TELEMETRY=1

실무 적용: 어디에 유용한가

Modern Web Guidance가 가장 효과적이거나 코딩 에이전트를 사용하는 프로젝트에서 레거시 패턴이 자주 생성되는 경우에 유용하다. 특히 다음과 같은 상황에서 고려할 만하다.

• 새로운 코드베이스에 에이전트를導入할 때: 초기 가이드 설치를 통해 에이전트가 modern API를 기본값으로 학습하게 할 수 있다.
• 레거시 코드베이스의 점진적 modernization: legacy-scan으로 문제 영역을 파악한 후, 수정 범위에 맞춰 가이드를 적용한다.
• 팀 내 표준화: .mwgrc를 저장소에 커밋해 전원이 동일한 modern web 기준을 사용하게 할 수 있다.

단, 모든 에이전트에서 코드 품질이 향상된다는 독립적 증거는 아직 확인하지 못했다. eval은 프로젝트가 설계한 하네스 내에서 수행되었으며, 실제 프로덕션 코드베이스에 대한 재현 결과는 별도다.

한계: eval 하네스의 범위

첫째, eval은 simulated developer tasks에 기반한다. "my images load faster"와 같이 API나 feature를 명시하지 않은 프롬프트를 테스트하지만, 실제 개발자가 직면하는 더 복잡한 문제(성능 병목, 접근성 감사, 브라우저별 버그)를 완전히 대체하지는 않는다.

둘째, "250개 feature"와 "203개 use case"는 프로젝트가 선별한 범위다. 모든 modern web feature를 cover하지는 않는다. 특히 단일 엔진에만 존재하는 기능은 volatile feature로 분류되어 retrieve 시 opt-in이 필요하다.

셋째, telemetry 수집이 기본으로 활성화되어 있다. 옵트아웃 가능하지만, 조직 정책상 외부 도구에서 어떤 데이터를 수집하는지 검토해야 하는 경우가 있다.

인사이트: 모델을 바꾸지 않고 지식 품질을 개선한다

Modern Web Guidance의 접근법은 흥미롭다. 모델 자체를 교체하거나 파인튜닝하지 않고, 에이전트에 제공하는 기술 지식의 품질을 개선한다. 250개 feature와 203개 use case를ロー컬 임베딩으로 검색해 컨텍스트에 주입한다는 것은, 모델의 훈련 데이터 품질을 실시간으로 보정하는 것과 유사하다.

도입을 검토한다면 질문은 "Modern Web Guidance가 에이전트의 코드 품질을 높이는가"가 아니라 "내 에이전트가 어떤 레거시 패턴을 자주 생성하는가, legacy-scan으로哪些问题이 발견되는가, guided/unguided pass rate의 상승이 내 작업에 의미 있는 개선인가"다. legacy-scan으로 기존 프로젝트를 검사하고, 브라우저 호환성과 함께 확인해 보는 것이 첫 단계다.

웹 에이전트의 구조를 더 알고 싶다면 에이전트 흐름 강의에서 관찰·실행·검증 패턴을 이어서 볼 수 있다.