Claude Code Prompt Caching: اجعل مساعدك أسرع وأوفر

هل لاحظت أن Claude Code يردّ أحيانًا بسرعة، وأحيانًا يتأخر فجأة بعد أن غيّرت شيئًا صغيرًا؟ السرّ في ميزة اسمها prompt caching. Claude Code يديرها وحده، لكن فهمها يجعلك تعمل أسرع وتوفّر من استهلاك حسابك. في هذا الدرس ستعرف كيف تعمل، وما الذي يكسرها، وكيف تحافظ عليها.

🎯 ماذا ستتعلم؟

بنهاية هذا الدرس ستكون قادرًا على:

شرح لماذا يعيد Claude Code إرسال المحادثة كلها مع كل رسالة.
شرح فكرة الـ prefix وكيف يعيد الـ prompt caching استخدامه.
التمييز بين الأفعال التي تكسر الـ cache والأفعال التي تحافظ عليه.
معرفة مدة بقاء الـ cache، وفحص أدائه بالأمر /usage.

🧰 ماذا تحتاج قبل أن تبدأ؟

Claude Code مثبّت، وتعرف كيف تبدأ جلسة وتكتب طلبًا. ويفيدك أن تكون قرأت درس Claude Code Best Practices. وتذكّر أن حساب Claude يملكه شخص بالغ يتعلّم معك.

الفكرة ببساطة

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

لكن إن غيّرت مكعبًا في الأسفل، تغيّر كل ما فوقه. فيضطر صديقك أن يعدّ البرج كله من البداية.

هذا بالضبط ما يحدث في Claude Code. الجزء الثابت من البداية اسمه الـ prefix. ما دام الـ prefix كما هو، يُعاد استخدامه بسرعة. وإن تغيّر شيء فيه، يُعاد حساب كل ما بعده.

الخطوة 1: لماذا تُرسَل المحادثة كلها كل مرة؟

النموذج الذكي لا يتذكّر شيئًا بين رسالة وأخرى. لذلك يرسل Claude Code مع كل رسالة جديدة كل شيء من البداية: التعليمات الأساسية، وملفات مشروعك المهمة، وكل الرسائل السابقة، ثم رسالتك الجديدة.

المحتوى الجديد يُضاف دائمًا في النهاية. إذن معظم الطلب يطابق الطلب الذي قبله تمامًا. والـ prompt caching يعيد استخدام هذا الجزء المتطابق، فيعالج الجديد فقط.

النتيجة: ردود أسرع، وتكلفة أقل، لأن الجزء الموجود في الـ cache يُحسب بسعر أرخص.

الخطوة 2: طبقات الطلب الثلاث

يرتّب Claude Code كل طلب بحيث يأتي الأقل تغيّرًا أولًا:

الطبقة	ماذا فيها؟	متى تتغيّر؟
System prompt	التعليمات الأساسية، وتعريفات الأدوات	عندما تتغيّر مجموعة الأدوات المحمّلة
Project context	ملف `CLAUDE.md` والـ auto memory	عند بدء الجلسة، أو بعد `/clear` أو `/compact`
Conversation	رسائلك وردود Claude ونتائج الأدوات	مع كل رسالة

تغيير الـ conversation لا يمسّ الطبقتين الأوليين. أما تغيير الـ system prompt فيكسر كل شيء، لأنه في أسفل البرج.

والتطابق يجب أن يكون تامًا. فلا يوجد cache لكل ملف وحده، بل للـ prefix كله مرة واحدة.

الخطوة 3: أفعال تكسر الـ cache

هذه الأفعال تجعل الرد التالي أبطأ وأغلى مرة واحدة، ثم يُبنى الـ cache من جديد:

