بني سيرڤيس ديال الهندسة المتزنة والتحقق الفعّال لــ Coding Agent باستعمال lean-mode

شنو هو lean-mode؟

lean-mode هو ملف SKILL.md موجّه لــ Coding Agent. الهدف ديالو ماشي هو «الكود الأقل ديما هو الأحسن»، ولكن كيعطي للـ Agent معايير واضحة باش يجاوب على جوج ديال الأسئلة الهندسية:

1. واش شي كود باين آمن يستاهل يتكتب، بحال التحقق، وtry/catch، وطبقة تجريد، والمنطق الاحتياطي، ولا نظام أمان إضافي؟
2. علاش البناء والاختبارات دابا بطيئة، وكيفاش نقصّرو دورة التحقق غير للمدة المعقولة؟

ملف المهارة كاين فـ skills/lean-mode/SKILL.md، وكيستعمل frontmatter عادي، يعني name وdescription مع محتوى Markdown. ما مربوطش بمضيف معيّن، وأي Agent كيدعم اتفاقية SKILL.md يقدر يستعملو.

المشكل الأساسي اللي كيعالجو

فجلسات البرمجة الطويلة، الموديل كيقدر يميل بشكل متكرر لجوج ديال الاتجاهات: البرمجة الدفاعية الزايدة ودورة تحقق غير فعّالة.

البرمجة الدفاعية الزايدة

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

دورة تحقق غير فعّالة

من بين المظاهر المعروفة: تشغيل البناء الكامل بزاف، الاستعمال المتكرر ديال clean، تعطيل العمليات المقيمة، تشغيل جميع الاختبارات كل مرة، وخلي الأوامر اللي باين عالقة كتسنى مدة طويلة. lean-mode كيضبط هاد السلوكات بستة ديال القواعد: إعادة استعمال العمليات، التنفيذ التدريجي، التحكم فالنطاق، ترتيب التنفيذ، وتيرة الاستدعاء، وتدبير المهلة.

المعطيات الرقمية فـ README جاية من جلسة طويلة وحدة فمشروع Java وGradle فيه تقريباً 20k سطر، والغرض منها غير توضيح أن المشكل موجود فعلاً، وما خاصهاش تعتبر معياراً صناعياً صالحاً لجميع النماذج ولا المشاريع.

القدرات الرئيسية

• تحقق مرة وحدة فحدود الثقة: خاصك تجاوب أولاً على «منين جا هاد null؟»، باش ما تبقاش المعطيات الموثوقة كتدخل للنظام وكتعاود تتفحص فكل طبقة.
• ما تخبيش السبب الجذري: خاص الحذر من catch اللي كيرجع null أو false أو مجموعة خاوية أو قيمة صفرية، حيث يقدر يحوّل استثناء واضح لخطأ أصعب فالتحديد.
• ضبط التجريد المبكر: إلا كان غير تنفيذ واحد، والتجريد تخلق غير حيث «يمكن يتبدل فالمستقبل»، راه ماشي بالضرورة كاينة حدود توسعة مستقرة فعلاً.
• صلّح السبب الجذري أولاً: إضافة منطق احتياطي كتعني أن السبب الجذري ما تصلحش كامل. إلا كان الاحتياط ضروري فعلاً، خاص توضح شكون مسؤول على المشكل، وشرط الحذف، والأساس اللي تأكدتي منو.
• خلي حجم التغيير مناسب للتغيير فالسلوك: إلا زاد الكود الجديد على 50 سطر، خاص أولاً تذكر مجموع السطور، وعدد سطور التحقق والاحتياط، والكلفة الحقيقية ديال عدم كتابة هاد الكود.
• قبل ما تكتب كود آمن جاوب على 3 أسئلة: واش المشكل يقدر يوقع فعلاً؟ شنو غادي يوقع للمستخدم من بعد؟ وشنو كلفة عدم كتابتو؟ إلا ما قدرتش تجاوب على شي سؤال، ما تضيفش الكود دابا.
• قصّر دورة التحقق: كيغطي الحد الأدنى من أفكار التحقق فسبعة أنواع ديال أنظمة البناء: Gradle وMaven وGo وNode وTypeScript وRust وPython و.NET.
• سمح بالوصول لنتيجة «ما خاص حتى تغيير»: الهدف هو حل المشكل، ماشي فرض إنتاج الكود، وما خاصش تزيد تقوّي مناطق ما طلبهاش المستخدم.
• وفّر مسار لتدقيق الكود الموجود: قيس الكثافة أولاً، ومن بعد راجع أخطر الملفات، وقرّر لكل حالة واش تتحيد، تطلع لحدود الثقة، ولا تبقى، وقدّم جدول النتائج للمستخدم قبل التعديل.

بالنسبة للكود الدفاعي، المهارة كتقدم أمثلة مضادة فـ Java وGo وTypeScript وPython، باش تعاون الـ Agent يميّز نفس المشكل وراء صيغ نحوية مختلفة.

