التطوير مع وكلاء الذكاء الاصطناعي الأدلة التقنية

Git مع وكلاء البرمجة: فروع وWorktrees ورجوع آمن

فرع وWorktree لكل مهمة، وcommit صغير برسالة تقول من كتبه، وفحص لا يتجاوزه الوكيل، وطريق معروف للرجوع، مع مختبر حقيقي فيه خطاف لم يعمل وcommit أوقف المشروع وجده git bisect.

Git مع وكلاء البرمجة: فروع وWorktrees ورجوع آمن

عندما كنت تكتب الكود بنفسك كان Git يسجل ما تفعله أنت، بالسرعة التي تكتب بها، وتعرف ما في كل commit لأنك كتبته. أما مع وكيل البرمجة Coding Agent فإن الأمر يختلف، فالوكيل يستطيع أن يعدل عشرة ملفات في دقيقة، ويعمل commit برسالة مرتبة تقول شيئاً قريباً مما حدث، وقد يعمل على مهمتين في الوقت نفسه إذا شغلت منه نسختين. وإذا لم يكن عندك نظام واضح لهذا كله فإن تاريخ Git يتحول بسرعة إلى خليط لا تعرف فيه أي تغيير كتبته أنت وأي تغيير كتبه الوكيل، ولا تستطيع أن ترجع عن خطأ واحد دون أن تخسر معه عمل ساعة.

والخبر الجيد أن Git نفسه فيه كل ما تحتاجه لتعمل مع الوكيل بأمان: الفروع Branches والـ Worktrees لتفصل كل مهمة عن الأخرى، والـ commits الصغيرة لتراجع وترجع خطوة واحدة، والخطافات Hooks لتفحص كل commit قبل أن يدخل، وأوامر مثل git revert وgit bisect وgit reflog لتصلح ما فات. والذي ينقص أغلب الفرق ليس الأوامر، وإنما العادات التي تجعل هذه الأوامر تعمل عندما تحتاجها.

في هذا المقال سوف نتناول:

  • لماذا يغير الوكيل طريقة استعمالك لـ Git، وما القواعد الخمس التي تحميك.
  • فرع وWorktree لكل مهمة: كيف تشغل وكيلين في الوقت نفسه دون أن يتصادما.
  • الـ commit الصغير ورسالته: Conventional Commits وسطور التذييل Trailers التي تقول من كتب الكود.
  • كيف تراجع فرق الوكيل Diff قبل أن تدمجه.
  • الرجوع الآمن: git revert و/undo وgit bisect وgit reflog، ومتى تستعمل كل واحد.
  • مختبر حقيقي: Aider مع نموذج محلي في Worktrees منفصلة، وخطاف pre-commit لا يعمل كما تتوقع، وcommit خاطئ نجده بـ git bisect ونرجع عنه، وتعارض بين وكيلين عند الدمج.

ونفترض في هذا المقال أنك تعرف أساسيات Git، فإذا أردت أن تراجع الأوامر التي نبني عليها فقد شرحناها في مقالات مستقلة:

دليلالتراجع عن الأخطاء في Git: revert أم reset أم restore؟لكل خطأ في Git أمر تراجع يناسب المكان الذي وصل إليه، وهنا تتعلم أن تختاره بسؤال واحد، وأن تسترجع عملاً ظننت أنه ضاع.دليلالتبديل بين المهام في Git: Stash أم Worktree؟عندما يأتيك طلب عاجل وأنت في منتصف ميزة، تحفظ عملك جانباً بالأمر stash أو تفتح له مجلداً ثانياً بالأمر worktree، وهنا تتعلم الاثنين خطوة بخطوة ومتى تختار كل واحد.دليلCherry-pick مع git bisect: نقل الإصلاح وإيجاد الخطأكيف تنقل إصلاحاً واحداً إلى الإصدار الذي يعمل عند العميل دون بقية التغييرات وتضع له وسماً، وكيف تجد الـ Commit الذي أدخل الخطأ بين عشرات الـ Commits في دقائق.دليلGit Hooks مع pre-commit: افحص الكود قبل أن يدخل المستودعكيف تمنع الأسرار وملفات الإعداد المعطوبة قبل أن تصل إلى مستودع الفريق، بخطافات على جهاز المطور مع إطار pre-commit، ثم بخطاف pre-receive على Gitea لا يستطيع أحد أن يتخطاه.دليلMerge أم Rebase أم Squash؟ دمج الفروع في Git خطوة بخطوةثلاث طرق لإدخال عمل فرعك إلى main، نجربها على المستودع نفسه حتى ترى بعينك ماذا تفعل كل واحدة بالتاريخ، ومتى تختارها، وكيف تحل التعارض في كل منها.

لماذا يغير الوكيل طريقة استعمالك لـ Git؟

ثلاثة أشياء تتغير عندما يكتب الوكيل جزءاً من الكود، وكل واحد منها يحتاج عادة جديدة:

  • السرعة والحجم: الوكيل يكتب في دقيقة ما يكتبه المطور في ساعة، وإذا تركته يعمل على مهمة كبيرة دون توقف فإنك تحصل على فرق من مئات الأسطر في عشرة ملفات، ولا أحد يراجع مثل هذا الفرق بجدية. ولذلك فإن حجم الـ commit هو أول ما يجب أن تتحكم فيه.
  • الثقة الزائدة في الرسالة: رسالة الـ commit التي يكتبها الوكيل تصف ما أراد أن يفعله، وليس بالضرورة ما فعله فعلاً. وسوف نرى في المختبر رسالة تقول إنها أعادت تسمية دالة، بينما تركت المشروع لا يعمل.
  • التوازي: تستطيع أن تشغل أكثر من وكيل في الوقت نفسه، واحد يصلح خطأ وآخر يضيف ميزة Feature، فإذا عملا في المجلد نفسه فإن كل واحد يغير الملفات تحت يد الآخر.

ومن هذه الثلاثة تخرج خمس قواعد، هي محور هذا المقال:

  1. لا يعمل الوكيل على الفرع الرئيسي main أبداً، وإنما على فرع لمهمته.
  2. لكل مهمة تعمل في الوقت نفسه Worktree مستقلة، أي مجلد عمل منفصل.
  3. كل commit صغير بما يكفي لتقرأه في دقيقة، ورسالته تقول من كتبه.
  4. لا يدخل شيء إلى main قبل أن تراجع الفرق كاملاً وتنجح الفحوص، وفي الفحوص لا تعتمد على الوكيل نفسه.
  5. تعرف قبل أن تبدأ كيف ترجع: عن commit واحد، وعن فرع كامل، وعن خطأ لا تعرف متى دخل.
خط زمني للفرع الرئيسي main في الأعلى بثلاث commits، ومنه فرعان: agent/slug-length في Worktree اسمها blog-slug-length مع commit واحد أخضر، وagent/rename في Worktree اسمها blog-rename مع commit أحمر، وبينهما درع مكتوب عليه pre-commit وتحتهما سهم دمج إلى main بعد المراجعة والاختبار، وسهم git revert يخرج من الـ commit الأحمر
فرع وWorktree لكل مهمة، وcommit صغير تقرؤه، وفحص لا يعتمد على الوكيل، وطريق معروف للرجوع.

