«جلوگیری از برخورد عامل‌ها»؛ هدف Claude Code از به‌کارگیری Git Worktrees

تصور کنید دو برنامه‌نویس هم‌زمان روی یک فایل کار کنند و هر کدام تغییرات دیگری را پاک کند؛ این دقیقاً همان کابوسی است که در جلسات موازی برنامه‌نویسی با هوش مصنوعی رخ می‌دهد. در حالت عادی، وقتی دو عامل (Agent) سعی می‌کنند یک نسخه محلی (Local Checkout) را تغییر دهند، جلسات آن‌ها با یکدیگر برخورد کرده و باعث اختلال می‌شوند. Claude Code برای پایان دادن به این تداخل، از مکانیزم Git Worktrees استفاده می‌کند تا برای هر جلسه، یک فضای فیزیکی کاملاً مجزا روی دیسک ایجاد کند.

این رویکرد، گلوگاه سنتی «یک پوشه برای یک پروژه» را می‌شکند. در مدل‌های قدیمی، توسعه‌دهنده مجبور بود برای تغییر شاخه (Branch)، وضعیت فعلی دایرکتوری را تغییر دهد که این کار باعث پاک شدن وضعیت محلی (Local State) می‌شد. اکنون، به جای این جابجایی‌های مداوم، توسعه‌دهندگان می‌توانند چندین عامل — شبیه به دستیاران متخصصی که هر کدام در اتاق جداگانه‌ای روی یک بخش از پروژه کار می‌کنند — را هم‌زمان روی ویژگی‌های مختلف فعال کنند بدون اینکه آن‌ها با یکدیگر تداخل داشته باشند.

همان‌طور که در تحلیل قبلی ما درباره‌ی بهره‌وری مدل Claude Sonnet 5.5 اشاره کردیم، تمرکز Anthropic در این به‌روزرسانی از قدرت خام مدل به سمت بهبود تجربه توسعه‌دهنده (DX) تغییر کرده است. این رویکرد در کنار توانایی‌های بالای مدل در مدیریت پروژه‌های پیچیده قرار می‌گیرد؛ چنان‌که در گزارش DevTools Review مشاهده شد که Claude Code در بازسازی‌های چندفایلی عملکردی پیشتاز دارد. برای یک تیم نرم‌افزاری مدرن، چالش اصلی ایجاد شاخه نیست، بلکه مدیریت هرج‌ومرج کارهای هم‌زمان است؛ مثلاً وقتی یک عامل در حال پیاده‌سازی یک ویژگی پیچیده است و شما باید هم‌زمان یک خطای بحرانی در محیط عملیاتی (Production Incident) را رفع کنید. در این شرایط، داشتن محیط‌های ایزوله حیاتی است.

مکانیزم جداسازی فیزیکی

طبق مستندات فنی، در حالت سنتی Git، تمام فایل‌ها در یک دایرکتوری کاری (Working Directory) قرار دارند و با تغییر شاخه، محتویات آن پوشه عوض می‌شود. برای انسان‌ها این روند معمولاً کافی است، اما برای عامل‌های کدنویس، این یک نقطه شکست بحرانی است زیرا عامل‌ها به ثبات محیط برای اجرای تست‌ها و تحلیل کد نیاز دارند.

در محیط‌های تیمی بزرگ، حتی اگر دو نفر یک فایل واحد را ویرایش نکنند، تداخل رخ می‌دهد. برای مثال، یک تیم ممکن است API را تغییر دهد در حالی که تیم دیگر هنوز به نسخه قبلی وابسته است، یا یک PR مربوط به زیرساخت (Infrastructure) باید قبل از PRهای مصرف‌کننده ادغام شود. در این حالت، شاخه‌های Git تاریخچه را جدا می‌کنند، اما دایرکتوری مشترک همچنان یک مانع برای اجرای موازی جلسات عامل‌هاست. این چالش‌ها نشان می‌دهد که ساختارهای مبهم مخزن چگونه می‌توانند مانع عملکرد صحیح عامل‌های کدنویس شوند و منجر به خطاهای پیش‌بینی نشده در محیط عملیاتی گردند.

