최신 웹 가이드는 개발을 '기본적으로 올바른' 접근 방식으로 전환하는 것을 목표로 하지만, 에이전트 활성화, 구현 정확성 또는 기능 검색과 관련된 문제가 가끔 발생할 수 있습니다. 이 섹션에서는 프롬프트에 의해 Modern Web 기능이 올바르게 트리거되는지 확인하거나 코드 대체가 프로젝트의 설정된 기준 상태와 일치하는지 확인하는 등 일반적인 문제를 해결하는 데 도움이 되는 진단 단계를 제공합니다. 지속적인 기술적 장애물이 발생하거나 오래된 안내를 발견한 경우 이러한 리소스의 정확성과 효과를 유지할 수 있도록 문제를 신고해 주시기 바랍니다.
에이전트가 최신 웹 기술을 인식하지 못하는 문제 진단
스킬 확장 프로그램을 설치한 프롬프트는 어떤 방식으로든 '최신 웹 안내'를 포함하여 활성화할 수 있어야 하지만, 어떤 이유로든 사용 중인 에이전트가 어려움을 겪는 경우 다음과 같이 직접 호출할 수 있습니다.
/modern-web-guidance <your prompt>
이는 npx skills add <skill-extension>를 허용하는 AI 기반 IDE에 적용됩니다.
'환각' 코드 또는 추측된 구현 진단
LLM 모델이 경고 없이 지식 격차를 메우는 것은 흔한 일입니다. 에이전트가 정보를 만들어 내지 않도록 하려면 프롬프트에 다음 안내를 추가하는 것이 매우 유용합니다.
Bring up knowledge gaps and don't attempt to guess implementation. List them as open questions."
특정 안내 트리거 실패 진단
특정 기능 사용 사례를 타겟팅하고 있는데 에이전트가 이를 검색하지 못하는 경우, 프롬프트에 적절한 검색 가능성을 위한 특정 키워드와 앵커 요구사항이 포함되어 있는지 확인하세요. 이를 통해 상담사는 관련 안내 트랙 (예: '전환 보기', 'LCP 최적화')을 식별할 수 있습니다.
/modern-web-guidance Execute LCP optimization against my Progressive Web App.
에이전트의 사고 과정을 추적합니다.
- 최신 웹 가이드 기능 (예:
modern-web/SKILL.md)이 발견된 경우 따릅니다. - 검색 호출(예:
node modern-web.mjs search "scroll snap")을 찾아 키워드와 결과 가이드가 예상한 것인지 확인합니다. 검색 결과에서 가장 위에 있는 가이드가 프롬프트에 적용되도록 선택된 가이드입니다.
/modern-web-guidance Create a new folder and create a carousel web app for me that implements scroll-snap.
...
● Bash(node --experimental-strip-types serving/bin/modern-web.ts search "carousel scroll-snap")
⎿ [{"id":"carousel-item-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"]},
{"id":"light-dismiss-content-overlay","description":"Create swipeable layered navigation menus using native overlays and scroll gestures.","category":"user-experience","featuresUsed":["Popover","Scroll snap","inert"]},
{"id":"scroll-target-on-load","description":"Build a scrollable list of elements (e.g. a carousel of images or a chat conversation thread) that can be displayed with a particular element scrolled into view on the initial render.","category":"user-experience","featuresUsed":["scroll-initial-target","scrollIntoView()"]},
{"id":"parallax-scroll-effects","description":"Create scroll-based effects (such as parallax) where foreground and background layers move at different rates, creating a sense
of depth as the user scrolls.","category":"user-experience","featuresUsed":["Scroll-driven animations"]},
{"id":"pull-to-reveal","description":"Build a pull-to-reveal feature that would enable the user to pull down on the screen to reveal more content, like a search bar.", "category":"user-experience","featuresUsed":["scroll-initial-target","Scroll snap"]}]
...
▾ Thought for 1s
Ah, let's look at the actual folder names under `guides/user-experience/` that we listed earlier to find the exact ID mapping.
Let's see the folders we found earlier:
- `carousel-slide-effects`
- `carousel-snap-highlights`
- `scroll-snap-realtime-feedback`
- `scroll-snap-state-sync`
Ah! The ID in the filesystem is `carousel-slide-effects`, while the search index returns `carousel-item-effects`.
- 관련 가이드에 대한 검색 명령어를 직접 실행합니다.
# Search for relevant guides
npx modern-web-guidance@latest search "scroll snap"
특정 웹브라우저 기능의 누락된 대체 진단
이는 프로젝트 내에서 설정한 기준 상태를 기반으로 합니다. API가 최근에 출시된 경우 에이전트가 의존할 수 있는 동등한 대체가 없을 수 있습니다. 또는 대체 또는 폴리필이 필요하지 않을 만큼 오랫동안 '광범위한 기준'으로 제공된 기능일 수 있습니다.
오래된 학습 데이터 편향 진단
에이전트가 최신 브라우저 API 대신 이전 라이브러리를 제안하는 경우 기본 학습 데이터를 사용하거나 기준 상태가 아직 해당 기능을 지원하지 않도록 구성되어 대체가 구현되었을 수 있습니다.
다시 한번 확인하려면 CLI를 사용하여 안내 라이브러리를 명시적으로 검색하여 기능이 우선하도록 강제할 수 있습니다.
# Search for a specific feature
npx modern-web-guidance search "<feature>"
오래된 안내 진단
정보가 최신 상태로 유지되는 것이 가장 중요하므로 가이드에서 구현된 코드가 오래된 경우 저장소에 문제를 신고해 주시기 바랍니다. 이때 에이전트가 추천하는 내용이 AI 기반 IDE에서 사용할 수 있는 LLM 모델의 기본 학습 데이터가 아닌 modern-web 스킬 및 가이드에서 비롯된 것임을 입증하는 증거를 수집하세요.
에이전트 창이나 터미널에서 에이전트의 사고 과정을 추적할 수 있지만, 코드 변경 결론에 도달한 방법을 알려 달라고 요청할 수도 있습니다. 스킬에서 제공된 것이 확실하다고 판단되면 해당 의견과 증거를 Google에 전달하세요.
의견
이러한 새로운 기능에 관해 추가 질문이나 의견이 있는 경우 먼저 최신 웹 가이드에 참여하는 방법을 읽은 후 GitHub 저장소에 문제를 신고하세요. 문제를 생성할 때 초기 에이전트 프롬프트, 에이전트 사고 과정의 스크린샷과 로그, 해당 에이전트 사고에 기반한 최종 코드 변경사항을 제공합니다.