# ثمانية خطافات تضمن موثوقية وكيل الذكاء الاصطناعي

> Author: Tony Lee
> Published: 2026-04-05
> URL: https://tonylee.im/ar/blog/eight-hooks-that-guarantee-ai-agent-reliability/
> Reading time: 4 minutes
> Language: ar
> Tags: claude-code, ai-agents, hooks, developer-tools, harness-engineering

## Canonical

https://tonylee.im/ar/blog/eight-hooks-that-guarantee-ai-agent-reliability/

## Rollout Alternates

en: https://tonylee.im/en/blog/eight-hooks-that-guarantee-ai-agent-reliability/
ko: https://tonylee.im/ko/blog/eight-hooks-that-guarantee-ai-agent-reliability/
ja: https://tonylee.im/ja/blog/eight-hooks-that-guarantee-ai-agent-reliability/
zh-CN: https://tonylee.im/zh-CN/blog/eight-hooks-that-guarantee-ai-agent-reliability/
zh-TW: https://tonylee.im/zh-TW/blog/eight-hooks-that-guarantee-ai-agent-reliability/

## Description

قواعد CLAUDE.md تُتّبع في حدود 80% من الأوقات. الخطافات تُتّبع 100% من الوقت. بعد ستة أشهر من الاختبار، هذه هي الثمانية التي لم أحذفها مرة واحدة.

## Summary

ثمانية خطافات تضمن موثوقية وكيل الذكاء الاصطناعي is part of Tony Lee's ongoing coverage of AI agents, developer tools, startup strategy, and AI industry shifts.

## Outline

- الحراس الأربعة قبل التنفيذ
- المفتشون الثلاثة بعد التنفيذ
- حفظ العمل حين يتوقف الوكيل
- ما لم يعمل بسلاسة
- الصورة الأشمل

## Content

ملف `CLAUDE.md` مجرد اقتراح. إذا كتبت "شغّل Prettier قبل الـ commit"، سيتجاهل الوكيل هذا التعليم مرة من كل ثلاث تقريباً. صياغة التعليمات بدقة أكبر لا تحل المشكلة. معدل الامتثال البالغ 80% ليس مشكلة في جودة النموذج، بل قيد هيكلي ينشأ من وضع القواعد داخل نافذة السياق والأمل في أن النموذج يلتزم بها.

الخطافات تعمل على مستوى مختلف تماماً. هي سكريبتات تُنفَّذ تلقائياً عند نقاط محددة في دورة الحياة، بصرف النظر عما يقرره النموذج. `PreToolUse` يُطلق قبل أن يعدّل الوكيل ملفاً أو يشغّل أمراً. `PostToolUse` يُطلق بعده مباشرة. النموذج لا يختار تشغيلها أو تجاهلها، فهي تعمل وكفى.

الفارق العملي واضح فوراً. إضافة عشرة أسطر من القواعد إلى `CLAUDE.md` شيء، وإضافة خطاف واحد إلى `.claude/settings.json` شيء آخر تماماً. رمز الخروج 2 يوقف عمل الوكيل في مكانه. رمز الخروج 0 يسمح له بالمتابعة. أي رمز آخر يسجّل تحذيراً دون إيقاف. ولأن الخطافات تعيش في `settings.json`، تلتزم بها بمجرد عملية commit واحدة ويحصل عليها الفريق بالكامل عبر git.

## الحراس الأربعة قبل التنفيذ

أشغّل الخطافات منذ أكثر من ستة أشهر. هذه الأربعة خطافات من نوع `PreToolUse` نجت في كل مشروع دون أن تُحذف مرة واحدة.

**حجب الأوامر الخطيرة** يرصد الأنماط المدمرة كـ`rm -rf` و`git reset --hard` و`DROP TABLE` عبر تطابق تعبيرات منتظمة، ثم يعيد رمز الخروج 2 لوقف العملية قبل حدوثها. رأيت وكلاء يحاولون تنفيذ `rm -rf` على مجلدات لا ينبغي لهم لمسها. بدون هذا الخطاف، كان الضرر سيكون حقيقياً.

**حماية الملفات الحساسة** يحجب أي محاولة تعديل على `.env` و`package-lock.json` و`*.pem` وما شابهها. الوكيل لن يحصل على فرصة الكتابة فوق ملف القفل أو تسريب بيانات الاعتماد داخل commit.

**اشتراط اجتياز الاختبارات قبل طلب المراجعة** يربط إنشاء pull request بنجاح الاختبارات. اضبط المطابق على `mcp__github__create_pull_request` ولن يستطيع الوكيل حرفياً فتح طلب مراجعة حتى تجتاز الاختبارات. لن تسمع "سأصلح الاختبارات لاحقاً" بعد الآن.

**تسجيل كل أمر** يكتب كل أمر bash يشغّله الوكيل في `.claude/command-log.txt` مع الطوابع الزمنية. بعد ثلاثة أيام حين يبدو شيء ما خاطئاً، يمكنك تتبع ما حدث بالضبط.

## المفتشون الثلاثة بعد التنفيذ

خطافات `PostToolUse` تعمل فور انتهاء الوكيل من تعديل ملف. أسلسل ثلاثة منها بالتتابع.

