استراتيجيات نافذة السياق

تحدي السياق

قواعد الكود الكبيرة تقدم تحديًا جوهريًا لمساعدي الذكاء الاصطناعي:

• سياق Claude: ~200K رمز (Opus 4.5)
• قاعدة كود كبيرة نموذجية: 500K - 5M+ سطر
• نسبة الأسطر للرموز: ~1 سطر ≈ 3-5 رموز

قاعدة كود 500K سطر = 1.5M - 2.5M رمز. لا يمكنك وضعها كلها في السياق.

تحميل السياق الاستراتيجي

نهج السياق المتعدد الطبقات

الطبقة 1: نظرة عامة على المشروع (محملة دائمًا)
├── وثائق الهندسة المعمارية
├── هيكل الدليل
└── الواجهات الرئيسية

الطبقة 2: سياق المجال (خاص بالمهمة)
├── الوحدات ذات الصلة
├── تعريفات الأنواع
└── أمثلة الاختبار

الطبقة 3: تفاصيل التنفيذ (عند الطلب)
├── الملفات المحددة التي يتم تعديلها
├── اعتماديات تلك الملفات
└── التغييرات الأخيرة

تنفيذ طبقات السياق

الطبقة 1: إنشاء نظرة عامة على المشروع

<!-- .claude/CLAUDE.md -->

# نظرة عامة على المشروع

## الهندسة المعمارية
- Next.js 15 App Router للواجهة الأمامية
- Node.js/Express API للخادم
- PostgreSQL + Prisma ORM
- Redis للتخزين المؤقت
- S3 لتخزين الملفات

## الدلائل الرئيسية
- `/src/app` - صفحات ومسارات Next.js
- `/src/components` - مكونات React (التصميم الذري)
- `/src/lib` - الأدوات المشتركة
- `/api/src/routes` - نقاط نهاية API
- `/api/src/services` - منطق الأعمال
- `/packages/shared` - الأنواع والأدوات المشتركة

## الأنماط الأساسية
- نمط Repository للوصول للبيانات
- طبقة الخدمة لمنطق الأعمال
- React Query لحالة الخادم
- Zod للتحقق

## نقاط الدخول
- الواجهة: `src/app/page.tsx`
- API: `api/src/index.ts`
- العمال: `workers/src/index.ts`

الطبقة 2: سياق خاص بالمجال

claude "أحتاج العمل على نظام الدفع.
حمّل السياق لـ:
1. الأنواع المتعلقة بالدفع
2. تكامل Stripe
3. تدفق معالجة الطلبات
4. الاختبارات ذات الصلة"

Claude Code يقرأ استراتيجيًا:

جارٍ تحميل سياق مجال الدفع:
- packages/types/src/payment.ts (الأنواع)
- api/src/services/payment.ts (الخدمة)
- api/src/services/stripe.ts (التكامل)
- api/src/routes/checkout.ts (نقطة النهاية)
- tests/payment.test.ts (الأمثلة)

الإجمالي: 1,200 سطر (~5K رمز)
السياق المتبقي: 195K رمز

تقنيات تحسين السياق

1. التحميل بالواجهة أولاً

حمّل الواجهات والأنواع قبل التنفيذات:

claude "اقرأ فقط الواجهات المُصدَّرة من
src/services/. لا تقرأ التنفيذات بعد."

// الذكاء الاصطناعي يستخرج الأشكال فقط
interface PaymentService {
  createIntent(amount: number, currency: string): Promise<PaymentIntent>;
  confirmPayment(intentId: string): Promise<PaymentResult>;
  refund(paymentId: string, amount?: number): Promise<RefundResult>;
}

interface OrderService {
  create(items: CartItem[], userId: string): Promise<Order>;
  fulfill(orderId: string): Promise<void>;
  cancel(orderId: string, reason: string): Promise<void>;
}

2. القراءة الانتقائية للملفات