وقد يتساءل البعض: هل هذا كله ضروري إذا كانت الأداة نفسها تعطيني نقاط رجوع وأمراً للتراجع؟ والإجابة أن نقاط الرجوع داخل الأداة تعرف ما فعلته الأداة في جلستها فقط، وسوف نرى في المختبر أن أمر التراجع في Aider رفض أن يرجع عن commit عمله Aider نفسه في جلسة سابقة. أما Git فيعرف كل ما دخل المستودع، من أي أداة، وفي أي وقت، ويعمل بالطريقة نفسها مع كل الوكلاء ومع زملائك. ولذلك فإن عاداتك في Git هي الشيء الوحيد الذي لا يتغير إذا غيرت الأداة، وهي ما يجعل تغيير الأداة نفسه سهلاً. وفي مقال الفايب كودنج ذكرنا حوادث موثقة غير فيها الوكيل ما لم يطلب منه، وكان الرجوع فيها ممكناً أو مستحيلاً بحسب ما كان محفوظاً قبلها.

لا تدع الوكيل يعمل على main

القاعدة الأولى أبسطها وأكثرها نسياناً، والسبب أن أغلب الوكلاء يعملون على الفرع الذي أنت فيه دون أن يسألوا، فإذا فتحت الطرفية على main وشغلت الوكيل فإن كل commit يعمله يدخل إلى main مباشرة. وAider مثلاً يعمل commit بعد كل تعديل يطبقه بحسب صفحة Git في توثيقه، أي أن تعديلاته تصبح جزءاً من الفرع الذي أنت فيه قبل أن تقرأها.

والفرع للمهمة يعطيك ثلاثة أشياء: تستطيع أن تقارنه بـ main بأمر واحد لترى كل ما فعله الوكيل، وتستطيع أن تحذفه كله إذا لم يعجبك دون أن تلمس أي شيء آخر، وتستطيع أن تدمجه كـ commit واحد أو كما هو بحسب سياسة فريقك. واجعل اسم الفرع يقول إنه عمل وكيل، مثل agent/rename-slug، حتى تعرف من القائمة أي الفروع تحتاج مراجعة أدق.

فرع وWorktree لكل مهمة: وكيلان دون تصادم

الفرع وحده لا يكفي إذا أردت أن تشغل وكيلين في الوقت نفسه، لأن مجلد العمل Working Directory واحد، والفرع الذي فيه واحد في أي لحظة. والحل هو git worktree، وهو كما في توثيق git worktree مجلد عمل إضافي مرتبط بالمستودع نفسه، له فرعه وملفاته الخاصة، ويشترك مع المجلد الرئيسي في تاريخ Git والكائنات Objects، فلا تنسخ المستودع ولا تضاعف حجمه.

والفكرة أن كل وكيل يعمل في مجلده الخاص، فلا يرى ملفات الآخر وهي في منتصف التعديل، ولا يشغل اختباراته على كود غيره. وهذه الطريقة هي التي تتبعها الأدوات نفسها اليوم: فـ Claude Code يعطيك الخيار -w ليبدأ جلسة في Worktree جديدة بحسب توثيق أفضل الممارسات، ويذكر التوثيق أن الـ Worktree نسخة جديدة لا تحتوي الملفات المتجاهلة مثل .env ولا الاعتماديات المثبتة، وأن الأمر /batch يقسم التغيير الكبير إلى وحدات لكل منها Worktree خاصة. وفي أداتي الطرفية Codex CLI بالإصدار 0.170.0 وOpenCode بالإصدار 2.3.2 خيار اسمه --worktree في أمر التشغيل دون واجهة، يبدأ الجلسة في Worktree جديدة، كما يظهر في codex exec --help وopencode run --help. وCline يحفظ نقاط الرجوع Checkpoints في مستودع ظل منفصل كما شرحنا في مقال الوكلاء مفتوحة المصدر.

ثلاثة مجلدات: blog على الفرع main، وblog-slug-length على الفرع agent/slug-length، وblog-rename على الفرع agent/rename، ولكل منها طرفية، وكلها متصلة بخطوط متقطعة بصندوق أسود مكتوب عليه blog/.git مشترك فيه الكائنات والفروع والخطاف pre-commit الذي يعمل لكل Worktree، وتحته سطران عن أن كل وكيل يرى ملفات مجلده فقط وأن الملفات المتجاهلة لا تنسخ
مستودع واحد بمجلدات عمل منفصلة: كل وكيل في مجلده، والتاريخ والخطافات مشتركة.

والأوامر الأساسية ثلاثة، وسوف نشغلها في المختبر:

# A new branch agent/fix-x checked out in a sibling folder ../blog-fix-x
git worktree add -b agent/fix-x ../blog-fix-x

# Every worktree, its commit and its branch
git worktree list

# When the task is merged or dropped: remove the folder, then the branch
git worktree remove ../blog-fix-x
git branch -D agent/fix-x

ولاحظ في الأوامر أعلاه التالي:

  • الفرع الواحد لا يكون في Worktree اثنتين في الوقت نفسه، وGit يرفض ذلك، وهذا بالضبط ما يحميك من وكيلين على الفرع نفسه.
  • الخطافات Hooks في .git/hooks مشتركة بين كل الـ Worktrees لأنها جزء من المستودع، أما الملفات المتجاهلة والاعتماديات فلكل مجلد نسخته.
  • الأمر git worktree remove يرفض أن يحذف مجلداً فيه تعديلات لم تحفظ، وهذا يحميك من أن تحذف عمل وكيل لم تراجعه.
⚠️
الـ Worktrees تفصل الملفات ولا تفصل التعارض Conflict، فإذا عدل وكيلان الدالة نفسها في فرعين فسوف يظهر التعارض عند الدمج. قسم المهام بحيث لا يلمس وكيلان الملف نفسه في الوقت نفسه، أو ادمج واحداً قبل أن تبدأ الآخر.

الـ commit الصغير ورسالته: من كتب ماذا ولماذا؟

الـ commit الصغير هو الذي يغير شيئاً واحداً، تستطيع أن تصفه في سطر، وتقرأ فرقه في دقيقة، وترجع عنه دون أن تخسر شيئاً آخر. ومع الوكيل تصبح هذه القاعدة أهم، لأن الوكيل لا يتعب ولا يتوقف من نفسه، فإذا أعطيته ثلاث مهام في طلب واحد فإنه يكتب الثلاث في commit واحد، وعندما تكتشف أن واحدة منها خاطئة لا تستطيع أن ترجع عنها وحدها. ولذلك فإن حجم الـ commit يبدأ من حجم الطلب: طلب واحد لتغيير واحد، وهذا ما شرحناه في المختبر وفي مقالات هذه المرحلة.

أما الرسالة فأشهر صيغة لها اليوم هي Conventional Commits، وهي سطر أول بالشكل type(scope): description، حيث النوع مثل feat لميزة جديدة وfix لإصلاح خطأ وrefactor لإعادة الهيكلة، ثم سطر فارغ، ثم شرح اختياري، ثم سطور التذييل Trailers في آخر الرسالة. وفائدة هذه الصيغة مع الوكيل أنها تجعل تاريخ Git قابلاً للبحث والفرز: تستطيع أن ترى كل الإصلاحات بأمر واحد، وأن تولد ملاحظات الإصدار Release Notes منها، وأن تعرف من أول كلمة هل غير الوكيل سلوك النظام أم شكل الكود فقط. وAider يكتب رسائله بهذه الصيغة افتراضياً كما سوف نرى.

والجزء الأهم في الرسالة مع الوكيل هو سطور التذييل، فهي المكان المعتمد في Git لبيانات إضافية مثل من شارك في الكود، كما في توثيق git interpret-trailers. وأشهرها Co-authored-by الذي يعرضه GitHub كمؤلف مشارك، وتضيفه أدوات كثيرة باسمها واسم النموذج، فتعرف بعد سنة أي التعديلات كتبها الوكيل وبأي نموذج. وشرحنا لماذا يجب أن يكون هذا الإفصاح قاعدة في الفريق، ومن يتحمل المسؤولية عن الكود، في مقال سياسة الفريق لاستخدام الذكاء الاصطناعي، فلا نكرره هنا، ونركز على كيف تستعمله في العمل اليومي.

