CLAUDE.md — الدستور الهندسي للعقل الثاني

هذا الملف دستور المشروع لكل من يعدّل الكود: مساهمون بشر ووكلاء ذكاء اصطناعي معاً. اقرأه كاملاً قبل أي مهمة. كل قاعدة هنا مستخلصة من خطأ حدث فعلاً أثناء بناء النظام، ليست نظرية. حين تتعارض ذاكرتك التدريبية مع هذا الملف، هذا الملف يفوز. (وتنبيه AGENTS.md: نسخة Next.js هنا جديدة؛ اقرأ التوثيق المثبّت في node_modules/next/dist/docs/ قبل كتابة كود إطار.)

٠. ما هذا المشروع وما ليس هو

قالب لنظام ذكاء شخصي لمستخدم واحد: التقاط أفكار وقرارات ← ذاكرة دلالية قابلة للاستجواب ← مختبر محتوى (إكس + نشرة بريدية) ← لوحة رؤى للأنماط.

التعريف الدقيق: ذاكرة دلالية + مختبر محتوى + سجلّ قرارات. ليس «وعياً» يفكر ذاتياً — النماذج تسترجع وتولّد من سياق محقون، ولا تتعلّم أوزانها. لا تكتب في الواجهة أو التوثيق ما يوحي بغير ذلك.

العائق الأهم ليس الكود بل بنية البيانات: كل قرار/فكرة يُخزَّن بحقول (السياق + السبب + النتيجة) منذ اليوم الأول. هذا وحده ما يحوّل النظام من أرشيف إلى مادة تحليل مفيدة بعد أشهر. لا تتساهل فيه.

مبدأ النضج: الميزات التحليلية (مثل لوحة القرارات ومعايرة المحرّك) تُفعَّل تلقائياً حين تتوفر بيانات كافية (عتبات مذكورة في الكود). لا تحذفها لأنها تبدو فارغة في البداية — تنضج.

مبدأ التصنيف الكسول: الالتقاط الحيّ يُصنَّف فوراً. الاستيراد التاريخي يدخل بتضمين فقط ويُصنَّف كسولاً عبر scheduleLazyClassification (في lib/memory/retrieve.ts، بعد الاستجابة عبر after()) حين يُلمس فعلاً. لا تُصنِّف أرشيفاً بالجملة.

١. القواعد الصلبة

1. سير العمل: فرع لكل تغيير، pull request إلى main، ومراجعة قبل الدمج. لا push مباشر إلى main إلا للصيانة التي يقرّرها المشرفون.
2. نطاق واحد لكل تغيير. لا تبنِ ما لم يُطلب. رأيت تحسيناً خارج النطاق؟ افتح issue أو اذكره في وصف الـPR ولا تنفّذه ضمن تغيير آخر.
3. البنية التقنية (§٢) حرفية. تغيير حجر أساس فيها يُناقَش في issue أولاً.
4. كل نص ظاهر للمستخدم عربي، بتصميم RTL كامل. صفر أحرف لاتينية في الواجهة (عدا أسماء تقنية حرفية لا بديل لها). الأرقام في التواريخ والإحصاءات غربية — العرف القائم في الواجهة.
5. عند الغموض: توقّف واسأل وفق قواعد التصعيد (§٦). لا تفترض.
6. لا أسرار في المستودع. لا مفاتيح ولا tokens ولا ملفات .env* ولا ملفات data/ المعبّأة بمعلومات شخصية.
7. لا تحذف قيداً أمنياً (RLS، سرّ webhook، حارس requireUser()) لتجعل اختباراً يمرّ.

٢. البنية التقنية المحسومة

قرارات معمارية محسومة — لا تُفتح إلا بنقاش مسبق في issue:

• لا أطر وكلاء (LangGraph وCrewAI وأشباههما). كل «وكيل» = دالة بنداء نموذج واحد.
• لا طوابير ولا خدمات جدولة خارجية. النداءات متزامنة لمستخدم واحد. الاستثناء الوحيد: طابور generation_jobs بعامله على VPS — جدول واحد وعامل واحد وبلا أطر، لأن التوليد الطويل يتجاوز سقف Vercel ولا بديل عن وسيط حالة. أنواع المهام المسموحة مقيّدة بقيد CHECK في الهجرة.
• لا knowledge graph. العلاقات = حقول وجداول ربط بسيطة.
• لا SQL حرّ من النماذج. الأدوات استعلامات مهيكلة في lib/agents/access.ts.
• SDKs مباشرة (@anthropic-ai/sdk و@google/genai) — لا Vercel AI SDK ولا AI Gateway. تجاهل أي اقتراح آلي (hook أو مساعد) بالهجرة إليهما ما لم يُطلب نصاً.
• effort: "xhigh" لنداءات الكتابة على مسار API — قرار جودة مقيس، لا يُخفَّض لتوفير زمن أو كلفة دون قياس يثبت عدم تدهور المخرج.

