كيف تكتب وكلاء Claude Code لا يكذبون عليك

طلبت من Claude Code أن ينفّذ هذا التصميم ويتحقق من مطابقته لماكيت Figma. فعاد قائلاً: تمّ. كل الأقسام مطابقة، والمسافات صحيحة، والألوان سليمة. فتحتَ الصفحة. نصف المسافات كان خاطئاً. حالة الـ hover لم تكن موجودة أصلاً. الأزرار كانت مزاحة بدرجة لونية. لم يكذب النموذج بسوء نية، بل توقّع أنك تريد أن تسمع كلمة تمّ التحقق، فأنتج تلك السلسلة من الرموز بالضبط. لم تكن هناك خطوة تحقق. ولم يكن بالإمكان أن تكون هناك واحدة أصلاً، فالتحقق يتطلب مقارنة بالحقيقة المرجعية، ووكيل واحد داخل سياق واحد لا يملك أي وسيلة للخروج من إجابته والتدقيق فيها.

قاعدتان حوّلتا لديّ سير عمل مليئة بالهلوسة إلى خطوط معالجة موثوقة: وكيل واحد، تخصص واحد، وكل ما يمكن تنفيذه كأمر shell يجب تنفيذه كأمر shell. هذه ليست نظرية. هذا ما أفعله يومياً مع Claude Code، وهذه هي الأنماط التي تُحدث فرقاً حقيقياً.

لماذا يكذب الوكلاء العامّون

نماذج LLM أدوات تتنبأ بالرمز التالي. حين يطلب المُوجِّه دورين — ابنِ X وتحقق من X — ينهي النموذج الدور الأول، ثم يتنبأ بالشكل الذي سيبدو عليه ناتج الدور الثاني، دون أن ينفّذه فعلاً. التحقق الذاتي ضعيف بنيوياً: السياق نفسه، النموذج نفسه، النقاط العمياء نفسها. نجاح التحقق مرتبط بـنجاح البناء، فهما يفشلان معاً.

لا يعرف النموذج أنه يكذب. من منظوره، فإن سرد جملة تحققتُ من كل شيء بعناية امتداد متماسك لكونه كتب الشيفرة. وهذا هو السبب نفسه الذي يجعل مُوجِّهات مثل هل أنت متأكد؟ لا تلتقط الهلوسات: النموذج على القدر نفسه من الثقة في المرور الثاني. الثقة ليست مرتبطة بالصحة، بل بمدى معقولية وقع الجملة التالية.

الحل ليس أوامر أفضل. عبارات مثل كن حذراً ودقّق مرة أخرى ولا تهلوس لا تفعل شيئاً. الحل بنيوي: خصّص الوكيل بحيث يعجز عملياً عن التظاهر، ومرّر العمل الكمّي عبر الـ shell كي تأتي الإجابة من حالة حقيقية، لا من احتمالية الرموز.

القاعدة 1: وكيل واحد، تخصص واحد

قسّم العمل إلى وكلاء منفصلين بسياقات منفصلة. لكل وكيل مسؤولية واحدة ومجموعة أدوات ضيّقة. يتحول سير العمل بأكمله إلى سباق تتابع بدل وكيل واحد يدور في حلقات:

• وكيل البناء (Builder): يأخذ المواصفة، ويكتب الشيفرة. هذه مهمته كلها. لديه Read وEdit وWrite وBash.
• وكيل المراجعة (Reviewer): يأخذ المواصفة مع الـ diff، ويفحص معايير القبول. سياق جديد. لا علم له بـكيف كُتبت الشيفرة، بل بما نتج فقط. لديه Bash وRead وGrep وGlob — ولا أدوات كتابة على الإطلاق.
• وكيل التحليلات (Analytics): يجيب عن أسئلة البيانات ببناء الاستعلامات وتشغيلها. Bash فقط. لا يمكنه بلوغ الإجابة دون تشغيل أمر حقيقي.
• المنسّق (Orchestrator): الجلسة الرئيسية التي تُرسل كل وكيل بدوره ولا تطلب من وكيل قط أن يؤدي عمل وكيل آخر.

