Modern Web Guidance — AI 코딩 에이전트에게 최신 웹 플랫폼을 가르치는 방법

LLM의 학습 데이터는 과거 코드로 가득하다. View Transitions, Popover API, Container Queries 같은
최신 브라우저 API를 에이전트가 올바르게 사용하도록 만드는 Google Chrome 팀의 접근법을 정리한다.

목차

• 1. 문제: AI가 레거시 코드를 생성하는 이유
• 2. Modern Web Guidance 개요
• 3. 동작 원리
• 4. 설치 및 사용법
• 5. 102개 웹 기능 커버리지
• 6. 효과 측정: 에이전트 성능 +33pp 향상
• 7. Google I/O 2026에서의 위치
• 8. 기존 접근법과의 비교
• 9. 트레이드오프 및 한계
• 10. 결론

1. 문제: AI가 레거시 코드를 생성하는 이유

Claude Code에게 "모달 다이얼로그를 만들어달라"고 요청하면 높은 확률로 z-index: 9999와 수동 포커스 트랩 JavaScript를 생성한다. GPT-4o에게 "이미지 로딩 최적화"를 요청하면 IntersectionObserver 폴리필과 lazy loading 라이브러리를 추천한다.

문제의 근원: LLM 학습 데이터의 대부분이 2020~2023년 코드이며, 그 시점에는 <dialog>, loading="lazy", View Transitions API, Popover API가 표준화되지 않았거나 브라우저 지원이 부족했다. 모델은 API의 존재를 "알고" 있더라도, 프로덕션 수준의 올바른 사용 패턴을 학습할 데이터가 부족하다.

결과: 네이티브 브라우저 API로 10줄에 끝나는 작업에 200줄짜리 JavaScript와 3개의 npm 패키지가 붙는다.

2. Modern Web Guidance 개요

Modern Web Guidance는 Google Chrome 팀과 Microsoft Edge 팀이 공동으로 관리하는 오픈소스 프로젝트로, AI 코딩 에이전트의 컨텍스트 윈도우에 최신 웹 플랫폼 지식을 직접 주입하는 "스킬(Skill)" 세트이다.

• 102개 웹 기능 — CSS, HTML, JavaScript, Performance, Accessibility, Built-in AI 6개 분야
• 128개 실전 사용 사례 — "parallax scroll", "navigation drawer", "passkey registration" 등
• 로컬 시맨틱 검색 — TensorFlow.js 기반 오프라인 검색, 네트워크 호출/API 키 불필요
• 토큰 효율 설계 — 모델이 이미 아는 기초 내용은 제거, 핵심 패턴만 포함
• Baseline 호환성 데이터 통합 — 실시간 브라우저 지원 상태 반영

지원 에이전트: Claude Code, GitHub Copilot, Google Antigravity, Codex CLI, Vercel Skills, JetBrains AI 등 주요 코딩 에이전트에서 설치 가능하다. (공식 설치 가이드)

3. 동작 원리

Modern Web Guidance는 3단계로 동작한다:

Modern Web Guidance 동작 흐름

👨‍💻 개발자
"모달 다이얼로그 만들어줘"

▼ 프롬프트

AI 코딩 에이전트
Claude Code / Copilot / Codex

▼ 1. 스킬 활성화 (웹 관련 작업 감지)

modern-web-guidance CLI
npx modern-web-guidance search "dialog modal"

▼ 2. 로컬 시맨틱 검색 (TF.js, 오프라인)

가이드 매칭
animate-to-from-top-layer.md

▼ 3. 가이드를 컨텍스트 윈도우에 주입

에이전트가 최신 패턴으로 코드 생성
<dialog> + @starting-style + Popover API

핵심 설계 원칙

• 오프라인 우선 — 네트워크 호출 없음. npm 패키지에 모든 가이드와 임베딩 모델이 포함됨
• 토큰 절약 — 모델이 이미 알고 있는 기초 내용은 eval을 통해 제거. 에이전트가 실수하는 부분만 남김
• 공급망 보안 — 외부 의존성 없는 자체 완결형 패키지
• 점진적 강화 — fallback 가이드 포함. "이 API를 지원하지 않는 브라우저에서는 이렇게 하라"

4. 설치 및 사용법

4.1 인터랙티브 설치 (권장)

# 대화형 위자드로 설치 (에이전트 자동 감지)
npx modern-web-guidance@latest install

4.2 에이전트별 설치

# Claude Code
/plugin marketplace add GoogleChrome/modern-web-guidance
/plugin install modern-web-guidance@googlechrome