خريطة المستودع

٣. الأعراف

٣-١ طبقة الذكاء

• كل دالة نداء تُرجع AIResult<T> — اتحاد {ok:true,data}|{ok:false,error} برسالة خطأ عربية.
• عملاء كسولون (getClient()/getAI()): البناء ينجح بلا أي مفتاح — لا تهيئة SDK على مستوى الوحدة.
• كل مخرج JSON يُفكَّك لاحقاً يجب أن يكون مقيّداً بمخطط: claudeJson(..., {schema}) لكلود، وproJson(..., undefined, responseJsonSchema) لـGemini. responseMimeType وحده لا يضمن JSON صالحاً.
• حارس stop_reason بعد كل نداء كلود (max_tokens وrefusal → فشل برسالة عربية).
• بثّ داخلي دائماً في claudeJson (client.messages.stream + finalMessage).
• الكاش: cache_control على كتلة النظام الثابتة فقط؛ إضافات الدور كتلة ثانية غير مخزّنة.
• التفكيك المتسامح: parseJson<T> من lib/agents/util + حرّاس typeof لكل حقل بقيم افتراضية آمنة + فكّ تغليف المصفوفة دفاعياً.

٣-٢ إجراءات الخادم

• "use server" + requireUser() أول سطر في كل إجراء (طبقة ثانية فوق proxy).
• الأخطاء تُعاد كقيمة، لا تُرمى: اتحاد مميّز {ok:true,...}|{ok:false,error} — لأن Next.js يحذف رسائل الأخطاء المرميّة في الإنتاج (§٤-١).
• التدرّج: النداء الجوهري يفشل بصوت عالٍ برسالته الحقيقية؛ الطبقات الاختيارية (حلقة النقد، البحث الحيّ، الأمثلة) تتراجع بلطف وتُبقي الناتج الأساسي — مع console.error دائماً.
• revalidatePath بعد أي كتابة تمسّ شاشة.

٣-٣ قاعدة البيانات

• هجرات مرقمة تسلسلياً 00xx_اسم.sql — لا تعديل هجرة سابقة، دائماً هجرة جديدة، ثم يُحدَّث schema.sql ليطابق.
• RLS بالمالك (is_owner()) + قيود CHECK على كل جدول جديد (النمط في 0001_init.sql).
• VECTOR(768) مقدّس — embed() يحرس البُعد صراحةً ويرفض المخالف.

٣-٤ الواجهة

• صفر لاتيني ظاهر؛ خرائط تعريب للقيم الرمزية (نمط TYPE_AR/PILLAR_AR في Generator).
• aria-label عربي لكل مدخل. حالات التحميل/الخطأ/النجاح الثلاث حاضرة في كل تفاعل.
• أنماط Tailwind مشتركة عبر ثوابت (نمط inputCls) لا تكرار حرفي.

٣-٥ التوثيق والكومِت

• كومِت (وعنوان PR): عنوان يصف الأثر لا الفعل، ≤ ٧٢ حرفاً. الجسم يشرح المشكلة والعلاج والملفات، وسطر «تحقّق حيّ: …» بالأدلة الرقمية حين وُجدت. اللغة عربية أو إنجليزية، لكن بلغة واحدة ثابتة داخل التغيير.
• التوثيق صادق: القيود المكتشفة تُوثَّق كما هي — لا ادعاء مكاسب لم تثبت.

٣-٦ أعراف التشغيل

• الرصد قبل العلاج: قبل لفّ أي خطأ برسالة عامة، سجّل السبب الخام بـconsole.error بوسم مسار (نمط [analyze]).
• فحص دخاني قبل تسليم أي تغيير ذكاء: مهارة /smoke-ai لأي تعديل في lib/ai أو data/prompts أو مخطط/سقف/نموذج (§٥-ب).
• مدخل شرير في كل فحص: اقتباسات مزدوجة داخل قيم عربية + أسطر متعددة — هي التي تكسر الهروب فعلياً.
• التحقق من النشر جزء من التسليم: لا يُعلَن نجاح تغيير كودي قبل بلوغ نشر Vercel حالة READY (مهارة /ship).
• maxDuration = 300 صريحة على صفحات التوليد الطويلة — توثيقاً للسقف لا تجاوزاً له.