تنصيب lean-mode

الطريقة الأولى: الجلب من URL

إلا كان المضيف كيدعم استيراد المهارات من URL، بحال صفحة المهارات ديال Vantaloom، تقدر تلصق عنوان المستودع مباشرة. المضيف غادي يلقى ملف المهارة فـ skills/lean-mode/.

https://github.com/Timefiles404/lean-mode-skill

الطريقة الثانية: النسخ لمساحة العمل

كلون المستودع أولاً، ومن بعد نسخ مجلد المهارة للمكان اللي متفق عليه مع المضيف. مع اتفاقية مساحة عمل Vantaloom نفّذ:

git clone https://github.com/Timefiles404/lean-mode-skill.git
cp -r lean-mode-skill/skills/lean-mode <مساحة العمل ديالك>/.vantaloom/skills/

إلا كان المضيف كيستعمل مجلد مهارات على طريقة Claude، نسخو لــ .claude/skills/:

cp -r lean-mode-skill/skills/lean-mode <مساحة العمل ديالك>/.claude/skills/

الطريقة الثالثة: إنشاء المهارة يدوياً

أنشئ مهارة جديدة فالمضيف، ومن بعد لسّق فيها المحتوى كامل ديال skills/lean-mode/SKILL.md من المستودع. ما تنساش frontmatter اللي فالفوق، حيث المضيف كيعتمد على description ديالو باش يقرر فاش يحمّل المهارة.

المسار الأساسي للاستعمال

من بعد التنصيب، lean-mode كيعتمد أساساً على دخول وصف المهارة للسياق عند الحاجة. خاصو يتفعّل ملي الـ Agent كيحضّر يزيد تحقق، أو التقاط استثناءات، أو طبقة تجريد، أو منطق احتياطي، أو نظام أمان إضافي، أو ملي يكون شغّل البناء والاختبارات مرات متعددة فدورة وحدة.

الحالة الأولى: تقرير واش خاص تحقق جديد

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

مثلاً، إلا بغا الـ Agent يزيد Objects.requireNonNull فعدة دوال داخلية، ما خاصوش يضيفو غير حيث المعامل «نظرياً يقدر يكون null». خاصو يتبع المصدر الحقيقي ديال null، ويتأكد واش التحقق تدار من قبل فحدود الثقة.

الحالة الثانية: معالجة الاستثناءات

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

catch (...) {
    return false;
}

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

الحالة الثالثة: تقييم طبقة التجريد

إلا كانت الواجهة عندها حالياً تنفيذ واحد، والسبب الوحيد لإنشائها هو «يمكن تتبدل فالمستقبل»، خاص الـ Agent يوقف ويفحص فين كاين التغيير الحقيقي. lean-mode ما كيرفضش التجريد، ولكن كيرفض إنشاء طبقات وسيطة بكري بلا حاجة حالية وبلا حدود مستقرة.

الحالة الرابعة: تقصير البناء والاختبارات

1. عاود استعمل عملية البناء الموجودة، وتفادى التشغيل البارد المتكرر بلا سبب.
2. خلي مخرجات البناء التدريجي، وما تشغّلش clean بشكل اعتيادي.
3. شغّل أولاً أصغر أمر ممكن: غير التجميع، أو غير فحص الموديول المعني، أو غير اختبار واحد.
4. من بعد نجاح التحقق الأدنى، وسّع تدريجياً لاختبارات الموديول أو الاختبارات الكاملة.
5. ضبط وتيرة الاستدعاءات المتكررة، وما تعاودش نفس الأمر ملي ما تبدل حتى كود.
6. حط مهلة معقولة للأوامر اللي تقدر تعلق، ومن بعد الفشل حلّل أول سبب جذري.

المحتوى الكامل ديال المهارة فـ README كيعطي دورة تحقق أدنى من نوع «شغّل غير هادا» لسبعة أنظمة بناء. فالتطبيق الحقيقي، بدّل هاد الأمثلة بالأوامر الفعلية اللي تقدر تشغلها مباشرة فالمشروع.

تدقيق الكود اللي ولى دفاعي بزاف

lean-mode فيه مسار تدقيق «قيس قبل ما تحيد»، مناسب للمشاريع اللي تراكمات فيها بزاف ديال التحققات، والاحتياطات، ومنطق ابتلاع الاستثناءات.

1. قلّب وقيس: استعمل أنماط البحث فالملحق حسب اللغة، وحسب العدد والكثافة ديال الأنماط المعنية.
2. ضيّق نطاق الفحص: شوف غير 5 ملفات اللي فيها المشكل مركز بزاف، وما تبدأش بتدقيق المستودع كامل.
3. صنّف كل حالة: علّم كل منطق بــ «حيد»، أو «طلّع»، أو «خلّي». «طلّع» غالباً كتعني جمع التحقق فحدود الثقة الحقيقية.
4. قدّم التقرير قبل التعديل: عطِ جدول التدقيق للمستخدم باش يختار، وما تديرش حذف واسع بلا تأكيد.
5. تحقق على دفعات: من بعد التعديل استعمل أصغر نطاق للبناء والاختبارات، ومن بعد وسّعو حسب النتائج.

