ملف CLAUDE.md والصلاحيات والـ Hooks: جهّز Claude Code لمشروعك قبل أول مهمة

كل جلسة جديدة مع Claude Code تبدأ وهو ما يعرف عن مشروعك شي: وش أمر تشغيل الاختبارات؟ ليش المجلد الفلاني ممنوع تلمسه؟ هل تستخدمون pnpm ولا npm؟ لو ما قلت له، بيخمّن. والتخمين في مشروع حقيقي يعني وقتاً ضائعاً في تصحيح أشياء كان ممكن ما تصير. الحل ثلاث طبقات إعداد، تسويها مرة وتستفيد منها كل يوم.

الطبقة الأولى: CLAUDE.md

ملف نصي بصيغة Markdown في جذر المشروع، يقرؤه Claude Code تلقائياً في بداية الجلسة. فكّر فيه كورقة تعريف تعطيها لمطوّر جديد أول يوم. وتقدر يكون عندك ملف عام في مجلد المستخدم لتفضيلاتك الشخصية، وملف لكل مشروع لقواعده.

• أوامر المشروع: التشغيل، البناء، الاختبار، الفحص (lint).
• البنية باختصار: وين الواجهة، وين الخادم، وين المكونات المشتركة.
• القواعد: نمط التسمية، مكتبة الحالة المعتمدة، ممنوع تضيف مكتبات بدون سؤال.
• المحاذير: ملفات مولّدة لا تُعدّل يدوياً، بيانات إنتاج لا تُلمس.
• قواعد خاصة مثل: النصوص العربية تستخدم «» للاقتباس، والتخطيط RTL.

أخطاء في كتابة CLAUDE.md

• ملف طويل جداً ينسخ التوثيق كامل — يستهلك السياق ويضيع المهم.
• تعليمات عامة مثل «اكتب كوداً نظيفاً» — ما تغيّر شي.
• معلومات قديمة ما تحدثت بعد تغيير البنية.
• قواعد متناقضة بين الملف العام وملف المشروع.

القاعدة: كل سطر في الملف لازم يجاوب على سؤال «وش الغلطة اللي بيسويها لو ما قرأ هذا؟».

الطبقة الثانية: الصلاحيات

Claude Code يطلب إذنك قبل تشغيل الأوامر وتعديل الملفات حسب الإعداد. بدل ما توافق على «npm test» مئة مرة، تقدر تضيف قواعد سماح في ملف الإعدادات settings.json للأوامر الآمنة المتكررة، وقواعد منع للأوامر اللي ما تبيها تنفذ أبداً.

• اسمح: أوامر القراءة والاختبار والفحص والبناء المحلي.
• اسأل: تثبيت مكتبات، أوامر git اللي تغيّر التاريخ، أي شي يلمس الشبكة.
• امنع: قراءة ملفات .env والمفاتيح، أوامر الحذف الشامل، النشر للإنتاج.

وافصل بين إعدادات المشروع المشتركة مع الفريق (تُرفع مع الكود) والإعدادات المحلية الخاصة بجهازك.

الطبقة الثالثة: الـ Hooks

التعليمات في CLAUDE.md «نصائح» قد تُنسى في جلسة طويلة. الـ hooks أوامر تنفذها الأداة نفسها تلقائياً عند أحداث معينة، مثل قبل استخدام أداة أو بعد تعديل ملف أو عند انتهاء المهمة. الفرق جوهري: الـ hook مضمون التنفيذ، مو معتمد على تذكّر النموذج.

• بعد كل تعديل ملف: شغّل المنسّق (formatter) على الملف.
• قبل تنفيذ أمر: امنع أي أمر يحاول يقرأ مجلد الأسرار.
• عند انتهاء المهمة: شغّل فحص الأنواع وبلّغ لو فيه أخطاء.
• إشعار على جهازك لما يحتاج Claude Code إذنك.

ابدأ صغيراً

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

هيكل مقترح لملف CLAUDE.md مختصر

هذا ترتيب عملي يناسب أغلب مشاريع الويب والتطبيقات، وتقدر تكتبه في أقل من نص ساعة:

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

وتذكّر إن الملف يُقرأ في كل جلسة، يعني كل سطر فيه يستهلك من السياق دائماً. لو عندك توثيق طويل مهم، ضعه في ملف منفصل واذكر في CLAUDE.md متى يُقرأ، بدل ما تحشره كاملاً. وراجع الملف كل ما تغيرت البنية أو أضفت أداة جديدة للمشروع.

في منصة أزهل الرقمية نشتغل بهذا الأسلوب في مشاريعنا، ومكتبة «سكيلز» المجانية على موقعنا فيها أدوات جاهزة تكمّل هذا الإعداد. تصفّحها، ولو تبي مساعدة في تجهيز بيئة تطوير لمشروعك تواصل معنا على واتساب.