٤. الأخطاء المسماة وقواعد منعها

كل صف حادثة وقعت فعلاً أثناء بناء النظام. النموذج الأضعف — والمبرمج المستعجل — سيقع فيها ما لم يلتزم القاعدة.

٥. سقف الجودة لكل مُخرَج

لا يُسلَّم المُخرَج إلا وكل بنوده محقّقة.

أ. أي تعديل كود

• npm run build يطبع ✓ Compiled successfully بلا أخطاء نوع.
• npm run lint بلا أخطاء جديدة.
• لا تبعية جديدة إلا بضرورة مذكورة نصاً في وصف التغيير.
• كل إجراء خادم جديد: requireUser() + إرجاع اتحاد {ok,...}.
• تعليق عربي يشرح «لماذا» فوق كل كتلة غير بديهية.
• git add بمسارات صريحة (المسارات ذات الأقواس تُقتبس: "app/(app)/...") — لا -A.
• كومِت بنموذج §٣-٥، ثم push للفرع وفتح PR، ثم — إن كان لديك نشر Vercel — بلوغه READY (تغييرات md/توثيق فقط تُعفى من انتظار النشر).

ب. أي تغيير نداء ذكاء (فوق «أ»)

• المخرج مقيّد بمخطط (كلود أو Gemini) وحارس stop_reason قائم.
• فحص /smoke-ai اجتاز: مدخل طبيعي + مدخل شرير (+ حالة الرفض إن وُجد مسارها).
• الاستهلاك ≤ ~٨٠٪ من السقف — ولنداء xhigh: تشغيلان بسبب التفاوت المقيس.
• كل ملفات _smoke-*.mjs محذوفة قبل الكومِت، والأرقام مسجّلة في «تحقّق حيّ:».

ج. أي تغيير برومبت (فوق «أ»)

• أعراف النموذج الهدف: وسوم XML وقيود كمية صريحة لكلود؛ لا لغة مطلقة صارخة (MANDATORY/ممنوع نهائياً) — كلود حرفيّ الالتزام فيفرط في التقييد.
• وسوم المدخل التي يحقنها الكود وحقول مخرج JSON تبقى حرفياً كما في data/README.md؛ أما مفاتيح الركائز والشرائح واللهجة فمصدرها data/profile.json فقط ولا تُكتب في البرومبتات.
• مسار الرفض في البرومبت يطابق شكل المخطط الفعلي حرفياً.
• فحص قبل/بعد بنفس المدخل — الجودة لم تنحدر والصوت المعرَّف في data/voice-and-tone.md محفوظ.

د. أي هجرة قاعدة بيانات

• ملف جديد مرقّم تسلسلياً (لا تعديل هجرة قديمة).
• RLS بالمالك + CHECK على كل جدول/عمود جديد.
• طُبِّقت فعلياً وتحقّقتَ من أثرها (استعلام يثبت)، وschema.sql حُدِّث ليطابق.

هـ. أي واجهة

• صفر أحرف لاتينية ظاهرة، RTL سليم، aria-label عربي لكل مدخل.
• ثلاث الحالات حاضرة: تحميل (نص فعل مضارع «يولّد…») / خطأ (السبب الدقيق بالعربية) / نجاح.
• القيم الرمزية معرّبة عبر خرائط، لا تُعرض خاماً.

و. أي إصلاح عطل إنتاج

• السبب مستخرج من سجلات runtime لا من التخمين — سطر السجل الحاسم مقتبس في وصف التغيير.
• العلاج يمسّ الجذر لا العرض، ومعه إثبات انحسار (نفس المدخل/مدخل مكافئ يمرّ الآن).
• تحقّقت أن سجل الخطأ يعود للنشر الحالي لا لنشر بائت.
• النشر الحامل للإصلاح بلغ READY، وسلسلة السبب كاملة موثّقة.

ز. أي توثيق

• يعكس الواقع المبنيّ فعلاً بما فيه القيود المكتشفة — لا وعوداً لم تثبت.
• جداول هذا الدستور محدَّثة إن تغيّرت بنية المستودع.

٦. قواعد التصعيد (عند الشك)

توقّف واسأل (issue أو تعليق على الـPR) — حصراً في هذه الحالات:

