«تبدیل نویسنده به کامپایلر»؛ راهکاری برای پایان توهمات مستندات فنی

تصور کنید یک برنامه‌نویس ساعت‌ها وقت صرف پیاده‌سازی قابلیتی کند که در مستندات API آن، با اطمینان کامل نوشته شده «همیشه در محیط عملیاتی ایمن است»، اما در واقعیت هیچ تست یا کدی چنین تضمینی نمی‌دهد. این شکاف میان «لحن حرفه‌ای» و «واقعیت فنی»، بزرگ‌ترین نقطه ضعف مستندات تولیدشده توسط هوش مصنوعی است. طبق پیشنهادی که MonkeyCode در ۵ سپتامبر ۲۰۲۶ منتشر کرد، مدل‌های زبانی وقتی از یک پرامپت خالی شروع به نوشتن می‌کنند، تمایل دارند تضمین‌های باورپذیر اما دروغین را در جداول پارامترها بگنجانند. نتیجه این است که صفحه مستندات کامل به نظر می‌رسد، اما قرارداد فنی زیربنایی آن صرفاً یک حدس است.

بسیاری از تیم‌های مهندسی در حال حاضر با مدل زبانی بزرگ (LLM) — مثل کتابخانه‌داری که میلیاردها صفحه را خوانده و حالا با همان لحن کتاب‌ها جواب می‌دهد — به‌گونه‌ای برخورد می‌کنند که گویی نویسنده‌ای است که خلأهای دانشی را پر می‌کند. این رویکرد، بازبینی مستندات را به یک عملیات باستان‌شناسی خطرناک تبدیل می‌کند؛ جایی که بازبین باید به دنبال صفت‌هایی مثل «Production-safe» یا «Always» بگردد که هیچ کدی در لایه‌های زیرین آن‌ها را پشتیبانی نمی‌کند. راهکار پیشنهادی این است که نقش مدل از «نویسنده» به «کامپایلر» تغییر کند؛ یعنی مستندات را به‌عنوان یک مرحله کامپایل روی حقایق استخراج‌شده ببیند و نویسندگی را فقط برای «تعهدات انسانی» رزرو کند. این رویکرد تکامل‌یافته‌ای از متدولوژی‌های پیشین است که در آن MonkeyCode با گیت‌های انسانی تلاش کرد توقف توهمات در مستندات فنی را اتوماتیک کند.

تفکیک حقیقت از تعهد

هسته اصلی این متدولوژی، یک طبقه‌بندی دوتایی سخت‌گیرانه از اطلاعات است. در این دیدگاه، اطلاعات به دو دسته تقسیم می‌شوند: «حقایق» که شناسه‌های ماشین‌خوان هستند و یک پارسر می‌تواند آن‌ها را از مخزن کد استخراج کند، و «تعهدات» که ادعاهای حساس و پرمخاطره‌ای هستند و برای تایید به یک انسان مسئول (Owner) نیاز دارند. این تفکیک دقیق، شباهت زیادی به ساختار دفتر کل پیامدها دارد که راهکاری برای توقف خطاهای خاموش هوش مصنوعی در مستندات فنی ارائه داده بود.

حقایق استخراج‌شده (Extractable Facts): این‌ها شامل عملیات OpenAPI، ویژگی‌های JSON Schema، فیلدهای protobuf، فلگ‌های CLI و متغیرهای محیطی است که مستقیماً از کد پارس می‌شوند. این دسته شامل مواردی چون کدهای وضعیت (Status Codes)، فیلدهای اجباری و نام فلگ‌ها است.

تعهدات انسانی (Human Promises): این‌ها مواردی مثل منطق معماری، زمان‌بندی‌های مهاجرت، ساعات پشتیبانی و راهنمای «چه زمانی از این ابزار استفاده نکنید» هستند. ادعاهایی مانند «پشتیبانی شده است»، «تلاش مجدد (Retry) ایمن است» و «باعث شکست فراخوان‌کننده‌ها نخواهد شد» در این دسته قرار می‌گیرند.