**التنسيق التلقائي** يشغّل Prettier على كل ملف مُعدَّل. لمشاريع Python استبدله بـBlack، ولـGo استخدم gofmt. المنسّق يعمل سواء تذكّر الوكيل التنسيق أم لا.

**الفحص التلقائي** يشغّل ESLint مباشرة بعد التنسيق. إذا اكتشف ESLint أخطاء، يراها الوكيل في الحال ويصلحها في نفس الجولة. عدد مشكلات الـlint التي تصل إلى مراجعة الكود البشرية يقترب من الصفر.

**الاختبار التلقائي** يشغّل مجموعة الاختبارات المرتبطة بعد كل تعديل على الملف. حين يفشل اختبار، يعلم الوكيل بذلك في ثوانٍ ويحاول الإصلاح. أمرر المخرجات عبر `tail -5` للاحتفاظ بالملخص فقط، مما يمنع مخرجات الاختبار من إغراق نافذة السياق.

الترتيب مهم. Prettier أولاً، ثم ESLint، ثم الاختبارات. بحلول الوقت الذي ينظر فيه إنسان إلى الكود، يكون التنسيق والفحص قد اجتازا بالفعل. تعليقات الأسلوب في مراجعة الكود تختفي.

## حفظ العمل حين يتوقف الوكيل

خطاف `Stop` واحد يتولى هذه المهمة: **الـcommit التلقائي** يشغّل `git add -A && git commit` في كل مرة ينهي فيها الوكيل رده. كل وحدة عمل تحصل على commit مستقل. لن تختلط مهمتان في commit واحد أبداً.

ادمج هذا مع git worktrees وستحصل على commits تلقائية على فروع الميزات. إذا تعطّل الوكيل أو قاطعته، لن تفقد آخر جزء من العمل.

## ما لم يعمل بسلاسة

تسلسل الخطافات يبدو أنيقاً على الورق، لكن تشخيص سلسلة فاشلة أصعب من تشخيص سكريبت واحد. حين بدأ خطاف الاختبار التلقائي يفشل بصمت لأن مشغّل الاختبار لم يكن مثبتاً في مشروع جديد، أمضيت ساعة أتتبع سبب إنتاج الوكيل لكود غير مختبر. الخطاف كان يعيد رمز الخروج 0 لأن السكريبت نفسه لم يُعثر عليه، والـshell عامل "command not found" كحالة غير حاجبة. اضطررت لإضافة فحص صريح لوجود مشغّل الاختبار قبل استدعائه.

الأداء قيد آخر. القلق الشائع هو أن الخطافات الكثيرة تُبطئ الأمور، لكن هذا ليس الوصف الدقيق. السؤال الحقيقي هو ما إذا كان كل خطاف منفرد ينتهي في أقل من 200 مللي ثانية. تشغيل Prettier على ملف واحد يأخذ نحو 50ms. فحص ESLint نحو 80ms. الاختبارات تتفاوت، لكن تضييق النطاق على الملفات المتأثرة يُبقي معظم التشغيلات سريعة. إذا أخذ أي خطاف منفرد أكثر من ثانية، بدأت حلقة تغذية راجعة الوكيل تبدو بطيئة.

## الصورة الأشمل

مقالة هندسة الـHarness لـOpenAI أشارت إلى أن الوكلاء يعملون بأفضل حالاتهم داخل حدود صارمة وهيكل متوقع. فلسفة تصميم React تقول الشيء ذاته عن المكوّنات: وحدات قابلة للتركيب بمراحل دورة حياة محددة وحالة واضحة.

الخطافات في Claude Code تتبع نفس المبدأ. الحالة تقابل الجلسات والذاكرة. الخطافات هي الدوال التي تتدخل عند حدود دورة الحياة. `PreToolUse` يرسم الحدود. `PostToolUse` يجعل الهيكل متوقعاً. `Stop` يحفظ النتيجة.

السطر الذي كنت أضعه في `CLAUDE.md` لتشغيل Prettier اختفى. الخطاف يشغّله في كل مرة، دون أن يُطلب منه ذلك.

## Related URLs

- Author: https://tonylee.im/en/author/
- Publication: https://tonylee.im/en/blog/about/
- Related article: https://tonylee.im/ar/blog/claude-code-layers-over-tools-2026/
- Related article: https://tonylee.im/ar/blog/codex-folder-structure-why-config-breaks/
- Related article: https://tonylee.im/ar/blog/codex-inside-claude-code-openai-plugin-strategy/

## Citation

- Author: Tony Lee
- Site: tonylee.im
- Canonical URL: https://tonylee.im/ar/blog/eight-hooks-that-guarantee-ai-agent-reliability/

## Bot Guidance

- This file is intended for AI agents, search assistants, and text-mode retrieval.
- Prefer citing the canonical article URL instead of this text endpoint.
- Use the rollout alternates when you need the same article in another prioritized language.

---

Author: Tony Lee | Website: https://tonylee.im
For more articles, visit: https://tonylee.im/ar/blog/
This content is original and authored by Tony Lee. Please attribute when quoting or referencing.