‏هوک‌ها تو ایجنت‌های کدنویس چطور کار می‌کنن؟

تو این مقاله اومده که هوک (hook، یعنی اسکریپتی که موقع یه رویداد مشخص خودکار اجرا می‌شه) با قانون‌های متنی یه فرق بنیادی داره: هوک تضمین می‌ده، قانون فقط توصیه می‌کنه. نویسنده یادآوری می‌کنه مدل‌های زبانی احتمالاتی‌ان، پس یه دستور تو CLAUDE.md یا AGENTS.md براشون یه پیشنهاد قویه نه محدودیت. برای همینه که ایجنت اغلب تست‌ها رو اجرا می‌کنه ولی گاهی یه مرحله رو جا می‌ندازه یا کار رو تموم‌شده اعلام می‌کنه، در حالی که بخشی از تست‌ها هنوز قرمزه.

مکانیزمش ساده‌ست: اسکریپت به یه رویداد چسبیده و یه exit code برمی‌گردونه. کد خروجی صفر یعنی چک پاس شده و ایجنت می‌تونه ادامه بده، کد خروجی ۲ یعنی کار بلاک شده و ایجنت باید اول مشکل رو حل کنه. بقیهٔ کدها معمولاً یعنی خود اسکریپت هوک خراب شده که مسئلهٔ جداییه. زبون اسکریپت هم مهم نیست؛ bash، پایتون یا TypeScript فرقی نداره و همین مدل ذهنی تو Claude Code و Codex و بقیهٔ ابزارهای مشابه یکیه.

دو رویداد پرکاربرد pre-tool-use و stop هستن. pre-tool-use درست قبل از اینکه ایجنت کاری انجام بده اجرا می‌شه، مثلاً قبل از خوندن یه فایل، و همون‌جا می‌شه جلوی دسترسی به فایل اعتبارنامه یا پوشهٔ محافظت‌شده رو گرفت. stop هم وقتی ایجنت فکر می‌کنه نوبت یا مکالمه تموم شده اجرا می‌شه؛ اینجاست که کل تست‌سوییت اجرا می‌شه و تا سبزنشدن همه‌چیز، ایجنت اجازهٔ تحویل کار رو نداره. کاربرد سوم هوک‌ها هم لاگ‌گیری و ساختن ردپاییه که مستقل از گزارش خود ایجنته.

نویسنده تأکید می‌کنه قرار نیست هر قانونی هوک بشه. تو پژوهشی که مقاله بهش ارجاع می‌ده، وقتی به ایجنت اجازه دادن سیستم‌پرامپت خودش رو مدام گسترش بده عملکردش تو همهٔ تسک‌ها بدتر شد، ولی وقتی به جاش «میان‌افزار» یعنی همون هوک‌ها رو تکامل داد، تو همهٔ انواع تسک جز سخت‌ترین‌ها بهتر شد و تو سخت‌ترین‌ها ترکیب هوک و قانون بهترین نتیجه رو داد. جمع‌بندی عملی‌اش اینه: هر مرحلهٔ ثابت و قابل‌چک باید بشه هوک، و هرچی که قضاوت و سلیقه می‌خواد بمونه تو قانون‌ها.

نکات کلیدی:

• هوک اسکریپتیه که به رویدادهای چرخهٔ عمر ایجنت وصله و برخلاف قانون‌های CLAUDE.md یا AGENTS.md قابل نادیده‌گرفتن نیست.
• کد خروجی ۰ یعنی اجازهٔ ادامه و کد خروجی ۲ یعنی بلاک‌شدن یا ادامهٔ اجباری کار؛ بقیهٔ کدها یعنی خود اسکریپت خطا داده.
• stop hook موقع اعلام اتمام کار کل تست‌سوییت رو اجرا می‌کنه و تا پاس‌شدن تست‌ها اجازهٔ بستن مکالمه رو نمی‌ده.
• pre-tool-use قبل از اقدام ایجنت فایر می‌شه و برای بستن دسترسی به فایل‌های اعتبارنامه، فایل .env و کانفیگ پروداکشن به کار می‌ره.
• تو پژوهش ارجاع‌شده، گسترش خودکار سیستم‌پرامپت عملکرد رو بدتر کرد ولی تکامل هوک‌ها تقریباً تو همهٔ انواع تسک بهترش کرد.
• اسکریپت هوک می‌تونه bash، پایتون یا TypeScript باشه و همین مفهوم تو Claude Code و Codex مشترکه.