مستندسازی از یک سایت زنده
از lore:site-to-doc برای مستندسازی اینکه محصول امروز واقعاً چطور رفتار می‌کند استفاده کنید، با مشاهده‌ی آن در یک مرورگر واقعی.
lore:site-to-doc <product-url>
پیش‌نیاز: یک مرورگر
این اسکیل یک مرورگر واقعی را از طریق سرور Playwright MCP هدایت می‌کند. یک‌بار اضافه‌اش کنید:
claude mcp add playwright -- npx @playwright/mcp@latest
یک اجرا چطور کار می‌کند
-
پیش‌پرواز. در دسترس‌بودن ابزارهای مرورگر را تأیید می‌کند، یک‌بار می‌پرسد که چطور اجرا شود (تأیید هر مرحله، یا اجرای بی‌وقفه)، مشخص می‌کند کدام مسیرها و فیچرها کاوش شوند، و یک‌بار می‌پرسد که آیا نمای ریسپانسیو هم مستند شود (موبایل ۳۹۰×۸۴۴، تبلت ۷۶۸×۱۰۲۴، یا هر دو). این آخری اختیاری است، چون هر viewport اضافه یک پاس مرورگر جداگانه است. منابع مورد اعتماد پیکربندی‌شده را هم برای مطالب مربوط به مسیرهای در محدوده جست‌وجو می‌کند، چون مشاهده‌ی زنده برای رفتار مرجع است اما منابع مورد اعتماد قواعدی را پر می‌کنند که UI به زبان نمی‌آورد؛ و یافته‌های هر منبع را در یک سرشماری منبع قابل حسابرسی ثبت می‌کند، که هر سطرش رسید پشتش را همراه دارد. هر چیزی که در گفت‌وگو خواسته‌اید («نمای واردشده را هم پوشش بده») پیش از شروع مرور همین‌جا به‌صورت یک سطر شماره‌دار نوشته می‌شود، و تا وقتی یکی از آن‌ها باز باشد اجرا تحویل نمی‌شود.
اگر فیچری به ورود نیاز داشته باشد، یک‌بار در مرورگر headed وارد می‌شوید و نشست باقی می‌ماند. هر وضعیت احراز هویت را یک محصول متفاوت بدانید، نه مانعی که باید از آن گذشت: نمای مهمان یک محصول احرازشده همان چیزی است که هر کاربر تازه اول می‌بیند، و پروفایل ماندگار مرورگر در اجراهای بعدی بی‌صدا پنهانش می‌کند. اینکه واقعاً به کدام وضعیت‌ها رسیده‌اید (وضعیت احراز × نقش × مسیر × viewport، هر کدام پشتوانه‌ی یک اسکرین‌شات) به‌صورت یک ماتریس مشاهده ثبت می‌شود، تا اجرایی که فقط مهمان را دیده همان‌طور پیدا باشد، نه ضمنی.
-
اسکریپت‌های سناریو. هر فیچر یک سناریوی کوچک و قابل اجرای مجدد می‌گیرد: فهرستی از مراحل که هر کدام یک اقدام، یک نام اسکرین‌شات، و در صورت نیاز متنی برای انتظار دارند. این‌ها آرتیفکت‌های داخلی‌اند و هرگز در مستندات منتشرشده ظاهر نمی‌شوند.
-
اتوماسیون مرورگر. کار سنگین مرور به ساب‌اجنت
lore:site-explorerواگذار می‌شود، که مراحل را اجرا می‌کند، متن دقیق رابط کاربری را از snapshot دسترس‌پذیری می‌خواند، اسکرین‌شات‌های قطعی می‌گیرد و یک خلاصه‌ی فشرده برمی‌گرداند. وقتی همه‌ی پاس‌ها تمام شد، اسکرین‌شات‌ها یکجا فشرده می‌شوند: معمولاً حدود ۷۰٪ کوچک‌تر با همان ابعاد و بدون تفاوت قابل‌دیدن. اسکرین‌شات‌ها در ریپازیتوری شما کامیت و توسط سایتتان سرو می‌شوند، پس آن حجم همین‌جا پس گرفته می‌شود؛ ابزار فشرده‌سازی به‌جای عبور از کف کیفیت، فایل را دست‌نخورده می‌گذارد، و ماشینی که هیچ بهینه‌ساز تصویری روی آن نصب نیست همین را به شما می‌گوید، نه صرفه‌جویی‌ای که هرگز رخ نداده. -
اعتبارسنجی و گزارش.
پوشش نظام‌مند
هر فیچر در چهار بُعد آزموده می‌شود:
- مسیر موفق: سفر موفق سرتاسری.
- خطاهای اعتبارسنجی: فیلدهای خالی، داده‌ی نامعتبر، فایل‌های بیش از حد بزرگ؛ متن دقیق خطا ثبت می‌شود.
- حالت‌های مرزی: بر اساس تاکسونومی حالت‌های مرزی قالب مستندسازی، تقریباً به ترتیب فراوانی نقص. هر حد با یک پروب سه‌مقداری آزموده می‌شود (کمی زیر، روی حد، کمی بالا؛ مثلاً ۹۹ و ۱۰۰ و ۱۰۱)، و گذارهای وضعیت هم تمرین می‌شوند (دکمه‌ی بازگشت وسط فلو، ورود مستقیم URL به یک وضعیت میانی)، در کنار حالت‌های خالی و خطاهای شبکه.
- نقش‌ها و دسترسی‌ها: اینکه نمای هر نقش و دسترسی‌اش چطور فرق می‌کند.
یک QAی رایگان در کنارش
مستندسازی یک محصول زنده، نقص‌های واقعی را آشکار می‌کند. ناهم‌خوانی‌های میان طراحی یا بریف و رفتار واقعی علامت‌گذاری می‌شوند، و نقص‌های واقعی محصول در پیش‌نویس‌های ساختارمند باگ (عنوان، شدت، گام‌های بازتولید، اسکرین‌شات) جمع می‌شوند. به‌اختیار می‌توانید آن‌ها را به‌شکل ایشوهای گیت‌هاب ثبت کنید؛ پیش‌فرض، پیش‌نویس روی دیسک است.
قطعی به‌طراحی
اسکرین‌شات‌ها از یک viewport ثابت (پیش‌فرض ۱۲۸۰×۷۲۰، یا یک پریست موبایل و تبلت وقتی نمای ریسپانسیو را انتخاب کنید) و انتظارهای پایدار استفاده می‌کنند، نه sleepهای ثابت، تا تصاویر سازگار و قابل‌مقایسه باشند. وقتی پاس ریسپانسیو اجرا شود، سناریو در viewport کوچک‌تر بازاجرا می‌شود و فقط تفاوت‌ها در یک بخش نمای موبایل و تبلت ثبت می‌شوند (اسکرین‌شات‌های موبایل با نصف عرض نمایش داده می‌شوند). متن رابط کاربری از درخت دسترس‌پذیری خوانده می‌شود، نه از پیکسل‌ها، که هم دقیق است هم کم‌هزینه.