استفاده از Git Hooks برای حل مشکل بازگشت مخرب در Claude Code

تصور کنید در حال کدنویسی با یک عامل (Agent) هستید و یک اشتباه کوچک — مثل «مرتب‌سازی» ناگهانی فایل tsconfig.json توسط مدل — کل بیلد پروژه را می‌شکند. حالا شما با یک انتخاب دردناک روبرو هستید: یا از ابزار rewind داخلی استفاده کنید و تمام پیشرفت‌های ۱۰ مرحله بعد را از دست بدهید، یا ساعت‌ها وقت بگذارید تا آن یک خطای کوچک را دستی پیدا کنید. در دنیای واقعی، یک چرخه بدِ عامل نباید شما را مجبور کند که ده چرخه خوب را دور بریزید.

فرض کنید در مراحل ۱ تا ۸، سه هندلر مسیر را با موفقیت منتقل کرده و برای هر کدام تست نوشته‌اید. در مرحله ۹، عامل فایل تنظیمات را تغییر می‌دهد و بیلد می‌شکند. در مراحل ۱۰ و ۱۱، شما دو خطای unrelated را رفع می‌کنید. آخرین کامیت شما دو ساعت پیش بوده است. اگر حالا دستور git checkout . را بزنید، تمام دستاوردهای ۱۰ مرحله اخیر برای حذف یک اشتباه پاک می‌شود. ابزار rewind در Claude Code می‌تواند شما را به قبل از مرحله ۹ برگرداند، اما مراحل ۱۰ و ۱۱ هم با آن می‌روند و هر تغییری که عامل از طریق دستورات شل ایجاد کرده باشد، اصلاً ردیابی نمی‌شود.

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

محدودیت‌های نقاط بازرسی داخلی

Claude Code نقاط بازرسی (Checkpoint) ساده‌ای ارائه می‌دهد. این سیستم وضعیت کد را قبل از هر پرامپت که یک چرخه را شروع می‌کند، ثبت می‌کند. کاربران می‌توانند با فشردن دو بار کلید Esc در حالی که پرامپت خالی است، یا با اجرای دستور /rewind و انتخاب یک پرامپت قدیمی‌تر، کد، گفتگو یا هر دو را بازیابی کنند.

طبق مستندات نقاط بازرسی، سیستم اسنپ‌شات‌های فایل‌ها را برای ۱۰۰ نقطه بازرسی اخیر در یک جلسه نگه می‌دارد. این داده‌ها پس از رزومه کردن جلسه باقی می‌مانند و معمولاً حدود ۳۰ روز پس از آخرین ذخیره‌سازی جلسه پاک می‌شوند، مگر اینکه تنظیمات cleanupPeriodDays افزایش یابد.

با این حال، این نقاط بازرسی سه نقطه کور بحرانی دارند:

• نامرئی بودن دستورات Bash: فایل‌هایی که توسط دستورات شل تغییر می‌کنند، ردیابی نمی‌شوند. مستندات صراحتاً از rm ،mv و cp به عنوان مثال ذکر می‌کنند. طبق همین قاعده، یک تغییر دسته‌جمعی با sed -i در ده فایل، اجرای یک فرمتر از طریق شل، یا یک npm install که فایل lock را بازنویسی می‌کند، برای ابزار rewind نامرئی است.
• شکاف‌های زیر-عامل‌ها: ویرایش‌های انجام شده توسط زیر-عامل‌ها (Subagents) معمولاً بازیابی نمی‌شوند؛ مستندات صراحتاً توصیه می‌کند برای بازگرداندن این تغییرات از گیت استفاده کنید.
• بازیابی خطی: بازگشت به یک نقطه در زمان عمل می‌کند. اگر به قبل از مرحله ۹ برگردید، هر چیزی که بعد از آن اتفاق افتاده است نیز حذف می‌شود.

مستندات صریح هستند: این نقاط بازرسی برای «بازیابی سریع در سطح جلسه» طراحی شده‌اند و «جایگزینی برای کنترل نسخه نیستند». اگر چرخه بد، آخرین چرخه باشد و عامل فقط از ابزارهای ویرایش فایل خود استفاده کرده باشد، rewind ابزار مناسبی است. برای هر مورد دیگر، گیت ضروری است. این نیاز به کنترل دقیق، در راستای تلاش‌های گسترده‌تری است که برای جلوگیری از ادعاهای دروغین عامل‌ها درباره رفع باگ‌ها در Claude Code صورت گرفته تا اعتماد توسعه‌دهنده به خروجی مدل افزایش یابد.