به نقل از راهنمای MonkeyCode، اگر این دو دسته در یک پرامپت مشترک قرار بگیرند، مستندات نهایی تبدیل به «حدسی در قالب یک قرارداد» می‌شود. استعاره‌ی کامپایلر تضمین می‌کند که این دو دسته پیش از نوشتن حتی یک خط Markdown، کاملاً از هم جدا بمانند. در این مدل، درخت مستندات به عنوان گرافی از گره‌ها در نظر گرفته می‌شود؛ هر گره تولیدشده باید به یک شناسه منبع ماشین‌خوان اشاره کند، در غیر این صورت مرحله کامپایل باید از تولید آن فایل خودداری کند.

قوانین طبقه‌بندی

برای جلوگیری از نفوذ SLAهای ساختگی به صفحات مختلط، این راهنما یک قانون عملیاتی را پیشنهاد می‌کند که برای هر فایل به‌طور مجزا اعمال می‌شود:

• ارجاعات به End-pointها: (ورودی‌ها: operationId، مسیر، فعل HTTP، فیلدهای اجباری). مدل فقط می‌تواند از استخراج‌ها پیش‌نویس بنویسد. ادغام نهایی و مثال‌هایی که به Tenantهای واقعی متصل می‌شوند، بر عهده انسان است.
• کاتالوگ خطاها: (ورودی‌ها: کدهای وضعیت مستند شده و نام‌های اسکیما). مدل می‌تواند کدها را لیست کند، اما یک انسان باید تصمیم بگیرد که آیا یک کد باید برای کاربر نهایی نمایش داده شود یا خیر.
• ارجاعات به فلگ‌ها و متغیرهای محیطی: (ورودی‌ها: نام‌های argparse، کلیدهای os.environ). مدل می‌تواند نام‌ها و انواع داده را پیش‌نویس کند، اما سیاست پیش‌فرض محیط عملیاتی (Production) بر عهده انسان است.
• یادداشت‌های تغییرات شکست‌دهنده (Breaking-change): (ورودی‌ها: Diff بین دو نسخه اسکیما). مدل می‌تواند لیستی از کاندیداها را پیشنهاد دهد، اما انسان باید طبقه‌بندی کند که آیا تغییر «شکست‌دهنده» است یا «افزایشی».
• پشتیبانی، SLA و امنیت: هیچ پارسری نمی‌تواند این موارد را از مخزن کد ثابت کند. بنابراین، کل صفحه باید تحت مالکیت و مسئولیت انسان باشد.
• زمان‌بندی‌های Deprecation: مگر در صورتی که یک حاشیه‌نویسی (Annotation) تاریخ‌دار در منبع کد وجود داشته باشد، این موارد (شامل تقویم، مخاطبان و جایگزین‌ها) بر عهده انسان است.

خط لوله کامپایل پنج‌مرحله‌ای

گردش کار پیشنهادی به صورت یک خط لوله متوالی عمل می‌کند که نادیده گرفتن هر یک از مراحل آن، مشکل «پرامپت خالی» اولیه را بازتولید می‌کند.

اول، سیستم حقایق را در یک دایرکتوری موقت (Stub) استخراج می‌کند. این مرحله OpenAPI، JSON Schema یا خروجی --help را به رکوردهای JSON تبدیل می‌کند که فقط شامل نام‌ها، انواع، فلگ‌های اجباری و مقادیر شمارشی (Enumerated) است. نکته حیاتی این است که سیستم هرگونه توصیف قبلی که توسط مدل نوشته شده را نادیده می‌گیرد تا از ایجاد حلقه‌های بازخورد (Feedback Loops) جلوگیری شود.

دوم، خط لوله هر رکورد را طبقه‌بندی می‌کند. رکوردهای «قابل پیش‌نویس» آن‌هایی هستند که یک شناسه پشتیبانی‌شده توسط پارسر دارند. رکوردهای «فقط انسانی» به عنوان تعهدات، زمان‌بندی‌ها یا توصیه‌های مخاطبان تعیین می‌شوند، حتی اگر در همان صفحه‌ای باشند که یک End-point قرار دارد.