تغيير النموذج بالأمر /model: لكل نموذج cache خاص به، فيُقرأ كل شيء من جديد.
تغيير مستوى الـ effort في أغلب النماذج.
تشغيل الـ fast mode لأول مرة في المحادثة.
ربط MCP server أو إزالته في بعض الحالات، لأن تعريفات الأدوات في الطبقة الأولى.
ضغط المحادثة بالأمر /compact: يستبدل الرسائل بملخّص، فتتغيّر طبقة الـ conversation.
تحديث Claude Code إلى إصدار جديد: أول محادثة بعده تبني الـ cache من البداية.

لذلك اختر النموذج ومستوى الـ effort في بداية الجلسة. واستخدم /compact بين المهام، لا في منتصف مهمة.

الخطوة 4: أفعال تحافظ عليه

هذه الأفعال تضيف إلى نهاية المحادثة فقط، فلا تكسر شيئًا:

تعديل ملفات مشروعك: يضيف Claude Code تنبيهًا بأن الملف تغيّر، ويعيد قراءته عند الحاجة.
تشغيل الـ Skills والأوامر: تعليماتها تُضاف رسالةً جديدة في النهاية.
تغيير الـ permission mode، مثل الانتقال إلى قبول التعديلات تلقائيًا.
الرجوع بالأمر /rewind إلى رسالة سابقة: يعود إلى prefix موجود في الـ cache من قبل.

وهناك حالة مهمة: تعديل CLAUDE.md أثناء الجلسة لا يكسر الـ cache. لكن التعديل لا يُطبَّق أيضًا. يبقى Claude يعمل بالنسخة القديمة حتى تكتب /clear أو /compact، أو تعيد التشغيل.

الخطوة 5: كم يبقى الـ cache؟

الـ cache ينتهي بعد فترة بلا نشاط. وكل رسالة تستخدمه تعيد عدّاده من جديد، فيبقى «دافئًا» ما دمت تعمل.

هناك مدّتان: خمس دقائق وساعة واحدة. مع اشتراك Claude وضمن حدود خطتك، تأخذ المحادثة الرئيسية ساعة. أما مع API key أو مزوّد سحابي، فالمدة الافتراضية خمس دقائق.

لهذا قد يكون أول رد بعد استراحة طويلة أبطأ من المعتاد. هذا طبيعي تمامًا، فالـ cache يُبنى من جديد.

الخطوة 6: افحص أداء الـ prompt cache

اكتب هذا الأمر داخل جلسة Claude Code:

/usage

بعد أول رد في الجلسة، يظهر سطر اسمه Prompt cache (main). يعرض نسبة الـ cache hits، وعدد الـ cache misses، وهل الـ cache دافئ الآن. وقد يذكر السبب المحتمل لآخر miss، مثل likely cause: tool definitions changed.

النسبة العالية تعني أن الـ prompt caching يعمل جيدًا. وإن رأيت الـ misses تتكرّر، فراجع قائمة الأفعال في الخطوة 3.

🚀 للمتقدمين: تستطيع اختيار مدة الـ cache بنفسك بالإعداد promptCacheTtl، وقيمته 5m أو 1h. مثلًا في ملف .claude/settings.json: {"promptCacheTtl": "1h"}. لكن انتبه: الساعة الواحدة تجعل كتابة الـ cache أغلى، فتفيد فقط إن كنت تترك الجلسة وتعود إليها. وتستطيع رؤية نوع الـ cache المستخدم بالأمر claude -p "hello" --output-format json، ثم تقرأ الحقل usage.cache_creation في الناتج.

⚠️ أخطاء شائعة

1. تبديل النموذج في منتصف المهمة.

في منتصف مهمة طويلة تكتب هذا الأمر، ثم تعود إلى النموذج الأول بعد قليل:

❌ /model

✅ الحل: اختر النموذج في بداية الجلسة وابقَ عليه حتى تنتهي المهمة. كل تبديل يعني قراءة المحادثة كلها من جديد.

2. تعديل CLAUDE.md وانتظار أثره فورًا.

❌ أضفت قاعدة جديدة إلى CLAUDE.md، لكن Claude ما زال يتجاهلها!