# GitHub Copilot
/plugin marketplace add GoogleChrome/modern-web-guidance

# Google Antigravity
agy plugin install https://github.com/GoogleChrome/modern-web-guidance

# Vercel Skills CLI
npx skills add GoogleChrome/modern-web-guidance

4.3 CLI 직접 사용 (설치 없이 테스트)

# 시맨틱 검색: 관련 가이드 찾기
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 update

텔레메트리: 기본적으로 검색 쿼리와 가이드 조회 통계를 Google에 전송한다. 비활성화하려면 export DISABLE_TELEMETRY=1 을 셸 프로파일에 추가한다. 수집 항목은 소스 코드에서 확인 가능하다.

5. 102개 웹 기능 커버리지

Modern Web Guidance가 다루는 영역은 6개 분야, 102개 기능이다.

분야기능 수주요 항목

🎨 User Experience	51	View Transitions, Scroll-driven Animations, Parallax, Navigation Drawer
📐 CSS & Layout	(포함)	Container Queries, Subgrid, oklch, text-wrap, Anchor Positioning
⚡ Performance	20+	Speculation Rules, scheduler.yield(), INP 진단, fetchLater()
📝 Forms & UI	19	Customizable <select>, Popover API, :user-invalid, field-sizing
♿ Accessibility	1+	aria-invalid 동기화, 스크린 리더 호환 에러 안내
🤖 Built-in AI	5	Language Detection, Summarizer, Translator, LanguageModel (Prompt API)

사용 사례 예시: Navigation Drawer

"네비게이션 드로어를 만들어달라"고 에이전트에게 요청하면, MWG가 navigation-drawer 가이드를 컨텍스트에 주입한다. 이 가이드에는:

• <dialog> + Popover API로 구현 (z-index 전쟁 없음)
• @starting-style로 진입 애니메이션 (JavaScript 없음)
• 스와이프 제스처 + Escape 키 + 외부 클릭으로 닫기 (light dismiss)
• 접근성: 포커스 트랩, aria-label, 키보드 네비게이션 자동 지원

에이전트 없이 같은 결과를 얻으려면 MDN 3~4페이지를 읽고 호환성 표를 교차 확인해야 하는 작업이다.

6. 효과 측정: 에이전트 성능 +33pp 향상

Google Chrome 팀은 자체 eval 파이프라인을 운영하여 MWG의 효과를 정량적으로 검증한다. 75개 실전 과제에 대해 "MWG 있음/없음"으로 에이전트를 실행하고, Playwright 기반 자동 테스트로 정확도를 측정한다.

날짜에이전트 + 모델가이드 없음가이드 있음향상

2026-05-18	Claude Code (Opus 4.7)	52%	85%	+33pp
2026-05-16	Codex CLI (GPT-5.5)	49%	82%	+33pp
2026-05-15	Antigravity	47%	91%	+44pp
2026-04-30	Claude Code (Opus 4.6)	44%	81%	+37pp

Eval 방법론: 과제는 "이미지 로딩 속도를 개선해줘"처럼 API명을 언급하지 않는 자연어 요청이다. 에이전트가 MWG 없이 스스로 최신 API를 찾아쓸 수 있는지 측정한다. Playwright 스크립트가 런타임 동작, 계산된 스타일, 접근성 상태를 검증한다. (상세 방법론)

7. Google I/O 2026에서의 위치

2026년 5월 Google I/O에서 Chrome 팀은 "Agentic Web"을 핵심 테마로 발표했다. Modern Web Guidance는 이 전략의 두 축 중 하나이다:

• WebMCP — 웹 페이지가 AI 에이전트에게 구조화된 도구(Tool)를 노출하는 표준. Chrome 149 Origin Trial. 에이전트가 웹사이트와 "상호작용"하는 방법을 정의한다.
• Modern Web Guidance — AI 에이전트가 웹사이트를 "만드는" 방법을 정의한다. 코드 생성 시 최신 웹 플랫폼 패턴을 따르도록 유도한다.

두 프로젝트는 상호 보완적이다. WebMCP는 에이전트의 "행동"을, MWG는 에이전트의 "코딩 품질"을 다룬다. (Chrome at I/O 2026 공식 발표)

8. 기존 접근법과의 비교

코딩 에이전트에게 최신 웹 지식을 제공하는 방법은 MWG 외에도 존재한다. 각 접근법의 장단점을 정리한다.

접근법방식장점단점

