راهنمای عیب‌یابی وب مدرن

اگرچه هدف راهنمای وب مدرن، حرکت توسعه شما به سمت رویکردی «صحیح به طور پیش‌فرض» است، اما ممکن است گاهی اوقات با مشکلاتی در فعال‌سازی عامل، دقت پیاده‌سازی یا کشف ویژگی‌ها مواجه شوید. این بخش مراحل تشخیصی را برای کمک به شما در حل چالش‌های رایج ارائه می‌دهد، مانند اطمینان از اینکه مهارت وب مدرن به درستی توسط درخواست‌های شما فعال می‌شود یا تأیید اینکه کدهای جایگزین با وضعیت پایه تعیین‌شده پروژه شما همسو هستند. اگر با موانع فنی مداوم مواجه شدید یا راهنمایی‌های قدیمی را شناسایی کردید، شما را تشویق می‌کنیم تا یک مشکل را ثبت کنید تا به ما در دقیق و مؤثر نگه داشتن این منابع کمک کند.

تشخیص دهید که راهنمای وب مدرن توسط نماینده شما استفاده نمی‌شود

وقتی Modern Web Guidance نصب می‌شود، به کارگزاران دستور داده می‌شود که از آن برای هرگونه کار توسعه وب استفاده کنند. با این حال، کارگزاران گاهی اوقات این دستورالعمل‌ها را نادیده می‌گیرند.

شما می‌توانید با افزودن عبارتی مانند «use 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 مطالعه کنید . هنگام ایجاد مشکل، دستورالعمل‌های اولیه، تصاویر و گزارش‌های مربوط به روند فکری کاربر و تغییر کد نهایی توصیه شده بر اساس آن تفکر را ارائه دهید.