مستندات قدیمی دلیل اصلی بروز باگ در کدهای تولیدشده توسط عامل‌های هوش مصنوعی است

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

طبق اعلام Focused Labs در ۲ ژوئیه ۲۰۲۶، پدیدهٔ «لغزش مستندات» (Documentation Drift) دیگر یک هزینهٔ بهره‌وری برای برنامه‌نویسان نیست، بلکه به یک حالت شکست اجرایی (Runtime Failure) برای عامل‌های خودمختار تبدیل شده است. پیش از این، مسائل خسته‌کنندهٔ مربوط به مستندات تنها مزاحم‌هایی ساده بودند. اما اکنون این مسائل درجه اهمیت جدیدی پیدا کرده‌اند، زیرا مستقیماً تعیین می‌کنند که آیا یک عامل کدنویس تغییر اشتباهی را در سیستم اعمال و ارسال می‌کند یا خیر.

سال‌ها بود که مستندات نرم‌افزار در حاشیهٔ فرآیند تحویل کد قرار داشتند. آن‌ها برای پذیرش نیروهای جدید، بازرسی‌ها، پشتیبانی و بازبینی‌های معماری مفید بودند، یا به روح‌های جسارتی کمک می‌کردند که سعی داشتند بفهمند چرا یک ماژول خاص هنوز از پروتکل SOAP استفاده می‌کند. یک مهندس ارشد همیشه می‌توانست مشکل بدترین مستندات تاریخ را «حل» کند. او می‌توانست به خاطر بیاورد که در فصل گذشته مسیر پرداخت‌ها چگونه جابجا شده است، نویسنده صفحه خاطه‌دار را پیدا کند، تاریخچه گیت (git blame) را چک کند، در اسلک (Slack) به دنبال گفتگوهای اصلی بگردد و دستی مستندات را به‌روز کند. این روند کند بود اما نتیجه‌اش حقیقت داشت.

اما عامل‌های هوش مصنوعی فاقد این شهود اجتماعی و حافظهٔ تاریخی هستند. آن‌ها با کلمات موجود در فایل‌های AGENTS.md یا CLAUDE.md و همچنین ویکی‌های مخزن کد (repo wikis)، متدها (rubrics)، کتاب‌های راهنمای عملیاتی (runbooks) و خلاصه‌های تولیدشده، به عنوان دستورالعمل‌های عملیاتی سخت‌گیرانه برخورد می‌کنند. این رویکرد با تلاش‌های اخیر برای استانداردسازی قواعد کدنویسی هم‌سو است، همان‌طور که پذیرش گستردهٔ فایل‌های AGENTS.md برای یکسان‌سازی دستورالعمل‌ها در ابزارهای مختلف نشان می‌دهد. در واقع مستندات از نقش پشتیبان خارج شده و وارد مسیر اصلی اجرا شده‌اند. همان‌طور که در تحلیل‌های پیشین ما دربارهٔ امنیت مدل‌های بازمتن اشاره کردیم، هرگونه داده‌ای که به عنوان «منبع حقیقت» به مدل داده شود، بدون پرسش پذیرفته می‌شود؛ بنابراین مستندات اکنون بخشی از زیرساخت زمان اجرا هستند.

وقتی یک عامل می‌خواند که مسیر پرداخت در یک سرویس قدیمی قرار دارد — در حالی که این مسیر ماه‌ها پیش تغییر کرده — مدل شک نمی‌کند. او صرفاً آن فرض غلط را به یک تغییر کد (diff) تبدیل می‌کند. چون کد تولیدشده اغلب ساختار صحیحی دارد و بهره‌ور به نظر می‌رسد، این خطاهای پنهان و موذیانه از بازبینی‌های سطحی عبور کرده و وارد محیط عملیاتی می‌شوند. خطرناک‌ترین بخش این است که این شکست‌ها با ظاهرِ «در حال انجام کار» رخ می‌دهند.

انتقال مستندات به مسیر اجرا

برای مقابله با این بحران، LangChain ابزار OpenWiki را معرفی کرده است؛ یک عامل و رابط خط فرمان (CLI) متن‌باز که برای تولید و نگهداری مستندات مخزن کد، به‌خصوص برای مصرف عامل‌ها طراحی شده است. OpenWiki با دانش مخزن کد را به عنوان پایهٔ اجرای دستورات برای عامل‌ها می‌بیند. این ابزار یک دایرکتوری مخصوص به نام openwiki/ ایجاد یا به‌روزرسانی می‌کند و دستورالعمل‌های عامل را به پروژه اضافه می‌کند.

این ابزار توابع عملیاتی مشخصی برای مدیریت این چرخه ارائه می‌دهد:

• openwiki --init: ساختار مستندات را مقداردهی اولیه می‌کند.
• openwiki --update: دانش مخزن کد را به‌روز می‌کند.
• قالب GitHub Action: برای خودکارسازی به‌روزرسانی مستندات در طول فرآیند تحویل کد، در بسته قرار داده شده است.

فلسفهٔ اصلی در اینجا تفکیک «زمینهٔ داغ» (Hot Context) از «دانش سرد» است. فایل داغ نباید کل داستان کدبیس را حمل کند، بلکه باید به دانش به‌روز شده و نگهداری‌شدهٔ مخزن اشاره کند. این فایل‌ها باید شامل قوانینی باشند که در هر اجرا اعمال می‌شوند، مانند:

• دستورات ساخت، تست و اجرای کد.
• مکان‌هایی که سرویس‌ها و پکیج‌ها در آن‌ها ذخیره شده‌اند.
• محدوده مالکیت یک سرویس خاص.
• محدودیت‌های امنیتی که باید اعمال شوند.
• اطلاعات مسیریابی برای سرویس‌ها.

هر بار اجرای عامل باید هزینه تمام اطلاعات اضافی (junk) که به یک فایل اضافه شده است را بپردازد. بنابراین، این فایل نباید به مخزنی برای تمام تصمیمات معماری تبدیل شود که در طول مسیر گرفته شده‌اند.

گنجاندن کل ویکی در یک پرامپت، یک «راهکار تنبلانه» است. این «تخلیه عظیم پرامپت» (giant prompt dump) منجر به جنون می‌شود، زیرا زمینه بیشتر همیشه بهتر نیست. نویز افزایش می‌یابد و چون دانش ویکی اغلب قدیمی است، مدل صرفاً به اولین پاراگرافی که مرتبط به نظر برسد می‌چسبد.

معماری لایه‌ای زمینه

برای جلوگیری از شکست‌های ناشی از تخلیه پرامپت، سیستم باید از یک معماری لایه‌ای استفاده کند، همان‌طور که در مقاله «زمینهٔ کدگذاری‌شده» (Codified Context) آمده است. این مقاله جزئیات یک سیستم سه لایه را شرح داد که روی یک کدبیس ۱۰۸ هزار خطی C# اعمال شده بود:

• قانون اساسی حافظهٔ داغ (Hot-memory constitution): قوانین سطح بالا و محدودیت‌هایی که در هر اجرای واحد اعمال می‌شوند.
• عامل‌های تخصصی (Specialized agents): منطق و راهنمایی‌های مربوط به تکالیف خاص.
• پایگاه دانش حافظهٔ سرد (Cold-memory knowledge base): حقایق عمیق مخزن که فقط در صورت نیاز بازیابی می‌شوند.

این ساختار ثابت می‌کند که مستنداتی که عامل‌ها می‌خوانند، در واقع یک زیرساخت حیاتی (load-bearing infrastructure) هستند. این رویکرد، مستندات را از دسته‌بندی «بر اساس حس/Vibes» خارج کرده و به قلمروی عملی می‌برد؛ جایی که یک صفحهٔ ویکی درست مثل یک فایل پیکربندی (config) عمل می‌کند. در نتیجه، این مستندات باید مالک داشته باشند، از طریق بازبینی تغییر کنند، به‌راحتی قابلیت diff (مقایسه تغییرات) داشته باشند و روش شکست تعریف‌شده‌ای داشته باشند.

این دیدگاه توسط تحقیقات شرکت Chroma در مورد «پوسیدگی زمینه» (context-rot) پشتیبانی می‌شود. طبق گزارش این شرکت، با آزمایش روی ۱۸ مدل مختلف، مشخص شد که با رشد حجم زمینه، عملکرد مدل زبانی بزرگ (LLM) — مثل کتابخانه‌داری که میلیاردها صفحه را خوانده و حالا با همان لحن کتاب‌ها جواب می‌دهد — غیرقابل‌اعتمادتر می‌شود، حتی اگر پیچیدگی تکلیف ثابت بماند. این مسئله با یافته‌های پژوهشی دربارهٔ پوسیدگی متنی و منسوخ شدن تنظیمات دستیارهای کدنویس هم‌خوانی دارد که نشان می‌دهد حجم زیاد داده‌های قدیمی لزوماً به معنای دقت بیشتر نیست. در کدبیس‌های بزرگ، کلید کار این است که تعیین کنیم کدام زمینه «داغ» است (بازیابی شود)، کدام نادیده گرفته شود و کدام یک توسط یک ردپا (trace) یا تست، غلط ثابت شده است.

ماهیت لغزش مستندات

لغزش مستندات مسئله‌ای قدیمی است: کد تغییر می‌کند اما مستندات به‌موعد به‌روز نمی‌شوند. برای انسان، این یعنی یک مهندس جدید دو روز زمان صرف می‌کند تا بفهمد چرا یک قطعه کد کار نمی‌کند و سپس در حین پاک‌سازی، صفحهٔ ویکی را اصلاح می‌کند. اما برای یک عامل، مخاطرات عملیاتی هستند.

