قواعد Claude Code: كيفية كتابة CLAUDE.md وإدارة سياق البرمجة الوكيلية

قواعد Claude Code موجودة في ملفات CLAUDE.md — ملفات Markdown تضعها في مستودع مشروعك، أو دليل المنزل، أو إعدادات المؤسسة التي يقرؤها Claude في بداية كل جلسة. بالإضافة إلى القواعد المحددة النطاق في .claude/rules/، وملف settings.json للأذونات، والذاكرة التلقائية للتفضيلات المكتسبة، يمنحك نظام القواعد تحكمًا دقيقًا ودائمًا في كيفية تصرف الوكيل البرمجي عبر أي مهمة.

ما هي قواعد Claude Code؟

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

نظامان متكاملان يتعاملان مع هذا:

ملفات CLAUDE.md هي ملفات Markdown تكتبها ويقرؤها Claude في بداية كل جلسة. استخدمها للتعليمات التي يجب أن تنطبق دائمًا: أوامر البناء، اتفاقيات الكود، قرارات البنية، القيود الصارمة.

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

يتم تحميل كليهما في السياق عند بدء الجلسة، لكنهما ليسا تكوينًا إلزاميًا. إنها تعليمات يتبعها Claude كسياق. للفرض الصارم — منع أمر معين بغض النظر عما يقرر Claude فعله — تحتاج إلى خطاف PreToolUse أو قاعدة deny في settings.json. هذا التمييز مهم للتشغيلات المستقلة حيث تريد سلوكًا متوقعًا، وليس امتثالًا احتماليًا.

مواقع ملفات CLAUDE.md ونطاقها

يقوم Claude Code بتحميل ملفات CLAUDE.md من عدة مواقع، كل منها يغطي نطاقًا مختلفًا. يتم تحميلها بالترتيب من الأوسع إلى الأكثر تحديدًا:

الموقع	النطاق	ما الغرض منه
~/.claude/CLAUDE.md	جميع المشاريع على جهازك	التفضيلات الشخصية، عادات سير العمل العامة
./CLAUDE.md (جذر المستودع)	جميع الجلسات في ذلك المشروع	اتفاقيات المشروع، أوامر البناء، قواعد مشتركة للفريق
./CLAUDE.local.md (جذر المستودع)	جلساتك المحلية فقط	تفضيلات لكل مطور؛ أضفه إلى .gitignore
./src/CLAUDE.md (دليل فرعي)	الجلسات التي تلمس الملفات في ذلك الدليل	قواعد خاصة بالوحدة لا تنطبق على مستوى المشروع

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

يمكنك استيراد ملفات إضافية باستخدام مراجع @path داخل أي CLAUDE.md:

@./docs/architecture.md
@./CONTRIBUTING.md

يتم تحميل الملفات المستوردة عند بدء الجلسة، تمامًا مثل ملف CLAUDE.md نفسه. الاستيرادات مفيدة للتنظيم لكنها لا توفر السياق — المحتوى المستورد يحسب ضمن ميزانية الرموز الخاصة بك.

للفرق: قم بتسجيل ملف CLAUDE.md الخاص بالمشروع في التحكم بالمصادر. هذا يضمن أن كل جلسات Claude لكل مطور — وأي عمليات وكيل قائمة على CI — تبدأ بنفس السياق المشترك. تعامل معه مثل .eslintrc أو pyproject.toml.

ما يجب وضعه في CLAUDE.md

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

مرشحون جيدون:

• أوامر البناء والاختبار التي تختلف عن الإعدادات الافتراضية الواضحة (./scripts/test.sh --ci، وليس فقط npm test)
• اتفاقيات الكود غير الملتقطة بواسطة المدقق اللغوي (“نستخدم التصدير المسمى في كل مكان؛ لا تصدير افتراضي في الأدوات المساعدة المشتركة”)
• قرارات البنية غير الواضحة من قراءة الكود (“دليل lib/ مشترك عبر الخدمات — لا تقم بإضافة منطق خاص بالخدمة هناك”)
• المشكلات المعروفة (“ملف config.ts يتم إنشاؤه في وقت البناء؛ لا تقم بتحريره يدويًا”)
• قيود سير العمل (“قم دائمًا بإنشاء فرع قبل إجراء التغييرات؛ ادفع إلى المستودع البعيد قبل فتح طلب سحب”)

أشياء يجب تركها خارجًا:

