أفضل ممارسات CLAUDE.md: 9 قواعد تجعل Claude يلتزم بتعليماتك (2026)

أفضل ممارسات CLAUDE.md: 9 قواعد تجعل Claude يلتزم بتعليماتك (2026)

معظم المقالات التي تتناول أفضل ممارسات CLAUDE.md تعطيك قالباً وتعتبر المهمة منجزة — لكن الملف الذي كتبته الأسبوع الماضي على الأرجح يُتجاهل بالفعل، وأنت لا تدري. الحل نادراً ما يكون "أضف المزيد من القواعد"، بل العكس في الغالب. لقد شحنّا Claude Code في كل مشروع عميل مؤخراً، وهذه القواعد التسع هي ما يُحدث فارقاً حقيقياً: تسلسل هرمي يتوافق مع آلية تحميل Claude للملفات، وميزانية تعليمات لا يمكن تجاوزها، وقرار AGENTS.md، والأسباب الستة التي تجعل Claude يتجاهل ملفك في صمت في منتصف الجلسة.

أبرز النقاط

• CLAUDE.md هو ذاكرة المشروع التي يحملها Claude Code في سياقه — احتفظ بها تحت 200 سطر وإلا ستبدأ القواعد تتساقط.
• تُحمَّل الملفات من أعلى إلى أسفل: العام، وجذر المشروع، والدليل الفرعي (تحميل كسول)، وCLAUDE.local.md (شخصي، مستبعد من git).
• استخدم AGENTS.md إن كنت تشغّل Cursor أو Copilot أيضاً؛ قم بعمل symlink من CLAUDE.md إلى AGENTS.md للاستهداف المزدوج.
• إذا كان Claude يتجاهل ملفك، فالسبب في 90% من الحالات هو طول الملف، أو الصياغة المبهمة، أو غياب "السبب".

ما الذي يفعله CLAUDE.md فعلاً (ولماذا يهم)

باختصار: CLAUDE.md هو ملف markdown يقرأه Claude Code كـذاكرة للمشروع في بداية كل جلسة. إنه ليس system prompt ولا hook ولا skill — بل سياق استشاري يُوجّه Claude نحو اتفاقيات فريقك. فكّر فيه أقل كوثيقة وأكثر كملف إعداد يقرأه فعلاً المبرمج الذكاء الاصطناعي المشارك لك في العمل.

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

كذلك ليس الطريقة الوحيدة لتوجيه Claude. Hooks تُشغّل إجراءات حتمية (تنسيق، حجب commits). Skills تجمع سير عمل قابلة لإعادة الاستخدام. يقع CLAUDE.md بينهما كسياق استشاري — يُقيّمه Claude، وأحياناً يتجاوزه، ويطغى على أجزاء منه إن كتبت كثيراً. هذا الفرق هو أساس كل ما سيأتي، وهو سبب كون CLAUDE.md أداة ضمن ممارسة أشمل تُسمى هندسة السياق، لا حلاً سحرياً شاملاً.

القاعدة الأولى: تعامل معه ككود، لا كوثيقة. احتفظ بنسخه. راجع تغييراته في طلبات السحب (PRs). قلّمه كما تُعيد هيكلة وحدة برمجية متضخمة. وفقاً لـدليل Anthropic لـ CLAUDE.md، يُحمَّل الملف بالأولوية ذاتها لأي تعليمة نظام — مما يعني أن قاعدة قديمة من ستة أشهر لا تزال تشكّل كل رد اليوم.

كيف يُحمَّل CLAUDE.md: التسلسل الهرمي ذو الأربعة مستويات

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

التسلسل الهرمي هو الجزء الأكثر سوء فهماً في CLAUDE.md، وهو المكان الذي لا يتعمق فيه أي من أفضل 5 نتائج في محركات البحث. إليك ما يجري فعلاً خلف الكواليس:

مصطلحان يستحقان التثبيت: التحميل الكسول والعزل بين الدلائل المجاورة.

