Modern Web Guidance 1.0: Claude Code·Codex·Cursor 설정

Modern Web Guidance 1.0을 프로젝트 스킬로 설치한 뒤, 저장소 전체에 적용하기 전에 프런트엔드 작업 하나에서 가이드 활용 여부를 확인합니다. legacy-scan은 검토할 코드 개선안을 만드는 데 사용하고, 감독 없이 코드를 다시 작성하는 용도로 사용하지 않습니다. Modern Web Guidance의 사용 텔레메트리를 보내지 않으려면 첫 명령을 실행하기 전에 DISABLE_TELEMETRY=1을 설정합니다.

Modern Web Guidance 1.0에서 달라지는 점

Modern Web Guidance는 기존 코딩 에이전트가 코드를 작성하기 전에 브라우저 기능에 관한 구체적인 지침을 제공합니다. 2026년 11월 10일 공개된 1.0 릴리스에는 사용 사례별 가이드 203개가 포함되어 있으며, 웹 플랫폼 기능 250개를 다룹니다. Chrome, Edge, Firefox, MDN 팀이 커뮤니티 기여자와 함께 프로젝트를 관리합니다.

스킬은 에이전트에 제공하는 지침 묶음입니다. 관련 가이드를 검색하고 내용을 가져온 다음, 구현 규칙과 호환성을 위한 대체 처리인 폴백을 적용하도록 안내합니다.

검색에는 로컬 임베딩 모델과 키워드 기반 순위 지정 방식인 BM25를 함께 사용합니다. 공식 프로젝트 README에 따르면 이 검색의 매칭 작업에는 외부 모델 API나 API 키가 필요하지 않습니다.

에이전트가 브라우저 API의 존재는 알지만 전환 동작이나 호환성 폴백 같은 세부 사항을 놓칠 때 유용합니다. 다만 지원 브라우저를 정하고, 변경 사항을 검토하고, 애플리케이션 테스트를 실행하는 책임은 개발자에게 남습니다.

Claude Code, Codex, Cursor에 설치하기

세 에이전트 모두 동일한 명령줄 도구인 CLI를 통해 프로젝트 단위로 설치합니다. 설치 명령의 래퍼 코드는 Vercel Skills를 호출합니다. 2026-11-13 기준으로 현재 Skills 설치 프로그램의 요구 사항을 충족하려면 Node.js 22.20 이상을 사용해야 합니다. npm/npx와 필요한 패키지를 내려받을 권한도 필요합니다.

프로젝트 루트에서 Bash를 엽니다. 공식 설치 명령을 실행하기 전에 Modern Web Guidance 텔레메트리를 해제합니다.

export DISABLE_TELEMETRY=1
npx modern-web-guidance@latest install

대화형 설치 프로그램에서 대상 에이전트를 선택할 수 있습니다. Claude Code, Codex, Cursor 중 실제로 사용하는 에이전트를 선택합니다. 저장소 하나에서 시험할 때는 설치 범위를 프로젝트로 유지합니다. 설치 프로그램도 기본적으로 프로젝트 범위를 사용합니다.

이 CLI 설치 방식에서는 다음 프로젝트 파일과 명시적 호출 방법을 확인합니다.

에이전트	프로젝트의 스킬 파일	명시적 호출 방법
Claude Code	.claude/skills/modern-web-guidance/SKILL.md	/modern-web-guidance를 입력합니다.
Codex	.agents/skills/modern-web-guidance/SKILL.md	/skills를 사용하거나 $modern-web-guidance를 지정합니다.
Cursor	.agents/skills/modern-web-guidance/SKILL.md	Agent 채팅에 /를 입력하고 스킬을 선택합니다.

이 디렉터리는 현재 설치 프로그램이 각 에이전트에 지정한 위치입니다. 플러그인 캐시나 전역 설치 경로가 아닙니다.

같은 저장소에서 에이전트의 새 세션을 시작하고, 첫 확인에서는 스킬을 명시적으로 호출합니다. 스킬이 나타나지 않으면 다시 설치하기 전에 선택한 에이전트, 설치 범위, 파일 위치를 확인합니다.

CLI로 설치한 스킬은 프로젝트 디렉터리에서 다음 명령으로 업데이트합니다.

npx modern-web-guidance@latest update

