פתרון בעיות שקשורות להנחיות לגבי אתרים מודרניים

ההנחיות לגבי אתרים מודרניים נועדו לעזור לכם לפתח אתרים בגישה של 'נכון כברירת מחדל', אבל יכול להיות שתיתקלו מדי פעם בבעיות בהפעלת הסוכן, בדיוק ההטמעה או בגילוי תכונות. בקטע הזה מפורטים שלבי אבחון שיעזרו לכם לפתור בעיות נפוצות, כמו לוודא שההנחיות שלכם מפעילות את המיומנות 'אינטרנט מודרני' בצורה תקינה, או לוודא שהקודים החלופיים תואמים לסטטוס הבסיסי שנקבע בפרויקט. אם נתקלתם בבעיות טכניות חוזרות או זיהיתם הנחיות לא עדכניות, מומלץ לשלוח לנו דיווח על בעיה כדי לעזור לנו לשמור על הדיוק והיעילות של מקורות המידע האלה.

אבחון של בעיה שבה הסוכן לא מזהה מיומנות מודרנית לאינטרנט

כל הנחיה שהתקינה את תוסף המיומנות אמורה להפעיל אותו על ידי הכללת השימוש ב'הנחיות מודרניות לאינטרנט' בצורה כלשהי, אבל אם מסיבה כלשהי יש קושי עם הסוכן שבו אתם משתמשים, אתם יכולים להפעיל אותו ישירות כך:

/modern-web-guidance <your prompt>

ההגדרה הזו רלוונטית לסביבות פיתוח משולבות (IDE) מבוססות-AI שמקבלות את npx skills add <skill-extension>.

אבחון של קוד שנוצר על ידי AI גנרטיבי או של הטמעות משוערות

זהו מקרה נפוץ שבו מודל 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 פורסם לאחרונה, יכול להיות שלא יהיה לסוכן חלופה מקבילה להסתמך עליה, או שמדובר בתכונה שזמינה ב-Baseline Widely מספיק זמן, כך שחלופות או polyfills לא נדרשים.

אבחון הטיה בנתוני אימון לא עדכניים

אם הסוכן מציע ספרייה ישנה במקום API של דפדפן מודרני, סביר להניח שהוא מסתמך על נתוני האימון הבסיסיים שלו או שסטטוס הבסיס שלכם מוגדר כך שעדיין לא תהיה תמיכה בתכונה הזו, והגיבוי הופעל.

כדי לוודא, אפשר לחפש במפורש בספריית ההנחיות באמצעות ה-CLI כדי לאלץ את המיומנות לקבל עדיפות:

# Search for a specific feature
npx modern-web-guidance search "<feature>"

אבחון הנחיות לא עדכניות

חשוב מאוד שהמידע שלנו יהיה עדכני, ולכן נבקש ממך לדווח על בעיה במאגר אם תמצא קוד שהוטמע מתוך מדריך ולא היה עדכני. במהלך השימוש, חשוב לאסוף הוכחות לכך שההמלצות של הסוכן מגיעות מmodern-web המיומנות והמדריכים שלה ולא מנתוני האימון הבסיסיים של מודל ה-LLM שסביבת ה-IDE מבוססת ה-AI שלכם עשויה להשתמש בהם.

יכול להיות שתוכלו לעקוב אחרי תהליך החשיבה של הסוכן בחלון או במסוף שלו, אבל אתם יכולים גם לבקש ממנו להסביר איך הוא הגיע למסקנה לגבי שינוי הקוד. אחרי שתגיעו למסקנה שהתגובה אכן נוצרה על ידי המיומנות, תוכלו להעביר לנו את המשוב והראיות.

משוב

אם יש לכם שאלות נוספות או משוב על התכונות החדשות האלה, כדאי קודם לקרוא איך אפשר לתרום ל-Modern Web Guidance לפני שפותחים בעיה במאגר Github שלנו. כשיוצרים את הבעיה, צריך לספק את ההנחיות הראשוניות לסוכן, צילומי מסך ויומנים של תהליך החשיבה של הסוכן, ואת השינוי הסופי בקוד שמומלץ על סמך תהליך החשיבה הזה.