الوكيل فتح pull request صحيحًا بنسبة 80 بالمئة. ماذا الآن؟

فتح وكيلٌ pull request على مستودعك. البناء ينجح، والاختبارات التي كتبها خضراء، ومن الواضح أنه فهم شيئًا من التذكرة. ومع ذلك لا يمكن دمجه: دالة مساعدة مكرّرة على بُعد ثلاثة مجلدات من نظيرتها القائمة، وملف إعدادات عدّله بلا سبب، والحالة الحدّية الوحيدة التي سمّتها معايير القبول متروكة على شكل TODO.

فأمامك قرار: تُكمله بيدك، أو تعيده مع ملاحظات، أو تغلقه وتعيد كتابة التذكرة. ابحث عن هذا السؤال فتجد في معظم النتائج أدوات مراجعة معروضة للبيع، والأداة التي تقرأ الفروقات لن تخبرك أي المخارج تسلك. والثلاثة تكلّف أسبوعك أثمانًا شديدة التفاوت.

طلب واضح النفع، واضح التعذّر على الدمج

هذه هي النتيجة الوسيطة، لا سوء حظ. راجع باحثون 567 pull request فتحها Claude Code في 157 مشروعًا مفتوح المصدر فوجدوا أن 83.8% منها دُمجت في النهاية (نُشرت الورقة في سبتمبر 2025 ونُقّحت في فبراير الماضي). ومن المدموجة، دخل 54.9% فقط بلا تعديل. أما 45.1% الباقية فاحتاجت تعديلات أولًا، «خصوصًا في إصلاح الأخطاء والتوثيق والالتزام بالمعايير الخاصة بكل مشروع».

أي أن قرابة نصف الطلبات الجيدة بما يكفي للدمج احتاجت إنسانًا، لأسباب تتعلق بأعراف المستودع في الغالب، لا بمنطق معطوب. هذا هو «صحيح بنسبة 80 بالمئة» مسنودًا بأرقام.

والمطورون يقولون الشيء نفسه من الجهة المقابلة. في استطلاع Stack Overflow للمطورين لعام 2025، كانت الشكوى الأولى من أدوات الذكاء الاصطناعي هي «حلول شبه صحيحة، لكن ليست صحيحة تمامًا»، بنسبة 66% من 31,476 إجابة، متقدمة على بطء تتبّع الأخطاء عند 45.2%.

فبدل أن تسأل إن كانت هذه نسخة رديئة بعينها، اسأل سؤالًا أضيق.

سؤال واحد يحسم الأمر

هل أساء الوكيل فهم المشكلة، أم فهمها وأساء التنفيذ؟

سوء الفهم يعني أن التذكرة كانت خاطئة، وتعليقات المراجعة لا تصلح تذكرة خاطئة: أغلق الطلب وأعد كتابة المهمة. أما سوء التنفيذ فيعني أن الفجوة ميكانيكية، فأكمِله أو أعِده ومعه القيد الناقص.

هذا التقسيم قاعدتنا العملية، لا نتيجة منشورة. لا نعرف مجموعة بيانات تفصل «أساء قراءة المهمة» عن «فهمها ثم تعثّر»، فالسند هنا ظرفي. ويقول فريق وكلاء الخلفية في Spotify إن أكثر ما يرصده الحَكَم الآلي عندهم هو خروج الوكيل عن التعليمات الواردة في الطلب، وهذا خلل في النطاق لا في الكود.

واتّبع هذا الترتيب: التذكرة، ثم وصف الطلب، ثم الملفات التي أشارت إليها التذكرة وحدها.

flowchart TD
  A["Read the ticket, then the PR"] --> B{"Does it aim at the problem the ticket describes?"}
  B -->|"No"| C["It misread the task"]
  B -->|"Yes"| D{"Is the gap mechanical, not conceptual?"}
  D -->|"No"| C
  D -->|"Yes"| E{"Closable in under 30 minutes?"}
  C --> F["Close it. Rewrite the ticket."]
  E -->|"Yes"| G["Finish it. Record the fix."]
  E -->|"No"| H["Return the missing constraint."]