업데이트한 뒤에는 변경된 스킬 파일을 검토하고, 다음 절의 가이드 조회 확인을 반복합니다. 이 명령은 @latest를 사용하므로 앞으로 업데이트해도 버전 1.0이 유지된다고 가정하면 안 됩니다.

플러그인 마켓플레이스 설치는 별도 경로입니다. 해당 경로의 업데이트 절차와 이 CLI 절차를 구분해야 합니다. Claude Code 플러그인의 구성과 관리 방법은 플러그인 설치·확인·제거 가이드에서 확인할 수 있습니다.

검색, 조회, 에이전트의 실제 활용 확인하기

CLI가 작동하는지뿐 아니라 에이전트가 출력 내용을 실제로 사용하는지도 확인합니다. 터미널 명령이 성공했다는 사실만으로 에이전트가 스킬을 불러왔다고 볼 수는 없습니다.

문서의 대화상자 예제를 Bash에서 실행합니다.

npx modern-web-guidance@latest search "animate a dialog modal backdrop"
npx modern-web-guidance@latest retrieve "animate-to-from-top-layer"

검색은 가이드 ID와 설명을 담은 JSON을 반환합니다. 조회는 선택한 가이드의 내용을 반환합니다. 출력이 크면 CLI가 본문 대신 저장된 파일 경로를 표시할 수 있습니다. 이때는 에이전트가 해당 파일을 끝까지 읽도록 요청합니다.

설치한 스킬을 호출한 뒤 범위가 명확한 작업을 맡깁니다. 다음 요청은 기존 프레임워크와 브라우저 지원 정책을 유지하고, 편집 전에 관련 가이드를 가져오도록 요구합니다.

Use the modern-web-guidance skill to add an animated modal dialog.
Keep the existing framework and browser support policy.
Retrieve the relevant guidance before editing.
Afterward, report the guide IDs, required fallbacks, and tests run.

도구 호출 기록에서 실제 검색과 조회가 있었는지 확인합니다. 최종 보고서에는 사용한 가이드와 그 가이드가 영향을 준 구현 결정이 나와야 합니다. 에이전트가 “모범 사례를 적용했다”고 말하는 것만으로는 충분하지 않습니다.

릴리스에 포함된 대화상자 애니메이션 가이드는 구체적인 코드 검토 기준을 제공합니다. 코드에서 transition 단축 속성을 사용한다면 transition-behavior: allow-discrete를 그 뒤에 선언해야 합니다. 그렇지 않으면 단축 속성이 해당 값을 초기화합니다.

대화상자가 나타나고 사라질 때의 동작, 모션 감소 설정에서의 동작, 기존 대화상자 상호작용을 테스트합니다.

첫 명령이 검색 결과를 반환하기 전에 실패한다면 Node.js와 패키지 다운로드 권한부터 확인합니다. 릴리스의 스킬 지침은 패키지를 내려받는 단계와 오프라인 동작을 명확히 구분합니다. 임의의 npx 실행을 허용하지 말고 필요한 패키지 명령만 승인해야 합니다.

검색 결과가 맞지 않으면 “confirmation modal dialog”처럼 구체적인 브라우저 동작을 나타내는 검색어로 다시 시도합니다. 절차가 성공한 것처럼 보이게 하려고 관련 없는 가이드를 가져오면 안 됩니다.

legacy-scan으로 자동 수정 대신 변경 후보 검토하기

legacy-scan은 저장소나 디렉터리에서 최신 방식으로 바꿀 수 있는 코드 후보를 찾는 데 사용합니다. 특정 컴포넌트를 변경할 때는 검색과 가이드 조회를 사용합니다. 코드 현대화 절차 문서도 이 차이를 설명합니다.

읽기 쉬운 형식으로 결과를 보려면 프로젝트 루트에서 다음을 실행합니다.

npx modern-web-guidance@latest legacy-scan .

에이전트가 검토할 구조화된 출력이 필요하면 다음을 사용합니다.

npx modern-web-guidance@latest legacy-scan . --json

결과는 관련 가이드에 연결된 변경 후보이며, 수정된 소스 파일이 아닙니다. 정적 스캐너는 언어 모델을 호출하지 않습니다. 이후 에이전트가 결과를 분석하고 편집하는 단계에서는 평소의 모델 접근 경로를 계속 사용합니다.

