Tutorial 4 Prompting and Reviewing ar

الدرس 4 · التوجيه والمراجعة

🌎 اللغة: العربية — شاهد كل اللغات الـ33

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

← السابق: الدرس 3 مهمتك الأولى مع الوكيل · التالي: الدرس 5 التوطين

---

وجّه كقائد، لا كمربّع بحث

الوكيل مهندس مبتدئ سريع وحرفي ومتحمس. قُده كما تقود مبتدئا جيدا:

• اذكر الهدف والقيود. «أضف endorse» ضعيف. «أضف endorse متبعا نمط connect، عشوائية مُبَذَّرة فقط، مع اختبارات، والبوابة تبقى خضراء» قوي. القيود هي كيف تحصل على شيفرة تناسب.
• أشِر إلى أمثلة. «اتبع النمط المستخدم في renderConnect» يتفوق على فقرة من الوصف. الشيفرة القائمة أفضل مواصفات.
• اطلب خطة قبل التعديلات في أي شيء غير تافه. توجيه خطة رخيص؛ وحلّ عشرة ملفات معدّلة مكلف.
• مهمة واحدة لكل توجيه. جمع «أضف endorse، وأعد هيكلة مولّد الأرقام العشوائية أيضا، وحدّث README أيضا» ينتج فرقا متشابكا يصعب مراجعته.
• أعطه بوابة الاختبار. «شغّل npm test ولا تعتبره منجزا حتى يصير أخضر» يحوّل الوكيل إلى شيء يفحص عمله بنفسه.

راجع الفرق في كل مرة

السرعة هي غاية الوكيل كلها — لكن السرعة غير المقروءة هي كيف تُشحن العلل. ابنِ منعكس مراجعة سريعا ومتسقا:

1. النطاق: هل غيّر ما ينبغي فقط؟ الأسطر المنقولة غير ذات الصلة رائحة مريبة.
2. الأنماط: هل يطابق الشيفرة المحيطة، بلا اعتماديات جديدة وبلا إدخال/إخراج داخل src/؟
3. قواعد المشروع: لهذا المستودع، هي عشوائية مُبَذَّرة فقط (ابحث في الفرق عن Math.random)، والنص الظاهر للمستخدم في حزم اللغة (لا مضمّنا بالشيفرة)، وأسطر البطاقة لا تتجاوز أبدا العرض الذي يحشو إليه التخطيط.
4. إمكانية الوصول: هل تنجو المخرجات الجديدة من --accessible؟ شغّل lockedin --accessible <your command> وتحقق أنه يُقرأ كنص عادي نظيف — بلا رموز زخرفية جديدة تتسلل عبر a11yFilter.
5. الاختبارات: هل يوجد اختبار جديد، وهل سيفشل فعلا إن كُسِرت الميزة؟ اسأل: «أي سطر أغيّره لأجعل هذا الاختبار الجديد يفشل؟»
6. شغّله: npm test، ثم شغّل الأمر وانظر إلى المخرجات.

لست بحاجة إلى فهم كل حرف — لكن يجب أن تفهم كل قرار. إن لم تستطع شرح تغيير، فاطلب من الوكيل شرحه قبل أن تقبله.

كرّر حين لا تكون خضراء

البوابة الحمراء خطوة طبيعية، لا فشل. الإصلاح هو ملاحظات دقيقة:

«npm test يفشل بـ: [paste the exact error]. اختبار عرض renderEndorse يتوقع أن يكون كل سطر بطاقة ≤ 60 عمودا مرئيا. أصلحه دون إضعاف الاختبار.»

الصق نص الخطأ الفعلي. «إنه معطوب» يجعل الوكيل يخمّن؛ وتتبّع المكدس يجعله يُصلح. وفضّل متابعة المحادثة نفسها بدلا من البدء من جديد — فلدى الوكيل أصلا سياق ما كتبه للتو. إن لم يتقارب تكراران أو ثلاثة، فتراجع وأعد تحديد النطاق: قد تكون المهمة أكبر من أن يستوعبها توجيه واحد.

حافظ على الزخم عبر الجلسات

العمل الحقيقي يمتد لأكثر من جلسة واحدة. عادتان تبقيان الوكيل فعّالا عبر الزمن:

• الذاكرة / الأعراف. إن كان وكيلك يدعم ذاكرة دائمة أو ملف تعليمات مشروع، فسجّل فيه القواعد التي ينبغي أن يتبعها دائما (مثلا «كل العشوائية يجب أن تستخدم pick/shuffle»، «شغّل npm test قبل إعلان الإنجاز»). تذكر العرف مرة بدل كل توجيه.
• ملاحظة تسليم. يحفظ هذا المستودع وثيقة حالة قصيرة ومنقّاة في docs/HANDOFF.md: ما المشروع، وكيف بُني، وكيف يُختبر، وما التالي. حين تعود (أو تسلّم لزميل — أو وكيل آخر)، تعيد تلك الملاحظة بناء السياق في ثوان. اطلب من وكيلك إبقاءها محدّثة كجزء من أي تغيير.

حواجز حماية تستحق الإبقاء

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

---

✅ جرّبه مع وكيلك

1. اكتب مواصفات من فقرة واحدة لأمر mentor («يوزّع نصائح غير مطلوبة»)، بما فيها القيود، واجعل الوكيل يبنيه بأسلوب الاختبار أولا — خطة، اختبارات، شيفرة، بوابة — مراجعا عند كل خطوة.
2. اطلب من الوكيل تحديث docs/HANDOFF.md ليذكر الأمر الجديد.
3. اكسِر شيئا عمدا (مثلا احذف مدخلة مجمّع)، وشغّل npm test، وتمرّن على تغذية الوكيل بالفشل الدقيق ليُصلحه.

---

إلى أين تذهب بعد ذلك

• تصفّح الشيفرة الحقيقية في src/lockedin.js — تعرف الآن شكلها.
• اقرأ docs/HANDOFF.md لملاحظات المشروع عن حالته وبنيته.
• استمتع بالنكات في مرجع الأوامر.

هذا هو الدرس. تستطيع الآن توجيه وكيل ذكاء اصطناعي لبناء برمجيات حقيقية وتغييرها خلف بوابة اختبار — مستعينا بأكثر مثال مفرط الثقة يمكن تخيله. موافق؟ 👇