Agent Operable Codebase

Image: AI generated

سؤال واحد

افتح أطول ملف في مشروعك. كم عدد الدوال فيه؟

اطلب من وكيل ذكاء اصطناعي تعديل دالة واحدة في ذلك الملف. الوكيل يقرأ الملف بالكامل. فتح الملف لأنه يحتاج دالة واحدة، لكن 19 دالة غير ضرورية جاءت معها.

هنا تبدأ المشكلة.

كود يقرأه البشر مقابل كود يعمل عليه الوكلاء

حتى الآن، كان الكود مكتوبًا ليقرأه البشر. تسمية المتغيرات بشكل جيد، وكتابة التعليقات، وإنتاج التوثيق — كل ذلك كان لتقليل العبء المعرفي البشري.

في عصر الوكلاء، يتغير السؤال. هل الكود السهل القراءة للبشر هو نفسه الكود السهل التشغيل للوكلاء؟

ليس كذلك.

البشر عند التمرير في ملف من 2,000 سطر يملكون حدسًا يقول “لا تلمس هذا الجزء”. الوكيل لا يملك هذا الحدس. عندما يقرأ 2,000 سطر، فإن 1,950 منها تلوث سياقي.

الأبحاث تؤكد ذلك. عندما تُخلط معلومات غير ذات صلة، ينخفض أداء الذكاء الاصطناعي بنسبة 30 إلى 85%. ينخفض الأداء حتى عندما تكون الرموز غير الضرورية مجرد مسافات بيضاء. أن السياق الأقصر أفضل ليس حدسًا — بل نتيجة تجريبية.

لا تضع روبوتًا في مكتب بشري. ابنِ مصنعًا يمكن للروبوتات العمل فيه.

ثلاثة أشياء يحتاجها الوكلاء

لكي يعمل الوكلاء بشكل موثوق في قاعدة الكود، يجب توفر ثلاثة أشياء.

1. يجب أن يكون قابلًا للقراءة — بدون ضوضاء

مفهوم واحد لكل ملف. اسم الملف هو اسم المفهوم.

before: read utils.go → 20 دالة، 19 غير ضرورية
after:  read check_one_file_one_func.go → دالة واحدة، بالضبط ما هو مطلوب

filefunc يحل هذه المشكلة. يفصل الكود إلى وحدات دلالية بـ 22 قاعدة هيكلية. طُبّق على إطار عمل Hono (أكثر من 23 ألف نجمة)، فقسّم 186 ملفًا إلى 626. نجحت جميع الاختبارات البالغ عددها 4,419. زادت الملفات 3.4 مرة، لكن لم يتغير سطر واحد من المنطق.

“ألن تكون الملفات كثيرة جدًا؟” — الوكلاء لا يتصفحون المجلدات. يبحثون. سواء كان هناك 500 أو 1,000 ملف، بحث grep واحد يكفي. عدم فتح 295 ملفًا غير ضروري أهم من اختيار الـ 5 التي تحتاجها.

2. يجب أن يكون قابلًا للتحقق — آليًا

عندما تعدّل دالة بدون اختبارات، لا أحد يعرف ما الذي ينكسر. الوكيل أيضًا لا يعرف. يقع في doom loop.

before: 0 اختبارات، لا طريقة لمعرفة ما ينكسر عند التعديل
after:  527 دالة مع اختبارات، تغييرات السلوك تُكتشف فورًا

tsma يحل هذه المشكلة. يفهرس كل دالة في المشروع، ويكشف وجود الاختبارات، ويقيس التغطية، ويعيد الفروع غير المغطاة بأرقام الأسطر.

بدون تغذية راجعة، يتوقف LLM عند كتابة الاختبارات عند تغطية 60-70%. أخبره “السطر 41، 44، 70 غير مغطى” ويصل إلى 100%. نفس النموذج. الفرق الوحيد هو دقة التغذية الراجعة.

نتائج تجريبية على مشروع بـ 527 دالة: اكتمل حتى TODO 0. وكيل مستقل أعلن “تم الانتهاء” عند 40. طبّق الـ ratchet: 527 مكتملة.

3. يجب أن تكون المواصفات قابلة للتحقق المتبادل

يجب أن يكون من الممكن التحقق آليًا من تناسق مخططات API ومخططات قواعد البيانات وسياسات الأمان وانتقالات الحالة مع بعضها البعض. عند تغيير أحدها، يجب أن تعرف قبل الترجمة ما إذا كان يتعارض مع البقية.

before: 200 نقطة نهاية، البشر يتحققون من تناسق المواصفات
after:  operationId واحد يربط جميع الطبقات، الآلات تكشف الانحراف

