هوک‌های کنترلی
اسکیل‌ها و ساب‌اجنت‌ها نگارش را انجام می‌دهند؛ هوک‌ها قواعد را قطعی می‌کنند. Lore چند هوک اسکریپت شل دارد که خودکار اجرا می‌شوند: در هر بار نوشتن فایل، وقتی یک ساب‌اجنت کارش تمام می‌شود، و در پایان هر نوبت. اگر قاعده‌ای نقض شود، کار را مسدود می‌کنند و دقیقاً می‌گویند چه چیزی باید اصلاح شود.
این هوک‌ها دو خانواده‌اند، و همین تمایز کل طراحی است:
- کنترل‌کننده‌های خروجی می‌پرسند: آیا شکل Markdown درست است؟
- کنترل‌کننده‌های شواهد می‌پرسند: آیا کار پشت آن واقعاً انجام شده است؟
خانواده‌ی دوم به‌خاطر یک شکست مشخص وجود دارد. قاعده‌ای که فقط با نثر اجرا شود، اصلاً اجرا نمی‌شود: همان عاملی که مرحله‌ای را رد کرده، همان است که گزارش «رد نشد» را می‌نویسد؛ پس تعهدی که با نوشتن یک جمله ادا شود، همیشه قبول می‌شود. عبارت «هیچ چیز مرتبطی نبود، جست‌وجو تأیید شد» بایت‌به‌بایت یکسان است، چه منبع خوانده شده باشد چه هرگز باز نشده باشد.
کنترل‌کننده‌های خروجی، در هر نوشتن
| هوک | کی مسدود می‌کند |
|---|---|
| بررسی frontmatter | یک فایل مستندات frontmatter لازمش را ندارد (یک بلوک YAML بسته با کلیدهای مورد انتظار). |
| بررسی مسیر تصویر | تصویری داخل پوشه‌ی مستندات نوشته شود، یک ارجاع تصویر Markdown از پیشوند مسیر اشتباه استفاده کند، یا اسکرین‌شات موبایل به‌جای تگ خام <img> با نحو Markdown جاسازی شود. (بیلد دومی را بازنویسی می‌کند و استایل موبایل دیگر اعمال نمی‌شود.) |
| بررسی ارجاع ابزار | یک سند منتشرشده به ابزار نگارش اشاره کند: مسیرهای داخلی، نقل‌قول‌های پیکربندی، یا نام اسکیل‌ها. (خروجی خواننده‌محور خودبسنده می‌ماند؛ تقسیم مسئولیت را ببینید.) |
کنترل‌کننده‌های شواهد، آیا کار انجام شد؟
| هوک | چه می‌کند |
|---|---|
| ثبت‌کننده‌ی شواهد | هرگز مسدود نمی‌کند. برای هر واکشی و هر اجرای ساب‌اجنت یک سطر به گزارشی فقط-افزودنی اضافه می‌کند. این فایل را شما نمی‌نویسید، ابزار می‌نویسد، پس منبعی که هرگز واکشی نشده تصادفاً در آن ظاهر نمی‌شود. سطرها لایه‌بندی‌شده‌اند: واکشی‌ای که ابزاری واقعاً انجام داده مدرک است، ولی نشانی اینترنتی‌ای که صرفاً داخل یک فرمان شل دیده شده، نه. |
| بررسی سرشماری | سرشماری منابعی را مسدود می‌کند که سطرهایش رسید ندارند (کاوشی که اجرا شد، وضعیت HTTP، پاسخ خام ذخیره‌شده)، پاسخ‌های خام ارجاع‌شده‌اش موجود نیستند، منابع ادعایی‌اش واکشی تأییدشده‌ای پشتشان نیست، یا صفری ثبت کرده که پاسخ خام نقضش می‌کند. |
| ثبت‌کننده‌ی اعتبارسنج | هرگز مسدود نمی‌کند. هر اجرای بازبینی را ثبت می‌کند: حکمش، اینکه واقعاً کدام فایل‌ها را بازبینی کرده، و اثرانگشت هر صفحه‌ی مستندات در همان لحظه. تاریخچه‌ای فقط-افزودنی از همه‌ی اجراها هم نگه می‌دارد. |
| نگهبان ارجاع | ویرایشی را که بخواهد پیوند منبعی را حذف کند که واکشی‌اش در گزارش ثبت شده، مسدود می‌کند. ارجاع، رسیدِ همان ادعایی است که کنارش نشسته، و ازدست‌رفتنش هنگام یک اصلاح تنها شکستی است که هیچ اندازه‌ای از دستورالعمل دقیق جلویش را نمی‌گیرد. جابه‌جایش کنید، یا به خواننده بگویید چرا ادعا می‌رود؛ اما به‌عنوان اثر جانبی یک ویرایش دیگر ناپدید نمی‌شود. پیوندی که گزارش هرگز واکشی‌اش را ندیده رسید نیست و مشمول این دروازه نمی‌شود. |
| دروازه‌ی شواهد کارگر | نمی‌گذارد کارگر استخراج کارش را تمام کند در حالی که هیچ چیزی پشت آنچه می‌خواهد گزارش کند نیست: نه پاسخ خام ذخیره‌شده‌ای روی دیسک، نه واکشی‌ای که به نامش ثبت شده باشد. کارگر یک خلاصه برمی‌گرداند، و خلاصه‌ای بدون رسید دقیقاً همان چیزی است که مدل شواهد برای ردکردنش وجود دارد. کارگر برای واکشی درست برگردانده می‌شود، به‌جای اینکه عددهایش پذیرفته شود. |
| یادآور سرشماری | هرگز مسدود نمی‌کند. وقتی صفحه‌ای تازه ساخته می‌شود و هنوز سرشماری‌ای وجود ندارد، تعهد را در همان لحظه‌ی عمل یادآوری می‌کند. |
| یادآور ویرایش انبوه | هرگز مسدود نمی‌کند. پیش از یک ویرایش همسان سراسری روی مستندات، بررسی‌هایی را که این جنس ویرایش لازم دارد جلو می‌آورد؛ چون در آن هیچ‌چیز غلط تایپ نشده، پس هیچ کنترل خروجی‌ای آسیبش را نمی‌بیند. |
دو بار سنجیده می‌شود، با دو سخت‌گیری متفاوت
سرشماری تدریجی نوشته می‌شود. قرارداد اجرا در پیش‌پرواز ثبت می‌شود، یعنی پیش از آنکه چیزی واکشی شده باشد، پس یک‌بار سنجیدنش به‌ناچار در یکی از دو جهت غلط می‌شد:
- هنگام نوشتن، شکل سنجیده می‌شود. آیا آنچه تا اینجا نوشته شده خوش‌ساخت و رسیددار است؟ همین اجازه می‌دهد سرشماری پیش‌پرواز اصلاً وجود داشته باشد.
- در پایان نوبت، کامل‌بودن سنجیده می‌شود. اجرا تمام شده، پس هر نوع منبعی که آن ورودی طلب می‌کند باید شمارش واقعی داشته باشد، و اجرای سایت زنده باید وضعیت‌هایی را که واقعاً دیده نشان بدهد.
اجبار کامل‌بودن هنگام نوشتن، همان اولین نوشتن را مسدود می‌کرد، و ارزان‌ترین راه فرار از آن انسداد یک جای‌نگهدار بود که بعد تا پایان اجرا همان بررسی را راضی می‌کرد. دروازه عملاً به مدل یاد می‌داد چطور دروازه را از کار بیندازد.
در پایان نوبت
یک هوک Stop جاروب نهایی را می‌زند. روی تصاویر جابه‌جا و مسیرهای ارجاع تصویر بد مسدود می‌کند، و در پروژه‌ای که اجرایی شواهد بر جا گذاشته، روی این‌ها هم:
- نشستی که مستند نوشته ولی هیچ سرشماری منابعی بر جا نگذاشته؛
- سرشماری‌ای که هنوز ناقص است؛
- دستور صریحی از شما که هنوز در قرارداد اجرا باز است (برای «انجام‌شده» باید شواهد کنارش باشد؛ «صرف‌نظر» تأیید شما را می‌خواهد)؛
- مستنداتی که محتوایشان با آنچه آخرین بازبینی سبز واقعاً سنجیده فرق دارد.
درباره‌ی تصاویری که چیزی به آن‌ها ارجاع نمی‌دهد هم هشدار می‌دهد، و حلقه‌آگاه است، پس شما را روی یک نقض غیرقابل‌رفع گرفتار نمی‌کند.
تغییر پس از بازبینی سبز، تصمیم شماست نه یک دور دیگر
این بررسی پیش‌تر زمان آخرین تغییر فایل را می‌سنجید، که در هر دو جهت غلط بود. یک git pull، یک rebase یا ذخیره‌ی ویرایشگر که همان بایت‌ها را برمی‌گرداند، یک دور کامل اعتبارسنجی را بی‌دلیل تحمیل می‌کرد. و وقتی واقعاً چیزی تغییر کرده بود، تنها پاسخ موجود «دوباره اجرا کن» بود، پس اصلاح یک غلط املایی و یک جایگزینی سراسری گسترده یکسان برخورد می‌شدند. هیچ‌کدام به شما نمی‌رسید.
حالا محتوا، صفحه‌به‌صفحه، مقایسه می‌شود:
- بازنویسی بدون تغییر محتوا اصلاً رویداد نیست: نه دوری، نه پرسشی؛
- تغییر واقعی نوبت را نگه می‌دارد و به شما می‌رسد. به شما گفته می‌شود کدام فایل‌ها تغییر کرده‌اند و ریسکش چیست، و شما انتخاب می‌کنید: بازبینی دوباره‌ی دقیقاً همان فایل‌ها، یا تأیید تحویل به همین شکل.
تأیید شما به همان محتوای دقیق گره می‌خورد، پس ویرایش بعدی بی‌سروصدا بازنشسته‌اش می‌کند؛ یک تأیید هرگز نمی‌تواند تغییری را که شما ندیده‌اید پوشش دهد. و نمی‌تواند بازبینی ناموفق را کنار بزند: حکم بازدارنده باید رفع شود، نه صرف‌نظر.
در برابر این حس که «فقط یک اصلاح املایی بود» مقاومت کنید. این قاعده دقیقاً از دل یکی از همان‌ها بیرون آمده: یک واژه که در کل پروژه جایگزین شد، داخل متن نقل‌شده‌ی رابط کاربری نشست و بی‌صدا بیست‌ویک صفحه را نادرست کرد، در حالی که هر خط تغییریافته به‌تنهایی درست خوانده می‌شد.
تا وقتی بازبینی بازدارنده است، اصلاح‌ها از مسیر بازنویس می‌روند
حلقه‌ی پرهزینه هرگز بازبینی نبود، اصلاح بود. به بازبینی بازدارنده پیش‌تر همان نشستی پاسخ می‌داد که صفحه را نوشته بود: زیر فشار زمان، یک یافته در هر بار، گاهی وقتی دوری هنوز در جریان بود. هر یک از آن ویرایش‌ها ادعای تازه‌ای است که از هیچ‌کدام از بررسی‌هایی که اصل متن از آن‌ها گذشته، نگذشته است.
پس تا وقتی حکم جاری بازدارنده است، ویرایش مستندات فقط داخل یک اجرای lore:doc-reviser مجاز است. یک هوک بیرون از آن ویرایش را رد می‌کند و می‌گوید به‌جایش چه باید کرد. یافته‌ها به‌صورت یک دسته می‌روند، بازنویس فقط چیزی را دست می‌زند که نامش برده شده، و بعد دقیقاً همان فایل‌هایی که تغییر کرده دوباره بازبینی می‌شوند. یافته‌هایی که اصلاح متن نیستند اصلاً به او نمی‌رسند: رسید جامانده به جمع‌آوری منابع برمی‌گردد و پرسش محصولی به شما.
حکم سبز بلافاصله این محدودیت را برمی‌دارد. از آن نقطه، همان دروازه‌ی تغییر بالا کار را دست می‌گیرد و تصمیم دوباره با شماست.
این یکی پیش از انتشار اندازه‌گیری شد. در نخستین اجراهای این قاعده به‌شکل نثر، نشست آن را خواند و بعد باز هم خودش دسته را اعمال کرد، هر دو بار؛ چیزی که مسیردهی را واقعی کرد، همین اجبار بود.
محدوده و امنیت
- هوک‌ها فقط در یک پروژه‌ی مستندسازی Lore عمل می‌کنند. پلاگین به‌ازای هر کاربر نصب می‌شود، پس هوک‌هایش در هر مخزنی که در آن کار می‌کنید اجرا می‌شوند. بنابراین هر هوک اول بررسی می‌کند که این یک پروژه‌ی Lore باشد و در غیر این‌صورت بلافاصله خارج می‌شود. قواعد اینجا تعریف تحویل Lore است، نه حقیقتی جهان‌شمول؛ پروژه‌ای که هرگز آن را نپذیرفته دست‌نخورده می‌ماند، حتی اگر اتفاقاً Markdown یا تصویری در پوشه‌ای به نام
docsداشته باشد. - درون یک پروژه‌ی Lore، هوک‌ها فقط روی پوشه‌ی مستندات عمل می‌کنند، که نسبت به ریشه‌ی پروژه حل می‌شود. نمونه‌های عمدی (زیر دایرکتوری‌های قالب و پیکربندی) کنار گذاشته و رد می‌شوند.
- تجزیه به‌صورت گام‌به‌گام بین ابزارهای موجود تنزل می‌یابد و اگر هیچ‌کدام نباشند با صدای بلند هشدار می‌دهد، به‌جای اینکه بی‌سروصدا رد شود.
این دروازه‌ها چه هستند و چه نیستند
این‌ها در برابر رد شدن یک مرحله محافظت می‌کنند، نه در برابر جعل عامدانه. هر آرتیفکتی که در کار است یک فایل معمولی است و عاملی با دسترسی شل می‌تواند آن را بنویسد. خاصیتی که می‌خرند این است که شواهد نادرست تصادفاً در جریان کار عادی پدید نمی‌آید، و دقیقاً همین شکست بود که برایش ساخته شدند. ادعای بیش از این، همان اشتباهی است که باعث شد نسخه‌ای پیش‌تر باور کند این دسته از باگ را رفع کرده است.
محدودیت‌های شناخته‌شده
- منبعی که پیش از ارتقا واکشی شده در گزارش نیست، پس اولین اجرا پس از ارتقا دوباره واکشی می‌کند.
- تطبیق منابع ادعایی با گزارش بر اساس میزبان است؛ عمداً سهل‌گیرانه، تا انسدادهای کاذب نزدیک صفر بماند.
- مستنداتی که خارج از ابزارهای معمول فایل نوشته شود نشانگر نشست ندارد و بنابراین دروازه‌ی فرایندی شاملش نمی‌شود.
- رسید، واکشی را ثبت می‌کند، نه سرنوشت بعدی منبع را. وضعیت پاسخ و اثرانگشت آنچه برگشته را دارد، پس می‌دانید چه چیزی خوانده شده؛ اما هیچ چیزی منبع را بین لحظه‌ی واکشی و لحظه‌ی تحویل دوباره بررسی نمی‌کند. صفحه‌ای که منبعش در این فاصله عوض شده، همچنان سبز به نظر می‌رسد.
- بخشی از محدودیت‌های بازنویس به نسخه‌ی Claude Code شما بستگی دارد. اینکه کدام عامل در حال ویرایش است، در هر نسخه برای هر هوک دیده نمی‌شود؛ جایی که دیده نشود، قواعد تنگ‌تر بازنویس (هرگز جایگزینی سراسری، هرگز بیرون از پوشه‌ی مستندات) بر دستورالعمل تکیه دارند نه بر اجبار. ناتوانی‌اش در واکشی و ساخت فایل همه‌جا اعمال می‌شود، از راه ابزارهایی که به او داده شده.
نتیجه: رایج‌ترین اشتباهات مستندسازی، یعنی مسیرهای اشتباه تصویر، نبود frontmatter و نشت ابزار، بلافاصله گرفته می‌شوند؛ و اشتباه بسیار پرهزینه‌تر، یعنی منبعی که بی‌صدا رد شود و بعد «بررسی‌شده» گواهی شود، دیگر مسیر آرامی به تحویل ندارد.