مستندات قدیمی حالت‌های شکست خاصی ایجاد می‌کنند:

• PRهای مسیر اشتباه (Wrong-track PRs): یک یادداشت معماری قدیمی می‌تواند باعث شود مهندسان یا عامل‌ها کل یک Pull Request را روی مسیر غلط پیش ببرند.
• مدیریت غلط حوادث (Incident Mismanagement): دستورالعمل‌های قدیمی (runbooks) باعث می‌شوند دستیار مدیریت بحران، در زمان بحران داشبورد اشتباه را هدف قرار دهد یا بررسی کند.
• تست‌های خیالی (Phantom Testing): عامل ممکن است مجموعه‌ای از تست‌ها را اجرا کند که تیم دیگر از آن‌ها استفاده نمی‌کند یا اصلاً روی دیسک وجود ندارند. عامل با موفقیت این تست‌ها را اجرا می‌کند و باگ‌های پیاده‌سازی اشتباه را به سیستم‌های زنده می‌فرستد.

به همین دلیل، مستنداتِ مخصوص عامل‌ها باید در همان چرخهٔ ارزیابی (evaluation) قرار بگیرند. اگر ارزیابی یک عامل پس از انتشار ادامه دارد، مستندات آن هم باید در همان چرخه مداوم کاری باشند.

هزینهٔ خروجی سریع‌تر

توسعه با کمک هوش مصنوعی، چرخهٔ لغزش را تسریع کرده است. Mixpanel گزارش داد که تیم‌های مهندسی پس از ادغام AI در جریان کاری خود، ۵۰٪ Pull Requestهای بیشتری ارسال کردند. علاوه بر این، تیم‌ها در حال متصل کردن پروتکل زمینهٔ مدل (MCP) و عامل‌های کدنویس به داده‌های مشاهده‌پذیری (observability) هستند تا عامل‌ها بتوانند ردپاهای (traces) سیستم را بازرسی کرده و شواهدی از تغییرات زنده را ببینند.

با افزایش خروجی، هزینهٔ زمینهٔ قدیمی نیز به همان نسبت بالا می‌رود. لغزش مستندات در عامل‌های کدنویس سریع‌تر پیش می‌رود چون باید در هر Pull Request و هر آیتم کاری جدید به‌روز شود. وقتی عاملی بر اساس یک فرض قدیمی تغییر ایجاد می‌کند:

• بازبین‌ها زمان ارزشمندی را از دست می‌دهند.
• چرخه‌های بازنویسی (Rework loops) چندین برابر می‌شوند.
• سیستم‌های CI چیزهای غلط را تأیید می‌کنند.
• سیستم «مشغول» به نظر می‌رسد اما در حالی است که همچنان اشتباه است.

این وضعیت را می‌توان به عنوان مشکل «کد قدیمی» (legacy code) برای کارهای تولیدشده توسط AI دانست. سخت‌ترین کار در یک سیستم بزرگ، نوشتن کد جدید نیست، بلکه درک دانش محلی است: اینکه کجاها اجساد دفن شده‌اند (اشتباهات پنهان)، کدام انتزاع‌ها صرفاً فرمالیته‌اند و می‌توان نادیده‌شان گرفت، کدام تست‌ها واقعاً شکست واقعی را سیگنال می‌دهند، کدام قراردادهای نام‌گذاری واقعاً قانون هستند و کدام مرزهای سرویس‌ها سیاسی هستند.

کدهایی که توسط عامل‌ها نوشته می‌شوند، اکنون زمینهٔ محلی خودشان را دارند که فهم آن به اندازه کدهای قدیمی انسانی دشوار است. در واقع، این آثار تولیدشده، چرخهٔ حیات، مالکیت و نیازهای مانیتورینگ تله‌متری و تست‌های QA زمان اجرا (runtime) مخصوص به خود را دارند.

بستن چرخه با ارزیابی

برای حل این مشکل، مستندات مخصوص عامل‌ها باید دقیقاً مانند کد مدیریت شوند. باید در کنترل نسخه باشند تا امکان بازگشت (roll back) وجود داشته باشد. اگر تغییری در مستندات بر خروجی کد اثر می‌گذارد، آن تغییر باید بازبینی، اصلاح و در یک مخزن ردیابی شود و به اصلاحات بازگردد. باید ممکن باشد وقتی عملکرد عامل بدتر شد، تغییرات مستندات را به حالت قبل برگردانیم.