یک محصول را در نظر بگیرید که توسط چندین تیم نگهداری می‌شود: تیم Checkout تغییرات ایجاد سفارش را مدیریت می‌کند، تیم Payments وضعیت پرداخت را به‌روز می‌کند، تیم Accounts رویدادها را مصرف می‌کند و تیم Platform بسته انتشار (Release Package) را آماده می‌سازد. هر تیم بخشی را مدیریت می‌کند، اما یک تغییر مشترک می‌تواند باعث برخورد این جبهه‌ها شود. این وضعیت شبیه به چندین تیم در یک کارگاه است: هر تیم برای باز کردن یک خودرو به فضای اختصاصی (Bay) خود نیاز دارد، اما همه آن‌ها همچنان به یک انبار قطعات و یک میز بازرسی نهایی مشترک وابسته هستند.

Claude Code با پیاده‌سازی Git Worktrees، ساختاری شبیه به این ایجاد می‌کند:

• repo/main/ (شاخه اصلی)
• repo/exportacao/ (ویژگی: خروجی/Export)
• repo/dashboard/ (ویژگی: داشبورد)
• repo/notificacoes/ (ویژگی: اعلان‌ها/Notifications)

هر دایرکتوری فایل‌ها و شاخه مخصوص به خود را دارد اما تاریخچه مخزن (Repository History) را به اشتراک می‌گذارد. این کار «تداخلات محلی» را حذف می‌کند؛ یعنی دیگر دو جلسه برای تصاحب یک Checkout نمی‌جنگند. این سیستم یک «پارکینگ اختصاصی» برای هر تکلیف فراهم می‌کند تا توسعه‌دهنده بتواند بدون از دست دادن وضعیت محلی خود، یک PR را بررسی کند یا اجازه دهد یک عامل وابستگی‌ها را به‌روز کند در حالی که عامل دیگر در حال تغییر پیکربندی است.

ارکستراسیون بصری در نسخه دسکتاپ

در حالی که Worktrees یک قابلیت بومی Git است، اپلیکیشن Claude Code Desktop آن‌ها را به یک نقشه عملیاتی بصری تبدیل کرده است. نوار کناری (Sidebar) پروژه‌ها و جلسات را سازماندهی می‌کند و کار موازی را قابل درک و بازبینی می‌سازد. در واقع، نوار کناری به یک داشبورد عملیاتی تبدیل شده است که در آن هر گفتگو، یک جلسه مستقل با تاریخچه و پوشه پروژه مجزا است.

در مخازن Git، این اپلیکیشن به‌طور خودکار برای هر جلسه محلی یک Worktree می‌سازد. نتیجه این است که توسعه‌دهنده به جای مجموعه‌ای از ترمینال‌های بی‌نام، لیستی از جبهه‌های کاری فعال را می‌بیند:

• پروژه: checkout
  • جلسه: fix authentication (Worktree اختصاصی + شاخه مجزا، Diff در حال بازبینی، PR در انتظار CI)
  • جلسه: update SDK (Worktree اختصاصی + شاخه مجزا، پیاده‌سازی در حال انجام)
  • جلسه: investigate regression (Worktree اختصاصی + شاخه مجزا، در انتظار تصمیم انسانی)

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

جزئیات قابلیت‌های بصری

• نوار کناری جلسات: لیستی از تکالیف مستقل که هر کدام به یک Worktree و شاخه متصل هستند. این بخش امکان فیلتر بر اساس وضعیت، پروژه و محیط، و همچنین گروه‌بندی بر اساس پروژه را فراهم می‌کند تا مشخص شود چه چیزی در حال اجراست و در چه وضعیتی قرار دارد.
• جلسات در کنار هم (Side-by-Side): قابلیت مشاهده هم‌زمان دو جریان کاری مختلف برای مقایسه تغییرات یک تولیدکننده (Producer) با وابستگی‌های یک مصرف‌کننده (Consumer).
• ردیابی یکپارچه CI/PR: ایجاد یک لینک مستقیم بین Worktree محلی و وضعیت Pull Request در سرور. اپلیکیشن دسکتاپ وضعیت بررسی‌های PR را مستقیماً در داخل جلسه نمایش می‌دهد.
• پیشوندهای قابل تنظیم برای شاخه‌ها: استانداردسازی نام‌گذاری شاخه‌ها برای شناسایی آسان منشأ، تکلیف یا کنوانسیون‌های تیمی.
• ترمینال و ویرایشگر یکپارچه: این ابزارها دقیقاً در دایرکتوری جلسه فعال عمل می‌کنند و از اجرای دستورات در Worktree اشتباه جلوگیری می‌کنند.
• بایگانی جلسات: امکان حذف دستی Worktreeها پس از بسته شدن یا ادغام PR برای جلوگیری از شلوغ شدن محیط محلی.
• پنل‌های Chat، Plan، Tasks و Subagent: سازماندهی استدلال، اجرا و تفویض اختیار در داخل جلسه، به‌طوری که بستر تکلیف به کدی که در حال تغییر است متصل بماند.
• تفاوت‌های بصری (Diff) و کامنت‌های خطی: امکان بازبینی فایل‌ها و ارائه بازخورد به کلود پیش از ثبت کامیت یا ارسال PR.

