🇬🇧 English Version: Read the original article in English here.
كونتكست مبيتنسيش: الذاكرة الدائمة بفولدر app_context/ وقواعد الـ Agents 📓☕
الجزء الخامس من سلسلة “أبيكس تحت السيطرة”.
⚡ الخلاصة في كلمتين (TL;DR)
الشغل مع مساعد ذكي من غير ذاكرة وسياق دائم (Persistent Context) عامل بالظبط زي ما تعيّن مطور جونيور عبقري بس بيجيله فقدان ذاكرة كامل كل يوم الساعة 12 بالليل! كل يوم الصبح محتاج تفهمه من أول وجديد إن مجات الشاي في الرف الفوقاني، وإن سلة المشتريات متخزنة في APEX Collection مش جدول عادي، وإن الخصومات لازم تعدي على Package معينة في الداتابيز!
في المقال ده، هنشوف إزاي قالب مشروع APEX بيستخدم فولدر
app_context/<app-id>/، وقواعد الـ Agents القياسية، وأمر التهيئة/initعشان يدي للـ AI Agents بتوعك ذاكرة مؤسسية دائمة ومستقرة.
🤯 يوم اليرموك اليومي مع الذكاء الاصطناعي (The Daily Groundhog Day)
لو بنيت تطبيقات Oracle APEX معقدة باستخدام أدوات الذكاء الاصطناعي، أكيد حفظت الحوار ده صم:
أنت (اليوم الأول): “ضيف لي حقل كود الخصم في صفحة الشراء. افتكر دايماً، عناصر السلة متخزنة في الـ APEX Collection اللي اسمها
ORDER_CART، مش في جدولORDERS!”
الـ Agent: “علم وينفذ! هستخدمAPEX_COLLECTION.ADD_MEMBER.” (والشغل طلع روعة!)
— تاني يوم الصبح (شات جديد خالص) —
أنت (اليوم التاني): “احسب لي الضريبة في صفحة الشراء.”
الـ Agent: “عينيّا! هشغلINSERT INTO ORDERS (TAX_AMOUNT) VALUES (...)”
أنت: “🤦♂️ يخرب عقلك! مش لسه قايلك إمبارح إننا شغالين بـ APEX Collections؟!”
ولأن نماذج الـ LLM بطبيعتها ملهاش ذاكرة ممتدة بين الجلسات (Stateless)، بتلاقي نص وقتك ضاع وأنت بتعيد شرح نفس القواعد المعمارية كل يوم من الصفر.
📓 الحل الجذري: فولدر app_context/<app-id>/
قالب مشروع APEX بيحل المأساة دي بتخصيص بيت دائم لكل حكمة ومعلومة خاصة بالتطبيق:
app_context/
├── README.md ← القواعد العامة لكل التطبيقات
└── 100/ ← فولدر برقم الـ APEX_APP_ID
├── overview.md ← هدف التطبيق، واليوزرات، ودورة العمل الرئيسية
├── architecture.md ← إدارة الـ State، الـ Collections، والـ Session Items
└── gotchas.md ← الحركات الغريبة، الفخاخ القديمة، والحلول الالتفافيةإيه اللي بيتكتب جوه app_context/100/architecture.md؟
# تطبيق 100: معمارية صفحة الدفع والشراء
## إدارة الـ State
- **محتويات السلة**: دايماً وأبداً بتدار جوه الـ APEX Collection المسماة `ORDER_CART`.
- ممنوع الاستعلام المباشر من جدول `PENDING_ORDERS` أثناء عملية الـ Checkout.
- تفاصيل العناصر:
- `c001`: كود المنتج (SKU)
- `n001`: الكمية المطلوبة
- `n002`: سعر الوحدة
## الأسعار والضرائب
- كل حسابات الضرائب لازم تنادي `PKG_BILLING.CALCULATE_TAX(p_cart_collection => 'ORDER_CART')`.
- ممنوع حساب الضريبة بالجافاسكريبت على المتصفح نهائياً.🧠 فهرسة الذاكرة جوه الـ Knowledge Graph
فولدر app_context/ مش مجرد شوية ملفات نصية مركونة على جنب وخلاص.
أول ما بتشغل أمر graphify extract .، أداة Graphify بتفهرس كل ملف Markdown جوه app_context/ كـ نود مفاهيمية معمارية (Architectural Concept Nodes) مربوطة مباشرة في جراف التطبيق!
┌──────────────────────────────────────┐ ┌──────────────────────────────────────┐
│ نود شاشة أبيكس │ │ نود الذاكرة المعمارية │
│ │ │ │
│ [ صفحة 20: شبكة الشراء ] ────────────┼───────┼──► [ مفهوم: كولكشن ORDER_CART ] │
│ │ │ └── قاعدة: "استخدم PKG_BILLING" │
└──────────────────────────────────────┘ └──────────────────────────────────────┘لما تطلب من الـ Agent يعدل صفحة 20، استعلام الجراف بيسحب مفهوم ORDER_CART أوتوماتيكياً في أول دور (Turn 1)—قبل ما يفكر يكتب سطر SQL غلط واحد.
📜 وصايا الـ Agents — ملف AGENTS.md والقواعد الإجبارية
عشان نضمن إن كل أدوات البرمجة بالذكاء الاصطناعي (Claude Code, Cursor, Copilot, Antigravity) تقرأ الذاكرة دي وتلتزم بيها، القالب بيحط تعليمات واضحة وصريحة في AGENTS.md:
# قاعدة: افحص السياق والذاكرة أولاً
قبل ما تعدل أو تولد كود لأي تطبيق:
1. افتح واقرأ محتويات `app_context/<app-id>/`.
2. راجع المشاكل المعروفة (Gotchas) وقواعد إدارة الـ State.
3. لو اكتشفت تركة غريبة في الكود أو حليت لغز معماري،
لازم تحدث ملف `app_context/<app-id>/gotchas.md` قبل ما تقفل الجلسة!بالطريقة دي، لما الـ Agent يحل bug معقدة ويوثقها في gotchas.md، مشروعك بيوثق نفسه بنفسه، وخبرة الفريق بتكبر وتتراكم مع كل Commit.
🚀 تأهيل في 60 ثانية: تشغيل أمر /init
لما مطور جديد (أو AI Agent لسه ميعرفش حاجة عن المشروع) يعمل Clone للمستودع، مش محتاج يقعد يقرأ ويكي من 40 صفحة عشان يبدأ يشتغل.
كل اللي بيعمله إنه بيكتب أمر التهيئة التفاعلي /init:
# تشغيل التهيئة التفاعلية
/init[INIT] مرحباً بك في إعداد مشروع Oracle APEX!
[INIT] جاري فحص المتطلبات الأساسية...
✓ تم العثور على بايثون 3.10+
✓ أداة SQLcl مثبتة وجاهزة
✓ أدوات Graphify و tree-sitter-sql مثبتة
✓ مستودع الـ Git نظيف ومستقر
[CONFIG] جاري إعداد ملف .env للمشروع:
• بيئة الداتابيز: [development]
• رقم تطبيق أبيكس: [100]
• الـ Parsing Schema: [APEX_PARSER]
• تم التحقق من اتصالات SQLcl المسماة بنجاح.
[GRAPH] جاري بناء الـ APEXlang Knowledge Graph...
✓ تم توليد 627 Nodes و 835 علاقة هندسية بنجاح.
[SUCCESS] اكتمل الإعداد! بيئة عملك محمية وجاهزة للبرمجة والانطلاق فوراً.🔮 إيه اللي مستنينا في مسك الختام (الجزء السادس)؟
في الجزء السادس (الحلقة الأخيرة من السلسلة)، هنجمع كل اللي اتعلمناه في تجربة عملية كاملة من الألف للياء (End-to-End Walkthrough):
- تخطيط ميزة جديدة خطوة بخطوة في
ai_generate/YYYY-MM-DD/. - توليد صفحة APEX و Package كاملة بالذكاء الاصطناعي.
- مراجعة الكود، والـ Deployment المحمي بحراس الأمان، والمزامنة الذرية التلقائية.
- تشغيل حزمة الاختبارات الشاملة (36 اختبار في
scripts/test_template.sh) للتأكد من الكمال الهندسي!
استنونا في الجزء السادس الكبير! 🚀🎉
كتبه: أحمد شريف (Ahmed Sherif).
