오늘(11/14) GitHub Trending 일간 2위에 오른 GoogleChrome/modern-web-guidance-src는 하루 만에 별 1,925개를 받았습니다(누적 4,944개, 11/14 오전 기준). 이름만 보면 문서 저장소 같지만, 실제로는 “코딩 에이전트가 낡은 웹 코드를 쓰지 않게 만드는 스킬”을 작성하고, 배포하고, 효과를 측정하는 파이프라인 전체가 들어 있는 저장소입니다. npm 패키지 modern-web-guidance가 11월 10일(KST) 1.0.0을 찍었고, README에는 Chrome·Microsoft Edge·Mozilla Firefox·MDN 팀이 함께 관리한다고 적혀 있습니다.
이 글은 입문 소개가 아니라 실무자 관점의 해부입니다. 저장소 구조, 로컬 하이브리드 검색(정적 임베딩 + BM25 + RRF)의 설계 이유, 그레이더 보정 기반 평가 하네스, legacy-scan의 “후보는 기계가, 판정은 에이전트가” 구조를 짚고, GPU 없는 리눅스 박스에서 직접 돌린 결과와 도입할 때 걸리는 점까지 정리했습니다.
1. 한눈에 보기
| 항목 | 내용 |
|---|---|
| 저장소 | GoogleChrome/modern-web-guidance-src (소스) → 배포용 GoogleChrome/modern-web-guidance |
| 라이선스 | 코드 Apache-2.0, guides/ 아래 문서·가이드 CC-BY 4.0 (일부 MDN·W3C·WHATWG·IETF 문서 파생) |
| 배포 버전 | npm modern-web-guidance 1.0.0 (2026-11-10 12:29 KST 게시, 직전은 0.0.206) |
| 저장소 생성 | 2026-01-27 (UTC) — 약 10개월 동안 0.0.x로 120여 회 배포 |
| 런타임 | CLI는 Node.js 22+ (저장소 개발은 Node ≥22.18, pnpm 10) |
| 규모 | 배포 패키지 기준 list 결과 208개 가이드, 패키지 압축 해제 약 17MB |
| 지원 에이전트 | Claude Code, OpenAI Codex, Gemini/Antigravity, GitHub Copilot CLI, Grok Build CLI, Kimi Code, Vercel npx skills, gh skill 등 |
| 핵심 명령 | search / retrieve / list / legacy-scan / install / update |
2. 왜 이런 게 필요한가: “모델은 API를 알아도, 최신 구현 밀도가 없다”
README가 내세우는 문제 정의는 단순합니다. LLM 학습 데이터에는 레거시 코드가 압도적으로 많아서, 에이전트는 모달을 만들 때 <dialog>와 closedby 대신 div.overlay와 z-index: 9999, 키보드 이벤트 핸들러를 엮는 쪽으로 기웁니다. 모델이 API의 존재를 알더라도 “실제 프로덕션에서 쓰는 최신 패턴”의 밀도가 부족하다는 겁니다.
해법은 파인튜닝이 아니라 컨텍스트 주입입니다. 에이전트가 웹 UI·CSS·클라이언트 JS 작업을 시작하면 스킬이 켜지고, CLI로 관련 가이드를 찾아 필요한 부분만 컨텍스트 창에 넣습니다. 여기까지는 다른 “문서 MCP”와 비슷해 보이지만, 이 프로젝트가 다른 점은 세 가지입니다.
- 완전 로컬 검색 — 질의 임베딩까지 패키지 안의 정적 단어표로 처리해 API 키·네트워크 호출이 없습니다(최초
npx다운로드 제외). - Baseline 연동 — 각 가이드가 web-features/Baseline 호환성 데이터를 빌드 타임에 끼워 넣고, Widely available이 아닌 기능은 폴백을 강제합니다.
- 효과 측정 루프 — 가이드마다 Playwright 그레이더를 만들어 “스킬 사용/미사용” 통과율 차이(uplift)를 재고, 모델이 이미 잘하는 내용은 잘라냅니다.
3. 두 저장소의 관계와 배포 형태
트렌딩에 오른 것은 -src 저장소입니다. 사용자가 설치하는 것은 별도의 배포 저장소와 npm 패키지이고, -src에는 저작·빌드·평가 도구가 모두 들어 있습니다. 실무에서 헷갈리기 쉬운 부분이라 표로 정리합니다.
| 구분 | modern-web-guidance-src (트렌딩) | modern-web-guidance (배포) | npm modern-web-guidance |
|---|---|---|---|
| 용도 | 가이드 저작, 빌드, 평가 하네스, 대시보드 | 에이전트 플러그인 마켓플레이스·스킬 소스 | npx로 실행하는 자체 완결 CLI |
| 주요 내용 | guides/, src/(rag·harness·grading·analyzing), bin/gd.ts |
skills/modern-web-guidance/, skills/chrome-extensions/ |
SKILL.md, modern-web.mjs, search.mjs, legacy-scan.mjs, gen/ |
| 누가 쓰나 | 기여자·SME·평가 엔지니어 | Claude Code·Codex·Copilot CLI 등 플러그인 사용자 | 모든 에이전트(스킬이 이 CLI를 호출) |
| 의존성 | pnpm, Playwright, ts-morph, @huggingface/transformers 등 | — | 런타임 의존성 없음(번들) |
스킬 팩은 두 개입니다. modern-web-guidance(README 기준 약 205토큰)와 chrome-extensions(약 175토큰). 여기서 토큰 수는 상시 로드되는 스킬 설명 부분이고, 실제 가이드 본문은 retrieve 때만 들어옵니다. 상시 컨텍스트 비용을 작게 유지하고 본문은 온디맨드로 당기는, 요즘 Agent Skills 설계의 전형입니다.
4. 저장소 구조
| 경로 | 역할 | 실무 포인트 |
|---|---|---|
guides/<category>/<slug>/ |
가이드 단위 디렉터리 (css, html, js, forms, accessibility, performance, security, built-in-ai, webmcp, wasm, ui-components 등) | 에이전트가 런타임에 읽는 것은 guide.md 하나뿐 — 그래서 자기완결적·명령형으로 써야 한다는 규칙 |
features/ |
기능 정의, 트랜스클루전용 스니펫, volatile-features.json, origin-trials.json |
변동성 기능·오리진 트라이얼 게이트의 원천 데이터 |
src/rag/ |
하이브리드 검색, 정적 임베더, BM25, 청크 캐시, 벤치마크 | gen/에 Int8 양자화 벡터가 커밋돼 있음 |
src/harness/, src/grading/ |
에이전트 실행기, 베이스 앱(daily-grind, devtools-times), Playwright 그레이더 생성·보정 | 에이전트를 bwrap/sandbox-exec 샌드박스에 격리해 그레이더를 못 보게 함 |
src/analyzing/ |
legacy-scan 정적 분석기 (rules, scanners, llm-verifier) |
규칙마다 keepWhen/dropWhen 루브릭 동봉 |
src/build/, src/cli/ |
가이드 빌드(매크로 확장), 배포 패키지, 릴리스 노트, 텔레메트리 | pnpm build → dist/skills-cli |
.agents/skills/ |
이 저장소에서 일하는 에이전트용 내부 스킬(가이드 작성, 평가 작성, 야간 평가 조사 등) | 기여 자체도 에이전트 친화적으로 설계 — AGENTS.md가 진입점 |
가이드 하나의 파일 구성은 저작과 평가의 경계를 그대로 보여 줍니다. SME(주제 전문가)는 정확성에만 집중하고, Playwright 테스트 작성·디버깅은 gd dev 파이프라인이 맡습니다.
| 파일 | 작성 주체 | 용도 |
|---|---|---|
guide.md |
SME | 가이드 본문. 프런트매터 name·description·web-feature-ids, 빌드 매크로(BASELINE_STATUS, FEATURE_FALLBACKS, GUIDE_REF 등) |
demo.html |
SME | 정답 수준의 단독 구현 |
expectations.md |
SME | 관찰 가능한 체크 목록(자연어) — 그레이더 생성의 입력 |
targets/<app>/task.md |
자동 생성 | API 이름을 언급하지 않는 개발자 프롬프트 한 줄 |
targets/<app>/patches/ |
자동 생성 | 서로 다른 에이전트 계열 3종의 골든 패치 + 기준 패치(zero-passrate.patch) |
targets/<app>/grader.ts |
자동 생성 | 골든은 100% 통과, 원본 앱은 0% 통과하도록 보정된 Playwright 테스트 |
예를 들어 light-dismiss-a-dialog의 expectations.md에는 “<dialog>에 closedby="any"가 있어야 한다”, “다이얼로그 내부 클릭으로는 닫히면 안 된다”, “closedby 미지원 브라우저용 폴백이 있어야 한다” 같은 문장이 그대로 들어 있습니다. 이 문장이 그레이더로 번역됩니다.
5. 검색 설계: 왜 질의와 문서를 다르게 임베딩하나
search는 이 프로젝트에서 가장 공들인 부분입니다. src/rag/README.md 기준 구조는 비대칭 dense 검색 + Okapi BM25 + RRF입니다.
| 구성요소 | 구현 | 설계 의도 |
|---|---|---|
| 질의 임베딩 | StaticEmbedder — 29,165단어 × 256차원 Int8 단어표, gemini-embedding-001에서 Model2Vec + Tokenlearn 방식으로 증류 |
23.4MB짜리 all-MiniLM-L6-v2 런타임을 대체, 질의 임베딩 약 30µs |
| 문서 임베딩 | 빌드 타임에 gemini-embedding-001(RETRIEVAL_DOCUMENT, 768→256차원 MRL)로 계산해 Int8 캐시로 커밋 |
런타임엔 네트워크 없이 벡터만 로드 |
| 어휘 검색 | Okapi BM25 (k1=1.2, b=0.75), Lucene EnglishMinimalStemmer 토크나이즈 | 청크마다 가이드 제목·카테고리·web-feature ID를 접두로 붙여 정확한 식별자 재현율 확보 |
| 융합 | Reciprocal Rank Fusion, k=60 | dense 순위와 BM25 순위를 점수 스케일 걱정 없이 합침 |
| 범위 밖 거부 | BM25 적중이 0이고 dense top-1 코사인이 0.30 미만이면 [] |
무관한 질의에 엉뚱한 가이드를 밀어 넣는 컨텍스트 낭비 방지 |
| 출력 | 상위 10개 {id, description} (결과당 약 53토큰) |
README 기준 같은 ~530토큰 예산에서 Hit@K +7.4pp |
흥미로운 것은 왜 비대칭인가에 대한 설명입니다. 정적 임베딩은 단어 벡터의 가중 평균이라, 300단어짜리 마크다운 청크를 평균하면 모든 문서 벡터가 영어 빈도 중심 쪽으로 쏠려 코사인 0.970 근처의 좁은 원뿔로 모입니다(README의 표현으로 “cone collapse”). 실제로 대칭 실험에서 "best pizza in new york"가 <dialog>와 0.899 코사인을 기록했다고 합니다. 반면 3단어 질의의 합은 256차원에서도 날카롭게 유지되므로(평균 쌍별 코사인 0.28), 질의는 싸고 빠른 정적 표로, 문서는 무거운 교사 모델로 따로 만들어 같은 256차원 공간에서 만나게 한 것입니다.
이 선택의 비용도 분명합니다. 정적 단어표는 영어 어휘 기반이라 한국어 질의는 사실상 BM25도 dense도 잡지 못합니다. 박스에서 "다크 모드 스크롤바"로 검색하면 빈 배열이 돌아왔습니다. 스킬 지침이 “2~5단어의 동작 중심 영어 질의”를 요구하는 이유이기도 합니다. 에이전트가 질의를 만들기 때문에 실사용에는 큰 문제가 아니지만, 사람이 직접 CLI를 칠 때는 기억해 둘 만합니다.
검색 품질 평가도 꽤 엄격합니다. 텔레메트리에서 뽑은 실제 질의 4,000개(wild, dev/test 2,000씩, 형태소 토큰 묶음이 겹치지 않게 분할), 야간 평가 궤적에서 캐낸 에이전트 질의 1,029개(agent, 정답 가이드 연결요소 단위로 분할), 범위 밖 질의 90개(oos)로 Hit@K, Leaf nDCG, 그리고 무관 가이드에 쓴 토큰을 감점하는 SNR 지표를 씁니다. 다만 wild 데이터셋은 내부 저장소에 있어서 외부에서는 pnpm benchmark:rag --public-only로 공개 데이터셋만 재현할 수 있습니다.
6. 설치와 실행
README의 기본 경로는 대화형 설치 마법사입니다. 설치 없이 바로 써 볼 수도 있습니다.
# 대화형 설치 (스킬 팩 선택은 --choose)
npx modern-web-guidance@latest install
npx modern-web-guidance@latest install --choose
# 설치 없이 시험
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 legacy-scan .
# 업데이트
npx modern-web-guidance@latest update
# 텔레메트리 끄기 (셸 프로필에)
export DISABLE_TELEMETRY=1에이전트별 플러그인 설치도 README에 명시돼 있습니다.
# Claude Code
/plugin marketplace add GoogleChrome/modern-web-guidance
/plugin install modern-web-guidance@googlechrome
# OpenAI Codex
codex plugin marketplace add GoogleChrome/modern-web-guidance
codex plugin add modern-web-guidance@googlechrome
# Vercel Skills CLI / GitHub CLI
npx skills add GoogleChrome/modern-web-guidance
gh skill install GoogleChrome/modern-web-guidance| 명령 | 동작 | 운영 메모 |
|---|---|---|
search <query> |
상위 10개 {id, description} JSON |
짧은 영어 동작형 질의 권장, 프레임워크 이름은 빼기 |
retrieve <ids> |
가이드 본문(쉼표로 여러 개) | 출력이 9.5KB를 넘고 파이프면 /tmp/mwg-guide-*.md로 떨구고 경로만 안내 |
list |
전체 가이드 목록 | 검색이 두 번 빗나갔을 때의 최후 수단 |
legacy-scan [path] |
레거시 패턴 탐지 (--json, --guide, --include-docs-and-tests) |
문서·테스트·데모 파일은 기본 제외 |
set-allow-origin-trials |
.mwgrc에 "allowOriginTrials": true |
오리진 트라이얼 API 가이드 잠금 해제 |
set-allow-volatile-features |
.mwgrc에 "allowVolatileFeatures": true |
단일 엔진·최근 출시 기능 가이드 잠금 해제 |
retrieve의 /tmp 스필링은 작지만 영리한 디테일입니다. Claude Code·Codex CLI 같은 하네스는 약 10KB를 넘는 터미널 출력을 가운데서 잘라 버리는데, 에이전트는 “리다이렉트하라”는 지시를 잘 따르지 않는다는 관찰에서 나온 장치입니다. README에 따르면 가이드의 76.6%는 9.5KB 미만이라 한 번에 인라인으로 들어갑니다.
7. 박스 실측: GPU·키 없이 돌려 본 결과
GPU 없는 리눅스 박스(Node 24.22)에서 DISABLE_TELEMETRY=1을 켜고 npm 1.0.0을 직접 실행했습니다. 수치는 이 환경에서 관찰한 값이며 일반화된 벤치마크가 아닙니다.
| 시험 | 결과 | 해석 |
|---|---|---|
search "animate a dialog modal backdrop" |
1위 animate-to-from-top-layer, 이어 light-dismiss-a-dialog, prevent-page-scroll-under-modal-dialog, dialog 등 10개 / 첫 실행 포함 약 1.0초 |
대부분은 npx·Node 기동 시간, 검색 자체는 체감 불가 수준 |
retrieve animate-to-from-top-layer |
10.7KB·244줄 → /tmp/mwg-guide-*.md로 저장하고 안내 2줄만 출력 |
9.5KB 스필링 규칙 그대로 동작. 파일로 리다이렉트(>)하면 인라인 출력 |
retrieve language-model (Prompt API) |
stdout 0바이트, 경고만 출력 — “변동성 기능은 프로젝트 opt-in 필요, 에이전트가 직접 잠금 해제하지 말 것” | 단일 엔진 기능의 무분별한 채택을 막는 게이트가 실제로 작동 |
search "다크 모드 스크롤바" |
[] |
영어 어휘 기반 정적 임베딩·BM25의 한계 |
search "best pizza in new york" |
범용 가이드(accessibility, performance, html 등) 10개 반환 | README가 말하는 0.30 바닥은 BM25 적중이 0일 때만 작동 — 흔한 영단어가 BM25에 걸리면 거부되지 않음 |
list |
208개 항목 | README의 “250 modern web features”는 기능 수, 가이드 수와는 다름 |
legacy-scan (일부러 낡게 쓴 예제 4파일) |
3건/2개 가이드: 비밀번호 input의 autocomplete 누락 1건, ::-webkit-scrollbar 2건 / 약 0.7초, 35개 규칙·33개 가이드 검사 |
같은 예제의 JSON.parse(JSON.stringify()), 수동 AbortController 타임아웃, scrollHeight 자동 높이 조절은 미탐 |
마지막 줄은 버전 차이로 설명됩니다. 저장소 main에는 11/13(현지) 커밋으로 structured-clone, abort-signal-timeout 등 JS 규칙이 추가됐지만 npm 1.0.0은 그 이전 빌드입니다. 즉 소스 저장소 README·코드와 배포된 CLI의 기능이 하루 이틀씩 어긋날 수 있다는 점을 염두에 둬야 합니다. 커버리지 자체도 CLI가 스스로 밝히듯 코퍼스의 약 20%에 해당하는 가이드에만 결정적 규칙이 있습니다.
8. legacy-scan: 정밀도를 루브릭에 위임하는 정적 분석
legacy-scan은 일반적인 린터와 철학이 다릅니다. 런타임에는 LLM도 네트워크도 쓰지 않는 고재현율 Static Matcher만 돌립니다. fastTokens 선필터로 매칭 가능성이 없는 파일은 파싱조차 하지 않고, JS/TS는 ts-morph AST, HTML·SFC 마크업은 linkedom(JSX는 TypeScript AST), CSS는 cssomnom, 의존성은 package.json과 벤더링된 라이브러리 파일로 봅니다.
대신 규칙마다 verifierRubric(keepWhen/dropWhen)을 JSON으로 함께 내보내고, 오탐 제거는 그 코드베이스를 이미 보고 있는 코딩 에이전트에게 맡깁니다. 예컨대 기능 감지로 가드된 코드, 무관한 스코프에서 같은 이름으로 쓰인 식별자(오디오 엔진의 dialog 변수 같은), WebGL·Node CLI 같은 도메인 밖 코드는 dropWhen으로 걸러집니다. 오프라인 규칙 검증 단계에서는 같은 루브릭으로 llm-verifier.ts가 후보를 채점합니다. 각 발견에는 SHA256(repo:commit:guideId:file:line) 앞 12자리 ID가 붙어 반복 실행 간 추적이 됩니다.
이 설계는 “정적 분석은 문맥을 모른다”는 오래된 한계를 정면 돌파하지 않고 우회합니다. 규칙 작성자는 재현율에 집중하고, 정밀도는 문맥을 가진 쪽이 책임지게 하는 분업입니다. 대신 에이전트 없이 사람이 터미널 출력만 보고 일괄 수정하면 오탐을 그대로 고칠 위험이 있습니다. 스킬 지침도 “드롭한 발견과 유지한 폴백은 계속 정적 스캔에 걸린다, 0건을 만들려고 안전한 코드를 고치지 말라”고 못 박고 있습니다.
9. 평가 하네스: 가이드의 존재 이유를 숫자로
이 저장소의 진짜 차별점은 평가입니다. 흐름은 이렇습니다.
- 현실적 과제 — 실제 규모의 베이스 앱(
daily-grind,devtools-times)에 “이미지를 더 빨리 로드되게 해 줘” 같은 프롬프트를 줍니다. API·기능 이름은 일부러 언급하지 않아, 에이전트가 스스로 가이드를 찾아 적용하는지를 봅니다. - 보정된 그레이더 — Playwright 그레이더가 소스 패턴, 계산된 스타일, 런타임 DOM 동작, 접근성 상태를 검사합니다. 서로 다른 계열 에이전트 3종(Claude/Codex/AGY)의 골든 솔루션은 100% 통과, 손대지 않은 원본 앱은 0% 통과해야 보정 완료로 봅니다(보정 중 최대 5회 시도).
- 격리 — 에이전트는 임시
HOME과 OS 수준 샌드박스(리눅스bwrap, macOSsandbox-exec) 안에서 돌아 저장소 소스나 그레이더를 엿볼 수 없습니다. - E2E 비교 — 스킬 사용(guided)과 미사용(unguided) 통과율을 비교해 opportunity(100% − unguided)와 uplift(guided − unguided)를 계산합니다. 모델이 이미 잘하는 내용은 가이드에서 잘라 토큰을 아낍니다.
README의 최근 스냅샷(11월 8일 실행분)은 다음과 같습니다. 프로젝트 측이 자체 하네스로 잰 수치이며, 저는 재현하지 않았습니다.
| 에이전트 + 모델 | 과제 / 체크 | unguided → guided | uplift |
|---|---|---|---|
| antigravity_cli (gemini-4-argon) | 214 / 1,673 | 58% → 94% | +36pp |
| codex_cli (gpt-6.1-sol) | 215 / 1,795 | 54% → 82% | +28pp |
| claude_code (opus-5-5) | 215 / 1,801 | 57% → 88% | +31pp |
해석할 때 주의할 점이 있습니다. 첫째, 과제와 그레이더를 만든 쪽과 가이드를 만든 쪽이 같은 프로젝트라, 그레이더가 “가이드가 권하는 방식”을 정답으로 삼는 구조적 편향이 있습니다. expectations가 SME의 판단을 반영하므로 가이드를 따르면 점수가 오르는 것은 어느 정도 당연합니다. 둘째, 그래도 골든 3종·원본 0% 보정과 API 이름을 숨긴 프롬프트는 “에이전트가 그 기능을 스스로 떠올리지 못했다”는 신호로는 꽤 설득력이 있습니다. 셋째, 대시보드(googlechrome.github.io/modern-web-guidance-src)에 에이전트별·가이드별 세부가 공개돼 있어 우리 팀이 주로 쓰는 영역의 uplift만 따로 확인할 수 있습니다.
10. 핵심 설계 트레이드오프
| 결정 | 얻는 것 | 잃는 것 |
|---|---|---|
| 로컬 정적 임베딩 + BM25 | 키·서버 불필요, 프라이버시, 지연 극소, 공급망 단순화 | 영어 외 질의 취약, 교사 모델 대비 의미 이해 한계, 벡터 갱신은 릴리스 주기에 묶임 |
항상 npx …@latest |
가이드가 낡지 않음(0.0.x 시절 하루 두 번 꼴 배포) | 매 호출 네트워크 확인, 재현성 낮음 — 고정 버전이 필요하면 직접 핀을 걸어야 함 |
| 스킬 설명을 “MANDATORY: Execute FIRST”로 공격적으로 작성 | 에이전트의 활성화율 향상 | HTML/CSS가 조금만 섞여도 호출 — 툴 호출·토큰이 늘어남(백엔드·인프라 작업은 명시적 제외) |
최종 응답에 ### Modern Web Guidance 공개 섹션 강제 |
어떤 가이드가 코드에 영향을 줬는지 감사 가능 | 모든 프런트엔드 작업 응답에 고정 섹션이 붙음 — 팀 취향에 따라 소음 |
| 변동성·오리진 트라이얼 게이트 | 단일 엔진 API의 무분별한 채택 차단, 팀 단위 .mwgrc 정책 |
Built-in AI(Prompt API 등)처럼 실험하고 싶은 기능은 opt-in 전까지 가이드 없음 |
| legacy-scan 정밀도를 루브릭에 위임 | 규칙 작성 단순화, 다양한 프레임워크 대응 | 에이전트 없이 쓰면 오탐 관리 부담, 커버리지 ~20% |
11. 비슷한 도구와 비교
| 도구 | 무엇을 주나 | 동작 위치 | 강점 | Modern Web Guidance와의 관계 |
|---|---|---|---|---|
| Modern Web Guidance | SME가 쓴 웹 플랫폼 구현 가이드 + Baseline 폴백 + 레거시 스캔 | 로컬 CLI (스킬이 호출) | 효과 측정 루프, 브라우저 벤더 공동 관리, 키 불필요 | — |
| Context7 류 문서 MCP | 라이브러리·프레임워크의 버전별 공식 문서 조각 | 원격 서버/MCP | React·Next.js 등 서드파티 API 최신성 | 보완 관계 — MWG는 프레임워크 이름을 일부러 배제하고 “플랫폼 기본기”를 다룸 |
| eslint-plugin-compat + browserslist | 대상 브라우저에서 지원 안 되는 API 사용 경고 | 린터 | CI 강제 가능, 결정적 | 방향이 반대 — compat은 “너무 새 것”을, MWG는 “너무 낡은 것”을 잡음 |
| web-features / Baseline 데이터 직접 사용 | 기능별 브라우저 지원 상태 | 데이터 패키지 | 정확한 호환성 원천 데이터 | MWG가 빌드 타임에 이미 이 데이터를 가이드에 주입 |
| Chrome DevTools MCP | 에이전트가 실제 브라우저를 열어 디버깅·성능 측정 | MCP 서버 + 브라우저 | 런타임 검증 | 보완 관계 — 작성 전 지식(MWG)과 작성 후 검증(DevTools) |
| 범용 프런트엔드 스킬(디자인·UI 스킬 모음) | 스타일·디자인 원칙, 작업 절차 | SKILL.md | 미감·일관성 | MWG는 API 정확성과 폴백에 집중, 평가 근거가 수치로 공개됨 |
12. 주의할 점과 한계
| 항목 | 내용 | 대응 |
|---|---|---|
| 텔레메트리 기본 켜짐 | 설치 수, 호출 에이전트 이름, retrieve한 가이드 ID, 에이전트가 만든 검색 질의 수집(원 프롬프트는 미수집이라고 명시) | 사내 정책에 따라 DISABLE_TELEMETRY=1을 셸 프로필·CI·샌드박스 환경변수에 설정 |
| 네트워크·샌드박스 | 최초 npx 다운로드는 네트워크 필요. Codex·Claude Code 샌드박스에서는 승인 필요 |
허용 목록은 npx -y modern-web-guidance@latest *로 좁게, 오프라인이면 npx --offline, ~/.npm이 읽기 전용이면 NPM_CONFIG_CACHE=/tmp/npm-cache |
| Claude Code 공식 마켓플레이스 고착 | README에 따르면 claude-plugins-official 경유 설치는 10/12 이후 v0.0.194에서 업데이트가 멈춤 |
@claude-plugins-official 제거 후 googlechrome 마켓플레이스로 재설치, AutoUpdate 켜기 |
| 소스와 배포의 시차 | main의 새 규칙·가이드가 npm에 바로 반영되지 않음(실측: JS 규칙 미포함) | 문서보다 npx … --version과 실제 출력으로 확인 |
| 범위 | 바닐라 HTML/CSS/JS 기준. React·Vue 등은 에이전트가 번역해야 함 | 스킬 지침의 SSR 가드·useId()·ref 사용 규칙 참고 |
| 한국어 질의 | 실측상 빈 결과 | 사람이 쓸 때도 영어 키워드로 |
| 라이선스 이원화 | 코드는 Apache-2.0이지만 가이드 내용은 CC-BY 4.0 | 가이드 문구를 사내 문서·제품에 재사용하면 출처 표기 필요 |
13. 누가 도입하면 좋은가
| 상황 | 권장도 | 이유 |
|---|---|---|
| 에이전트로 프런트엔드 UI를 많이 만드는 팀 | 높음 | 모달·팝오버·폼·셀렉트·스크롤바 같은 “에이전트가 습관적으로 JS로 때우는” 영역이 정확히 가이드 커버리지 |
| 오래된 웹 코드베이스 현대화 | 중간~높음 | legacy-scan --json → 에이전트 검증 → retrieve → 재스캔 루프가 바로 쓸 만함. 단 커버리지 ~20% |
| 브라우저 지원 정책이 엄격한 B2B·공공 | 중간 | Baseline 기반 폴백 규칙은 유용하지만, AGENTS.md에 지원 정책을 명시해야 의도대로 동작 |
| 백엔드·인프라 위주 팀 | 낮음 | 스킬 스스로 백엔드·CI·Docker 작업에서는 트리거하지 말라고 규정 |
| 사내 가이드 스킬을 만들려는 플랫폼 팀 | 높음(참고용) | expectations → 보정 그레이더 → uplift 측정, 비대칭 로컬 검색, /tmp 스필링 등 설계를 그대로 차용할 가치 |
정리하면 Modern Web Guidance는 “에이전트용 문서”라기보다 에이전트용 지식을 제품처럼 만들고 측정하는 방법론에 가깝습니다. 당장 쓸 사람은 npx modern-web-guidance@latest install과 DISABLE_TELEMETRY=1 두 줄로 시작하면 되고, 자기 도메인의 스킬을 만드는 팀이라면 src/rag/와 docs/CONTEXT.md를 먼저 읽어 보시길 권합니다. 오늘 트렌딩 상위권에 오른 이유가 단순히 Google 이름값만은 아니라는 걸 코드가 보여 줍니다.