CLAUDE.md لدينا 162 سطرًا. هذا ما فيه — وما حذفناه.
اختصرنا CLAUDE.md في جذر المشروع من 820 إلى 162 سطرًا دون فقدان أي guardrails. الحيلة كانت استبدال البروتوكولات inline بجدول محفّزات للمهارات ونقل قواعد المجال إلى ملفات متداخلة وقواعد path-scoped.
أغلى ملف في مستودعك لم تكن تعلم بأمره
إذا كنت تستخدم Claude Code، فإن CLAUDE.md في جذر مشروعك هو الملف الأغلى منفردًا في مستودعك. ليس بسبب مساحة القرص — بل لأن كل بايت منه يُحمَّل في السياق عند بدء كل جلسة دون أي تحميل كسول. الـ skills تُحمَّل تدريجيًا. وأدوات MCP يمكن تأجيلها. أما CLAUDE.md فيجلس هناك، محمَّلًا دائمًا، مفروضًا على نافذتك دائمًا.
كان لدينا 820 سطرًا. اختصرناه إلى 162 دون فقدان أي guardrail. هذا المقال هو بالضبط ما خرج، وما بقي، والأنماط الثلاثة التي قامت بالعمل.
الأرقام الرئيسية: 820 → 162 سطرًا، ~8000 → ~1200 رمز، وحصّة ~12% → ~0.75% من نافذة سياق 200K.
لماذا يستحق CLAUDE.md مقالًا خاصًا به
في مقالنا الأشمل عن تحسين الرموز، كان MCP Tool Search أكبر رافعة منفردة. وCLAUDE.md هو الثانية. تشير الأبحاث على أُطُر Claude Code الكبيرة إلى أن إعدادات الجذر المحسَّنة تحقّق انخفاضًا بنسبة 54-62% في الحمل الأساسي، وأحد الأنماط المضادّة الموثّقة — CLAUDE.md بحجم 2800 سطر — أهدر نحو 62% من الرموز لكل جلسة.
السبب يكمن في الآلية. يُحمَّل محتوى CLAUDE.md على كل مستوى في التسلسل الهرمي بشكل غير مشروط:
- ملفات سياسة المؤسسة
CLAUDE.mdفي جذر المشروع~/.claude/CLAUDE.mdعلى مستوى المستخدم- التجاوزات المحلّية للمشروع
- أي ملف يُستورَد عبر صيغة
@path/to/file(متكرّر حتى 5 مستويات في العمق)
كل ما يفعله Claude Code حول السياق — التحميل التدريجي للـ skills، MCP Tool Search، عزل subagent — مصمَّم لتفادي ضريبة التحميل الدائم. أما CLAUDE.md فهو الشيء الوحيد الذي تدفع ثمنه دون شرط، في كل دور.
قبل: 820 سطرًا، نحو 12% من السياق
كان CLAUDE.md الأصلي لدينا يُقرأ كدليل شركة. كان يوثّق كل skill نستخدمه، وكل خطوة من بوابة الإصدار، وكل دقيقة من إعداد WordPress Coding Standards، وكل اصطلاح تسمية لمكوّنات React، وكل قاعدة scoping للأصول الإدارية. كان مادة مرجعية مفيدة فعلًا. كان أيضًا يُحمَّل في كل جلسة، بما في ذلك جلسات لا علاقة لها بمعظمه.
إليك حصرًا تقريبيًا لما كان فيه:
| القسم | الأسطر | الرموز التقريبية | هل تكرار التحميل مبرَّر؟ |
|---|---|---|---|
| خريطة مساحة العمل وبنية المشروع | 90 | 900 | نعم — سياق لأي جلسة |
| البنية وحزمة التقنيات | 60 | 600 | نعم |
| قواعد الخصوصية (غير قابلة للتفاوض) | 40 | 400 | نعم — invariants حرجة |
| أوصاف لكل skill (أكثر من 30 مدخلًا) | 180 | 1800 | لا — الـ skills الفردية تُحمَّل عند الطلب |
| بروتوكولات لكل سير عمل (مفصّلة) | 200 | 2000 | لا — مطلوبة فقط أثناء ذلك السير |
| معايير الاختبار بالتفصيل | 120 | 1200 | لا — مرتبطة فقط بجلسات كتابة الاختبارات |
| إرشادات بوابة الإصدار | 80 | 800 | لا — تعيش في skill الإصدار |
| ملاحظات استكشاف الأخطاء | 50 | 500 | لا — نادرًا ما تُحتاج |
كل ما وُسم بـ «لا» كان يدفع ضريبة على كل جلسة ليكون متاحًا لجزء صغير منها. هذا نحو 6300 رمز هدر — حوالي 3% من نافذة السياق بأكملها، بشكل دائم.
بعد: 162 سطرًا، نحو 0.75%
يغطّي CLAUDE.md الجديد مساحة السطح ذاتها بثلاثة أنماط: جدول محفّزات، وملفات CLAUDE.md متداخلة، وقواعد path-scoped.
النمط 1: جدول محفّزات الـ Skill
بدلًا من توثيق كل skill بفقرة، استبدلنا ~30 وصفًا لكل skill بجدول بحث واحد:
## Skill triggers
| Trigger keywords | Skill | Domain |
|------------------|-------|--------|
| sprint, backlog, iteration | pm-sprint-plan | PM |
| story, acceptance criteria | pm-story-write | PM |
| deploy, release, ship | statnive-release | Dev |
| security, audit, CVE | sec-audit-remediate | Security |
| wireframe, mockup | ux-design | UX |
| benchmark, performance | wp-performance | WP |تشير الأبحاث على الأُطُر الكبيرة إلى أن هذا النمط يكلّف ~800 رمز مقابل 3000+ للنثر المسهب لكل skill. توجيه Claude لا يزال يعمل بشكل صحيح لأن الكلمات المحفّزة هي ما يطابقه فعلًا — النثر المطوّل «متى تستخدم هذا الـ skill ومتى لا تستخدمه» الذي اعتدنا كتابته لم يساعد التوجيه أبدًا، بل ملأ السياق فحسب.
كل المحتوى التفصيلي «متى تستخدم / متى لا تستخدم» يعيش في ملفات SKILL.md الفردية، تُحمَّل فقط عندما يوجّه Claude إليها. الجدول هو الفهرس؛ والـ skills هي الفصول.
النمط 2: ملفات CLAUDE.md متداخلة لقواعد المجال
هذه الخاصية الحرجة التي يفوّتها معظم المطوّرين: ملفات CLAUDE.md المتداخلة في مجلّدات فرعية تُحمَّل بشكل كسول. تدخل في السياق فقط عندما يقرأ Claude ملفات في تلك الأشجار الفرعية.
تخطيط مستودعنا الآن يبدو هكذا:
statnive-workflow/
├── CLAUDE.md # 162 lines — global only
├── statnive/
│ ├── CLAUDE.md # PHP / WordPress plugin conventions
│ ├── src/
│ └── tests/
├── statnive-website/
│ └── CLAUDE.md # Astro / MDX / frontend conventions
└── jaan-to/
└── CLAUDE.md # AI framework conventionsعندما نكتب PHP لـ plugin، يُحمَّل statnive/CLAUDE.md تلقائيًا ويجلب ملاحظات WordPress Coding Standards، وقاعدة فرض $wpdb->prepare()، وقاعدة scoping الأصول الإدارية. عندما نكتب محتوى مدوّنة MDX، يُحمَّل statnive-website/CLAUDE.md مع اصطلاحات Astro وملاحظات أسلوب البيت. لا يتداخل أحدهما مع الآخر.
اقتطع هذا النمط نحو 2200 رمز من المحتوى «المرتبط أحيانًا فقط» من الجذر.
النمط 3: قواعد path-scoped في .claude/rules/
الآلية الثالثة هي .claude/rules/ — ملفات قواعد بـ frontmatter من YAML تستطيع أن تعلن المسارات التي تنطبق عليها:
---
paths: ["statnive-website/src/**/*.tsx", "statnive-website/src/**/*.astro"]
---
Use Tailwind utilities scoped under `#statnive-app`. Never import the default
Tailwind bundle — it restyles the WordPress admin chrome.القواعد التي لها حقل paths: تُحمَّل بشكل مشروط — فقط عندما يعمل Claude مع ملفات مطابقة. القواعد بدون حقل paths: تُحمَّل بدون شرط، لذا نُبقي تلك في عدد صغير جدًا (قواعد الخصوصية، قواعد الأمن، اصطلاحات commit).
نقلنا نحو 1800 رمز من اصطلاحات خاصّة بالأطر من جذر CLAUDE.md إلى قواعد path-scoped تحت .claude/rules/. لا تزال تُطلَق بشكل موثوق عند الحاجة، ولا تكلّف شيئًا عند عدم الحاجة.
النمط المضاد الذي أزلناه: @-Imports
كان CLAUDE.md الأصلي لدينا يحتوي على ثلاث @-imports:
@jaan-to/docs/best-practices.md
@jaan-to/context/tech.md
@jaan-to/outputs/ROADMAP.mdتبدو مرتّبة. وهي فخّ. صيغة @ تحمِّل بشكل متكرّر المحتوى الكامل لكل ملف هدف في كل جلسة، حتى خمسة مستويات في العمق. كانت استيراداتنا الثلاث وحدها تضيف نحو 6000 رمز من الحمل الدائم لمحتوى كان النموذج يحتاجه ربما في جلسة من كل عشرين.
استبدلنا كل واحد بمؤشّر:
For architectural context see `jaan-to/context/tech.md`.
For the current roadmap see `jaan-to/outputs/ROADMAP.md`.يقرأ Claude هذه المسارات عندما يحتاج إليها فعلًا — عبر أداة Read، عند الطلب. صفر كلفة أساسية، وذات النتيجة العملية.
ما يزال يعيش في ملف الجذر
بعد القصّ، يحتوي CLAUDE.md بحجم 162 سطرًا في الجذر بالضبط على:
| القسم | الأسطر | لماذا بقي |
|---|---|---|
| فلسفة المنتج (8 مبادئ من البحث) | 28 | تشكّل كل قرار؛ يجب أن تؤثّر في كل الجلسات |
| خريطة مساحة العمل | 18 | توجيه بنظرة واحدة، يُحمَّل لأي جلسة |
| قواعد الخصوصية (غير قابلة للتفاوض) | 16 | invariants حرجة — cookies، IPs خام، salts، SHA-256 |
| قاعدة scoping الأصول الإدارية | 22 | عضّتنا من قبل، تنطبق على نطاق واسع |
| سياسة commit (لاحقة co-authored-by محظورة) | 8 | اصطلاح git عام |
قاعدة سير عمل /simplify | 18 | فرض بوابة الجودة لدينا |
| جدول محفّزات الـ skill | 32 | يحلّ محل ~30 قسم نثري لكل skill |
| المسارات الرئيسية (مؤشّرات، لا استيرادات) | 20 | مراجع من سطر واحد إلى المستندات |
كل شيء آخر إمّا انتقل إلى CLAUDE.md متداخل، أو قواعد path-scoped، أو أجسام skill فردية.
ما لم نحسّنه
تحفّظات صادقة، نفس النمط الذي يتّبعه باقي السلسلة:
~/.claude/CLAUDE.mdعلى مستوى المستخدم خارج سيطرتنا. لكل من مهندسينا تكوينه العام الخاص، وتلك تُحمَّل فوق ملف المشروع. تشير الأبحاث إلى ذلك كمصدر شائع للحمل الخفي — CLAUDE.md عام يحتوي على «تذكّر تشغيل الاختبارات قبل commit» فوق سير عمل على مستوى المشروع يفعل ذلك بالضبط، يكلّف رموزًا دون إضافة إشارة. طلبنا من أعضاء الفريق تدقيق ملفاتهم. ملفك ربما يستحق نظرة.- ليس لدينا بوابة CI على حجم CLAUDE.md في الجذر بعد. تقترح الأبحاث إفشال PR إذا تجاوز CLAUDE.md في الجذر + أي
@-imports~2500 رمز. نفرض ذلك بفحوصات/contextنقطية. بوابة CI على خارطة الطريق. - علامتا
IMPORTANTوYOU MUSTمغريتان. Anthropic تشغّل داخليًا ملفات CLAUDE.md عبر مُحسِّن الـ prompt الخاص بها وتستخدم علامات التشديد للقواعد الحرجة. نستخدمها بحذر — كل واحدة هي حمل دائم، لذا نحتفظ بها لقواعد الخصوصية (لا cookies، لا IPs خام) وسياسة commit (لا لاحقة co-authored-by).
خطوة القياس التي لا يمكنك تخطّيها
إذا كنت تدقّق CLAUDE.md الخاص بك، فالأمر الواحد الذي يهمّ هو /context. شغّله في بداية جلسة جديدة تمامًا، قبل أي prompts. يُقسّم استخدامك للسياق حسب المصدر: prompt النظام، الأدوات، الذاكرة (هذا CLAUDE.md)، metadata الـ skills، وschemas أدوات MCP.
الأرقام التي نستهدفها لجلسة بنافذة 200K:
| المصدر | الهدف | السقف الصارم |
|---|---|---|
| CLAUDE.md في الجذر + قواعد غير مقيّدة | ≤ 1500 رمز | 2500 |
| metadata الـ Skill | ≤ 2500 رمز | 5000 |
| schemas أدوات MCP (مع Tool Search) | ≤ 3000 رمز | 8000 |
| stdout الـ hook (SessionStart، UserPromptSubmit) | 0 رمز | 300 لكل hook |
إذا تجاوز /context لديك أيًا من هذه بأكثر من ~50%، فلديك المشكلة ذاتها التي كانت لدينا. الإصلاحات هي الأنماط الثلاثة أعلاه بالإضافة إلى MCP Tool Search.
لماذا يهمّ هذا للأشخاص الذين يديرون Statnive
CLAUDE.md لدينا علني في مستودع Statnive على GitHub — للسبب ذاته الذي جعل خط الاختبار لدينا علنيًا. إعداد جذر مضغوط يعني جلسات أسرع وعمليات تشغيل أرخص ونموذجًا يقرأ فعلًا ما يهمّ بدلًا من أن يغرق في مادة مرجعية «متاحة دائمًا، نادرًا ما تُحتاج». تتراكم تلك الكفاءة لتصبح الشيء ذاته الذي يهمّ مستخدمينا: plugin يُشحن بكثرة ويبقى تحت ميزانية tracker بحجم 5KB.
جرّب Statnive
تحليلات WordPress بمنطق الخصوصية أولاً، مبنية بفريق يأخذ ميزانيات الرموز بنفس جدّية ميزانيات الأداء. ثبّت Statnive مجانًا من WordPress.org — بياناتك تبقى على خادمك، وممارساتنا الهندسية تبقى على GitHub لأي شخص يريد تدقيقها.