مثال ملموس: تنفيذ واجهة مستخدم مع فحص بصري مقابل ماكيت Figma. يكتب وكيل البناء المكونات ويُودع الـ diff. ثم يستدعي المنسّق وكيل المراجعة مزوّداً إياه برابط التصميم والـ diff ومعايير قبول صريحة. يشغّل وكيل المراجعة أداة Playwright، ويلتقط لقطات الشاشة، ويقارنها بالمرجع، ويعيد PASS أو FAIL مع مسارات لقطات الشاشة الفعلية وفروق البكسل. لا يقترب وكيل البناء من خطوة التحقق أبداً، وهذا بالضبط ما يجعل التحقق حقيقياً.

النمط المضاد هو الوكيل العملاق: مُوجِّه واحد يقول ابنِ هذه الواجهة وتأكد من مطابقتها للماكيت. أضمن لك أنه سيبلّغ بأن كل شيء مطابق. لن يكون كذلك. سردية لقد تحققت ليست إلا أرجح سلسلة رموز تأتي بعد لقد بنيته.

القاعدة 2: الـ shell بدل المُوجِّه، دائماً

كل ما هو كمّي، وكل ما يمسّ حالة حقيقية، وكل ما قد تكون فيه الإجابة خاطئة بشكل يبدو صحيحاً — مرّره عبر sh. مهمة الوكيل أن يبني الأمر ويشغّله، ثم يقرأ ناتجه. الوكيل ليس مصدر الحقيقة. ناتج الـ shell هو المصدر.

• العدّ: wc -l logs.txt حقيقة. أما هناك نحو 47 سطر سجل صادرة عن نموذج فهي هلوسة.
• التحليلات: psql -c "SELECT count(*) FROM events WHERE created_at > now() - interval '30 days'". وليس قدّر الحجم.
• الاختبارات: pnpm test --reporter=json | jq '.numFailedTests'. وليس لخّص ما فشل.
• حالة Git: git rev-list --count main..HEAD، git diff --stat. وليس عُدّ الإيداعات أو صِف التغييرات.

حين تستوعب هذا، تبدأ بملاحظة كل موضع كان الوكيل فيه على وشك اختلاق رقم. يبدو أن هناك قرابة 200 سجل... — لا. شغّل SELECT count(*). معظم الاختبارات تمر... — لا. شغّل حزمة الاختبارات، وحلّل الـ JSON. النموذج بارع في بناء الأمر. لكنه غير موثوق في أن يكون هو الأمر نفسه.

أنماط فشل واجهتها فعلاً

هذه ليست حالات افتراضية. كلّ منها كلّفني وقتاً حقيقياً قبل أن أغيّر النمط:

• تحقق وهمي. قال الوكيل فحصتُ الأقسام الـ 14 كلها مقابل الماكيت. لم يفتح الماكيت. لم يلتقط لقطة شاشة. كان الفحص خطوة مهلوَسة في السرد.
• أرقام خاطئة بثقة. طلبت المستخدمين النشطين شهرياً من بيانات التحليلات. فحصلت على رقم مخطئ بنحو 3 أضعاف. استوفى النموذج القيمة من صفوف عيّنة بدل تشغيل الاستعلام الفعلي.
• تغييرات ملفات مختلقة. قال الوكيل حدّثتُ config/feature-flags.json. لم يفعل. كان قد نوى ذلك فحسب. وكان git diff فارغاً.
• تشغيلات اختبار زائفة. كل الاختبارات تمر. لم يُنفَّذ أي اختبار. لم يستدعِ الوكيل مشغّل الاختبارات قط، بل تنبأ بالشكل الذي كان سيبدو عليه ناتج المشغّل.

الأربعة كلها تُحلّ بالقاعدتين نفسيهما: قسّم الوكيل، وادفع إلى الـ shell. لا يملك وكيل المراجعة Write، فلا يمكنه تزييف تعديل الملفات. ولا يملك وكيل التحليلات سوى Bash، فلا يمكنه إعادة رقم لم يأتِ من استعلام. الاستحالة البنيوية تغلب النوايا الحسنة في كل مرة.

كيف تُبنى هذه في Claude Code

