تخطّى إلى المحتوى الرئيسي
تشغيل عدة وكلاء برمجة بالذكاء الاصطناعي بالتوازي باستخدام Git Worktrees: كيف نعزل نسخ العمل والمنافذ وقواعد البيانات وعمليات الدمج

تشغيل عدة وكلاء برمجة بالذكاء الاصطناعي بالتوازي باستخدام Git Worktrees: كيف نعزل نسخ العمل والمنافذ وقواعد البيانات وعمليات الدمج

November 15, 2026
أدوات المطورين
8 دقيقة قراءة

الخلاصة: يمنح git worktree كل وكيل برمجة بالذكاء الاصطناعي مجلد عمل خاصًا به وفهرس staging وفرعًا مستقلًا، بينما تتشارك كل الوكلاء قاعدة كائنات واحدة، فيستطيع عدة وكلاء تعديل المستودع نفسه في الوقت ذاته دون أن يكتب أحدهم فوق عمل الآخر. لكن Git يعزل الملفات فقط، لذلك تظل منافذ خوادم التطوير وملفات تعريف الارتباط على localhost وقاعدة البيانات المحلية وأرقام الـ migrations وملفات .env غير المتتبَّعة تتصادم حتى يفصلها سكربت إعداد.

عندما بدأ فريقنا تشغيل عدة جلسات Claude Code على المستودع نفسه، لم تعد نسخة العمل الواحدة كافية. وكيلان في مجلد واحد يعدّلان الملفات نفسها، ويعيدان تشغيل خادم التطوير نفسه، ويتنازعان على git switch. حلّت الـ worktrees مشكلة الملفات بأمر واحد، وكل ما تعطّل بعد ذلك كان في أجزاء من البنية لا يعرف Git عنها شيئًا.

أهم النقاط

• وكيل واحد، worktree واحد، فرع واحد: الأمر git worktree add، المتاح منذ Git 2.5، ينشئ مجلد عمل إضافيًا مدعومًا بالمستودع نفسه، ويرفض Git سحب الفرع نفسه في اثنين من الـ worktrees.

• الملفات غير المتتبَّعة لا تنتقل: لا توجد .env.local ولا node_modules ولا .next في worktree جديد، لذلك يجب أن ينسخها سكربت الإعداد أو يعيد بناءها.

• Git يعزل الملفات لا بيئة التشغيل: خوادم التطوير المتوازية تتشارك المنافذ وملفات تعريف الارتباط على localhost وقاعدة البيانات المحلية ما لم يحصل كل worktree على اسم مضيف وقاعدة بيانات خاصين به.

• أبقِ الـ worktrees خارج جذر المستودع: الـ worktree المتداخل تُفحَص أنواعه ويُختبَر ويُدقَّق كأنه جزء من المشروع الرئيسي.

• الفروع المتوازية تتعارض في نقاط ساخنة متوقعة: ملفات القفل (lockfiles) والـ migrations المرقّمة تسلسليًا والسجلات المشتركة، لذلك نقسّم مهام الوكلاء على هذه الحدود.

ما الذي يتشاركه git worktree وما الذي يعزله؟

يتشارك git worktree الـ commits والفروع والوسوم (tags) والـ stash والـ hooks وإعدادات المستودع، ويعزل الملفات المسحوبة وفهرس الـ staging والـ HEAD. تحتفظ نسخة العمل الرئيسية بمجلد .git الحقيقي، بينما يحتوي كل worktree مرتبط على ملف .git من سطر واحد يشير إلى مجلد داخل .git/worktrees/ في النسخة الرئيسية.

لهذا التقسيم أثر مباشر على الوكلاء. أي commit يُنشأ في worktree يظهر فورًا في كل worktree آخر دون push أو fetch، لأن الجميع يقرأ قاعدة الكائنات نفسها. والـ hooks الموجودة في .git/hooks أو في core.hooksPath مشترك تعمل في كل worktree. والـ stash مشترك أيضًا، فالوكيل الذي ينفّذ git stash pop قد يطبّق stash أنشأته جلسة أخرى. لذلك تطلب ملفات CLAUDE.md لدينا من الوكلاء عمل commit للعمل الجاري بدلًا من تخزينه في الـ stash.

إنشاء worktree أمر واحد: git worktree add -b agent/search-filters ../app.worktrees/search-filters main ينشئ الفرع agent/search-filters ويسحبه في مجلد مجاور. ويطبع git worktree list سطرًا لكل worktree يضم مساره وآخر commit فيه وفرعه.

لماذا نستخدم الـ worktrees بدلًا من نسخ مستنسخة إضافية أو تبديل الفروع؟

الـ worktrees هي أرخص طريقة للحصول على نسخ عمل متوازية ومعزولة الملفات لمستودع واحد: فهي تضيف مجلد عمل دون نسخ السجل، والـ commits الجديدة تُشارَك فورًا. أما تبديل الفروع في نسخة عمل واحدة فلا يتيح أي توازٍ، والنسخ المستنسخة المنفصلة تكرّر قاعدة الكائنات وتنحرف عن بعضها حتى ينفّذ كل منها fetch.