• قوائم الدليل والأشجار — يقرأها Claude من المستودع
• قوائم التبعيات — متاحة من package.json و pyproject.toml وما شابه
• أوصاف نثرية لما يفعله الكود الموجود — يقرأ Claude الكود المصدر مباشرة
• التغييرات الأخيرة — يستخدم Claude git log و git diff عندما يحتاج إلى التاريخ

اجعل CLAUDE.md مركزًا على ما لا يمكن استنتاجه من قراءة قاعدة الكود. الملفات التي تزيد عن 200 سطر تستهلك سياقًا أكبر وتقلل من موثوقية الالتزام. الأمر /doctor في Claude Code يدقق ملف CLAUDE.md المسجل ويقترح إزالة المحتوى القابل للاشتقاق من الكود — طريقة مفيدة لقص ملف متضخم.

كتابة قواعد فعالة

الخصوصية مهمة. قارن:

# غامض — أقل اتساقًا
اتبع معايير البرمجة الخاصة بالمشروع.

# محدد — أكثر اتساقًا
- استخدم pnpm، وليس npm أو yarn
- قم بتشغيل pnpm test قبل كل commit؛ لا تقم بالالتزام إذا فشلت الاختبارات
- قم بتصدير جميع الأنواع المشتركة من src/types/index.ts — لا تعرف الأنواع داخل ملفات المكونات
- دليل data/ للقراءة فقط في الاختبارات؛ استخدم تركيبات الاختبار من tests/fixtures/ بدلاً من ذلك

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

القواعد المحددة النطاق مع .claude/rules/

يسمح لك دليل .claude/rules/ بإرفاق القواعد بأنماط ملفات محددة دون تحميلها في كل جلسة. يكتشف Claude الملفات في .claude/rules/ ويحملها عندما تعمل مع ملفات مطابقة.

هيكل نموذجي لمستودع TypeScript متعدد الحزم:

.claude/rules/
  api.md             # قواعد لـ src/api/** — التحقق من صحة الطلبات، تنسيقات الأخطاء
  components.md      # قواعد لـ src/components/** — أنواع الخصائص، اتفاقيات التنسيق
  tests.md           # قواعد لـ tests/** — أنماط التجهيزات، إعداد mock
  database.md        # قواعد لـ migrations/ و models/ — تسمية الترحيل، أنماط الاستعلام

يستخدم كل ملف قاعدة صفحة أمامية YAML مع حقل paths للتحكم في وقت تحميله:

---
paths:
  - "src/api/**/*.ts"
  - "src/api/**/*.test.ts"
---

# قواعد تطوير API

- يجب على جميع معالجات المسار التحقق من صحة الإدخال باستخدام zod قبل أي منطق عمل
- قم بإرجاع الأخطاء كـ `{ error: string; code: string }` — لا تستخدم أبدًا سلاسل نصية عادية
- يتم تطبيق تحديد المعدل عند البوابة؛ لا تقم بإضافته داخل المعالجات

القواعد بدون حقل paths يتم تحميلها دون شرط عند بدء الجلسة، تمامًا مثل المحتوى في CLAUDE.md الخاص بالمشروع. القواعد التي تحتوي على paths يتم تحميلها فقط عندما يفتح Claude ملفات تطابق تلك الأنماط.

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

settings.json مقابل CLAUDE.md

CLAUDE.md يتحكم في ما يعرفه Claude ويعتزم فعله. settings.json يتحكم في ما مسموح لـ Claude بتنفيذه فعليًا.

	CLAUDE.md	settings.json
الغرض	تعليمات وسياق	أذونات وتكوين
مفروض؟	لا — يعمل عليه Claude كإرشاد	نعم — قواعد deny تمنع استدعاءات الأدوات دون شرط
التنسيق	Markdown حر	JSON منظم
الموقع	./CLAUDE.md، ~/.claude/CLAUDE.md	.claude/settings.json، ~/.claude/settings.json

ملف settings.json للمشروع في .claude/settings.json:

{
  "permissions": {
    "allow": [
      "Bash(pnpm test)",
      "Bash(pnpm build)",
      "Bash(git status)",
      "Bash(git diff *)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(git push --force*)",
      "Bash(git reset --hard*)"
    ]
  }
}