والمثال التالي رسالة كاملة بهذا الشكل:

feat(slug): add optional max_length to make_slug

Cuts the slug at max_length characters and drops a trailing hyphen.
Reviewed and tested by the developer before merge.

Co-authored-by: aider (ollama_chat/qwen2.5-coder:3b) <[email protected]>

وفي الرسالة أعلاه لاحظ التالي:

  • النوع feat والنطاق slug يخبرانك من السطر الأول أن هذا سلوك جديد في وحدة معينة.
  • سطر التذييل في آخر الرسالة بعد سطر فارغ، وهذا شرط حتى يقرأه Git كتذييل وليس كجزء من النص.
  • Git يستطيع أن يستخرج التذييلات وحدها بالصيغة %(trailers) في git log، فتعرف من التاريخ كله أي الـ commits كتبها وكيل، وسوف نشغل ذلك في المختبر.

كيف تراجع فرق الوكيل قبل أن تدمجه؟

المراجعة تبدأ من الصورة الكبيرة ثم تنزل إلى التفاصيل، وثلاثة أوامر تكفي في الغالب، وكلها تقارن الفرع بـ main دون أن تحتاج أي أداة أخرى:

# 1. What did the agent commit on its branch, and who is listed as author?
git log --format='%h %an | %s' main..agent/slug-length

# 2. Which files changed and how much (three dots: since the branch left main)
git diff --stat main...agent/slug-length

# 3. The full change, one commit at a time, with its message
git log -p main..agent/slug-length

وفي الأوامر أعلاه لاحظ التالي:

  • النقطتان في main..agent/slug-length تعنيان الـ commits الموجودة في الفرع وليست في main، أي عمل الوكيل فقط.
  • النقاط الثلاث في git diff main...agent/slug-length تقارن الفرع بالنقطة التي خرج منها من main، فلا ترى تغييرات دخلت main بعد ذلك على أنها من الوكيل.
  • ابدأ دائماً بـ --stat، فإذا رأيت ملفاً لا علاقة له بالمهمة فهذه أول ملاحظة، ولا داعي أن تقرأ التفاصيل قبل أن تعرف لماذا تغير.
ثلاث نوافذ طرفية من المختبر: الأولى git log مع سطر التذييل Co-authored-by تظهر commitين باسم Lab Developer وتحت كل منهما aider مع اسم النموذج، والثانية git diff --stat تظهر slug.py بعشرة أسطر وtest_textkit.py باثنين وستين سطراً بالأحمر، والثالثة python -m unittest تظهر AssertionError و FAILED، وتحت كل نافذة سطر يشرح ما تبحث عنه
ثلاثة أوامر من المختبر قبل أن تقرأ الكود: من كتب، وأي الملفات وكم، وهل تنجح الاختبارات فعلاً.

وبعد الأوامر يأتي السؤال الذي لا يجيب عنه Git: هل يفعل الكود ما تقوله الرسالة؟ والطريقة أن تشغل الاختبارات بنفسك على الفرع، وألا تعتمد على أن الوكيل قال إنها نجحت، ثم تقرأ الفرق بالقائمة التي شرحناها في مقال مراجعة كود الذكاء الاصطناعي، وفيها ما يخص كود الوكيل من أخطاء متكررة.

الرجوع الآمن: أي أمر لأي خطأ؟

شرحنا الفرق بين أوامر الرجوع بالتفصيل في مقال التراجع عن الأخطاء في Git، وما يهمنا هنا هو أي أمر يناسب أي موقف مع الوكيل:

الموقفالأمرلماذا
آخر commit للوكيل خاطئ ولم تشاركه مع أحد/undo في Aider في الجلسة نفسها، أو git reset --hard HEAD~1 على فرع الوكيليحذف الـ commit من الفرع كأنه لم يحدث، وهذا مقبول على فرع لم يدفع Push بعد
commit خاطئ دخل فرعاً مشتركاً أو maingit revert <commit>يضيف commit جديداً يعكس التغيير، ولا يعيد كتابة تاريخ يعتمد عليه غيرك
الفرع كله لا يصلحgit worktree remove ثم git branch -Dتحذف عمل المهمة كله دون أن يلمس main شيء
شيء توقف عن العمل ولا تعرف أي commit سببهgit bisect run مع أمر الاختباراتيبحث بالتنصيف بين الـ commits ويشغل الاختبار في كل خطوة حتى يجد أول commit خاطئ
حذفت شيئاً بـ reset --hard بالخطأgit reflog ثم git reset --hard HEAD@{n}Git يحفظ أين كان كل فرع في كل لحظة لمدة من الزمن، حتى الـ commits التي لم تعد في أي فرع
خمسة صفوف لكل منها سؤال وأمر: آخر commit للوكيل خاطئ والفرع لم يشارك مع undo وgit reset، وcommit خاطئ في فرع مشترك مع git revert، والفرع كله لا يصلح مع git worktree remove وgit branch -D، وشيء توقف ولا تعرف متى مع git bisect run، وحذفت شيئاً بـ reset hard مع git reflog
ابدأ من الموقف ثم اختر الأمر: الرجوع على فرعك يختلف عن الرجوع على فرع يشاركك فيه غيرك.

والقاعدة التي تربط الجدول: كلما كان الـ commit أصغر كان الرجوع أسهل وأدق، فـ git revert لـ commit فيه تغيير واحد يرجع هذا التغيير فقط، أما لـ commit فيه ثلاث مهام فيرجع الثلاث، وgit bisect يجد لك الـ commit الخاطئ، ولكنه لا يخبرك أي جزء منه هو الخاطئ.

الخطاف pre-commit: فحص لا يعتمد على الوكيل

الخطاف Hook في Git سكربت يشغله Git بنفسه عند حدث معين، وأشهرها pre-commit الذي يعمل قبل كل commit، فإذا خرج برمز غير الصفر رفض Git الـ commit، كما في توثيق githooks. وشرحنا كيف تبنيه بأداة pre-commit في مقال Git Hooks. ومع الوكيل يبدو الخطاف الحل المثالي: الوكيل يعمل commit لكل تعديل، والخطاف يشغل الاختبارات قبل كل commit، فلا يدخل التاريخ شيء يوقف المشروع عن العمل.

ولكن هناك تفصيلاً صغيراً يغير كل شيء: Git نفسه يسمح بتجاوز الخطاف بالخيار --no-verify، وبعض الوكلاء يستعملون هذا الخيار افتراضياً. ففي صفحة الخيارات في توثيق Aider خيار اسمه --git-commit-verify وصفه أنه يفعل أو يعطل خطافات pre-commit مع --no-verify، والقيمة الافتراضية False، أي أن Aider يعمل الـ commit متجاوزاً خطافاتك ما لم تطلب غير ذلك. وقرأنا هذا في التوثيق، ثم تأكدنا منه في المختبر كما سيأتي، لأن الفرق بين ما تظن أن الخطاف يفعله وما يفعله فعلاً هو بالضبط نوع المفاجآت التي يجب أن تكتشفها قبل أن تعتمد عليه.

والقاعدة من هذا: الفحص الذي لا يجوز تجاوزه يكون في مكان لا يملك الوكيل أن يتجاوزه، أي في خط CI على الخادم، أو في حماية الفرع Branch Protection التي ترفض الدمج إذا فشل الفحص. أما الخطاف المحلي فهو طبقة مفيدة توفر عليك دورة كاملة، ولكن تأكد أن أداتك لا تتجاوزه، وشرحنا بناء البوابات في خط CI في مقال خط CI/CD الآمن.