Modern Web Guidance	에이전트 컨텍스트에 가이드 주입	오프라인, 토큰 효율, 검증된 효과(+33pp)	npm 설치 필요, 102개 기능만 커버
MDN 웹 검색	에이전트가 MDN을 실시간 검색	최신 정보, 광범위한 커버리지	네트워크 필요, 토큰 낭비, 정확도 불안정
프롬프트 지시	"최신 API를 사용해"라고 프롬프트에 명시	추가 도구 불필요	모델이 올바른 패턴을 모르면 무의미
Fine-tuning	최신 코드로 모델을 재학습	근본적 해결	비용 극대, 주기적 재학습 필요
.cursorrules / Steering	커스텀 규칙 파일로 코딩 가이드 주입	프로젝트별 맞춤 가능	수동 관리, 호환성 데이터 부재

MWG의 차별점은 "전문가가 작성 + eval로 검증 + 호환성 데이터 통합"이라는 점이다. 수동으로 .cursorrules를 관리하는 것 대비, Google/Microsoft 팀이 지속적으로 업데이트하고 정량적 효과를 측정한다는 신뢰도가 있다.

9. 트레이드오프 및 한계

9.1 커버리지 한계

현재 102개 기능만 다룬다. React Server Components, Next.js App Router 같은 프레임워크 레벨 패턴은 포함되지 않는다. MWG는 "웹 플랫폼 네이티브 기능"에 집중하며, 프레임워크는 범위 밖이다.

9.2 프리뷰 상태

README에 "preview release"로 명시되어 있다. 가이드가 추가/수정되는 속도가 빠르며, 구조가 변경될 수 있다. 프로덕션 워크플로우에 고정 버전으로 핀하는 것이 안전하다.

9.3 에이전트 의존성

MWG는 코딩 에이전트의 "스킬" 시스템을 전제한다. 에이전트가 웹 관련 작업을 감지하여 스킬을 활성화하지 못하면 효과가 없다. 에이전트의 스킬 라우팅 정확도에 의존한다.

9.4 텔레메트리

기본적으로 검색 쿼리를 Google에 전송한다. 보안이 민감한 환경에서는 DISABLE_TELEMETRY=1 설정이 필수이다. 수집 내용은 소스 코드에서 확인 가능하지만, 비활성화를 잊으면 내부 프로젝트 관련 쿼리가 외부로 전송될 수 있다.

주의: MWG는 코드 생성 "패턴"을 개선하는 도구이지, 에이전트의 추론 능력 자체를 향상시키지는 않는다. 복잡한 비즈니스 로직이나 아키텍처 결정은 여전히 개발자의 판단이 필요하다.

10. 결론

Modern Web Guidance는 "AI 에이전트의 웹 플랫폼 지식 격차"라는 명확한 문제를 해결하는 도구이다. eval 결과를 기준으로, MWG를 적용하면 에이전트의 웹 코딩 정확도가 평균 33~44 퍼센트포인트 향상된다.

도입을 권장하는 경우:

• 팀에서 Claude Code, Copilot, Codex 등 AI 에이전트로 프론트엔드 코드를 생성하는 경우
• 에이전트가 jQuery, polyfill, 불필요한 npm 패키지를 자꾸 추가하는 경우
• View Transitions, Container Queries, Popover API 등 최신 API를 적극 활용하고 싶은 경우

적합하지 않은 경우:

• React/Next.js/Vue 프레임워크 레벨의 패턴 가이드가 필요한 경우
• IE11 또는 매우 오래된 브라우저를 지원해야 하는 경우
• 에이전트를 사용하지 않고 수동으로 코딩하는 환경

설치는 npx modern-web-guidance@latest install 한 줄이다. 에이전트가 다음에 웹 관련 코드를 생성할 때 차이를 확인할 수 있다.

참고 자료

• • Modern Web Guidance GitHub Repository
• • Chrome for Developers — Modern Web Guidance 공식 문서
• • Get Started with Modern Web Guidance
• • Chrome at I/O 2026 — Agentic Web 발표
• • WebMCP — AI 에이전트를 위한 웹 표준
• • Google Cloud Blog — Skills Repository 발표
• • 예시 가이드: Navigation Drawer
• • The New Stack — Google Wants to Make the Web Agent-Ready
• • 기여 가이드 (소스 리포지토리)

이 글은 Modern Web Guidance GitHub README, Chrome for Developers 공식 문서,
Google I/O 2026 발표 자료를 기반으로 작성되었다.