حلقة التخطيط والملاحظة والتحقق لوكلاء البرمجة

باختصار

تُعد حلقة «خطط، راقب، تحقق» أسلوباً لتشغيل وكلاء البرمجة بحيث تتضمن كل خطوة من خطوات الخطة فحصاً خاصاً بها. يتخذ الوكيل الإجراء، ثم يراقب الأدلة الناتجة (مثل الاختبارات، وفروقات الشيفرة diff، وعملية البناء build)، ويتحقق من مطابقة تلك الأدلة لفحص الخطوة، ثم يعيد التخطيط عند إخفاق أي فحص. ولا يُعتبر أي عمل مكتملاً ما لم يجتز الفحص المخصص له ويوافق عليه المراجع.

حتى 29 أكتوبر 2026، فإن أوضح نموذج معلن لتطبيق هذه الحلقة يعمل داخل Genie 4 من Google DeepMind، والذي أُعلن عنه في 27 أكتوبر 2026؛ حيث أدرجت Google نموذج Gemini 3.8 Flash داخل الحلقة لتقسيم الهدف إلى خطوات متتالية، ومراقبة كل إطار جديد، والتحقق من صحة كل خطوة قبل الانتقال لما يليها. ويحتاج وكلاء البرمجة لديك إلى الانضباط ذاته، ويوضح لك هذا الدليل كيفية تطبيق ذلك باستخدام الأدوات المتوفرة لديك بالفعل.

إذا كنت تستخدم وكلاء برمجة بالفعل، فإن منصة Sharkly تجمعهم في فريق عمل متكامل، وتوفر مساحة مشتركة تعود إليها أدلة كل تشغيل ضمن المهمة (Task) لمراجعتها.

ماذا يقدم نموذج Genie 4 من Google DeepMind في حلقة الوكيل الخاصة به

يُعد Genie 4 نموذج العالم الأحدث من Google DeepMind: فهو يُنشئ عالماً تفاعلياً وواقعياً بالكامل في الوقت الفعلي ومزوداً بالصوت. والجانب الأهم لوكلاء البرمجة يتمثل في الوكيل المدمج الذي ربطته Google به؛ ففي إعلان Genie 4، توضح Google أن Gemini 3.8 Flash «يراقب المشهد بصورة مستمرة، ويقسم الأهداف إلى سلسلة من الخطوات، ويدقق في الإطارات الواردة لتتبع التقدم والتحقق من نجاح كل خطوة».

أعد قراءة خانة «القصور المعروف» بتمعن؛ فنموذج Google نفسه يعاني من الانحراف كلما طالت فترة التشغيل وتراكمت التعديلات، وهو الإخفاق عينه الذي يصيب وكيل البرمجة لديك في الساعة الثانية من إعادة هيكلة الشيفرة (refactor).

لماذا يفشل وكلاء البرمجة في غياب حلقة التحقق

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

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

ينحرفون عن مسار الخطة في المهام الطويلة. قد تبدأ مهمة تتألف من 12 خطوة بالخطوة الأولى، لكنها تنتهي عند نقطة قريبة من الخطوة التاسعة لخطة مختلفة تماماً. وكان كل انحراف بسيط يبدو منطقياً بمعزل عن غيره، ولكن في غياب فحص مستقل لكل خطوة، لا ينتبه أحد للأمر إلا عند المراجعة، حين يكتشف المراجع أن فروقات التعديل طالت 40 ملفاً بدلاً من 6 ملفات.

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

حلقة «خطط، راقب، تحقق» للشيفرة البرمجية

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

1. التخطيط (Plan): تقسيم المهمة إلى خطوات، وتخصيص فحص محدد وملموس لكل خطوة.
2. التنفيذ (Act): تنفيذ خطوة واحدة فقط ثم التوقف.
3. المراقبة (Observe): تشغيل الفحص وجمع النتائج المباشرة.
4. التحقق (Verify): مقارنة النتائج بفحص الخطوة للتحقق من النجاح أو الفشل.
5. إعادة التخطيط (Re-plan): في حال الفشل، يجري إصلاح الخطوة أو تعديل الخطة المتبقية قبل المتابعة.

التخطيط: كتابة فحص محدد لكل خطوة

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

## Plan for SH-312: add rate limiting to /api/export

1. Add RateLimiter middleware in src/middleware/rate-limit.ts
   Check: npx tsc --noEmit exits 0
2. Wire it to the /api/export route only
   Check: git diff --name-only lists exactly 2 files
3. Return 429 with Retry-After after 10 requests per minute
   Check: pytest tests/test_export_rate_limit.py -x passes
4. Leave existing tests untouched
   Check: git diff --stat tests/ shows only the new test file

في Claude Code، ابدأ التشغيل في وضع التخطيط ليقترح الوكيل هذه الخطوات قبل إجراء أي تعديل: claude --permission-mode plan. وتوضح وثائق سير العمل في Claude Code ذلك مشيرةً إلى أن Claude «يقرأ الملفات ويقترح خطة عمل، ولكنه لا يُجري أي تعديلات إلا بعد الحصول على موافقتك».

المراقبة: الاطلاع على الأدلة المباشرة لا الملخص

تعني المراقبة تشغيل الفحص والاحتفاظ بالمخرجات الأولية المباشرة؛ فرموز الإنهاء (Exit codes)، ومخرجات الاختبار، وفروقات الشيفرة (diff) تمثل أدلة ملموسة، بينما لا تتعدى عبارة «اجتازت جميع الاختبارات» في ملخص الوكيل كونها مجرد ادعاء.

أبرز ثلاثة فحوصات تكشف أغلب المشكلات:

• فروقات الشيفرة (The diff): يوضح الأمران git diff --stat و git diff --name-only نطاق التعديلات بنظرة سريعة. راجع مرجع git diff للاطلاع على خيارات تصفية المسارات.
• الاختبارات (The tests): يوقف خيار pytest -x الاختبار عند أول إخفاق، مما يمنع الوكيل من إخفاء الخطأ وسط مئات الأسطر من النتائج الناجحة. وتغطي وثائق معالجة الإخفاق في pytest هذه الخيارات.
• عملية البناء (The build): يُثبت تشغيل npx tsc --noEmit أو npm run build قابلية الشيفرة للتجميع والترجمة بنجاح، وهو أمر قد لا تكشفه اختبارات الوحدة وحدها.

التحقق: المطابقة مع فحص الخطوة المحدد

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

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

إعادة التخطيط: عند إخفاق أي فحص

إخفاق الفحص هو معلومة مفيدة وليس خطأً يُطلب إخفاؤه. يتعين على الوكيل إما إصلاح الخطوة وإعادة تشغيل الفحص، أو تعديل ما تبقى من خطوات الخطة مع بيان السبب. وهذا الأسلوب يماثل تماماً سلوك وكيل Genie 4 عند تدخل المستخدم، حيث يعيد تكييف خطته بدلاً من الإصرار على إتمام الخطة السابقة.

احرص دائماً على تحديد سقف لعدد المحاولات؛ ففشل ثلاث محاولات متتالية في خطوة واحدة يعني أن الخطة تحتاج إلى مراجعة وتدخل بشري مباشر.

أين يتدخل المراجع البشري أو الوكيل الإضافي للمراجعة

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

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

تحتاج خطوة المراجعة إلى بيئة عمل ملائمة؛ ففي منصة Sharkly، تجمع المهمة (Task) الخطة وسجل التشغيل والملاحظات في سجل موحد. ويمكن لسير عمل المساحة (Space workflow) إضافة حالة مراجعة مخصصة بين حالتي «قيد التنفيذ» و«مكتمل»، لتصبح عبارة «أنهى الوكيل عمله» وحالة «اعتمده المراجع» مرحلتين منفصلتين تماماً.

انطلاقاً من ذلك، يعمل مُشغّل حالة المهمة (task-status trigger) على بدء أتمتة محددة «عند انتقال المهمة إلى إحدى حالات المؤسسة المختارة». وعند ربطه بوكيل مراجع، تخضع كل مهمة تبلغ حالة «جاهز للإطلاق» لمراجعة تدقيق ثانية بصورة آلية. وتشرح وثائق تنفيذ مهام الوكيل كيف يحدد سير عمل نوع المهمة (Task type Workflow) الحالات التي يحق للوكيل اختيارها.

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

صيغة موجه (Prompt) لحلقة التحقق جاهزة للنسخ

انسخ هذا النص والصقه في ملف تعليمات الوكيل أو في حقل وصف المهمة:

Work in a plan, observe, verify loop.

1. Before editing, write a numbered plan. Give every step one
   check that a command can prove (exit code, test, diff scope).
2. Do one step at a time. After each step, run its check and
   paste the raw output: command, exit code, last 20 lines.
3. Mark each step PASS or FAIL against its check. Never mark
   PASS from memory or from a summary.
4. On FAIL: fix and re-run, or revise the remaining plan and say
   why. Stop after 3 failed attempts on one step and ask.
5. Never edit, skip, or delete an existing test to make a check
   pass. If a test looks wrong, stop and ask.
6. Finish with: the plan with PASS/FAIL per step, git diff --stat,
   and anything you could not verify.

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

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

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

ما هي حلقة التحقق لوكلاء البرمجة؟

حلقة التحقق لوكلاء البرمجة هي مسار عمل يتحقق فيه الوكيل من صحة كل خطوة وفق اختبار محدد مسبقاً، أو عبر فحص الفروقات (diff) أو فحص البناء، وذلك قبل الانتقال إلى الخطوة الموالية؛ وبذلك تحل الأدلة القابلة للفحص والتدقيق محل ادعاءات الوكيل وملخصاته الذاتية.

ما وجه الصلة بين نموذج Genie 4 ووكلاء البرمجة؟

نموذج Genie 4 من Google DeepMind لا يكتب الشيفرات البرمجية، فهو نموذج عالم، إلا أن حلقة الوكيل المتبعة فيه—والتي يعتمد فيها Gemini 3.8 Flash على تخطيط الخطوات والتحقق من كل خطوة بصورة منفصلة—تجسد النمط الهندسي عينه الذي يحتاجه وكلاء البرمجة.

هل يستطيع وكيل البرمجة التحقق من عمله بنفسه؟

نعم، ولكن بصورة جزئية؛ فالتحقق الذاتي ينجح بكفاءة في الفحوصات الإجرائية الآلية مثل التجميع واختبارات الشيفرة ومطابقة نطاق التعديلات، لكنه يعجز عن تقييم مدى ملاءمة التعديل وجدواه، وهو ما يتطلب تدخلاً من مراجع ثانٍ.

ما الذي ينبغي أن يتناوله فحص خطوة التحقق؟

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

كيف تمنع الوكيل من تعديل الاختبارات لتمرير الفحص؟

أدرج بند «عدم تعديل أي اختبارات قائمة إطلاقاً» ضمن تعليمات الوكيل، ثم تحقق من التزامه بذلك عبر تنفيذ git diff --stat tests/ في نهاية كل خطوة. كما يغطي مقالنا حول من يوقف وكلاءك الجوانب المتعلقة بسياسات الإيقاف والتحكم.