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

ما هي قابلية مراقبة وكيل الذكاء الاصطناعي

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

المشكلة نظامية. الوكيل نفسه قد يقول «تم» بصدق عشر مرات في أسبوع، وفي كل مرة تعني الكلمة شيئًا مختلفًا: في مرة اجتازت كل الاختبارات، وفي أخرى اختبار واحد، وفي ثالثة لا شيء. وكلما تقدم عمر المشروع أصبحت كل جلسة جديدة أغلى، لأنها تبدأ بالتنقيب.

طبقتان: التشغيل والعملية

يُخلط بين قابلية المراقبة والسجلات، لكن السجلات نصف الصورة فقط.

طبقة التشغيل وحدها: نرى ما الذي تعطل، لكن لا نعرف ماذا كنا نريد. طبقة العملية وحدها: نعرف ماذا أردنا، لكن لا نرى لماذا لم ينجح. نحتاج الاثنتين.

لماذا لا يفعل الوكيل ذلك بنفسه

قول الوكيل «سجّل بشكل أفضل» لن ينفع لثلاثة أسباب.

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

لذلك تُزرع قابلية المراقبة في الهارنس، أي في بيئة الوكيل: القوالب، والهوكس، والسكربتات، وصيغة التقرير الإلزامية.

ما الذي تسجله: الحد الأدنى

السجل الجيد ليس تسجيلًا لكل شيء، بل مجموعة من الحقائق تكفي لاستعادة سير العمل وحساب الإحصاءات.

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

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

سجل الأفعال عبر هوكس Claude Code

في Claude Code يُفضَّل إدارة السجل بالهوكس، وهي أوامر تشغّلها الأداة نفسها لا النموذج، لذلك تعمل دائمًا. يتلقى الهوك JSON يصف الحدث، يتضمن معرّف الجلسة واسم الأداة ومعاملاتها. مثال إعداد في .claude/settings.json يضيف بعد كل استدعاء لـ Bash أو Edit أو Write سطرًا إلى السجل:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Bash|Edit|Write",
        "hooks": [
          { "type": "command", "command": ".claude/hooks/log-action.sh" }
        ]
      }
    ]
  }
}

#!/usr/bin/env bash
# .claude/hooks/log-action.sh — سطر JSON واحد لكل فعل
mkdir -p .agent/logs
jq -c '{ts: (now | todate), session: .session_id, tool: .tool_name,
        cmd: .tool_input.command, file: .tool_input.file_path}' \
  >> .agent/logs/actions.jsonl || true

صيغة JSONL (سجل JSON واحد في كل سطر) مريحة لأنها سهلة التصفية بـ jq ويمكن تحميلها في أي نظام تحليل. إضافة إلى ذلك يحفظ Claude Code محليًا تاريخ الجلسات الكامل في المجلد ~/.claude/projects/، ويمكن فتحه لرؤية الاستدلال والمخرجات كاملة، لكن للإحصاءات يكون سجلك المضغوط أنسب.

التتبع: trace لكل جلسة وspan لكل مهمة

عندما تكثر الوكلاء أو يعملون وفق جدول زمني، لا تكفي السجلات النصية، وتلزم التجميعات. هنا تفيد أدوات التتبع الموزع المعتادة ومعيار OpenTelemetry.

• Trace — جلسة واحدة للوكيل.
• Span — مهمة واحدة داخل الجلسة.
• Span متداخلة — خطوات التحقق: البناء والاختبارات وe2e.

الحد الأدنى من السمات لكل span: معرّف الميزة والجلسة، والنموذج، ونتيجة الفحص، والتوكنات، وعدد المحاولات. تُقرأ هذه البيانات في Jaeger أو Grafana Tempo أو Honeycomb، وتجيب عن أسئلة لا تظهر داخل جلسة واحدة: أي نوع من المهام يحتاج إعادة محاولات أكثر، وأين يستهلك الوكيل معظم التوكنات، وبعد أي تغيير في الهارنس انخفضت نسبة المهام المقبولة. ولدى Claude Code تصدير مدمج للمقاييس والأحداث عبر OpenTelemetry، يُفعَّل بمتغيرات البيئة، والتفاصيل في توثيق الأداة.

