بوابة جودة للارافيل بالذكاء الاصطناعي: التصميم

هذه ترجمة آلية لم تُراجَع بعد. الأصل الإنجليزي هو المرجع. اقرأ الأصل الإنجليزي

Claude Kit حزمة Composer تجهّز Claude Code على مشروع لارافيل بأمر تثبيت، وتضع الفحوص نفسها (PHPStan وPint وPest) عند الإيداع (commit) وفي نهاية كل دور من Claude وفي CI. الأولان يستدعيان سكربتًا واحدًا، أما CI المولَّد فيشغّل الأدوات نفسها مباشرة. يشرح هذا المقال كيف صُمّمت الحزمة، وأين تتوقف هذه الجملة عن أن تكون صحيحة.

المشكلة

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

المبدأ 1: سكربت واحد خلف الخطافات، والأدوات نفسها في CI

runtime/quality-checks.sh هو المصدر الوحيد للحقيقة للبوابة المحلية. وهو يشغّل:

• Pint في وضع الاختبار، إذا وُجد pint.json.
• PHPStan، إذا وُجد phpstan.neon، عند المستوى الذي اخترته، ولا يُسمح بأي خطأ.
• مشغّل اختباراتك، كما هو مسجّل في .claude/claude-kit.json. مع Pest وبرنامج تشغيل للتغطية يضيف --coverage --min=<threshold>. وبدون pcov أو Xdebug تعمل المجموعة مع ذلك ويُحذَّر من التغطية ولا تُفرض.
• فحوص الواجهة الأمامية، فقط للسكربتات التي يعرّفها package.json عندك: lint:check وformat:check وtypes:check.

خطاف git pre-commit وخطاف Stop في Claude كلاهما يستدعي السكربت، فالمعيار معرَّف مرة واحدة لهذين. أما CI فمسار منفصل: المسارات المولَّدة تشغّل بنفسها composer lint:check وcomposer types:check وphp artisan test --coverage --min=80 وفحوص الواجهة الأمامية. الأدوات هي نفسها، والحدود مكتوبة في ملفات المسارات، فتغيير ملف manifest عندك لا يغيّر CI من تلقاء نفسه.

CLAUDE_KIT_CHECKS يختار مجموعة جزئية من فحوص PHP (pint وphpstan وtests). وفحوص الواجهة الأمامية تعمل دائمًا، ويستخدم خطاف Stop الفحوص المدرجة في hooks.checks في manifest.

المبدأ 2: على الوكيل أن يجتاز أكثر من مرة

يشترط خطاف Stop عددًا hooks.min_passes من التشغيلات النظيفة المتتالية، بين 1 و5 والافتراضي 2، قبل أن يُسمح بإنهاء الدور. وأي فشل يوقف الحلقة فورًا، ويخرج بالرمز 2، ويعيد التقرير إلى Claude ليصلحه. سبب طلب أكثر من تشغيل نظيف أن الإصلاح قد يُدخل فشلًا جديدًا.

يحمل خطاف Stop أيضًا بوابة توثيق الميزات: أي تغيير تحت app/ أو database/ أو routes/ أو resources/js/ يجب أن يأتي معه مستند مضاف أو محدَّث تحت features/<name>/. وهذا يُبقي المستندات متسقة مع الشيفرة. ويمكن إيقافه بـ CLAUDE_KIT_FEATURE_DOCS=0.

وخطاف وقت التعديل الاختياري صريح في ما لا يستطيع فعله. خطاف PostToolUse يعمل بعد أن تعمل الأداة، فلا يستطيع منع التعديل ولا التراجع عنه. هذا ضمان من Claude Code، لا اختيار من Claude Kit. الوضع يحدد فقط من يعلم بالفشل: في وضع الحجب (block) تعود الأخطاء إلى Claude مع رمز الخروج 2، وفي وضع التحذير (warn) ترى تحذيرًا ولا يُقاطَع Claude. خطاف Stop هو ما يحجب الدور فعلًا.

المبدأ 3: الآلية يُشار إليها، والمحتوى يُنسخ

كل ما تشحنه الحزمة يقع في سلة من اثنتين.

• runtime/ يُشار إليه. يستدعيه المشروع المضيف في مكانه تحت vendor/، فيصلح composer update كل مشروع يستخدمه. ويُعامل كواجهة عامة (public API)، لأن خطاف Stop في المضيف يشير إلى هذه المسارات.
• stubs/ يُنسخ. CLAUDE.md والقواعد والمهارات والوكلاء وقوالب الميزات وإعدادات المدقّقات (linters) تُكتب في مستودعك، فتعدّلها بحرية.

يحدّث php artisan claude-kit:update المحتوى المنسوخ. يسجّل manifest تجزئة (hash) لكل ملف نشره، فالملف الذي لم يُمَس يُحدَّث بصمت، والملف الذي عدّلته لا يُستبدل دون سؤال، إلا إذا مرّرت --force. وخطاف PHPStan لوقت التعديل استثناء من «الآلية يُشار إليها»: فهو يُنسخ إلى مشروعك لأنه يُولَّد لكل مشروع.

المبدأ 4: لا تدُس على ما كتبه الآخرون

مساران للكتابة يجعلان الوعد ملموسًا.

