Workspace ایجنت — Worktree و Copy-on-Write — تکنیک Ralph Wiggum

تا حالا Ralph را مستقیم روی Branch اصلی اجرا می‌کردیم. کار می‌کند، ولی آزاردهنده است: لحظه‌ای که حلقه شروع می‌شود، پروژه‌ات عملاً قفل است. اگر فایلی ویرایش کنی یا Branch عوض کنی، با حلقه در حال اجرا تداخل می‌کنی. راه‌حل: به هر ایجنت یک Workspace اختصاصی بده. دو راه تمیز داریم.

راه اول: Git Worktree

Worktree اجازه می‌دهد همان مخزن را در یک پوشه جدا با Branch خودش Checkout کنی:

git worktree add -b my-feature ../vue-shop-my-feature
cd ../vue-shop-my-feature

این Branch تاریخچه Git را با پوشه اصلی به اشتراک می‌گذارد، پس عملیات Git ساده است. اما یک تله دارد: فایل‌هایی که Git ردیابی نمی‌کند (مثل `node_modules` یا `‎.env`) خودکار نمی‌آیند. پس اول باید Bootstrap کنی:

yarn install   # وگرنه «vite not found» می‌گیری
yarn dev

Git Worktree

Checkout همان مخزن در پوشه‌ای جدا با Branch مستقل؛ تاریخچه Git مشترک است ولی فایل‌های Untracked (وابستگی‌ها) خودکار نمی‌آیند.

post-checkout Hook

اسکریپت Git که بعد از Checkout اجرا می‌شود؛ می‌تواند خودکار node_modules را نصب کند.

به‌جای Bootstrap دستی، یک `post-checkout` Hook نصب می‌کنیم (که خود Claude می‌سازد). اسکریپت واقعی چیزی شبیه این است:

#!/bin/bash
# .git/hooks/post-checkout
if [ ! -d node_modules ]; then
  echo "node_modules missing — running yarn install"
  yarn install
fi

بعد از `chmod +x`، هر Worktree تازه خودش وابستگی‌هایش را نصب می‌کند. تست عملی در ویدیو: Worktree را `remove` کردند، Branch را حذف کردند، دوباره `git worktree add` زدند — و این‌بار `yarn install` خودکار اجرا شد.

چالش Port و ابزار portless

وقتی چند Worktree هم‌زمان Dev Server دارند، هرکدام یک Port می‌گیرد (5173، 5174، ...) و فهمیدن اینکه کدام Port مال کدام Branch است سخت می‌شود. ابزار `portless` این را حل می‌کند:

npm install -g portless
portless run yarn dev --host   # از هر Worktree

`portless` تشخیص می‌دهد که در یک Worktree هستی و خودکار یک Subdomain به نام Branch می‌سازد (`my-feature.…`) — پس بصری می‌فهمی کدام Branch را تست می‌کنی.

دستور توکار Claude

Claude خودش راه توکار ساخت Worktree دارد:

claude --worktree my-feature

که یک Worktree در پوشه worktrees می‌سازد. برای کار تعاملی عالی است، ولی برای حلقه‌های Ralph کنترل بیشتری لازم است — برای همین این را به‌صورت فلگ و کانفیگ به Ralph CLI اضافه می‌کنیم:

# ralph.toml
workspace = "worktree"          # یا copy-on-write
directory = "vue-shop"
yolobox = true

راه دوم: Copy-on-Write

بزرگ‌ترین عیب Worktree مصرف فضای دیسک است: پنج Worktree یعنی پنج کپی `node_modules`. راه‌حل Copy-on-Write است:

cp -Rc vue-shop vue-shop-cow   # -c روی macOS/APFS

Copy-on-Write — CoW

قابلیت فایل‌سیستم که کپی «به‌ظاهر کامل» می‌سازد ولی داده واقعاً تکثیر نمی‌شود؛ فقط هنگام تغییر یک فایل، نسخه واقعی‌اش ساخته می‌شود.

APFS / BTRFS

فایل‌سیستم‌هایی که CoW را پشتیبانی می‌کنند — APFS روی macOS، BTRFS روی Linux. روی Windows بهتر است Worktree بمانی.

CoW پوشه‌ای می‌سازد که همان داده زیرین را به اشتراک می‌گذارد؛ فقط وقتی فایلی تغییر کند نسخه واقعی‌اش ساخته می‌شود. مزیت بزرگ: `node_modules` و `‎.env` از همان اول آنجا هستند — نه Hook می‌خواهی نه نصب مجدد. Setup فوق‌سریع.

مقایسه دو روش

معیار	Worktree	Copy-on-Write
فضای دیسک	زیاد (کپی node_modules)	کم (اشتراک داده)
سرعت Setup	کند (نصب وابستگی)	فوری
نیاز به Hook	بله (post-checkout)	خیر
Git مشترک	بله	خیر (با PR جبران می‌شود)
Windows	پشتیبانی	ندارد

DIAGRAMدو مدل Workspace

مخزن اصلی

→

Worktree: Branch مستقل + node_modules جدا

Copy-on-Write: داده مشترک، تغییرات جدا

→

حلقه Ralph روی Workspace ایزوله

در پایان، هر دو Branch را با `merge` در main ادغام می‌کنیم — ترجیحاً داخل YoloBox تا Permission را با خیال راحت Bypass کنیم. اگر Conflict کوچکی پیش آمد، حل می‌کنیم و تست می‌گیریم.

به زبان ساده

چند ایجنت روی یک پوشه در کار هم می‌روند. به هر کدام یک Workspace بده: Worktree (Git مشترک، نصب مجدد وابستگی) یا Copy-on-Write (فوری، فضای کم).

مثال واقعی

Worktree اول `vite not found` داد چون node_modules نیامده بود. post-checkout هوک `yarn install` را خودکار کرد. portless به Branch یک Subdomain داد تا Portها قاطی نشوند. سازنده سری در کار روزمره CoW را ترجیح می‌دهد.