AI خزنة
أدلة

كيف تجعل الذكاء الاصطناعي يلتزم بقواعد مشروعك: CLAUDE.md وكيرسر

شرح CLAUDE.md وقواعد مشروع كيرسر وAGENTS.md، مع مثال قصير يمكنك تكييفه

ATAI Khazna Team6 دقيقة قراءة

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

ما هو ملف القواعد

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

لكنه إرشاد لا قفل. يوضح توثيق أنثروبيك أن كلود يتعامل مع CLAUDE.md بوصفه سياقا لا إعدادا ملزما. فإذا كان هناك أمر يجب ألا يحدث أبدا، فادعم القاعدة بضابط فعلي أيضا، مثل خطاف (hook) أو إعداد أذونات أو فرع محمي.

ملف CLAUDE.md في كلود كود

يقرأ كلود كود ملفات CLAUDE.md في بداية كل جلسة. وبحسب توثيق الذاكرة الرسمي، هذه أهم المواقع:

  • ./CLAUDE.md أو ./.claude/CLAUDE.md داخل المشروع، ويشارك مع الفريق عبر جيت.
  • ~/.claude/CLAUDE.md في مجلدك الرئيسي، لتفضيلاتك الشخصية في كل مشاريعك.
  • CLAUDE.local.md في جذر المشروع، لملاحظاتك الخاصة بمشروع واحد، مع إضافته إلى .gitignore.

نفذ /init داخل كلود كود ليكتب مسودة CLAUDE.md مما يجده في شيفرتك، بما فيها أوامر البناء والاختبار. ويمكن لملف CLAUDE.md أن يستدعي ملفات أخرى بصيغة @path/to/file، أما القواعد الخاصة بجزء من الشيفرة فمكانها .claude/rules/. وتوصي أنثروبيك بأن يبقى كل ملف CLAUDE.md دون 200 سطر تقريبا، لأن الملفات الأطول تستهلك سياقا أكثر ويقل الالتزام بها.

قواعد المشروع في كيرسر

يحفظ كيرسر قواعد المشروع في مجلد .cursor/rules، لكل قاعدة ملف بامتداد .mdc، كما يشرح توثيق القواعد في كيرسر. يبدأ كل ملف بترويسة قصيرة فيها description، وglobs الاختيارية لأنماط الملفات، وalwaysApply. وتحدد هذه الحقول هل تطبق القاعدة دائما، أم حين يرى الوكيل أنها مناسبة، أم على ملفات بعينها، أم فقط حين تذكرها بنفسك. وفي إعدادات كيرسر أيضا قواعد المستخدم لتفضيلاتك في كل المشاريع. أما ملف .cursorrules القديم في جذر المشروع فصيغة سابقة، ويوصي كيرسر باستخدام قواعد المشروع بدلا منه.

ملف AGENTS.md، الخيار المشترك

AGENTS.md صيغة مفتوحة: ملف Markdown عادي في جذر المشروع يعمل كدليل README موجه لوكلاء البرمجة. وهو عرف حقيقي واسع الانتشار، إذ يذكر موقعه أدوات متوافقة معه منها Codex من أوبن إيه آي، وJules وGemini CLI من جوجل، ووكيل البرمجة في GitHub Copilot، وكيرسر، وويندسيرف، وزد، ويذكر أن الصيغة صارت تحت رعاية مؤسسة Agentic AI Foundation التابعة لمؤسسة لينكس.

يقرأ كيرسر ملف AGENTS.md في الجذر وفي المجلدات الفرعية. أما الإصدارات الحديثة من كلود كود فتقرؤه حين لا يوجد CLAUDE.md في المشروع، وإذا وجد الملفان معا قرأ CLAUDE.md. فإذا كان فريقك يستخدم أكثر من أداة، فاحفظ المحتوى في AGENTS.md وأضف سطرا مثل @AGENTS.md إلى CLAUDE.md لاستدعائه. مصدر واحد للحقيقة أفضل من ملفين يبتعد أحدهما عن الآخر مع الوقت.

ماذا تضع فيه

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

