كنت كسولاً جداً لأكتب CLAUDE.md — واتضح أن ذلك كان القرار الصحيح

في كل مرة كانت تظهر في تيمة مقالة عن CLAUDE.md أو AGENTS.md، كنت أقول لنفسي “سأُعدّها لاحقاً” وأتخطاها. كنت أرى الآخرين يبنون إعدادات متقنة لـ AGENTS.md، وكان يراودني قلق خفيف — هل أنا متأخر؟

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

ملفات السياق التي يُنشئها النموذج تُفسد الأمور

“أليس من المنطقي أن تُعطي الوكيل سياقاً أكثر؟” — هذا ما كنت أظنه أيضاً.

حين اختبر الباحثون السياق الذي يُولّده النموذج تلقائياً على اختبار SWE-bench Lite، انخفض معدل النجاح بنسبة 0.5%. وعلى AgentBench، هبط بنسبة 2% إضافية. حتى الملفات المكتوبة يدوياً بعناية لم تُحقق سوى تحسن بنسبة 4% في أفضل الأحوال. أُسمّي هذه الظاهرة “الإفراط في السياق”.

• انخفاض بنسبة 0.5% في معدل النجاح مع السياق الذي يُولّده النموذج على SWE-bench Lite
• هبوط إضافي بنسبة 2% على AgentBench
• ارتفاع تكاليف الاستدلال بنسبة 20-23%
• أثر إيجابي (2.7%) فقط في المشاريع الخالية كلياً من التوثيق

الورقة البحثية “تقييم AGENTS.md” لغلواغن وزملائه أكّدت ذلك: ملفات السياق تميل إلى تراجع معدلات نجاح المهام مقارنةً بغياب أي سياق للمستودع من الأساس.

الوكلاء يتبعون التعليمات بشكل مفرط — وهذه هي المشكلة بعينها

المشكلة ليست أن الوكيل يتجاهل تعليماتك. بالعكس تماماً.

اكتب سطراً واحداً في ملف السياق تطلب فيه من الوكيل استخدام uv، وسيُثبّته ويُشغّله حتى في المواقف التي لا حاجة فيها لذلك، مُضيفاً خطوات زائدة في كل مرة.

مع GPT-5.2، ارتفعت رموز الاستدلال بنسبة 14-22% حين كانت ملفات السياق موجودة. كان الوكيل منشغلاً جداً باتباع التعليمات لدرجة أنه أضاع تركيزه عن حل المشكلة الفعلية.

• تشغيلات pytest غير الضرورية تضاعفت
• استخدام أدوات grep والقراءة اتسع بكثير فوق الحاجة

”لا تفعل X” يجعل الوكيل يُفكّر في X أكثر

تحدثت في مقالة سابقة عن كيف يُقرأ محتوى SKILL.md في توقيتات بعينها، ولدى AGENTS.md مشكلة مشابهة.

يقع هذا الملف في طبقة “رسالة المطوّر” بين موجّه النظام وموجّه المستخدم. وهذا الموضع يُقيّد تفكير الوكيل تقييداً شديداً.

اكتب “لا تلمس هذا الملف”، وسيُفكّر الوكيل في ذلك الملف مرةً إضافية. أسمى الباحثون هذه الظاهرة “تأثير الفيل الوردي” — قل لشخص ما “لا تُفكّر في فيل وردي”، وهذا بالضبط ما سيقفز إلى ذهنه.

• ترتيب الأولوية: تعليمات المزوّد ← موجّه النظام ← AGENTS.md ← موجّه المستخدم
• الملفات التي تُصان يدوياً لا تواكب تغييرات الكود، فتتقادم المعلومات بسرعة

إن اضطررت لكتابة ملف، اجعله في حده الأدنى

إن كان مشروعك خالياً تماماً من التوثيق، فقد تُفيد ملفات السياق — البيانات أظهرت أثراً إيجابياً بنسبة 2.7% في تلك الحالات. لكن إن كتبت واحداً، فاحرص على إبقاء حجمه في حده الأدنى.

سطر واحد لأداة البناء الخاصة بالمشروع. سطر واحد لتصحيح نمط يُكرر الوكيل خطأه.

أضف تعليقاً من قبيل “إن وجدت شيئاً غريباً هيكلياً، أبلغ فوراً” وسيتحول الوكيل إلى أداة تُبلّغ عن ثغرات في قاعدة الكود. وما عدا ذلك، فإن جعل بنية كودك أكثر وضوحاً وبديهية أجدى بكثير من كتابة تعليمات حولها.

• تعزيز اختبارات الوحدة وفحوصات الأنواع أنفع من ملفات السياق
• إن كانت مواقع الملفات مُربِكة، فانقل الملفات بدلاً من كتابة إرشادات عنها

كتابة ملفات سياق جيدة ليست بالضرورة دليلاً على المهارة. أن تفهم بنية ملفات السياق وتُصمّم أنظمة ميتا حولها — هذه هي المهارة الحقيقية. وأحياناً، “الكسل” هو أفضل قرار هندسي يمكنك اتخاذه.