قائمة allow توافق مسبقًا على أوامر محددة حتى يتمكن Claude من تشغيلها دون مطالبة. هذا يسرع الجلسات التفاعلية للعمليات التي تثق بها. قائمة deny تمنع الأوامر دون شرط — بغض النظر عما يقرر Claude فعله، بغض النظر عما يقوله CLAUDE.md. استخدم deny للعمليات غير القابلة للعكس على بيانات الإنتاج أو البنية التحتية.

إعدادات مستوى المستخدم في ~/.claude/settings.json تنطبق على جميع المشاريع. إعدادات المشروع في .claude/settings.json تنطبق فقط في هذا المستودع. إعدادات المشروع لها الأسبقية على إعدادات المستخدم عند تداخلها.

الذاكرة التلقائية: ملاحظات Claude

الذاكرة التلقائية هي النظير لـ CLAUDE.md. بينما CLAUDE.md هو تعليمات تكتبها، فإن الذاكرة التلقائية هي ملاحظات يكتبها Claude بنفسه بناءً على ما يتعلمه أثناء جلساتك.

عندما تصحح Claude أثناء جلسة — “نستخدم Vitest، وليس Jest في هذا المشروع” — يمكنه حفظ ذلك كملاحظة في ~/.claude/projects/<repo>/memory/. في الجلسة التالية، يقرأ Claude تلك الملاحظة ويعيد تطبيق التصحيح دون أن يقال له مرة أخرى.

يحتوي دليل الذاكرة على:

~/.claude/projects/<repo>/memory/
  MEMORY.md          # فهرس يستخدمه Claude للعثور على الملفات الأخرى؛ أول 200 سطر يتم تحميلها كل جلسة
  debugging.md       # أنماط اكتشفها Claude أثناء حل المشكلات في هذا المستودع
  conventions.md     # اتفاقيات تعلمها Claude من تصحيحاتك

هذا محلي للجهاز ولكل مستودع. الذاكرة التلقائية تكمل CLAUDE.md بدلاً من استبداله: CLAUDE.md مخصص لقواعد المشروع المشتركة بين الفريق؛ الذاكرة التلقائية مخصصة للأنماط الشخصية التي تعلمها Claude من العمل معك.

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

أفضل الممارسات للبرمجة الوكيلية

تشغيل Claude Code بشكل مستقل — من خلال claude -p، أو Agent SDK، أو خطوط CI — يرفع المخاطر بالنسبة لإعداد القواعد الخاص بك. قد يكمل الوكيل العشرات من استدعاءات الأدوات دون توقف، ولا يوجد حوار تفاعلي لالتقاط سوء الفهم في منتصف التشغيل.

اكتب قيودًا صريحة، وليس مجرد تفضيلات. يمكن لـ Claude التفاعلي أن يطلب منك توضيحًا. يعمل التشغيل المستقل بما يجده في السياق. إذا كانت “عدم تعديل ملفات الترحيل مطلقًا دون إنشاء لقطة قاعدة بيانات أولاً” مهمة، فيجب أن تكون في CLAUDE.md. لا تفترض أن Claude سيستنتج القيد من بنية قاعدة الكود.

استخدم قواعد deny لأي شيء يصعب عكسه. الموافقة المسبقة على Bash(pnpm build) تسرع الجلسات التفاعلية وهي منخفضة المخاطر. لكن بالنسبة للتشغيلات المستقلة، فإن قائمة deny هي شبكة الأمان الخاصة بك للعمليات التي تلمس البنية التحتية للإنتاج، أو تلتزم بشكل دائم في تاريخ git، أو تحذف البيانات.

احتفظ بملف CLAUDE.md للمشروع في التحكم بالإصدارات. ملف CLAUDE.md المسجل في جذر المستودع ينطبق بشكل متسق على الجلسات التفاعلية، وتشغيلات CI، وأي وكيل محلي لأي عضو في الفريق. هذا هو المكان المناسب للقواعد التي تحدد ما يعنيه “صحيح” لقاعدة الكود الخاصة بك.

استخدم .claude/rules/ للمحتوى الخاص بالمجال. إذا كان مشروعك يحتوي على طبقات متميزة — مكونات الواجهة الأمامية، واجهة برمجة التطبيقات الخلفية، مخطط قاعدة البيانات، نصوص البنية التحتية — ضع قواعد كل طبقة في .claude/rules/ مع نطاق المسار. ملف CLAUDE.md واحد بطول 400 سطر يحتوي على كل شيء يجعل من الصعب على Claude التنقل ويكلف سياقًا أكثر لكل جلسة.

