🇬🇧 English Version: Read the original article in English here.
جلسة التعارف من أول يوم: إزاي تدي الـ AI ذاكرة دائمة بفولدر app_context/ 📓🧠
الجزء السادس من سلسلة “مطور APEX المدعوم بالذكاء الاصطناعي”.
⚡ الخلاصة في كلمتين (TL;DR)
الشغل مع مساعد ذكاء اصطناعي معندوش سياق دائم للمشروع، عامل بالظبط زي ما تعين استشاري كبير عبقري بس بيصحى كل يوم الصبح ناسي كل حاجة حصلت في حياته! كل يوم محتاج تشرح له من الصفر مكنة القهوة فين، وأنهي Schema اللي فيها بيانات العملاء، وليه أسامي الجداول في شركتنا لازم تبدأ بـ
HR_!بدل ما تقعد تنسخ وتلزق ديباجة برومبت طويلة ومملة في بداية كل شات جديد، تقدر تنشئ فولدر
app_context/<app-id>/وتربطه بـ طقس تهيئة سريع عبر أمر/init.الحركة دي بتسلم الـ Agent بتاعك “دوسيه ترحيب وذاكرة مؤسسية” بتحول أي جلسة شات فاضية لشريك برمجة فاهم كل تكة في معمارية نظامك في أقل من 30 ثانية!
🤯 يوم اليرموك اليومي مع مساعدي الذكاء الاصطناعي
لو قضيت أكتر من أسبوعين بتبرمج بمساعدة أدوات الـ AI، فأنت أكيد حافظ الحوار اليومي السخيف ده:
جلسة رقم 1 (يوم الإثنين):
أنت: "اعمل لي شاشة طلب كارت موظف جديد في صفحة 20."
الـ Agent: "من عينيّا! هعمل جدول T_BADGES بعمود Identity بيزيد تلقائي..."
أنت: "لأ يا عم الحج! حسب معايير شركتنا، كل جداول الـ HR بتستخدم Sequence اسمه HR_SEQ_،
ولازم أعمدة التدقيق الإلزامية (CREATED_BY, CREATED_ON)،
وتسمية الـ Packages بنظام PKG_HR_<MODULE>_API!"
الـ Agent: "أعتذر جداً عن الخطأ! هعيد كتابة الكود حسب معاييركم..."(تقفل الشات، تنام، وتفتح شات جديد خالص صباح يوم الثلاثاء)
جلسة رقم 2 (يوم الثلاثاء):
أنت: "دلوقتي اعمل لي شاشة الموافقات المنبثقة في صفحة 21."
الـ Agent: "تمام جداً! هعمل جدول T_APPROVALS بعمود Identity بيزيد تلقائي..."
أنت: "🤦♂️ هو إحنا هنعيد نفس الموشح كل يوم الصبح؟!"التكرار اللانهائي ده بيحرق أعصابك، وبيشتت تركيزك، وبيحرق رصيد التوكنز. نموذج الذكاء الاصطناعي مش قاصد يعاندك ولا كسلان—هو ببساطة شغال بنظام (Stateless)؛ كل جلسة جديدة بتبدأ بصفحة بيضاء تماماً وميعرفش أي حاجة عن ماضيك معاه.
قوالب الـ System Prompts في واجهات الشات بتساعد شوية، بس بتقدم بسرعة، وبتتوه بين فروع الـ Git، ومبتتشاركش بين أعضاء الفريق.
عشان نحل المشكلة دي للأبد، بنتعامل مع السياق كأنه كود برمجي (Context as Code).
📓 دوسيه الترحيب: فولدر app_context/<app-id>/
في شغل السوفتوير الحديث المدعوم بالذكاء الاصطناعي، كل تطبيق في مستودعك لازم يحتفظ بـ “دوسيه توثيق حي” جوه فولدر app_context/<app-id>/:
my-apex-project/
└── app_context/
└── 100/ ← رقم تطبيق أبيكس (نظام الـ ERP أو الـ HR)
├── APP_ARCHITECTURE.md ← المعمارية العامة ونظام الأمان والصلاحيات
├── DATABASE_MODEL.md ← الـ Schemas، معايير التسمية، والجداول
├── BUSINESS_RULES.md ← قيود البيزنس والحدود المالية الثابتة
└── CONVENTIONS.md ← معايير كتابة الكود وتسمية عناصر أبيكسدي مش مواصفات ميتة من 500 صفحة؛ دي ملفات Markdown مركزة جداً ومكتوبة بنقاط سريعة بتحدد قواعد اللعبة للتطبيق ده تحديداً.
تعالوا نشوف كل ملف فيهم بيشيل إيه:
1. ملف APP_ARCHITECTURE.md (الرسم المعماري)
بيحدد التطبيق مبني إزاي، نظام الأمان، وشجرة القوائم:
# تطبيق 100: بوابة إدارة الطلبات والمبيعات
- **إصدار أبيكس المستهدف**: APEX 26.1 (Universal Theme)
- **المصادقة الأساسية**: نظام مصادقة مخصص (`PKG_AUTH.AUTHENTICATE`)
- **خطط الصلاحيات (Authorization Schemes)**:
- `AUTH_ADMIN`: بيتطلب دور `ROLE_ADMIN` في جدول `APP_USERS`
- `AUTH_SALES_REP`: الدور الافتراضي لكل الموظفين
- **مكونات عامة في التطبيق**:
- صفحة 0 (Global Page): فيها شريط التنبيهات الموحد للرسائل الإدارية
- قائمة التنقل: قائمة ديناميكية معتمدة على `USER_PERMISSIONS_V`2. ملف DATABASE_MODEL.md (معايير الداتابيز)
بيثبت حدود الـ Schemas، ملكية الجداول، وطريقة توليد المفاتيح:
# معايير قاعدة البيانات والـ Schemas
- **معمارية الـ Dual-Schema المزدوجة**:
- `APP_CODE`: مالك كود البرمجة (الـ Packages، والـ Views، ويوزر الـ Deployer)
- `APP_DATA`: مالك البيانات والجداول (Tables، Indexes، Sequences)
- **معيار المفتاح الأساسي (PK)**: عمود `NUMBER(18,0)` بيتغذى من Sequence صريح عبر Trigger (`SEQ_<TABLE_NAME>`)
- **أعمدة التدقيق الإلزامية في كل الجداول بدون استثناء**:
- `CREATED_ON DATE DEFAULT SYSDATE NOT NULL`
- `CREATED_BY VARCHAR2(100) DEFAULT NVL(V('APP_USER'), USER) NOT NULL`
- `UPDATED_ON DATE`
- `UPDATED_BY VARCHAR2(100)`
- **قاعدة الحذف المنطقي (Soft-Delete)**: الجداول الحساسة بتستخدم `IS_DELETED CHAR(1) DEFAULT 'N' CHECK (IS_DELETED IN ('Y', 'N'))`3. ملف BUSINESS_RULES.md (قواعد البيزنس الثابتة)
بيسجل شروط البيزنس عشان الـ AI ميهبدش منطق يخالف سياسة الشركة:
# قواعد ومنطق البيزنس الجوهرية
1. **شرائح الخصومات للعملاء**:
- خصم حتى 15%: بيعتمد أوتوماتيكياً بدون مراجعة.
- خصم من 15% وحتى 30%: بيتطلب موافقة صريحة من مدير المبيعات.
- خصم أكتر من 30%: ممنوع تماماً؛ ويرمي Exception برقم `-20050`.
2. **دورة حياة الأوردر (Order State Machine)**:
- `DRAFT` ──> `SUBMITTED` ──> `APPROVED` ──> `FULFILLED`
- مستحيل الأوردر ينط من مسودة `DRAFT` لمعتمد `APPROVED` مباشرة.4. ملف CONVENTIONS.md (دليل الأسلوب وتسمية العناصر)
بيقفل أي نقاش أو تضارب في التسمية، وبيخلي أي كود طالع كأن أشطر مهندس Senior في الفريق هو اللي كاتبه:
# معايير التسمية في APEX و PL/SQL
- **حقول الصفحات**: `P<PAGE>_<PURPOSE>` (مثال: `P12_CUSTOMER_NAME`, `P12_ORDER_TOTAL`)
- **الزراير**: `BTN_<ACTION>` (مثال: `BTN_SUBMIT`, `BTN_CANCEL`, `BTN_APPLY_DISCOUNT`)
- **الـ Dynamic Actions**: `DA_<EVENT>_<TARGET>` (مثال: `DA_CHANGE_DISCOUNT_CODE`)
- **عمليات الصفحات**: `PROC_<ACTION>` (مثال: `PROC_SAVE_ORDER_HEADER`)
- **أسماء الـ Packages**: `PKG_<MODULE>_API` (مثال: `PKG_CHECKOUT_API`)🚀 بروتوكول الـ /init: تأهيل في 30 ثانية
بعد ما جهزت الدوسيه ده، إزاي توكله للـ Agent من غير ما تفضل تقص وتلزق كل مرة؟
بتعمل طقس تهيئة بسيط جداً: أمر /init.
كل ما تفتح شات جديد في Cursor أو Antigravity أو التيرمينال، كل اللي بتعمله إنك بتكتب:
/initالـ Agent بيشغل روتين التهيئة القياسي:
- قراءة ملف
.env: بيعرف التطبيق النشط (100) والـ Schema المستهدفة (APP_CODE). - فحص
app_context/100/: بيقرا الملفات الأربعة المعمارية. - التأكد من الـ Knowledge Graph: بيتأكد إن شبكة العلاقات محدثة.
- طباعة شاشة التأكيد الخضراء:
[تم تجهيز الـ Agent بنجاح]:
✓ التطبيق المحمل: 100 ("بوابة إدارة الطلبات والمبيعات")
✓ الـ Schemas النشطة: APP_CODE (للبرمجة) | APP_DATA (للداتا)
✓ المعايير المفروضة: تريجرات الـ Sequences، أعمدة الـ Audit، بادئات P<PAGE>_*
✓ قواعد البيزنس مفعلة: شرائح موافقات الخصم ودورة حياة الأوردر
✓ حالة الـ Knowledge Graph: تم فهرسة 412 Node و 980 علاقة
أنا جاهز لتعليماتك يا فنان!من اللحظة دي، أي حقل الـ Agent هيبنيه هيبدأ بـ P12_، وأي جدول هيعمله هيحتوي على أعمدة الـ Audit الأربعة، وأي شرط خصم هيطبق شرائح البيزنس المظبوطة—من أول محاولة وبدون أي أخطاء!
🎁 المكسب المزدوج: ذاكرة للذكاء الاصطناعي وتأهيل سريع للبشر!
أحلى ما في دوسيه app_context/ إنه بيضرب عصفورين بحجر واحد:
نفس الملفات الأربعة اللي بتدي للـ AI ذاكرة خارقة، بتحل واحدة من أكبر عقد الشركات البرمجية: تأهيل المطورين الجدد (Developer Onboarding).
لما ينضم لفريقك مطور Junior جديد أو استشاري خارجي، بدل ما تقعد معاه أسبوعين تشرح له معايير التسمية وجداول الداتابيز، بتديه فولدر app_context/<app-id>/. في خلال ساعة واحدة بس، بيبقى فاهم معمارية المشروع وقواعد البيزنس كأنه شغال معاكم من سنتين!
🛠️ إزاي تضيف فولدر السياق لمشروعك؟
مش هياخد منك 15 دقيقة:
- أنشئ الفولدر: ضيف
app_context/في الـ Root. - اكتب الملفات الأربعة:
APP_ARCHITECTURE.md، وDATABASE_MODEL.md، وBUSINESS_RULES.md، وCONVENTIONS.md. - اربطه بتعليمات الـ Agent: جوه ملف القواعد (مثل
AGENTS.md) كالآتي:“لما اليوزر يكتب
/init، اقرأ ملف.env، وحمل كل ملفات الـ Markdown فيapp_context/<app-id>/، وأكد تحميل السياق قبل ما تبدأ البرمجة.”
[!TIP]
📦 عايز قوالب سياق جاهزة؟
مستودع APEX Project Template بيحتوي على قوالب Markdown جاهزة لفولدر
app_context/مع سكربت/initوقواعد الـ Agents متظبطة. تقدر تاخدها كوبي وبيست في مشروعك وتعدل عليها فوراً!
🚀 إيه اللي مستنينا في مسك الختام (الجزء السابع)؟
دلوقتي كودنا بقى مقسم لملفات .apx نظيفة، وعلاقاتنا مرسومة في Knowledge Graph، ومناطق المعمل النظيف معزولة، والـ Agent بقى معاه ذاكرة حديدية مابتنساش.
مفاضلش غير قطعة واحدة أخيرة وحاسمة جداً: زرار إطلاق الصاروخ للـ Deployment.
إزاي نسمح للـ AI أو لسكربتات الـ CI/CD تشغل الـ Migrations عبر SQLcl من غير الرعب القاتل إن سكربت تجارب يضرب في داتابيز الـ Production الحية؟
في ختام السلسلة، الجزء السابع (“إطلاق الصاروخ بالمفتاحين: حراس أمان SQLcl المحكمة”)، هنبني Pipeline مزدوج المفاتيح باتصالات معزولة الصلاحيات وفحوصات هوية آلية تحميك من أي خطأ بشري أو ذكاء اصطناعي!
نشوفكم في الحلقة الأخيرة الكبيرة! 🔑🚀✨
كتبه: أحمد شريف (Ahmed Sherif).