yongol يحل هذه المشكلة. يربط 10 من SSOT (OpenAPI وDDL وsqlc وSSaC وRego وHurl وغيرها) من خلال operationId واحد ويتحقق متبادلًا بحوالي 287 قاعدة. user_id هو string في OpenAPI لكنه BIGINT في DDL — الأدوات الحالية لا تستطيع اكتشاف تناقضات كهذه بين الطبقات.

بنية واحدة تمر عبر الأدوات الثلاث

filefunc وtsma وyongol أدوات مستقلة، لكنها تشترك في بنية مشتركة.

filefunc:  22 قاعدة هيكلية → validate → إصلاح → تكرار
tsma:      قياس التغطية → تغذية راجعة للفروع غير المغطاة → إصلاح → تكرار
yongol:    تحقق متبادل → كشف الانحراف → إصلاح → تكرار

كلها نفس الحلقة.

LLM يولّد → أداة حتمية تحكم → النتيجة تُعاد إلى LLM → تكرار

Symbolic Feedback Loop. بنية دورية حيث تصحح الأدوات الحتمية التوليد الاحتمالي لـ LLMs. ليس ذكاء اصطناعي يتحقق من ذكاء اصطناعي — بل آلات تتحقق من الذكاء الاصطناعي.

أعطه آراءً فيتملق. أعطه حقائق فيُصلح. اسأله “هل الكود جيد؟” فيجيب “نعم، يبدو رائعًا”. أخبره “السطر 41: عدم تطابق في اسم الحقل” فيصلحه فورًا. تغذية راجعة بدون شخص للتملق — لأن الأرقام والمواقع ليست مشاعر.

من النظام القديم إلى agent-operable

لا تحتاج لتغيير قاعدة كود موجودة دفعة واحدة. هذا ليس عمل أساسات — إنه تعزيز زلزالي. تقوية المبنى بدون إغلاق المتجر.

الخطوة 1 — اجعله قابلًا للقراءة

ابدأ بأطول الملفات. شغّل filefunc validate وأوصل المخالفات إلى صفر. جميع الاختبارات الحالية يجب أن تنجح.

الخطوة 2 — اجعله قابلًا للتحقق

كرر tsma next. أضف اختبارات للدوال بدون اختبارات واملأ الفروع غير المغطاة. حتى لو مات الوكيل في منتصف التشغيل، التقدم محفوظ. وكيل جديد يشغّل tsma next ويكمل من حيث توقف.

الخطوة 3 — تحقق متبادل

أدخل SSOT وشغّل yongol validate. الآلات تكتشف التناقضات بين الطبقات.

كل خطوة مستقلة. يمكنك تنفيذ الخطوة 2 بدون الخطوة 1، أو الخطوة 1 بدون الخطوة 2. لكن عندما تتحد الثلاث، يتوسع نطاق العمل المستقل للوكلاء بشكل كبير.

تغيير نظام التشغيل

agent-operable codebase ليس مجرد lint أو أدوات. إنه تغيير نظام تشغيل قاعدة الكود.

كثيرون يعملون على جعل القطار أسرع. نماذج أكبر، وكلاء أذكى، مطالبات أفضل.

كلما أسرع القطار، زادت أهمية السكة. لا يكاد أحد يمد السكك بعد.

مقالات ذات صلة

• filefunc — مفهوم واحد لكل ملف — اتفاقية هيكلة كود تزيل تلوث سياق LLM بـ 22 قاعدة هيكلية
• tsma — خط دفاع الانحدار للكود القديم — أتمتة اختبارات قائمة على الـ ratchet تكمل 527 دالة حتى TODO 0
• لماذا تعمل وكلاء البرمجة ولماذا تنهار — تحليل هيكلي لـ Symbolic Feedback Loop
• طوبولوجيا التغذية الراجعة أهم من ذكاء النموذج — لماذا نفس النموذج يتوقف عند 40 أو يكمل 527
• whyso — ما لا يُظهره git blame — استخراج تلقائي لسجل التغييرات على مستوى الملف

المراجع

• Stanford, “Lost in the Middle: How Language Models Use Long Contexts” (2024) — انخفاض أداء بنسبة 30%+ عندما تُدفن المعلومات ذات الصلة في منتصف السياق
• Amazon, “Context Length Alone Hurts LLM Performance” (2025) — انخفاض أداء بنسبة 13.9–85% حتى عندما تكون الرموز غير الضرورية مسافات بيضاء
• دراسة حالة إطار عمل Hono — 186 ملفًا → 626 ملفًا، جميع الاختبارات البالغ عددها 4,419 نجحت
• دراسة حالة 527 دالة مع tsma — PASS 246 (46.7%)، DONE 281 (53.3%)، TODO 0
• تجربة Ratchet Pattern — وكيل مستقل 40/527 (7.6%) مقابل ratchet CLI 527/527 (100%)