"AI가 옛날 jQuery 코드 또 짰어?" — 그 문제를 정면 공격하는 SKILL.md + CLI. Chrome·Edge 팀과 웹 개발자 커뮤니티가 함께 큐레이션한 102개 모던 웹 기능 + 128개 실전 use case 가이드. npx modern-web-guidance@latest install 한 줄로 Claude·Cursor·Gemini·Copilot에 다 꽂힌다. Apache-2.0.
AI 코딩 에이전트가 갖는 구조적 약점을 이해해야 한다.
Claude·Cursor·Copilot·Gemini 같은 AI 코딩 에이전트로 웹 코드를 짜본 사람은 한 번쯤 본 풍경이 있다. "왜 또 jQuery를 추천하지?" "왜 모달을 직접 구현하지? <dialog> 태그가 있는데?" "왜 폴리필부터 갖다 붙이지?". 모던 웹 표준이 다 있는데 — 에이전트는 옛 패턴을 답한다.
이유는 학습 데이터에 있다. LLM은 인터넷에 쌓여 있는 코드를 학습하는데 — 인터넷 코드의 압도적 다수가 2015~2020년대 초반 패턴이다. 같은 양이라면 옛 패턴이 새 패턴보다 100배 많다. 결과: 모델은 "옛 패턴이 정답"이라고 학습해 버린다. 새 API를 알아도 — 자주 본 옛 패턴이 더 자신 있게 나온다.
Modern Web Guidance가 푸는 게 정확히 이 문제다. "에이전트의 컨텍스트 윈도우에 직접 — 새 API의 정답 패턴을 끼워 넣는다." 학습 데이터를 못 바꾸니, 추론 시점에 가이드라인을 주입하는 방식.
SKILL.md 하나에 "이런 상황엔 이렇게 해라"를 적어두면 에이전트가 자동으로 트리거. Modern Web Guidance는 이 SKILL.md를 — 모든 주요 에이전트에 깔리도록 만든 큐레이션이다.전체 글의 핵심 메시지.
웹 개발자 한 명을 가상으로 만들어 — 에이전트 옆에 앉혀 두는 셈. "그건 옛날 방식이야, 이게 더 빠르고 접근성도 좋아"라고 옆에서 알려주는 — 그 한 명이 SKILL.md 파일이다.
대단한 건 "수동으로 새 API를 가르치는 게 아니라 — 자동으로 컨텍스트에 주입"된다는 점. 사용자는 npx ... install 한 번 깔면 — 평소처럼 코드 짜라고만 하면 에이전트가 자연스럽게 최신 패턴을 쓴다.
111 stars지만 — Chrome 공식 + Edge 협력 + 102개 기능이라는 무게.
① Chrome·Edge 공식 협업이라는 단일 사실. 이 레포는 GoogleChrome 조직에서 만들었고 — Microsoft Edge 팀이 함께 검토했다. 두 메이저 브라우저 벤더가 — "AI 시대에 웹 표준이 무너지는 걸 막자"는 공동 합의로 움직였다는 신호.
② Anthropic Skills 패턴의 메이저 채택 사례. SKILL.md는 Anthropic이 정립한 형식인데 — 이걸 Google이 자기 표준 가이드라인의 배포 매체로 골랐다. "SKILL.md가 사실상 AI 에이전트 가이드의 표준 포맷"으로 굳어지고 있다는 증거. 그래서 트렌딩.
③ 멀티 에이전트 호환. 한 레포에 .claude-plugin, .cursor-plugin, gemini-extension.json이 다 들어있다. Claude Code·Cursor·Gemini CLI 모두 같은 가이드를 — 각 도구의 네이티브 형식으로 받아간다. "한 번 만들면 어디서나 동작"의 성공 사례.
④ 실전 use case 128개. "API 설명"이 아니라 "이 상황엔 이걸 써라" 형식. 예: animate-dialog-modal-backdrop, passkey-registration, break-up-long-tasks. 추상 매뉴얼보다 — "내가 지금 마주친 그 문제"에 바로 답한다.
디렉토리 하나가 어떻게 4개 도구를 동시에 지원하는지.
modern-web-guidance/ ├── .claude-plugin/ ← Claude Code용 플러그인 매니페스트 ├── .cursor-plugin/ ← Cursor용 플러그인 매니페스트 ├── .github/img/ ← 로고·아이콘 ├── policies/ ← 큐레이션 원칙 (어떤 가이드를 받아주는가) ├── skills/ │ └── modern-web-guidance/ │ ├── SKILL.md ← 핵심 — 에이전트가 읽는 진입점 │ └── guides/ │ ├── accessibility/ (접근성 가이드) │ ├── built-in-ai/ (브라우저 AI API) │ ├── css/ (모던 CSS) │ ├── css-layout/ (CSS 레이아웃) │ ├── forms/ (폼·자동완성) │ ├── html/ (HTML 요소·속성) │ ├── passkeys/ (패스키 인증) │ ├── performance/ (성능) │ ├── privacy/ (프라이버시) │ ├── security/ (보안) │ ├── user-experience/ (UX 패턴) │ └── webmcp/ (WebMCP 에이전트) ├── gemini-extension.json ← Gemini CLI Extension 매니페스트 ├── package.json ← npm — CLI 본체 ├── CONTRIBUTING.md ├── LICENSE ← Apache-2.0 └── README.md
핵심은 skills/modern-web-guidance/guides/ 디렉토리. 여기에 128개의 작은 마크다운 파일이 있다. 각 파일은 하나의 use case — 예: animate-to-from-top-layer.md는 "모달 배경을 어떻게 애니메이션해야 하는지". 카테고리는 12개(accessibility, built-in-ai, css, css-layout, forms, html, passkeys, performance, privacy, security, user-experience, webmcp).
그리고 루트의 .claude-plugin, .cursor-plugin, gemini-extension.json — 이 세 어댑터가 각 도구의 네이티브 플러그인 형식. "중앙에 진실 하나, 어댑터가 분기"라는 깔끔한 패턴.
모든 가이드는 평범한 .md 파일. JSON·YAML 없음. 사람이 읽고 GitHub 웹에서 바로 PR. 에이전트는 같은 파일을 — fence 안 내용 그대로 컨텍스트에 넣는다. "사람이 쓰는 글이 에이전트에게도 정답"이라는 원칙.
install / search / retrieve 세 명령어의 흐름.
사용자 터미널 │ npx modern-web-guidance@latest install ▼ [CLI 위저드] │ "어떤 에이전트 쓰세요?" │ → Claude Code / Cursor / Gemini / Copilot / Codex / ... ▼ [에이전트별 어댑터] │ Claude Code → .claude/skills/modern-web-guidance/SKILL.md 복사 │ Cursor → .cursor/rules/ 또는 plugin manifest 등록 │ Gemini → gemini-extension.json에 등록 │ Copilot/Cline→ project rule 파일에 추가 ▼ [에이전트가 코드 작성 시작] │ 사용자: "다이얼로그 모달 만들어줘" │ 에이전트: SKILL.md 트리거 → guides/user-experience/animate-to-from-top-layer.md 로드 │ → 옛 jQuery 패턴 대신 native
1. install — 인터랙티브 위저드로 어떤 에이전트에 깔지 묻고, 알맞은 위치에 SKILL.md 배치.
2. search "키워드" — 가이드 검색. 예: npx modern-web-guidance@latest search "animate a dialog modal backdrop". 매칭되는 가이드 id 반환.
3. retrieve "guide-id" — 특정 가이드의 내용을 stdout으로. 에이전트가 도구로 직접 호출하거나, 사람이 확인용으로.
npm 패키지처럼 — 그러나 코드가 아니라 "지식"을 배포하는 매니저. npm install이 의존성 코드를 가져온다면, npx modern-web-guidance install은 "에이전트의 지식 의존성"을 가져온다. 같은 메타포, 새로운 시대.
102개 기능 + 128개 use case가 어떻게 묶여 있는가.
모던 시각 전환: View Transitions API, entry/exit 애니메이션, parallax 스크롤, scrollbar-color. 예시 가이드: navigation-drawer (사이드 메뉴를 native API로 — 라이브러리 없이).
컨테이너 쿼리, subgrid, oklch 색공간, text-wrap: balance, 라인 높이 트리밍. 예시: highlight-text-ranges — 검색 결과·맞춤법 오류·협업 커서 같은 임의 텍스트 범위를 모던 CSS만으로 강조.
Instant Preloading (Speculation Rules), INP 진단, scheduler.yield()로 긴 작업 쪼개기. 예시 가이드 15개: break-up-long-tasks, batch-analytics-events, defer-rendering-heavy-content, efficient-background-processing.
Anchor Positioning, Popover API, :user-invalid 검증, autofill 시리즈(주소·결제·로그인·가입 — 4개 별도 가이드), field-sizing으로 자동 크기 조정. 예: required-field-feedback — "사용자가 입력 끝낸 후에만" 에러 표시.
aria-invalid·aria-live 동기화, 키보드 포커스 관리. 예시: accessible-error-announcement — 시각 상태와 스크린리더 알림을 정확히 같은 시점에 일치시키기.
2024~2026 사이 Chrome이 도입한 on-device API 4종: Translator, Summarizer, Language Detector, LanguageModel. 예: language-detection로 사용자 입력 언어 자동 인식, summarizer로 긴 텍스트 요약 — 전부 사용자 기기 안에서, 서버 호출 0.
패스키 인증의 전 생애 주기 — register, authenticate, reauthenticate, management, conditional-create. WebAuthn을 모른 채로 "passkey-registration"만 retrieve하면 — 작동하는 코드가 나온다.
웹 개발자·에이전트 설계자 양쪽에 다 보석.
CSS 51개 + HTML/DOM 20개 + JS API 31개. 평소 안 쓰는 API를 찾고 — 가이드(retrieve)를 통해 실전 예시까지 한 번에. "이 API를 들어본 적은 있지만 못 써본" 90%를 줄여준다.
각 .md 파일이 — "에이전트가 잘 읽도록" 어떻게 구조화됐는지 그 자체가 교본. 짧은 코드 예시, 명확한 do/don't, "왜 이게 더 나은가" 1~2문장. 자기 도메인의 SKILL.md를 쓸 때 — 이 레포를 그대로 베껴서 시작하면 90점.
한 콘텐츠를 Claude / Cursor / Gemini / Copilot에 동시 배포하는 방법. .claude-plugin / .cursor-plugin / gemini-extension.json의 각 매니페스트를 비교하면 — 4개 도구의 플러그인 시스템 차이가 한눈에 보인다. "플러그인 호환의 모범 답안".
이 레포는 Baseline(브라우저 호환 등급)과 통합됐다. 사용자가 "Baseline Widely Available 타깃"이라고 정하면 — 그 등급에 안 닿는 가이드는 자동 제외. 폴리필이 아니라 — "내가 지원하는 브라우저에서 작동하는 것만" 추천. 옛 라이브러리 없이도 안심.
README에 적힌 표현: "models already know"한 내용을 evals로 잘라낸다. 가이드가 짧을수록 좋다는 원칙. 이것 자체가 — 에이전트 가이드 작성자가 배워야 할 메타-스킬. 자기 SKILL.md를 쓸 때 "이 부분은 모델이 이미 알지 않을까?" 의심해 보는 습관.
아주 가볍다 — Node.js만 있으면 끝.
최소: Node.js 20+ (package.json engines.node: ">=20.0.0" 명시). 에이전트: Claude Code, Cursor, GitHub Copilot, Gemini Code Assist, Cline, Codex — 이 중 하나. CLI 자체는 매우 가벼움 — 가이드 텍스트는 모두 마크다운이라 디스크 차지 미미. "한 번 깔면 평생 모든 웹 프로젝트에서 활용".
Claude Code는 SKILL.md의 description을 보고 자동 트리거하지만 — Cursor는 .mdc 룰 파일로, Gemini는 extension 매니페스트로, Copilot은 프로젝트 규칙 파일로. CLI 위저드가 알아서 변환해주지만, "왜 에이전트가 가이드를 안 쓰지?" 싶으면 깔린 위치와 트리거 조건을 확인.
난이도별 4개. 가이드를 받기만 하는 게 아니라 — 만들어 보는 것까지.
npx modern-web-guidance@latest install → 자기가 쓰는 에이전트 선택. 그 다음 — 동일한 프롬프트(예: "다이얼로그 만들어줘")를 깔기 전·후에 비교. native <dialog>를 쓰는지, jQuery를 쓰는지. 가이드의 효과를 눈으로 확인.
retrieve로 다음 5개 가이드 받기: view-transitions, passkey-registration, break-up-long-tasks, animate-to-from-top-layer, summarizer. 각각 — 빈 HTML 파일에 직접 구현. 평소 안 쓰던 API 5개를 손에 새긴다.
Modern Web Guidance를 그대로 모방 — 자기 분야(예: "한국 결제 API 가이드", "NextJS 모범 패턴")의 SKILL.md + guides 디렉토리 + CLI를 만든다. README, CONTRIBUTING.md, .claude-plugin 매니페스트까지 동일한 구조로. "베스트 프랙티스를 인터넷에 배포하는 새 방법"을 손에 익힌다.
이 레포의 가이드 중 5개를 골라 — 한국어로 번역 + 한국 개발자 맥락에 맞춰 개선(예: 한국 결제, 한국 신원 인증, KST 타임존). 결과를 fork에 올리고 원본에 PR. "오픈소스 큐레이션에 기여하는 첫걸음"으로 가장 큰 무대.
이 레포를 따라가다 보면 — 모던 웹 표준 + AI 에이전트 양쪽이 동시에 늘어난다.
Anthropic의 Agent Skills 공식 문서 정독. SKILL.md의 frontmatter(name/description), 트리거 조건, 마크다운 본문 구조. Modern Web Guidance의 SKILL.md를 — "잘 쓴 예시"로 한 줄씩 분석.
web-features 데이터셋(W3C·Google·MDN 공동). Baseline 등급의 작동 원리. web-platform-dx 사이트. 이 레포가 각 가이드에 — 어떻게 Baseline 정보를 묶었는지 살펴보기.
View Transitions, Anchor Positioning, Popover, Container Queries, Speculation Rules, Built-in AI(Translator). 각 API를 — 이 레포 가이드 + 공식 spec + 작은 데모 페이지 3단 콤보로 완전히 흡수.
자기 팀이 자주 쓰는 — 그러나 에이전트가 자꾸 옛 방식으로 짜는 — 5개 패턴을 골라 SKILL.md로. npx CLI까지 짤 필요는 없고 — 그냥 사내 git repo의 SKILL.md만으로도 충분. "오픈소스 기여 + 사내 생산성" 동시 달성.
레포·매뉴얼·문서 안에서 자주 나오는 용어.
position-anchor, inset-area. 옛날엔 Popper.js·floating-ui 같은 라이브러리를 깔아야 했지만 — 이젠 CSS만으로 끝. 이 레포의 forms·UX 가이드 절반이 여기 기반.popover 속성으로 — 메뉴·툴팁·다이얼로그를 native top-layer에 표시. backdrop·접근성·키보드 ESC 처리 모두 자동. "라이브러리 없이 모달 만들기"의 정답. <dialog>와 함께 묶이는 경우 많음.setTimeout(0)의 후속. INP(Interaction to Next Paint) 메트릭 개선의 핵심 도구.레포·공식 문서·관련 자료.
레포 본체: github.com/GoogleChrome/modern-web-guidance
공식 문서: developer.chrome.com/docs/modern-web-guidance
web-features 데이터셋: web-platform-dx.github.io/web-features-explorer
예시 가이드: navigation-drawer, passkey-registration, break-up-long-tasks, view-transitions, summarizer
npx modern-web-guidance@latest install. 30초면 끝.