中文版本 →

أمثلة الكود: code/ مشروع عملي: المشروع 01. الاعتماد على المطالبة فقط مقابل القواعد أولًا

المحاضرة 01. النماذج القوية لا تعني تنفيذًا موثوقًا

تظن أنك خبير بما يكفي في عالم الذكاء الاصطناعي: اشتراك Claude Pro، مفتاح GPT-4o API، وأرقام لوحة SWE-bench محفوظة في ذاكرتك. ثم في يوم ما تسلم مشروعًا حقيقيًا إلى وكيل ذكاء اصطناعي وأنت واثق تمامًا. النتيجة؟ يضيف ميزة لكنه يكسر الاختبارات، يصلح عيبًا لكنه يضيف عيبين جديدين، يعمل لمدة 20 دقيقة ثم يعلن بفخر "تم" - وعندما تنظر إلى الكود تكتشف أنه ليس ما طلبته إطلاقًا.

غريزتك الأولى؟ "هذا النموذج ليس جيدًا بما يكفي. حان وقت الترقية." تمهل. قبل أن تمد يدك إلى محفظتك، فكّر في احتمال أن المشكلة ليست في النموذج أصلًا.

لننظر إلى بعض الأرقام. بحلول أواخر عام 2025، كانت أقوى وكلاء البرمجة على SWE-bench Verified تحقق تقريبًا 50-60%. وهذا على مهام مختارة بعناية، مع أوصاف Issues واضحة وحالات اختبار موجودة. انقل الأمر إلى بيئة تطويرك اليومية - متطلبات غامضة، لا اختبارات جاهزة، وقواعد عمل ضمنية مبعثرة في كل مكان - وستنخفض هذه النسبة أكثر.

لكن خلف هذه الأرقام توجد حقيقة غير بديهية.

الحصان نفسه، مصائر مختلفة

أجرت Anthropic تجربة مضبوطة. المطالبة نفسها ("ابنِ صانع ألعاب ريترو ثنائية الأبعاد")، والنموذج نفسه (Opus 4.5). التشغيل الأول: عارٍ بلا دعم - 20 دقيقة، 9 دولارات، والميزات الأساسية للعبة لم تعمل إطلاقًا. التشغيل الثاني: Harness كامل (مخطط + مولد + مقيم في بنية من ثلاثة وكلاء) - 6 ساعات، 200 دولار، وأصبحت اللعبة قابلة للعب.

لم يغيروا النموذج. بقي Opus 4.5 هو Opus 4.5. ما تغيّر هو السرج.

مقال OpenAI لعام 2025 عن هندسة الـ Harness يقولها بوضوح: ينتقل Codex في مستودع مجهز جيدًا بالـ Harness من "غير موثوق" إلى "موثوق". لاحظ الصياغة - ليست "أفضل قليلًا"، بل انتقال نوعي. مثل حصان أصيل: يمكنك ركوبه بلا سرج، لكنك لن تذهب بعيدًا، ولن تتحرك بسرعة، والسقوط لن يكون مفاجأة. الـ Harness هو ذلك السرج - كل ما في البنية الهندسية خارج أوزان النموذج.

أين تتعطل الوكلاء فعليًا

إذًا، ما الذي يسوء تحديدًا؟

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

حتى عندما تحدد المطلوب، لدى المشروع أعراف معمارية ضمنية لا يعرفها الوكيل. فريقك اعتمد صيغة SQLAlchemy 2.0، لكن الوكيل يكتب افتراضيًا بصيغة 1.x. كل نقاط API يجب أن تستخدم مصادقة OAuth 2.0، لكن هذه القاعدة موجودة فقط في رأسك وفي رسالة Slack من ثلاثة أشهر. الوكيل لا يرى ذلك - ليس لأنه لا يريد الالتزام، بل لأنه حرفيًا لا يعرف أن هذه القواعد موجودة.

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

والأكثر شيوعًا من ذلك: لا توجد طريقة للتحقق. لا اختبارات، لا Lint، أو لم تُبلّغ أوامر التحقق إلى الوكيل. يكتب الوكيل الكود، ينظر إليه، يقرر أنه جيد، ثم يقول "تم". هذا يشبه أن تطلب من طالب تسليم واجب بلا نموذج إجابة - يظن أنه أجاب بشكل صحيح، لكن عند التصحيح تجد الأخطاء متراكمة. لاحظت Anthropic أيضًا ظاهرة مثيرة: عندما تشعر الوكلاء أن السياق يوشك على النفاد، تندفع لإنهاء المهمة، وتتخطى التحقق، وتختار حلًا بسيطًا بدل الحل الأفضل. يسمون ذلك "context anxiety" - وهو شبيه بما يحدث عندما تدرك أن وقت الامتحان أوشك على الانتهاء فتبدأ بتخمين إجابات الأسئلة المتبقية.

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

مصطلحات أساسية

مع هذه السيناريوهات في الذهن، لم تعد هذه المفاهيم مجرد مصطلحات:

• Capability Gap: الفجوة الكبيرة بين أداء النموذج على المعايير القياسية وأدائه في المهام الحقيقية. معدل نجاح 50-60% على SWE-bench Verified يعني أن قرابة نصف القضايا الحقيقية لا تُحل.
• Harness: كل ما هو خارج النموذج - التعليمات، الأدوات، البيئة، إدارة الحالة، وتغذية التحقق الراجعة. إن لم يكن من أوزان النموذج فهو جزء من الـ Harness. هذا هو "السرج" الذي نتحدث عنه.
• Harness-Induced Failure: لدى النموذج قدرة كافية، لكن بيئة التنفيذ فيها عيوب بنيوية. تجربة Anthropic المضبوطة أثبتت ذلك بالفعل.
• Verification Gap: الفجوة بين ثقة الوكيل في مخرجاته والصحة الفعلية. يقول الوكيل "انتهيت" وهو لم ينتهِ - وهذا هو نمط الفشل الأكثر شيوعًا.
• Diagnostic Loop: نفّذ، لاحظ الفشل، انسبه إلى طبقة Harness محددة، أصلح تلك الطبقة، ثم نفّذ مرة أخرى. هذه هي المنهجية الأساسية لهندسة الـ Harness.
• Definition of Done: مجموعة شروط قابلة للتحقق آليًا - الاختبارات تمر، الـ lint نظيف، وفحوصات الأنواع ناجحة. من دون Definition of Done صريحة، سيخترع الوكيل تعريفه الخاص.

عندما تفشل الأمور، أصلح الـ Harness أولًا

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

خطوات عملية:

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

اكتب Definition of Done صريحة لكل مهمة. لا تقل "أضف ميزة بحث". قل:

Completion criteria:
- New endpoint GET /api/search?q=xxx
- Supports pagination, default 20 items
- Results include highlighted snippets
- All new code passes pytest
- Type checking passes (mypy --strict)

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

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

قِس التحسن. احتفظ بسجل بسيط: هل نجحت كل مهمة أم فشلت، وأي طبقة سببت الفشل؟ بعد عدة جولات سترى أي طبقة هي عنق الزجاجة - ركز طاقتك هناك.

تجربة المليون سطر

أجرت OpenAI في 2025 تجربة جريئة: استخدام Codex لبناء منتج داخلي كامل من مستودع Git فارغ. بعد خمسة أشهر، احتوى المستودع على نحو مليون سطر كود - منطق تطبيق، بنية تحتية، أدوات، توثيق، وأدوات تطوير داخلية - كلها مولدة بواسطة الوكلاء. قاد ثلاثة مهندسين Codex، وفتحوا ودمجوا نحو 1,500 Pull Request. بمعدل 3.5 Pull Request لكل شخص يوميًا.

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

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

تثبت هذه التجربة مباشرة الأطروحة المركزية لهذه المحاضرة: النموذج نفسه ينتج مخرجات مختلفة جوهريًا في بيئة عارية مقارنة ببيئة ذات Harness كامل. النموذج لم يتغير. البيئة تغيرت.

المصدر: OpenAI: Harness engineering: leveraging Codex in an agent-first world

مثال أقرب إلى الواقع

استخدم فريق Claude Sonnet لإضافة نقطة API جديدة إلى تطبيق ويب Python متوسط الحجم (FastAPI + PostgreSQL + Redis، نحو 15,000 سطر كود).

في البداية أعطوه جملة واحدة فقط: "add user preferences endpoints under /api/v2/users." النتيجة؟ استهلك الوكيل 40% من نافذة السياق في استكشاف بنية المستودع، وأنتج كودًا يبدو معقولًا لكنه لا يتبع أنماط معالجة الأخطاء في المشروع، واستخدم صيغة SQLAlchemy قديمة، وأعلن الانتهاء رغم أن نقطة النهاية كانت تحتوي على أخطاء تشغيل. اضطرت الجلسة التالية إلى إعادة كل عمل الاكتشاف.

لاحقًا أضافوا AGENTS.md (يصف معمارية المشروع وإصدارات مكدس التقنية)، وأوامر تحقق صريحة (pytest tests/api/v2/ && python -m mypy src/)، وسجلات قرارات معمارية. نجح النموذج نفسه في الجولات الثلاث المستقلة كلها، مع كفاءة سياق أفضل بنحو 60%.

لم يغيروا النموذج. غيّروا الـ Harness.

الخلاصات الأساسية

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

قراءات إضافية

• OpenAI: Harness Engineering — Leveraging Codex in an Agent-First World
• Anthropic: Effective Harnesses for Long-Running Agents
• HumanLayer: Skill Issue — Harness Engineering for Coding Agents
• SWE-bench Leaderboard
• Thoughtworks Technology Radar: Harness Engineering

تمارين

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

2. قياس Verification Gap: اختر 5 مهام برمجية. بعد كل مهمة، سجل هل يدعي الوكيل أنه انتهى، ثم تحقق من الصحة الفعلية باختبارات مستقلة. احسب نسبة الحالات التي يقول فيها الوكيل إنه انتهى بينما لم ينتهِ فعليًا - هذه هي Verification Gap لديك. ثم فكّر: ما أوامر التحقق التي ستخفض هذه النسبة؟

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