مکانیزم ارجاع‌های پنهان گیت

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

این فرآیند شامل سه گام فنی دقیق در گیت است:
۱. Staging: اجرای git add -A در کپی، تا اسنپ‌شات شامل هر فایلی شود که گیت نادیده نمی‌گیرد، از جمله فایل‌های ردیابی‌نشده (untracked).
۲. ایجاد درخت: تبدیل این ایندکس به یک درخت با دستور git write-tree.
۳. کامیت و ارجاع: بسته‌بندی درخت در یک کامیت با git commit-tree و نام‌گذاری آن کامیت در مسیر refs/turns/ با دستور git update-ref.

چون این ارجاع‌ها در مسیر refs/heads/ نیستند، در دستور git branch ظاهر نمی‌شوند و هنگام git push معمولی (با فرض استفاده از push.default=simple) ارسال نمی‌شوند. با این حال، آن‌ها کاملاً نامرئی نیستند: دستور git log --all با هر ارجاع در refs/ به عنوان یک نقطه شروع برخورد می‌کند و دستور git push --mirror این ارجاع‌ها را به سرور می‌فرستد.

هر چرخه دو اسنپ‌شات دریافت می‌کند: یک اسنپ‌شات «قبل» (pre) که هنگام ارسال پرامپت گرفته می‌شود و یک اسنپ‌شات «بعد» (post) که در پایان چرخه ثبت می‌شود. تفاوت (diff) چرخه، فاصله بین pre و post است. این ساختار تضمین می‌کند که هر ویرایشی که شما دستی بین چرخه‌ها انجام می‌دهید، هرگز وارد تاریخچه چرخه عامل نمی‌شود. چون اسنپ‌شات درخت را می‌خواند، هر تغییری که در طول چرخه رخ داده باشد — چه توسط ابزار ویرایش عامل و چه توسط دستور شل مثل sed — ثبت می‌شود.

اتوماسیون از طریق هوک‌ها

این مکانیزم از طریق هوک‌های Claude Code خودکار می‌شود. این هوک‌ها در رویدادهای چرخه حیات اجرا شده و یک شیء JSON شامل فیلدهایی مثل session_id و cwd را از طریق stdin دریافت می‌کنند. پیاده‌سازی این سیستم نیازمند یک اسکریپت (ذخیره شده در .claude/turns.sh) و یک پیکربندی در .claude/settings.json است.

سه رویداد خاص برای این کار به کار گرفته می‌شوند:

• UserPromptSubmit: زمانی اجرا می‌شود که یک پرامپت ارسال شود، اما قبل از اینکه کلود آن را پردازش کند. این رویداد اسنپ‌شات pre را فعال می‌کند.
• Stop: زمانی اجرا می‌شود که کلود پاسخ دادن را تمام کند. این رویداد اسنپ‌شات post را فعال می‌کند.
• StopFailure: زمانی اجرا می‌شود که چرخه به دلیل خطای API به پایان برسد، تا وضعیت حتی در زمان کرش‌ها ثبت شود.

برای اینکه هوک بی‌صدا بماند، اسکریپت از exec 1>&2 استفاده می‌کند تا خروجی استاندارد (stdout) را به stderr بفرستد. این موضوع حیاتی است زیرا در رویداد UserPromptSubmit ،Claude Code خروجی stdout را به صورت متن ساده به زمینه (Context) کلود اضافه می‌کند؛ در غیر این صورت، مدل خروجی‌های گیت را می‌خواند.

جزئیات فنی اسکریپت

• جداسازی جلسات: ارجاع‌ها به صورت refs/turns/<session-id>/009/pre و .../009/post ذخیره می‌شوند. کلیدگذاری بر اساس ID جلسه اجازه می‌دهد دو جلسه Claude Code در یک مخزن (مثلاً در دو worktree مختلف) بدون تداخل در شماره‌گذاری‌ها هم‌زیستی کنند. هوک، ID جلسه را از طریق git rev-parse --git-path در یک فایل turns-session می‌نویسد تا CLI جلسه درست را برای worktree فعلی شناسایی کند.
• عملکرد: با شروع از کپی ایندکس واقعی، دستور git add -A از بازبینی مجدد (rehashing) فایل‌هایی که اندازه و زمان تغییر آن‌ها از آخرین stage تغییر نکرده است، صرف‌نظر می‌کند.
• مدیریت وقفه‌ها: اگر کاربر با فشردن Esc چرخه را متوقف کند، رویداد Stop اجرا نمی‌شود (طبق مستندات هوک‌ها، اگر توقف به دلیل مداخله کاربر باشد، اجرا نمی‌شود). تابع کمکی at در اسکریپت این مورد را مدیریت می‌کند؛ به این صورت که اسنپ‌شات pre چرخه بعدی را به عنوان پایان چرخه متوقف شده در نظر می‌گیرد، یا اگر چرخه جدیدی شروع نشده باشد، یک اسنپ‌شات تازه از درخت می‌گیرد.
• پیکربندی: فایل .claude/settings.json از متغیر محیطی $CLAUDE_PROJECT_DIR برای ارجاع به اسکریپت استفاده می‌کند. استفاده از نقل‌قول‌های دوگانه (Double quotes) تضمین می‌کند که مسیرهایی که دارای فاصله (space) هستند به درستی مدیریت شوند.

