ورشة مجانية 21–22.11ورشة مجانية لمدة يومين في Vibecoding يومي 21–22 نوفمبر الساعة 16:00 بتوقيت موسكو · الدفعة 3 تبدأ 23.11سجّل مجاناً ←الدفعة 3 (23.11)
إصدارتحليل · على الرادارHabr AI→ المصدر

AGENTS.md ساعد Codex على الالتزام بقواعد المشروع: 0 انتهاكات من 13 مقابل 5 من 13

الجلسة الجديدة لوكيل الذكاء الاصطناعي لا تتذكر اتفاقات الأمس: فتضع SQL مباشرة في الخدمة، وتُنشئ عمودًا زائدًا cancelled_at، وتنسى تسجيل الإجراء في سجل التدقيق. أجرى Tech Lead سيرغي بروشايف 18 جلسة من Codex على خدمة Python صغيرة. بلا قواعد انتهك الوكيل 5 من 13 قرارًا في المشروع، أما مع ملف AGENTS.md أو مع skill فكانت النتيجة 0 من 13. لذلك يُستحسن أن يقتصر الملف على ما كان الوكيل سيفعله بشكل مختلف لو لم يُنبَّه إليه.

معالج بواسطة الذكاء الاصطناعي من Habr AI؛ بتحرير Hamidun News
AGENTS.md ساعد Codex على الالتزام بقواعد المشروع: 0 انتهاكات من 13 مقابل 5 من 13
المصدر: Habr AI. كولاج: Hamidun News.
استمع للمقال
بطاقة الحقائق والأرقام
المعيارالتفاصيل
المصدر الأصليHabr AI ↗
رئيس التحرير
لم يتفوق skill على AGENTS.mdكل ما حدث أن الملف الجذري أصبح أقصر
Vercelفي 56% من الحالات لم يُستدعَ skill دون إشارة صريحة إليه في AGENTS.md
ETH Zurichالملفات التي كتبها النموذج رفعت كلفة المهام بنسبة 20–23%

تعمل أسبوعًا كاملًا على مشروع مع وكيل ذكاء اصطناعي وتتفقان على ما يلي: SQL يوضع في db.py فقط، والأخطاء تمر عبر AppError، وإلغاء الاشتراك يغيّر الحقل status ويكتب سجلًا في سجل التدقيق. تُغلق الجلسة.

وفي اليوم التالي تضيف جلسة جديدة تقريرًا عن الإيرادات، فتضع conn.execute مباشرة في الخدمة، وتُنشئ عمود cancelled_at، وتنسى التدقيق. الاختبارات خضراء، والتقرير يحسب بشكل صحيح، لكن قرارات الفريق بقيت في محادثة الأمس.

اختبر Tech Lead سيرغي بروشايف على 18 جلسة من Codex ما إذا كان ملف AGENTS.md يعالج هذه المشكلة. هذا الملف نصي عادي يحوي قواعد المشروع ويقرأه الوكيل عند البدء.

النتيجة: بلا قواعد انتهك الوكيل 5 من 13 قرارًا قابلًا للفحص، ومع AGENTS.md أو مع skill، أي دليل منفصل يحوي التعليمات، كانت النتيجة 0 من 13.

ماذا أظهرت التجربة

شغّل المؤلف Codex CLI 0.166.0 على خدمة Python صغيرة. المهمة: اشتراكات بسعر بالروبل، وإلغاء، وتقرير عن الإيرادات. بدأت كل جلسة من الصفر، في دليل معزول ودون سجل محادثات. قورنت ثلاثة أنماط: بلا قواعد، ومع AGENTS.md، ومع skill منفصل. وشُغّل كل نمط ثلاث مرات.

في الجولة الأولى كانت هناك ثمانية فحوصات. بلا قواعد ارتكب الوكيل انتهاكين في كل جلسة: سمّى عمود المبلغ المالي price_kopecks بدل الاسم المعتمد، ووضع SQL في الخدمة مع أن الملف المجاور users.py يصل إلى قاعدة البيانات عبر db.py. أما الباقي فاستنتجه الوكيل بنفسه من الشيفرة: خزّن المبالغ بالكوبيك، وأخذ الوقت عبر clock، ورفع AppError.

