ملفات settings.json: الإعدادات الشخصية والمشاريع

📚 تنقل السلسلة: المقال السابق 30 كيفية اختيار الميزات المناسبة: CLAUDE.md مقابل المهارات والخطافات والـ MCP والوكلاء علمك كيفية تحديد الميزة والمسار الأنسب لمهمتك البرمجية. وينتقل هذا المقال لخطوة أعمق - أين يتم حفظ إعدادات هذه الميزات، وكيف يتم ترتيب الأولويات بين الإعدادات الشخصية وإعدادات المشاريع. يمثل ملف settings.json لوحة التحكم الرئيسية لـ Claude Code، وسنقوم اليوم بتوضيح قواعد عملها بالتفصيل.

هناك خطأ بسيط وشائع يقع فيه الكثير من المستخدمين، وعند مواجهته لمرة واحدة لن تنساه أبداً.

عند بدء استخدام Claude Code بشكل فعلي، من الممارسات الشائعة إضافة سطر "defaultMode": "auto" في ملف .claude/settings.json الخاص بمشروع معين لتفعيل وضع التشغيل الحر تلقائياً وتجنب مقاطعتك بالأسئلة عند كل خطوة. ولكن بعد حفظ الملف، لن تلاحظ أي تغيير. في البداية ستظن أنك كتبت اسم الحقل بشكل خاطئ، وستقوم بمطابقة الكلمات مع التوثيق الرسمي عدة مرات لتكتشف أن الحروف صحيحة تماماً. ثم ستشك في سلامة صياغة ملف JSON وتفحصه ببرامج التدقيق لتجد أنه سليم ومطابق للمواصفات. وقد تضيع قرابة عشرين دقيقة في الفحص وتظن أن المشكلة تعود لخطأ برمجى في هذا الإصدار من Claude Code.

لتكتشف لاحقاً ملاحظة مكتوبة في زاوية التوثيق الرسمي: عند تعيين defaultMode إلى "auto"، يتم تجاهل هذا الخيار تماماً إذا تم كتابته في إعدادات المشروع - كإجراء أمان لمنع المستودعات الخارجية من تفعيل الوضع التلقائي سراً (وهذا ما أشرنا إليه في المقال 20). كانت كتابتك للحروف صحيحة والملف سليم، ولكنك كتبته في "المستوى الخاطئ" فقط. وبمجرد نقل السطر إلى ملف الإعدادات الشخصي ~/.claude/settings.json عمل الخيار في ثانية واحدة.

أشاركك هذا الفخ لتتذكر قاعدة أساسية: تكمن صعوبة التعامل مع ملفات settings.json في تحديد مستوى الحفظ وترتيب الأولويات بين المستويات، وليس في صياغة الإعدادات نفسها. وسنقوم اليوم بشرح مستويات الإعدادات وتوضيح الأولويات لتتمكن من تحديد مستوى الحفظ الأنسب لكل خيار برمجى مباشرة.

بعد قراءة هذا المقال، ستحصل على:

• شرح مبسط لملف settings.json والفرق الجوهري بينه وبين ملف CLAUDE.md.
• المستويات الثلاثة للإعدادات (شخصي / مشروع / محلي) من حيث موقع الحفظ ونطاق التأثير وما يُنصح بحفظه في كل مستوى.
• جدول ترتيب الأولويات لتحديد الإعداد الفعال عند التعارض، وشرح فكرة دمج المصفوفات بدلاً من استبدالها.
• خيارات الإعدادات الأكثر استخداماً وتعديلاً (model، permissions، env، hooks， statusLine) ووظيفة كل منها والمستوى الأنسب لحفظها.
• تطبيق عملي مباشر: كتابة إعدادات لمستويين مختلفين ← والتحقق من تفعيلها باستخدام أمر /status.

---

01 ما هو ملف settings.json وبماذا يختلف عن CLAUDE.md؟

لنبدأ بالخلاصة: يمثل ملف settings.json لوحة التحكم الرئيسية لإعدادات وسلوك Claude Code - ويستخدم صيغة JSON لإدارة الصلاحيات، ومتغيرات البيئة، والنموذج الافتراضي، والخطافات (Hooks)، وشريط الحالة؛ وهو مختلف تماماً عن ملف CLAUDE.md، حيث ينظم الأول سلوك وتشغيل الأداة، وينظم الثاني القواعد المطبقة للكود.

يقع الكثير من المستخدمين في لبس بين الملفين في البداية. فخلال المقالات السابقة قمنا بكتابة ملف CLAUDE.md (المقال 18) وتهيئة قواعد الصلاحيات (المقال 20)، وسنقوم لاحقاً بتهيئة الخطافات - وتُحفظ هذه التهيئة والإعدادات في النهاية داخل ملف settings.json، ولكن محتواه يختلف تماماً عن ملف CLAUDE.md.