에이전트에 문서화된 네 단계를 따르도록 요청합니다.

1. 선택한 디렉터리를 스캔하고 변경 후보를 수집합니다.
2. 주변 코드와 keepWhen/dropWhen 규칙을 기준으로 각 후보를 확인합니다. 모든 일치를 필수 변경으로 취급하지 말고 오탐을 제외합니다.
3. 확인된 결과와 제안하는 수정 내용을 보고합니다. 코드 현대화를 시작하기 전에 개발자의 승인을 받도록 합니다.
4. 승인된 후보에 해당하는 가이드를 조회한 뒤 지침에 따라 수정합니다. 기존 테스트를 실행하고 변경한 범위를 다시 스캔합니다.

의도적으로 남겨 둔 폴백과 기능 지원 여부를 확인한 뒤 실행하는 호환성 코드를 특히 주의해서 검토합니다. 오래되어 보이는 구현도 프로젝트의 브라우저 지원 정책상 필요할 수 있습니다.

버전 1.0의 스캐너는 가이드의 약 20%를 다룹니다. 오래된 패턴을 확정적인 규칙으로 식별할 수 있는 가이드만 해당합니다. 이 비율은 가이드 목록에서 차지하는 비중이지 코드베이스의 비율이 아닙니다. 따라서 검출 결과가 없다는 사실만으로 프로젝트가 완전히 현대화되었거나, 접근성을 갖췄거나, 올바르게 작동한다고 판단할 수 없습니다.

변경 전에 브라우저 지원 정책과 .mwgrc 설정하기

호환성 요구 사항을 명확히 지정하고, 프로젝트에 필요하지 않다면 실험적 가이드는 비활성 상태로 둡니다. 기본적으로 스킬은 Baseline Widely available 기능을 폴백 없이 사용할 수 있다고 가정합니다.

Baseline 설정 지침은 프로젝트의 지원 목표를 AGENTS.md나 CLAUDE.md에 기록하는 방법을 설명합니다. 실제 지원 정책을 사용해야 합니다. 제안된 대체 구현을 받아들이기 위해 지원 정책을 바꾸면 안 됩니다.

프로젝트 루트의 선택적 JSON 파일 .mwgrc는 실험적 가이드 접근을 제어합니다. 보수적인 정책을 기록하려면 기존 설정에 다음 필드를 추가하거나 병합합니다.

{
  "allowOriginTrials": false,
  "allowVolatileFeatures": false
}

volatile 가이드는 단일 브라우저 엔진에서만 제공되는 기능 중 최근 3개월 안에 출시되었거나 아직 안정화 중인 기능을 다룹니다. 이런 가이드는 검색 결과에 계속 나타나지만, 내용을 조회하려면 명시적인 허가가 필요합니다. Origin Trial 가이드에는 별도의 허가 설정이 있습니다.

volatile 기능의 가이드를 허용하려면 개발자가 직접 사용하는 대화형 Bash 터미널에서 다음을 실행합니다.

npx modern-web-guidance@latest set-allow-volatile-features

Origin Trial 가이드는 필요할 때만 별도의 명령으로 허용합니다.

npx modern-web-guidance@latest set-allow-origin-trials

각 명령은 확인을 요청한 뒤 해당 불리언 값을 true로 설정합니다. 출력된 설정 파일 경로와 변경된 키를 확인하고, 가이드 조회를 다시 시도합니다.

에이전트 내부나 비대화형 셸에서 실행이 거부되는 것은 의도된 동작입니다. 허가 처리 구현은 사람이 제어하는 대화형 터미널을 요구합니다. 에이전트에 이 확인을 우회하도록 요청하면 안 됩니다.

이 설정은 가이드 접근만 허용합니다. 브라우저 기능을 활성화하거나, 사이트를 Origin Trial에 등록하거나, 프로젝트의 브라우저 지원 정책을 확대하지 않습니다.

텔레메트리와 컨텍스트 비용 관리하기