ابزارهای بازیابی: Diff، Undo و Go Back

پس از اینکه اسکریپت قابل اجرا شد (chmod +x .claude/turns.sh)، یک رابط خط فرمان (CLI) قدرتمند برای بازیابی فراهم می‌کند:

• list: دستور git diff --shortstat را بین pre و post هر چرخه اجرا می‌کند. این به شما اجازه می‌دهد بدون خواندن تمام diffها، بفهمید کدام چرخه فایل tsconfig.json را تغییر داده است.
• diff N: دقیقاً نشان می‌دهد که در چرخه N چه تغییراتی رخ داده است.
• undo N: اثرات یک چرخه را حذف می‌کند در حالی که بقیه تغییرات حفظ می‌شوند. این ابزار پچ چرخه N را می‌گیرد و آن را به صورت معکوس روی فایل‌های فعلی اعمال می‌کند. اگر در چرخه‌های بعدی همان خطوط ویرایش شده باشند، پچ معکوس جای نمی‌گیرد. طبق مستندات git apply ،این فرآیند اتمیک است: اگر برخی بخش‌ها (hunks) اعمال نشوند، کل پچ شکست می‌خورد و هیچ تغییری در درخت کاری ایجاد نمی‌شود.
• back N: یک نسخه خشن‌تر از بازیابی است. درخت کاری را دقیقاً با پایان چرخه N مطابقت می‌دهد، فایل‌های ایجاد شده در چرخه‌های بعدی را حذف می‌کند و ویرایش‌های دستی بعد از آن نقطه را دور می‌ریزد.
• oops: آخرین عملیات undo یا back را معکوس می‌کند. هر دو دستور undo و back قبل از اجرا، درخت فعلی را در refs/turns/<session-id>/undo اسنپ‌شات می‌گیرند.

محدودیت‌های این روش

• شماره‌گذاری: شماره چرخه‌ها هر پرامپتی که کلود پردازش می‌کند را می‌شمارد. UserPromptSubmit برای تسک‌های زمان‌بندی شده و تکرارهای /loop نیز اجرا می‌شود، بنابراین «چرخه ۹» در ارجاع‌ها لزوماً نهمین پیامی نیست که شما تایپ کرده‌اید.
• فایل‌های نادیده گرفته شده: فایل‌های موجود در .gitignore در اسنپ‌شات‌ها نیستند. اگر چرخه ۹ دستور npm install را اجرا کند، undo کردن آن فایل package-lock.json را برمی‌گرداند اما node_modules را نه.
• تداخل عامل‌ها: اگر دو عامل را در یک checkout اجرا کنید، چرخه‌های هر کدام شامل ویرایش‌های دیگری می‌شود. راهکار این است که به هر عامل یک Git worktree مجزا بدهید.
• ذخیره‌سازی: فایل‌های حجیم ردیابی‌نشده که در .gitignore نیستند، در اولین اسنپ‌شات به داخل .git کپی می‌شوند. فایل ignore خود را دقیق نگه دارید.
• پاک‌سازی: ابزار /rewind و این اسکریپت از یکدیگر بی‌خبرند. برای پاک کردن این ارجاع‌ها از دستور زیر استفاده کنید: git for-each-ref --format='delete %(refname)' refs/turns | git update-ref --stdin. کامیت‌های غیرقابل دسترس حاصل، سپس توسط Garbage Collection گیت حذف می‌شوند.

ادغام در Hermes IDE

من در حال ساخت Hermes IDE هستم که این منطق را به صورت بومی ادغام کرده است. این محیط عامل‌هایی مثل Claude Code، Codex، GitHub Copilot CLI و OpenCode را اجرا می‌کند، به طوری که هر کدام در ترمینال مجزای خود قرار دارند و چرخه‌ها را بدون نیاز به هوک‌های دستی، به طور خودکار ثبت می‌کنند.

