최신 웹 가이드는 개발을 '기본적으로 올바른' 접근 방식으로 전환하는 것을 목표로 하지만, 에이전트 활성화, 구현 정확성 또는 기능 검색과 관련된 문제가 가끔 발생할 수 있습니다. 이 섹션에서는 프롬프트에 의해 Modern Web 스킬이 올바르게 트리거되는지 확인하거나 코드 대체가 프로젝트의 설정된 기준 상태와 일치하는지 확인하는 등 일반적인 문제를 해결하는 데 도움이 되는 진단 단계를 제공합니다. 지속적인 기술적 장애물이 발생하거나 오래된 안내를 발견한 경우 이러한 리소스의 정확성과 효과를 유지할 수 있도록 문제를 신고해 주시기 바랍니다.
에이전트에서 Modern Web Guidance를 사용하지 않는 문제 진단
Modern Web Guidance가 설치되면 상담사는 모든 웹 개발 작업에 이를 사용하라는 안내를 받습니다. 하지만 상담사가 이러한 안내를 무시하는 경우가 있습니다.
프롬프트 끝에 'use modern-web-guidance'와 같은 문구를 추가하여 상담사에게 최신 웹 안내를 사용하도록 명시적으로 지시할 수 있습니다.
일부 에이전트는 에이전트에 따라 /modern-web-guidance 또는 $modern-web-guidance과 같은 특정 구문을 사용하여 스킬을 직접 호출하는 것도 지원합니다.
확실하지 않은 경우 에이전트의 문서를 참고하거나 에이전트에게 modern-web-guidance 스킬을 직접 호출하는 방법을 문의하세요.
'환각' 코드 또는 추측된 구현 진단
이는 LLM이 경고 없이 지식 격차를 채우는 경우에 흔히 발생합니다. 에이전트가 정보를 만들어 내지 않도록 하려면 프롬프트에 다음 안내를 추가하는 것이 매우 유용합니다.
Bring up knowledge gaps and don't attempt to guess implementation. List them as open questions.
특정 안내 트리거 실패 진단
특정 기능 사용 사례를 타겟팅하고 있는데 에이전트가 이를 검색하지 못하는 경우, 프롬프트에 적절한 검색 가능성을 위한 특정 키워드와 앵커 요구사항이 포함되어 있는지 확인하세요. 이를 통해 상담사는 관련 안내 트랙 (예: '전환 보기', 'LCP 최적화')을 식별할 수 있습니다.
에이전트의 사고 과정을 추적합니다.
- 출력을 확인하여
modern-web-guidance스킬이 호출되었는지 확인합니다. - 검색 호출(예:
npx -y modern-web-guidance@latest search "carousel scroll snap")을 찾아 키워드와 결과 가이드가 예상한 것인지 확인합니다. - 검색 호출에서 관련 가이드(예:
npx -y modern-web-guidance@latest retrieve "carousel-snap-highlights,carousel-slide-effects,scroll-snap-state-sync")를 요청했는지 확인합니다.
Create a new folder and create a carousel web app for me that implements scroll-snap.
...
● Bash(npx -y modern-web-guidance@latest search "carousel scroll snap" --skill-version 2026_05_16-c5e7870)
⎿ [{"id":"carousel-snap-highlights","description":"Visually highlight the currently snapped non-interactive item in scroll-snapping carousels, galleries, or full-page swipe experiences. For example, expanding a card when snapped, or revealing hidden
content.","category":"user-experience","featuresUsed":["Container scroll-state queries"],"tokenCount":1442,"similarity":0.7783},
{"id":"carousel-slide-effects","description":"Create a carousel of slides with images or other visual elements, where each slide animates as they enter/center/exit their scroller. For example, the slides may fade-in/fade-out, rotate, get bigger or smaller,
etc.","category":"user-experience","featuresUsed":["Scroll-driven animations","Scroll snap"],"tokenCount":2105,"similarity":0.6625},
{"id":"scroll-snap-state-sync","description":"Synchronize navigation indicators, linked content panels, and analytics tracking with the actively snapped item in a scrollable container.","category":"user-experience","featuresUsed":["Scroll snap events","Scroll
snap"],"tokenCount":1053,"similarity":0.6166},
{"id":"scroll-snap-realtime-feedback","description":"Provide real-time visual feedback in linked UI elements while a user scrolls through snap-aligned content, before the scroll gesture completes.","category":"user-experience","featuresUsed":["Scroll snap events","Scroll
snap"],"tokenCount":1886,"similarity":0.5664},
{"id":"navigation-drawer","description":"Create a navigation drawer component that, when triggered from a menu button, slides in from the side overlayed on top of existing page content, and slides out when dismissed (by swiping away, tapping outside, or pressing
escape).","category":"user-experience","featuresUsed":["inert","Intersection observer","Popover","Registered custom properties","Scroll-driven animations","scroll-initial-target","Scroll snap"],"tokenCount":4317,"similarity":0.5099}]
● Bash(npx -y modern-web-guidance@latest retrieve "carousel-snap-highlights,carousel-slide-effects,scroll-snap-state-sync")
⎿ <output +158 lines>
}, undefined);
if (topEntry) setSelectedParagraph(topEntry.id);
},
{ root: main, threshold: 0.9 // Adjust based on your use case },
);
// Observe all snap targets (e.g., section headers)
document.querySelectorAll('h2').forEach(header => observer.observe(header));
}
- 터미널에서 검색 명령어를 직접 실행하여 검색어와 일치하는 가이드를 확인할 수도 있습니다.
# Search for relevant guides
npx modern-web-guidance@latest search "carousel scroll snap"
의견
이러한 새로운 기능에 관해 추가 질문이나 의견이 있는 경우 GitHub 저장소에 문제를 신고하기 전에 먼저 Modern Web Guidance에 참여하는 방법을 읽어보세요. 문제를 생성할 때 초기 에이전트 프롬프트, 에이전트의 사고 과정 스크린샷과 로그, 해당 사고에 기반한 최종 코드 변경사항을 제공하세요.