اترك ما تستطيع الأداة رؤيته بنفسها، مثل قائمة كاملة بالملفات أو شيفرة يمكنها قراءتها مباشرة. واكتب كل قاعدة تعليمة قصيرة محددة، فعبارة «استخدم مكون Button الموجود في components/ui» أنفع من «حافظ على اتساق الواجهة».

مثال قصير

هذا ملف قواعد مختصر لتطبيق صغير مبني بـ Next.js مع قاعدة بيانات Postgres مستضافة، ويصلح أن يكون CLAUDE.md أو AGENTS.md:

  • # Project: bookings app
  • Stack: Next.js (App Router), TypeScript, Postgres, deployed on Vercel
  • Run: npm run dev | Test: npm test | Lint: npm run lint
  • Layout: app/ routes, components/ui shared UI, lib/ server helpers, db/migrations SQL
  • Conventions: reuse components/ui; never import server code into client components
  • Never: edit a migration that has already run; add a package without asking
  • Security: secrets only in environment variables; check the signed-in user in every server action
  • Before finishing: run lint and tests, then list the files you changed

ثمانية أسطر، وكل سطر منها يغير السلوك. هذا هو الهدف. ويمكنك كتابة القواعد بالعربية إن شئت، لكن إبقاء الأوامر وأسماء الملفات كما هي يمنع الالتباس.

اجعله قصيرا ومحدثا

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

أين تأتي المهارات

القواعد تحمل الحقائق التي تنطبق على كل مهمة، والمهارات تحمل خبرة لا تحتاجها إلا بعض المهام. في نموذج المهارات (Agent Skills) من أنثروبيك، المهارة مجلد فيه ملف SKILL.md يضم التعليمات، مع ملفات مرجعية اختيارية. لا يحمل في البداية إلا الوصف القصير للمهارة، أما التعليمات الكاملة فتحمل حين تتطلبها المهمة أو حين تستدعي المهارة باسمها. ونصيحة أنثروبيك أن تحول جزءا من CLAUDE.md إلى مهارة حين يتحول من حقيقة إلى إجراء.

تقسيم عملي: يقول ملف القواعد «ننشر على فيرسل ونشغل الاختبارات قبل كل commit»، وتحمل مهارة ما قائمة خطوات الإطلاق بالتفصيل. ومهارات كلود كود تتبع المعيار المفتوح Agent Skills. ويعرض دليلنا عن المهارات لتطبيقات Next.js وسوبابيز أمثلة لتقنيات شائعة.

خطوتك التالية

افتح مشروعك، ونفذ /init في كلود كود أو أنشئ AGENTS.md يدويا، ثم اختصره إلى الأسطر المهمة فقط. وإن كنت تبدأ من الصفر، فاتبع أولا دليل تطبيقك الأول مع كلود كود، ثم تصفح كتالوج المهارات لتجد خبرة جاهزة تناسب تقنياتك.

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

هل أستخدم CLAUDE.md أم AGENTS.md؟
إن كنت تستخدم كلود كود وحده فيكفيك CLAUDE.md. وإن كان فريقك يستخدم أيضا كيرسر أو Codex أو وكلاء آخرين، فاحفظ المحتوى المشترك في AGENTS.md واستدعه من CLAUDE.md بسطر @AGENTS.md ليبقى المصدر واحدا.
ما الطول المناسب لملف القواعد؟
أقصر ما يمكن. توصي أنثروبيك بأن يبقى كل ملف CLAUDE.md دون 200 سطر تقريبا، وكثير من المشاريع يكفيها أقل من ذلك بكثير. انقل الإجراءات الطويلة إلى مهارات أو قواعد خاصة بملفات معينة.
هل يلتزم الذكاء الاصطناعي بملف القواعد دائما؟
ليس دائما. ملف القواعد سياق وليس أداة إلزام. القواعد المحددة والموجزة يلتزم بها أكثر، وما يجب ألا يحدث أبدا ينبغي منعه أيضا بالخطافات أو الأذونات أو حماية الفروع.
ما الفرق بين القاعدة والمهارة؟
القاعدة حقيقة أو قيد ينطبق على كل مهمة ويحمل في كل جلسة. أما المهارة فخبرة مجمعة، مثل قائمة خطوات الإطلاق، لا تحمل إلا حين تحتاجها المهمة.
claude.mdcursoragents.mdskillsvibe coding