في الجولة الثانية أضاف المؤلف خمسة قرارات تخالف عادات النموذج. بلا قواعد، في الجلسات الثلاث كلها، أنشأ الوكيل cancelled_at بدل status، ولم يستدعِ db.add_audit مع أن الدالة موجودة في المشروع، وكتب رموز الأخطاء بالأسلوب القديم bad_price. هذه هي الانتهاكات الخمسة من 13 فحصًا. أما مع AGENTS.md ومع skill فلم تقع أي انتهاكات إطلاقًا. ومع ذلك نجحت اختبارات القبول في جميع الأنماط، بما فيها نمط «بلا قواعد». الاختبارات العادية لا ترى مثل هذه الاتفاقات، ولذلك لزم سكربت منفصل check.py يحلل الشيفرة عبر ast.

استبعد المؤلف من الحساب مؤشرين بأمانة. اعتمد الوكيل UUID حتى بلا قواعد لأن توقيع الدالة كان يتطلب معرّفًا نصيًا. ولم يُنتهك تنسيق السجلات لأنه لم تكن هناك سجلات أصلًا في الوحدة الجديدة.

كيف تكتب القواعد

الخطوة 1: اسأل عن كل قرار: هل سيفعل الوكيل ذلك من تلقاء نفسه؟ والتحقق لا يكون بالتخمين بل بجلسة بلا قواعد. الخطوة 2: يجب أن يكون للقاعدة سبب وعلامة ملحوظة على انتهاكها، وأن يُسمّى المحظور صراحة (cancelled_at، execute). وإذا كانت الشيفرة القديمة لا تتوافق مع القاعدة، فاكتب ذلك في القاعدة نفسها، وإلا اعتبر الوكيل ما يراه بجانبه نموذجًا يُحتذى.

الخطوة 3: ضع في AGENTS.md الجذري القرارات التي تمس أي تعديل. يقرأ Codex الملف العام أولًا، ثم ملفًا واحدًا لكل دليل على المسار حتى الدليل العامل. الحد الإجمالي project_doc_max_bytes هو 32 كيبي بايت افتراضيًا. والأفضل إبقاء قواعد الوحدة الواحدة في AGENTS.md الخاص بدليلها.

الخطوة 4: انقل المحتوى الطويل إلى skill، لكن أشِر إليه من AGENTS.md. فالوكيل يرى من skill رأسه فقط ويقرر بنفسه هل يحمّل الباقي. وفي قياس Vercel على وثائق Next.js 16 لم يُستدعَ skill في 56% من الحالات، وبقيت نسبة المهام المحلولة عند 53%، كما في غياب الوثائق. أما عبارة صريحة في AGENTS.md فرفعتها إلى 79%، وفهرس مضغوط داخل الملف نفسه أوصلها إلى 100%. وفي تجربة بروشايف كانت الإشارة موجودة دائمًا، وفُتح skill في ست جلسات من ست.

الخطوة 5: تحقق من القواعد في بيئة نظيفة. لدى المؤلف في AGENTS.md العام 62 كيلوبايت من القواعد الشخصية ونحو مئة skill، لذا لم يكن نمط «بلا قواعد» دون عزل بلا قواعد فعلًا. وللفحص يُوجَّه HOME وCODEX_HOME إلى دليل مؤقت. الخطوة 6: حوّل القرارات إلى فحوصات آلية، واختبر الفحوصات نفسها على شيفرة معطوبة عمدًا.

القيود والكلفة

التجربة صغيرة: نموذج واحد، ومهمة واحدة، وثلاث جلسات لكل نمط. ولا يمكن من هذه النتائج استنتاج نسبة الانتهاكات لدى وكلاء آخرين. ولم يعطِ skill ميزة قابلة للقياس مقارنة بـ AGENTS.md، وفائدته تنظيمية فقط. أما سكربت check.py فيلتقط فقط أشكال الانتهاك المعروفة سلفًا: وإذا مرّ SQL عبر دالة مساعدة أخرى فسيفوته.

ملف السياق له كلفة مالية. ووفق دراسة ETH Zurich «Evaluating AGENTS.md»، لم ترفع الملفات التي ولّدها النموذج نسبة المهام المحلولة، بينما ارتفعت الكلفة بنسبة 20–23%. أما الملفات التي كتبها المطورون فأعطت +2,4% في المهام المحلولة، وهي زيادة غير ذات دلالة إحصائية، مع ارتفاع في الكلفة بلغ 19%. فالوكلاء يبدؤون بالاستكشاف والاختبار أكثر، وهذا بدوره يستهلك توكنات.