텔레메트리는 Modern Web Guidance를 실제로 실행하는 환경에서 해제해야 합니다. 별도의 터미널에만 설정해서는 충분하지 않습니다. 프로젝트 개인정보 보호 설명에 따르면 수집 정보에는 설치 횟수, 호출한 에이전트 이름, 조회한 가이드 ID, 에이전트가 생성한 검색어가 포함됩니다. 원본 사용자 프롬프트는 수집하지 않는다고 명시되어 있습니다.

다만 검색어로도 작업의 세부 내용이 드러날 수 있습니다. .bashrc 같은 Bash 시작 설정에 export DISABLE_TELEMETRY=1을 추가합니다. 에이전트가 명령을 실행하는 환경에 이 변수가 전달되는지 확인해야 합니다. 필요하면 이미 실행 중인 에이전트나 IDE를 갱신된 환경으로 다시 시작합니다.

도구 호출에 사용하는 Bash 환경에서 다음 명령으로 값을 출력하지 않고 확인할 수 있습니다.

test "${DISABLE_TELEMETRY:-}" = 1

종료 상태 0은 해당 환경에서 변수 값이 1임을 뜻합니다. 네트워크 트래픽을 감사한 결과는 아닙니다. 이 확인만으로 에이전트 제공자나 다른 도구의 텔레메트리 설정을 알 수는 없습니다.

오프라인 검색이 전체 작업의 오프라인 실행을 뜻하지도 않습니다. 패키지를 내려받으려면 네트워크 접근이 필요합니다. Modern Web Guidance 텔레메트리도 해제하기 전까지 활성 상태입니다.

컨텍스트 사용량의 참고치로 README는 modern-web-guidance를 약 205 tokens, chrome-extensions를 약 175 tokens로 안내합니다. 이 수치는 에이전트 작업 전체의 최대 사용량이 아닙니다. 조회한 가이드 내용이 컨텍스트에 추가되며, 검증과 편집에도 에이전트의 추가 작업이 필요합니다.

대표적인 작업에서 실제 사용량을 측정해야 합니다. 안내된 스킬 크기만으로 절감액을 계산하면 안 됩니다.

평가 개선치를 참고해 직접 비교하기

Google의 결과는 스킬을 시험할 근거가 되지만, 모든 작업에서의 성공률이나 토큰 절감을 보장하지는 않습니다. 2026-11-08 기준 공식 README의 평가 결과는 다음과 같습니다.

에이전트와 모델 표기	작업 / 검증 항목	가이드 없음	가이드 사용	개선 폭
claude_code / opus-5-5	215 / 1801	57%	88%	31퍼센트포인트
codex_cli / gpt-6.1-sol	215 / 1795	54%	82%	28퍼센트포인트
antigravity_cli / gemini-4-argon	214 / 1673	58%	94%	36퍼센트포인트

이는 개별 검증 항목의 통과율이지, 프로덕션 프로젝트를 성공적으로 완료한 비율이 아닙니다. 행마다 작업 수와 검증 항목 수도 다릅니다. 따라서 동일한 작업 조건에서 통제된 비교로 얻은 모델 순위로 해석하면 안 됩니다.

평가 대시보드의 방법론은 통과율을 통과한 검사 수를 실행된 검사 수로 나눈 값으로 정의합니다. 채점 전에 비정상 종료되거나 시간 제한을 초과한 실행은 제외됩니다. 그 실행과 짝을 이루는 비교 실행도 함께 제외됩니다.

Google은 자체 가이드를 기준으로 평가를 설계했습니다. 에이전트의 흔한 오류를 설명한 글은 가이드가 정한 기대 사항과 출력을 비교하는 방식을 설명합니다. 도구 제공자가 수행한 평가 결과로 받아들여야 하며, 애플리케이션 품질에 대한 독립적 검증으로 보면 안 됩니다.

도입을 결정하려면 대표적인 컴포넌트 작업 하나를 가이드 사용 전후로 비교합니다. 모델, 프롬프트, 브라우저 지원 정책은 동일하게 유지합니다. 관련 브라우저 동작, 회귀 테스트, 소요 시간, 실제 사용량을 검토합니다.

비용을 판단할 때는 토큰 단가만이 아니라 코딩 작업 하나를 완료하는 데 드는 비용을 사용합니다. 저장소에서 중요한 검증 결과를 개선하면서도 검토와 사용 비용이 감당할 수 있는 범위일 때 Modern Web Guidance를 계속 사용합니다.