--- name: "context-engineering-gate" description: "Context-engineering gate for long AI builds: prevent context-window degradation, cross-window code duplication, lost-in-the-middle, orchestrator bloat." status: active version: "v1" date: "2026-09-03" ---
🧠 Context-Engineering Gate — بوابة هندسة السياق لبناء الكود الطويل بالـ AI
> name: context-engineering-gate
> version: v1
> date: 2026-09-03
> الأصل: استُخلصت من مراجعة هندسية لظاهرة Vibe Coding (فيديو «مراجعة موقع فايب كود» — بشمهندس مازن، 2026-09-03) + نقد فني على عدة مستويات + مقارنة حيّة بمنهجيتنا.
>
> العلاقة بـ production-readiness-gate: مكمّلة لا مكرِّرة. تلك البوابة تحرس الكود الناتج (أمن/أداء/maintainability). هذه البوابة تحرس عملية البناء نفسها — تمنع تدهور جودة الـ AI أثناء البناء الطويل. تُطبَّقان معاً.
---
🎯 المبدأ الجوهري (الجذر المُشخَّص)
❌ العطب الجذري (سبب فشل Vibe Coding في المشاريع الكبيرة): الـ AI لا يفشل لأنه «غبي» — يفشل لأن context window يمتلئ أثناء البناء الطويل، فيحدث تسلسل انهيار: 1. الوعاء (context) يمتلئ → النموذج يُلخّص/يفتح نافذة جديدة → الملخّص أضعف من الأصل (فقدان معلومة معمارية). 2. النافذة الجديدة لا تعرف ما كُتب في النافذة السابقة → يعيد كتابة نفس الدالة (تكرار الكود = العرَض الأشهر). 3. Lost in the Middle: النموذج يهمل منتصف السياق (يركّز على البداية+النهاية) → قرارات معمارية في المنتصف تضيع. 4. النتيجة: نظام «ملزوق» بلا فصل طبقات ولا shared modules ولا design pattern → ينهار عند التوسّع.
✅ القاعدة الحاكمة: لا نتصارع مع حدّ الـ context (فيزيائي/تربيعي O(n²))؛ نُهندس السياق بحيث لا يمتلئ أصلاً، ولا تفقد النوافذ ذاكرتها المعمارية، ولا يتكرّر الكود.
---
🚪 البوابة — 4 أعمدة إلزامية (قبل/أثناء أي بناء AI طويل)
① سجلّ الوحدات المشتركة (Shared-Module Registry) — يمنع التكرار من الجذر
قبل توليد أي feature ثانية تستخدم منطقاً مشتركاً:
- سجّل كل دالة/وحدة مشتركة (currency-convert, date-format, auth-check, api-client...) في ملف واحد ظاهر:
SHARED_MODULES.mdأوcontracts/. - كل نافذة/وكيل جديد يقرأ السجل أولاً ويُلزَم بـ استحضار الوحدة لا إعادة كتابتها.
- acceptance check: أي دالة تظهر مرّتين بجسمين متطابقين ≈ = فشل → refactor فوري لوحدة مشتركة واحدة.
- الاستعارة الحاكمة: الدرج الواحد لكل مسؤولية — لا تخلط أوراق الحسابات بأوراق العقود بأوراق الموظفين.
② ميزانية سياق Orchestrator (Context Budget) — يحمي المنسّق من الامتلاء
- الـ Orchestrator (المنسّق الرئيسي) لا يستهلك سياقه في تفاصيل التنفيذ.
- يوزّع العمل على sub-agents لكل نطاق (sales / invoices / quotes...)، كلٌّ في context window مستقل.
- كل sub-agent يُعيد تقريراً مضغوطاً (ما فعل + الواجهات التي أنتج + acceptance)، لا الكود الخام كاملاً.
- الـ Orchestrator يحتفظ فقط بـ: المعمارية + العقود + حالة كل نطاق — لا التفاصيل.
- القاعدة الكمّية: إذا تجاوز سياق الـ Orchestrator ~50% من نافذته → لخّص الحالة إلى
PROJECT_STATE.mdوأعد التأسيس منه (لا تعتمد على ذاكرة النافذة).
③ ذاكرة معمارية مستمرة (Persistent Architecture Memory) — يعالج فقدان الملخّص + Lost-in-the-Middle
- المعمارية + العقود + القرارات = تُكتب في ملفات على القرص (
ARCHITECTURE.md,SHARED_MODULES.md,DECISIONS.md,PROJECT_STATE.md) — لا في ذاكرة نافذة الـ AI. - كل نافذة/وكيل جديد يبدأ بـ حقن هذه الملفات في مقدّمة سياقه (أول السياق = مقاوم لـ Lost-in-the-Middle).
- المعلومات الحرجة تُوضع في بداية ونهاية أي prompt طويل، لا وسطه.
- RAG للاسترجاع الانتقائي: بدل حشو كل الكود في السياق، استرجع فقط الوحدات ذات الصلة بالمهمة الحالية عند الحاجة.
④ تقطيع المهمة بحدود معمارية (Architecture-Bounded Chunking) — يمنع «feature-by-feature» الأعمى
- قسّم البناء على حدود الطبقات/النطاقات (bounded contexts)، لا عشوائياً بحجم النافذة.
- كل chunk يُنجَز كاملاً ومختبَراً قبل الانتقال (walking skeleton أولاً ثم توسيع).
- حدّ الإدخال لكل استدعاء: لا تُغذِّ النموذج code base كاملة؛ أعطه الوحدة + عقودها + الملخّص المعماري فقط.
🔗 الدمج في السلسلة الذهبية (CODING_MASTER_STRATEGY — 11 مرحلة)
هذه البوابة تُطعّم مراحل البناء (لا تستبدلها):
- المرحلة 3-4 (Plan→Architecture): أنشئ
SHARED_MODULES.md+ARCHITECTURE.md+PROJECT_STATE.mdقبل أي كود (Fable architect يملؤها). - المرحلة 7 (Parallel Exec): كل sub-agent يقرأ السجلات أولاً → يُلزَم بالاستحضار لا التكرار → يُعيد تقريراً مضغوطاً للـ Orchestrator.
- المرحلة 8 (Code Review): أضف فحص cross-window duplication (دالة مكرّرة بجسمين متطابقين) + فحص فصل الطبقات إلى مراجعة الـ diff.
- أثناء أي بناء طويل: راقب ميزانية سياق الـ Orchestrator؛ عند ~50% → checkpoint إلى
PROJECT_STATE.md.
🧪 الأداة المرافقة (أصلية، صفر تبعيات)
scripts/dupscan.py — فاحص تكرار الكود عبر الملفات (كاشف عرَض «إعادة كتابة الدالة»):
- يمسح شجرة المشروع، يستخرج الدوال/الكتل، يحسب تطابقها (تطبيع + hash + تشابه)، ويُبلّغ عن أي منطق مكرّر عبر أكثر من ملف مع اقتراح وحدة مشتركة.
- degradation-safe: أي خطأ في ملف يُسجّل ويُكمل، لا يُسقط الفحص.
- صفر LLM/صفر تكلفة: stdlib فقط (ast/hashlib/difflib) → تشغيله مجاني مهما تكرّر.
- الاستخدام:
python3 skills/context-engineering-gate/scripts/dupscan.py <project_dir> [--json out.json] [--threshold 0.85] - الاختبار الذاتي:
python3 skills/context-engineering-gate/scripts/dupscan.py --selftest
🎓 الشقّ الأكاديمي (بصفر سلبيات)
في السياق التعليمي/الدفاعي، البوابة تُثري لا تعيق: تُستخدم لشرح لماذا ينهار كود مبني بلا هندسة سياق (تعليم سبب الفشل يوضّح قيمة المعمارية). لا تُطبَّق كحاجز على كود تعليمي يُوضّح مفهوماً عمداً.
---
✅ Checklist سريع (قبل/أثناء أي بناء AI طويل)
[ ] SHARED_MODULES.md موجود ومُحدَّث قبل توليد الـ feature الثانية؟
[ ] كل sub-agent يقرأ السجل ويستحضر (لا يعيد كتابة) الوحدات المشتركة؟
[ ] الـ Orchestrator يحتفظ بالمعمارية+العقود فقط (لا الكود الخام)؟
[ ] المعمارية/القرارات على القرص (ARCHITECTURE.md/DECISIONS.md) لا في ذاكرة النافذة؟
[ ] المعلومات الحرجة في بداية/نهاية السياق (لا المنتصف)؟
[ ] التقطيع على حدود الطبقات/النطاقات (لا عشوائي بحجم النافذة)؟
[ ] dupscan.py يمرّ بلا تكرار عبر الملفات؟
[ ] عند ~50% من سياق Orchestrator → checkpoint إلى PROJECT_STATE.md؟
أي بند غير محقّق في بناء AI طويل = توقّف + إصلاح قبل المتابعة (وإلا يتراكم العطب حتى الانهيار).
---
📌 لماذا هذه الإضافة (التبرير مقابل ما نملك)
production-readiness-gate= يحرس الناتج (أمن/أداء/طبقات/PoC≠Prod).context-engineering-gate= يحرس العملية (منع تدهور الـ AI أثناء البناء الطويل).- معاً = تغطية كاملة: كود سليم مبنيّ بطريقة سليمة. صفر تكرار مع أي skill قائم (dispatching-parallel-agents يوزّع؛ هذه البوابة تحدّد بروتوكول إدارة السياق ومنع التكرار الذي كان مفقوداً صراحةً).