دليل Claude AI: نصائح وأفضل الممارسات

خطافات Claude Code هي أوامر شِل يعرّفها المستخدم وتُنفَّذ تلقائيًا عند نقاط محددة في دورة حياة Claude Code، فتجعل قاعدة "يجب أن يحدث هذا دائمًا" حقيقية وحتمية دون الاعتماد على حكم نموذج اللغة الكبير. الأحداث الكلاسيكية تسعة — SessionStart، وUserPromptSubmit، وPreToolUse، وPostToolUse، وNotification، وStop، وSubagentStop، وSessionEnd، وPreCompact — ومنها PreToolUse وغيره يمكنه الحظر (موقِفًا تعديلات الملفات المحمية أو الأوامر الخطيرة). تُعِدّها في settings.json تحت مفتاح "hooks" على هيئة اسم الحدث ← matcher ← type + command. عقد الإدخال/الإخراج: يتلقى الخطاف JSON على stdin (session_id، وtool_input، إلخ) ويُرجع عبر رمز الخروج 0 (نجاح) / 2 (حظر، مع تمرير stderr إلى Claude) أو JSON مُهيكَل (continue، وdecision:block، وpermissionDecision: deny/allow/ask). المبدأ الرئيسي هو "يمكن للخطافات التشديد لا التخفيف للقيود" (deny تفوز دائمًا، وتحظر حتى في وضع bypassPermissions؛ لكن الـ mod قد يتجاوز ذلك في بعض الحالات). حالات استخدام كلاسيكية: التنسيق التلقائي بعد التعديلات (PostToolUse + Edit|Write)، وحماية الملفات الحرجة، وإيقاف الأوامر الخطيرة، وإعادة حقن السياق (SessionStart)، والإشعارات/سجل التدقيق، والاختبار قبل التوقف (Stop). بخصوص الأمان، تشغّل الخطافات أوامر شِل عشوائية بصلاحياتك، لذا لا تُعِدّ سوى الموثوقة منها وتحقّق من المدخلات واقتبسها؛ وفي الجلسات التفاعلية لا تعمل خطافات ملفات الإعدادات حتى تثق بالمجلد (ميزة أمان)، والتعديلات المباشرة على تلك الملفات تسري عادةً تلقائيًا. استنادًا إلى التوثيق الرسمي، مرتكزًا على الأحداث التسعة الكلاسيكية وعقد الإدخال/الإخراج.

checkpointing و ‎/rewind شبكة أمان: يتتبع Claude Code تلقائيًا تعديلات Claude للملفات أثناء عملك، فتعود إلى "ما قبل الخطأ" بضغطات قليلة. تُلتقط لقطة قبل كل تعديل، ويصبح كل موجّه ترسله نقطة استعادة، وتستمر نقاط التفتيش عبر الجلسات. للاستخدام، اكتب ‎/rewind أو اضغط Esc مرتين عندما يكون الإدخال فارغًا لفتح القائمة، ثم اختر نقطة واختر استعادة الكود والمحادثة / استعادة المحادثة / استعادة الكود (ملاحظة: إذا احتوى الإدخال على نص، فإن Esc مرتين يمسحه بدلًا من ذلك). التحذير الأهم: تُستعاد فقط التغييرات التي تتم عبر أدوات تحرير Claude (Write/Edit/NotebookEdit) — أما تغييرات أوامر bash (rm/mv/cp)، والتغييرات خارج الجلسة أو من جلسات أخرى، وتعديلات الوكلاء الفرعيين، والملفات ذات الروابط الرمزية أو الصلبة، وحالة قاعدة البيانات فلا يُتراجَع عنها عبر rewind. تصف الوثائق نقاط التفتيش بأنها "مصممة للاستعادة السريعة على مستوى الجلسة"، وتوصي بالاستمرار في استخدام نظام للتحكم في الإصدارات مثل Git للتاريخ الدائم والعمل المشترك، لذا الالتزام بـ Git عند المعالم هو القاعدة. كما أن ‎/rewind هو التعافي من خطأ 400 المرتبط بتزامن استخدام الأدوات وكتل التفكير (يدفعك المنتج نفسه لتشغيله)، رغم أن الإصدارات السابقة لـ v2.1.156 قد لا تزيله فيأتي claude update أولًا. مُفعّل افتراضيًا في واجهة سطر الأوامر التفاعلية، واشتراك صريح في Agent SDK، ومُحتفَظ به مع الجلسات لمدة 30 يومًا (قابل للتهيئة). استنادًا إلى الوثائق الرسمية، مع الإشارة إلى مواطن عدم اليقين.

