Claude Code في المونوربو: تحديد السياق والحفاظ على الدقة

لماذا تقل دقة Claude في المونوربو الكبيرة

قد يبدو Claude Code في المونوربو غير متوقع لسبب بسيط: المستودع أكبر من ما يمكن للنموذج أن يحفظه في ذاكرة العمل دفعة واحدة.

"السياق" هو مجموعة الملفات والمقاطع والملاحظات والتعليمات التي عُرضت على Claude لهذه المهمة، بالإضافة إلى ما يمكنه استنتاجه منها. عندما تكون التفاصيل الأساسية مفقودة، يعوّض Claude الفجوات بتخمينات. في مستودع كبير، يحدث ذلك أكثر.

تظهر ثلاث أوضاع فشل مرارًا وتكرارًا:

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

ثانيًا، التشابه الخاطئ. غالبًا ما تحتوي المونوربو على حزم متعددة تبدو متشابهة: نموذجان للمصادقة، ثلاثة عملاء API، أو عدة تطبيقات React ببُنى مجلدات متشابهة. قد يخلط Claude الأنماط بينها، يحدث مساعدًا في الحزمة الخاطئة، أو يستورد من اسم وحدة "شبه صحيح".

ثالثًا، الانجراف الزمني. قواعد الكود الكبيرة عادةً ما تحتوي على طرق قديمة وحديثة لأداء نفس العمل. إذا رآى Claude ملفاتًا أقدم فقط، فقد ينسخ أنماطًا منتهية الصلاحية (خيارات إعدادات مهجورة، واجهات برمجة قديمة) رغم أن الفريق قد انتقل إلى نهج جديد.

مثال واقعي شائع: تطلب تغييرًا صغيرًا لواجهة فوترة، فيعدل Claude مكونًا مشتركًا payments يستخدمه تطبيقات أخرى لأنه لم ير غلاف التطبيق الخاص الذي كان يجب تغييره.

الهدف ليس إظهار المونوربو كله لـ Claude. الهدف هو تقديم مدخلات أصغر ومقصودة تُجيب على السؤال: الحزمة التي تغيّرها، تبعياتها المباشرة، ومصدر/مصادر الحقيقة (الأنواع والإعدادات). اذكر أيضًا مناطق "لا تلمس" (تطبيقات أخرى، بنية تحتية، كود مولَّد) وأكد أي حزمة تملك السلوك.

ابدأ بتعريف المهمة، لا المستودع

تعتمد الدقة أقل على مقدار الكود الذي تلصقه وأكثر على وضوح وصفك للمهمة.

ابدأ بالنتيجة التي تريدها: إصلاح محدد، إعادة هيكلة، أو جواب. سؤال "عن الكود" يمكن أن يبقى عالي المستوى. طلب "إجراء تغيير" يحتاج حدودًا، مدخلات، وفحوص نجاح.

قبل مشاركة أي شيء، اكتب جملة واحدة تكمل العبارة: "بعد انتهائك، يجب أن أتمكن من…". مثال: "تشغيل اختبارات الوحدة للحزمة X بدون فشل" أو "رؤية الحقل الجديد في استجابة API لنقطة النهاية Y." تصبح تلك الجملة النجم الشمالي عندما يكون المستودع ضخمًا.

للتغييرات، شارك أصغر مجموعة من العناصر التي تُبرهن أن التغيير صحيح: نقطة/نقاط الدخول، الأنواع/الواجهات أو المخطط ذات الصلة، اختبار واحد فاشل أو خطوة استنساخ مع النتيجة المتوقعة، وأي إعداد يؤثر على هذا المسار (التوجيه، أعلام الميزات، البناء أو قواعد lint). إذا ساعد، أضف خريطة مجلدات قصيرة للحزمة حتى يفهم Claude ما يفعله كل دليل.

كن صريحًا بما يجب تجاهله. قل: "تجاهل الملفات المولَّدة، مجلدات البائع، مخرجات البناء، اللقطة snapshots، وملفات القفل ما لم أطلب." يمنع ذلك إضاعة الوقت والتعديلات في أماكن لن تراجعها.