علامات أن الوكيل أساء قراءة التذكرة

وصف الطلب يعيد صياغة تذكرتك بكلمات أوسع مما كتبت. تذكرتك قالت: «ارفض الرفع فوق 10 MB عند خطوة intent.» والطلب يقول: «تحسين مسار الرفع.» هذا الانزياح هو التشخيص.

أو أنه حلّ نسخة عامة من مشكلتك المحددة. طلبت شرط if إضافيًا واحدًا فجاءك بواجهة استراتيجيات قابلة للضبط، أي أنه صوّب نحو شيء لم تصفه.

أو أن الملفات التي عدّلها ليست حيث تسكن المشكلة. أصلح ما يجاور العَرَض لا ما يسبّبه، وهذا يحدث حين تسمّي التذكرة نتيجة بلا حدود.

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

وسجل النشاط أسرع من الفروقات في أحيان كثيرة. مهمة أُعيدت تسميتها، أو حالة قفزت إلى «قيد المراجعة»، أو تعديلات على حقول لم تذكرها المهمة قط: كلها تُقرأ انزياحًا في النطاق.

علامات أنه فهم وأخطأ في التنفيذ

هنا يمكن تسمية كل خطأ في جملة واحدة، ولا جملة منها عن التصميم. اختبارات ناقصة لحالة سمّتها التذكرة. دالة مساعدة مكرّرة بدل استيرادها. انحراف عن الأعراف: الطلب يفعل الشيء بطريقة أخرى، وكلتا الطريقتين تعمل. المسار المعتاد يعمل، والحالة الحدّية في معايير القبول بلا معالجة.

وانتبه إلى مسّ CI ليمرّ التشغيل بدل إصلاح الكود: تأكيدات محذوفة، وخطوة lint متجاوَزة، ومهلة موسَّعة. هذا وكيل يُرضي المقياس الذي أعطيته إياه، ومكانه هنا رغم ذلك.

شدّة الخطأ ليست الفيصل. سوء الفهم قد يُنتج طلبًا مرتبًا حسن الاختبار وخاطئًا تمامًا. وسوء التنفيذ قد يُنتج فوضى تصل إلى الجواب الصحيح. احكم على الهدف، لا على أناقة التنفيذ.

المخارج الثلاثة، وثمن كل منها

الفخ هو حجم الفروقات. الفروقات الكبيرة تبدو عملًا ستُلقيه في السلة، فتُكمله. والحدس هنا مقلوب الإشارة. في دراسة على 33,707 pull request كتبها وكلاء، أمكن التنبؤ بجهد المراجعة لحظةَ إنشاء الطلب من سمات ساكنة وحدها، أهمها حجم التغيير وأنواع الملفات، بمساحة تحت المنحنى AUC تساوي 0.96. الحجم إشارة كلفة، لا إشارة تقدّم أبدًا.

المخرج	متى تختاره	ما يكلّفك	ما تحتفظ به
أكمِله بنفسك	الهدف صحيح، والفجوة ميكانيكية، وأقل من 30 دقيقة	بعد ظهرك، واسمك على تصميم لم تختره	الفرع وما يعمل منه
أعِده إليه	الهدف صحيح، وتستطيع تسمية القيد الناقص في جملة	تشغيلة واحدة وانتظار، بحظوظ متكافئة	الجلسة نفسها والطلب نفسه، والسياق محفوظ
أغلِقه وأعِد الكتابة	الهدف خاطئ	كل ما في الفرع	ما علّمك إياه عن تذكرتك

حدّ الثلاثين دقيقة اعتباطي، فاضبطه كما يناسبك. وفائدة وجود حدّ أصلًا أن جملة «سأصلح هذا الجزء فحسب» تحوّل مراجعة من عشرين دقيقة إلى أربع ساعات. اختر الرقم قبل أن تفتح الفروقات، ثم أعلِن المخرج الذي سلكته. الطلب المعلّق بلا قرار أسوأ من مخرج خاطئ، لأن أحدًا لا يعرف أهو ينتظرك أم ميت.