أُطلق Claude Managed Agents كإصدار تجريبي عام في 8 أبريل 2026 كمجموعة من واجهات برمجة التطبيقات القابلة للتركيب لبناء ونشر وكلاء مستضافين على السحابة على نطاق واسع. بدلاً من بناء حلقة الوكيل الخاصة بك وتنفيذ الأدوات وبيئة التشغيل، تحصل على بيئة مُدارة بالكامل يمكن فيها لـ Claude قراءة الملفات وتشغيل الأوامر وتصفح الويب وتنفيذ التعليمات البرمجية بأمان، مع تخزين مؤقت للموجّهات وضغط للسياق وعزل في sandbox وحفظ للحالة مدمجة. وهو منظَّم حول أربعة مفاهيم (Agent وEnvironment وSession وEvents)، ويمكن أن تكون الـ Environment بيئة سحابية مُدارة من Anthropic أو ذاتية الاستضافة. والفرق عن Agent SDK ذاتي الاستضافة (حيث تُشغّل الحلقة والأدوات والبنية التحتية) هو "أنت تشغّله مقابل Anthropic تشغّله" — ليسا متنافسَين بل خيار حول مقدار ما تحتفظ به من التشغيل. ومن السمات المميّزة الذاكرة الدائمة المحدودة بنطاق مساحة العمل (memory store) المُركّبة في الـ sandbox على ‎/mnt/memory، يقرأها الوكيل ويكتب إليها بعمليات الملفات الاعتيادية وتبقى عبر الجلسات (نسخ غير قابلة للتعديل، النسخ السابقة تُحفظ 30 يوماً والحديثة دائماً، حدود مثل 100 kB لكل ذاكرة). والـ dreaming مهمة غير متزامنة تقرأ الذاكرة القائمة والنصوص السابقة لإنتاج متجر ذاكرة مُعاد تنظيمه — بدمج المكرّرات وتحديث القيم القديمة وإبراز رؤى جديدة (معاينة بحثية تتطلب وصولاً؛ تصفها تدوينة إطلاق Anthropic بـ"المجدولة"، بينما تصفها وثائق الواجهة البرمجيّة بمهمة غير متزامنة تُنشئها وتتابع حالتها). ويتضمن أيضاً تقييماً قائماً على النتائج (يقيّم مُقيّم منفصل وفق معيارك؛ تحسّن يصل إلى 10 نقاط في اختبارات Anthropic نفسها) وتنسيق تعدد الوكلاء. والتسعير هو الرموز (tokens) + 0.08$ لكل ساعة جلسة (يُقاس بالملّي ثانية، فقط أثناء التشغيل؛ نحو 0.705$ لجلسة مدتها ساعة في المثال العملي من Anthropic بأسعار Claude Opus 5). مُفعَّل افتراضياً لجميع حسابات الـ API، لكنه ذو حالة لذا غير مؤهّل لـ ZDR أو HIPAA BAA. استناداً إلى المعلومات الرسمية، مع الإشارة إلى أوجه عدم اليقين.

تجمع إضافات Claude Code المهارات والوكلاء الفرعيين والخطافات وإعدادات MCP وامتدادات أخرى للتوزيع. والسوق كتالوج يحدد مصادر جلبها. يشرح المقال الكتالوج الرسمي وكتالوج المجتمع والتسجيل والتثبيت والتفعيل، ثم يتتبع إنشاء مهارة والتحقق من إضافتها وكتالوجها منفصلين وتوزيعهما عبر Git ببنية مجلدات متسقة. ويتناول نطاقات التثبيت وشروط التحديث المرتبطة بالإصدار وحدود ما تضمنه المراجعة الأمنية.

تتشابه الأسماء بين subagents وAgent Teams في Claude Code، لكن دوريهما وأسلوب التنسيق مختلفان جوهريًا. الـ subagents ميزة مدمجة تفوّض مهمة إلى مساعد بسياق جديد وتستعيد ملخّصًا فقط (هرمي، تتداخل افتراضيًا حتى 3 طبقات). أما Agent Teams فتجريبية معطّلة افتراضيًا (تحتاج CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1) وتتنسّق فيها جلسات مستقلة كأقران عبر قائمة مهام مشتركة. يوضّح المقال الفرق الحاسم وأيهما تستخدم وكيف.

Claude Design أداة تصميم من Anthropic Labs تتيح إنشاء واجهات المستخدم والنماذج الأولية وصفحات الملخّص عبر المحادثة، وصارت منذ 16 سبتمبر 2026 تعمل داخل أي محادثة. أضاف تحديث 17 يونيو 2026 استيراد أنظمة التصميم والتنقّل مع Claude Code: ينقل ‎/design-sync نظام التصميم من الـ repo إلى Claude Design، ويتولى التسليم إلى Claude Code و‎/design نقل التصاميم إلى الكود، مما قلّص رحلة الذهاب والإياب بين المصممين والمطورين. يشرح المقال ما هي الأداة وما الذي تغيّر وتوزيع الأدوار بين ‎/design-sync و‎/design وشروط الاستخدام ولماذا يُعدّ هذا مهمًّا.