• git switch في نسخة عمل واحدة: لا وكلاء متوازين، نسخة واحدة من السجل، ولا شيء معزول.

• git clone لكل وكيل: وكلاء متوازون، نسخة من السجل لكل استنساخ، وcommits الوكلاء الآخرين لا تظهر إلا بعد push وfetch، مع عزل الملفات وكل بيانات Git.

• git worktree لكل وكيل: وكلاء متوازون، نسخة واحدة مشتركة من السجل، وcommits الوكلاء الآخرين تظهر فورًا، مع عزل الملفات والفهرس والـ HEAD.

• حاوية أو بيئة sandbox سحابية لكل وكيل: وكلاء متوازون، نسخة لكل بيئة، والـ commits لا تظهر إلا بعد push، مع عزل الملفات والعمليات والشبكة.

نستخدم الـ worktrees للوكلاء الذين يعملون على أجهزتنا، ونحتفظ ببيئات الـ sandbox للكود الذي لا ينبغي أن يلمسها.

كيف ننشئ worktree يستطيع الوكيل تشغيله فعلًا؟

يحتاج الـ worktree القابل للتشغيل إلى أربعة أشياء لا يوفرها git worktree add وحده: فرع جديد من أحدث main، وملفات البيئة غير المتتبَّعة، والاعتماديات مثبّتة، وإعدادات تشغيل خاصة به. نجمع الأربعة في سكربت واحد حتى يبدأ كل وكيل من الحالة نفسها.

يأخذ السكربت اسم المهمة، وينفّذ fetch لـ origin main، ثم git worktree add --no-track -b agent/<name> داخل مجلد مجاور باسم <repo>.worktrees/<name>. بعدها ينسخ .env.local من النسخة الرئيسية، ويكتب DATABASE_URL خاصًا بالـ worktree في .env.development.local، وينشئ قاعدة بيانات Postgres مطابقة عبر createdb، وينتهي بـ pnpm install --frozen-lockfile.

ثلاث من هذه الخطوات جاءت من أخطاء سابقة. الخيار --no-track يمنع الفرع الجديد من اعتماد origin/main فرعًا upstream له، فلا يتعامل git status ولا git pull في ذلك الـ worktree مع main كأنه الفرع البعيد، وأول git push -u origin agent/<name> يضبط الـ upstream الحقيقي. ونكتب القيم الخاصة في .env.development.local لأن Next.js يمنح هذا الملف أولوية على .env.local أثناء next dev، فيبقى الملف المنسوخ دون تعديل. أما pnpm فيحتفظ بمخزن واحد معنوَن بالمحتوى ويربط الحزم بروابط صلبة (hard links) داخل node_modules لكل worktree، فيكون التثبيت الثاني ربطًا في الغالب لا تنزيلًا، بينما ينسخ npm كل حزمة من جديد.

كيف نمنع خوادم التطوير وقواعد البيانات المتوازية من التصادم؟

تتصادم خوادم التطوير المتوازية على ثلاثة موارد مشتركة: منافذ TCP وملفات تعريف الارتباط في المتصفح وقاعدة البيانات المحلية. لا يعزل Git أيًا منها، لذلك يحتاج كل منها إلى قاعدة صريحة لكل worktree.

• المنافذ: ينتقل next dev إلى المنفذ الحر التالي عندما يكون المنفذ 3000 مشغولًا، لكن المنفذ المثبّت في main.ts الخاص بـ NestJS أو في ربط منافذ Docker Compose يفشل مباشرة. لا نثبّت المنافذ في سكربتات التطوير أبدًا، ونترك متغير البيئة PORT يقرر.

• ملفات تعريف الارتباط: لا تعزل المتصفحات ملفات تعريف الارتباط حسب المنفذ، فـ localhost:3000 و localhost:3001 يتشاركان الوعاء نفسه، وتكتب جلسة تسجيل دخول كل وكيل فوق جلسة الآخر. اسم مضيف مختلف لكل worktree، مثل search-filters.localhost، يمنح كلًا منها ملفات تعريف ارتباط منفصلة، ويحلّ Chrome وFirefox أي اسم ينتهي بـ .localhost إلى عنوان الـ loopback. نشغّل كل خادم تطوير عبر portless، وهو proxy محلي يربط اسمًا ثابتًا بأي منفذ اختاره الخادم.

• قواعد البيانات: فرعان يشغّلان migrations على قاعدة بيانات واحدة يتركان مخططها غير مطابق لأي منهما. يكفي خادم Postgres واحد مع قاعدة بيانات لكل worktree ينشئها سكربت الإعداد. يشتق Docker Compose اسم المشروع من اسم المجلد، فتبقى الحاويات ووحدات التخزين منفصلة لكل worktree، لكن ربط منفذ ثابت مثل 5432:5432 يظل يتصادم.

