Claude Code وCodex: كيف تقلّل هدر الرموز (tokens) بثلاثة ملفات markdown

لا تحرق وكلاء الذكاء الاصطناعي (AI) المخصصة للتطوير السياق لأنها تجيب بشكل سيئ، بل لأنها تقضي معظم وقتها في البحث عن المكان المطلوب في الشيفرة. وحتى مع نافذة سياق بحجم مليون رمز، تعيد هذه الوكلاء استعراض المجلدات، وتعيد قراءة ملفات مألوفة، وتفحص الخوادم كأنها ترى المشروع للمرة الأولى. ويُظهر التحليل أن الوكيل أنفق على سؤال بسيط عن المدفوعات أكثر من 80 ألف رمز وأكثر من 15 استدعاءً للأدوات، بينما لم تتجاوز الإجابة نفسها نحو 800 رمز.

أي أن الميزانية كلها تقريبًا ذهبت إلى التنقل لا إلى التفكير. وتبيّن أن المشكلة ليست خاصية محلية في Claude Code، بل قيد عام في وكلاء البرمجة الحديثة. فـ Cursor وCodex وGemini CLI تعمل بالمخطط نفسه: ففي غياب خريطة لمساحة العمل، تبدأ كل جلسة جديدة بمرحلة استطلاع.

وإذا كان المشروع واحدًا فالأمر محتمل. أما حين يملك المطوّر عشرات المستودعات وخوادم VPS وبيئات staging، فإن الوكيل يبحث أولًا بأمر grep في المجلد الرئيسي، ويجد ملفات مشابهة في مشاريع مجاورة، ويقرؤها، ثم يدرك أنه سلك الطريق الخطأ، فيبدأ دورة بحث جديدة. وفي المثال الواقعي تحوّل سؤال عن طرق الدفع في أحد البوتات إلى بحث في عدة مشاريع، وإعادة قراءة ستة ملفات، بل وفحص للإعدادات على الخادم عبر SSH.

هذا النمط مكلف وهشّ في آن واحد: فالنموذج ينفق جهده في التوجّه، ويفوّت بسهولة المواضع ذات الصلة. ويستعرض الكاتب ثلاثة حلول شائعة تُقترح عادةً علاجًا. الأول هو RAG والبحث المتجهي.

فهو يجد جيدًا المقاطع المتشابهة دلاليًا، لكنه لا يفهم بنية المشروع جيدًا: قد يعيد أجزاء (chunks) تتعلق بـ auth وlogin وtoken، لكنه لا يعيد بناء سلسلة التبعية الدقيقة بين middleware ومنطق التحديث (refresh) وإعدادات JWT. كما يتطلب RAG بنية تحتية منفصلة وفهرسًا وإعادة فهرسة، ويضيف كل طلب زمن تأخير. والسبيل الثاني هو التحليل الساكن ورسم التبعيات عبر AST وtree-sitter.

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

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

وفي المستوى الأول يوجد ملف CLAUDE.md في جذر المشروع المعيّن، ويتضمن حزمة التقنيات (stack) والملفات الأساسية وأوامر النشر واسم الخدمة والسجلات (logs). وبين المستويين يمكن إضافة طبقة وسيطة على هيئة Graphify، إذا كانت قاعدة الشيفرة كبيرة وتلزم شبكة دقيقة من الروابط.

أما بوصفها طبقة markdown ثالثة، فيقترح الكاتب تخزين الجلسات السابقة والقرارات الهندسية في ملفات markdown مع YAML frontmatter، كي يتذكر الوكيل ما جرى نقاشه، وأي الملفات تغيّرت، وأي القرارات اتُّخذت قبل أسبوع بشأن تصحيح الأخطاء أو المدفوعات. والفكرة بسيطة: أولًا الخريطة، ثم وصف المشروع، ثم ذاكرة النقاشات السابقة، وبعد ذلك فقط الشيفرة المصدرية. وتُظهر القياسات أن هذا المخطط يحقق مكسبًا عمليًا لا شكليًا.

ففي سؤال عن بنية المشروع احتاج الوكيل الأعمى إلى 12 استدعاءً للأدوات مقابل استدعاء واحد مع وجود التسلسل الهرمي. وفي سؤال عن المشاريع التي تستخدم مكتبة معينة، أجرى الوضع الأعمى 44 استدعاءً ومسح القرص بأكمله، ومع ذلك فاته أحد المشاريع الثلاثة المطلوبة؛ أما التسلسل الهرمي فاكتفى بطلبين موجّهين وقدّم إجابة كاملة. وفي حالة النشر كان الأثر أوضح: فبدون بنية كان الوكيل يقرأ ملفات الإعدادات ويتصل عبر SSH، بينما استطاع مع ملف CLAUDE.

md مملوء بشكل صحيح أن يجيب مباشرة من السياق دون أي استدعاءات إضافية. والاستنتاج المهم هنا أن السياق الأكثر تنظيمًا لا يرفع السرعة ويوفّر الرموز فحسب، بل يرفع دقة الإجابة أيضًا. لماذا يعمل هذا بشكل أفضل من خط RAG المعتاد؟ لأن ملفات markdown تمنح الوكيل زمن تأخير صفريًا وقابلية للتنبؤ وسهولة في التحديث.

فالمطوّر هو من يحدد ما يلزم معرفته عن المشروع، بدلًا من أن يعوّل على أن يستخرج المُرتِّب (ranker) المقاطع المناسبة من الفهرس. وإذا تغيّر النشر أو انتقلت خدمة إلى خادم آخر، يكفي تصحيح سطر واحد. كما يبدو التوسّع معقولًا: فخريطة المشاريع تشغل نحو 2 كيلوبايت، وخمسة عشر ملف مشروع بحجم 5 كيلوبايت لكل منها تعطي أقل من 80 كيلوبايت من السياق المنظَّم بدلًا من مئات الكيلوبايتات من الشيفرة المصدرية الخام.

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

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