مقیاس‌پذیری تیمی با دستور /batch

برای تغییرات گسترده‌ای که کل مخزن را در بر می‌گیرد، ابزار جدید دستور /batch را معرفی کرده است. این دستور به عامل اجازه می‌دهد ابتدا کد را تحقیق کند، یک پیشنهاد برای تجزیه (Decomposition) ارائه دهد و سپس واحدهای مستقل را در Worktreeهای مجزا اجرا کند.

هر واحد می‌تواند به طور مستقل پیاده‌سازی شود، تست شود و PR مخصوص به خود را باز کند. این روش برای به‌روزرسانی‌های تکراری، مانند تغییر چندین ماژول برای پیروی از یک قرارداد (Contract) مشترک جدید، بسیار مؤثر است. با این حال، نویسنده هشدار می‌دهد که این قابلیت نیازمند یک تصمیم معماری قوی پیش از شروع موازی‌سازی است. اگر تمام واحدها به یک تصمیم معماری هسته‌ای وابسته باشند، تجزیه باید قبل از فرآیند /batch رخ دهد تا از تکثیر بدهی فنی و حجم بیش از حد PRها جلوگیری شود.

علاوه بر نسخه دسکتاپ، این جداسازی در محیط خط فرمان (CLI) نیز از طریق دستور claude --worktree <feature-name> در دسترس است. این قابلیت اجازه می‌دهد دو تکلیف را بدون تداخل تغییرات محلی اجرا کنید، به شرطی که مخزن حداقل یک کامیت داشته باشد تا Git بتواند پایه (Base) را شناسایی کند. این جریان کاری در بخش «Common workflows» مستندات رسمی توضیح داده شده است.

چرخه Pull Request و واحد کار

Claude Code می‌تواند PRها را ایجاد کرده، Diffها را بازبینی کند و وضعیت بررسی‌ها را ردیابی نماید. در جاهایی که در دسترس باشد، دستور /autofix-pr یک جلسه از راه دور را برای مشاهده شکست‌های CI و بازبینی کامنت‌ها آغاز می‌کند. علاوه بر این، GitHub Actions مربوط به Claude Code، عامل را به رویدادهای مخزن متصل می‌کند و تکالیف مرتبط با PR را خودکار می‌سازد. این گزینه‌ها PR را به نقطه اصلی ادغام بین کار عامل و کنترل‌های تیمی تبدیل می‌کنند، هرچند ادغام خودکار (Auto-merge) به عنوان پیش‌فرض توصیه نمی‌شود.

در این مدل، واحد کار از مسیر خطی «شخص $ \rightarrow $ شاخه $ \rightarrow $ کامیت $ \rightarrow $ PR» به یک ساختار صریح‌تر تغییر می‌کند:
۱. تکلیف + مالک انسانی $ \rightarrow $ قرارداد محدوده (Scope) و پذیرش
۲. جلسه Claude Code $ \rightarrow $ Worktree + شاخه
۳. پیاده‌سازی + تست‌های محلی $ \rightarrow $ Pull Request
۴. CI + بررسی استنتاجی + بررسی انسانی $ \rightarrow $ ادغام