كيف تعيده إليه فتأتي المحاولة الثانية مختلفة

على الأرجح مررت بجولة نبّهته فيها ففعل الشيء نفسه. الدراسة ذاتها التي فحصت 33,707 طلبًا رصدت شكل المشكلة: الوكلاء أقوياء في الأتمتة الضيقة، ضعفاء في التحسين التدريجي، وتُهجر طلباتهم متى صارت الملاحظات انطباعية. فاجعل ملاحظتك نقيض الانطباع.

أعِد القيد، لا الشكوى. عبارة «هذا خطأ» لا تعطي الوكيل شيئًا لم يكن يملكه. أما «الرفع يُرفض عند خطوة intent في storage/usage.ts، لا عند commit، ويجب ألا يوجد فحص ثانٍ» فحقيقة كانت تنقصه. كل تعليق مراجعة إما حقيقة كانت غائبة عن الوكيل، وإما ضجيج.

وثمة حدّ تصبح بعده الجولات الإضافية بلا عائد. تضع أفضل ممارسات Claude Code من Anthropic رقمًا لها. بعد تصحيحين على المشكلة نفسها في الجلسة الواحدة، «يكون السياق مزدحمًا بمقاربات فاشلة. شغّل /clear وابدأ من جديد بطلب أكثر تحديدًا يضمّ ما تعلمته. جلسة نظيفة بطلب أفضل تتفوق في الغالب الأعم على جلسة طويلة بتصحيحات متراكمة».

أي أن الجهة الصانعة للوكيل نفسها تنصحك بالبدء من جديد.

والحظوظ أفضل مما يتوقع الناس. يعترض الحَكَم الآلي في Spotify على نحو ربع جلسات الوكلاء، وهي بالآلاف، ويصحح الوكيل مساره في نصف الحالات.

Returning WEB-13. Target is right, one constraint was missing.

Correct: over-cap uploads rejected before the browser PUT.
Wrong:   the check runs at commit. It must run at intent, in
         storage/usage.ts. Commit cannot stop the upload.
Do not:  add a second check. Move the existing one.
Done is: the existing tests pass unchanged, plus a 2 MB file on Free.

يتخطّى الناس السطر الأخير، ثم يستغربون لماذا تتوقف المحاولة عند نقطة اعتباطية. وإن ظل الوكيل يكتب في حقول لا ينبغي أن يمسّها، فضيّق ذلك في الإعدادات لا في الملاحظة.

ماذا تغيّر في التذكرة حين تبدأ من جديد

إن كان الجواب «أساء القراءة»، فالإصلاح يقع في المنبع. الطلب الفاشل دليل على حال تذكرتك أفضل من إعادة قراءتها بنفسك، لأنه يُظهر كيف تهبط كلماتك على طرف لا يشاركك أي سياق.

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

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

أين تمسك أداة التتبّع بالقرار، وأين لا تفعل شيئًا

‏Taskfolk لا يراجع الكود: لا عرض للفروقات، ولا تحليل ساكن، ولا تعليقات على الأسطر. ولقراءة آلية للفروقات، استعن بـCodeRabbit أو Greptile أو Graphite، وسبب وجود هذا السوق أصلًا هو موضوع الذكاء الاصطناعي نقل عنق الزجاجة من كتابة الكود إلى مراجعته. الحكم حكمك، وأداة التتبّع تحفظ السجل.

الوحدة هنا هي الجلسة، والجلسات تُفتح من جديد. إسناد مهمة إلى وكيل موصول يُنشئ جلسة في حالة pending، فيلتقطها الوكيل ويتنقل بين الحالات أدناه. والجلسة في review أو needs_input يمكن إعادتها إلى running، محتفظةً بالعنوان نفسه والملاحظة والتكلفة المُبلَّغ عنها ورابط الطلب. أما متى صارت done فقد تجمّدت: يردّ API بتعارض، وأي محاولة ثانية لا بد أن تكون جلسة جديدة. فأعِدها وهي قيد المراجعة، لا بعد أن تدعها تُغلق.

