English Version →

المشروع 07. ابني أول حلقة آلية

المحاضرة ذات الصلة: المحاضرة 13. لماذا تحتاج إلى التوقف عن مطالبة وكيلك

ماذا ستفعل

هذا هو المشروع الانتقالي من "Harness" إلى "Loop". أنت تعرف بالفعل كيفية إعداد وكيل ببيئة مناسبة وتعليمات وتغذية راجعة - الآن ستحول هذا الإعداد إلى حلقة تعمل من تلقاء نفسها.

ستقوم بثلاثة تجارب متتالية: أولاً تحول مهمة من يدوية إلى /goal، ثم تحول مهمة مراقبة إلى مؤقت /loop، وأخيراً بناء حلقة كاملة من نوع صانع-مدقق لتجربة شعور عندما تخرج من الحلقة.

ملفات المشروع

مسار المستودع: projects/project-07/

الدليل	ما بداخله	ماذا تفعل
starter/	مشروع قاعدة معرفة صغير بـ Harness كامل (الحالة النهائية لـ P06)، بما في ذلك AGENTS.md، و feature_list.json، و init.sh، و session-handoff.md، و clean-state-checklist.md.	حوّل هذا الـ Harness إلى واحد يمكنه الحلقة تلقائيًا.
solution/	تنفيذات كاملة لثلاث حلقات: حلقة هدف، وحلقة مؤقت، وحلقة صانع-مدقق، بالإضافة إلى ملفات حالة الحلقة ونصوص التحقق.	مرجع لأنماط تصميم الحلقة وإدارة الحالة.

الأدوات التي ستستخدمها

• Claude Code أو Codex
• Git
• الـ Harness الكامل الخاص بك من P06
• مُضاعِف طرفية (tmux أو screen، لمراقبة الحلقات طويلة الأمد)
• اختياري: GitHub Actions أو cron (للتجارب المتقدمة المدفوعة بالأحداث / المجدولة)

الخطوات

التحضير

1. ابدأ من نفس الالتزام الذي أنهيت فيه P06.
2. أنشئ ثلاثة فروع: p07-goal-loop، p07-timer-loop، p07-maker-checker.
3. أكد أن الـ Harness الخاص بك يعمل: شغّل init.sh، وتحقق من ملف الحالة، وقائمة الميزات، ومستندات التسليم كلها في مكانها.
4. اختر مهمة مستهدفة تريد أن تعمل الحلقة عليها بشكل متكرر. اختر شيئًا متوسط الحجم بمعايير إكمال واضحة - مثل "أضف اختبارات وحدة إلى جميع الوحدات، مع الوصول إلى تغطية 80٪" أو "أضف التحقق من صحة الإدخال إلى جميع نقاط نهاية API."

التجربة 1: حلقة الهدف — من التشغيل اليدوي إلى التشغيل التلقائي

انتقل إلى الفرع p07-goal-loop.

1. اكتب وصف الهدف: حوّل المهمة التي اخترتها إلى ملف goal.md يحتوي على:

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

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

3. شغّل بـ /goal: استخدم نفس goal.md كمدخل وشغّله في وضع /goal. يكرر الوكيل من تلقاء نفسه حتى يتم الوصول إلى الهدف أو ينشط شرط التوقف.

4. قارن النتائج:

   • الفرق في عدد الدورات
   • الفرق في عدد تدخلاتك
   • الفرق في جودة النتيجة (باستخدام نفس معيار التحقق)
   • الفرق في الوقت الذي قضيته

5. كرر على goal.md: إذا كانت النتائج ضعيفة، راجع وصف الهدف وشغّل مرة أخرى. استمر حتى تكون راضيًا عن النتائج، أو حتى تؤكد الحد الأقصى لما يمكن أن تفعله حلقة الهدف في هذه المهمة.

التجربة 2: حلقة المؤقت — حوّل المراقبة إلى نبض قلب

انتقل إلى الفرع p07-timer-loop.

1. اختر مهمة مراقبة: ابحث عن فحص متكرر تقوم به عادةً يدويًا. على سبيل المثال:

   • شغّل مجموعة الاختبارات كل ساعة، وأصلح الأخطاء
   • تحقق من تحديثات أمان التبعيات كل صباح
   • تحقق من انتهاكات أسلوب الكود بعد كل التزام
   • افحص تعليقات TODO بشكل دوري لمعرفة أيها قديم

2. اكتب مطالبة/نص المراقبة: ضع خطوات المراقبة بوضوح - ماذا تتحقق، وماذا تفعل عند العثور على مشاكل، ومتى تستدعي إنسانًا.

3. شغّل بـ /loop (أو أتمتة موضوع Codex):

   • اضبط فاصلًا زمنيًا معقولًا (10-30 دقيقة موصى به - قصير جدًا وستشعر بالازعاج، وطويل جدًا ولن ترى التأثير)
   • دعها تعمل لمدة ساعتين على الأقل (أو اذهب لتفعل شيئًا آخر وعد لاحقًا)