التحميل الكسول يعني أن ملف CLAUDE.md في دليل فرعي لا يدخل سياق Claude حتى يفتح Claude فعلياً ملفاً داخل ذلك الدليل. إذا طلبت "أصلح خلل تسجيل الدخول" ولم يتعامل Claude إلا مع backend/، فإن frontend/CLAUDE.md لن يُحمَّل قط. هذا جيد — يُبقي نافذة السياق نظيفة — لكنه يعضّ الفرق التي تضع قواعد حرجة في دلائل فرعية متوقعةً أن تُطبَّق دائماً.

العزل بين الدلائل المجاورة هو النتيجة الطبيعية لذلك: frontend/CLAUDE.md وbackend/CLAUDE.md لا يُحمِّل أحدهما الآخر. يشتركان فقط فيما هو في ملف جذر المشروع. إذاً إن تعارضت قواعد الواجهة الأمامية مع قواعد الخلفية، لا مشكلة. أما إن احتاجت إلى اتفاقية مشتركة، فارفعها إلى الملف الجذري.

CLAUDE.local.md هو مخرج الطوارئ. يُحمَّل دون أن يُودَع، مثالي لتعديلات من نوع "أنا أفضّل pnpm لكن الفريق توحّد على npm". التحذير: لا يُستبعد تلقائياً من git. عليك إضافته يدوياً إلى .gitignore. انسَ ذلك وستودع قواعدك الشخصية في مستودع الفريق.

القاعدة الرابعة: طابق التعليمات مع المكان الذي يقرأ فيه Claude فعلاً. قواعد تنسيق مكوّنات React تنتمي إلى frontend/CLAUDE.md، لا الجذر. قواعد هجرة قاعدة البيانات تنتمي إلى backend/. تؤكد وثائق Anthropic للذاكرة (محدَّثة نوفمبر 2025) هذا — سلوك التحميل الكسول مقصود وجوهري.

ما يجب وضعه داخل CLAUDE.md (وما يجب تركه خارجه)

باختصار: داخل CLAUDE.md يذهب كل ما لا يستطيع Claude استنتاجه من كودك: أوامر البناء، اتفاقيات التسمية، الأنماط المضرة التي أخطأ فيها فريقك، وسبب كل قاعدة. خارجه يذهب ما هو في README، وما هو في package.json، وأي قاعدة تتغير أسبوعياً. يجب أن تكون تعليمات Claude Code قابلة للاختبار ومحددة.

إليك ملف CLAUDE.md مبسّط يُؤدي دوره فعلاً:

# Project: techsy-app

