[AI] Modern Web Guidance 1.0 사용법: 에이전트 웹 지침

· IT기술 › AI

코딩 에이전트가 만든 웹 코드는 대개 동작한다. 하지만 브라우저 내장 기능을 자바스크립트로 다시 만들거나 낡은 우회 코드를 쓰기도 한다.

이번 포스팅에서는 이를 겨냥해 2026년 11월 1.0 이 나온 Modern Web Guidance 를 알아볼 것이다.

1. Modern Web Guidance 란

코딩 에이전트에게 웹 플랫폼 모범 사례와 브라우저 호환성 정보를 알려 주는 스킬(Skill) 묶음이다. 에이전트용 최신 웹 표준 참고서인 셈이다.

  • 관리 : Chrome, Edge, Firefox, MDN 팀의 오픈소스
  • 내용 : 접근성·성능·보안·UI 분야 가이드. 직접 짠 JS 대신 네이티브 HTML·CSS 기능을 권한다.
  • 지원 도구 : Claude Code, Codex, Cursor, Copilot 등

2. 설치 전에 써 보기

Node.js 22 이상이 필요하다(1.0.1 의 요구 버전). 처음 npx 로 실행하면 패키지를 내려받을지 묻는다.

npx modern-web-guidance@latest search "tooltip"
npx modern-web-guidance@latest retrieve secure-external-subresources
  • search : 가이드 id 와 한 줄 설명을 JSON 으로 준다. "tooltip" 은 position-aware-tooltips, dialog 등 10개가 나왔다.
  • retrieve : 가이드 본문을 Markdown 으로 출력한다.

위 가이드는 CDN 파일에 하위 리소스 무결성(SRI, Subresource Integrity)을 거는 법이다. URL 버전을 고정하고, 직접 계산한 해시를 integrity 에 넣는다.

<script src="https://cdn.example.com/lib@1.2.3/lib.min.js"
        integrity="sha384-(빌드 때 계산한 해시)"
        crossorigin="anonymous" referrerpolicy="no-referrer"></script>

legacy-scan 은 낡은 패턴을 찾는다. 낡은 코드만 모은 폴더에서 돌려 봤다.

<!doctype html>
<script src="https://code.jquery.com/jquery-3.7.1.min.js"></script>
<script>
  $(window).on('scroll', () => console.log(window.scrollY));
</script>
{ "dependencies": { "jquery": "^3.7.1", "core-js": "^2.6.12" } }
npx modern-web-guidance@latest legacy-scan .

결과는 jQuery <script> 에 SRI 가 없다는 1건뿐이었다. 1.0 의 스캔은 정적 분석이고, 출력에 따르면 규칙으로 판정 가능한 가이드 38개(약 20%)만 본다. jQuery 의존성, scroll 리스너, 낡은 core-js 는 잡지 않았다. 결과가 깨끗해도 안심하면 안 된다.

3. 설치하고 에이전트에서 쓰기

공식 문서의 권장 방법은 자동 업데이트되는 대화형 마법사다.

npx modern-web-guidance@latest install

Claude Code 플러그인으로도 설치할 수 있지만, 대체로 자동 업데이트가 안 된다.

claude plugin marketplace add GoogleChrome/modern-web-guidance
claude plugin install modern-web-guidance@googlechrome

공식 문서에 따르면 설치 후 에이전트가 이 CLI 로 가이드를 찾아 읽는다. 공식 글에 따르면 기존 코드는 /modern-web-guidance Modernize the code in this directory 로 호출하면 정적 스캔 뒤 에이전트가 결과를 검토한다고 한다. 마법사가 쓰는 파일은 문서에 없으니 설치 직후 git status 로 확인하자.

4. CLAUDE.md 에 Baseline 명시하기

Baseline 은 주요 브라우저(Chrome, Edge, Firefox, Safari)가 모두 지원하는 웹 기능의 기준이다. 모두 지원하면 Newly available, 그 뒤 30개월이 지나면 Widely available 이다. Baseline 2024 는 2024년에 Newly available 이 된 기능 묶음이다.

에이전트는 프로젝트의 브라우저 지원 범위를 스스로 알 수 없으니, 목표를 CLAUDE.md 나 AGENTS.md 에 한 줄 적어 둔다.

This project's Baseline target is Baseline 2024.

적지 않으면 Widely available 로 본다. 공식 문서에 따르면 목표 범위에 아직 없는 기능은 폴백(fallback)을 고려한 안내를 함께 받는다. 지침 파일 활용은 시리즈 1편과 같다.

5. 주의사항!

  • 테스트가 아니다 : 지침은 코드를 검증하지 않는다. 공식 글도 Chrome DevTools for agents 같은 도구로 확인하라고 한다. 2편 [AI] Claude Code 에이전트 결과 검증하기: diff·테스트·QA (2/3)의 결과 검증이 여전히 필요하다.
  • 실험 기능은 기본 제외 : 한 엔진에만 있는 기능과 오리진 트라이얼(Origin Trial) 기능은 숨겨진다. 프로젝트 루트에서 set-allow-volatile-features, set-allow-origin-trials 명령으로 허용한다.
  • 결과는 상황마다 다르다 : 공식 문서도 프로젝트·모델·프롬프트에 따라 다르다고 한다. 고친 코드는 diff 로 보자.

이렇게 Modern Web Guidance 1.0 을 알아보았다. 설치 없이도 search·retrieve 로 최신 웹 기능을 공부하기에 좋은 것 같다.

참고