المختبر: وكيلان في Worktreeين، وخطاف، وcommit خاطئ

لنرى هذه القواعد تعمل، أو لا تعمل، بنينا مستودعاً صغيراً لمدونة فيه ثلاثة ملفات: slug.py فيه دالة make_slug تحول عنوان المقال إلى رابط، وreport.py يستدعيها ليبني روابط الأرشيف، وtest_textkit.py فيه ثلاثة اختبارات. وشغلنا عليه Aider 0.86.2 مع نموذج qwen2.5-coder:3b على Ollama 0.40.13 على معالج دون بطاقة رسومية، وGit 2.47.3، وكل الأوامر وكل المخرجات في هذا القسم من التشغيل نفسه.

وأول ما فعلناه بعد أول commit أننا أضفنا خطاف pre-commit يكتب سطراً في ملف كلما عمل، ثم يشغل الاختبارات ويرفض الـ commit إذا فشلت:

#!/bin/sh
# Log every run, then refuse the commit if the tests fail.
echo "pre-commit ran in $(basename "$PWD") at $(date +%T)" >> /runs/hook.log
python -m unittest -q 2>/dev/null || { echo "pre-commit: tests failed, commit refused"; exit 1; }

ثم أنشأنا Worktree لكل مهمة، بفرع لكل واحدة:

$ git worktree add -b agent/slug-length ../blog-slug-length
Preparing worktree (new branch 'agent/slug-length')
HEAD is now at 8ab62dd chore: initial blog text kit
$ git worktree add -b agent/rename ../blog-rename
Preparing worktree (new branch 'agent/rename')
HEAD is now at 8ab62dd chore: initial blog text kit
$ git worktree list
/runs/blog              8ab62dd [main]
/runs/blog-rename       8ab62dd [agent/rename]
/runs/blog-slug-length  8ab62dd [agent/slug-length]

في المخرج أعلاه لاحظ التالي:

  • كل Worktree بدأت من الـ commit نفسه 8ab62dd، وكل واحدة على فرعها، والمجلد الرئيسي بقي على main.
  • عندما بدأ Aider في المجلد الأول كتب في أول سطوره Git repo: ../blog/.git/worktrees/blog-slug-length، أي أنه عرف أنه داخل Worktree مرتبطة بالمستودع الأصلي، ولم يحتج أي إعداد إضافي.

المهمة الأولى: خيار max_length، وcommit لاختبار خاطئ

في المجلد الأول طلبنا من الوكيل أن يضيف وسيطاً اختيارياً max_length يقص الرابط دون أن يترك شرطة في آخره، وأن يضيف اختباراً، مع الملفين في المحادثة. والكود الذي كتبه للدالة معقول:

def make_slug(title, max_length=None):
    """Lower-case words joined by hyphens: 'Hello World!' -> 'hello-world'."""
    words = re.findall(r"[a-z0-9]+", title.lower())
    slug = "-".join(words)
    if max_length is not None:
        if len(slug) > max_length:
            slug = slug[:max_length]
            if slug.endswith("-"):
                slug = slug[:-1]
    return slug

أما الاختبارات فدخلت في الحلقة التي رأيناها في مقالات المسار: سطر بعد سطر يتوقع hello-world لكل طول من 11 إلى 61، حتى انقطع الملف عند حد طول الرد، فعمل Aider له commit، ثم أمسك خطأ الصياغة، ثم أصلحه الوكيل في commit ثان. وبعد 667 ثانية كان تاريخ الفرع كما يلي، ومعه نتيجة الاختبارات التي شغلناها نحن:

$ git log --format='%h %an | %s' main..HEAD
1f6222f Lab Developer | fix: close syntax error in test_textkit.py
bc64550 Lab Developer | feat(slug.py): add optional max_length argument to make_slug
$ python -m unittest -q
FAIL: test_make_slug_with_max_length (test_textkit.TextkitTest.test_make_slug_with_max_length)
...
    self.assertEqual(make_slug("Hello World!", 10), "hello-world")
AssertionError: 'hello-worl' != 'hello-world'
...
Ran 4 tests in 0.004s
FAILED (failures=2)

في المخرج أعلاه لاحظ التالي:

  • الدالة صحيحة، والاختبار هو الخاطئ: يتوقع رابطاً من أحد عشر حرفاً بحد أقصى عشرة. وهذا تذكير بأن الاختبار الذي يكتبه الوكيل يحتاج مراجعة مثل الكود، كما شرحنا في مقال الاختبار أولاً.
  • الوكيل أضاف السطر الخاطئ نفسه إلى الاختبار القديم test_slug أيضاً، فأصبح اختبار كان يعمل قبل المهمة يفشل بعدها.
  • اسم المؤلف في الـ commits هو اسمنا Lab Developer، لأن Aider في هذا الإصدار يضيف سطر Co-authored-by افتراضياً بدل تغيير اسم المؤلف، كما سنرى في المراجعة.

المهمة الثانية: إعادة تسمية في ملف واحد

في المجلد الثاني أعطينا الوكيل الملف slug.py وحده، وطلبنا أن يعيد تسمية make_slug إلى slugify. وهذه مهمة يعطيها المطور للوكيل كل يوم، لأنها تبدو آلية لا تحتاج تفكيراً:

-def make_slug(title):
+def slugify(title):
Tokens: 852 sent, 68 received.
Applied edit to slug.py
Commit b06fb01 refactor: rename make_slug to slugify
== agent elapsed 54 s
$ python -m unittest -q
ImportError: Failed to import test module: test_textkit
...
  File "/runs/blog-rename/report.py", line 2, in <module>
    from slug import make_slug
ImportError: cannot import name 'make_slug' from 'slug' (/runs/blog-rename/slug.py)
Ran 1 test in 0.000s
FAILED (errors=1)

في المخرج أعلاه لاحظ التالي:

  • في أقل من دقيقة، وبـ 68 توكناً فقط، عمل الوكيل commit برسالة صحيحة تماماً بصيغة Conventional Commits، والمشروع كله لا يعمل بعده: report.py ما زال يستورد الاسم القديم، فلا يستطيع مشغل الاختبارات أن يحمل ملف الاختبارات أصلاً.
  • السبب ليس غباء النموذج، وإنما أن Aider لا يعدل إلا الملفات التي في المحادثة، ونحن أعطيناه ملفاً واحداً. وهذا خطأ في الطلب لا في الوكيل، ويحدث مع الأدوات التي تبحث بنفسها أيضاً إذا كان الاستدعاء بطريقة لا يجدها البحث.
  • الخطاف الذي أضفناه كان يجب أن يرفض هذا الـ commit لأن الاختبارات تفشل، ولكن هذا لم يحدث.

والدليل على الأخير هو الملف الذي يكتب فيه الخطاف سطراً كلما عمل، بعد ثلاثة commits من الوكيل في Worktreeين:

$ cat /runs/hook.log
cat: /runs/hook.log: No such file or directory

الملف غير موجود، أي أن الخطاف لم يعمل ولا مرة واحدة، وهذا بالضبط ما يقوله توثيق Aider عن القيمة الافتراضية للخيار --git-commit-verify. فالوكيل يعمل commits تمر من خطافاتك دون أن تعرف، والـ commit الذي يترك المشروع لا يعمل دخل الفرع بلا أي اعتراض. وبعد أن نراجع الفرعين نعيد المهمة نفسها بخيار واحد مختلف، لنرى هل يتغير شيء.

المراجعة من main: من كتب ماذا؟

قبل أن نصلح أي شيء راجعنا الفرعين من المجلد الرئيسي بالأوامر التي ذكرناها، وأضفنا إلى git log سطر التذييل Co-authored-by وحده بالصيغة %(trailers):