هاد المسار كيركّز على المراقبة، وإمكانية الاختيار، وإمكانية الرجوع، وما كيخليش «تقليل الكود الدفاعي» يتحول لإعادة هيكلة كبيرة وما متحكمش فيها.

تخصيص SKILL.md

SKILL.md بحد ذاتو Markdown وتقدر تعدلو مباشرة. كاينين 3 أنواع ديال التخصيص اللي عندها أكبر قيمة.

بدّل أوامر التحقق ديال المشروع

بدّل الأوامر العامة فالقسم السابع بأوامر حقيقية قابلة للتنفيذ فالهندسة الحالية، بحال «غير التجميع» و«تشغيل اختبار واحد». الأمر اللي تقدر تنسخو وتشغلو مباشرة غالباً كيضبط سلوك الـ Agent أكثر من المبادئ المجردة.

عدّل أنماط البحث

بدّل قواعد البحث فالملحق حسب أسلوب الكود ديال المشروع. مثلاً، مشروع Java يقدر يستعمل Guava Preconditions، أو يعتمد أساساً على Objects.requireNonNull. خاص أنماط البحث توافق الكود الحقيقي.

عدّل الكثافة المرجعية

المهارة كتعتبر ظهور تحقق واحد كل 200 حتى 500 سطر مرجعاً تجريبياً، ولكن ماشي معيار موحّد. الكثافة المناسبة كتختلف بين المحللات، وحدود البروتوكولات، وعمليات CRUD ديال الأعمال، وخصها تتبدل حسب مخاطر المجال ومصدر المعطيات.

نصائح متقدمة للاستعمال

• خلي الاستثناءات حاضرة فالسياق: المعايير ديال المهارة قواعد إرشادية وماشي نظريات. ما تحتافظش غير بشعارات مبسطة بحال «ما تتحققش» أو «ما تديرش catch».
• طلب من الـ Agent يشرح مكونات التغيير: ملي يزيد على 50 سطر، خليه يوضح مجموع السطور، وعدد سطور التحقق والاحتياط، وكلفة عدم تنفيذ هاد المنطق.
• وسّع نطاق التحقق بالتدريج: بدا بالملف المعني، أو اختبار واحد، أو موديول، ومن بعد دخل لنطاق اختبارات أكبر، باش ما يتشغّلش البناء الكامل مع كل تعديل.
• استعمل الدليل لتبرير الاحتياط: إلا كان الاحتياط ضروري، سجّل مصدر المشكل بالتحديد، ونتيجة التحقق، وشرط الحذف مستقبلاً، وما تستعملش «يمكن يوقع خطأ فشي بيئات» بلا دليل قابل للتحقق.
• اعتبر «عدم التعديل» نتيجة صحيحة: إلا كان المشكل محلول بالمنطق الموجود، أو ما عندش الكود الجديد فائدة واضحة، خاص الـ Agent يقدر يقول مباشرة ما كاين حتى تغيير ضروري.

الحدود والتجهيزات الاختيارية

lean-mode كيبدّل ميول الموديل، وماشي القدرات ديالو. ما يقدرش يفرض عليه يوقف كتابة نوع معيّن من الكود، غير كيحط المعايير فالسياق فالوقت المناسب، وبهذا كيكون مفيد ولكن ماشي ضمانة.

وماشي محلل ثابت، وما كيقرأش ولا كيفحص الكود بوحدو. التدقيق اللي فالملحق خاص الـ Agent يشغّل أوامر البحث المناسبة بنفسو، ومن بعد يحكم حسب النتائج.

الإضافة الاختيارية ديال Vantaloom بنفس الاسم كتخلي القواعد المختصرة حاضرة باستمرار فالسياق الديناميكي ديال كل دورة، وكتوفر ملاحظات فآخر نتائج الأدوات وأداة lean_review. الإضافة مسؤولة على التذكير المستمر، والمهارة مسؤولة على تقديم المعايير كاملة. وحتى بلا تنصيب الإضافة، المهارة كتخدم بوحدها.

تقدر تشوف مستودع المشروع فـ lean-mode-skill فـ GitHub، وهو مرخّص برخصة MIT.

الخلاصة

القيمة ديال lean-mode ماشي فتنقيص الكود بشكل آلي، ولكن فخلي كل تحقق، ومعالجة استثناء، وتجريد، واحتياط، وأمر تحقق عندو سبب واضح. من بعد التنصيب، ومع تخصيص الأوامر الحقيقية ديال المشروع، وأنماط البحث، وكثافة المخاطر، يقدر يعاون Coding Agent يركّز أكثر على السبب الجذري، ويبني دورة ملاحظات هندسية أقصر وأكثر موثوقية.