최신 웹 안내 문제 해결

Modern Web Guidance는 개발을 '기본적으로 올바른' 접근 방식으로 전환하는 것을 목표로 하지만, 에이전트 활성화, 구현 정확성 또는 기능 검색과 관련된 문제가 발생할 수 있습니다. 이 섹션에서는 프롬프트에 의해 Modern Web 기술이 올바르게 트리거되는지 확인하거나 코드 대체가 프로젝트의 설정된 기준 상태와 일치하는지 확인하는 등 일반적인 문제를 해결하는 데 도움이 되는 진단 단계를 제공합니다. 지속적인 기술적 장애가 발생하거나 오래된 가이드를 발견한 경우 문제를 신고하여 이러한 리소스가 정확하고 효과적으로 유지되도록 도와주세요.

에이전트에서 사용하지 않는 Modern Web Guidance 진단

Modern Web Guidance가 설치되면 에이전트는 웹 개발 작업에 이를 사용하도록 지시받습니다. 하지만 상담사가 이러한 안내를 무시하는 경우가 있습니다.

프롬프트 끝에 'modern-web-guidance 사용'과 같은 문구를 추가하여 에이전트가 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"

의견

이러한 새로운 기능에 관해 추가 질문이나 의견이 있는 경우 먼저 Modern Web Guidance에 기여하는 방법을 읽어본 후 GitHub 저장소에 문제를 제출하세요. 문제를 만드는 동안 초기 에이전트 프롬프트, 에이전트의 사고 과정에 대한 스크린샷 및 로그, 해당 사고를 기반으로 권장되는 최종 코드 변경사항을 제공합니다.