✅ الحل: Claude يقرأ CLAUDE.md مرة واحدة عند بدء الجلسة. اكتب /clear لبدء محادثة جديدة، أو /compact، أو أعد تشغيل Claude Code.

3. انتظار الـ auto-compact في منتصف العمل.

✅ الحل: شغّل /compact بنفسك في استراحة طبيعية بين مهمتين. وإن أردت التخلّي عن طريق جرّبته، فاستخدم /rewind بدلًا منه، لأنه يعود إلى prefix موجود في الـ cache أصلًا.

🧪 جرّب بنفسك

التحدي 1 (سهل): صنّف كل فعل: هل يكسر الـ cache أم يحافظ عليه؟ (أ) تعديل ملف game.py (ب) تغيير النموذج بالأمر /model (ج) تشغيل Skill اسمها /quiz.

💡 اضغط لرؤية الحل

(أ) يحافظ: يُضاف تنبيه في نهاية المحادثة فقط.
(ب) يكسر: لكل نموذج cache خاص به.
(ج) يحافظ: تعليمات الـ Skill تُضاف رسالةً جديدة في النهاية.

التحدي 2 (متوسط): افتح جلسة Claude Code، واسأله سؤالين عن مشروعك. ثم اكتب /usage وابحث عن سطر Prompt cache (main). ما الذي يعرضه؟

💡 اضغط لرؤية الحل

/usage

يعرض السطر نسبة الـ cache hits، وعدد الـ misses، وهل الـ cache دافئ الآن. بعد سؤالين متتاليين يُفترض أن يكون الـ cache دافئًا.

التحدي 3 (للمتقدمين): أنت تعمل بـ API key، وتأخذ استراحة نصف ساعة كثيرًا ثم تعود للجلسة نفسها. ما الإعداد الذي يساعدك؟ اكتبه.

💡 اضغط لرؤية الحل

مع API key تكون المدة الافتراضية خمس دقائق، فينتهي الـ cache أثناء الاستراحة. اجعلها ساعة في .claude/settings.json:

{
  "promptCacheTtl": "1h"
}

تذكّر أن كتابة الـ cache تصبح أغلى، فهذا مفيد فقط مع الاستراحات الطويلة.

✅ اختبر نفسك

لماذا يرسل Claude Code المحادثة كلها مع كل رسالة؟ (أ) لأن الإنترنت بطيء (ب) لأن النموذج لا يتذكّر شيئًا بين الرسائل (ج) لكي يحذف الرسائل القديمة
صح أم خطأ: تعديل CLAUDE.md في منتصف الجلسة يُطبَّق فورًا.
أين يُضاف المحتوى الجديد في كل طلب: في البداية أم في النهاية؟

💡 اضغط لرؤية الإجابات

(ب) النموذج لا يتذكّر، لذلك يُرسل الـ prefix كاملًا كل مرة.
خطأ. التعديل يُطبَّق بعد /clear أو /compact أو إعادة التشغيل.
في النهاية، ولهذا يبقى الـ prefix متطابقًا ويُعاد استخدامه.

📝 الخلاصة

النموذج لا يتذكّر، فيرسل Claude Code المحادثة كلها مع كل رسالة.
الـ prompt caching يعيد استخدام الـ prefix المتطابق، فتصبح الردود أسرع وأرخص.
تغيير النموذج أو مستوى الـ effort أو الأدوات يكسر الـ cache، أما تعديل الملفات وتشغيل الـ Skills فلا.
الـ cache يبقى خمس دقائق أو ساعة، ويتجدّد مع كل رسالة.
تفحص أداءه بالأمر /usage من سطر Prompt cache (main).

⏭️ الخطوة التالية

صرت تعرف كيف تحافظ على سرعة مساعدك. في الدرس التالي ستكتشف Claude Code Prompt Library، لتكتب طلبات أقوى بسرعة. وتستطيع متابعة مسار Claude درسًا بعد درس.