claude "اقرأ src/services/payment.ts لكن فقط
دالتي createIntent و confirmPayment، تخطَّ
بقية الملف."

3. السياق القائم على الملخصات

claude "لخّص ما يفعله كل ملف في src/services/
في جملة واحدة. سأسأل عن تفاصيل ملفات محددة."

الذكاء الاصطناعي يقدم نظرة عامة مكثفة:

ملخص src/services/:
- auth.ts: مصادقة المستخدم مع رموز JWT و OAuth
- payment.ts: معالجة الدفع Stripe وإدارة الاشتراكات
- order.ts: دورة حياة الطلب من الإنشاء للتنفيذ
- notification.ts: إرسال البريد الإلكتروني وإشعارات الدفع
- inventory.ts: إدارة المخزون ونظام الحجز
- analytics.ts: تتبع الأحداث ومقاييس الاستخدام

4. السياق القائم على الفروقات

للتغييرات، حمّل فقط ما هو مختلف:

claude "ما الذي تغير في src/services/ في الأسبوع الماضي؟
اقرأ فقط الأقسام المعدلة."

# الذكاء الاصطناعي يشغل
git diff --stat HEAD~7 -- src/services/

# ثم يقرأ بشكل انتقائي الأجزاء المتغيرة
git diff HEAD~7 -- src/services/payment.ts

نقاط التحقق للسياق

إنشاء جلسات قابلة للاستئناف

claude "نحن نعمل على إعادة هيكلة الدفع.
أنشئ ملف نقطة تحقق مع:
1. ما حللناه حتى الآن
2. الملفات التي عدلناها
3. الخطوات التالية
4. القرارات الرئيسية المتخذة"

<!-- .claude/checkpoints/payment-refactor.md -->

# نقطة تحقق إعادة هيكلة الدفع

## التاريخ: 2026-01-06
## الجلسة: 3

### تم التحليل
- [x] تدفق الدفع الحالي (3 نقاط اتصال)
- [x] معالجة webhook من Stripe
- [x] آليات استرداد الأخطاء

### تم التعديل
- api/src/services/payment.ts (أُضيف منطق إعادة المحاولة)
- api/src/routes/webhooks.ts (تم تحسين الـ idempotency)

### القرارات
1. استخدام تراجع أسي لإعادة المحاولات (5 محاولات كحد أقصى)
2. تخزين الدفعات الفاشلة في قائمة الرسائل الميتة
3. إضافة آلة حالة الدفع للتتبع

### الخطوات التالية
1. تنفيذ معالج قائمة الرسائل الميتة
2. إضافة مراقبة لفشل الدفع
3. تحديث الاختبارات لسلوك إعادة المحاولة الجديد

استئناف الجلسات

claude "اقرأ نقطة تحقق payment-refactor و
استمر من حيث توقفنا."

إدارة ميزانية الرموز

راقب استخدامك

claude "قدّر كم عدد الرموز في سياقي الحالي.
اذكر أكبر الملفات واقترح ما يجب إفراغه."

تقدير السياق الحالي: 45,000 رمز

أكبر العناصر:
1. api/src/services/payment.ts - 2,100 سطر (~8K رمز)
2. packages/types/src/index.ts - 1,500 سطر (~6K رمز)
3. سجل المحادثة - (~12K رمز)

التوصيات:
- أفرغ packages/types، حمّل فقط الأنواع المتعلقة بالدفع
- فكر في تلخيص payment.ts، حمّل فقط الدوال النشطة
- امسح سياق المهام المكتملة من المحادثة

إفراغ السياق

claude "انسَ تدفق مصادقة المستخدم،
انتهينا منه. ركز فقط على الدفعات الآن."

أفضل الممارسات لقواعد الكود الكبيرة

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

قادم

بعد ذلك، سنتعلم أنماط التنقل في قاعدة الكود—كيف تجد وتفهم الكود بكفاءة في المشاريع الضخمة. :::