استقرار مؤثر عامل‌ها نیازمند یک چرخه مداوم است که در آن ردپاهای ارزیابی (evaluation traces)، مستندات را به‌روز کنند. مورد مطالعاتی LangChain با شرکت Pendo این هم‌افزایی را نشان می‌دهد. تیم Novus با متصل کردن تحلیل‌های محصول، رفتار کاربر، بازپخش جلسه (session replay) و زمینهٔ کد به اصلاحات کد از طریق ردپاهای LangSmith، به نرخ موفقیت بیش از ۹۰٪ در ارزیابی‌های بازبینی‌شده توسط مدیر محصول (PM) رسید و ظرف چند روز به استفاده زنده منتقل شد.

این یعنی شواهدی که در زمان ارزیابی جمع‌آوری می‌شوند باید مستندات اصلی را به‌روز کنند:

• اصلاح الگوها (Pattern Correction): اگر بازبین مکرراً عامل را برای استفاده از یک زیرسیستم یا قرارداد اشتباه اصلاح می‌کند، این اصلاح باید وارد مستندات مخصوص عامل شود.
• مهاجرت API (API Migration): اگر ردپاها نشان دهند عاملی از طریق یک API قدیمی میان‌بر می‌زند، ویکی باید به‌روز شود تا مرز مهاجرت فعلی را توصیف کند.
• اعتبار تست‌ها (Test Validity): اگر عاملی تست‌های منسوخ شده را (که تیم دیگر استفاده نمی‌کند یا روی دیسک نیستند) با موفقیت اجرا می‌کند، می‌تواند باگ‌های اشتباه را به سیستم‌های زنده بفرستد. آن تست‌ها باید از زمینهٔ عامل حذف شوند.

لغزش مستندات باید توسط همان چرخه تحویلی که رفتار عامل را می‌گیرد، شناسایی شود. وقتی به‌روزرسانی مستندات باعث می‌شود عامل چیزی را متفاوت پیاده کند، آن به‌روزرسانی باید در قالب یک Pull Request باشد.

تعیین مالکیت

مالکیت، عامل حیاتی در موفقیت این سیستم است. مستندات مخصوص عامل‌ها نیازمند یک مدل نگهداری سخت‌گیرانه هستند:

• تیم پلتفرم (Platform Team): مالک مکانیسم‌ها (اندکس‌گذاری، بازیابی، قالب‌ها، ردیابی و خودکارسازی به‌روزرسانی‌ها) است.
• تیم‌های محصول (Product Teams): مالک حقایق خاص دامنه (domain facts) هستند.
• تیم‌های امنیتی (Security Teams): مالک مرزهای دسترسی و الگوهای ممنوعه هستند.
• مالکان تست (Test Owners): مالک دستوراتی هستند که ثابت می‌کنند یک تکلیف «انجام شده» است.
• مالکان معماری (Architecture Owners): مالک نقشه‌های زیرسیستم و یادداشت‌های مهاجرت هستند.

چرخه عملیاتی باید ساده باشد: یک تغییر کد اعمال می‌شود، یک جاب (job) چک می‌کند که آیا زمینهٔ مخصوص عامل هنوز با زیرسیستم تغییر‌یافته مطابقت دارد یا خیر، و در صورت ظهور لغزش، عامل کدنویس یک PR برای به‌روزرسانی مستندات باز می‌کند. سپس ارزیابی‌ها روی تکالیف نمونه اجرا می‌شوند و به بازبین‌ها اجازه می‌دهند تغییر زمینه را در کنار تغییر کد، همراه با یک ردپا یا تکلیف شکست‌خورده، تأیید کنند.

این انتقال، نشان‌دهنده یک لایه جدید از مرز عملیاتی است. بحث دیروز درباره ترتیب کش پرامپت (prompt-cache order) بود؛ بحث امروز درباره منشاء، محدوده و تازگی دانش مخزنی است که توسط موتور اجرا بازیابی، خلاصه و obeyed (اطاعت) می‌شود. مستندات قابل‌خوان برای عامل‌ها، یک لایه مجزا از زیرساخت زمینه هستند. آن‌ها باید توسط انسان‌هایی که مالک سیستم هستند، قابل بازیابی، قابل استناد، قابل تست و قابل تعمیر باشند. این حقیقت که لغزش مستندات زمانی یک «مالیات» بود و اکنون با عامل‌های کدنویس به یک «نقص زمان اجرا» تبدیل شده، موضوعی است که تیم باید مسئولیت آن را بپذیرد.

گام بعدی شما

• مستندات مخزن خود را به دو دستهٔ «قوانین ثابت» (Hot) و «دانش ارجاعی» (Cold) تقسیم کنید تا نویز پرامپت کاهش یابد.
• از ابزارهایی مانند OpenWiki برای خودکارسازی به‌روزرسانی مستندات در جریان CI/CD استفاده کنید.
• هر بار که یک بازبین انسانی کدی را به دلیل «اشتباه در درک ساختار سیستم» رد می‌کند، آن را به عنوان یک باگ در مستندات عامل ثبت و اصلاح کنید.

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