الخلاصة العملية: خذ آخر ثلاثة تعديلات أجريتها يدويًا خلف الوكيل، واكتبها قواعد مع علامة الانتهاك، وشغّل جلسة واحدة في بيئة نظيفة. القواعد التي ينتهكها الوكيل دون الملف ويلتزم بها معه هي ما ينبغي أن يتألف منه AGENTS.md الخاص بك. أما الباقي فلا يضيف سوى النفقات. ودعم التنسيقات يتوقف على الأداة: يقرأ Claude Code الملف CLAUDE.md، ويقرأ Gemini CLI افتراضيًا GEMINI.md، لذا يُستحسن مراجعة وثائق الوكيل الذي تستخدمه.

القصة

أسئلة وأجوبة حول الخبر

ما أبرز التفاصيل حول ماذا أظهرت التجربة؟

شغّل المؤلف Codex CLI 0.166.0 على خدمة Python صغيرة. المهمة: اشتراكات بسعر بالروبل، وإلغاء، وتقرير عن الإيرادات. بدأت كل جلسة من الصفر، في دليل معزول ودون سجل محادثات. قورنت ثلاثة أنماط: بلا قواعد، ومع AGENTS.md، ومع skill منفصل. وشُغّل كل نمط ثلاث مرات. في الجولة الأولى كانت هناك ثمانية فحوصات. بلا قواعد ارتكب الوكيل انتهاكين في كل جلسة: سمّى عمود المبلغ المالي price_kopecks بدل الاسم المعتمد، ووضع SQL في الخدمة مع أن الملف المجاور users.py يصل إلى قاعدة البيانات عبر db.py.

ما أبرز التفاصيل حول كيف تكتب القواعد؟

الخطوة 1: اسأل عن كل قرار: هل سيفعل الوكيل ذلك من تلقاء نفسه؟ والتحقق لا يكون بالتخمين بل بجلسة بلا قواعد. الخطوة 2: يجب أن يكون للقاعدة سبب وعلامة ملحوظة على انتهاكها، وأن يُسمّى المحظور صراحة (cancelled_at، execute). وإذا كانت الشيفرة القديمة لا تتوافق مع القاعدة، فاكتب ذلك في القاعدة نفسها، وإلا اعتبر الوكيل ما يراه بجانبه نموذجًا يُحتذى. الخطوة 3: ضع في AGENTS.md الجذري القرارات التي تمس أي تعديل. يقرأ Codex الملف العام أولًا، ثم ملفًا واحدًا لكل دليل على المسار حتى الدليل العامل.

ما أبرز التفاصيل حول القيود والكلفة؟

التجربة صغيرة: نموذج واحد، ومهمة واحدة، وثلاث جلسات لكل نمط. ولا يمكن من هذه النتائج استنتاج نسبة الانتهاكات لدى وكلاء آخرين. ولم يعطِ skill ميزة قابلة للقياس مقارنة بـ AGENTS.md، وفائدته تنظيمية فقط. أما سكربت check.py فيلتقط فقط أشكال الانتهاك المعروفة سلفًا: وإذا مرّ SQL عبر دالة مساعدة أخرى فسيفوته. ملف السياق له كلفة مالية. ووفق دراسة ETH Zurich «Evaluating AGENTS.md»، لم ترفع الملفات التي ولّدها النموذج نسبة المهام المحلولة، بينما ارتفعت الكلفة بنسبة 20–23%.

ZK
جمال حميدون — مدير المنتجات في Alpina Digital ومدير منتج AlpinaGPT. يبني منتجات الذكاء الاصطناعي منذ 2019. بدأ Hamidun News كمشروع شخصي ثم أصبح مُجمِّعًا إنتاجيًا بأكثر من 6000 قارئ.
✦ Hands-On AI Engineering · Hamidun Academy

Build & Ship Production AI Agents Without Boilerplate Code

Start your free 72-hour trial at Hamidun Academy (academy.hamidun.com) — interactive lessons on Claude Code & Cursor, live Tech Radar, and production agent templates.

Start 72h Free Trial →Vibe-Coding Intensive
ما رأيك؟
جارٍ تحميل التعليقات…