نقش انسان در ابتدا برای تعریف تجزیه و تصمیم‌گیری درباره ادغام ضروری باقی می‌ماند. یک قرارداد تکلیف ممکن است شامل مواردی چون owns: src/export/** (مالکیت مسیر)، must_not_change: migrations/** (عدم تغییر مسیرها) و معیارهای پذیرشی مانند «حفظ فیلترهای فعلی» یا «خنثی کردن فرمول‌ها در سلول‌های خروجی» باشد.

وقتی ابتکارات بین چندین تیم (Cross-squad) مشترک است، قرارداد باید شامل وابستگی‌ها باشد: مثلاً ابتکاری برای تکامل یک قرارداد اعلان (Notification Contract) ممکن است squad-plataforma را به عنوان مالک، service-events را به عنوان تولیدکننده و app-web/app-mobile را به عنوان مصرف‌کننده لیست کند، با یک ترتیب ادغام سخت‌گیرانه (قرارداد/تولیدکننده $ \rightarrow $ مصرف‌کنندگان $ \rightarrow $ حذف نسخه قدیمی). این هماهنگی توسط سنسورهایی مانند تست‌های قرارداد، CI هر مخزن و بازبینی‌های مالک پشتیبانی می‌شود.

سنسورهای محاسباتی و «هارنس کاربر»

جداسازی فیزیکی تنها نیمی از راه است. یک عامل کدنویس ترکیبی از مدل و یک «هارنس» (Harness) است. در حالی که Claude Code زیرساخت محاسباتی (جلسات، ابزارها، مجوزها، زیر-عامل‌ها و ادغام با Git) را فراهم می‌کند، تیم باید «هارنس کاربر» را تعریف کند.

این کار مستلزم تعادل بین راهنمای استنتاجی (دستوراتی که AI تفسیر می‌کند) و سنسورهای محاسباتی (تست‌های عینی که پاس یا فیل می‌شوند) است:

• محدوده و رفتار: هدایت شده توسط قراردادهای تکلیف (تعیین مسیرهای owns و must_not_change) و تأیید شده توسط تست‌های واحد (Unit)، یکپارچگی (Integration) و E2E.
• قابلیت نگهداری: هدایت شده توسط فایل CLAUDE.md و قوانین خاص هر مسیر، و تأیید شده توسط Linterها و Formatterها.
• معماری: هدایت شده توسط نقشه‌های ماژول و قوانین وابستگی، و تأیید شده توسط تست‌های برازش معماری (Architectural Fitness Tests).
• یکپارچگی: هدایت شده توسط انتخاب شاخه پایه و ترتیب ادغام، و تأیید شده توسط CI اجباری و حفاظت از شاخه‌ها (Branch Protections).
• قراردادهای بین تیمی: هدایت شده توسط تعریف مالک و نسخه‌های سازگاری، و تأیید شده توسط تست‌های قرارداد و بازبینی‌های مالک.
• امنیت: هدایت شده توسط حداقل مجوزها و فایل‌های ممنوعه، و تأیید شده توسط اسکنرها و بازبینی‌های انسانی Diff.

Worktree تنها یک زیرساخت است و جایگزین این سنسورها نمی‌شود. اگر در CLAUDE.md ذکر شده باشد «سازگاری را به هم نزن» اما هیچ تست قراردادی در CI وجود نداشته باشد، تیم در واقع برای یک رفتار عینی، به یک دستور استنتاجی تکیه کرده است. هارنس زمانی قوی‌ترین حالت خود را دارد که قوانین تکرارپذیر به سنسورهای محاسباتی تبدیل شوند.

محدودیت‌های Worktreeها

Worktreeها تداخلات فیزیکی فایل‌ها را حل می‌کنند، اما تداخلات منطقی (Logical Conflicts) را نه. آن‌ها نمی‌توانند از شکستن یک قرارداد API مشترک توسط دو عامل جلوگیری کنند یا جنگ بر سر یک فایل Lock یا یک فایل Migration را متوقف کنند.

آن‌ها همچنین ترتیب استقرار (Deployment) را مدیریت نمی‌کنند. نوار کناری بصری نشان می‌دهد که یک جلسه فعال است، اما نمی‌تواند تضمین کند که PR تولیدکننده قبل از PR مصرف‌کننده ادغام شود. این موارد همچنان مسائل هماهنگی انسانی هستند که از طریق بازبینی PRها و حفاظت‌های CI مدیریت می‌شوند.

علاوه بر این، Worktreeها موارد زیر را حل نمی‌کنند:

• مالکیت تعریف نشده و ناسازگاری‌های API بین تیم‌های مختلف.
• تست‌های کند یا ناپایدار که در شناسایی رگرسیون‌ها ناتوان هستند.
• شاخه‌های طولانی‌مدت که فاصله زیادی با شاخه پایه پیدا کرده‌اند.
• اختلافات منابع محلی، مانند رقابت چندین جلسه برای یک پورت دیتابیس یا منبع خارجی.
• مسئولیت پراکنده در مورد اینکه چه کسی هر تغییر را تأیید و ادغام می‌کند.
• جریان انتقال از develop $ \rightarrow $ release/homolog $ \rightarrow $ بسته تولید (Production Package).

در مورد پیکربندی محلی، نویسنده پیشنهاد می‌کند از .worktreeinclude به عنوان یک لیست سفید (Allowlist) برای آرتیفکت‌های محلی ضروری استفاده شود، در حالی که اطمینان حاصل شود اعتبارنامه‌ها (Credentials) و اسرار (Secrets) به‌طور خودکار در دایرکتوری‌ها تکثیر نمی‌شوند. همچنین باید از Auto-merge در مراحل اولیه اجتناب کرد تا زمانی که تیم تأیید کند تست‌ها و حفاظت‌های شاخه به‌طور مؤثر خطاهای بحرانی را شناسایی می‌کنند.

استراتژی پیاده‌سازی برای تیم‌ها

برای پذیرش این جریان کاری، گزارش یک استقرار مرحله‌بندی شده را پیشنهاد می‌کند تا از فشار بیش از حد به خط لوله ادغام جلوگیری شود:

۱. Worktreeهای کمکی: شروع با claude --worktree <task> برای رفع باگ‌های فردی و ویژگی‌های کوچک. این کار جداسازی را با کمترین تغییر در فرآیند معرفی می‌کند.
۲. نقشه‌برداری بصری: استفاده از اپلیکیشن دسکتاپ برای ردیابی چندین جبهه فعال، تا وضعیت تکالیف مختلف برای تیم قابل مشاهده باشد.
۳. هماهنگی مبتنی بر قرارداد: تعریف صریح مالکان، الزامات سازگاری و ترتیب ادغام برای ابتکارات چند-تیمی. این تضمین می‌کند که در حالی که اجرا ایزوله است، ادغام هماهنگ باشد.
۴. حلقه PR و CI: پیاده‌سازی GitHub Actions و /autofix-pr تا عامل بتواند به شکست‌های CI و کامنت‌های بازبینی واکنش نشان دهد.
۵. ارکستراسیون دسته‌ای: استفاده از /batch تنها برای تکالیف تجزیه‌پذیر و تکراری برای افزایش بازدهی بدون اشباع کردن صف بازبینی.

استقرار آزمایشی

دو آزمایش بازگشت‌پذیر برای اعتبارسنجی این رویکرد پیشنهاد شده است:

آزمایش داخلی تیم: انتخاب دو تکلیف مستقل با تست‌های قابل اعتماد. تعریف مالک، فایل‌های مجاز و معیارهای پذیرش. باز کردن یک جلسه/Worktree مجزا برای هر کدام. الزام به PRهای جداگانه، CI سبز و بازبینی انسانی. مقایسه نرخ تداخل و زمان بازبینی در مقابل تکالیف غیرموازی.

آزمایش بین-تیمی: انتخاب یک تغییر کوچک در یک کتابخانه یا قرارداد مشترک. نام‌گذاری مالک قرارداد و مالکان مصرف‌کننده. تعریف سازگاری و ترتیب ادغام. اجرای هر بخش در Worktree خود. الزام به تست‌های قرارداد و بازبینی‌های متقاطع. اندازه‌گیری زمان انتظار بین تیم‌ها و شکست‌های ادغام.

موفقیت با تعداد PRهای باز شده سنجیده نمی‌شود، بلکه با کاهش جابجایی زمینه (Context-switching) و زمان‌های انتظار، بدون افزایش رگرسیون‌ها یا انتقال دوباره کارها به تیم‌های دیگر اندازه‌گیری می‌شود.

گام بعدی شما

• اگر از CLI استفاده می‌کنید، دستور claude --worktree را برای تفکیک تکالیف کوچک امتحان کنید.
• برای پروژه‌های تیمی، یک فایل CLAUDE.md جامع بنویسید تا دستورات استنتاجی به سنسورهای محاسباتی تبدیل شوند.
• در صورت استفاده از نسخه دسکتاپ، جلسات موازی را برای مقایسه تغییرات در دو شاخه مختلف به صورت Side-by-Side تست کنید.

اما مدیریت این حجم از PRهای خودکار، چالش جدیدی در بازبینی کد ایجاد می‌کند — به تحلیل ما درباره‌ی آینده‌ی Code Review در عصر عامل‌ها مراجعه کنید.