$ git log --format='%h %an | %s%n         %(trailers:key=Co-authored-by,valueonly)' main..agent/slug-length
1f6222f Lab Developer | fix: close syntax error in test_textkit.py
         aider (ollama_chat/qwen2.5-coder:3b) <[email protected]>
bc64550 Lab Developer | feat(slug.py): add optional max_length argument to make_slug
         aider (ollama_chat/qwen2.5-coder:3b) <[email protected]>
$ git diff --stat main...agent/slug-length
 slug.py         | 10 ++++++++--
 test_textkit.py | 62 ++++++++++++++++++++++++++++++++++++++++++++++++++++++---
 2 files changed, 67 insertions(+), 5 deletions(-)
$ git diff --stat main...agent/rename
 slug.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

في المخرج أعلاه لاحظ التالي:

  • المؤلف في كل commit هو المطور، وسطر التذييل يقول إن الكود من Aider وبأي نموذج بالضبط، وهذا ما يجعل البحث في التاريخ ممكناً بعد سنة: كل ما كتبه الوكيل بنموذج معين يخرج بأمر واحد.
  • أول سطر في --stat للفرع الأول يكفي ليثير السؤال: 62 سطراً في ملف الاختبارات لميزة من عشرة أسطر. وهذا بالضبط ما وجدناه، اختبارات متكررة وخاطئة.
  • الفرع الثاني تغيير من سطر واحد في ملف واحد، ويبدو أنظف فرق يمكن أن تراجعه، وهو الذي أوقف المشروع كله. أي أن صغر الفرق لا يغني عن تشغيل الاختبارات، وإنما يجعل فهم سبب الفشل سريعاً.

المهمة نفسها مع --git-commit-verify

ثم أعدنا مهمة إعادة التسمية بالطلب نفسه والملف نفسه، في Worktree ثالثة جديدة، والفرق الوحيد أننا أضفنا الخيار --git-commit-verify حتى لا يتجاوز Aider الخطافات:

$ git worktree add -b agent/rename-verify ../blog-rename-verify
...
Tokens: 852 sent, 68 received.
Applied edit to slug.py
Unable to commit: Cmd('git') failed due to: exit code(1)
  cmdline: git commit -m refactor: rename make_slug to slugify
Co-authored-by: aider (ollama_chat/qwen2.5-coder:3b) <[email protected]> -- /runs/blog-rename-verify/slug.py
  stderr: 'pre-commit: tests failed, commit refused'
Unable to commit: Cmd('git') failed due to: exit code(1)
  cmdline: git commit -m fix: update function name to `slugify`
...
  stderr: 'pre-commit: tests failed, commit refused'
== agent elapsed 137 s
$ git log --format='%h %an | %s' main..HEAD
$ git status --short
M  slug.py
$ cat /runs/hook.log
pre-commit ran in blog-rename-verify at 03:55:14
pre-commit ran in blog-rename-verify at 03:55:24

في المخرج أعلاه لاحظ التالي:

  • النموذج كتب التعديل نفسه حرفاً بحرف، 68 توكناً، لأن الحرارة صفر والطلب نفسه.
  • هذه المرة عمل الخطاف مرتين، وكتب سطرين في hook.log، ورفض الـ commit في المرتين لأن الاختبارات فشلت، ونقل Git رسالة الخطاف إلى Aider فطبعها.
  • حاول Aider مرة ثانية برسالة أخرى، ورفضها الخطاف أيضاً، ثم انتهى. فالفرع لا يحتوي أي commit من الوكيل، والتعديل ما زال في الملف وفي منطقة التحضير Staging Area بعلامة M، تراه وتقرر فيه بنفسك.
  • الفرق بين التشغيلين خيار واحد في سطر الأوامر. والقاعدة التي نخرج بها: اكتب git-commit-verify: true في ملف إعدادات Aider للمشروع .aider.conf.yml، أو ما يقابله في أداتك، حتى لا يعتمد على ذاكرة كل مطور.

الرجوع عن الـ commit الخاطئ بـ git revert

بقي الـ commit الخاطئ في الفرع agent/rename، ولنفترض أن هذا الفرع شاركه المطور مع زميل أو دفعه إلى الخادم، فالرجوع الصحيح هنا git revert لا reset:

$ git revert --no-edit HEAD
[agent/rename 3da42df] Revert "refactor: rename make_slug to slugify"
 Date: Fri Nov 20 03:55:26 2026 +0000
 1 file changed, 1 insertion(+), 1 deletion(-)
$ git log --format='%h %an | %s' main..HEAD
3da42df Lab Developer | Revert "refactor: rename make_slug to slugify"
b06fb01 Lab Developer | refactor: rename make_slug to slugify
$ python -m unittest -q
----------------------------------------------------------------------
Ran 3 tests in 0.000s

OK

ولاحظ أن التاريخ احتفظ بالـ commit الخاطئ وبالـ commit الذي يعكسه، فمن يقرأ الفرع بعد ذلك يعرف ماذا حدث، ومن سحب الفرع قبل ذلك لا يجد تاريخه مختلفاً عن الخادم. ولأن الـ commit الخاطئ كان تغييراً واحداً في سطر واحد فإن الرجوع عنه لم يأخذ معه أي شيء آخر.

ثلاث مهام دون اختبار، ثم git bisect يجد المذنب

في الواقع لا تكتشف الخطأ دائماً بعد الـ commit مباشرة، فقد يعمل الوكيل عدة مهام متتالية على فرع واحد، ثم تكتشف في النهاية أن شيئاً توقف. ولنرى ذلك أنشأنا Worktree رابعة agent/batch، وأعطينا الوكيل فيها ثلاث مهام متتالية دون أن يشغل الاختبارات: دالة جديدة reading_time في report.py، ثم إعادة التسمية نفسها في slug.py وحده، ثم توثيق كل الدوال في report.py. وكانت النتيجة ثلاثة commits مرتبة في أقل من ست دقائق:

$ git log --format='%h %an | %s' main..HEAD
38d5675 Lab Developer | refactor: Add docstrings to every function in report.py that does not have one.
71dd047 Lab Developer | refactor: rename make_slug to slugify
d65a725 Lab Developer | feat(report.py): add reading_time function
$ python -m unittest -q
...
ERROR: test_textkit (unittest.loader._FailedTest.test_textkit)
ImportError: Failed to import test module: test_textkit
ImportError: cannot import name 'make_slug' from 'slug' (/runs/blog-batch/slug.py)
FAILED (errors=1)

في حالة كهذه فيها ثلاثة commits يسهل أن تجد المذنب بالعين، ولكن في فرع فيه ثلاثون commit من الوكيل لا يمكن ذلك، وهنا يأتي git bisect، الذي يبحث بالتنصيف بين commit تعرف أنه سليم وcommit تعرف أنه خاطئ، كما في توثيق git bisect. ومع git bisect run لا تحتاج أن تختبر بنفسك، فـ Git يشغل الأمر الذي تعطيه في كل خطوة، ويعتبر رمز الخروج صفر سليماً وغيره خاطئاً:

$ git bisect start HEAD main
Bisecting: 0 revisions left to test after this (roughly 1 step)
[71dd047766d0c3db1b779d42fe02dd6f2b8896a4] refactor: rename make_slug to slugify
$ git bisect run python -m unittest -q
running 'python' '-m' 'unittest' '-q'
...
ImportError: cannot import name 'make_slug' from 'slug' (/runs/blog-batch/slug.py)
FAILED (errors=1)
Bisecting: 0 revisions left to test after this (roughly 0 steps)
[d65a72510ae4532a4654347452012e1d8cffe00b] feat(report.py): add reading_time function
running 'python' '-m' 'unittest' '-q'
Ran 3 tests in 0.000s
OK
71dd047766d0c3db1b779d42fe02dd6f2b8896a4 is the first bad commit
commit 71dd047766d0c3db1b779d42fe02dd6f2b8896a4
Author: Lab Developer <[email protected]>
Date:   Fri Nov 20 03:58:28 2026 +0000
...
 slug.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