تشبيه: ملف مستندات الشركة مقابل لوحة مفاتيح الكهرباء في مكتبك. ملف CLAUDE.md يشبه مستند "دليل العمل" للشركة - ويحتوي على قواعد مثل "نستخدم pnpm دائماً ونمنع npm" و "شغل الاختبارات قبل الرفع" وهي تعليمات مكتوبة بلغة طبيعية ليقرأها الموظف (Claude) وتكون حاضرة في ذهنه كخلفية للعمل. بينما ملف settings.json هو بمثابة لوحة مفاتيح الكهرباء في مكتبك - ويحتوي على أزرار تشغيل حقيقية: هل يُسمح بتشغيل هذه الأداة أم لا، وما هو النموذج الافتراضي المعتمد للتشغيل، وما هو النص البرمجي الذي يعمل تلقائياً عند حفظ الملف. دليل العمل يمثل "التعليمات والقوانين الموجهة للشركاء"، ولوحة المفاتيح تمثل "خيارات التشغيل الميكانيكية للآلات".

يعرف التوثيق الرسمي دور الملف كالتالي:

يمثل ملف settings.json الآلية الرسمية لتهيئة وإعداد Claude Code عبر مستويات متعددة ومتداخلة.

ركز على كلمتي "الآلية الرسمية" و "مستويات متعددة"، فهما يمثلان محور هذا المقال: فهو المنفذ الرئيسي المعتمد لتهيئة Claude Code (وليس كتابة الخيارات يدوياً في سطر الأوامر)، وتتوزع الإعدادات فيه على ثلاثة مستويات متداخلة (شخصي، مشروع، محلي).

وتتولى إعدادات settings.json معالجة الحالات التالية:

• "نريد منع وإيقاف تشغيل أوامر rm -rf تماماً في هذا المشروع" ← يتم تعيين خيار permissions.deny.
• "نريد اعتماد نموذج Sonnet كنموذج افتراضي للمشروع لتوفير التكلفة وتجنب Opus" ← يتم تعيين خيار model.
• "نريد تشغيل برنامج التنسيق تلقائياً بمجرد قيامه بتعديل ملف" ← يتم تعيين خيار hooks.
• "أريد إظهار اسم فرع git الحالي في شريط الحالة في الأسفل" ← يتم تعيين خيار statusLine.

هذه الخيارات لا تمثل نصائح موجهة لـ Claude، بل هي أزرار تشغيل حقيقية تحدد سلوك الأداة. وهذا هو الفرق الجوهري بين إعدادات settings.json وقواعد CLAUDE.md.

💡 خلاصة سريعة: يمثل ملف CLAUDE.md التعليمات المكتوبة بلغة طبيعية ليقرأها Claude، ويمثل ملف settings.json لوحة أزرار التحكم بسلوك وتوجيه الأداة - الأول لحفظ القواعد، والثاني لضبط سلوك الآلة، فتجنب الخلط بينهما.

---

02 مستويات الإعدادات الثلاثة: شخصي، مشروع، محلي

النقطة الأهم لفهم ملفات settings.json ليست حفظ الخيارات المتاحة، بل استيعاب وجود ثلاثة مستويات للملف، حيث يحدد موقع الحفظ نطاق تأثير هذه الإعدادات. والمشكلة الشائعة في البداية تعود لعدم الفصل بين هذه المستويات.

تشبيه: تعليق ورقة التنبيهات في أماكن مختلفة. تعليق ورقة "يرجى إطفاء التكييف قبل المغادرة" في مدخل الشركة الرئيسي (يقرأها كافة الموظفين في جميع المشاريع)، أو تعليقها على باب مكتب محدد (تخص العاملين في هذا المكتب فقط ويتم تسجيلها كأصل للمكتب)، أو تعليقها كـ قصاصة صغيرة على شاشتك الخاصة (تخصك أنت فقط ولا يراها الآخرون) - يختلف نطاق التأثير تماماً. مستويات settings.json الثلاثة تعمل بنفس الطريقة.

يوضح الجدول التالي المستويات الثلاثة المعتمدة في النظام (بالإضافة لمستوى Managed المخصص لإدارات تقنية المعلومات في الشركات الكبرى والذي لا نحتاج إليه غالباً في البداية وسنشير إليه سريعاً في القسم القادم):

المستوى	موقع الحفظ	نطاق التأثير	رفعه لنظام git	خيارات الإعدادات المناسبة
شخصي (User)	~/.claude/settings.json	كافة مشاريعك وجلساتك على جهازك الحالي	لا (يحفظ في دليلك الرئيسي)	التفضيلات الشخصية العامة: النموذج المفضل، مظهر الواجهة، وأدواتك الخاصة
مشروع (Project)	.claude/settings.json	لجميع أعضاء الفريق في هذا المشروع	نعم (يتم رفعه ومشاركته في المستودع)	معايير وقواعد الفريق المشتركة: قواعد الصلاحيات، الخطافات، وتفاصيل الـ MCP للمشروع
محلي (Local)	.claude/settings.local.json	يخصك أنت فقط في هذا المشروع	لا (يتم تجاهله تلقائياً بـ gitignore)	تعديلاتك الشخصية المؤقتة، والخيارات التجريبية التي تحتوي على بيانات حساسة

القواعد الأساسية للاختيار بين المستويات الثلاثة:

• "أريد تطبيق هذا الإعداد في كافة مشاريعي البرمجية" → المستوى الشخصي (~/.claude/settings.json). مثل اختيار النموذج المفضل أو تعديل شكل شريط الحالة، إعداد لمرة واحدة ويعمل في كل مكان.
• "يجب التزام جميع أعضاء الفريق بهذا الإعداد في المشروع" → مستوى المشروع (.claude/settings.json). يُرفع هذا الملف مع الكود إلى git، ويتم تطبيقه وتفعيله لدى كافة أعضاء الفريق تلقائياً عند سحب الكود.
• "تعديل مخصص لي فقط في هذا المشروع ولا أريد مشاركته" → المستوى المحلي (.claude/settings.local.json).

وهناك تفصيل أمني هام يذكره التوثيق الرسمي: بمجرد إنشاء ملف .claude/settings.local.json محلي، يقوم Claude Code تلقائياً بإضافته لقائمة التجاهل في git (gitignore):

يقوم Claude Code بتهيئة ملفات git لتجاهل ملف .claude/settings.local.json تلقائياً فور إنشائه.

لماذا صمم النظام بهذه الطريقة؟ لأن المستوى المحلي مخصص لحفظ "الخيارات الشخصية والبيانات الحساسة" التي لا يصح رفعها للمستودع العام ومشاركتها مع الآخرين. وتكفل النظام بحظر رفعها تلقائياً لحمايتك من الأخطاء العشوائية. ويرتبط هذا مباشرة بمبدأ الأمان الذي شرحناه في المقال 21: تجنب تزويد git بالبيانات الحساسة من البداية.

توزيع الإعدادات في مشروع واقعي

لتوضيح الفكرة، دعنا نرى كيف تتوزع الإعدادات في مشروع عمل واقعي:

• المستوى الشخصي (~/.claude/settings.json): شكل شريط الحالة المخصص لك، ونوع النموذج المفضل. وهي خيارات لا علاقة لها بالمشروع بل تمثل تفضيلاتك الشخصية التي ترافقك في كل مكان.
• مستوى المشروع (.claude/settings.json): قواعد حظر الصلاحيات permissions.deny (منع curl ومنع قراءة .env)، وخطاف فحص الكود قبل الرفع. وهي قوانين عامة للفريق تُرفع للمستودع ليلتزم بها الجميع.
• المستوى المحلي (.claude/settings.local.json): صلاحيات إضافية مؤقتة تحتاجها لفحص ميزة معينة (لا تهم الفريق)، أو خطاف تجريبي تعمل على تطويره ولم يكتمل لمشاركته مع الآخرين.

القاعدة الذهبية للاختيار: اسأل نفسك "هل هذا الإعداد يخصني أنا فقط (شخصي/محلي)، أم يخص قوانين ومعايير المشروع (مستوى المشروع)؟"، وثم حدد: "هل يخص كافة مشاريعي (شخصي)، أم يخص هذا المشروع فقط دون مشاركته (محلي)؟".

من الأخطاء الشائعة كتابة إعدادات وصلاحيات خاصة بمشروع معين في المستوى الشخصي - والنتيجة هي تفعيل وتطبيق هذه الصلاحيات في المشاريع الأخرى وتداخل الخيارات وظهور أخطاء غير متوقعة. لذا اسأل نفسك دائماً: "هل يرافقني هذا الإعداد في كل مكان، أم يرتبط بالمشروع الحالي فقط؟"، واحفظ خيارات المشاريع في مجلداتها المخصصة.

💡 خلاصة سريعة: مستويات الحفظ - شخصي في ~/.claude/settings.json لكافة المشاريع، مشروع في .claude/settings.json مشترك مع الفريق (يرفع لـ git)، ومحلي في .claude/settings.local.json لتعديلاتك الخاصة في المشروع (يُحظر رفعه تلقائياً).

---

03 ترتيب الأولويات: من الأقوى وكيف تُعالج التعارضات؟

عند كتابة نفس الخيار البرمجى في مستويات متعددة (مثال: تعيين نموذج Opus في المستوى الشخصي ونموذج Sonnet في مستوى المشروع)، كيف يقرر النظام الخيار الفعال للتشغيل؟ يتبع النظام قواعد ترتيب أولويات صارمة تحديد الخيار الأقوى.

ترتيب الأولويات من الأقوى للأضعف (المستوى الأعلى يلغي خيارات المستوى الأدنى):

الترتيب	المستوى	الوصف والتأثير
1 (الأقوى)	Managed (إدارة الشركات)	خيارات تفرضها الشركة برمجياً ولا يمكن للمستخدم أو المشروع تعديلها
2	سطر الأوامر (عبر --settings)	خيارات تكتبها يدوياً عند تشغيل الجلسة وتطبق لهذه الجلسة فقط
3	المحلي (.claude/settings.local.json)	تعديلاتك الشخصية الخاصة بهذا المشروع
4	المشروع (.claude/settings.json)	خيارات ومعايير المشروع المشتركة المرفوعة للمستودع
5 (الأضعف)	الشخصي (~/.claude/settings.json)	إعداداتك وتفضيلاتك الشخصية العامة التي تلتزم بها عند غياب خيارات المستويات الأعلى