سوم، مدل رکوردهای قابل پیش‌نویس را به Markdown محدود تبدیل می‌کند. پرامپت در اینجا به‌طور عمدی «خصمانه» نسبت به کامل‌گرایی طراحی شده است؛ یعنی مدل را از اضافه کردن کدهای وضعیت، مقادیر پیش‌فرض یا تضمین‌هایی که در داده‌های اولیه (Stub) نیست، منع می‌کند. مدل فقط مجاز است جملات را بازآرایی کند و نام فیلدها را به تعاریف کوتاه تبدیل نماید.

چهارم، یک «Linter تعهدات» پیش‌نویس را برای یافتن توکن‌های ممنوعه اسکن می‌کند. هر فایلی که کلماتی مانند «تضمین» (Guarantee)، «SLA»، «همیشه» (Always)، «هرگز نمی‌شکند» (Never break) یا «Production-safe» را معرفی کند، به‌طور خودکار رد می‌شود.

در نهایت، سیستم فایل‌ها را تنها پس از آنکه یک مالک نام‌برده (Named Owner) صفحات انسانی را تایید کرد، ادغام می‌کند. یک پیش‌نویس مرجع می‌تواند با بررسی اسکیما ادغام شود، اما یک صفحه «تعهد» نمی‌تواند با فیلد مالک خالی ادغام گردد.

پیاده‌سازی دروازه (The Gate)

برای اجبار به اجرای این قوانین، هر فایل Markdown باید source_ids را در Front Matter خود اعلام کند. گره‌های تحت مالکیت انسان همچنین باید یک owner مشخص را اعلام کنند. نبود هر یک از این فیلدها منجر به «خطای کامپایل» می‌شود، نه یک کامنت ساده درباره استایل. لحن و طول متن خارج از محدوده کامپایلر است؛ تنها حضور شناسه منبع (Source ID) به عنوان دروازه ورود پذیرفته می‌شود.

یک نمونه از اسکیمای موجودی (Inventory Schema) برای این فرآیند می‌تواند به این شکل باشد:

{
  "schema_version": 1,
  "sources": [
    {
      "id": "openapi:users.list",
      "kind": "openapi.operation",
      "path": "docs/sources/openapi.yaml",
      "pointer": "#/paths/~1users/get",
      "owner": null
    },
    {
      "id": "human:deprecation.users.list",
      "kind": "human.promise",
      "path": "docs/human/deprecation-users-list.md",
      "pointer": null,
      "owner": "api-platform"
    }
  ]
}

سیستم از یک استخراج‌کننده مبتنی بر پایتون استفاده می‌کند که به‌جای «تکمیل کردن»، «کپی» می‌کند. اگر یک عملیات OpenAPI پاسخ‌های 4xx را حذف کرده باشد، استخراج‌کننده نیز آن‌ها را حذف می‌کند. این ابزار از اضافه کردن «بخش‌های خطای عمومی» برای کمک به کاربر خودداری می‌کند، زیرا این کار به معنای اختراع یک حقیقت است. استخراج‌کننده به‌طور خاص از نوشتن کلیدهایی مانند deprecated_on یا retry_safe اجتناب می‌کند چون این‌ها حقایقی در سند OpenAPI نیستند.

نرده‌های حفاظتی فنی

این خط لوله شامل یک مجموعه تست است (مانند ماژول پیشنهادی test_doc_gate.py) تا سه شکست رایج را شناسایی کند:

1. کامل بودن Front Matter: اطمینان از حضور page_kind ،source_ids ،owner و review_state.
2. مالکیت: تایید اینکه هر صفحه‌ای با نوع human. حتماً یک مالک تعیین شده داشته باشد.
3. توکن‌های تعهد: اطمینان از اینکه صفحات تولیدشده حاوی توکن‌های ممنوعه (مانند SLA یا Guarantee) نباشند.

با اجرای این موارد به‌عنوان Unit Test (مثلاً pytest tools/test_doc_gate.py -q) به‌جای لینترهای اختیاری، تیم‌ها می‌توانند تضمین کنند که رشد صفحات مرجع تولیدشده، با رشد متناظر تعهدات تاییدشده توسط انسان همگام است. اگر تعداد صفحات تولیدشده افزایش یابد در حالی که تعداد صفحات انسانی صفر بماند، یعنی لیست موجودی در حال دروغ گفتن است.

محدود کردن پرامپت رندر

