جودة الكود مع الذكاء الاصطناعي: قواعد agent.md لدى فابيان سانغلار

نشر المبرمج فابيان سانغلار في 21 أغسطس 2026 تدوينة بعنوان "My agent.md to improve LLM-assisted code quality"، شارك فيها ملف agent.md الذي تحمّله أدوات البرمجة تلقائيًا في بداية كل جلسة.

من محاولة فاشلة إلى سير عمل فعّال

يتذكر سانغلار محاولته الأولى في منتصف 2025: كان يعمل على libadbmdns، وهو تطبيق لبروتوكول mDNS بلغة Rust، والكود المولَّد لم يكن يمرّ حتى من مرحلة التصريف. وفي يناير 2026 عاد إلى النماذج اللغوية، فكتب النموذج صنفًا معقدًا لكومة ثنائية مُفهرسة، بل حدّد خطأً خفيًا في حزمة polling ناتجًا عن تنفيذ Windows لـ IOCP.

لكن جودة الكود كانت سيئة للغاية: كود متشابك بلا تعليقات ولا بنية. وفي مارس 2026 انتقل إلى بيئات تطوير عاملة بالوكلاء مثل Antigravity وإضافة Claude Code في VS Code، ما أتاح له المراجعة التكرارية للكود. تحسنت الجودة تحسنًا كبيرًا واقتربت مما كان سيكتبه بيده، لكن تكرار الملاحظات ذاتها في كل جلسة جديدة كان مُرهقًا.

ما يحتويه الملف

يوضع agent.md في جذر المشروع، ويمكن ربط gemini.md أو claude.md به عبر رابط رمزي لتعمل القواعد في أي مكان. ومن قواعد سانغلار: استخدام أقل عدد ممكن من الكلمات في كل نص موجّه للبشر؛ وتجنّب المدح وطلب «الحقيقة الباردة»؛ واستبدال الأرقام السحرية بثوابت وصفية أو بـ enum؛ وتقليل الإزاحة وتجنّب نمط السهم عبر return المبكر؛ وإبقاء أسماء الدوال أقصر من 30 حرفًا؛ واستخدام enum بدل boolean في المعاملات؛ وإضافة أسطر فارغة بين الكتل المنطقية؛ وكتابة تعليقات قصيرة تشرح «ماذا» و«لماذا»، مع رسوم ASCII عند الحاجة؛ والتعامل مع تغيير صلاحية الوصول كتغيير تصميمي يستوجب طلب موافقة قبل جعل أي حقل عامًا؛ والبرمجة وفق مستويات التجريد مع طبقة تشغيل مستقلة؛ وعدم لمس الكتل غير المرتبطة وتقليل عدد الأسطر المتغيرة؛ واحترام تسلسل الطبقات دون «ثقبها»؛ واستخدام الأقواس المعقوفة دائمًا حتى في جملة if من سطر واحد.

رسائل الالتزام والاختبارات

يتضمن الملف أيضًا سبع قواعد لرسائل الالتزام: فصل سطر الموضوع عن المتن بسطر فارغ؛ وقصر الموضوع على 50 حرفًا (72 هو الحد الأقصى المطلق)؛ وكتابة الحرف الأول كبيرًا؛ وعدم إنهاء السطر بنقطة؛ واستخدام صيغة الأمر مع اختبار إكمال جملة "If applied, this commit will..."؛ وتقسيم المتن عند 72 حرفًا؛ وشرح «ماذا» و«لماذا» في المتن لا «كيف». أما في إصلاح الأخطاء فالقاعدة إجرائية: اكتب الاختبار أولًا، ولاحظ فشله، ثم نفّذ الإصلاح ولاحظ نجاح الاختبار.

الحدود: الهلوسة وتمييع السياق

يشدد سانغلار على أن هذا ليس حلًا سحريًا. فالنماذج اللغوية تهذي باستمرار ولا يمكن الوثوق بها، لذلك لا يزال التثبّت والتكرار ضروريين، غير أنه يركّز الآن على البنية والتصميم بدلًا من أسلوب الكود. والمشكلة الثانية هي تمييع السياق أو الانتباه الموصوف في ورقة Lost in the Middle: فكلما كبر السياق قلّ انتباه النموذج للتعليمات الواقعة في المنتصف وزاد انتباهه لما في البداية والنهاية.

وجد طريقتين لتقليل الأثر: إبقاء السياق قصيرًا ببدء جلسة جديدة لكل ميزة، وطلب إعادة تحميل agent.md صراحةً من الأداة عند تراجع الجودة — وعبارة "Reload agent.md" كافية. ولإضافة قاعدة لا يفتح محررًا، بل يطلب من الوكيل تحديث agent.md بنفسه.