يوضح الشكل التالي كيفية تداخل وترتيب المستويات، حيث يمثل المستوى الأعلى طبقة تغطي وتلغي الحقول المتشابهة في الطبقات الأدنى:

تترتب الأولويات من الأعلى للأسفل: الطبقة الأعلى تلغي وتغطي خيارات الطبقة الأدنى (للحقول ذات القيم الفردية). بمعنى آخر، المستويات الأكثر "تحديداً وتخصيصاً بالوقت الحالي" تفوز على المستويات "العامة والدائمة" - ولن يُلجأ للخيار الشخصي العام إلا عند غياب التهيئة في بقية المستويات الأعلى.

القاعدة الذهبية للحفظ: المستويات الأكثر قرباً وتخصيصاً باللحظة الحالية هي الأقوى. أمر سطر الأوامر (لهذه الجلسة فقط) يفوز على المحلي (لهذا المشروع ويخصك فقط)، والمحلي يفوز على المشروع (مشترك مع الفريق)، والمشروع يفوز على الشخصي (عام لكافة المشاريع). ويشرح التوثيق ذلك بمثال واضح:

على سبيل المثال، إذا كانت إعداداتك الشخصية تسمح بـ Bash(npm run *) بينما تمنعها إعدادات المشروع المشتركة، فستكون الكلمة لإعدادات المشروع ويتم منع تشغيل الأمر.

وهذا يعني أن الخيارات المفتوحة التي سمحت بها لنفسك في الإعدادات الشخصية قد يتم إيقافها وحظرها بمجرد دخولك لمشروع يحتوي على قواعد صارمة. وهذا يؤكد الفكرة التي أشرنا إليها: تأثير الإعداد يختلف تماماً بناءً على مستوى الحفظ. والفخ الذي واجهناه في البداية مع خيار defaultMode: "auto" يعود لتجاهل ترتيب هذه الأولويات.

مستوى Managed للعلم فقط للمبتدئين. وهو مستوى مخصص لفرق تقنية المعلومات في الشركات لفرض معايير حماية موحدة على أجهزة الموظفين ولا يمكن للمستخدم أو المشروع تعديلها أو تجاوزها (مثال: منع تشغيل أوامر curl للموظفين بالكامل لدواعي الأمان). إذا كنت تعمل بمفردك أو في فريق صغير فلن تحتاج إليه - يكفي معرفة وجود هذا المستوى كحد أقصى للأولويات.

قاعدة هامة ومخالفة للتوقعات: دمج المصفوفات بدلاً من استبدالها

قواعد التغطية والإلغاء الموضحة أعلاه تنطبق على الحقول ذات القيم الفردية (مثل حقل model الذي يحمل قيمة واحدة فقط). ولكن هناك نوع من الحقول يتبع سلوكاً مختلفاً تماماً ويجب الانتباه له - وهو حقول المصفوفات (مثل قوائم الصلاحيات permissions.allow و permissions.deny) حيث يتم دمج القيم من كافة المستويات بدلاً من استبدالها.

يوضح التوثيق سلوك المصفوفات كالتالي:

تُدمج قيم المصفوفات عبر المستويات المختلفة. عند كتابة نفس حقل المصفوفة في مستويات متعددة، يتم جمع القيم وإزالة العناصر المكررة بدلاً من الاقتصار على خيار المستوى الأعلى.

باللغة البسيطة: لن تقوم إعدادات المشروع بإلغاء وإخفاء قواعد الصلاحيات الشخصية التي حددتها لنفسك، بل سيتم دمج القائمتين معاً لتطبيقهما.

يوضح الجدول التالي هذا السلوك البرمجى:

الحالة	النتيجة المتوقعة (خاطئة)	النتيجة الفعلية (صحيحة)
تحديد allow: ["Bash(npm run *)"] شخصياً، وتحديد allow: ["Bash(git diff *)"] للمشروع	إلغاء الخيار الشخصي والاقتصار على خيار المشروع git diff	تفعيل الخيارين معاً: يُسمح بتشغيل أوامر npm run وأوامر git diff

هذا السلوك يختلف تماماً عن سلوك الحقول الفردية، ويجب عليك تذكر الفارق جيداً:

• الحقول الفردية (مثل model أو defaultMode): خيار المستوى الأعلى يلغي ويغطي خيارات المستويات الأدنى بالكامل.
• حقول المصفوفات (مثل قوائم الصلاحيات وقيم البيئة env): تُجمع وتُدمج قيمها معاً من كافة المستويات وإزالة العناصر المكررة دون إلغاء أي منها.

يرجى الانتباه لهذه القاعدة - فقد تظن أن تعيين قائمة deny صارمة في المشروع كافٍ لإلغاء خيارات allow المفتوحة التي حددتها شخصياً، لتكتشف استمرار عملها لدمج القائمتين معاً.

💡 خلاصة سريعة: ترتيب الأولويات - المستويات الأكثر تخصيصاً باللحظة الحالية هي الأقوى (سطر الأوامر > محلي > مشروع > شخص启用)؛ وتذكر أن حقول المصفوفات (كقوائم الصلاحيات) تُجمع وتُدمج قيمها عبر كافة المستويات بدلاً من استبدالها.