اضبط أيضًا التوقعات بالنسبة للعدم اليقين. اطلب من Claude تمييز الافتراضات والمجهولات بدل التخمين. مثال: "إذا لم تستطع رؤية مكان استدعاء هذه الدالة، اذكر ذلك واقترح طريقتين لتحديده."

رسم حدود واضحة يجب ألا يتجاوزها Claude

في مونوربو كبير، تنخفض الدقة عندما يبدأ النموذج بـ "مساعدة" من خلال جرّ كود قريب ليس جزءًا من المهمة. الحل واضح: حدد ما هو داخل النطاق وما هو خارجه قبل طلب التغييرات.

ابدأ بحد يتطابق مع كيفية تنظيم المستودع: حزمة، خدمة، تطبيق، أو مكتبة مشتركة. إذا كان التغيير "تحديث واجهة الدفع"، فالحد غالبًا حزمة تطبيق واحدة، ليس كل مكان يذكر كلمة "checkout".

الإشارات التي تساعد Claude على البقاء في موضعها تشمل اتفاقيات المجلدات (apps/, services/, packages/, libs/)، ملفات تعريف الحزمة (exports و dependencies)، نقاط الدخول العامة (ملفات index، المكونات المصدّرة، المعالجات)، والاختبارات (غالبًا ما تكشف عن مساحة السطح المقصودة). يمكن أن يكون README داخل المجلد علامة حد سريعة.

تعمل الحدود بشكل أفضل عندما تسمي الجسور بينها. اذكر الواجهات المحددة التي قد يتعامل معها Claude واعتبر كل شيء آخر خارج الحدود. الجسور النموذجية هي عقود HTTP API، مواضيع الأحداث وحمولاتها، الأنواع المشتركة، أو مجموعة صغيرة من الدوال المصدَّرة.

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

تفصيل محدد يساعد:

"أجرِ تغييرات فقط داخل packages/cart/ واختباراته. يمكنك قراءة الأنواع المشتركة في packages/types/ لكن لا تعدلها. لا تلمس infra أو auth أو billing."

كيف تكتب ملخصات محلية مفيدة

تتحسن الدقة عندما تزود خريطة صغيرة وثابتة للمنطقة التي تريد تغييرها. "الملخص المحلي" هو تلك الخريطة: قصيرة لقراءة سريعة، ومحددة بما يكفي لمنع التخمين.

اجعل كل ملخص حوالي 10 إلى 20 سطرًا. اكتبها كأنك تُسلم الكود لزميل جديد يحتاج لمس هذا الحد فقط، لا المستودع كله. استخدم لغة بسيطة وأسماءًا حقيقية من الكود: مجلدات، حزم، دوال مصدّرة.

يجيب الملخص المحلي المفيد عن خمسة أسئلة:

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

أضف سطر "مآخذ" واحد. هذا يمنع الأخطاء المكلفة: التخزين المؤقت المخفي، أعلام الميزات، خطوات الترحيل، وأي شيء يكسر بصمت.

إليك قالبًا مضغوطًا يمكنك نسخه:

Local summary: \u003cpackage/service name\u003e
Purpose: \u003c1 sentence\u003e
Scope: \u003cwhat to touch\u003e | Not: \u003cwhat not to change\u003e
Entry points: \u003cfiles/routes/commands\u003e
Public surface: \u003cexports/endpoints/events\u003e
Data sources: \u003ctables/collections/queues/caches\u003e
Conventions: errors=\u003chow\u003e, logging=\u003chow\u003e, tests=\u003cwhere/how\u003e
Gotchas: \u003cflags/caching/migrations/edge cases\u003e

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

أين تعيش الملخصات وكيف تحافظ عليها محدثة

أفضل ملخص هو الذي يرى Claude عندما يحتاجه. ضَعه بجانب الشيفرة التي يصفها ليصبح من الصعب تجاهله وسهل التحديث. مثال: احتفظ بـ SUMMARY.md قصير (أو قسم في README.md) داخل كل حزمة أو تطبيق بدل وثيقة ضخمة في جذر المستودع.

هيكل بسيط وقابل للتكرار يساعد. اجعله قصيرًا بما يكفي ليحافظ الناس عليه:

• ما هذا المجلد (غرض في 1–2 جمل)
• السطح العام (نقاط الدخول الرئيسية، الموديولات المصدّرة أو الواجهات)
• التبعيات الرئيسية (داخلية وخارجية)
• الحدود (ما لا يجب استيراده أو تعديله)
• كيفية الاختبار (أسرع فحص محلي)
• آخر تحديث: YYYY-MM-DD - \u003cwhat changed in one sentence\u003e

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

حدّث الملخص عند تغير الهيكل أو الأسماء بعد إعادة هيكلة، عندما يصبح موديل جديد هو الطريقة الرئيسية لأداء شيء، عند تغيير API/event/schema (حتى لو ظلت الاختبارات تمر)، عند تغيير الحدود بين الحزم، أو عند إزالة أو استبدال تبعية.

عادة عملية عملية: عند الدمج، أضف سطر "Last updated" يذكر ما تغيّر. أدوات مثل Koder.ai يمكن أن تساعدك على إنجاز التغيير بسرعة، لكن الملخص هو ما يحافظ على دقة التغييرات المستقبلية.

سير عمل خطوة بخطوة للبقاء داخل السياق الصحيح

تعتمد الدقة غالبًا على كيفية توقيت المحادثة. اجعل Claude يكسب السياق على دفعات صغيرة بدل التخمين من لقطة ضخمة.

الخطوة 1: اطلب خريطة سريعة أولًا

قبل أي تعديل، اطلب من Claude وصف ما يراه وما يحتاجه. خريطة جيدة قصيرة: الحزم الرئيسية المعنية، نقطة الدخول للتدفق، وأين توجد الاختبارات أو الأنواع.

مثال مطالبة:

"أنشئ خريطة لهذا التغيير: الحزم المعنية، التدفق الرئيسي، ونقاط اللمس المحتملة. لا تقترح كودًا بعد."

الخطوة 2: ابدأ بشريحة واحدة وحد واحد

اختر شريحة ضيقة: ميزة واحدة، حزمة واحدة، تدفق مستخدم واحد. حدده بوضوح (مثال: "غيّر فقط packages/billing-api. لا تلمس shared-ui أو infra." ).

سير عمل يحافظ على السيطرة:

• عرّف الهدف والحد في جملة واحدة.
• اطلب الافتراضات والمجهولات (يجب أن يذكرها Claude).
• اطلب الملفات الدقيقة التي يحتاجها لاحقًا (حدد من 3 إلى 6).
• قدّم تلك الملفات فقط، ثم كرّر.
• اشترط خطة قصيرة قبل أي تعديل على الشيفرة.

الخطوة 3: أجبر الافتراضات وطلب الملفات صراحة

إذا كان Claude يفتقد شيئًا، فيجب أن يقول ذلك. اطلب منه كتابة: (1) الافتراضات التي يبني عليها، (2) ما ينقضها، و (3) الملفات التالية المطلوبة لتأكيدها.

مثال: تحتاج إضافة حقل لاستجابة Invoice في حزمة. يطلب Claude الـ handler، تعريف DTO/النوع، واختبار واحد. تشارك تلك الملفات فقط. إذا كنت تستخدم باني محادثة مثل Koder.ai، تطبق نفس القاعدة: قدم أصغر مجموعة من الملفات المصدرية ثم وسّع عند الحاجة الحقيقية.

استخدم القيود والعقود في مطالباتك

أفضل دفاع ضد التعديلات الخاطئة هو "عقد" صغير ضمن المطالبة: ما يمكن لـ Claude لمسه، كيف ستحكم النجاح، وما القواعد التي يجب اتباعها.

ابدأ بحد يسهل الالتزام به والتحقق منه. كن صريحًا بشأن مساحات التحرير المسموح بها واذكر مناطق "لا تلمس" حتى لا يكون هناك إغراء للتجوّل.

قالب عقد:

• عدّل فقط الملفات تحت packages/payments/.
• لا تعدل packages/auth/, infra/, أو أي إعدادات مشتركة.
• إذا احتجت تغييرات خارج النطاق، توقف واسأل أولًا.
• اجعل التغييرات طفيفة: أصلح العطل، تجنب إعادة الهيكلة.

ثم عرّف فحوص القبول. بدونها، قد ينتج Claude كودًا يبدو صحيحًا لكنه يخالف قواعد الريبو الحقيقية.

