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
تعمل أسبوعًا كاملًا على مشروع مع وكيل ذكاء اصطناعي وتتفقان على ما يلي: 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، لذا يُستحسن مراجعة وثائق الوكيل الذي تستخدمه.
- 30 أبريل 2026كيف تحوّل OpenAI Codex إلى وكيل ذكاء اصطناعي متكامل للتطوير الفعلي: 5 ممارسات
- 12 أكتوبر 2026T-Bank يعلّم وكيل الذكاء الاصطناعي كتابة اختبارات الوحدة لنظام iOS عبر AGENTS.md وSKILL.md
- 30 أبريل 2026Anthropic وETH Zurich: ملف CLAUDE.md الطويل يضعف أداء الوكيل ويرفع التكاليف
- 27 أكتوبر 2026LangChain ترفع وكيل البرمجة من خارج المراتب الثلاثين الأولى إلى المراتب الخمس الأولى في Terminal Bench دون تغيير النموذج
أسئلة وأجوبة حول الخبر
ما أبرز التفاصيل حول ماذا أظهرت التجربة؟
شغّل المؤلف 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%.
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.
أهم ما في عالم الذكاء الاصطناعي — مرة كل أسبوع
سبع قصص مهمة فعلاً هذا الأسبوع، مختارة بعناية. بلا ضجيج ولا بيانات صحفية.
تم! تحقق من بريدك للتأكيد.