---

04 خيارات الإعدادات الأكثر استخداماً

يحتوي ملف settings.json على مئات الحقول المتاحة، ولكن غالبية احتياجاتك اليومية تنحصر في بضعة حقول أساسية. سنشرح وظيفة كل منها والمستوى الأنسب لحفظه.

لنلقِ نظرة أولاً على ملف تهيئة مبسط يحتوي على هذه الحقول الأساسية:

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "model": "claude-sonnet-4-6",
  "permissions": {
    "allow": ["Bash(npm run test *)"],
    "deny": ["Bash(curl *)", "Read(./.env)"]
  },
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1"
  }
}

يُنصح بكتابة السطر الأول $schema دائماً. فهو يربط الملف بالمواصفات المعتمدة للنظام، مما يتيح للمحررات (مثل VS Code أو Cursor) تقديم ميزات الإكمال التلقائي وفحص الأخطاء وعرض التنبيهات فوراً عند وجود أخطاء في الصياغة أو أسماء الحقول. وإذا قمت بكتابته، فستنبهك المحررات للأخطاء فوراً وتوفر عليك وقت البحث والفحص اليدوي. يذكر التوثيق:

تساعد إضافة هذا السطر في تفعيل ميزات الإكمال التلقائي والتدقيق الفوري داخل محررات VS Code و Cursor وأي محررات تدعم بروتوكول JSON schema.

دعنا نفصل هذه الحقول الأساسية:

model: تحديد النموذج الافتراضي

يحدد حقل model نوع النموذج المعتمد للتشغيل لهذه الطبقة. ويتم كتابة المعرف الخاص بالنموذج (مثل "claude-sonnet-4-6").

• مستوى الحفظ الأنسب: حسب حاجتك. لتفضيلاتك الشخصية العامة → احفظه في المستوى الشخصي؛ لتوحيد خيارات الفريق في مشروع معين → احفظه في مستوى المشروع.
• ملاحظة هامة: يختلف حقل model عن بقية الحقول في كونه يُقرأ مرة واحدة فقط عند بدء تشغيل الجلسة، وأي تعديل عليه يتطلب إغلاق الجلسة وإعادة تشغيلها ليتم تطبيقه (أو التبديل يدوياً عبر أمر /model في المحادثة). وتلغي معلمات بدء التشغيل --model ومتغيرات البيئة ANTHROPIC_MODEL قيم هذا الحقل.

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

permissions: ضبط قواعد الصلاحيات

يضم هذا حقل قواعد الصلاحيات الثلاثة allow (سماح)، ask (سؤال)، و deny (منع) لضبط وضمان عمل الأدوات والأوامر (كما شرحنا في المقال 20)。

• مستوى الحفظ الأنسب: لقوانين الأمان المشتركة للفريق (منع curl ومنع قراءة .env) → احفظها في مستوى المشروع (لتُرفع لـ git)； لتعديلاتك وسهولة عملك الشخصي → احفظها في المستوى الشخصي أو المحلي.
• تذكر قاعدة دمج المصفوفات: يتم دمج قيم الصلاحيات عبر المستويات المختلفة ولا تلغي إحداها الأخرى.

env: تزويد الجلسة بمتغيرات البيئة

تُستخدم قيم env لتمرير متغيرات البيئة لـ Claude Code والعمليات الفرعية التابعة له في الجلسة.

تشبيه: بطاقة التعريف والمعدات التي يستلمها الموظف عند دخول الورشة. فبمجرد دخول الجلسة، تتوفر هذه القيم لكافة الأوامر والعمليات الفرعية للعمل بها - يمثل حقل env هذه المعدات.

• الاستخدام الشائع: تفعيل وإرسال بيانات الاستخدام (CLAUDE_CODE_ENABLE_TELEMETRY)، أو تحديد مسار خدمات مخصصة للمشروع.
• مستوى الحفظ الأنسب: للقيم الخاصة بالمشروع (رابط خادم التطوير مثلاً) → احفظها في مستوى المشروع؛ للقيم الشخصية العامة → احفظها في المستوى الشخصي.

hooks: تشغيل برمجيات تلقائية عند الأحداث

يستخدم لتحديد ونقاط انطلاق الخطافات (Hooks) التي تعمل تلقائياً عند رصد أحداث معينة (مثل فحص وتنسيق الملفات بعد تعديلها). وسنفصل استخدامها في المقال 33.

• مستوى الحفظ الأنسب: لمعايير وقوانين الفريق (فحص الكود قبل الرفع) → احفظها في مستوى المشروع； لأتمتة مهامك الشخصية → احفظها في المستوى الشخصي.
• تُكتب إعدادات الخطافات وتُحفظ inside settings.json.

statusLine: تعديل شريط الحالة

تحدثنا في المقال 14 عن إمكانية تعديل شريط الحالة في الأسفل. يتيح لك حقل statusLine تخصيص البيانات المعروضة - كتشغيل نص برمجى لعرض اسم فرع git الحالي، أو نوع النموذج المطبق، أو مستوى استهلاك الرموز.