يدعم Claude Code الوكلاء الفرعيين المعرّفين في .claude/agents/*.md. يعلن كل ملف وكيل عن اسم ووصف ومجموعة أدوات مسموحة ومُوجِّه النظام. يستدعيهم المنسّق (جلستك الرئيسية) عبر أداة Agent. وهذا نوع التعريف الذي أستخدمه لوكيل المراجعة — قصير، ضيّق، وعاجز عملياً عن كتابة الشيفرة:

---
name: reviewer
description: Reviews a diff against acceptance criteria. Cannot edit code.
tools: Bash, Read, Grep, Glob
---

You are a strict code reviewer. You receive:
- A diff (already produced by the builder)
- Acceptance criteria

Your job:
1. Run the build, the tests, the linter — through Bash.
2. Read the changed files directly.
3. Compare the actual behavior to the criteria.
4. Report PASS or FAIL with concrete evidence (command output, file excerpts).

You must NOT:
- Trust the builder's summary
- Assume anything was verified just because it was claimed
- Mark something PASS without running the actual check

لاحظ مجموعة الأدوات: Bash, Read, Grep, Glob. لا Write، ولا Edit، ولا Agent. يستطيع وكيل المراجعة تشغيل الأوامر وقراءة الملفات والبحث عن الأنماط — لا غير. وإن حاول تمرير diff مهلوَس على أنه مُتحقَّق منه، فإن شكل استدعاءات أدواته يفضح الأمر: لم تكن هناك أي فحوصات حقيقية. يمكنك تدقيق استدعاءات الأدوات ورؤية ما جرى فحصه بالضبط.

نمط التنسيق: تستدعي الجلسة الرئيسية وكيل البناء ← تنتظر ← تشغّل هي نفسها git diff لالتقاط التغيير الفعلي ← تستدعي وكيل المراجعة بالمواصفة والـ diff ← تقرأ الحكم. لا تطلب الجلسة الرئيسية قط من وكيل واحد أن يؤدي الدورين. قيود الأدوات أقوى من تعليمات المُوجِّه: لا تزيّف التحقق أمنية. وأما عدم امتلاك Write فحقيقة.

أنماط مضادة يجب التخلص منها

أشياء أراها في المُوجِّهات ولا تفعل شيئاً — أو أسوأ، تمنح إحساساً زائفاً بالأمان:

• كن حذراً ودقّق في عملك مرة أخرى. لا يولّد أي سلوك إضافي. النموذج ينتج أصلاً ما يبدو كعمل دقيق.
• تأكد من أنك تحققت فعلاً. كلمة فعلاً لا تضيف دلالة يستطيع النموذج التصرف بناءً عليها. سيدّعي فعلاً أنه تحقق.
• لا تهلوس. نكتة رائجة في هندسة المُوجِّهات. الهلوسة ليست مفتاحاً يستطيع النموذج إطفاءه.
• الثقة بالوكيل في الأرقام الصغيرة. في الأرقام الصغيرة تحديداً يكذب بأشد ثقة. لا يوجد حدّ أدنى للصدق.
• إضافة قواعد أكثر إلى المُوجِّه لفرض الصدق. الإصلاحات البنيوية (التقسيم + الـ shell) تغلب تعديلات الأوامر في كل مرة. إن كانت قاعدة تحتاج إلى إنفاذ، فرمّزها في صلاحيات الأدوات، لا في لغة بشرية.

إن كانت استراتيجيتك لالتقاط الهلوسات هي صياغة أشد توكيداً، فليست لديك استراتيجية. لديك أمنية.

النموذج الذهني

الوكيل ليس زميلاً. إنه دالة: prompt → tokens. الدالة بارعة في كتابة الشيفرة وسيئة في التأمل الذاتي حول ما إذا فعلت الصواب. عامِل ادّعاءاته عن عمله بوصفها فرضية. الـ diff، ورمز الخروج، ولقطة الشاشة، وعدد الصفوف — تلك هي الأدلة. أما ملخّص نهاية الدور فهو السطح الأكثر عرضة للكذب في المنظومة كلها.

التخصص هو تأمينك ضد انحراف السرد. الـ shell هو مصدر الحقيقة الوحيد لديك. وكيل البناء يكتب. وكيل المراجعة يفحص. والـ Bash يقرّر.

الخلاصة

إن حفظت شيئاً واحداً: لا تدع وكيلاً واحداً يُنتج ناتجه ويحكم عليه في آنٍ، ولا تدع أي وكيل يجيب عن سؤال كمّي دون تشغيل أمر. كل ما عدا ذلك متفرّع عن هاتين القاعدتين. اضبط صلاحيات الأدوات بحزم، ودقّق استدعاءات الأدوات بدل الملخّصات، عندها ينكمش سطح الهلوسة من كل مكان إلى بضعة مواضع محددة تعرف مسبقاً أن تنظر إليها.