4. سجّل النتائج:

   • كم مشكلة وجدت؟
   • كم أصلحت من تلقاء نفسها؟
   • كم كانت إيجابيات كاذبة؟
   • كم جعلتها أسوأ؟
   • كم وقت قضيته في متابعة نتائجها؟

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

التجربة 3: حلقة الصانع-المدقق — أخرج نفسك من الحلقة

انتقل إلى الفرع p07-maker-checker.

هذه هي الأهم من التجارب الثلاث. ستبني حلقة كاملة لا تحتاج إلى وجودك هناك:

1. صمم بنية الحلقة:

   • وكيل صانع: ينفذ، يكتب الكود، يعدل الملفات
   • وكيل مدقق: يتحقق، يشغّل الاختبارات، يقوم بمراجعة الكود، يمر / يفشل
   • ملف الحالة (loop-state.md): يسجل الجولة الحالية، وما تم إنجازه، ونتائج التحقق، وما هو التالي
   • شرط التوقف: N مرات نجاح متتالية، أو الوصول إلى الحد الأقصى من الجولات

2. اكتب ثلاث مطالبات:

   • تعليمات الصانع (ماذا يفعل، كيف يفعله، ما لا يلمسه)
   • تعليمات المدقق (ماذا يتحقق، كيف يتحقق، ما يعتبر نجاحًا، كيف يقدم الملاحظات)
   • منطق التحكم في الحلقة (من يبدأ أولاً، كيف يعمل التسليم، كيف تبدأ الجولة التالية)

3. شغّل 5 جولات على الأقل:

   • الجولة 1: ينفذ الصانع → يتحقق المدقق → يفشل → ملاحظات للصانع
   • الجولة 2: يعدل الصانع بناءً على الملاحظات → يتحقق المدقق → ...
   • ...
   • حتى النجاح المتتالي، أو تقرر ذلك أنت

4. سجّل حالة كل جولة:

   • رقم الجولة
   • ماذا فعل الصانع
   • ما المشاكل التي وجدها المدقق
   • نجاح / فشل
   • هل تدخلت؟ (إذا كان نعم، لماذا؟)

5. الاستعراض النهائي:

   • كم مرة تدخلت؟ لماذا؟
   • ماذا كان سيحدث لو لم تتدخل؟
   • هل فات المدقق أي مشاكل؟
   • هل استمر الصانع في ارتكاب نفس الخطأ؟
   • أين هو سقف الجودة لهذه الحلقة؟ قدرة الصانع، أم قدرة المدقق؟

كيف تقيس النتائج

المقياس	التجربة 1 (الهدف)	التجربة 2 (المؤقت)	التجربة 3 (الصانع-المدقق)
معدل إكمال المهمة	هل تم الوصول إلى الهدف؟	كم دورة مراقبة شغّلت؟	كم جولة حتى النجاح؟
التدخلات البشرية	كم مرة تدخلت؟	كم وقت قضيته في المتابعة؟	كم مرة تدخلت؟
جودة النتيجة	كيف تقارن باليدوية؟	معدل الإيجابيات الكاذبة؟ المشاكل التي فاتت؟	كم مشكلة وجدها المدقق ولما وجدتها أنت؟
الوقت الموفّر	كم وقت وفرت؟	هل تستحق الأتمتة؟	الوقت المستغرق في تصميم الحلقة مقابل الوقت الموفّر
الموثوقية	هل كان شرط التوقف موثوقًا؟	هل هربت؟	هل يمكن للحلقة أن تتعثر في نفس المكان؟

ما يجب تقديمه

• goal.md (وصف هدف التجربة 1، جولتان على الأقل)
• ملاحظات مقارنة التجربة 1: يدوي مقابل حلقة الهدف
• مطالبة مراقبة التجربة 2 + سجل تشغيل لمدة ساعتين
• المطالبات الثلاث للتجربة 3 (الصانع / المدقق / التحكم في الحلقة)
• loop-state.md للتجربة 3 (مسجلة 5 جولات على الأقل)
• الاستعراض النهائي: الدروس المستفادة من التجارب الثلاث جميعها، وكيف تغير فهمك لهندسة الحلقات، وما هي الأشياء مرشحة جيدة للتحويل إلى حلقة وما ليست كذلك.

المحاضرات ذات الصلة

• المحاضرة 13 — لماذا تحتاج إلى التوقف عن مطالبة وكيلك
• المحاضرة 12 — لماذا يجب أن تترك كل جلسة حالة نظيفة (كل جولة من الحلقة تحتاج إلى حالة نظيفة)
• المحاضرة 11 — لماذا تنتمي إمكانية الملاحظة داخل الـ Harness (تحتاج إلى رؤية ما يحدث داخل الحلقة)
• المحاضرة 05 — لماذا تعد ملفات الحالة هي عمود الفقار للاستمرارية (ملفات حالة الحلقة هي امتداد لملفات الحالة)