{
  "statusLine": {
    "type": "command",
    "command": "~/.claude/statusline.sh"
  }
}

• مستوى الحفظ الأنسب: يمثل شريط الحالة تفضيلاً بصرياً شخصياً، لذا يُحفظ دائماً في المستوى الشخصي (~/.claude/settings.json) ليعمل في كافة مشاريعك.

تنبيه هام: بعض الخيارات لا تُحفظ في settings.json

يقع الكثير من المستخدمين في هذا اللبس لعدم معرفتهم بوجود ملف تهيئة آخر. حيث يملك Claude Code ملفاً آخر باسم ~/.claude.json (ملف JSON في دليلك الرئيسي ومختلف عن ملف إعدادات settings.json). ويختص هذا الملف بحفظ بيانات الجلسات وحالة الأداة: كجلسة تسجيل الدخول، وإعدادات خوادم MCP الشخصية (المقال 22)، وحالة ثقة المشاريع، والملفات المؤقتة.

وهناك بعض خيارات التهيئة التي يمنع النظام كتابتها في settings.json وتُحفظ حصرياً في ~/.claude.json - وأي محاولة لكتابتها في settings.json ستؤدي لظهور خطأ في فحص الصياغة. من أمثلة هذه الخيارات: autoConnectIde (الاتصال التلقائي بالـ IDE) و teammateDefaultModel (النموذج الافتراضي للأعضاء).

فإذا حاولت تفعيل خيار الاتصال بالـ IDE وكبته في settings.json وتفاجأت بظهور خطأ باللون الأحمر في المحرر، فتذكر أن موقع هذا الخيار الصحيح هو ملف ~/.claude.json. تذكر دائماً: يختص ملف settings.json بضبط سلوك وخيارات عمل الوكيل، ويختص ملف ~/.claude.json بحفظ بيانات الجلسات والـ MCP والملفات المؤقتة - وغالبية تعاملاتك اليومية ستكون مع الملف الأول.

💡 خلاصة سريعة: الخيارات الأساسية - model (النموذج)، permissions (الصلاحيات)، env (البيئة)، hooks (الخطافات)، و statusLine (شريط الحالة)؛ احفظ خيارات الفريق في مستوى المشروع وخياراتك الشخصية في المستوى الشخصي، واستعين بـ $schema لتسهيل التدقيق، وتذكر أن بعض خيارات الجلسات والـ MCP تُحفظ في ~/.claude.json.

---

05 التعديل، موعد تفعيل التغييرات، والتحقق من العمل

بعد فهم الخيارات ومستويات الحفظ، نصل لثلاثة أسئلة عملية: أين نقوم بالتعديل، ومتى تطبق التغييرات، وكيف نتأكد من سلامة وقراءة الإعدادات بنجاح لتفادي إضاعة الوقت.

أين نقوم بالتعديل: التحرير المباشر أو عبر أمر /config

يتوفر خياران لتعديل الإعدادات:

1. التحرير المباشر للملف - فتح ملف JSON للمستوى المطلوب وتعديله يدوياً. وهي الطريقة المفضلة والأكثر وضوحاً وتنسيقاً.
2. استخدام أمر /config داخل المحادثة - واجهة تفاعلية تتيح لك تعديل بعض الخيارات العامة السريعة (مثل مظهر الواجهة أو نمط المخرجات).

يرجى الانتباه لـ تفصيل هام: لا تعرض واجهة /config كامل خيارات إعدادات ملف settings.json المتاحة، بل تقتصر على تعديل بعض الأزرار والخيارات العامة السريعة. ولا تعتمد عليها لرؤية كافة تهيئات ملفك - وراجع ملف التهيئة يدوياً لرؤية كافة التفاصيل.

موعد تفعيل التغييرات: تفعيل تلقائي فوري باستثناء خيارين

يوفر النظام ميزة رائعة وهي مراقبة ملفات الإعدادات وتطبيق التغييرات فور حفظ الملف دون حاجة لإعادة تشغيل الجلسة:

يراقب Claude Code ملفات التهيئة باستمرار، ويعيد تحميل الإعدادات وتطبيقها فور حفظ الملف... ويشمل ذلك إعدادات الصلاحيات permissions والخطافات hooks.

ولكن هناك خياران مستثنيان من هذه القاعدة ويتم قراءتهما مرة واحدة عند بدء تشغيل الجلسة وتتطلب إعادة التشغيل لتطبيقهما:

الخيار	طريقة تطبيق التعديلات
model	إعادة تشغيل الجلسة، أو التبديل يدوياً بـ /model
outputStyle (نمط المخرجات)	إعادة تشغيل الجلسة، أو كتابة /clear لبدء جلسة جديدة

تذكر هذه القاعدة: إذا قمت بتعديل الصلاحيات أو الخطافات وحفظت الملف، ستطبق فوراً وتعمل مباشرة؛ ولكن إذا قمت بتعديل نموذج التشغيل ولم تلاحظ أي تغيير، فلا تقلق - فالأمر يتطلب إغلاق الجلسة وإعادة تشغيلها فقط لتطبيقه.