مرحله رندر تنها جایی است که یک مدل آزاد و سرور آزاد جای دارند، زیرا آن‌ها حقایق استخراج‌شده را روی ماشینی بدون دسترسی به اسرار تولید (Production Secrets) فرمت می‌کنند. برای جلوگیری از اینکه مدل داده‌های گم‌شده را با روایت‌های داستانی بپوشاند، پرامپت باید فقط Stubها را دریافت کند — نه تاریخچه Git یا دفترچه راهنما را. برای حفظ یکپارچگی این روایت‌ها، می‌توان از روش‌های استفاده از هش‌های blob برای جلوگیری از بازنویسی ناخواسته روایت‌های انسانی توسط AI بهره برد.

یک قرارداد پرامپت پیشنهادی شامل این محدودیت‌ها است:

• فقط از کلیدهای موجود در JSON استفاده کن.
• کدهای وضعیت، مقادیر پیش‌فرض، زمان‌بندی‌ها یا توصیه‌ها را اضافه نکن.
• از کلمات Guarantee، SLA، Always، Never break و Production-safe استفاده نکن.
• اگر فیلدی گم شده است، آن بخش را حذف کن.

محدودیت‌ها و محدوده

این گردش کار مستندات را به‌طور مطلق «درست» نمی‌کند، بلکه فقط جلوی دسته‌ای از دروغ‌ها را می‌گیرد که از حدس زدن فرمت ایجاد می‌شوند. این سیستم نمی‌تواند تشخیص دهد که یک Schema اساساً غلط است، یک فلگ پارس شده اما بدون استفاده است، یا یک فایل OpenAPI دو نسخه از سرویس در حال اجرا عقب‌تر است. این‌ها نقص‌های محصول هستند، نه نقص‌های مستندسازی.

علاوه بر این، این راهنما هشدار می‌دهد که از این رویکرد برای محتواهای پرریسک استفاده نشود. این روش برای موارد زیر مناسب نیست:

• توصیه‌های امنیتی یا شرایط حقوقی.
• قیمت‌گذاری یا متون مربوط به پزشکی و ایمنی.
• Runbookهای اختصاصی مشتریان.
• APIهایی که ماشین‌خوان نیستند (جایی که موجودی باید به‌صورت دستی و تخیلی نوشته شود).
• صفحات پشتیبانی GA که به‌طور خودکار منتشر می‌شوند.

در این موارد، طراحی روایت باید کاملاً در دسته انسانی باقی بماند. همچنین لینتر توکن‌های تعهد، ابزاری ابتدایی است؛ ممکن است یک رشته خطای نقل‌شده که حاوی کلمه «Always» است را اشتباهاً علامت‌گذاری کند یا یک پاراگراف مودبانه را که به‌طور ضمنی یک SLA را القا می‌کند، نادیده بگیرد. بنابراین، لینتر باید به عنوان یک «سیم هشدار» (Tripwire) عمل کند، در حالی که مالک نام‌برده همچنان شرط نهایی برای هرگونه تعهد به مشتری است.

این تغییر در شیوه عمل، شغل توسعه‌دهنده را از ویرایش نثر به مدیریت یک «لیست موجودی» تغییر می‌دهد. مدل تبدیل به یک ابزار فرمت‌بندی می‌شود که موجودی صادقانه را به Markdown خوانا تبدیل می‌کند، در حالی که انسان تنها منبع حقیقت برای تعهدات API باقی می‌ماند.

گام بعدی شما

• بررسی کنید آیا در مستندات فعلی شما، صفت‌های مطلق (مانند Always یا Guaranteed) وجود دارند که توسط کد پشتیبانی نشوند.
• برای بخش‌های مرجع (Reference) مستندات خود، یک سیستم source_id تعریف کنید تا هر پاراگراف به یک خط کد یا فایل Schema متصل باشد.
• یک لیست از «توکن‌های ممنوعه» برای مدل‌های زبانی خود ایجاد کنید تا از تولید تعهدات ساختگی جلوگیری شود.

اما داستان سخت‌افزاری این تحول حتی شگفت‌انگیزتر است — به تحلیل ما درباره‌ی تراشه‌های Blackwell مراجعه کنید.