انقل المواد المرجعية إلى المهارات. المهارات (.claude/skills/) يتم تحميلها عند الطلب، وليس عند بدء الجلسة. توثيق API الطويل، إجراءات النشر متعددة الخطوات، وأدلة استكشاف الأخطاء تنتمي إلى المهارات التي تستدعيها بـ /deploy أو /debug — وليس في CLAUDE.md حيث تستهلك السياق حتى عندما تكون غير ذات صلة.

راجع الذاكرة التلقائية بشكل دوري. تتراكم الذاكرة التلقائية بمرور الوقت. تتغير أوامر البناء، ويتم إعادة هيكلة الاتفاقيات، وتتحول أنماط الاختبار. ملاحظة ذاكرة قديمة تقول “استخدم عميل API v1” عندما هاجرت إلى v2 ستسبب أخطاء دقيقة في التشغيلات المستقلة. قم بتدقيق ~/.claude/projects/<repo>/memory/ عندما تقوم بتغييرات كبيرة في هيكل المشروع.

استخدام النماذج مفتوحة المصدر مع إعداد القواعد الخاص بك

يعمل سياق CLAUDE.md و .claude/rules/ الذي بنيته بنفس الطريقة بغض النظر عن النموذج الذي يتعامل مع الاستدلال. بمجرد كتابة قواعدك، فإن تبديل النماذج الخلفية يحافظ على كل ذلك — والنماذج مفتوحة المصدر عبر Novita AI’s LLM API هي خيار عملي للعمل الوكيلي عالي الحجم.

التكوين هو متغير بيئة واحد:

export ANTHROPIC_BASE_URL="https://api.novita.ai/anthropic"
export ANTHROPIC_AUTH_TOKEN="<your-novita-api-key>"
export ANTHROPIC_MODEL="qwen/qwen3-coder-480b-a35b-instruct"

مع ANTHROPIC_BASE_URL الموجه إلى Novita AI، يرسل Claude Code جميع طلبات الاستدلال إلى نقطة نهاية Novita المتوافقة مع Anthropic بدلاً من api.anthropic.com. ملف CLAUDE.md الخاص بك، والقواعد المحددة النطاق، وملف settings.json كلها تنطبق تمامًا كما كانت من قبل — طبقة القواعد أعلى من اختيار النموذج.

تستضيف Novita AI نماذج مفتوحة الوزن موجهة للبرمجة بما في ذلك Qwen3-Coder و GLM-4.7 و MiniMax M2.5 و DeepSeek V4. هذه النماذج محسّنة لاستخدام الأدوات متعددة الخطوات واستدعاء الوظائف، وهو ما يتوافق جيدًا مع أنماط استدعاء الأدوات التي يستخدمها Claude Code داخليًا لتحرير الملفات وأوامر الصدفة والتنقل في المستودع.

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

إذا كنت تدير وكلاء مقابل قاعدة كود إنتاج وتريد طبقة أمان إضافية تتجاوز قواعد deny، ففكر في إقران Novita’s LLM API مع Novita’s Agent Sandbox. يمنح الصندوق الرملي الوكيل بيئة Linux كاملة لعمليات الملفات وتنفيذ الأوامر، معزولة عن نظام المضيف الخاص بك. سياق CLAUDE.md الخاص بك ينتقل مع المهمة؛ مخاطر التنفيذ تظل محصورة.

الأسئلة الشائعة

ما هو CLAUDE.md في Claude Code؟

CLAUDE.md هو ملف Markdown يعطي Claude Code تعليمات دائمة عبر الجلسات. يتم تحميله عند بدء الجلسة حتى لا يحتاج Claude إلى إعادة تعليم اتفاقيات مشروعك في كل مرة. يمكن أن يكون لديك ملفات CLAUDE.md على مستويات متعددة: مستوى المستخدم (~/.claude/CLAUDE.md) للتفضيلات الشخصية التي تنطبق في كل مكان، ومستوى المشروع (جذر المستودع) للقواعد المشتركة بين الفريق المسجلة في التحكم بالإصدارات، ومستوى الدليل الفرعي للقواعد الخاصة بالوحدة.

ما الذي يجب أن أضعه في ملفات قواعد claude md؟