أين يجب أن توضع الـ worktrees حتى تتجاهلها الأدوات الأخرى؟

مكان الـ worktrees مجلد مجاور مثل ../app.worktrees/ وليس داخل المستودع. الـ worktree المتداخل تحت جذر المستودع نسخة ثانية كاملة من الشيفرة، والأدوات التي تبحث بأنماط glob من الجذر تلتقطه: ملف tsconfig.json بلا قائمة include يفحص أنواعه، وVitest وJest يجمعان ملفات اختباره مرة ثانية، وإعداد ESLint v9 المسطّح (flat config) يدقّقه لأن ESLint لا يقرأ .gitignore افتراضيًا.

إن كان الموضع المتداخل لا مفر منه، فيجب إضافة المجلد إلى .gitignore وقائمة exclude في tsconfig.json وأنماط الاستثناء في أداة الاختبار ومصفوفة ignores في ESLint. أما المجلد المجاور فلا يحتاج أيًا من ذلك.

كيف ندمج فروع الوكلاء المتوازية دون تراكم التعارضات؟

تتعارض فروع الوكلاء المتوازية غالبًا في ملفات قليلة متوقعة، لذلك نقسّم المهام بعيدًا عنها وندمج فرعًا واحدًا في كل مرة، ثم نعيد بناء (rebase) بقية الفروع على main الجديد.

• ملفات القفل: وكيلان يضيفان اعتماديات يعيد كل منهما كتابة pnpm-lock.yaml. نسند تغييرات الاعتماديات إلى وكيل واحد، وإلا نحل تعارض package.json يدويًا ونعيد تشغيل pnpm install لتوليد ملف القفل بدلًا من دمجه سطرًا بسطر.

• الـ migrations التسلسلية: يرقّم Drizzle Kit ملفات الـ migrations ويسجلها في journal، فقد يولّد فرعان معًا الـ migration رقم 0007. فرع واحد فقط يملك تغييرات المخطط في كل مرة، أو يعيد الفرع الثاني توليد الـ migration بعد الـ rebase.

• السجلات المشتركة: قوائم المسارات وملفات barrel وملفات JSON للترجمة كلها تُضاف إليها الإدخالات في الموضع نفسه. إدخال واحد لكل ملف، أو الإضافة في مواضع مختلفة، يتجنب معظم التعارضات النصية.

يشغّل كل وكيل فحوصات المشروع كاملة داخل الـ worktree الخاص به قبل فتح pull request، فيشير أي build فاشل إلى فرع واحد. والتنظيف ثلاثة أوامر: git worktree remove <path> الذي يرفض الحذف ما دامت هناك تغييرات لم تُحفظ في commit، ثم git branch -D agent/<name>، ثم git worktree prune الذي يحذف سجلات المجلدات المحذوفة يدويًا.

حذف مجلد الـ worktree بـ rm -rf يترك سجلًا قديمًا، ويظل Git يعامل الفرع كأنه مسحوب حتى يُشغَّل git worktree prune. ودمج squash يضع commit جديدًا على main، فيعتبر git branch -d فرع الوكيل غير مدموج، لذلك نتأكد من دمج الـ pull request قبل فرض الحذف بـ -D.

الأسئلة الشائعة

س: هل يمكن لاثنين من الـ worktrees سحب الفرع نفسه؟

ج: لا. يرفض Git سحب فرع مسحوب بالفعل في worktree آخر، وهذا يمنع وكيلين من تحريك الفرع نفسه. الخيار git worktree add --force يتجاوز هذا الفحص، لكن أي commit في أحدهما يترك الآخر بفهرس وملفات عمل قديمة.

س: هل تتشارك الـ worktrees مجلد node_modules؟

ج: لا. مجلد node_modules غير متتبَّع، لذلك يحتاج كل worktree إلى تثبيت خاص به. يربط pnpm الحزم بروابط صلبة من مخزن عام واحد فيبقى التثبيت المتكرر سريعًا واستهلاك القرص منخفضًا، بينما ينسخ npm كل حزمة في كل worktree.

س: هل يحمي الـ worktree المستودع من أوامر Git المدمّرة التي ينفذها الوكيل؟

ج: جزئيًا فقط. يعزل الـ worktree ملفات العمل، لكن الفروع والوسوم وقاعدة الكائنات مشتركة، فحذف فرع أو وسم أو تنفيذ force push من أي worktree يؤثر فيها جميعًا. ما زالت الحاجة قائمة إلى hooks أو قواعد صلاحيات تمنع هذه الأوامر.

س: هل يعمل Claude Code مع git worktrees؟

ج: نعم. جلسة Claude Code التي تبدأ داخل مجلد worktree تتعامل معه كنسخة عمل عادية، ويمكن للوكلاء الفرعيين في Claude Code العمل داخل worktree معزول يُنظَّف تلقائيًا عندما لا يُجري الوكيل أي تغيير.