في 18 يونيو 2026 أعلنت Anthropic عن Claude Code Artifacts، وهي ميزة تحوّل جلسة البرمجة في الطرفية إلى صفحة ويب حيّة يمكن لفريقك مشاركتها. فبدلًا من تدفّق git diff والسجلات نصًا بلا نهاية، ينشر Claude Code جولة PR مشروحة، ولوحة معلومات ذاتية التحديث، وخطًا زمنيًا للحوادث، وقائمة تحقّق تُعلَّم بنفسها، كصفحة واحدة على رابط claude.ai خاص. يشرح المقال ما هو، وكيف يختلف عن Artifacts ذي نمط اللوحة في claude.ai لعام 2024 (مصدره الجلسة، ذاتي التحديث، خاص افتراضيًا)، وكيفية استخدامه (لا يوجد أمر ‎/artifact، بل تطلب بلغة طبيعية؛ يكتب Claude ملف ‎.html وينشره ويطبع الرابط؛ ويتيح Share المشاركة داخل المؤسسة أو برابط عام)، وقيوده (التقاطٌ للعمل: بلا خلفية، وCSP صارمة تحدّ من الطلبات الخارجية، صفحة واحدة، حتى 16 MiB)، وتوفّره (Pro/Max/Team/Enterprise، مع تسجيل دخول إلزامي عبر ‎/login، وواجهة Anthropic API فقط) — استنادًا إلى الوثائق الرسمية.

تظهر أخطاء المصادقة في Claude Code مثل «Not logged in» و«Invalid API key» و«organization has been disabled» عادةً بصفة 401/403. السبب الحقيقي الأكثر شيوعًا هو أن متغيّر البيئة ANTHROPIC_API_KEY يتجاوز بصمت تسجيل دخول اشتراكك، فيُنتج رسومًا غير متوقعة ورفضًا للدخول. يشرح المقال ترتيب أولوية بيانات الاعتماد، وسير تشخيص من ‎/status إلى unset ثم ‎/logout و/login، وتمييزه عن 429 و529 وحد الاستخدام.

يكون الخطأ «command not found: claude» في معظم الحالات مجرّد أن مجلد التثبيت (‎~/.local/bin) غير مُدرَج في PATH؛ الملف الثنائي موجود، فيكفي إضافة سطر واحد وإعادة تشغيل الطرفية. يغطي المقال طرق التثبيت ومواقعه، وإصلاح PATH، وتعارض عمليات التثبيت المتعددة، ومزالق Windows، والتحديث. خطأ npm EACCES يُحَلّ بالانتقال إلى المثبّت الأصلي لا بـ sudo، وعند التعثّر شغّل claude doctor.

أخطاء الشبكة في Claude Code («Can't reach the API server» و«Connection refused» وSSL certificate verification failed وfetch failed) تعني أن الطلب لم يصل إلى خادم Anthropic أصلًا، وليست مصادقة أو تحميلًا زائدًا أو حدّ معدل. وقبل الإصدار v2.1.227 كانت الأخطاء نفسها تظهر بصيغة «Unable to connect to API (ECONNREFUSED)». يشرح المقال معنى كل رسالة حالية، والخروج عند الإعداد الأولي برسالة «Unable to connect to Anthropic services»، وتحذير «Streaming response ended before any complete data was received» حين يغيّر بروكسي الاستجابة، وضبط HTTPS_PROXY، والوثوق بشهادة CA المؤسسية عبر NODE_EXTRA_CA_CERTS، والنطاقات الواجب السماح بها، وسير عمل التشخيص. لا تعطّل التحقق أبدًا عبر NODE_TLS_REJECT_UNAUTHORIZED=0.

حين يتوقّف Claude Code فجأة برسالة «API Error: 529 Overloaded» أو «500 Internal server error»، فهذان حدثان عابران من جانب الخادم — وليسا خطأً في طلبك أو إعداداتك، ولا نفادًا لاستخدامك. يشرح هذا المقال معنى 529 (ازدحام واجهة Anthropic API مؤقتًا) و500 (خطأ داخلي غير متوقّع)، وأنهما لا يستهلكان حصتك، وكيف يعيد Claude Code المحاولة تلقائيًا حتى 10 مرات بتراجع أسّي، والحلول من جانب المستخدم (الانتظار، والتبديل بـ/model، ومراجعة status.claude.com، و/feedback مع request_id)، والتمييز بينه وبين 429 وusage limit و400، وإرشادات المطورين، وكيفية تمييز الارتفاع العابر عن العطل المستمر.

رسالة «You've hit your session limit · resets 3:45pm» في Claude Code ليست خطأً، بل آلية عمل حدود استخدام الاشتراك. يسرد المرجع الرسمي أربع صيغ: session (نافذة الخمس ساعات المتدحرجة)، وweekly (النافذة الأسبوعية)، وOpus وSonnet (حدود لعائلة واحدة من النماذج)؛ ولأن حدّي الجلسة والأسبوع مشتركان بين كل النماذج، فتغيير النموذج لا يعيد الوصول. يشرح المقال معنى كل رسالة وكيف تغيّر النصّ منذ الصياغة القديمة «Claude usage limit reached»، وما الذي يستهلك الحصّة، وما الذي تفعله لحظة بلوغ السقف: تبديل النموذج عبر ‎/model مع حدّ Opus/Sonnet، أو انتظار الإعادة (تلقائياً منذ الإصدار v2.1.234)، أو أرصدة الاستخدام عبر ‎/usage-credits، أو التحوّل إلى API بنظام الدفع حسب الاستخدام، إضافةً إلى كيفية رؤية ما تبقّى عبر ‎/usage والرسائل المشابهة التي لا تعني بلوغ حدّك.