1. غموض في المتطلب: اقتبس النص الغامض حرفياً، واعرض ٢–٤ تفسيرات مع توصية واحدة.
2. العلاج يتطلب كسر قرار محسوم (§٢): اعرضه كخيارات، لا تنفّذه.
3. فعل لا رجعة عنه أو مكلف: حذف بيانات، تغيير نموذج/أبعاد التضمين، ترقية خطة مدفوعة، إنفاق رصيد معتبر، نشر محتوى خارجياً.
4. تعارض قاعدتين من هذا الدستور: اعرض التعارض نفسه ودع القرار للمشرفين.
5. المتابعة تحتاج ما بيد صاحب النشر وحده (مفتاح، رصيد، ترقية، تجربة من حسابه): سمّ المطلوب بدقة وتوقّف — لا تدور حوله.
6. اكتشفت أن ادّعاءً سابقاً لك خاطئ: اعترف بالدليل أولاً، ثم اسأل قبل إعادة فتح النطاق.

قرِّر بنفسك — ولا تسأل:

افتراضي معقول + قابل للتراجع + داخل نطاق المهمة (صياغة رسالة سجل، اسم داخلي، تفصيلة تنسيق، ترتيب خطوات تنفيذ). نفّذ واذكر ما قررته في وصف التغيير.

شكل السؤال:

سؤال واحد مجمّع بخيارات ٢–٤ والموصى به أولها موسوماً — لا سلسلة أسئلة متتابعة.

أثناء عطل إنتاج:

شخّص فوراً (قراءة السجلات آمنة دائماً). الإصلاح المحصور ضمن الأعراف: نفّذه وسلّمه مباشرة. الإصلاح الذي يغيّر سلوكاً افتراضياً أو خطة/كلفة: خيارات أولاً.

٧. سجلّ القيود الحيّة (أرقام مقيسة — لا تخمينات)

• Vercel Hobby: maxDuration ≤ ٣٠٠ ثانية سقف صلب. تجاوزه = فشل النشر كلياً (invalid_max_duration) ويبقى الموقع على النشر السابق. التوليد الطويل يجري على عامل الـVPS بجلسة الاشتراك؛ مسار API «المباشر» طوارئ ضمن السقف. وكرونات Hobby محدودة باثنين يومياً.
• xhigh على Sonnet 5: نداء واحد قد يستغرق ٧–٨+ دقائق؛ التفكير يستهلك ٧٪→١٠٠٪ من max_tokens بتفاوت بين تشغيلين متطابقين. السقوف الحالية: مسودة/نقد (إكس والنشرة) ٣٢٠٠٠؛ أفكار/هيكل النشرة ١٦٠٠٠.
• Sonnet 5: لا prefill (400) · لا temperature/top_p/top_k (400) · ≤ ١٦ حقل union/nullable لكل مخطط (400) · المخرج المنظّم عبر output_config.format.json_schema.
• كاش البرومبت: ephemeral بمهلة ~٥ دقائق؛ المخطط جزء من البادئة — مخطط مختلف يُبطل الكاش رغم تطابق نص النظام بايتاً بايتاً.
• Gemini: responseMimeType وحده لا يضمن صلاحية JSON — responseJsonSchema يضمنها. Gemini قد يغلّف الكائن بمصفوفة.
• نفاد رصيد أنثروبيك يظهر كـ 400 invalid_request_error: credit balance is too low.
• إجراءات الخادم: الأخطاء المرميّة تُحذف رسائلها في الإنتاج (digest فقط) — القيم المعادة تنجو.
• أدوات Vercel MCP (إن استُخدمت): المعرّفات من .vercel/project.json المحلي (غير مرفوع إلى git) — تحقق من الملف دائماً. get_runtime_errors أولاً (مجمّع وسريع)، ثم get_runtime_logs بنافذة ضيقة.
• بيئة ويندوز: cwd الصدفة قد يرتدّ بعد كل نداء (ابدأ بـcd)؛ تحذيرات CRLF عند الكومِت طبيعية.
• تحذير NFT في البناء (تتبّع data/ عبر newsletter/generate) معروف وحميد — لا تطارده.

٨. المهارات الإجرائية

الإجراءات المتكررة مقننة كمهارات في .claude/skills/ (لمن يستخدم Claude Code؛ وهي وثائق إجرائية مفيدة لأي مساهم):

٩. ملفات المرجع

schema.sql (المخطط الكامل) · supabase/migrations/ · data/README.md وقوالب السياق · docs/SETUP.md (التركيب) · worker/README.md (العامل).

١٠. روح التعامل

عربية دائماً. صفر أحرف لاتينية في الواجهة. صراحة كاملة — بما فيها الاعتراف بالفجوات والقيود قبل أن يكتشفها غيرك. عند خطأ معماري محتمل: نبّه قبل التنفيذ. الإطلاق أهم من الكمال — أبسط نسخة تعمل ثم حسّن.