bisect found first bad commit
$ git bisect reset
Previous HEAD position was d65a725 feat(report.py): add reading_time function
Switched to branch 'agent/batch'

في المخرج أعلاه لاحظ التالي:

  • بدأ Git من منتصف المسافة، أي من الـ commit الثاني، فشغل الاختبارات وفشلت، ثم رجع إلى الأول فنجحت، فعرف أن الثاني هو أول commit خاطئ، في خطوتين.
  • الحكم هنا هو الأمر نفسه الذي يشغله الوكيل والخطاف، فإذا كان عندك أمر اختبار واحد للمشروع فإنه يخدمك في كل مكان: في طلب الوكيل، وفي الخطاف، وفي bisect، وفي خط CI.
  • لأن كل commit تغيير واحد، فإن bisect لم يجد commit فقط وإنما وجد السبب: فرق من سطر واحد في slug.py. لو كانت المهام الثلاث في commit واحد لوجد bisect ذلك الـ commit، وبقي عليك أن تبحث داخله.
  • بعد أن تعرف المذنب ترجع عنه وحده بـ git revert 71dd047، فتبقى الدالة الجديدة والتوثيق كما هما.

الدمج في main: الخطاف الذي تجاوزه الوكيل يحمي الدمج

بقي الفرع الأول agent/slug-length، وفيه دالة صحيحة واختبارات خاطئة. ولنرى ماذا يحدث لمن لا يقرأ نتيجة الاختبارات، جربنا أن ندمجه في main كـ commit واحد بالطريقة التي اقترحناها، أي git merge --squash ثم commit برسالة نكتبها نحن وسطر الإفصاح بالخيار --trailer:

$ git merge --squash agent/slug-length
Updating 8ab62dd..1f6222f
Fast-forward
Squash commit -- not updating HEAD
 slug.py         | 10 ++++++++--
 test_textkit.py | 62 ++++++++++++++++++++++++++++++++++++++++++++++++++++++---
 2 files changed, 67 insertions(+), 5 deletions(-)
$ git commit -q -m 'feat(slug): add optional max_length to make_slug' --trailer 'Co-authored-by: aider (ollama_chat/qwen2.5-coder:3b) <[email protected]>'
pre-commit: tests failed, commit refused
$ git log --format='%h %an | %s%n         %(trailers:key=Co-authored-by,valueonly)' -2
8ab62dd Lab Developer | chore: initial blog text kit

في المخرج أعلاه لاحظ التالي:

  • الخطاف نفسه الذي تجاوزه الوكيل في الفرع عمل هنا، لأن الـ commit هذه المرة من git commit العادي، فرفض الدمج لأن الاختبارين الخاطئين يفشلان. أي أن الطبقة التي لم تحم الفرع حمت main.
  • آخر commit في main ما زال الأول، والتغييرات في منطقة التحضير تنتظر قرارك: تصلح الاختبارين ثم تعمل الـ commit، أو تلغي الدمج.
  • الخيار --trailer في git commit يضيف سطر التذييل في مكانه الصحيح دون أن تكتبه يدوياً، وهو موجود في Git منذ الإصدار 2.32.

الأمر /undo يعرف الجلسة فقط، وreflog يعرف كل شيء

ثم جربنا الأمر /undo الذي يذكره توثيق Aider لحذف آخر commit عمله، في Worktree المهام الثلاث، بعد انتهاء الجلسة التي عملت فيها الـ commits:

$ git log --oneline -1
38d5675 refactor: Add docstrings to every function in report.py that does not have one.
The last commit was not made by aider in this chat session.
You could try `/git reset --hard HEAD^` but be aware that this is a destructive
command!

أي أن /undo يرجع فقط عن commits الجلسة الحالية، والـ commit الذي عمله Aider نفسه في جلسة سابقة لا يعرفه. وهذا منطقي، لأن الأداة لا تريد أن تحذف شيئاً لا تعرف من كتبه، ولكنه يعني أن /undo أداة للدقائق الأولى بعد التعديل، وأن الرجوع بعد ذلك يكون بأوامر Git نفسها.

واقتراح Aider نفسه، أي reset --hard، هو الأمر الذي يخاف منه المطورون، فلنجرب أسوأ حالة: رجعنا خطوة بالخطأ وحذفنا commit التوثيق من الفرع، ثم أعدناه بـ git reflog، كما في توثيق git reflog:

$ git reset --hard HEAD~1
HEAD is now at 71dd047 refactor: rename make_slug to slugify
$ git reflog -4
71dd047 HEAD@{0}: reset: moving to HEAD~1
38d5675 HEAD@{1}: checkout: moving from d65a72510ae4532a4654347452012e1d8cffe00b to agent/batch
d65a725 HEAD@{2}: checkout: moving from 71dd047766d0c3db1b779d42fe02dd6f2b8896a4 to d65a72510ae4532a4654347452012e1d8cffe00b
71dd047 HEAD@{3}: checkout: moving from agent/batch to 71dd047766d0c3db1b779d42fe02dd6f2b8896a4
$ git reset --hard HEAD@{1}
HEAD is now at 38d5675 refactor: Add docstrings to every function in report.py that does not have one.

في المخرج أعلاه لاحظ التالي:

  • الـ reflog سجل كل حركة للـ HEAD في هذه الـ Worktree، بما فيها خطوات git bisect السابقة، وكل سطر فيه رقم الـ commit الذي كان عليه.
  • السطر HEAD@{1} هو المكان قبل الخطأ مباشرة، فالرجوع إليه أعاد الـ commit المحذوف كما كان.
  • الـ reflog محلي في جهازك، ويحفظ لمدة محدودة، فهو شبكة أمان للأخطاء القريبة، لا بديل عن الفرع والـ commit.

التنظيف: Git يرفض أن يحذف عملاً لم تحفظه

وفي النهاية حذفنا الـ Worktrees والفروع التي انتهت:

$ git worktree list
/runs/blog                8ab62dd [main]
/runs/blog-batch          38d5675 [agent/batch]
/runs/blog-rename         3da42df [agent/rename]
/runs/blog-rename-verify  8ab62dd [agent/rename-verify]
/runs/blog-slug-length    1f6222f [agent/slug-length]
$ git worktree remove ../blog-rename-verify
fatal: '../blog-rename-verify' contains modified or untracked files, use --force to delete it
$ git worktree remove --force ../blog-rename-verify
$ git worktree remove ../blog-rename
$ git branch -D agent/rename agent/rename-verify
Deleted branch agent/rename (was 3da42df).
Deleted branch agent/rename-verify (was 8ab62dd).

ولاحظ السطر fatal: الـ Worktree التي رفض فيها الخطاف الـ commit ما زال فيها تعديل الوكيل في منطقة التحضير، فرفض Git أن يحذفها حتى قلنا له --force. وهذه حماية حقيقية، فإذا رأيت هذه الرسالة فاسأل نفسك أولاً: هل في هذا المجلد شيء لم أراجعه؟