الـ commits كسجل

أرخص سجل وأكثرها موثوقية موجود لديك بالفعل: git. كل ما يلزم هو أن تجعله مقروءًا.

1. commit واحد لكل مهمة. عندها يتطابق git log مع قائمة المنجز، وإلغاء المهمة يكون بـ git revert واحد.
2. في الرسالة: ما الذي تغيّر وكيف جرى التحقق. لا تكتب «fix» بل «ما الذي عُدّل ولماذا وبأي أمر جرى التحقق».
3. commit فقط بعد فحص أخضر. عندها كل نقطة في التاريخ حالة صالحة للعمل، ويجد git bisect المتسبب.

fix(payments): تقريب الخصم إلى القروش

كان الخصم يُحسب بـ float، فتضيع قرش على مبلغ 999.99.
نقلت الحساب إلى int بالقروش.
تحقق: make test (142 passed)، make e2e checkout — ok.
خارج النطاق: التقريب في التقارير، سُجّل في BACKLOG.md.

تقرير الوكيل: أدلة بدل الانطباعات

الرسالة النهائية للوكيل أيضًا أثر من آثار المراقبة إذا كان شكلها ثابتًا. اكتب القالب في AGENTS.md أو CLAUDE.md:

## تقرير في نهاية المهمة
- ما الذي أُنجز: قائمة التغييرات (الملف — المضمون)
- كيف جرى التحقق: الأوامر الدقيقة ونتيجتها
- ما الذي لم يُتحقق منه ولماذا
- انحرافات عن اتفاق المهمة
- أسئلة مفتوحة للإنسان

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

الاتفاق قبل الكود والمعيار بعده

الطبقة العملية تبدأ قبل العمل. اتفاق قصير على المهمة (sprint contract) يحدد النطاق ومعايير القبول وقسم «خارج النطاق» والأسئلة المفتوحة التي يحسمها الإنسان. قسم «خارج النطاق» يمنع نصف الخلافات حول النتيجة.

بعد العمل تُقيَّم النتيجة وفق معيار، لا وفق انطباع. وإلا فإن مراجعَين خبيرين سيصدران حكمين مختلفين، ويصبح التقييم قرعة.

يُقيَّم كل بُعد بالدرجات A/B/C/D، والتقييم بلا رابط دليل لاغٍ. قاعدة القرار البسيطة: درجة D واحدة أو درجتان C — ترفض العمل مع قائمة بما يجب إصلاحه. ويمكن لوكيل مدقق مستقل أن يطبّق المعيار نفسه.

كيف تفحص ما فعله الوكيل في الجلسة

إذا لم يكن هناك تقرير، أو لم تثق به، فمرّ على الآثار بهذا الترتيب.

1. حالة الشجرة: git status — ما الذي لم يُلتزم به، وهل توجد ملفات مهملات.
2. التاريخ: git log --stat منذ بداية الجلسة — أي commits وأي ملفات.
3. حجم التغييرات: git diff --stat main...HEAD، ثم الفرق الكامل للملفات المهمة.
4. سجل الأفعال: أي أوامر شُغّلت، وماذا أعادت الفحوص.
5. إعادة التحقق: شغّل البناء والاختبارات بنفسك. ثق بمخرج الأمر لا بإعادة سرد الوكيل.

# أي أوامر شغّلها الوكيل في آخر جلسة
jq -r 'select(.tool=="Bash") | .cmd' .agent/logs/actions.jsonl | tail -n 30
# أي الملفات عُدّلت أكثر من غيرها
jq -r '.file // empty' .agent/logs/actions.jsonl | sort | uniq -c | sort -rn | head

الأخطاء الشائعة

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

الخلاصة

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