• شغّل اختبارات الوحدة للحزمة (ضع أمر التشغيل الذي تستخدمه).
• شغّل lint/format (اذكر الأداة أو قل "استخدم الإعدادات الحالية").
• شغّل typecheck/build للحزمة.
• تأكد أن التطبيق لا يزال يبدأ (أمر تشغيل بسيط يكفي).

تؤثر قيود النمط أيضًا. أخبر Claude أي أنماط يتبع ولا يتبع بناءً على ما يفعله الكود لديك. مثال: "استخدم أدوات الخطأ الموجودة في هذه الحزمة؛ لا تضف تبعيات جديدة؛ حافظ على أسماء الدوال بصيغة camelCase; لا تُدخل طبقة معمارية جديدة."

أخيرًا، اشترط خطة قصيرة قبل أي تعديل:

"قبل التعديل، اذكر 3–5 ملفات تتوقع لمسها والتغير السلوكي الدقيق. انتظر الموافقة."

مثال:

"صلح تقريب القيم في إجماليات الفواتير. عدّل فقط packages/billing/src/ والاختبارات تحت packages/billing/test/. القبول: pnpm -C packages/billing test و typecheck. اتبع الأدوات المالية الحالية؛ لا تعيد كتابة أنواع API. قدّم خطة من 4 خطوات أولًا."

الفخاخ الشائعة التي تسبب الانجراف والتعديلات الخاطئة

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

فخ آخر هو السماح له بتخمين المعمارية. إذا لم تُظهر نقاط الدخول الحقيقية، قد يختار أول ملف يبدو معقولًا ويوصل المنطق هناك. في الممارسة، تأتي الدقة من مجموعة صغيرة من ملفات "مصدر الحقيقة" (وحدات الدخول، الراوترات، سجلات الخدمات، وثائق حدود الحزمة). إذا لم تكن هذه في السياق، يملأ النموذج الفجوات.

الأسماء قد تخدع أيضًا. غالبًا ما تحتوي المونوربو على حزم مثل ui, ui-kit, shared-ui، ومساعدات مكررة كـ date.ts في مكانين. إن خلط مقتطفات من كلاهما قد يجعل Claude ي patch ملفًا بينما يعالج منطقًا في الآخر. مثال: تطلب تغيير نمط زر، يغيّر packages/ui/Button.tsx لكن التطبيق يستورد packages/ui-kit/Button.tsx. الفرق يبدو سليمًا، لكن لا يتغير شيء في الإنتاج.

الإعدادات مصدر آخر لانجراف صامت. السلوك قد يعتمد على متغيرات بيئة، أعلام، إعدادات البناء، أو أدوات workspace. إن لم تذكرها، قد يزيل Claude فحصًا "غريبًا" يهم فقط عند تفعيل علم، أو يضيف كودًا يكسر خطوة بناء.

علامات حمراء تدل على أنك تنجرف:

• يَتحدّث الجواب عن "أنماط نمطية" دون تسمية ملفاتك الحقيقية
• يُدخل أداة مشتركة جديدة بدل استخدام الموجودة
• يغيّر الاستيراد عبر حدود الحزم
• يتجاهل أعلام الميزات أو فروع متعلقة بالبيئة
• يقترح إضافة تبعية إلى حزمة مشتركة أساسية

عامل استيراد عبر الحزم كقرار، لا كافتراض. حافظ على التعديلات محلية إلا إذا وسّعت النطاق عن قصد.

قائمة تحقق سريعة قبل أن تسأل Claude عن أي شيء

أسرع طريقة للحصول على تعديلات صحيحة هي البدء بالحدود بدل الحجم. مطالبتك الجيدة تبدو صارمة قليلًا: تخبر Claude أين ينظر، ماذا يتجاهل، وما معنى "تم".

قبل أن تلصق الكود، اكتب مقدمة قصيرة تحدد العمل إلى مكان واحد في الريبو. سمّ الحزمة، المجلد الدقيق، والهدف المحدد. ثم أضف ملخصًا محليًا (الغرض، التبعيات الرئيسية، الاتفاقيات المهمة) وملف الدخول الذي يرسّخ التغيير.

قائمة التحقق:

• Boundary: اعمل فقط في \u003cpackage\u003e/\u003cpath\u003e. الهدف: \u003cone sentence\u003e. تجاهل الباقي ما لم أطلب.
• Context starter: ملخص محلي: \u003c5-10 lines\u003e. ملف الدخول: \u003cpath/to/file\u003e.
• Constraints: المجلدات المسموح بها: \u003c...\u003e. يجب ألا تغيّر: \u003cfolders/files or APIs\u003e. احتفظ بالسلوك: \u003cwhat must stay true\u003e.
• File requests first: "قبل اقتراح التغييرات، اذكر الحد الأدنى من الملفات التي تحتاج رؤيتها (حد أقصى 5) ولماذا."
• Output format: "رد بخطة قصيرة أولًا. بعد الموافقة، قدم اقتراحات على شكل diff بحسب الملف."

إذا اقترح Claude تغييرات خارج حدودك، اعتبر ذلك إشارة: إما شدّد المطالبة، أو وسّع النطاق عن قصد وأعد صياغته بوضوح.

مثال: إجراء تغيير في حزمة واحدة بدون إيقاظ المونوربو كله

افترض أن المونوربو لديك يحتوي على apps/web-store (تطبيق React) و packages/ui-kit (أزرار مشتركة، مدخلات، وأنماط). تريد ميزة صغيرة: إضافة زر "حفظ للمتابعة" في صفحة السلة، باستخدام SaveIcon جديد من ui-kit. لا يجب أن يتغير شيء آخر.

قبل طلب التعديلات، اصنع ملخصين محليين يعملان كحدود. اجعلهما قصيرين ومحددين ومتحيّزين حول ما يهم.

# apps/web-store/LOCAL_SUMMARY.md
Purpose: Customer shopping UI.
Entry points: src/routes.tsx, src/pages/cart/CartPage.tsx
Cart rules: cart state lives in src/cart/useCart.ts
Do not touch: checkout flow (src/pages/checkout), payments, auth.
Tests: npm test -w apps/web-store

# packages/ui-kit/LOCAL_SUMMARY.md
Purpose: shared UI components.
Exports: src/index.ts
Icons: src/icons/*, add new icons by exporting from index.
Do not touch: theming tokens, build config.
Tests: npm test -w packages/ui-kit

ثم أبقِ الحلقة قصيرة:

1. خريطة: "هذا التغيير محصور في CartPage وأيقونات ui-kit. لا تعدّل checkout/auth."
2. افتراضات: اشترط قائمة بالافتراضات وانتظر التأكيد.
3. طلب ملفات: صادق فقط على الملفات القليلة التي يحتاجها فعلًا (CartPage, useCart, أيقونات ui-kit، index في ui-kit).
4. الخطة: تأكد أنها تطابق الحدود.
5. التعديلات: اجعل diff أصغر ما يمكن، ثم اطلب اختبارات محدثة.

بعد التغيير، وثّقه ليبقى السياق مستهدفًا:

• حدّث كلا الملخصين المحليين مع التصدير الجديد والملفات التي لمسها التغيير.
• أضف ملاحظة قصيرة في رأس صفحة السلة: ما الذي يفعله الزر وأين يُدار الحالة.
• سجّل أوامر الاختبار التي نجحت (وأي snapshots تم تحديثها).

الخطوات التالية: اجعل هذا قابلاً للتكرار لفريقك

إذا نجح هذا لشخص واحد ولم ينجح لباقي الفريق، فالعنصر المفقود غالبًا هو قابلية التكرار. اجعل "نظافة السياق الجيدة" افتراضية، لا عادة شخصية.

حول أفضل مطالباتك إلى قالب فريق

احفظ قالب مطالبة يمكن للجميع نسخه وملؤه. اجعله قصيرًا لكن صارمًا. اشمل الهدف (ما معنى "تم"), النطاق المسموح، الحدود الصارمة (ولماذا), ملخصًا محليًا، وعقد الإخراج (خطة أولًا، ثم اقتراحات على شكل diff واختبارات).

حافظ على الملخصات محدثة بدورة خفيفة

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

قاعدة بسيطة: إذا كان الزميل سيسأل "أين يقع هذا؟" أو "ما الذي يعتمد على هذا؟" فالملخص قديم الآن.

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