ثلاثة صفوف لثلاث محاولات commit: Aider بالإعداد الافتراضي يعمل commit لإعادة التسمية مع no-verify والخطاف لم يعمل وملف hook.log غير موجود والـ commit دخل الفرع والمشروع لا يعمل، وAider مع git-commit-verify الخطاف عمل مرتين ورفض والتعديل بقي في منطقة التحضير، والمطور يدمج بـ merge squash ثم git commit الخطاف عمل ورفض الدمج إلى main لأن الاختبارات تفشل
الخطاف نفسه في ثلاث حالات: تجاوزه الوكيل افتراضياً، ثم عمل عندما طلبنا، ثم حمى main عند الدمج.

وكيلان عدلا السطر نفسه: التعارض عند الدمج

قلنا في أول المقال إن الـ Worktrees تفصل الملفات ولا تفصل التعارض، ولنره بمخرج حقيقي: الفرع agent/slug-length غير توقيع make_slug ليضيف الوسيط الجديد، والفرع agent/batch أعاد تسميتها إلى slugify، وكلاهما عمل في مجلده دون أن يعرف بالآخر. فإذا جمعناهما في فرع واحد في نسخة مؤقتة من المستودع:

$ git switch -c integration
Switched to a new branch 'integration'
$ git merge --no-edit agent/slug-length
Fast-forward
 slug.py         | 10 ++++++++--
 test_textkit.py | 62 ++++++++++++++++++++++++++++++++++++++++++++++++++++++---
 2 files changed, 67 insertions(+), 5 deletions(-)
$ git merge --no-edit agent/batch
Auto-merging slug.py
CONFLICT (content): Merge conflict in slug.py
Automatic merge failed; fix conflicts and then commit the result.
$ git status --short
M  report.py
UU slug.py
$ sed -n 1,20p slug.py
"""URL slugs for blog posts."""
import re


<<<<<<< HEAD
def make_slug(title, max_length=None):
=======
def slugify(title):
>>>>>>> agent/batch
    """Lower-case words joined by hyphens: 'Hello World!' -> 'hello-world'."""

في المخرج أعلاه لاحظ التالي:

  • الدمج الأول كان Fast-forward لأن الفرع خرج من main ولم يتغير main بعده، والثاني اصطدم بالأول في سطر التعريف نفسه.
  • Git دمج report.py وحده دون مشكلة، بعلامة M، لأن التغييرين فيه لا يتقاطعان، وأوقف slug.py بعلامة UU حتى تقرر أنت.
  • والقرار هنا ليس آلياً: هل نريد الاسم الجديد مع الوسيط الجديد؟ وهل غير أحد الوكيلين ما يستدعي الدالة؟ وهذا القرار بالذات لا تعطه للوكيل دون أن تقرأ الفرعين، لأن كل وكيل يعرف نصف القصة فقط.
  • والطريقة التي كانت تمنع هذا من البداية أن تقسم المهام بحيث لا يلمس وكيلان الدالة نفسها في الوقت نفسه، أو أن تدمج الأول قبل أن تبدأ الثاني من main الجديد.

ماذا يعلمنا المختبر؟

  • الـ Worktrees تعمل كما وعد التوثيق: أربعة وكلاء في أربعة مجلدات على فروع منفصلة، لم يغير أي منهم ملفات الآخر، وكل واحد عرف أنه داخل Worktree دون إعداد.
  • الرسالة الجميلة لا تعني commit سليماً: أنظف رسالة في المختبر، refactor: rename make_slug to slugify، كانت على أخطر commit، لأنها أوقفت المشروع كله في سطر واحد.
  • اقرأ إعدادات أداتك قبل أن تثق بالخطاف: ثلاثة commits مرت دون أن يعمل الخطاف، وخيار واحد غير ذلك. ولو لم نكتب سطراً في ملف كلما عمل الخطاف لما عرفنا.
  • الطبقة الأخيرة هي التي تحمي main: الخطاف الذي لم يحم الفرع رفض الدمج في main، لأن الـ commit الأخير كان من المطور. وفي فريق حقيقي يكون هذا الدور لخط CI وحماية الفرع.
  • الـ commit الصغير يجعل كل أداة رجوع أدق: revert رجع عن سطر واحد، وbisect وجد السبب في خطوتين، والتعارض ظهر في سطر واحد يمكن أن تفهمه.
  • أدوات الرجوع داخل الوكيل محدودة بالجلسة: /undo في Aider لم يعرف commits جلسة سابقة، أما reflog في Git فعرف كل شيء.

قواعد Git في ملف تعليمات المشروع

كل ما سبق لا يفيد إذا كان كل مطور يتذكره بطريقته، والمكان الذي يقرؤه الوكيل في كل جلسة هو ملف التعليمات AGENTS.md أو CLAUDE.md، كما شرحنا في مقال ملف تعليمات المشروع. وهذا قسم قصير بقواعد Git يكفي لأغلب المشاريع:

## Git
- Never commit to main. Work on a branch named agent/<short-task-name>.
- One change per commit. Message format: Conventional Commits, e.g. "fix(slug): keep hyphens out of the end".
- Keep the Co-authored-by trailer your tool adds. Do not add Signed-off-by.
- Run `python -m unittest -q` before every commit; do not use --no-verify.
- Never push, force-push, rebase shared branches, or delete branches. Ask instead.

ولاحظ أن الملف يقول للوكيل ما يجب أن يفعله، ولكنه لا يمنعه، فالنموذج قد ينسى سطراً في جلسة طويلة. ولذلك فإن القواعد التي لا تحتمل الاستثناء، مثل عدم الكتابة على main وعدم تجاوز الخطافات، مكانها الإعدادات وحماية الفرع وخط CI، وملف التعليمات طبقة فوقها لا بديل عنها.

هل تدمج commits الوكيل كما هي أم كـ commit واحد؟

قد يتساءل البعض: إذا كانت commits الوكيل صغيرة ومفيدة للرجوع، فلماذا اقترحنا أن ندمجها في main كـ commit واحد؟ والإجابة أن الـ commits الصغيرة تفيدك أثناء العمل على الفرع، أي أثناء المراجعة والرجوع عن خطوة خاطئة، أما في main فالذي يفيد هو وحدة التغيير التي راجعتها ووافقت عليها. وفرع الوكيل في المختبر كان فيه commit لاختبار مكسور ثم commit «يصلح خطأ الصياغة»، وهذا تاريخ لا يفيد أحداً في main. فالقاعدة العملية: إذا كانت commits الفرع نظيفة، كل واحد منها تغيير يعمل وحده، فادمجها كما هي، وإلا فادمجها كـ commit واحد برسالة تكتبها أنت. وشرحنا الفرق بين طرق الدمج بالتفصيل في مقال Merge أم Rebase أم Squash.

كيف تتعامل الأدوات المعروفة مع Git؟

كل وكيل له طريقته مع Git، ومعرفة هذه الطريقة قبل أن تبدأ توفر عليك مفاجآت في التاريخ. والجدول التالي من التوثيق الرسمي لكل أداة:

الأداةهل يعمل commit بنفسه؟الرجوع داخل الأداةالعمل بالتوازي
Aiderنعم، بعد كل تعديل، مع سطر Co-authored-by افتراضياًالأمر /undo يحذف آخر commit عمله Aiderتشغله في Worktree مختلفة لكل مهمة
Claude Codeعندما تطلب منه، ويضيف سطر الإفصاح بحسب إعداداتهنقاط الرجوع بالأمر /rewind للملفات التي عدلها بأدواته، ولا تشمل ما غيره أمر Bashالخيار -w يبدأ جلسة في Worktree جديدة، و/batch يقسم العمل على Worktrees
Clineلا يعمل commit في مستودعك، وإنما يحفظ نقاط رجوع في مستودع ظلالرجوع إلى أي نقطة في المهمة من الواجهةمهمة واحدة في المحرر في الوقت نفسه
Copilot coding agentنعم، على فرع جديد في GitHubطلب الدمج نفسه: تغلقه أو تطلب تعديلاًكل تذكرة على فرع وطلب دمج مستقل