stateDiagram-v2
    [*] --> pending
    pending --> running
    running --> needs_input
    running --> review
    needs_input --> running
    review --> running
    review --> done
    running --> failed
    done --> [*]
    failed --> [*]

وإعادته إليه تحتاج استدعاءً واحدًا.

curl -X PATCH "https://taskfolk.ai/api/v1/workspaces/acme/agent-sessions/$SESSION_ID" \
  -H "Authorization: Bearer tfk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"state":"running","note":"Returned: move the cap check to intent."}'

await fetch(`${base}/agent-sessions/${sessionId}`, {
  method: "PATCH",
  headers: { Authorization: `Bearer ${key}`, "Content-Type": "application/json" },
  body: JSON.stringify({ state: "running", note: "Returned: move the check." }),
});

requests.patch(
    f"{base}/agent-sessions/{session_id}",
    headers={"Authorization": f"Bearer {key}"},
    json={"state": "running", "note": "Returned: move the check."},
)

الاستجابة هي الجلسة نفسها، بالمعرّف ذاته وexternal_url ذاته، فيبقى رابط الطلب قائمًا. ومفتاح الوكيل نفسه لا يحتاج شيئًا إضافيًا، أما من مفتاح بشري فيضيف المالك أو المسؤول قيمة agent_id للوكيل، وهي أيضًا طريقة إغلاق جلسة تخلّى عنها الوكيل. وكل كتابة يجريها مفتاح وكيل تحمل معرّف مستخدم ذلك الوكيل، فيكون لسؤال «من نقل هذه إلى قيد المراجعة عند 03:41» جواب بعد ستة أسابيع. والتفصيل في احتفظ بسجل تدقيق لكل ما يغيّره وكلاء الذكاء الاصطناعي.

والبوابة الصلبة هي الانتقالات المسموح بها. كل عمود يحمل قائمة «يمكن الانتقال إلى»، مفروضة على كل كتابة حالة بما فيها API والأتمتة، فلا تقفز مهمة أُعيدت من قيد المراجعة إلى منجزة. ولإدخال وقفة بشرية قبل نزول التغيير، انظر كيف تمنح وكيل الذكاء الاصطناعي مراجعة بشرية.

ما لا يصلحه شيء من هذا

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

وشارة التحقق أضعف مما يوحي اسمها. فهي تؤشّر على جلسة في review أو done لم تترك نشاطًا منسوبًا ولا تعليقًا على مهمتها. يكفي تعليق واحد لتخطّيها، والجلسة التي تحمل رابط طلب حقيقيًا هي بالضبط الحالة التي تفوتها. أما التحقق من ادّعاء الإنجاز ففي كيف تدير فريقًا من وكلاء الذكاء الاصطناعي.

والتكلفة المُبلَّغ عنها بلاغ لا أكثر. الوكيل ينفق على حساب مزوّده، وهو حساب لا يراه Taskfolk، فالجلسة التي تعرض $2.40 تعرضه لأن الوكيل قال ذلك. نستطيع التنبيه على الرقم، لا إيقاف الإنفاق. كما أن Taskfolk لا يشغّل الوكيل: يوصل إليه الإشارة ويحفظ السجل بينما تعمل بيئة تشغيله.

وربط المستودعات يقتصر على GitHub، فطلب على GitLab أو Bitbucket يعيش في رابط الجلسة ولا مكان له غيره. ولا ينفع هذا كله إن كنت لا تميّز وكيلًا يفكّر من وكيل استسلم بصمت، وذلك تشخيص آخر.

في المرة القادمة التي تفتح فيها طلبًا من وكيل، اقرأ التذكرة قبل الفروقات، واكتب الجواب قبل أن تُمرّر الشاشة: أساء القراءة، أم تعثّر. ثم اسلك المخرج الذي يشير إليه، واترك السبب في ملاحظة الجلسة.