یک راهنمای شروع‌به‌کارِ خراب، سریع‌ترین راه برای دفع برنامه‌نویسان جدید از پروژه است. به همین دلیل در ۳ سپتامبر ۲۰۲۶، یک راهنمای فنی در پلتفرم dev.to منتشر شد که یک فرآیند ممیزی پنج‌مرحله‌ای را برای جلوگیری از تبدیل فایل‌های README قدیمی به مستنداتی صیقل‌خورده اما غلط معرفی می‌کند.
بسیاری از توسعه‌دهندگان اکنون برای اصلاح سریع مستندات از هوش مصنوعی استفاده می‌کنند. اما اگر یک مدل پیش از تأیید دستورات واقعی، متن README را بازنویسی کند، در واقع یک دروغ متقاعدکننده‌تر را منتشر می‌کند. این وضعیت شکافی خطرناک ایجاد می‌کند؛ جایی که مستندات ادعا می‌کنند دستوری مثل npm run dev وجود دارد، در حالی که مخزن پروژه فقط از npm run start پشتیبانی می‌کند.
برای حل این مشکل، گردش‌کار پیشنهادی با مدل زبانی بزرگ (LLM) — مثل کتابخانه‌داری که میلیاردها صفحه را خوانده و حالا با همان لحن کتاب‌ها جواب می‌دهد — نه به عنوان منبع حقیقت، بلکه به عنوان یک مهمان برخورد می‌کند. هسته این سیستم ابزاری پایتونی به نام readme_drift.py است که تضمین می‌کند هیچ مستنداتی به‌روز نمی‌شود مگر اینکه ادعاهای فنی آن از طریق اسکن فایل‌های محلی به اثبات برسد.
همان‌طور که در تحلیل‌های قبلی ما درباره‌ی مبنی‌سازی (Grounding) در مدل‌های زبانی اشاره کردیم، حذف توهمات نیازمند اتصال مدل به داده‌های مرجع است. در این سیستم، این اتصال از طریق پنج مرحله اجرا می‌شود:
مرحله ۱: استخراج ادعاها
این فرآیند به‌جای تکیه بر پرامپت، با یک تجزیه‌کننده (Parser) سخت‌گیرانه آغاز می‌شود. ابزار مذکور بلوک‌های کد (bash، sh یا shell) و توکن‌های متغیرهای محیطی را اسکن می‌کند. سیستم با نادیده گرفتن متون توصیفی و تمرکز روی بلوک‌های کد، از ورود به حوزه‌هایی که مدل‌های زبانی معمولاً دچار توهم (Hallucination) — شبیه دوستی که خاطره‌ای را اشتباه تعریف می‌کند — می‌شوند، اجتناب می‌کند.
مرحله ۲: موجودی‌برداری از مخزن
در مرحله دوم، یک فهرست واقعی از مخزن تهیه می‌شود. ابزار برای یافتن حقیقت پروژه، فایل‌های خاصی را اسکن می‌کند:
- package.json: استخراج تمام اسکریپت‌های npm موجود.
- Makefile: شناسایی تمام اهداف (Targets) معتبر Make.
- .env.example: فهرست کردن کلیدهای مورد نیاز متغیرهای محیطی.
مرحله ۳: گزارش انحراف (Drift Report)
سیستم سپس یک عملیات diff بین ادعاهای README و موجودی مخزن انجام می‌دهد و فایل drift_report.json را تولید می‌کند. طبق مستندات این ابزار، اگر README وعده دستوری مثل make bootstrap را بدهد که در Makefile وجود ندارد، آن ادعا «غلط» علامت‌گذاری می‌شود.
این مرحله به‌طور عمدی سخت‌گیرانه است. برای مثال، اگر README به درخواستی روی پورت ۳۰۰۰ اشاره کند اما فایل .env.example پورت ۸۰۸۸ را مشخص کرده باشد، سیستم آن را شکست می‌داند. این کار مانع از آن می‌شود که هوش مصنوعی برای «درست نشان دادن» مستندات، یک راهکار یا پروکسی خیالی ابداع کند.
مرحله ۴: بازنویسی مبنی‌شده توسط هوش مصنوعی
تنها پس از شناسایی انحراف است که مدل هوش مصنوعی وارد عمل می‌شود. مدل هرگز کل README را دریافت نمی‌کند؛ بلکه فقط ردیف‌های ok: false و موجودی واقعی فایل‌ها را می‌بیند.
با استفاده از ابزاری مثل MonkeyCode، مدل مأمور می‌شود جایگزین‌های مناسب را پیشنهاد دهد. این رویکرد در واقع تکامل‌یافته‌ی همان سیستم اعتبارسنجی چهار لایه‌ای است که MonkeyCode برای تبدیل مدل‌های رایگان به ابزارهای اصلاح کد به کار می‌گیرد. نکته حیاتی این است که این پیشنهادات باید بر اساس موجودی فایل‌ها باشد. اگر مدل دستوری را پیشنهاد دهد که در package.json یا Makefile نیست، یک تست قرارداد (Contract Test) به‌طور خودکار خروجی را رد می‌کند.
مرحله ۵: ادغام در CI
گام نهایی، تبدیل این طبقه‌بندی به یک گیت در CI (یکپارچه‌سازی مداوم) است. بیلد پروژه به‌گونه‌ای تنظیم می‌شود که اگر مقدار missing_count در گزارش انحراف بیشتر از صفر بود، عملیات شکست بخورد. این یعنی انحراف مستندات به‌جای یک ترجیح ظاهری، به عنوان یک باگ بحرانی (Breaking Bug) تلقی می‌شود. این سخت‌گیری برای جلوگیری از تکرار حفره‌های امنیتی رایجی است که در کدهای تولیدشده توسط AI دیده می‌شود و می‌تواند کل زیرساخت را به خطر اندازد.
این رویکرد نقش توسعه‌دهنده را از «مهندس پرامپت» به «تأییدکننده» تغییر می‌دهد. با مجبور کردن هوش مصنوعی به کار در یک ساختار محدود JSON، خطر ورود باگ‌های نامرئی به فرآیند آنبوردینگ حذف می‌شود.
برای شما به عنوان کاربر، این به معنای تغییر بنیادین در نگهداری پروژه است. به‌جای اعتماد به مدل برای «اصلاح مستندات»، شما در حال پیاده‌سازی یک مجموعه تست (Test Suite) برای مستندات خود هستید. این کار جلویe سرخوردگی رایجی را می‌گیرد که پس از کلون کردن یک مخزن، متوجه می‌شوید پنج دستور اول راهنما منسوخ شده‌اند.
به گزارش نویسندگان این متد، اگرچه سیستم دستورات را اجرا نمی‌کند — یعنی یک دستور موجود ممکن است همچنان کرش کند — اما تضمین می‌کند که دستور حداقل وجود دارد. این روش مشکل «انحراف» را با تبدیل مستندات به مشتقی از کد حل می‌کند، نه یک موجودیت جداگانه که به‌مرور فاصله می‌گیرد.
برای پیاده‌سازی این سیستم، به پایتون ۳.۱۱ به بالا و مخزنی با بلوک‌های کد استاندارد در README نیاز دارید. مراحل اولیه ممیزی به هیچ حساب ابری نیاز ندارند و به راحتی در گردش‌کار محلی توسعه قرار می‌گیرند.
گام بعدی شما
- بررسی فایل‌های
package.jsonوMakefileپروژه خود برای شناسایی تضادهای احتمالی با README. - پیاده‌سازی یک اسکریپت ساده پایتون برای تطبیق دستورات ذکر شده در مستندات با فایل‌های پیکربندی.
- تعریف یک قانون در CI برای جلوگیری از ادغام (Merge) کدهایی که مستندات آن‌ها به‌روز نیست.
اما داستان سخت‌افزاری این تحول حتی شگفت‌انگیزتر است — به تحلیل ما درباره‌ی تراشه‌های Blackwell مراجعه کنید.
گفتگو