ولاحظ في الجدول أن نقاط الرجوع داخل الأدوات لا تغني عن Git، فتوثيق Claude Code الذي ذكرناه يحذر من أن نقاط الرجوع تغطي الملفات التي عدلها الوكيل بأدوات التعديل في المحادثة الرئيسية، وأن الملف الذي غيره أمر Bash لا يرجع، وأنها تعمل بجانب Git لا بدلاً منه. أي أن الطريقة الوحيدة المضمونة للرجوع هي commit تعرف أنه سليم، على فرع تعرف أين يبدأ.

أخطاء شائعة Common Mistakes

  • أن تشغل الوكيل على main: كل commit يعمله يدخل الفرع الرئيسي قبل أن تراه.
  • أن تشغل وكيلين في المجلد نفسه: كل واحد يغير الملفات تحت يد الآخر، وتختلط تعديلاتهما في الـ commits. استعمل Worktree لكل مهمة.
  • أن تثق برسالة الـ commit: الرسالة تصف ما أراد الوكيل، والفرق والاختبار يصفان ما فعله.
  • أن تظن أن الخطاف المحلي يحميك: بعض الأدوات تتجاوز الخطافات افتراضياً بـ --no-verify، وAider منها. فعل التحقق في الأداة، وضع الفحص الذي لا يتجاوز في خط CI.
  • أن تدمج فرع الوكيل بكل commits الصغيرة دون مراجعة: إما أن تراجعها كلها، أو تدمجها كـ commit واحد مراجع برسالة تكتبها أنت وسطر الإفصاح فيها.
  • أن تستعمل reset --hard على فرع مشترك: على الفرع المشترك استعمل git revert، فهو لا يعيد كتابة تاريخ يعتمد عليه غيرك.
  • أن تنسى الـ Worktrees القديمة: كل مجلد منها يبقى على القرص ويحجز فرعه، وراجعها بـ git worktree list واحذف ما انتهى.

قائمة تحقق Checklist قبل أن تدمج عمل الوكيل

  • الوكيل عمل على فرع باسم يدل على أنه عمل وكيل، في Worktree مستقلة.
  • قرأت git log main..branch وgit diff --stat main...branch، ولا يوجد ملف لا علاقة له بالمهمة.
  • شغلت الاختبارات بنفسك على الفرع، لا اعتماداً على كلام الوكيل.
  • كل commit فيه تغيير واحد يمكن الرجوع عنه وحده، أو ستدمجها كـ commit واحد مراجع.
  • سطر الإفصاح Co-authored-by موجود في الـ commit الذي يدخل main.
  • الخطافات تعمل فعلاً مع أداتك، والفحص الأخير في خط CI.
  • بعد الدمج حذفت الـ Worktree والفرع.

تدريب عملي

  1. شغل سكربتات المختبر من مجلد lab بالترتيب على جهازك، وقارن مخرجك بما في المقال، خاصة سطر الخطاف في hook.log.
  2. افحص الأداة التي تستعملها: اكتب خطاف pre-commit يكتب سطراً في ملف ويخرج بصفر، واطلب من الوكيل تعديلاً صغيراً، ثم انظر هل ظهر السطر.
  3. شغل وكيلين في Worktreeين مختلفتين على مهمتين في الملف نفسه، ثم ادمج الفرعين وراقب التعارض، وفكر كيف كنت سوف تقسم المهمتين لتتجنبه.
  4. أضف إلى ملف التعليمات في مشروعك قاعدة اسم الفرع وصيغة رسالة الـ commit وسطر الإفصاح، وراقب هل يلتزم الوكيل بها.

الخلاصة

  • الوكيل يكتب أسرع وأكثر، فاجعل Git يعمل لك: فرع لكل مهمة، وWorktree لكل مهمة تعمل في الوقت نفسه، وcommit صغير تقرؤه وترجع عنه وحده.
  • رسالة الـ commit من الوكيل تصف ما أراد، والفرق والاختبارات تصف ما فعل.
  • سطر Co-authored-by يحفظ في التاريخ من كتب الكود، ويمكن استخراجه بـ git log.
  • راجع بـ git log main..branch وgit diff --stat main...branch قبل أن تقرأ أي سطر كود.
  • لا تعتمد على خطاف محلي قبل أن تتأكد أن أداتك لا تتجاوزه، وضع الفحص الأخير في خط CI.
  • في المختبر عمل الوكيل ثلاثة commits دون أن يعمل الخطاف، وأحدها برسالة مرتبة أوقف المشروع كله، ووجده git bisect run في خطوتين، ورجع عنه git revert وحده.
  • الوكيلان في مجلدين لا يتصادمان أثناء العمل، ولكنهما يتصادمان عند الدمج إذا عدلا السطر نفسه، فقسم المهام قبل أن تبدأها.
  • اعرف أمر الرجوع لكل موقف: /undo في الجلسة نفسها فقط، أو reset على فرعك الذي لم تشاركه مع أحد، وrevert على الفرع المشترك، وbisect run عندما لا تعرف أين دخل الخطأ، وreflog عندما تحذف شيئاً بالخطأ.

وبهذا تكتمل مرحلة سير العمل اليومي مع الوكيل، وفي المرحلة التالية من المسار بإذن الله نتحدث عن تعدد الوكلاء، أي أن يعمل أكثر من وكيل على مهمة واحدة، وهنا تصبح الـ Worktrees أساس العمل لا خياراً:

دليلكيف تستخدم وكيل البرمجة Coding Agent بفعالية؟عادات يومية تفرق بين من يوفر وقته مع الوكيل ومن يضيعه في إصلاح كوده، مع مختبر يعطي الوكيل الهدف نفسه بأربع صيغ للطلب ويحكم عليها باختبارات لم يرها.دليلخطط ثم نفذ ثم تحقق: حلقة العمل مع وكيل البرمجةخطة قصيرة يراجعها إنسان، ثم خطوة واحدة في كل طلب، ثم دليل من أمر يرجع بنجاح أو فشل، مع مختبر يجرب الميزة نفسها بست طرق ويحكم عليها باختبارات لم يرها الوكيل.دليلالتطوير بالاختبار أولاً TDD مع وكلاء البرمجةاكتب الاختبارات التي تقول ما هو الصحيح، واقفلها، ثم دع الوكيل يصل إلى الأخضر، مع مختبر يقارن الكود أولاً بالاختبار أولاً ويحكم عليهما باختبارات قبول لم يرها الوكيل.دليلالوكلاء الفرعيون Subagents والعمل بالتوازي في فروع منفصلةكيف يعمل الوكيل الفرعي في Claude Code وCodex وCursor، ومتى يفيد عزل القراءة والكتابة في Worktree لكل وكيل، مع تجربة على نموذج محلي فيها أخطاء مزروعة وإصلاحات في فروع منفصلة وتعارض حقيقي.

سجل التحديثات

  • 20 نوفمبر 2026: كتابة المقال، وتشغيل المختبر بـ Aider 0.86.2 وGit 2.47.3 مع Ollama 0.40.13 ونموذج Qwen2.5-Coder 3B على معالج دون بطاقة رسومية.
نشرة عرب رووت | ArabRoot

معرفة تستحق مكاناً في بريدك.

مقالات مختارة وأدوات مفيدة وأفكار لمشروعك القادم، في رسالة واحدة كل أسبوع.

يمكنك إلغاء الاشتراك متى شئت. الخصوصية

تم استلام طلبك. افتح بريدك واضغط رابط التأكيد لإتمام الاشتراك.