Claude Code Worktree — ایزوله‌سازی Git تا عامل‌های موازی با کار یکدیگر تداخل نکنند
از 2026-10-20، Claude Code نشست‌های موازی را با git worktree ایزوله میکند: دستور claude --worktree feature-auth یک worktree زیر .claude/worktrees/ روی شاخه worktree-feature-auth ایجاد میکند؛ زیرعامل‌ها میتوانند isolation: worktree را تنظیم کنند. پاکسازی هنگام خروج بر اساس آنچه از دست می‌رود انجام میشود.
Worktree چیست و چرا اهمیت دارد
git worktree یک پوشه کاری جداگانه با فایلها و شاخه مخصوص خود است که همان تاریخچه و remote مخزن را با checkout اصلی به اشتراک می‌گذارد. Claude Code هر نشست موازی را در worktree خودش اجرا میکند: دستور claude --worktree feature-auth (یا -w) پوشه .claude/worktrees/feature-auth/ را در ریشه مخزن روی شاخه worktree-feature-auth ایجاد میکند. نشست A قابلیت X را می‌نویسد و نشست B باگ Y را برطرف میکند، بدون اینکه فایل‌های یکدیگر را لمس کنند.
ابزار EnterWorktree و پیکربندی isolation
همچنین می‌توانید از Claude بخواهید در طول یک نشست در یک worktree کار کند؛ Claude با ابزار EnterWorktree یکی ایجاد میکند. پیش از ورود به مسیری خارج از پوشه .claude/worktrees/ مخزن، Claude Code از شما تأیید میگیرد؛ پیش از v2.1.206، Claude می‌توانست بدون پرسیدن وارد هر مسیر worktree موجود شود. یک زیرعامل سفارشی می‌تواند isolation: worktree را به frontmatter خود اضافه کند تا هر ارسال یک worktree موقت دریافت کند. .claude/worktrees/ را به .gitignore اضافه کنید و از .worktreeinclude استفاده کنید تا .env و سایر فایل‌های نادیده‌گرفته‌شده به worktreeهای جدید منتقل شوند.
worktreeهای زیرعامل و عامل‌های موازی
زیرعامل‌ها میتوانند در worktreeهای خودشان اجرا شوند: از Claude بخواهید برای عامل‌های شما از worktree استفاده کند، یا isolation: worktree را به یک زیرعامل سفارشی اضافه کنید. هر زیرعامل یک worktree موقت میگیرد که در صورت پایان بدون تغییر بهطور خودکار حذف میشود؛ worktree دارای تغییر تا زمانی که جاروب دوره‌ای بتواند آن را بدون از دست رفتن کار حذف کند روی دیسک میماند. مثال: سه عامل همزمان auth را بازنویسی میکنند، تست واحد اضافه میکنند و migration می‌نویسند — ویرایش فایلها هرگز تداخل پیدا نمی‌کند و شما در پایان merge می‌کنید. هنگام خروج، Claude کار باقی‌مانده را بررسی میکند: نشست بی‌نام پاک بهطور خودکار حذف میشود، برای نشست دارای تغییر Claude از شما می‌پرسد که آن را نگه دارید یا حذف کنید، و اجراهای -p بهطور خودکار پاک نمی‌شوند.
پاکسازی خودکار، دام‌های رایج، قراردادهای تیمی
وقتی از یک نشست تعاملی worktree خارج می‌شوید، Claude فایل‌های تغییر‌یافته یا ردیابی‌نشده و commitهای جدید را بررسی میکند: نشست بی‌نام پاک بهطور خودکار حذف میشود، برای نشست نام‌دار Claude ابتدا می‌پرسد، و برای نشست دارای تغییر از شما می‌پرسد که آن را نگه دارید یا حذف کنید؛ اجراهای -p بهطور خودکار پاک نمی‌شوند. دام‌های رایج: 1) تداخل نام شاخه میان عاملها؛ 2) ماندن worktreeهای زیرعامل دارای تغییر روی دیسک تا جاروب دوره‌ای؛ 3) فراموش کردن افزودن .claude/worktrees/ به .gitignore. تیم‌ها باید روی یک پیشوند ثابت برای شاخه توافق کنند (مثلاً wt/agent-<name>-<ts>) تا از تداخل جلوگیری شود.
FAQ
worktree چه تفاوت اساسی با یک شاخه معمولی git دارد؟
شاخه یک اشارهگر به commit است؛ جابهجایی میان آنها یعنی checkout که فایلها را بازنویسی میکند. worktree یک پوشه کاری جداگانه است، بنابراین چند شاخه میتوانند همزمان در مسیرهای فیزیکی متفاوت checkout شوند. این پیشنیاز اجرای موازی عاملها است.
آیا worktreeهای زیرعامل مخزن اصلی را آلوده میکنند؟
خیر. هر زیرعامل یک worktree موقت میگیرد؛ git worktreeها را زیر .git/worktrees/<id> ردیابی میکند. worktree زیرعامل بدون تغییر بهطور خودکار حذف میشود؛ worktree دارای تغییر تا زمانی که فرایند پاکسازی بتواند آن را بدون از دست رفتن کار حذف کند باقی میماند، بنابراین checkout اصلی پاک میماند.
آیا میتوان در چین از worktree همراه Claude Code استفاده کرد؟
بله. worktreeها قابلیتهای محلی git و کلاینت Claude Code هستند؛ استنتاج مدل از طریق نقطه پایانی QCode پیکربندیشده شما انجام میشود. worktreeها به یک مخزن git نیاز دارند؛ برای سایر سیستمهای کنترل نسخه، hookهای WorktreeCreate و WorktreeRemove را برای جایگزینی منطق git پیکربندی کنید.
اجرای عامل‌های موازی Claude Code از طریق QCode
استنتاج مدل از طریق نقطه پایانی API مربوط به QCode انجام میشود؛ worktreeها به‌صورت محلی اجرا می‌شوند، بنابراین نشست‌های موازی فقط از دستورهای بالا استفاده میکنند.
پلن QCode خود را شروع کنید