تصور کنید یک برنامهنویس ارشد ساعتها وقت صرف توضیح دلیل انتخاب یک معماری خاص در مستندات کرده است، اما یک مدل هوش مصنوعی در بهروزرسانی بعدی، تمام این منطق را با یک متن کلیشهای جایگزین میکند. این اتفاق دقیقاً همان جایی است که «بدهی مستنداتی» (Documentation Debt) متولد میشود.
به نقل از MonkeyCode، مدلهای هوش مصنوعی اگرچه در بهروزرسانی سریع حقایق فنی پس از تغییر رابطها (Interface) عالی هستند، اما تمایل دارند کل فایل را بازنویسی کنند و در این مسیر، دلیل و منطق انسانی (Rationale) را پاک کنند. این رفتار باعث ایجاد یک چرخه از بدهی مستنداتی میشود. برای حل این مشکل، سیستمی پیشنهاد شده که مستندات را نه به عنوان یک پیشنویس واحد، بلکه به عنوان نقشهای از بخشهای «مقید به هش» (Hash-bound) در برابر روایتهای «آزاد» انسانی میبیند. این رویکرد در واقع تکامل یافتهی همان سیستم گیتهای انسانی برای توقف توهمات در مستندات است که پیشتر توسط MonkeyCode معرفی شده بود.
بسیاری از تیمها در حال حاضر پیشنویسهای هوش مصنوعی را به صورت صفر و یک میبینند: یا مدل مینویسد یا انسان بررسی میکند. این رویکرد یک شکاف دیدهشدنی ایجاد میکند؛ بازبینها نمیتوانند تشخیص دهند کدام پاراگرافها باید منجمد بمانند و کدامها باید با کد منبع تکامل یابند. نتیجه این است که «کهنگی خاموش» (Silent Staleness) رخ میدهد؛ یعنی یک عنوان بهروز به نظر میرسد اما پیادهسازی زیرین آن تغییر کرده است. این یک نوع خاص از بدهی است که تعداد توکنها آن را نشان نمیدهند: حالتی که در آن یک عنوان بهروز به نظر میرسد در حالی که منابعش جابهجا شدهاند، یا عنوانی که جابهجا شده اما منابعش ثابت ماندهاند.
همانطور که در تحلیلهای قبلی ما دربارهی امنیت مدلهای بازمتن اشاره کردیم، تفکیک دقیق دادههای ورودی و خروجی برای حفظ یکپارچگی سیستم حیاتی است. در اینجا نیز، تفکیک «منطق» از «فکت» کلید حل مسئله است. این تفکیک ساختاری شباهت زیادی به راهکار تداوم اصلاحات انسانی برای جلوگیری از اتلاف داده دارد که بر حفظ لایههای تصمیمگیری انسان در برابر پردازشهای خودکار تأکید میکند.
مکانیزم نقشه بازتولید
مرکز این پیشنهاد، یک «نقشه بازتولید» (Regeneration Map) است؛ یک فایل YAML که در کنار مستندات Markdown قرار میگیرد. این نقشه هر عنوان را پیش از فراخوانی هر مدلی، به یکی از دو کلاس مالکیت تقسیم میکند. طبق مستندات این روش، طبقهبندی باید در این فایل YAML بررسیشده باشد، نه در پرامپتی که ممکن است در حین یک جلسه پیشنویس بهصورت اتفاقی و غیررسمی ویرایش شود.
- مقید به هش (قابل پیشنویس توسط مدل): این بخشها شامل حقایق مکانیکی هستند که از کد منبع قابل بازیابیاند؛ مثل جداول Endpoint، نام فلگها، کدهای خطا، فلگهای CLI و فیلدهای Schema. هر بخش، یک یا چند مسیر منبع را لیست کرده و آخرین هش blob گیت (git blob hash) را که با متن پیشنویس پذیرفته شده است، ذخیره میکند.
- آزاد (متعلق به انسان): این بخشها حاوی قصدی هستند که فایلهای منبع نمیتوانند آنها را ثابت کنند؛ مثل مدلهای تهدید (Threat Models)، توافقنامههای سطح خدمات (SLA)، سیاستهای منسوخسازی (Deprecation Policy)، مرزهای پشتیبانی و طرحهای ردشده. این بخشها هیچ پینی به منبع ندارند و با برچسب
regenerate: neverعلامتگذاری میشوند تا از بازنویسی توسط هوش مصنوعی محافظت شوند.
اگر عنوانی در Markdown باشد اما در نقشه نباشد، سیستم آن را «بدون نقشه» (Unmapped) علامت میزند که منجر به شکست در فرآیند Build میشود. متن بدون نقشه، یک بکلاگ برای پیشنویس نیست، بلکه یک تخلف سیاستی است که تا زمانی که توسط انسان طبقهبندی نشود، باقی میماند.
برای حفظ یکپارچگی طبقهبندی، تیمها باید از یک قاعده در قالب Pull Requestهای خود استفاده کنند: اگر بخشی پس از یک بازسازی که فقط شامل تغییر نام است (Rename-only refactor) همچنان درست باشد، احتمالاً مدلمحور است؛ اما اگر پس از حذف کامل پیادهسازی همچنان درست باشد، احتمالاً انسانمحور است. نقشههایی که اعلانهای قانونی یا تاریخچه حوادث (Incident History) را به عنوان مدلمحور علامت میزنند، باید رد شوند. این دقت در بازبینی، یادآور پروتکل سه-مرحلهای MonkeyCode برای شناسایی باگهای پنهان است که در آن هر مرحله از بررسی، لایهی متفاوتی از خطاها را هدف قرار میدهد.
ساختار آرتیفکت نقشه بازتولید
این نقشه کوچک، صریح و مانند هر تنظیمات دیگر که گیتِ ادغام (Merge) است، بررسی میشود. این فایل در کنار فایل Markdown قرار میگیرد و نه در داخل یک تاریخچه چت. یک ساختار نمونه برای docs/api.regen.yaml شامل موارد زیر است:
- نسخه و سند: تعریف نسخه نقشه و فایل هدف (مثلاً
docs/api.md). - وضعیتهای مجاز: فهرستی از حالتهای معتبر:
[fresh, stale, human_locked, unmapped]. - تعاریف بخشها: هر ورودی شامل یک
id، عنوان دقیق (مثلاً## Endpoint index)،ownership(مالکیت) و قوانینregenerateاست. - پینهای منبع: برای بخشهای مدلمحور، مسیرها (مثلاً
src/http/routes.ts) وblob_shaمربوطه (مثلاًe3b0c44298fc1c149afbf4c8996fb924) لیست میشود.
در یک نقشه عملیاتی، بخشی مثل ## Authentication rules با مالکیت انسان (ownership: human)، وضعیت regenerate: never و یک جایگاه برای body_sha256 مانند PENDING_HUMAN_SLICE علامت میخورد. در مقابل، بخش ## CLI flags با مالکیت مدل (ownership: model)، وضعیت regenerate: when_source_stale و یک پین به src/cli/flags.ts با یک هش blob خاص مانند fcde2b2edba56bf408601fb721fe9b5c تعریف میشود.
جدول تصمیمگیری چهار وضعیتی
برای اجرای این سیاست، یک اسکریپت بررسیکننده در زمان ادغام، یکی از چهار وضعیت زیر را به هر بخش اختصاص میدهد. این جدول به عنوان سیاست نهایی عمل میکند؛ اگر پرامپت و جدول با هم اختلاف داشته باشند، جدول برنده است.
| وضعیت | مالکیت | سیگنال هش | بازنویسی توسط مدل؟ | اجازه ادغام؟ |
|---|---|---|---|---|
| human_locked | انسان | تطابق body_sha256 | خیر | بله |
| human_locked (drift) | انسان | تغییر در slice digest | خیر | فقط با تیک تایید انسان و digest جدید |
| fresh | مدل | تطابق تمام پینهای منبع | خیر | بله |
| stale | مدل | تفاوت در یک پین منبع | بله (فقط همان بخش) | خیر (تا بازنویسی، آپدیت پین و بررسی) |
| unmapped | نامعلوم | N/A | خیر | خیر |
گردشکار پیادهسازی
گام ۱ — فهرست کردن عناوین پیش از هر فراخوانی مدل:
فایل Markdown برای عناوین ATX در سطحی که به عنوان ریشه بخش در نظر گرفته شدهاند (معمولاً h2) تحلیل میشود. متن عنوان، آفست شروع و آفست پایان ثبت میگردد. این فرآیند قطعی و ارزان است، بنابراین باید توسط یک اسکریپت (مثلاً python3 tools/list_headings.py) و نه مدل انجام شود. اسکریپت فهرستکننده باید فایلهایی را که عناوین Setext و ATX را ترکیب کردهاند رد کند، زیرا نحوهی ناسازگار، مرزهای بخش را مبهم میکند. ابتدا نحوهی عناوین را اصلاح کنید، سپس طبقهبندی و در نهایت پین کنید.
گام ۲ — طبقهبندی هر عنوان در نقشه:
فهرست را بررسی کرده و مالکیت را بر اساس قوانین تعیین شده اختصاص دهید. ایندکسهای مکانیکی و لیستهای کد خطا مدلمحور هستند؛ هدف و سیاستها انسانمحور میمانند. این طبقهبندی باید در همان تغییری که عنوان را معرفی میکند، در نقشه YAML ثبت شود. اگر سندی قدیمی است که سیاست و مرجع را ترکیب کرده، آن را در یک جلسه بهصورت انبوه طبقهبندی نکنید؛ ابتدا فایل را تقسیم کنید.
گام ۳ — پین کردن هشهای blob برای بخشهای مدلمحور:
با استفاده از git hash-object هش blob گیت هر مسیر منبع لیست شده از فایل worktree محاسبه میشود. این هشها در همان کامیتی که آخرین بار بخش پیشنویس پذیرفته شد، در نقشه ذخیره میشوند. از دستوراتی مانند git ls-files -s برای تایید فایلهای ردیابی شده استفاده کنید. اگر در این مرحله هشها و متن با هم اختلاف داشته باشند، بخش از قبل «کهنه» (Stale) است و نباید برچسب fresh بگیرد. پین کردن یک هش قدیمی در مقابل متن جدید، روشی است که تیمها برای دور زدن بررسیها به کار میبرند؛ بررسیکننده با تلقی هر عدم تطابق به عنوان stale، جلوی این کار را میگیرد.
گام ۴ — اجرای بررسیکننده چهار وضعیتی به عنوان گیت ادغام:
یک اسکریپت (مثلاً tools/regen_check.py) را به عنوان یک بررسی اجباری CI تعریف کنید. بررسیکننده برای هر بخش نقشهبرداری شده یک وضعیت صادر میکند. وضعیتهای شکست (stale و unmapped) مانع ادغام میشوند. برای بخشهای human_locked اسکریپت هش فعلی slice را با body_sha256 ذخیره شده مقایسه میکند. اسکریپت از hashlib.sha256 برای ایجاد digest از slice مارکداون استفاده میکند و برای جلوگیری از نویز، فاصلههای خالی انتهایی (trailing whitespace) را حذف میکند.
گام ۵ — بازنویسی فقط محدوده عنوان کهنه:
وقتی بررسیکننده وضعیت STALE را چاپ میکند، فقط همان محدوده عنوان خاص استخراج میشود. فقط آن محدوده و فایلهای منبع لیست شده به مدل پیشنویس ارسال میشوند. بخشهای انسانمحور را در پرامپت قرار ندهید، زیرا مدلها تمایل دارند متون مجاور را بازنویسی کنند. پس از بازنویسی، git hash-object منابع را مجدداً محاسبه کرده و blob_sha را در نقشه بهروزرسانی کنید. واحد کار، یک عنوان کهنه است، نه کل دفترچه راهنما.
گام ۶ — قفل مجدد بخشهای انسانی بر اساس بایتها:
محدودههای انسانمحور به عنوان یک هش نرمالشده از slice عنوان مقایسه میشوند. فاصلههای خالی انتهایی حذف میشوند تا نویز ویرایشگر به عنوان تغییر سیاست ظاهر نشود. اگر ویرایش انسانی مورد نظر است، body_sha256 باید در همان کامیت مجدداً محاسبه شود و یک بازبین در Pull Request ثبت گردد. این قفل بایتی، مکمل کهنگیِ مقید به هش است.
جزئیات فنی و ابزارها
برای یکپارچهسازی این سیستم در یک خط لوله، میتوان از یک GitHub Action (مثلاً .github/workflows/docs-regen.yml) استفاده کرد تا بررسیها را روی Pull Requestهایی که docs/**، src/http/** یا src/cli/** و همچنین خود اسکریپت بررسیکننده را تغییر میدهند، فعال کند. این گردشکار یک تحلیلگر YAML را از طریق pip install pyyaml نصب کرده و اسکریپت بررسیکننده را روی نقشه هدف اجرا میکند.
مکانیزمهای دقیق ابزارها
- منطق بررسیکننده: اسکریپت پیشنهادی
regen_check.pyبخشهای YAML را پیمایش میکند. اگر عنوانی در Markdown گم شده باشد،MISSINGچاپ میکند. اگر هش واقعی یک بخش انسانمحور باbody_sha256متفاوت باشد،HUMAN_LOCK_DRIFTچاپ میکند. برای بخشهای مدلمحور،git hash-objectرا برای هر مسیر منبع فراخوانی میکند؛ هرگونه عدم تطابق منجر به وضعیتSTALEمیشود. - فرآیند استخراج: برای جلوگیری از آلودگی پرامپت، یک قطعه کد ساده پایتون میتواند محدوده کهنه را ایزوله کند. برای مثال، استخراج متن بین
## Endpoint indexو## CLI flagsو نوشتن آن در یک فایل موقت مانند/tmp/endpoint-index.stale.mdتضمین میکند که مدل فقط بخش مربوطه را میبیند. - کمک به بازبین: برای بازبینها، وضعیتهای جدا شده با Tab بررسیکننده میتوانند به یک گزارش Drift صادر شوند (مثلاً
python3 tools/regen_check.py docs/api.regen.yaml | tee docs/drift-report.txt). این به بازبینها اجازه میدهد بدون خواندن کل لاگ، ببینند کدام پینها جابهجا شدهاند، هرچند وضعیت خروجی غیر صفر (non-zero exit status) همچنان مانع اصلی ادغام باقی میماند.
محدودیتها و ملاحظات فنی
این سیستم بهطور خاص برای تیمهایی طراحی شده است که مستندات خود را در گیت ذخیره میکنند. این سیستم بر ریشههای h2 در ATX تکیه دارد؛ درختهای عناوین عمیقتر به یک فیلد صریح heading_level نیاز دارند تا اطمینان حاصل شود که آفستها قابل اعتماد میمانند. این سیستم از مستندات باینری، HTML تولید شده یا صفحات ویکی خارج از کنترل نسخه پشتیبانی نمیکند.
بهطور حیاتی، تطابق هش blob یک سیگنال از «تازگی» است، نه اثباتی بر «کامل بودن». این تایید میکند که فایلهای منبع از زمان آخرین پیشنویس تغییر نکردهاند، اما تضمین نمیکند که خلاصه هوش مصنوعی دقیق است یا دستورات قابل اجرا هستند. این سیستم نمیتواند فایلهای جابهجا شده، کدهای تولید شده یا مستندات تامینکنندگان پشت یک URL را محاسبه کند، مگر اینکه صراحتاً به لیست منابع اضافه شوند.
این گردشکار برای تاریخچههای روایی طراحی که هیچ بخش مکانیکی ندارند، تیمهایی که از گیت استفاده نمیکنند، یا متون حقوقی که باید در بازههای زمانی غیرمرتبط با تغییرات کد بازنویسی شوند، مناسب نیست. بازبینی انسانی برای خطاهای معنایی همچنان اجباری است، زیرا برابری هش، اثباتی برای کامل بودن نیست.
این رویکرد، بار تحریریه را از یک «حس کلی» در زمان بازبینی به یک «وضعیت قابل مشاهده» در خط لوله CI/CD تبدیل میکند. با تبدیل بدهی مستنداتی به یک خطای Build، تیمها میتوانند پیشنویسهای به کمک هوش مصنوعی را مقیاسبندی کنند — با استفاده از دسترسی رایگان به مدلها و سرورها برای صفهای بازنویسی کوچک و مختص به هر عنوان — بدون اینکه منطق انسانی را که مستندات را مفید میکند، از دست بدهند.
گام بعدی شما
- بررسی کنید آیا در مستندات شما بخشهایی وجود دارد که با هر تغییر کد، باید بهروز شوند اما منطق کلی آنها ثابت است؟
- پیادهسازی یک اسکریپت ساده برای استخراج هش
git hash-objectاز فایلهای کلیدی پروژه را امتحان کنید. - تفکیک فایلهای Markdown به بخشهای کوچکتر (Atomic) برای تسهیل طبقهبندی در YAML.
اما داستان سختافزاری این تحول حتی شگفتانگیزتر است — به تحلیل ما دربارهی تراشههای Blackwell مراجعه کنید.
گفتگو