در Hermes IDE (نسخه ۲.۳.۱، منتشر شده در ۱۳ اکتبر ۲۰۲۶)، رابط کاربری شامل یک نوار زیر هر جلسه با برچسب «Agent replies» است. هر چیپ (Chip) در این نوار نماینده یک پاسخ است و تعداد خطوط تغییر یافته (+افزوده شده، -حذف شده) را نشان می‌دهد.

• میز بررسی (Review Desk): با فشردن ⌘G (یا Ctrl+Shift+G)، کاربران می‌توانند تغییرات را بر اساس هر چرخه ببینند. در سناریوی tsconfig.json ،شما می‌توانید تغییرات چرخه ۹ را در ایزولاسیون بخوانید و فایل‌ها را به نقطه قبل از آن چرخه برگردانید.
• ناوبری: وقتی تعداد پاسخ‌ها از عرض صفحه بیشتر شود، یک چیپ «+N earlier» لیست کاملی از تمام پاسخ‌ها را باز می‌کند.
• محدودیت‌ها: طبق یادداشت‌های انتشار، اگر یک تسک از پوشه‌های اضافی استفاده کند، نوار تغییرات فقط تغییرات در پروژه اصلی را ردیابی می‌کند. برای تسک‌هایی که در worktree خودشان اجرا می‌شوند، اسنپ‌شات‌های چرخه ۱۴ روز پس از بسته شدن جلسه از مخزن حذف می‌شوند.

Hermes رایگان است، تحت لایسنس BSL 1.1 در دسترس است و روی macOS، Windows و Linux اجرا می‌شود. این ابزار هیچ وابستگی به Anthropic، OpenAI یا Nous Research ندارد.

تحلیل: تغییر در گردش‌کار هوش مصنوعی

این تغییر، کدنویسی با AI را از «تولید امیدوارانه» به «حسابرسی دقیق» تبدیل می‌کند. با تبدیل هر چرخه عامل به یک پچ قابل بازگشت به جای یک تغییر وضعیت کلی، توسعه‌دهندگان می‌توانند با عامل‌ها مانند مهندسان جونیور برخورد کنند که کارهایشان مشمول یک تاریخچه کامیت دقیق و خط‌به‌خط است. این رویکرد در واقع تکامل ابزارهای ارزیابی است؛ همان‌طور که پلاگین‌های جدید Claude Code برای اندازه‌گیری مهارت واقعی مدل‌ها طراحی شده‌اند، این سیستم نیز اجازه می‌دهد کیفیت هر گام از کدنویسی را به طور مجزا بسنجیم.

برای یک توسعه‌دهنده حرفه‌ای، این یعنی حذف «ترس از خرابی». توانایی حذف چرخه ۹ در حالی که چرخه‌های ۱۰ و ۱۱ حفظ شوند، هزینه اشتباه عامل را از «گم شدن دقایق کاری» به «یک دستور ساده» کاهش می‌دهد. خروجی عامل دیگر یک بلوک یکپارچه از تغییرات نیست، بلکه پشته‌ای از لایه‌های مجزا و قابل مدیریت است.

اگر در محیط کاری خود با TypeScript کد می‌زنید، می‌دانید لایه‌ای که در آن یک ویرایش تک‌خطی عامل می‌تواند همه چیز را در پایین‌دست بشکند، اغلب tsconfig و پیکربندی ابزارهای بیلد است. این موضوع در کتاب TypeScript in Production ،پنجمین کتاب از مجموعه The TypeScript Library بررسی شده است. برای کسانی که هنوز در حال آشنایی با این زبان هستند، کتاب‌های TypeScript Essentials و The TypeScript Type System مسیر اصلی را فراهم می‌کنند، در حالی که کتاب‌های تخصصی برای توسعه‌دهندگان JVM یا PHP شکاف‌ها را پر می‌کنند. هر پنج کتاب در نسخه‌های الکترونیکی، شومیز و جلد سخت موجود هستند.

گام بعدی شما

• اگر از Claude Code استفاده می‌کنید، اسکریپت turns.sh را در پروژه خود پیاده کنید تا از شر /rewind خطی خلاص شوید.
• برای مدیریت پروژه‌های بزرگ، از Git worktree استفاده کنید تا هر عامل در محیطی ایزوله فعالیت کند و تاریخچه‌ها تداخل نکنند.
• در صورت استفاده از ابزارهای اتوماسیون، حتماً فایل .gitignore را به‌روز کنید تا اسنپ‌شات‌های گیت با فایل‌های حجیم و بی‌مورد پر نشوند.

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