Claude Code و Codex: كيفية تقليل خسائر الرموز باستخدام ثلاثة ملفات markdown

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

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

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

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

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

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

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

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

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

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

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

يحدد المطور نفسه بالضبط ما هو مهم معرفته عن المشروع، بدلاً من أمل أن يسحب الترتيب الأجزاء المطلوبة من الفهرس. إذا تغير النشر أو انتقلت الخدمة، فيكفي إصلاح سطر واحد. يبدو التوسع أيضًا معقولاً: خريطة المشروع تشغل حوالي 2 كيلوبايت، وخمسة عشر ملف مشروع بـ 5 كيلوبايت لكل منهما يعطي أقل من 80 كيلوبايت من السياق المنظم بدلاً من مئات الكيلوبايتات من الكود المصدري الخام.

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

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