اكتب CLAUDE.md كأنه دستور: محظورات، قواعد سلوك، قرارات افتراضية. 92 التزامًا في 5 أيام دون انحراف.
في 5 أيام، دفعتُ 92 commit ووضعتُ منتجًا في الإنتاج (github.com/defi-io/smarts). دون انفجارات، دون تراجعات، دون إعادة هيكلة كبرى. السبب ليس أن Claude عبقري. السبب هو ملف CLAUDE.md بطول 565 سطرًا في جذر المشروع.
هذه التدوينة عن كيفية كتابة CLAUDE.md يعمل كدستور، وما الذي يحدث بعد ذلك.
كثيرون يكتبون CLAUDE.md كأنه README — ما هو المشروع، كيف يُشغَّل. هذا هدر.
README مكتوب للبشر. CLAUDE.md مكتوب لـ Claude. يحمّله Claude تلقائيًا في بداية كل جلسة. أي أن كل سطر تكتبه هناك يصير شرطًا مسبقًا لكل قرار يتخذه بعد ذلك.
اكتبه على نمط README وستحصل على هذا: Claude يعرف تقريبًا ما هو المشروع، يعرف كيف يشغّل الاختبارات، لكنه يتخذ كل قرار تقني من الصفر.
اكتبه على نمط الدستور وستحصل على هذا: Claude يعرف أي الطرق مغلقة، أي الاتفاقيات إلزامية، إلى أي اتجاه يميل افتراضيًا عند كل مفترق، ومتى يجب أن يتوقف ويسأل.
الفرق: الأول سيُدخل لك "بالمناسبة" تبعية جديدة، يضيف طبقة تجريد، يعدّل Gemfile. الثاني لا يفعل.
المشروع الذي أبنيه يُسمى smarts.md — منصة تُولّد توثيقًا حيًّا وخوادم MCP للعقود الذكية. ملف CLAUDE.md فيه 565 سطرًا، مقسّم إلى:
1. هوية المشروع (5 أسطر)
2. جوهر المنتج (تعريف بسطر واحد + الفروق الهيكلية مع المنافسين)
3. حزمة التقنيات (قيود صلبة، بصيغة YAML)
4. قائمة المحظورات (بنود ❌ صريحة)
5. النطاق (حدود MVP الصلبة)
6. المعمارية (مع رسم ASCII)
7. هيكل المجلدات (مسؤولية كل ملف)
8. أعراف الكود في Ruby (مع مقتطفات افعل/لا تفعل)
9. استراتيجية التخزين المؤقت (في جدول)
10. متطلبات الاختبار
11. تفاصيل النشر
12. تدفق Git
13. قواعد استخدام Claude Code (تعليمات سلوك)
14. مراحل الـ 90 يومًا
15. المبادئ الجوهرية
لا قسم زخرفي. أدناه أختار بعضها وأشرح لماذا تُكتب هكذا.
قائمتي تبدو كهذه:
❌ لا خدمات TypeScript / Node.js
❌ لا ethers.js / web3.js
❌ لا Sidekiq (نستخدم Solid Queue)
❌ لا React / Vue / Svelte (نستخدم Hotwire)
❌ لا Redis (يغطي Solid Cache / Solid Queue / Solid Cable كل شيء)
❌ لا عقود غير مُتحقّق منها (فقط المُتحقّقة على Etherscan)
❌ لا Solana / Bitcoin / Move (فقط EVM)
هذا مشروع Web3. الافتراضي في عالم Web3 هو TypeScript + ethers.js + Redis + React. أنا أسير عكس التيار. لي أسبابي، لكن Claude لا يعرفها. بدون قائمة محظورات، سيعتمد Claude على "الحس الصناعي العام" المدفون في بيانات تدريبه — وذلك يعني تقريبًا بشكل مؤكد مسار TypeScript.
مع وجود القائمة، يتوقف Claude عن السؤال "هل نضيف خدمة Node لتشغيل web3.js؟". هذا الطريق مغلق افتراضيًا.
المفتاح: كل بند يجب أن يكون صريحًا ومطلقًا. لا تكتب "حاول تجنّب TypeScript". اكتب "لا TypeScript". أي غموض سيقرأه Claude على أنه قابل للتفاوض.
الكتلة الكبيرة الأخيرة في CLAUDE.md هي "قواعد استخدام Claude Code":
### عندما أقول "ابدأ في X"
1. تحقق أولًا إن كانت قيود CLAUDE.md تسمح بهذا النهج
2. ثم ابحث عن تنفيذ ذي صلة في الكود الحالي (لا تعد اختراع العجلة)
3. قبل كتابة الكود، افتح فرعًا (branch) جديدًا
4. بعد الانتهاء من التنفيذ، شغّل الاختبارات
5. لا تعمل commit تلقائيًا — حين يُكتب الكود وتمر الاختبارات، توقف وأبلغ.
انتظر حتى أقول "commit" صراحة
### عندما أقول "لديّ فكرة"
لا تكتب الكود فورًا. أولًا:
1. تأكد من الفهم (أعد الصياغة)
2. قيّم النهج إزاء قيود CLAUDE.md
3. أشر إلى المشاكل المحتملة أو البدائل الأفضل
4. انتظر تأكيدي قبل التنفيذ
### عند مواجهة مفترق تقني
حين لا يحدّد CLAUDE.md:
1. الافتراضي: الخيار الأقرب إلى Rails native
2. الافتراضي: الخيار بأقل عدد من التبعيات
3. الافتراضي: الخيار الذي يُسرّع تكرار المطوّر المنفرد
4. عند الشك، توقف واسأل
هذا الجزء يفوق "استخدم snake_case" بعشر مرات أهمية.
نمط الكود يتعلّمه Claude بقراءة الكود. لكن "متى يتوقف ويسأل"، "حين يسمع 'لديّ فكرة' يعيد الصياغة قبل أن يكتب كودًا" — هذه أنماط سلوك. الكود وحده لا يعلّمها.
السطر الأهم: إلى أي اتجاه يميل افتراضيًا عند المفترق. هذه القاعدة وحدها تحدّد ما يفعله Claude حين تكون غائبًا (مثلًا حين تقول فقط "ابدأ في X" وتنصرف). اكتبها بوضوح، فتأمن جانبه ليعمل دون إشراف.
في أعلى CLAUDE.md سطر:
هذا الملف هو "المصدر الأول" للمشروع. يُحمَّل تلقائيًا في بداية كل جلسة Claude Code. حين تغيّر القرارات التقنية، غيّر هنا أولًا؛ ثم يلحق الكود.
هذا عقد سير عمل. حين أقرر تغيير اختيار تقني — مثلًا ترقية نموذج الذكاء الاصطناعي الرئيسي من gpt-5-mini إلى gpt-5 — الخطوة الأولى ليست تعديل initializer. الخطوة الأولى هي تعديل هذه الفقرة في CLAUDE.md:
ai:
fast: gpt-5-mini # قبل
fast: gpt-5 # بعد
ثم أترك Claude يعيد قراءة CLAUDE.md ويوائم الكود.
لماذا؟ لأنك إذا غيّرت قيمة في الكود وتأخّر CLAUDE.md، فعند قراءة CLAUDE.md لاحقًا سيرى Claude القيمة القديمة و"تكرّمًا منه" يُعيد كودك إلى ما كان عليه. جذر النزاع نقطة فشل واحدة — CLAUDE.md تخلّف عن المواكبة. الدستور المتأخر عن الواقع هو ما يُشعل الحروب الأهلية.
أن تتعامل مع CLAUDE.md كدستور يعني: يسبق الكودَ دائمًا.
smarts.md، 5 أيام، 92 commit:
متوسط عمر الـ PR: 30 دقيقة. لا إعادة هيكلة كبرى. لا "هذا الاتجاه خطأ، تراجع".
ليس لأن Claude سحري. بل لأنه في كل جلسة كان يجري على سكة من 565 سطرًا. كان يعرف ألّا يُدخل TypeScript، يعرف أن Solid Queue هو الطابور الافتراضي، يعرف أن دوال view مُخزّنة 60 ثانية، يعرف أن كل service يجب أن يطبّق ميثود صنف call، يعرف أن ينتظر تأكيدي قبل الـ commit.
انزع نصف هذه القيود وستحصل على: 30 دقيقة يوميًا في شرح "لماذا لا نستخدم X"، و5 دقائق في مراجعة التبعية التي أضافها "بالمناسبة"، وملف Gemfile يتفكّك تدريجيًا.
لا تبدأ من ملف فارغ. ابدأ من القرار الأخير الذي آلمك.
إن كان آخر ما فعله Claude هو "إدخال تبعيات جديدة باستمرار"، اكتب قائمة المحظورات.
إن كان "يغيّر المعمارية على هواه"، اكتب رسم المعمارية + "إضافة ميكروسيرفس، تغيير قاعدة البيانات، إلخ تتطلب تأكيدًا".
إن كان "لا يكتب اختبارات"، اكتب "ما يجب أن يخضع لاختبار وحدة إلزامي".
إن كان "يُجري commit بعدوانية"، اكتب "لا git commit تلقائي، انتظر تعليمًا صريحًا".
كلما آلمك شيء، أضف بندًا. ولا تكتب غيره الآن.
بعد ثلاثة أشهر سيكون لديك CLAUDE.md بطول 500 سطر، خلف كل سطر منه "لا أريده أن يفعل هذا مجددًا" ملموس. هذا الملف يهزم أي قالب، لأنه مُعاير بدقة لمشروعك، لسير عملك، لفريقك (حتى لو كنت وحدك).
الدستور لا يُكتب دفعة واحدة. يتبلور من نزاعات محدّدة، واحدًا تلو الآخر.
المصدر: github.com/defi-io/smarts