ملف CLAUDE.md يغيّر القرارات لا يصف المشروع
معظمها README باسم ملف مختلف. واختبار كل سطر هو هل يستطيع وكيل التصرف مختلفاً بسببه، وقسمان يبرران الملف وحدهما.
CLAUDE.md يقع في جذر المشروع ويقرؤه Claude Code في بداية كل جلسة. ومعظم ما نراه منها README باسم ملف مختلف: فقرة عما تفعله الشركة، وقائمة أوامر، ولا شيء يغيّر قراراً واحداً. والنافع أقرب إلى مجموعة تصحيحات دائمة، مكتوبة كي لا يعود الخطأ الذي أصلحته في الأسبوع الأول في الرابع.
اكتب القرارات لا الوصف
واختبار كل سطر هو هل يستطيع وكيل أن يتصرف مختلفاً بسببه. فجملة تشرح أن الشركة تبني مواقع لعملاء رعاية صحية لا تغيّر شيئاً. وجملة تقول إن لا صفحة يجوز أن تحمل إحصائية عميل ما لم تظهر في ملف مصدر مسمّى تغيّر ما يُكتب في كل صفحة. فالأولى سياق والثانية قيد، والثانية وحدها تكسب موضعها.
ما ينتمي إليه في مشروع موقع
| القسم | لماذا يكسب موضعه |
|---|---|
| المنصة والإصدارات | الإطار بإصداره الرئيسي، وأسلوب التنسيق، وأي شيء يجب ألا يثبّته الوكيل. فبلا الإصدار يكتب الواجهة التي دُرِّب عليها. |
| نموذج المحتوى | أين يسكن النص وأي الملفات بيانات لا كود. وهذا ما يمنع الوكيل من تثبيت عنوان في مكوّن. |
| سياسة الادعاءات | ما يجوز تأكيده في صفحة وما يحتاج مصدراً. وهو أعلى قسم قيمةً، فالتفاصيل المخترعة مكلفة في العثور لاحقاً. |
| أسلوب البيت | الترقيم والنبرة والكلمات التي لا تستخدمها. رخيص القول وإلا يُصحَّح للأبد. |
| التحقق | أي أمر يثبت نجاح تغيير. فبدونه سيدّعي الوكيل النجاح من بناء نظيف، وذلك لا يثبت شيئاً عن الصفحة. |
| الفخاخ المعروفة | العلل التي أنتجها هذا المستودع مرتين بالفعل. وهذا هو القسم الذي ينمو والذي يسدد. |
أبقه قصيراً بما يكفي ليُقرأ
ويُحمّل في بداية كل جلسة، فكل سطر مدفوع في كل دور. والملف الذي نما إلى ألف سطر من نصائح متراكمة يميّع العشرين سطراً التي تهم. فقلّمه كما تقلّم مجموعة اختبارات: فحين لا تمنع قاعدة شيئاً لثلاثة أشهر، كانت توثيقاً لا قيداً. ويبني Claude Code أيضاً ذاكرة تلقائية أثناء عمله.
حدّد نطاق القواعد حيث تنطبق
ومستودع أحادي فيه موقع تسويقي وتطبيق ومكتبة مكوّنات ليس له مجموعة أعراف واحدة. والملفات المتداخلة تُقرأ لجلسات في مجلدها أو تحته، فقواعد الموقع التسويقي تستطيع الجلوس معه بدل تقييدها باستثناء في ملف جذر واحد. وإن كان للمستودع AGENTS.md لوكلاء برمجة آخرين، فيستطيع Claude Code قراءته بدلاً منه.
ما لا ينتمي
- أي شيء سري. فهو ملف في المستودع ويُقرأ في السياق في كل جلسة.
- وسجل تغييرات. فينمو بلا حد ولا شيء منه يغيّر قراراً.
- وأي شيء قابل للفرض بأداة. فقاعدة تنسيق تنتمي إلى المنسّق وقاعدة فحص إلى الفاحص، حيث تنطبق سواء قرأ أحد الملف أم لا.
- وتعليمات تنطبق أحياناً فقط. فتلك مهارة، تُستدعى عند الصلة، لا تكلفة دائمة في كل جلسة.
وسير العمل المحيط في بناء موقع بـClaude Code، والفخاخ الجديرة بالكتابة في قسم الفخاخ المعروفة في مشروع ويب مجموعة في ما تفحصه قبل أن تصدق أن الوكيل بناه.
مثال عملي، مختصر
ما يلي شكل ملف حقيقي، بإزالة تفاصيل المشروع. والمقصد النسبة: فكل سطر تقريباً قاعدة بنتيجة، والوصف الوحيد الموجود هو الجملة اللازمة لجعل القواعد ذات معنى.
- المنصة: الإطار وإصداره الرئيسي، وأسلوب التنسيق، وقائمة مسمّاة بما لا يُثبَّت.
- المحتوى: كل سلسلة تسكن في طبقة البيانات. والعنوان المثبّت في مكوّن عيب لا اختصار.
- الادعاءات: لا إحصائية ولا اسم عميل ولا شهادة تظهر ما لم توجد في ملف مصدر مسمّى. وإن لزم رقم وغاب، فاترك الجملة.
- الأسلوب: الترقيم والكلمات التي لا يستخدمها البيت، مذكورة مرة كي لا تُصحَّح أسبوعياً.
- التحقق: الأمر الدقيق الذي يثبت نجاح تغيير، والملاحظة الصريحة أن بناءً نظيفاً لا يثبته.
- الفخاخ: العلل التي أنتجها هذا المستودع من قبل، كل منها مع الفحص الذي يمسكها.
اكتب قواعد تفشل بصوت
والقاعدة المصاغة تفضيلاً تُوزن مقابل اعتبارات أخرى وتخسر أحياناً. والمصاغة شرطاً لا تخسر. ففضّل لا نشحن صفحة بلا رابط قانوني أبداً على حاول تذكّر الروابط القانونية، وحيث يمكن جعل قاعدة ميكانيكية، فانقلها خارج الملف كلياً إلى فحص يُفشل البناء. فالملف لما لا تستطيع أداة تقريره.
الإعدادات رافعة منفصلة
والتعليمات ليست أذونات. فأي الأوامر تُشغَّل دون سؤال، وأي المجلدات قابلة للوصول، وأي الأدوات متاحة، تنتمي إلى الإعدادات لا إلى نثر يطلب بلطف. والفرق التي تحاول فرض حد بكتابته في CLAUDE.md كتبت طلباً. والتي وضعته في الإعدادات كتبت قاعدة. ولكليهما موضع، وخلطهما هو كيف ينتهي مشروع بملف طويل لا يتبعه أحد.
موضعان يبلغهما هذا الملف ويسهل تفويتهما. فالوكيل الفرعي يبدأ وتعليماتك محمّلة إلّا إن أسقطتها عن قصد، فالقاعدة المكتوبة هنا تحكم العمل المفوّض أيضاً، وهذا أهمّ مما يبدو عند تقسيم بناء كبير: ما يُفوَّض للوكلاء الفرعيين يبيّن أين يقع ذلك الحدّ. والقاعدة التي يجب أن تصحّ لا أن تُقرأ فقط ليس موضعها النثر إطلاقاً، وهذه حجّة الـhooks التي تُحكِم مستودع موقع.