install --force وupdate --force يستبدلان الملفات دون سؤال. ويُدمج composer.json وpackage.json ويُحتفظ بمدخلاتك. والجزء من CLAUDE.md الذي يملكه Claude Kit يقع بين علامتي claude-kit:begin وclaude-kit:end، فإعادة التشغيل تحدّثه دون المساس بإضافاتك.

المبدأ 5: المثبّت مُهيِّئ، وهو قابل للاختبار

طبقة الأوامر تملك كل سؤال. أما المثبّت وكاتب الملفات فلا يسألان أبدًا: يتلقيان إغلاقًا (closure) محلِّلًا ويستدعيانه حين يوجد ملف ويختلف. هذا الفصل يُبقي المولِّد قابلًا للاختبار على مجلد مؤقت. تصبح الخيارات كائن خيارات للقراءة فقط، ويمكن إعادة بناء الكائن نفسه من manifest للتحديث. والاختلافات بين الحزم التقنية (stacks) تقع غالبًا في مكان واحد، هو enum لحزمة الواجهة الأمامية. وإضافة حزمة تحتاج مدخلًا في enum ومجلد stub وملف قواعد وحالة في كاشف الحزمة.

يكتشف المثبّت حزمتك (Inertia مع Vue أو React، أو Livewire، أو Blade، أو API فقط)، ويسأل عمّا يُثبَّت، ويحدد الأدوات الدقيقة التي تحتاجها إجاباتك. ويعرض تشغيل الأمر composer require --dev أو يطبعه إن لم تقبل. ولا يحرّك أبدًا إصدارًا عندك أصلًا، ولا يضيف -W من تلقاء نفسه.

المبدأ 6: اختبارات معمارية مولَّدة تعمل فعلًا

اختر طبقات مثل services وrepositories وactions وcontracts، فيولّد Claude Kit الملف tests/Arch/ArchTest.php من أجزاء لكل طبقة. ثم يعدّل phpunit.xml عندك ليضيف مجموعة اختبارات tests/Arch، لأن اختبارًا مولَّدًا لا تشغّله أي مجموعة لا يحمي شيئًا. والطبقة التي ترفضها لا تأخذ قاعدة ولا اختبارًا معماريًا ولا ذكرًا في CLAUDE.md.

المفاضلات

• الأعراف افتراضات ذات رأي. يطلب README أن تقرأها وتكيّفها مع فريقك.
• الخطافات بقوة المضيف فقط. تعتمد البوابة المحلية على أن يحترم Claude Code رمز خروج خطاف Stop، وCI هو السند الاحتياطي. الاثنان معرَّفان على حدة، فأبقِ حدودهما متسقة.
• تعارض Pest على Laravel 13. فحص أُجري لهذا المقال في 2026-10-31 ثبّت هيكل Laravel 13 جديدًا، فحلّ PHPUnit 12.5.42. وفشل هناك composer require --dev pestphp/pest، حتى بدون Claude Kit. ومع -W استقر Composer على Pest 4.7.8 وPHPUnit 12.5.33. هذا التخفيض قرارك، ولا يتخذه Claude Kit عنك.
• توجد مخارج. git commit --no-verify يتجاوز البوابة المحلية. ولخفض حد التغطية غيّر tests.coverage_min في .claude/claude-kit.json (null تعني لا تفرض). والمتغير CLAUDE_KIT_MIN_COVERAGE احتياطي فقط للتثبيتات التي سبقت manifest. ويظل CI يفرض حدوده.

ما تحققت منه وما لم أتحقق منه

في 2026-10-31 قرأت README وdocs/Architecture.md وdocs/Quality-Gate.md وdocs/Configuration.md وسجل التغييرات وملفات المسارات المولَّدة وبنية المستودع. كما ثبّت مراجع لهذا المقال تطبيق Laravel 13 جديدًا وجرّب Pest عليه، ومن هنا أرقام Pest أعلاه. ويشغّل المستودع بوابته الخاصة عبر خطاف pre-commit مودَع، بما فيه قاعدة سجل التغييرات، ويقول التوثيق إن التغطية تُفرض عند 80% أو أكثر في CI.

لم أشغّل مثبّت Claude Kit على تطبيق Laravel جديد لهذا المقال، ولم أشغّل quality-checks.sh. السلوك الموصوف هنا مأخوذ من توثيق المشروع وملفاته. ومن أراد دليلًا فليشغّل الأوامر الموجودة في README على مشروع مؤقت. ولا يقول هذا المقال شيئًا عن وكلاء البرمجة الآخرين، لأنني لم أختبر أيًّا منهم.

ما الذي كنت سأفعله بشكل مختلف

1. أذكر تعارض Pest أولًا. المثبّت يشرحه أصلًا بعد فشل Composer (explainPestConflict). كنت سأقوله قبل عرض الأمر، حتى لا يقرأ أحد خطأ Composer أولًا.
2. أجعل CI يقرأ manifest. اليوم تحمل المسارات حدودها الخاصة. وقراءة .claude/claude-kit.json ستجعل الأماكن الثلاثة متفقة دون أن يتذكر أحد إبقاءها متسقة.

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

عن المشروع: Claude Kit.

Mohamed Ashraf Elsaed
قائد تقني في Convertedin، القاهرة. أبني أدوات لوكلاء البرمجة بالذكاء الاصطناعي وأكتب عن لارافيل وNode والهندسة.