# تعلّم هندسة الحزام (Learn Harness Engineering) > **دورة تعليمية قائمة على المشاريع حول بناء البيئة وإدارة الحالة وآليات التحقق والتحكم التي تجعل وكلاء البرمجة بالذكاء الاصطناعي يعملون بشكل موثوق.** تعلّم هندسة الحزام (Learn Harness Engineering) هي دورة تعليمية مكرّسة لهندسة وكلاء البرمجة بالذكاء الاصطناعي. لقد قمنا بدراسة وتوليف أحدث نظريات وممارسات هندسة الحزام في الصناعة بعمق. تشمل مراجعنا الأساسية: - [OpenAI: Harness engineering: leveraging Codex in an agent-first world](https://openai.com/index/harness-engineering/) - [Anthropic: Effective harnesses for long-running agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents) - [Anthropic: Harness design for long-running application development](https://www.anthropic.com/engineering/harness-design-long-running-apps) - [Awesome Harness Engineering](https://github.com/walkinglabs/awesome-harness-engineering) > **تبدأ سريعاً؟** مهارة [`skills/harness-creator/`](../../skills/harness-creator/) يمكن أن تساعدك في إنشاء حزام بمستوى الإنتاج (AGENTS.md، قوائم الميزات، init.sh، سير عمل التحقق) لمشروعك الخاص في دقائق. --- ## جدول المحتويات - [✨ معاينة بصرية](#معاينة-بصرية) - [ما تعنيه هندسة الحزام فعلياً](#ما-تعنيه-هندسة-الحزام-فعلياً) - [ابدأ بسرعة: حسّن وكيلك اليوم](#ابدأ-بسرعة-حسّن-وكيلك-اليوم) - [مشروع التخرج: تطبيق حقيقي](#مشروع-التخرج-تطبيق-حقيقي) - [مسار التعلم](#مسار-التعلم) - [المنهج الدراسي](#المنهج-الدراسي) - [المهارات](#المهارات) - [دورات أخرى](#دورات-أخرى) --- ## ✨ معاينة بصرية ### 🏠 الصفحة الرئيسية للدورة > مخطط شامل للدورة ومقدمة للفلسفات الأساسية، توفر مساراً واضحاً للبدء.  ### 📖 محاضرات تفاعلية > غوص عميق في نقاط الألم الواقعية ومشاريع عملية (مثل المشروع 01) لتجربة تعليمية تفاعلية.  ### 🗂️ مكتبة موارد جاهزة للاستخدام > قوالب وتكوينات مرجعية مصممة لحل المشكلات الشائعة في تطوير وكلاء الذكاء الاصطناعي متعددة الأدوار، مثل فقدان السياق والإنهاء المبكر للمهام.  ## كتيبات الدورة بصيغة PDF يحتوي هذا المستودع الآن على خط أنابيب لبناء كتيبات الدورة بصيغة PDF. - شغّل `npm run pdf:build` لتوليد ملفات PDF باللغتين الإنجليزية والصينية محلياً. - تُكتب ملفات المخرجات إلى `artifacts/pdfs/`. - شغّل `npm run screenshots:readme` إذا كنت تريد تحديث صور معاينة README. - سير عمل GitHub Actions [`release-course-pdfs.yml`](../../.github/workflows/release-course-pdfs.yml) يمكنه بناء ملفات PDF ونشرها على GitHub Releases. --- ## النموذج ذكي، الحزام يجعله موثوقاً هناك حقيقة قاسية يتعلمها معظم الناس بالطريقة الصعبة: **أقوى نموذج في العالم سيفشل في مهام الهندسة الحقيقية إذا لم تبني بيئة مناسبة حوله.** ربما رأيت هذا بنفسك. تعطي Claude أو GPT مهمة في مستودعك. يبدأ بشكل جيد — يقرأ الملفات، يكتب الكود، يبدو منتجاً. ثم يحدث خطأ ما. يتخطى خطوة. يكسر اختباراً. يقول "تم" لكن لا شيء يعمل فعلياً. تقضي وقتاً أطول في الإصلاح مما لو كنت فعلت ذلك بنفسك. هذه ليست مشكلة نموذج. إنها مشكلة حزام. الدليل واضح. أجرت Anthropic تجربة محكومة: نفس النموذج (Opus 4.5)، نفس الموجه ("بناء محرر ألعاب ريترو ثنائي الأبعاد"). بدون حزام، أنفق 9 دولارات في 20 دقيقة وأنتج شيئاً لا يعمل. مع حزام كامل (مخطط + مولّد + مقيّم)، أنفق 200 دولار في 6 ساعات وبنى لعبة يمكنك اللعب بها فعلياً. النموذج لم يتغير. الحزام هو الذي تغيّر. أبلغت OpenAI عن الشيء نفسه مع Codex: في مستودع مزود بحزام جيد، ينتقل نفس النموذج من "غير موثوق" إلى "موثوق." ليس تحسناً هامشياً — بل تحولاً نوعياً. **هذه الدورة تعلّمك كيف تبني تلك البيئة.** ```text نمط الحزام =========== أنت --> تعطي مهمة --> الوكيل يقرأ ملفات الحزام --> الوكيل ينفذ | الحزام يحكم كل خطوة: | +--> التعليمات: ماذا يفعل، بأي ترتيب +--> النطاق: ميزة واحدة في كل مرة، بلا تجاوز +--> الحالة: سجل التقدم، قائمة الميزات، سجل git +--> التحقق: اختبارات، تنسيق، فحص أنواع، تشغيل تجريبي +--> دورة الحياة: تهيئة في البداية، حالة نظيفة في النهاية | v الوكيل يتوقف فقط عندما يجتاز التحقق ``` --- ## ما تعنيه هندسة الحزام فعلياً هندسة الحزام تدور حول بناء بيئة عمل كاملة حول النموذج حتى ينتج نتائج موثوقة. الأمر لا يتعلق بكتابة موجهات أفضل. بل يتعلق بتصميم النظام الذي يعمل النموذج داخله. يتكون الحزام من خمس أنظمة فرعية: ```text ┌─────────────────────────────────────────────────────────────────┐ │ الحزام │ │ │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────────────┐ │ │ │ التعليمات │ │ الحالة │ │ التحقق │ │ │ │ │ │ │ │ │ │ │ │ AGENTS.md │ │ progress.md │ │ اختبارات + تنسيق │ │ │ │ CLAUDE.md │ │ feature_list │ │ فحص أنواع │ │ │ │ feature_list │ │ سجل git │ │ تشغيل تجريبي │ │ │ │ docs/ │ │ تسليم جلسة │ │ خط أنابيب شامل │ │ │ └──────────────┘ └──────────────┘ └──────────────────────┘ │ │ │ │ ┌──────────────┐ ┌──────────────────────────────────────┐ │ │ │ النطاق │ │ دورة حياة الجلسة │ │ │ │ │ │ │ │ │ │ ميزة واحدة │ │ init.sh في البداية │ │ │ │ في كل مرة │ │ قائمة حالة نظيفة في النهاية │ │ │ │ تعريف │ │ ملاحظة تسليم للجلسة التالية │ │ │ │ الإتمام │ │ التزام فقط عندما يكون آمناً للاستئناف │ │ │ └──────────────┘ └──────────────────────────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────────┘ النموذج يقرر أي كود يكتبه. الحزام يحكم متى وأين وكيف يكتبه. الحزام لا يجعل النموذج أذكى. بل يجعل مخرجات النموذج موثوقة. ``` لكل نظام فرعي وظيفة واحدة: - **التعليمات** — تخبر الوكيل بما يجب فعله، بأي ترتيب، وما يجب قراءته قبل البدء. ليس ملفاً ضخماً واحداً؛ بل هيكل إفصاح تدريجي يتنقل فيه الوكيل حسب الحاجة. - **الحالة** — تتبع ما تم إنجازه، ما قيد التنفيذ، وما هو التالي. محفوظة على القرص حتى تلتقط الجلسة التالية من حيث توقفت الجلسة السابقة تماماً. - **التحقق** — مجموعة اختبارات ناجحة فقط تُحسب كدليل. لا يمكن للوكيل إعلان النصر بدون دليل قابل للتشغيل. - **النطاق** — تقييد الوكيل بميزة واحدة في كل مرة. لا تجاوز. لا إنهاء نصف ثلاثة أشياء. لا إعادة كتابة قائمة الميزات لإخفاء العمل غير المنجز. - **دورة حياة الجلسة** — التهيئة في البداية. التنظيف في النهاية. ترك مسار إعادة تشغيل نظيف للجلسة التالية. --- ## لماذا توجد هذه الدورة السؤال ليس "هل يمكن للنماذج كتابة الكود؟" يمكنها ذلك. السؤال هو: **هل يمكنها إكمال مهام هندسية حقيقية بشكل موثوق داخل مستودعات حقيقية، عبر جلسات متعددة، بدون إشراف بشري مستمر؟** حالياً، الإجابة هي: ليس بدون حزام. ```text بدون حزام مع حزام ========= ====== الجلسة 1: الوكيل يكتب كوداً الجلسة 1: الوكيل يقرأ التعليمات الوكيل يكسر الاختبارات الوكيل يشغّل init.sh الوكيل يقول "تم" الوكيل يعمل على ميزة واحدة أنت تصلحه يدوياً الوكيل يتحقق قبل أن يدّعي الإتمام الوكيل يحدّث سجل التقدم الجلسة 2: الوكيل يبدأ من الصفر الوكيل يلتزم حالة نظيفة الوكيل ليس لديه ذاكرة لما حدث سابقاً الجلسة 2: الوكيل يقرأ سجل التقدم الوكيل يعيد العمل الوكيل يكمل من حيث توقف بالضبط أو يقوم بشيء آخر تماماً الوكيل يواصل الميزة غير المكتملة أنت تصلحه مرة أخرى أنت تراجع، لا تنقذ النتيجة: أنت تقضي وقتاً أطول النتيجة: الوكيل يقوم بالعمل، في الإصلاح مما لو كنت وأنت تتحقق من النتيجة فعلت ذلك بنفسك ``` الأسئلة التي تهتم بها هذه الدورة فعلياً: - أي تصاميم حزام تحسّن معدلات إكمال المهام؟ - أي تصاميم تقلل إعادة العمل والإكمالات غير الصحيحة؟ - أي آليات تحافظ على تقدم المهام طويلة التشغيل بشكل ثابت؟ - أي هياكل تحافظ على قابلية صيانة النظام بعد عمليات تشغيل وكيل متعددة؟ --- ## المنهج الدراسي والتوثيق للحصول على مواد الدورة الكاملة، يرجى زيارة **[موقع التوثيق](https://walkinglabs.github.io/learn-harness-engineering/)**. ينقسم المنهج إلى ثلاثة أجزاء: 1. **المحاضرات**: 12 وحدة مفاهيمية تشرح النظرية وراء هندسة الحزام. 2. **المشاريع**: 6 مشاريع عملية حيث تبني مساحة عمل وكيلية من الصفر. 3. **مكتبة الموارد**: قوالب جاهزة للنسخ (`AGENTS.md`، `feature_list.json`، `init.sh`، إلخ) لاستخدامها في مستودعاتك الخاصة اليوم. --- ## ابدأ بسرعة: حسّن وكيلك اليوم لا تحتاج إلى قراءة جميع المحاضرات الـ 12 قبل أن تبدأ في الحصول على قيمة. إذا كنت تستخدم بالفعل وكيل برمجة في مشروع حقيقي، إليك كيفية تحسينه الآن. الفكرة بسيطة: بدلاً من مجرد كتابة الموجهات، أعطِ وكيلك مجموعة من الملفات المنظمة التي تحدد ما يجب فعله، ما تم إنجازه، وكيفية التحقق من العمل. هذه الملفات تعيش داخل مستودعك، لذا تبدأ كل جلسة من نفس الحالة. ```text الجذر الرئيسي لمشروعك ├── AGENTS.md <-- دليل تشغيل الوكيل ├── CLAUDE.md <-- (بديل، إذا كنت تستخدم Claude Code) ├── init.sh <-- يشغّل التثبيت + التحقق + البدء ├── feature_list.json <-- الميزات الموجودة، أيها مكتمل ├── claude-progress.md <-- ما حدث في كل جلسة └── src/ <-- الكود الفعلي الخاص بك ``` احصل على القوالب الأولية من [مكتبة الموارد](https://walkinglabs.github.io/learn-harness-engineering/en/resources/) وأضفها إلى مشروعك. هذا كل شيء. أربعة ملفات، وستكون جلسات وكيلك أكثر استقراراً بشكل ملحوظ مقارنة بالاعتماد على الموجهات وحدها. --- ## مشروع التخرج: تطبيق حقيقي جميع مشاريع الدورة الستة تدور حول نفس المنتج: **تطبيق سطح مكتب لقاعدة المعرفة الشخصية مبني على Electron**. ```text ┌─────────────────────────────────────────────────────┐ │ تطبيق سطح مكتب لقاعدة المعرفة │ │ │ │ ┌──────────────┐ ┌──────────────────────────────┐│ │ │ قائمة المستندات│ │ لوحة الأسئلة والأجوبة ││ │ │ │ │ ││ │ │ doc-001.md │ │ س: ما هي هندسة الحزام؟ ││ │ │ doc-002.md │ │ ج: البيئة المبنية ││ │ │ doc-003.md │ │ حول نموذج وكيل... ││ │ │ ... │ │ [استشهاد: doc-002.md] ││ │ └──────────────┘ └──────────────────────────────┘│ │ │ │ ┌─────────────────────────────────────────────────┐│ │ │ شريط الحالة: 42 مستند | 38 مفهرس | آخر مزامنة 3د ││ │ └─────────────────────────────────────────────────┘│ └─────────────────────────────────────────────────────┘ الميزات الأساسية: ├── استيراد المستندات المحلية ├── إدارة مكتبة المستندات ├── معالجة وفهرسة المستندات ├── تشغيل أسئلة وأجوبة مدعومة بالذكاء الاصطناعي على المحتوى المستورد └── إرجاع إجابات مبنية على أدلة مع استشهادات ``` تم اختيار هذا المشروع لأنه يجمع بين قيمة عملية قوية، تعقيد كافٍ في المنتج الحقيقي، وبيئة جيدة لمراقبة تحسينات الحزام قبل وبعد. كل ملف بدء/حل لمشروع في الدورة هو نسخة كاملة من تطبيق Electron في تلك المرحلة التطورية. ملف بدء P(N+1) مشتق من حل P(N) — التطبيق يتطور مع نمو مهاراتك في الحزام. --- ## مسار التعلم الدورة مصممة لتُنفذ بالترتيب. كل مرحلة تبني على سابقتها. ```text المرحلة 1: شاهد المشكلة المرحلة 2: هيكل المستودع ======================= ======================== L01 النماذج القوية ≠ تنفيذ L03 المستودع كمصدر موثوق وحيد للحقيقة L02 ماذا يعني الحزام فعلياً L04 قسّم التعليمات عبر | ملفات، لا ملف ضخم واحد v P01 بالموجهات فقط مقابل | القواعد أولاً v P02 مساحة عمل قابلة للقراءة بواسطة الوكيل المرحلة 3: ربط الجلسات المرحلة 4: التغذية الراجعة والنطاق ========================== ================================== L05 أبقِ السياق حياً L07 ارسم حدود مهام واضحة عبر الجلسات L08 قوائم الميزات كعناصر L06 التهيئة قبل كل أساسية للحزام جلسة وكيل | | v v P04 تغذية راجعة وقت التشغيل P03 استمرارية متعددة الجلسات لتصحيح سلوك الوكيل المرحلة 5: التحقق المرحلة 6: اجمع كل شيء ===================== ======================== L09 أوقف الوكلاء عن L11 اجعل بيئة تشغيل الوكيل إعلان النصر مبكراً قابلة للملاحظة L10 تشغيل خط أنابيب كامل = L12 تسليم نظيف في نهاية تحقق حقيقي كل جلسة | | v v P05 الوكيل يتحقق من عمله بنفسه P06 ابنِ حزاماً كاملاً (مشروع التخرج) ``` كل مرحلة تستغرق حوالي أسبوع إذا كنت تعمل بدوام جزئي. إذا كنت تريد السرعة، يمكن إنجاز المراحل 1-3 في عطلة نهاية أسبوع طويلة. --- ## المنهج الدراسي ### المحاضرات — 12 وحدة مفاهيمية، كل منها يجيب عن سؤال أساسي واحد *اقرأ النص الكامل لكل محاضرة على [موقع التوثيق](https://walkinglabs.github.io/learn-harness-engineering/).* | الجلسة | السؤال | الفكرة الأساسية | |---------|--------|-----------------| | [L01](../../docs/en/lectures/lecture-01-why-capable-agents-still-fail/index.md) | لماذا تفشل النماذج القوية في المهام الحقيقية؟ | الفجوة في القدرة بين المعايير القياسية والهندسة الحقيقية | | [L02](../../docs/en/lectures/lecture-02-what-a-harness-actually-is/index.md) | ماذا يعني "الحزام" فعلياً؟ | خمسة أنظمة فرعية: التعليمات، الحالة، التحقق، النطاق، دورة الحياة | | [L03](../../docs/en/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md) | لماذا يجب أن يكون المستودع هو المصدر الوحيد للحقيقة؟ | إذا لم يستطع الوكيل رؤيته، فهو غير موجود | | [L04](../../docs/en/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md) | لماذا يفشل ملف التعليمات الضخم الواحد؟ | الإفصاح التدريجي: أعط خريطة، لا موسوعة | | [L05](../../docs/en/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md) | لماذا تفقد المهام طويلة التشغيل الاستمرارية؟ | احفظ التقدم على القرص؛ التقط من حيث توقفت | | [L06](../../docs/en/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md) | لماذا تحتاج التهيئة إلى مرحلة خاصة بها؟ | تحقق من صحة البيئة قبل أن يبدأ الوكيل العمل | | [L07](../../docs/en/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md) | لماذا يتجاوز الوكلاء الحدود وينهون أعمالاً بشكل ناقص؟ | ميزة واحدة في كل مرة؛ تعريف صريح للإتمام | | [L08](../../docs/en/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md) | لماذا تُعد قوائم الميزات عناصر أساسية للحزام؟ | حدود نطاق قابلة للقراءة آلياً لا يمكن للوكيل تجاهلها | | [L09](../../docs/en/lectures/lecture-09-why-agents-declare-victory-too-early/index.md) | لماذا يعلن الوكلاء النصر مبكراً جداً؟ | فجوات التحقق: الثقة ≠ الصحة | | [L10](../../docs/en/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md) | لماذا يغيّر الاختبار من طرف إلى طرف النتائج؟ | تشغيل خط أنابيب كامل فقط يُحسب كتحقق حقيقي | | [L11](../../docs/en/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md) | لماذا تنتمي قابلية الملاحظة داخل الحزام؟ | إذا لم تستطع رؤية ما فعله الوكيل، لا يمكنك إصلاح ما أفسده | | [L12](../../docs/en/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md) | لماذا يجب أن تترك كل جلسة حالة نظيفة؟ | نجاح الجلسة التالية يعتمد على تنظيف هذه الجلسة | ### المشاريع — 6 مشاريع عملية تطبق طرق المحاضرات على نفس تطبيق Electron | المشروع | ماذا تفعل | آلية الحزام | |---------|-----------|-------------| | [P01](../../docs/en/projects/project-01-baseline-vs-minimal-harness/index.md) | شغّل نفس المهمة مرتين: بالموجهات فقط مقابل القواعد أولاً | حزام أدنى: AGENTS.md + init.sh + feature_list.json | | [P02](../../docs/en/projects/project-02-agent-readable-workspace/index.md) | أعد هيكلة المستودع ليتمكن الوكيل من قراءته | مساحة عمل قابلة للقراءة بواسطة الوكيل + ملفات حالة مستمرة | | [P03](../../docs/en/projects/project-03-multi-session-continuity/index.md) | اجعل الوكيل يلتقط من حيث توقف | سجل التقدم + تسليم الجلسة + استمرارية متعددة الجلسات | | [P04](../../docs/en/projects/project-04-incremental-indexing/index.md) | أوقف الوكيل عن القيام بالكثير جداً أو القليل جداً | ملاحظات وقت التشغيل + التحكم في النطاق + الفهرسة التدريجية | | [P05](../../docs/en/projects/project-05-grounded-qa-verification/index.md) | اجعل الوكيل يتحقق من عمله بنفسه | التحقق الذاتي + أسئلة وأجوبة مبنية على أدلة + إكمال قائم على الأدلة | | [P06](../../docs/en/projects/project-06-runtime-observability-and-debugging/index.md) | ابنِ حزاماً كاملاً من الصفر (مشروع التخرج) | حزام كامل: جميع الآليات + قابلية الملاحظة + دراسة الاستئصال | ```text تطور المشاريع ============= P01 بالموجهات فقط مقابل القواعد أولاً أنت ترى المشكلة | v P02 مساحة عمل قابلة للقراءة بواسطة الوكيل أنت تعيد هيكلة المستودع | v P03 استمرارية متعددة الجلسات أنت تربط الجلسات | v P04 تغذية راجعة وقت التشغيل والنطاق أنت تضيف حلقات التغذية الراجعة | v P05 التحقق الذاتي أنت تجعل الوكيل يتحقق من نفسه | v P06 حزام كامل (مشروع التخرج) أنت تبني النظام الكامل حل كل مشروع يصبح بداية المشروع التالي. التطبيق يتطور. مهاراتك في الحزام تنمو معه. ``` ### مكتبة الموارد - [English](https://walkinglabs.github.io/learn-harness-engineering/en/resources/) — templates, checklists, and method references - [简体中文](https://walkinglabs.github.io/learn-harness-engineering/zh/resources/) — 中文模板、清单和方法参考 - [繁體中文](https://walkinglabs.github.io/learn-harness-engineering/zh-TW/resources/) — 繁體中文範本、清單和方法參考 - [日本語](https://walkinglabs.github.io/learn-harness-engineering/ja/resources/) — テンプレート、チェックリスト、方法リファレンス - [한국어](https://walkinglabs.github.io/learn-harness-engineering/ko/resources/) — 템플릿, 체크리스트, 방법 참고 자료 - [Español](https://walkinglabs.github.io/learn-harness-engineering/es/resources/) — plantillas, listas de verificación y referencias - [Français](https://walkinglabs.github.io/learn-harness-engineering/fr/resources/) — modèles, listes de contrôle et références - [Русский](https://walkinglabs.github.io/learn-harness-engineering/ru/resources/) — шаблоны, чек-листы и справочники - [Deutsch](https://walkinglabs.github.io/learn-harness-engineering/de/resources/) — Vorlagen, Checklisten und Referenzen - [العربية](https://walkinglabs.github.io/learn-harness-engineering/ar/resources/) — قوالب، قوائم تحقق ومراجع - [Tiếng Việt](https://walkinglabs.github.io/learn-harness-engineering/vi/resources/) — mẫu, danh sách kiểm tra và tài liệu tham khảo - [Oʻzbekcha](https://walkinglabs.github.io/learn-harness-engineering/uz/resources/) — andozalar, tekshiruv roʻyxatlari va maʼlumotnomalar - [Türkçe](https://walkinglabs.github.io/learn-harness-engineering/tr/resources/) — şablonlar, kontrol listeleri ve referanslar - [Português (BR)](https://walkinglabs.github.io/learn-harness-engineering/pt-BR/resources/) — modelos, listas de verificação e referências de métodos --- ## دورة حياة جلسة الوكيل إحدى الأفكار الأساسية في هذه الدورة: **يجب أن تتبع جلسة الوكيل دورة حياة منظمة، وليست عشوائية.** إليك كيف تبدو: ```text دورة حياة جلسة الوكيل ===================== ┌──────────────────────────────────────────────────────────────────┐ │ البداية │ │ │ │ 1. الوكيل يقرأ AGENTS.md / CLAUDE.md │ │ 2. الوكيل يشغّل init.sh (تثبيت، تحقق، فحص صحي) │ │ 3. الوكيل يقرأ claude-progress.md (ما حدث في المرة السابقة) │ │ 4. الوكيل يقرأ feature_list.json (ما تم إنجازه، ما هو التالي) │ │ 5. الوكيل يفحص سجل git (التغييرات الأخيرة) │ │ │ │ الاختيار │ │ │ │ 6. الوكيل يختار ميزة واحدة غير مكتملة بالضبط │ │ 7. الوكيل يعمل على تلك الميزة فقط │ │ │ │ التنفيذ │ │ │ │ 8. الوكيل ينفّذ الميزة │ │ 9. الوكيل يشغّل التحقق (اختبارات، تنسيق، فحص أنواع) │ │ 10. إذا فشل التحقق: إصلاح وإعادة التشغيل │ │ 11. إذا نجح التحقق: تسجيل الدليل │ │ │ │ الختام │ │ │ │ 12. الوكيل يحدّث claude-progress.md │ │ 13. الوكيل يحدّث feature_list.json │ │ 14. الوكيل يسجّل ما زال معطلاً أو غير مُتحقق منه │ │ 15. الوكيل يلتزم (فقط عندما يكون آمناً للاستئناف) │ │ 16. الوكيل يترك مسار إعادة تشغيل نظيف للجلسة التالية │ │ │ └──────────────────────────────────────────────────────────────────┘ الحزام يحكم كل انتقال في دورة الحياة هذه. النموذج يقرر أي كود يكتبه في كل خطوة. بدون الحزام، الخطوة 9 تصبح "الوكيل يقول يبدو جيداً." مع الحزام، الخطوة 9 هي "الاختبارات تجتاز، التنسيق نظيف، الأنواع صحيحة." ``` --- ## لمن هذه الدورة هذه الدورة موجهة لـ: - المهندسين الذين يستخدمون بالفعل وكلاء البرمجة ويرغبون في تحسين الاستقرار والجودة - الباحثين أو البناة الذين يريدون فهماً منهجياً لتصميم الحزام - قادة التكنولوجيا الذين يحتاجون لفهم كيف يؤثر تصميم البيئة على أداء الوكيل هذه الدورة ليست لـ: - الأشخاص الذين يبحثون عن مقدمة للذكاء الاصطناعي بدون كود - الأشخاص الذين يهتمون فقط بالموجهات ولا يخططون لبناء تطبيقات حقيقية - المتعلمين غير المستعدين للسماح للوكلاء بالعمل داخل مستودعات حقيقية --- ## المتطلبات هذه دورة حيث تقوم بتشغيل وكلاء البرمجة فعلياً. تحتاج إلى واحد على الأقل من هذه الأدوات: - Claude Code - Codex - وكيل برمجة IDE أو سطر أوامر آخر يدعم تعديل الملفات وتنفيذ الأوامر والمهام متعددة الخطوات تفترض الدورة أنك تستطيع: - فتح مستودع محلي - السماح للوكيل بتعديل الملفات - السماح للوكيل بتشغيل الأوامر - فحص المخرجات وإعادة تشغيل المهام إذا لم تكن لديك هذه الأداة، لا يزال بإمكانك قراءة محتوى الدورة، لكن لن تتمكن من إكمال المشاريع كما هو مقصود. --- ## المعاينة المحلية يستخدم هذا المستودع VitePress كعارض للتوثيق. ```sh npm install npm run docs:dev # Dev server with hot reload npm run docs:build # Production build npm run docs:preview # Preview built site ``` ثم افتح URL المحلي الذي يُخرجه VitePress في متصفحك. --- ## المتطلبات المسبقة المطلوب: - الإلمام بسطر الأوامر وgit وبيئات التطوير المحلية - القدرة على قراءة وكتابة الكود في مجموعة تطوير تطبيقات شائعة واحدة على الأقل - خبرة أساسية في تصحيح البرمجيات (قراءة السجلات والاختبارات وسلوك وقت التشغيل) - وقت كافٍ للالتزام بدورة عمل تركز على التنفيذ مفيد ولكن ليس مطلوباً: - خبرة مع Electron أو تطبيقات سطح المكتب أو الأدوات المحلية أولاً - خلفية في الاختبار أو التسجيل أو هندسة البرمجيات - تعرض سابق لـ Codex أو Claude Code أو وكلاء برمجة مشابهين --- ## المراجع الأساسية المراجع الأولية: - [OpenAI: Harness engineering: leveraging Codex in an agent-first world](https://openai.com/index/harness-engineering/) - [Anthropic: Effective harnesses for long-running agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents) - [Anthropic: Harness design for long-running application development](https://www.anthropic.com/engineering/harness-design-long-running-apps) - [OpenAI: Unrolling the Codex agent loop](https://openai.com/index/unrolling-the-codex-agent-loop/) - [Anthropic: Demystifying evals for AI agents](https://www.anthropic.com/engineering/demystifying-evals-for-ai-agents) - [LangChain: Improving Deep Agents with harness engineering](https://www.langchain.com/blog/improving-deep-agents-with-harness-engineering) - [Thoughtworks / Martin Fowler: Harness engineering for coding agent users](https://martinfowler.com/articles/harness-engineering.html) - [Cursor: Continually improving our agent harness](https://cursor.com/blog/continually-improving-agent-harness) راجع قائمة المراجع الطبقية الكاملة في [`docs/en/resources/reference/`](../../docs/en/resources/reference/index.md). --- ## هيكل المستودع ```text learn-harness-engineering/ ├── docs/ # VitePress documentation site │ ├── lectures/ # 12 lectures (index.md + code/ examples) │ │ ├── lecture-01-*/ │ │ ├── lecture-02-*/ │ │ └── ... (12 total) │ ├── projects/ # 6 project descriptions │ │ ├── project-01-*/ │ │ └── ... (6 total) │ └── resources/ # Multilingual templates & references │ ├── en/ # English templates, checklists, guides │ ├── zh/ # Chinese templates, checklists, guides │ ├── ru/ # Russian templates, checklists, guides │ └── vi/ # Vietnamese templates, checklists, guides ├── projects/ │ ├── shared/ # Shared Electron + TypeScript + React foundation │ └── project-NN/ # Per-project starter/ and solution/ directories ├── skills/ # Reusable AI agent skills │ └── harness-creator/ # Harness engineering skill ├── package.json # VitePress + dev tooling └── CLAUDE.md # Claude Code instructions for this repo ``` --- ## كيف تم تنظيم الدورة - كل محاضرة تركز على سؤال واحد - الدورة تتضمن 6 مشاريع - كل مشروع يتطلب من الوكيل القيام بعمل حقيقي - كل مشروع يقارن نتائج الحزام الضعيف بالقوي - ما يهم هو الفرق المقاس، وليس عدد الوثائق المكتوبة --- ## المهارات يحتوي هذا المستودع أيضاً على مهارات وكلاء ذكاء اصطناعي قابلة لإعادة الاستخدام والتي يمكنك تثبيتها مباشرة في IDE أو مساحة عمل وكيلك. - [**harness-creator**](../../skills/harness-creator/): مهارة تساعدك في إنشاء حزام بمستوى الإنتاج لمشروعك الخاص في دقائق. --- ## دورات أخرى فريقنا أنشأ دورات أخرى أيضاً! اطلع عليها: [](https://github.com/walkinglabs/hands-on-modern-rl) **Hands-on Modern RL**: منهج عملي مفتوح المصدر يسد الفجوة من مفاهيم التعلم المعزز الأساسية إلى محاذاة نماذج اللغة الكبيرة (LLM) وRLVR والأنظمة الوكيلية المتقدمة. --- ## تاريخ النجوم [](https://www.star-history.com/#walkinglabs/learn-harness-engineering&type=date&legend=top-left) --- ## شكر وتقدير هذه الدورة مستوحاة وتستمد أفكاراً من [learn-claude-code](https://github.com/shareAI-lab/learn-claude-code) — دليل تدريجي لبناء وكيل من الصفر، من حلقة واحدة إلى تنفيذ مستقل معزول.