# لماذا يهلوس وكلاء البرمجة بالذكاء الاصطناعي بمسارات الملفات

Canonical source: https://maguyva.ai/ar/blog/why-ai-coding-agents-hallucinate-file-paths

License: text under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/); code samples under [MIT-0](https://opensource.org/license/mit-0); the Maguyva name, logos, brand assets and other code are not covered. Details: [maguyva.ai/license](https://maguyva.ai/license).

Date: 2026-08-14 · Author: Maguyva Team

> يخترع وكلاء البرمجة بالذكاء الاصطناعي مسارات ملفات عندما لا يمتلكون خريطة حقيقية للمستودع. إليك سبب حدوث ذلك، وكيف تؤدي خريطة مدعومة بالأدلة إلى تغييرات أقل هلوسة.

العلامة ليست جسم دالة خاطئ. إنها تغيير واثق على ملف غير موجود، أو على ملف موجود لكنه ليس الملف الذي ينفّذ ذلك السلوك.

طلبت إصلاح انتهاء صلاحية الجلسة. يفتح الوكيل `src/auth/session.ts`. المسار معقول. إنه خاطئ أيضًا. المعالج الفعلي يعيش في `apps/api/src/middleware/expiry.ts`، الذي أُعيدت تسميته منذ عمليتي إعادة هيكلة. الوكيل لا يكذب عليك. إنه يكمل سلسلة نصية بشكل مسار بناءً على تحيز التدريب بالإضافة إلى أي شيء موجود بالفعل في نافذة السياق.

هذا نمط فشل شائع على المستودعات الحقيقية. يستطيع النموذج كتابة الكود. خطؤه هو اختيار المكان الخاطئ لكتابته.

## لماذا يخترع الوكلاء المسارات

وكلاء البرمجة هم نماذج تنبؤ بالرمز التالي مزودة بأدوات. عندما تقول 'أصلح انتهاء صلاحية الجلسة'، يجب أن يسمّي ملفًا قبل أن يتمكن من قراءة أو تصحيح أي شيء. إذا لم يكن لديه بعد خريطة مدعومة بالأدلة، فإنه يبني المسار من:

1. أعراف التسمية التي رآها في مستودعات أخرى. `src/auth/session.ts` شكل شائع.
2. الملفات الموجودة بالفعل في المحادثة، والتي قد تكون الملف الذي ألصقته الأسبوع الماضي، وليس الذي يهم الآن.
3. قائمة دليل شغّلها بالصدفة، غير مكتملة على شجرة كبيرة.
4. ملفات التعليمات. `CLAUDE.md` و`AGENTS.md` تخبر الوكيل كيف يتصرف. إنها ليست فهرسًا حيًا للرموز أو المستدعين أو المسارات الحالية.

ما من مصدر من هذه هو خريطة هذا المستودع، اليوم. يملأ النموذج الفجوة بنفس الطريقة التي يملأ بها أي فجوة: باستمرارية عالية الاحتمال. غالبًا ما تبدو تلك الاستمرارية كمسار حقيقي. أحيانًا يكون الملف موجودًا ويقع في الحي الصحيح. أحيانًا يكون موجودًا على فرع دُمج الشهر الماضي. أحيانًا لم يكن موجودًا أبدًا.

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

قراءة الملفات أيضًا ليست نفس الشيء مثل العثور على الملف الصحيح. يمكن لـ Claude Code وCursor وCodex وأدوات مماثلة فتح أي شيء تشير إليه. السؤال هو ما إذا كانت تجد بشكل موثوق الملف الصحيح، والرمز المهم، والتبعيات، والاختبارات، ونطاق التأثير قبل التحرير. الوصول إلى الملفات دون خريطة لا يزال يبدأ بالتخمين.

## تحرير الملف الخاطئ مشكلة استرجاع

فكّر في المسار المُخترَع كخطأ استرجاع، وليس عيبًا في الشخصية.

إذا كان على الوكيل إعادة `path/file.ext:line` قبل السماح له بالتحرير، سيحدث شيئان. أولًا، يمكنك فتح الاقتباس ورفض العمل في عشر ثوانٍ. ثانيًا، يجب على الوكيل أن يستعلم شيئًا يعرف تلك الشجرة فعليًا.

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

Maguyva هي تلك الطبقة لوكلاء البرمجة المتوافقين مع MCP. إنها ليست محررًا. تبقى Claude Code وCursor وCodex CLI وVS Code وWindsurf وعملاء MCP الآخرون في مكانهم. يستعلم الوكيل الخريطة المُصنَّفة قبل لمس سطر واحد.

المُدَّعى بسيط عمدًا: تغييرات أقل هلوسة. لا تنزع Maguyva قدرة التخمين من النموذج. إنها تحوّل الخطوة الأولى الافتراضية من 'اخترع مسارًا معقولًا' إلى 'اطلب موقعًا مُصنَّفًا ومقتبسًا'.

## كيف تبدو الإجابة المدعومة بالأدلة

الإجابة المفيدة على 'أين تُعالَج مهلة انتهاء الجلسة' ليست فقرة واحدة. إنها قائمة مواقع قصيرة:

- `apps/api/src/middleware/expiry.ts:48` - المعالج
- `apps/web/src/lib/auth-client.ts:112` - المستدعي
- `apps/api/tests/expiry.test.ts:20` - الاختبار الذي سيفشل إذا كان التغيير خاطئًا

يمكنك فتح هذه الأسطر. إذا كانت خاطئة، تتوقف. إذا كانت صحيحة، يمكن للوكيل التحرير. التحقق هو صلب الأمر، وليس شعارًا.

تكشف Maguyva عن 11 أداة MCP موجهة للعملاء عبر البحث والرموز وتحليل التبعيات واسترجاع الملفات وسياق المستودع وسير عمل الأدوات المساعدة الحتمية. تجتمع أربعة أنماط استرجاع (دلالي، وبنيوي، ورسم بياني/تبعيات، ونصي) في نتيجة واحدة مُصنَّفة؛ البحث عن الرموز أداة MCP منفصلة (`find_symbol`). تعود الإجابات المدعومة بالأدلة بمسارات ملفات وأرقام أسطر، حتى تتمكن من تقييمها مقابل الشجرة أمامك.

[الوثائق](/ar/docs) تصف أقصر مسار: ابدأ مجانًا، فهرس مستودعًا تعرفه بالفعل، اربط العميل، ثم اطرح سؤالًا واحدًا يمكنك التحقق منه.

## الحلقة التي تغيّر التغيير الأول

لست بحاجة إلى دين سير عمل جديد. تحتاج إلى خطوة إضافية واحدة قبل الكتابة الأولى.

1. اطرح سؤالًا واحدًا يمكنك تقييمه بالفعل. 'أي كود يعالج تسجيل الدخول وانتهاء صلاحية الجلسة؟' أفضل من 'أصلح المصادقة'.
2. طالب بالاقتباسات. مسار الملف ورقم السطر، وليس ملخصًا لـ 'وحدة المصادقة'.
3. افتح الملف المقتبس. تتبّع الرمز. تحقق من التبعيات التي أنت على وشك لمسها.
4. لا تدع الوكيل يصحّح إلا بعد ذلك.

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

لا تزال ملفات التعليمات مهمة. حافظ عليها. استخدمها للأعراف وقواعد المراجعة وما ينبغي عدم لمسه. لا تطلب منها أن تكون فهرسًا. `CLAUDE.md` الذي يسرد ثلاثة أدلة مهمة سيصبح قديمًا بعد أسبوع من تقسيم حزمة. الخريطة القابلة للاستعلام تُحدَّث عند تحديث المستودع.

فشل ذو صلة هو الملف شبه الصحيح: يفتح الوكيل `auth.ts` بينما يعيش السلوك في `auth-client.ts`، أو يصحّح ملفًا مُولَّدًا بدلًا من المصدر، أو يحرّر نسخة في `packages/legacy` لأن الاسم يتطابق. لا تجعل الاقتباسات هذه الأخطاء مستحيلة. إنها تجعلها مرئية قبل استقرار التغيير.

## ما لن تُصلحه الخريطة لك

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

ما يمكنك توقعه أضيق وأكثر فائدة: يتوقف الوكيل عن بدء تغييره بمسار مُخمَّن. تلك الخطوة الأولى تصبح مدعومة بالأدلة في خريطة حقيقية، ومن هناك تأتي التغييرات الأقل هلوسة. كل شيء بعد الاقتباس — قراءة التغيير، تقييم الرقعة — لا يزال عملك، كما كان دائمًا.

هذا الاختبار لا يكاد يكلفك شيئًا: فهرس مستودعًا تعرفه بالفعل واطرح سؤالًا واحدًا يمكنك التحقق منه. ابدأ بالمسار الذي أحرقك سابقًا. إذا كان الاقتباس خاطئًا، سترى ذلك فورًا. إذا كان صحيحًا، فإن تغيير وكيلك التالي لديه مكان أفضل للاستقرار فيه.

`// it doesn't know the file. it knows how to find it.`