Modern Web Guidance, 최신 API보다 지원 범위를 먼저 정한다
Modern Web Guidance 1.0은 코딩 에이전트에 최신 웹 구현 지침과 호환성 정보를 제공한다. Baseline 목표와 실험 기능 허용, 대체 구현의 검증 책임을 나눠 서비스에 적용할 조건을 살펴본다.
코딩 에이전트가 메뉴 하나를 만들면서 스크롤 이벤트와 위치 계산 코드를 길게 붙였다고 하자. 브라우저가 이미 제공하는 기능으로 줄일 수 있다면 반가운 일이다. 하지만 새 API로 짧아진 코드가 서비스에서 지원하는 Safari 버전에서는 동작하지 않는다면, 줄어든 줄 수만으로 개선을 판단할 수 없다. Modern Web Guidance를 볼 때 내가 먼저 확인한 것은 기능 목록보다 지원 범위를 결정하는 방식이다.
Modern Web Guidance는 웹 플랫폼 지식과 구현 지침을 코딩 에이전트에 전달하는 스킬 모음이다. 1.0 정식 릴리스는 2026년 11월 10일 공개됐고, GeekNews에는 11일 오전 7시 38분, 한국 시각으로 등록됐다. 아래는 v1.0.0과 공식 문서를 읽은 분석이다. 도구를 설치하거나 생성 코드와 성능을 직접 시험한 결과는 아니다.
새 API를 기억하게 하는 대신 필요한 근거를 찾는다
프로젝트는 모델의 학습 자료에 오래된 구현이 많고, 최신 API를 알아도 실제 구현 패턴은 부족하다는 점을 출발점으로 삼는다. 에이전트가 작업에 맞는 가이드를 검색하고, 선택한 문서의 코드 패턴·주의점·대체 구현을 문맥에 넣는 구조다. 검색에는 로컬 임베딩 모델과 BM25를 함께 쓴다. 임베딩은 의미가 비슷한 문서를 찾는 표현이고, BM25는 단어의 출현을 바탕으로 관련도를 계산하는 검색 방식이다. 동작 설명
1.0은 미리보기 단계를 끝내고 코드베이스의 오래된 패턴을 찾는 legacy-scan도 제공한다. 다만 릴리스가 밝힌 정적 탐지 규칙의 범위는 전체 가이드의 약 20%다. 스캔 결과가 없다는 사실을 현대화할 부분이 없다는 뜻으로 읽어서는 안 된다. 새 검색 구현으로 npm 다운로드 크기가 줄었다는 발표도 있지만, 그것은 배포 패키지의 크기이지 생성되는 웹앱의 용량이나 실행 속도 측정이 아니다. 변경 범위
내가 주목한 부분은 정답 코드를 하나 더 저장하는 것보다 판단 근거를 작업 가까이 가져온다는 점이다. 반복해서 직접 만드는 메뉴나 대화상자가 있는 팀에는 검토할 가치가 있다. 반대로 안정된 컴포넌트 라이브러리로 요구를 충족하고 있다면, 최신 API가 있다는 이유만으로 교체할 필요는 없다. 의존성을 줄이는 이득과 이미 확보한 동작을 다시 검증하는 비용을 같이 봐야 한다.
Baseline의 기본값과 제품의 지원 약속을 구분한다
시작 문서는 프로젝트의 AGENTS.md나 CLAUDE.md에 Baseline 목표를 적도록 안내한다. 별도 목표가 없으면 기본값은 Baseline Widely available이다. Baseline은 주요 브라우저 사이의 기능 지원 상태를 정리한 기준이다. Newly available은 핵심 브라우저 전체에서 지원되기 시작한 상태이고, Widely available은 그 시점부터 30개월이 지난 상태다. 정의와 대상 브라우저
이 기본값은 유용한 출발점이지만 우리 방문자의 환경을 조사한 결과는 아니다. 회사가 관리하는 오래된 브라우저나 특정 앱 안의 웹뷰까지 지원해야 한다면 요구를 별도로 적어야 한다. 예를 들어 “메뉴를 열고 링크로 이동하는 기능은 지원 하한에서도 유지하고, 전환 효과는 없어도 된다”처럼 기능과 표현의 약속을 나누겠다. 하나의 연도나 상태 이름만으로 사용자 흐름 전체가 검증되지는 않는다.
실험 기능을 막는 장치도 있다. 최근 단일 엔진에 출시됐거나 안정화 중인 기능, Origin Trial 기능의 가이드는 검색할 수 있지만 조회하려면 명시적으로 허용해야 한다. Origin Trial은 웹사이트에서 실험 기능을 제한적으로 시험하는 제도다. 허용 설정은 .mwgrc에 공유할 수 있다. 기능별 허용 설정
다만 이 설정을 켰다는 것은 관련 가이드를 읽게 했다는 뜻이다. 그 API를 모든 화면에 배포해도 된다는 제품 결정까지 대신하지 않는다. 나는 실험이 필요한 화면과 대체 동작을 정한 뒤 허용 범위를 넓히겠다.
메뉴 하나에서도 의미와 애니메이션의 조건이 다르다
탐색 서랍 가이드는 화면 가장자리에서 나오는 패널을 다룬다. 항상 서랍으로만 쓰면 모달 dialog를, 넓은 화면에서 일반 사이드바로도 쓰면 수동 팝오버를 선택한다. 후자는 배경을 조작하지 못하게 하는 처리와 닫힌 뒤 포커스 복원 등을 코드에서 맡아야 한다. 겉모양이 비슷해도 요소의 의미와 접근성 책임이 달라지는 사례다.
가이드 안에서도 호환성은 기능별로 나뉜다. 초기 스크롤 위치를 정하는 scroll-initial-target은 확인 시점에 Firefox와 Safari에서 지원하지 않는다고 표시돼 있고, 이를 보완하는 초기 위치 설정 코드가 따로 제시된다. 배경의 밝기를 스크롤에 맞추는 애니메이션에도 지원 여부 검사와 대체 경로가 있다. 구체적인 대체 전략
따라서 “가이드를 사용했다”는 사실보다 선택한 구현의 전제 조건을 읽어야 한다. 애니메이션이 빠져도 메뉴를 열고 닫을 수 있는지, 키보드로 닫은 뒤 원래 버튼에 돌아오는지, 좁은 화면과 동작 줄이기 설정에서도 흐름이 이어지는지 확인하겠다. 기능 존재를 검사하는 코드만으로 이 상호작용 전체가 올바르다고 판정할 수는 없다.
평가 점수와 실제 유지 비용을 함께 본다
1.0 릴리스는 Codex CLI와 gpt-6.1-sol을 사용한 220개 작업에서 가이드 미사용·사용 통과율을 50%와 86%로 보고한다. 36%포인트 차이는 프로젝트가 구성한 작업과 검사에서 나온 결과다. 공식 문서는 Playwright로 소스 패턴, 스타일과 동작 등을 검사하고 기준 구현으로 채점기를 보정한다고 설명한다. 우리 서비스의 결함률 감소나 개발 시간 절감으로 환산할 수는 없다. 릴리스의 평가 표, 평가 방법
운영 조건도 살펴야 한다. 검색 계산은 로컬에서 가능하지만, README는 별도로 에이전트 이름·조회한 가이드 ID·에이전트가 만든 검색어 등의 사용 정보 수집을 명시한다. 원래 사용자 프롬프트는 수집하지 않는다고 설명하며, DISABLE_TELEMETRY=1로 수집을 끌 수 있다. CLI 소스에서도 검색 결과와 함께 검색어를 로거에 전달하는 경로를 확인할 수 있다. 수집 안내, CLI 구현 오프라인 검색 지원과 사용 정보 전송 정책은 따로 확인할 항목이다.
코드는 Apache-2.0, 가이드 문서는 별도 명시가 없으면 CC BY 4.0이다. 문서를 사내 지침으로 복사해 배포할 계획이라면 코드와 문서의 라이선스가 같다고 가정하지 않겠다. 라이선스 구분
첫 적용은 기존 메뉴 하나를 고르는 정도로 충분하다.
- 지원할 브라우저와 반드시 유지할 동작을 먼저 적는다.
- 현재 구현과 가이드 적용 구현을 같은 키보드·모바일 흐름에서 비교한다.
- 추가된 대체 코드와 제거한 의존성, 회귀 확인에 드는 시간을 기록한다.
- 사용한 패키지 버전과 가이드 내용을 남겨 업데이트 뒤 차이를 추적한다.
내 도입 기준은 새 API의 개수가 아니다. 팀이 보장할 사용자 경험을 유지하면서 직접 관리할 코드와 검토 비용이 줄어드는가다. 이 조건이 확인되는 컴포넌트부터 적용하면, 가이드는 유행을 따라가는 목록보다 선택의 근거로 쓸 수 있다.
참고 자료
이 이야기가 도움이 되었나요?