التحقق من قراءة الإعدادات: أمر /status وقسم Setting sources

تعتبر هذه الأداة الأهم للتأكد من قراءة وتحميل ملفات الإعدادات بنجاح. اكتب في المحادثة:

/status

ستظهر واجهة تعرض حالة الأداة، وتضم قسماً باسم Setting sources يعرض ملفات التهيئة التي تم قراءتها وتحميلها للجلسة الحالية - مثل User settings أو Project local settings.

يوضح التوثيق آلية عرض الملفات كالتالي:

يعرض قسم Setting sources ملفات التهيئة النشطة والتي تم تحميلها بنجاح... ولا يظهر الملف في القائمة إلا إذا كان يحتوي على خيار واحد فعال على الأقل، وغياب الملف يعني عدم قراءته أو تحميله.

وتعني هذه القاعدة ما يلي:

• ظهور الملف في القائمة = تم العثور على الملف وقراءته وتفعيل خياراته بنجاح.
• غياب الملف من القائمة = لم يتمكن البرنامج من العثور على الملف أو قراءته (تحقق من صحة المسار واسم المجلد، كالتأكد من حفظه باسم .claude/settings.json وتجنب حفظه باسم settings.json مباشرة).
• عند وجود خطأ في الصياغة (خطأ في JSON أو قيم غير صالحة)، سيعرض أمر /status تفاصيل الخطأ ومكانه لمساعدتك في تصحيحه.

لذا بعد تهيئة أي ملف إعدادات جديد، ابدأ بتشغيل أمر /status للتأكد من ظهوره وقراءته بنجاح - لتوفر على نفسك عناء فحص وتخمين الأخطاء.

قائمة فحص وتصحيح مشاكل الإعدادات

نلخص المشاكل الشائعة وحلولها في الجدول التالي للرجوع إليها عند توقف الإعدادات عن العمل:

المشكلة	الاحتمال الخاطئ	الإجراء الصحيح للفحص
التعديلات لا تعمل إطلاقاً بعد الحفظ	خطأ في اسم الحقل؟	تشغيل /status والتحقق من ظهور الملف في قسم Setting sources - وغيابه يعني حفظ الملف في مسار خاطئ
تغيير حقل model لا يعمل	خطأ في اسم النموذج؟	يتطلب تعيين النموذج إعادة تشغيل الجلسة لتطبيقه (أو التبديل بـ /model)
تعيين "defaultMode": "auto" لا يعمل	خطأ في كتابة الحروف؟	يتم تجاهل وضع auto في إعدادات المشروع ويجب تعيينه في الإعدادات الشخصية
تشغيل أمر تم منعه في قائمة deny للمشروع	خطأ في كتابة قاعدة المنع؟	تُدمج قواعد الصلاحيات عبر المستويات، وتحقق من وجود قاعدة allow تسمح به في المستوى الشخصي
فشل كتابة حقل معين في ملف settings.json	خطأ في صياغة JSON؟	بعض الخيارات (مثل autoConnectIde) تُحفظ في ملف ~/.claude.json وليس في settings.json

توضح القائمة أن معظم المشاكل تعود لعدم الفصل بين مستويات الإعدادات وتأثيرها ومواعيد تفعيلها، وتكفي مراجعتها لتصحيح الأخطاء مباشرة.

💡 خلاصة سريعة: عدل الملف يدوياً أو بـ /config؛ وتفعل الصلاحيات والخطافات فوراً بينما يتطلب النموذج إعادة التشغيل؛ واستعين بأمر /status والتحقق من قسم Setting sources للتأكد من تحميل الملف بنجاح.

---

06 تطبيق عملي: تهيئة مستويين مختلفين والتحقق من العمل

سنقوم الآن بتجربة عملية لتهيئة ملفين في مستويين مختلفين (مستوى المشروع والمستوى المحلي) والتحقق من تحميلهما بنجاح ودمج صلاحياتهما. ولا يتطلب هذا المثال توفر مشاريع معقدة.

الخطوة الأولى: إنشاء مجلد تجريبي والدخول إليه

mkdir settings-demo && cd settings-demo

الخطوة الثانية: كتابة إعدادات مستوى المشروع

أنشئ مجلداً باسم .claude واكتب داخل ملف settings-demo/.claude/settings.json النص التالي (للسماح بأمر اختبارات npm، ومنع أمر curl). ونكتب السطر الأول لربط المواصفات وتسهيل التدقيق:

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": ["Bash(npm run test *)"],
    "deny": ["Bash(curl *)"]
  }
}

الخطوة الثالثة: كتابة إعدادات المستوى المحلي

اكتب داخل ملف settings-demo/.claude/settings.local.json النص التالي (للسماح بأمر git status كخيار شخصي لك في هذا المشروع ولن يتم رفعه للمستودع العام):

{
  "permissions": {
    "allow": ["Bash(git status *)"]
  }
}

النتيجة المتوقعة: توفر ملفين للإعدادات (مستوى المشروع والمستوى المحلي) في مجلد المشروع. ويرجى الانتباه: سيتم تجاهل الملف المحلي تلقائياً وحظر رفعه للمستودع عبر gitignore (سنفحص ذلك في الخطوة التالية).