## Commands
- Build: `pnpm build` (Turbopack — Webpack flags don't apply)
- Test: `pnpm test --run` (we use Vitest, not Jest)
- Lint: `pnpm lint` (will fail CI on warnings, not just errors)

## Conventions
- Server components by default. Add `'use client'` only when truly needed.
  Why: we hit 8s LCP last quarter from over-clienting.
- Database access only via `lib/db/` helpers — never raw SQL in routes.
  Why: row-level security policies live in those helpers.
- Tests colocate as `*.test.ts` next to the file under test.

## Don'ts
- Don't add a new dependency without opening a PR comment first.
- Don't use `any` — use `unknown` and narrow.

## Where to look
- Schema: `db/schema.ts`
- Auth flow: `lib/auth/README.md`

قارن الآن ذلك بالنمط المضاد الذي تشحن به معظم الفرق:

# Project Rules

- Write clean, maintainable code.
- Follow best practices.
- Use TypeScript properly.
- Make sure tests pass.
- Be consistent with existing patterns.
- Document complex logic.

الملف الثاني ليس خاطئاً. إنه عديم الفائدة فقط. Claude يريد أصلاً كتابة كود نظيف. "كن متسقاً" لا يخبر Claude مع أي نمط يتسق. تميل أمثلة المهندس في Anthropic Boris Cherny العامة بشدة نحو الأسلوب الأول — أوامر محددة، وأدوات مُسمّاة، وسبب القرارات غير الواضحة من قاعدة الكود وحدها.

القاعدة الثانية: كن محدداً، لا طموحاً. "اكتب كوداً نظيفاً" طموح. "مكوّنات الخادم كقاعدة افتراضية؛ أضف 'use client' فقط عند الضرورة الحقيقية" قابل للاختبار. الانضباط نفسه يقوم عليه هندسة الأوامر الجيدة: التعليمات المحددة القابلة للاختبار تتفوق على الطموحات الغامضة، سواء عاشت في برومبت أو في ملف CLAUDE.md.

القاعدة الثالثة: اشرح سبب أهمية كل قاعدة. السبب ليس ثرثرة — إنه ما يُمكّن Claude من التعامل مع الحالات الحدية. قاعدة مشفوعة بسبب ("أصبنا بـ 8 ثوانٍ LCP من الإفراط في استخدام client") تتعمّم على الحالات المشابهة. قاعدة دون سبب تُتجاهل ما إن يتغير السياق. هذا النمط موثق أيضاً في دليل Builder.io لـ CLAUDE.md.

لماذا يتجاهل Claude ملف CLAUDE.md الخاص بك؟ ميزانية التعليمات

باختصار: Claude ليس خبيثاً — إنه ينفد من الانتباه. بعد نحو 80 سطراً ستلاحظ سقوط القواعد؛ وبعد 200 سطر تُتجاهل مقاطع كبيرة كلياً؛ وبعد 500 كلمة من القواعد الكثيفة ينهار الالتزام. الحل هو ميزانية التعليمات. تعامل مع كل سطر كتكلفة على ذاكرة Claude Code والتزام كل قاعدة على حدة.

تُؤكد أبحاث حديثة ما يكتشفه مستخدمو الإنتاج باستمرار: اتباع التعليمات يتدهور بشكل غير خطي مع زيادة عدد القواعد. تُظهر ورقة arxiv رقم 2507.11538 حول قدرة اتباع التعليمات انخفاض الالتزام بكل قاعدة كلما تراكمت أكثر — وتعكس تحليلات HumanLayer لـ CLAUDE.md في بيئات الإنتاج النتيجة ذاتها.

الخلاصة: كل قاعدة تضيفها تجعل كل قاعدة أخرى أقل احتمالاً للاتباع. لذا CLAUDE.md من 400 سطر ليس أكثر فاعلية بـ 4 أضعاف من ملف 100 سطر. بل غالباً أقل فاعلية، لأن القواعد التي تهمك حقاً تُخفَّف بتلك التي كتبتها يوم جمعة قبل ثلاثة أشهر ولم تحذفها.

في ملفات CLAUDE.md لدينا، يبدأ كل شيء بعد السطر 150 في فقدان الالتزام بشكل واضح. وبحلول السطر 250 رأينا Claude يتخطى أقساماً كاملة. لذا نُحدد سقفاً.

wc -l CLAUDE.md

هذه هي الأداة الكاملة. شغّلها. إن تجاوزت 200، فقد تجاوزت الميزانية. القاعدة الصارمة التي نسلّمها للعملاء:

تعامل مع CLAUDE.md كميزانية من 200 سطر. كل سطر يُكلّف التزاماً. أنفقه حيث يهم.

القاعدة الأولى مُعززة: احتفظ به قصيراً. تحت 200 سطر. تحت 500 كلمة من القواعد الكثيفة. إن وجدت نفسك تريد إضافة قواعد أتمتة ("شغّل prettier دائماً بعد التعديلات")، فهذه على الأرجح تنتمي إلى hooks الخاصة بـ Claude Code عوضاً عن ذلك — فالـ hooks حتمية ولا تستهلك رموز ميزانية التعليمات.

هل تستخدم CLAUDE.md أم AGENTS.md أم .cursorrules أم copilot-instructions؟

باختصار: إن كنت تستخدم Claude Code فقط، CLAUDE.md يكفي. إن كنت تستخدم اثنتين أو أكثر من واجهات CLI للوكلاء (Codex وCursor وCopilot وSourcegraph)، انتقل إلى AGENTS.md واجعل CLAUDE.md رابطاً رمزياً (symlink) له. ظهر AGENTS.md في أواخر 2025 كمعيار مشترك بين الأدوات — تعود إليه معظم الوكلاء الحديثة كملف احتياطي، فيتغذى ملف واحد على كل النظام البيئي.

هذا هو السؤال الذي لا تُجيب عنه أي من أفضل 5 نتائج. إليك المصفوفة:

حيلة الاستهداف المزدوج في سطر واحد:

ln -s AGENTS.md CLAUDE.md

هذا كل شيء. الآن يقرأ Claude Code وCodex وأي أداة تدعم AGENTS.md الملف ذاته. حدّث مرة واحدة، يلتقطه كل وكيل. مواصفات AGENTS.md مفتوحة ومبسّطة بشكل مقصود — مجرد markdown مع أقسام متعارف عليها.

تحفظان من الواقع العملي. أولاً: إن كان فريقك يضم مستخدماً متمكناً من Cursor، فـقواعد Cursor .cursorrules تتبع نهجاً مختلفاً — ملف واحد، بدون تسلسل هرمي، تنسيق أكثر صرامة. بعض الفرق تحتفظ بالاثنين: AGENTS.md للقواعد المشتركة، و.cursorrules لخصوصيات Cursor. ثانياً: ملف .github/copilot-instructions.md الخاص بـ Copilot لا يعود إلى AGENTS.md احتياطياً، لذا تحتاج الفرق الكثيفة الاستخدام لـ Copilot ملفاً منفصلاً.

إن كنت تختار بنية وكلاء من الصفر، يُغطي مقارنتنا Claude Code مقابل Cursor مقابل Copilot المقايضات على مستوى الإطار. الخلاصة: تسلسل Claude Code الهرمي هو الأقوى للـ monorepos، وتجربة Cursor تفوز للعمل الفردي، وتكامل Copilot مع IDE لا يزال الأسلس للاعتماد التدريجي.

القاعدة التاسعة: استخدم AGENTS.md إن كنت تشغّل أكثر من واجهة CLI للوكلاء. لا تحافظ على ملفين يقولان الشيء نفسه. اختر الملف الذي يقرأه معظم بنيتك، واجعل الباقي روابط رمزية.

CLAUDE.md مقابل Hooks مقابل Skills: مثلث القرار

باختصار: CLAUDE.md = سياق استشاري. Hooks = إجراءات حتمية. Skills = قدرات مجمّعة. اختر الخطأ وستحرق ميزانية التعليمات على ما يجب أن يتولاه hook، أو تكتب قاعدة CLAUDE.md على شيء لا يستطيع تسليمه إلا skill. المثلث هو أرخص طريقة لإبقاء CLAUDE.md نحيلاً.

ثلاثة أدوات، ثلاثة أدوار. الخطأ الأكثر شيوعاً الذي نراه: وضع "شغّل prettier دائماً بعد التعديل" في CLAUDE.md. Claude يقرأها. Claude أحياناً يُشغّل prettier. أنت محبط. الحل هو نقل ذلك السطر خارج CLAUDE.md إلى hook — لأن الـ hooks تُشتعل حتمياً في كل مرة، بدون هامش استشاري.

إن كانت القاعدة يجب أن تُطبَّق دائماً، فهي تنتمي إلى hook. إن كانت تفضيل أسلوب يستطيع Claude تقييمه في السياق، فهي تنتمي إلى CLAUDE.md. إن كانت سير عمل متعدد الخطوات مع أصول مجمّعة (قوالب، سكريبتات، مطالبات)، فهي تنتمي إلى skill.

القاعدة الثامنة: اختر بين CLAUDE.md وHooks وSkills بصورة صحيحة — وضع hook داخل CLAUDE.md هو أكثر هدر شائع لميزانية التعليمات. اضبط الإجراءات الحتمية بـhooks الخاصة بـ Claude Code وعبّئ سير العمل القابلة للإعادة كـClaude skills. يصبح CLAUDE.md أقصر، وتصبح ضماناتك أصلب، ويتوقف Claude عن "نسيان" القواعد التي تهم.

أنماط Monorepo: CLAUDE.md المتداخل، @imports، و.claude/rules/

باختصار: في monorepo، احتفظ بـ CLAUDE.md الجذري صغيراً — مؤشرات واتفاقيات مشتركة فقط. ادفع التفاصيل إلى apps/*/CLAUDE.md لتكون لكل شجرة فرعية قواعدها المحددة. استخدم @imports لمشاركة ملفات قواعد نمطية عبر .claude/rules/. هذا هو الكشف التدريجي — Claude يسحب كل جزء فقط عند الحاجة.

شجرة CLAUDE.md نموذجية في monorepo:

.
├── CLAUDE.md                        # 30 سطراً — يُشير إلى الدلائل الفرعية والقواعد المشتركة
├── .claude/
│   └── rules/
│       ├── style.md
│       ├── testing.md
│       └── security.md
├── apps/
│   ├── web/
│   │   └── CLAUDE.md                # قواعد خاصة بـ Next.js
│   └── api/
│       └── CLAUDE.md                # قواعد خاصة بـ Fastify
└── packages/
    └── shared/
        └── CLAUDE.md                # قواعد مؤلف المكتبة

تتيح صيغة @import للملف الجذري استيراد أجزاء قواعد مشتركة دون إعادة ذكرها:

# Root CLAUDE.md

This is a Turborepo. See subdir CLAUDE.md for app-specific rules.

@import .claude/rules/style.md
@import .claude/rules/testing.md
@import .claude/rules/security.md

## Top-level commands
- `pnpm dev` runs all apps in parallel
- `pnpm test` runs every workspace's test script

هذا هو الكشف التدريجي عملياً. الملف الجذري مؤشر من 30 سطراً. كل ملف CLAUDE.md في دليل فرعي يضيف 50–80 سطراً من القواعد المركّزة. ملفات .claude/rules/ تحمل أجزاء الاتفاقيات التي يستطيع استيرادها عدة دلائل فرعية. لا شيء يُكرَّر، لا شيء يُفوَّت، ولا ملف واحد يتجاوز ميزانية التعليمات.

قاعدة التحميل الكسول من قبل أهم هنا أكثر من أي وقت: عندما يعمل Claude على apps/web/Button.tsx، يرى الملف الجذري بالإضافة إلى apps/web/CLAUDE.md بالإضافة إلى ملفات القواعد المستوردة بـ @import. لا يرى apps/api/CLAUDE.md. هذه هي النقطة بأكملها — اتفاقيات الخلفية لا تُلوّث سياق الواجهة الأمامية، وتظل نافذة سياقك قابلة للاستخدام.

القاعدة السادسة: استخدم @imports لإبقاء الملف الجذري تحت 200 سطر. يعدّ دليل Anthropic لأفضل ممارسات Claude Code هذا النمط القياسي لـ monorepos. يرث الوكلاء الفرعيون (subagents) سياق CLAUDE.md الأبوي أيضاً، وهو ما يستحق المعرفة إن كنت تُداخل سير العمل — راجع هندسة السياق لمعرفة كيفية تفاعل ذلك مع تصميم الوكلاء الفرعيين.

6 أسباب تجعل Claude يتجاهل ملفك (والإصلاح لكل منها)

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

1. الملف طويل جداً (أكثر من 200 سطر / 500 كلمة)

شغّل wc -l CLAUDE.md. إن تجاوز 200، قُصّ بحزم. انقل قواعد الأتمتة إلى hooks. انقل سير العمل إلى skills. قسّم الأجزاء المشتركة إلى .claude/rules/ واسحبها بـ @import. السبب الأكثر شيوعاً لتوقف Claude عن اتباع قواعدك هو أن الملف أصبح طويلاً تدريجياً وانهار الالتزام بصمت.

2. صياغة مبهمة ("اكتب كوداً نظيفاً")

استبدل كل قاعدة طموحة بقاعدة محددة قابلة للاختبار. "كن متسقاً" غير مرئي لـ Claude. "استخدم مكوّنات الخادم كقاعدة افتراضية؛ أضف 'use client' فقط للنماذج أو الواجهة التفاعلية" شيء يستطيع Claude تطبيقه فعلاً.

3. السبب غائب

القواعد بلا أسباب لا تتعمّم. لا يستطيع Claude استنتاج متى يثني القاعدة لأنه لا يعرف ما تحميه. كل قاعدة غير واضحة تحتاج سطراً: "نستخدم unknown لا any لأننا أصبنا بثلاثة تعطلات في وقت التشغيل من استجابات API كانت مُنمَّطة بـ any الربع الماضي."

4. ضغط السياق أسقطه

الجلسات الطويلة تُشغّل الضغط — Claude يُلخّص السياق السابق ليتناسب مع النافذة، وأحياناً يُلخَّص محتوى CLAUDE.md إلى حد الضياع. الإصلاح: /clear بعد حرق السياق الكثيف، أو أعد تشغيل الجلسة كلياً. هذا بالضبط ما تستمر مشكلة GitHub رقم 17530 في إظهاره.

5. تعارض مع CLAUDE.md أبوي

يقول العام "استخدم 4 مسافات". يقول جذر المشروع "استخدم مسافتين". الدليل الفرعي لا يقول شيئاً. يختار Claude — وأحياناً يختار الخطأ. افحص ~/.claude/CLAUDE.md وجذر المشروع بحثاً عن التناقضات. الأكثر تحديداً يجب أن يفوز، لكن فقط إن جعلت ذلك صريحاً.

6. مسار الملف خاطئ أو حالة الأحرف غلط

Claude.md وCLAUDE.md ملفان مختلفان على Linux وmacOS. وكذلك claude.md وCLAUDE.md. تأكد من أن المسار هو ./CLAUDE.md بالضبط (بأحرف كبيرة بالكامل)، وتأكد من تشغيل Claude Code من الدليل المحتوي عليه. مشكلة GitHub رقم 668 مليئة بحالات كان الملف موجوداً لكن Claude لم يستطع رؤيته بسبب المسار.

القاعدة السابعة: اختبر في جلسة جديدة. بعد أي تغيير على CLAUDE.md، افتح جلسة جديدة واسأل Claude "لخّص القواعد في CLAUDE.md". إن فاته شيء، فالملف لا يؤدي دوره.

أول CLAUDE.md لك في 10 دقائق: وصفة من 5 خطوات

باختصار: شغّل /init لبذر مسودة، قلّصها إلى 6–10 قواعد حقيقية مع أسباب، أضف 3 أوامر يجب أن يعرفها Claude، أضف نمطين مضادين أصابهما فريقك، ثم اختبر في جلسة جديدة بطلب من Claude تلخيص الملف. الوقت الإجمالي: نحو 10 دقائق. هذه الوصفة الخماسية هي ما نستخدمه في اليوم الأول من كل مستودع جديد.

1. شغّل /init لبذر مسودة. يفحص أمر /init في Claude Code مستودعك ويكتب CLAUDE.md ابتدائياً. لا ترسله كما هو. ناتج /init نقطة بداية، لا ملف جاهز — وبصراحة، معظم ما يولّده يمكن حذفه.

2. قلّصه إلى 6–10 قواعد حقيقية مع أسباب. احذف أي شيء عام. احذف أي شيء موجود في README. احتفظ فقط بالقواعد التي لا يستطيع Claude استنتاجها من الكود بنفسه.

3. أضف 3 أوامر يجب أن يعرفها Claude. البناء، والاختبار، والـ lint. ضمّن الأمر الدقيق وأي خيارات (flags) غير واضحة. إن كنت تستخدم Vitest لا Jest، قل ذلك.

4. أضف نمطين مضادين أصابهما هذا الفريق فعلاً. حقيقيين. "لا تستخدم any لأننا أصبنا بثلاثة تعطلات في وقت التشغيل" يفوق دائماً "استخدم TypeScript بشكل صحيح".

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

القاعدة الخامسة: لا تعتمد على /init وحده. /init نقطة بداية، لا ملف جاهز. الـ 8 دقائق التي تقضيها في التقليص والإضافة هي المكان الذي تكمن فيه القيمة.

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

ما هو ملف CLAUDE.md؟

ملف CLAUDE.md هو ملف markdown يقرأه Claude Code كذاكرة للمشروع في بداية كل جلسة. يُخبر Claude باتفاقياتك وأوامرك والأنماط المضرة كي لا يضطر إلى التخمين. يعمل على أربعة مستويات: العام، وجذر المشروع، والدليل الفرعي (تحميل كسول)، وملف CLAUDE.local.md الشخصي الذي تبقيه مستبعداً من git.

ما هو الطول المناسب لملف CLAUDE.md؟

تحت 200 سطر وتحت 500 كلمة من القواعد الكثيفة. بعد تلك العتبات، يتدهور اتباع Claude للتعليمات — كل قاعدة تضيفها تجعل كل قاعدة أخرى أقل احتمالاً للاتباع. تعامل معه كميزانية ثابتة. إن احتجت المزيد، قسّمه إلى ملفات CLAUDE.md في دلائل فرعية واستخدم @import للأجزاء المشتركة.

أين يجب أن أضع CLAUDE.md؟

الملف الرئيسي يذهب في جذر مشروعك (./CLAUDE.md) ويُودَع. أضف ملفات CLAUDE.md في دلائل فرعية للقواعد المخصصة لكل تطبيق في monorepos. ضع التفضيلات متعددة المشاريع في ~/.claude/CLAUDE.md. استخدم CLAUDE.local.md للتعديلات الشخصية التي لا تريد إيداعها — لكن تذكر استبعاده يدوياً من git.

لماذا يتجاهل Claude ملف CLAUDE.md الخاص بي؟

90% من الوقت يكون السبب واحداً من ثلاثة: الملف طويل جداً (فوق 200 سطر)، القواعد مبهمة ("اكتب كوداً نظيفاً")، أو القواعد تفتقر إلى "السبب" الذي يساعد Claude على تطبيقها. شغّل wc -l CLAUDE.md، ثم افحص التحديد. اختبر التغييرات في جلسة جديدة بطلب من Claude تلخيص الملف.

هل أستخدم CLAUDE.md أم AGENTS.md؟

إن كان فريقك يستخدم Claude Code فقط، الزم CLAUDE.md. إن كنت تستخدم اثنتين أو أكثر من واجهات CLI للوكلاء (Codex، Cursor، Sourcegraph)، انتقل إلى AGENTS.md واجعل CLAUDE.md رابطاً رمزياً له: ln -s AGENTS.md CLAUDE.md. تعود معظم واجهات CLI الحديثة للوكلاء إلى AGENTS.md احتياطياً، فيتغذى ملف واحد على كل الأدوات.

هل أشغّل /init لتوليد CLAUDE.md؟

نعم — كمسودة. لا — كملف جاهز. يفحص /init مستودعك ويُنتج نقطة بداية، لكنه مطوّل وعام. تُوصي كل من Anthropic وHumanLayer بالتقليص الجذري بعد تشغيل /init. الـ 8 دقائق التي تقضيها في الحذف وإضافة أسطر "السبب" هي المكان الذي يصبح فيه الملف مفيداً فعلاً.

كيف تعمل ملفات CLAUDE.md في monorepo؟

يظل CLAUDE.md الجذري صغيراً — مؤشرات وقواعد مشتركة فقط. كل تطبيق يحصل على apps/*/CLAUDE.md خاص به مع اتفاقيات محددة النطاق. تُحمَّل ملفات الدلائل الفرعية بشكل كسول فقط عندما يقرأ Claude ملفات داخل تلك الشجرة الفرعية، فتظل الدلائل المجاورة معزولة. استخدم @import .claude/rules/style.md لمشاركة أجزاء القواعد النمطية دون تكرارها عبر التطبيقات.

ما الفرق بين CLAUDE.md وHooks وSkills؟

CLAUDE.md هو سياق استشاري — يقرأه Claude ويتبعه عادةً. Hooks هي إجراءات حتمية تُشتعل دائماً (التنسيق، حجب الـ commits). Skills هي قدرات مجمّعة لسير عمل قابلة للإعادة مع أصول. استخدم CLAUDE.md لتوجيه الأسلوب، وHooks للقواعد الصارمة، وSkills للمهام متعددة الخطوات التي ستكررها عبر المشاريع.

كيف يتعامل Techsy مع هذا

في Techsy، كل مشروع Claude Code نشحنه يحتوي على CLAUDE.md تحت 150 سطراً ورابط رمزي لـ AGENTS.md. نتعامل مع الملف كالكود — نُصدر نسخاً منه، ونراجع التغييرات في طلبات السحب، ونُعيد الاختبار في جلسات جديدة قبل الدمج. هل تحتاج مساعدة في دمج وكلاء الذكاء الاصطناعي في سير عمل التطوير لديك؟ احصل على استشارة مجانية.