اكتب ما ستضطر إلى شرحه مرة أخرى في كل جلسة: أوامر البناء والاختبار، اتفاقيات البرمجة التي تختلف عن الإعدادات الافتراضية للإطار، قيود البنية، والمشكلات المعروفة في قاعدة الكود. اترك المحتوى الذي يمكن لـ Claude استنتاجه من قاعدة الكود نفسه — أشجار الملفات، قوائم التبعيات، وأوصاف ما يفعله الكود الموجود. حافظ على الملفات أقل من 200 سطر للالتزام المتسق.

ما الفرق بين CLAUDE.md و settings.json في Claude Code؟

CLAUDE.md هو تعليمات يتبعها Claude كإرشاد. settings.json هو تكوين يفرضه Claude Code على مستوى النظام. قاعدة في CLAUDE.md تشكل ما يعتزم Claude فعله؛ إدخال deny في settings.json يمنع استدعاء أداة دون شرط. لأي شيء يجب ألا يحدث بغض النظر عما يقرره Claude — حذف غير قابل للعكس، دفع قسري، عمليات بيئة الإنتاج — استخدم settings.json، وليس CLAUDE.md.

ما هو دليل .claude/rules/؟

.claude/rules/ يحتوي على ملفات قواعد محددة النطاق يتم تحميلها فقط عندما يعمل Claude مع ملفات تطابق نطاق القاعدة. هذا يتيح لك كتابة قواعد مفصلة خاصة بالمجال دون تحميلها في كل جلسة. القواعد هي ملفات Markdown مع صفحة أمامية YAML اختيارية تحدد أنماط glob لـ paths. القواعد بدون صفحة أمامية paths يتم تحميلها دون شرط عند بدء الجلسة، مثل محتوى CLAUDE.md إضافي.

هل يعمل CLAUDE.md في مهام CI و claude code الآلية؟

نعم. أي استدعاء claude -p، أو استدعاء Agent SDK، أو خط أنابيب CI يعمل في دليل مستودع يقوم بتحميل CLAUDE.md الخاص بالمشروع. هذا يجعل CLAUDE.md فعالاً لفرض سلوك متسق في كل من السياقات التفاعلية والآلية. تسجيله في التحكم بالإصدارات يضمن أن كل تشغيل — محلي و CI — يبدأ بنفس السياق المشترك.

كيف يعمل سياق claude code وكيف أديره؟

السياق هو ميزانية الرموز للجلسة الحالية. ملفات CLAUDE.md، والمراجع المستوردة، والذاكرة التلقائية، وتاريخ المحادثة كلها تحسب ضمنه. قم بإدارته عن طريق الحفاظ على CLAUDE.md موجزًا، واستخدام .claude/rules/ لتحميل محتوى المجال فقط عند الحاجة، واستخدام /compact لتلخيص الجلسات الطويلة دون فقدان الاستمرارية. بعد /compact، يعيد Claude قراءة ملف CLAUDE.md لجذر المشروع من القرص ويحقنه تلقائيًا في الجلسة.

كيف أستخدم أفضل ممارسات claude code للبرمجة الوكيلية في فريق؟

قم بتسجيل ملف CLAUDE.md للمشروع في مستودعك بحيث يشارك جميع أعضاء الفريق ووكلاء CI نفس القواعد. استخدم .claude/rules/ مع نطاق المسار للمحتوى الخاص بالمجال. أضف قواعد deny إلى .claude/settings.json للعمليات التي يجب ألا تعمل أبدًا في السياقات الآلية. أبقِ الذاكرة التلقائية خارج CI — فهي محلية للجهاز ولكل مطور؛ ملف CLAUDE.md المسجل هو مصدر الحقيقة للسلوك المشترك.

Novita AI هي منصة سحابية للذكاء الاصطناعي تقدم للمطورين طريقة سهلة لنشر نماذج الذكاء الاصطناعي باستخدام واجهة برمجة التطبيقات البسيطة الخاصة بنا، مع توفير سحابة GPU ميسورة التكلفة وموثوقة للبناء والتوسع.

مقالات موصى بها

• توثيق Claude Code CLI: الإعداد، أوامر الشرطة المائلة، وتكامل LLM API
• Claude Code SDK: بناء وكلاء مستقلين باستخدام Python و TypeScript
• بناء وكيل برمجي باستخدام Novita’s Agent Sandbox

---

المصادر تم التحقق منها في 21 يوليو 2026: توثيق ذاكرة Claude Code، نظرة عامة على ميزات Claude Code، Novita AI LLM API