الخطوة الرابعة: التحقق من حظر الملف المحلي في git

git init -q && git status --short

النتيجة المتوقعة: ستلاحظ وجود ملف مستوى المشروع .claude/settings.json في قائمة الملفات المتاحة للرفع، بينما يغيب ملف المستوى المحلي .claude/settings.local.json تماماً لتعرضه للحظر والتجاهل التلقائي. وهذا يثبت سلامة عمل الميزة الأمنية لحماية ملفاتك المحلية.

الخطوة الخامسة: التحقق من تحميل الملفين في الجلسة

شغل Claude Code:

claude

بمجرد الدخول، اكتب:

/status

النتيجة المتوقعة: ستلاحظ ظهور Project local settings و Project settings في قسم Setting sources الموضح في المخرجات. وهذا يؤكد العثور على الملفين وقراءتهما وتحميل خياراتهما للجلسة الحالية بنجاح.

الخطوة السادسة: التحقق من دمج قواعد الصلاحيات

اكتب:

/permissions

النتيجة المتوقعة: ستشاهد القواعد المكتوبة في الملفين معاً متوفرة في القائمة - حيث يظهر السماح بـ npm run test * والسماح بـ git status * في قائمة المسموحات، ويظهر منع curl * في قائمة الممنوعات. وهذا يمثل تطبيقاً واقعياً لقاعدة دمج مصفوفات الصلاحيات عبر المستويات المختلفة.

بإتمام هذه الخطوات، تكون قد تعاملت مع ملفات التهيئة بشكل عملي وفهمت مستويات الحفظ وآليات الدمج والتحقق من العمل.

💡 خلاصة سريعة: خطوات التطبيق - كتابة ملفين لمستوى المشروع والمستوى المحلي ← فحص حظر الملف المحلي بـ git status ← تشغيل الجلسة وفحص التحميل بـ /status ← فحص دمج الصلاحيات بـ /permissions.

---

07 ملخص

شرحنا في هذا المقال آليات عمل ملفات التهيئة settings.json وكيفية تنظيم وضبط سلوك Claude Code بدقة وتجنب التعارضات.

لنراجع النقاط الأساسية معاً:

الموضوع	التفاصيل والحلول	نقاط هامة
المقارنة مع CLAUDE.md	ملفات مختلفة الوظائف	يختص CLAUDE.md بحفظ القواعد البرمجية للمشروع، ويختص settings.json بضبط أزرار سلوك وتشغيل الأداة.
مستويات الحفظ	ثلاثة مستويات	شخصي في ~/.claude/ لجميع المشاريع، ومشروع في .claude/settings.json للفريق، ومحلي في .claude/settings.local.json لتعديلاتك الخاصة.
ترتيب الأولويات	المستويات الأكثر قرباً باللحظة الحالية تفوز	الترتيب: سطر الأوامر > محلي > مشروع > شخصي.
دمج المصفوفات	جمع القيم بدلاً من استبدالها	تُدمج قيم الصلاحيات والبيئة env عبر المستويات المختلفة ولا تلغي إحداها الأخرى.
خيارات الإعدادات	خمسة خيارات أساسية	تحديد النموذج model ضبط الصلاحيات permissions متغيرات البيئة env الخطافات hooks وشريط الحالة statusLine.
التحقق من العمل	تشغيل أمر /status	فحص قسم Setting sources للتأكد من ظهور الملف وقراءته بنجاح.

يمكنك الآن: التمييز بين ملفات settings.json و CLAUDE.md ومعرفة دور كل منهما، وتحديد مستوى الحفظ الأنسب لخياراتك (شخصي أم مشروع أم محلي)، وفهم ترتيب الأولويات ودورة دمج المصفوفات، ومعالجة الحقول الأساسية وتعديلها， والتحقق من سلامة قراءة الملفات وتصحيح الأخطاء الشائعة. هذه المهارة تتيح لك تهيئة وتطويع أداة Claude Code لتناسب أسلوب عملك وتوفر وقتك وتكلفتك البرمجية.

تذكر دائماً التحقق من قراءة الملف عبر أمر /status فور كتابة أي تعديلات جديدة.

---

المقال القادم 32 "أنماط ومخرجات الحديث (Output Styles)" - قمنا بالإشارة في هذا المقال لخيار outputStyle المتاح في التهيئة والذي يتطلب إعادة التشغيل لتطبيقه. سنشرح في المقال القادم بالتفصيل كيفية تعديل وتخصيص أسلوب حديث ومخرجات Claude، لتتمكن من تغيير نمط إجاباته لتناسب الشرح والتعليم أو لتكون خلاصات سريعة ومباشرة حسب رغبتك وسيناريو عملك الحالي. سنشرح ذلك بالتفصيل في المقال القادم.

---

قراءات موصى بها

• نظام الذاكرة المؤقتة (memory): حفظ تفضيلاتك عبر الجلسات
• الملحقات البرمجية (Plugins): حزم الإعدادات لتسهيل مشاركتها
• مقدمة وتعريف بـ Claude Code