فرض قواعد وكلاء البرمجة على كل تعديل باستعمال Abide

شنو كيدير Abide

Abide كيفرض التعليمات الخاصة بالمشروع اللي ما كيقدروش اللينترات العاديين يقيّموها بشكل موثوق. هاد التعليمات تقدر تكون فملفات بحال AGENTS.md ولا CLAUDE.md، وكتشمل قواعد بحال استعمل Yup بلاصة التحقّق اليدوي، ما تنشئش مساعد عندو مستعمل واحد غير، ولا عمرك تكشف خطأ خام للمستخدم.

من بعد كل تعديل ولا نهاية كل دورة، Abide كيبعث القاعدة المعنية والفرق ديال الكود لـ نموذج القرار Jev ديال TypeSafe. Jev كيرجع احتمال وماشي نص حر. إلا كان الاحتمال كيشير لخرق، Abide كيعلم وكيل البرمجة شنو هي القاعدة اللي تخرقات وكيطلب منو يصلّح الكود فنفس الدورة.

Jev كيشوف القاعدة والفرق، وما كيشوفش المحادثة ديال الوكيل. بهاد الطريقة، Abide كيطبّق نفس الفحوصات باستمرار خلال جلسة برمجة طويلة. حسب اختبار إعادة التشغيل المنشور ديال المستودع، الفحوصات كتحتاج تقريباً 300 ميلي ثانية فـ Jev، بينما الخطاف كامل كياخذ تقريباً ثانية وحدة ملي كنحسبو تشغيل Node.

الميزات الرئيسية

• فحوصات التعديلات التلقائية: القواعد تقدر تخدم مباشرة من بعد كل تعديل فالكود.
• فحوصات على مستوى الدورة: القواعد اللي كتحتاج الفرق الكامل ديال المهمة تقدر تخدم مرة وحدة فآخر الدورة.
• الاندماج مع الوكلاء: Abide كيدعم Claude Code وCodex وOpenCode.
• معيار مملوك للمستودع: القواعد المجمّعة كتتخزّن فملف .abide/rubric.json المقروء والسهل فالمراجعة والـ commit.
• قواعد محددة النطاق: القاعدة تقدر تستعمل نطاقات glob باش تطبّق أسئلة مختلفة على مسارات API ولا ملفات الأنماط ولا مجموعات أخرى ديال الملفات.
• مراجعة الكود الموجود: Abide يقدر يقيّم الملفات بحال إلا تكتبات دابا.
• المعايرة والضبط: يقدر يختبر القواعد على تاريخ Git الحديث، يعطّل القواعد غير الفعّالة، ويساعد فإعادة كتابة القواعد اللي ما كتخدمش أبداً.
• خطافات كتفتح عند الفشل: بيانات الدخول الناقصة، ومشاكل الشبكة، وأخطاء الخطافات ما كيوقفوش جلسة البرمجة.
• ما كايناش سياسة مضمّنة: Abide كيفرض القواعد المستخرجة من ملفات التعليمات ديالك، وما كيفرضش مجموعة قواعد محددة مسبقاً.

المتطلبات الأساسية

خاصك مستودع فيه تعليمات لوكيل البرمجة ديالك، وعلى الأقل وكيل واحد مدعوم: Claude Code ولا Codex ولا OpenCode. وخصك حتى مفتاح API ديال TypeSafe من typesafe.ai. كبديل، Abide يقدر يستعمل مفتاح موجود ديال Vercel AI Gateway عبر متغير البيئة AI_GATEWAY_API_KEY.

تثبيت Abide وإعداده

الخطوة 1: خزّن مفتاح API ديالك

شغّل أمر تسجيل الدخول ولسّق مفتاح TypeSafe ديالك ملي يطلبو منك:

npx @coldtea/abide login

Abide كيخزّن المفتاح فـ ~/.abide/.env بصلاحيات المالك بوحدو. وتقدر عوض ذلك تحط بيانات الدخول فـ .env.local ولا .env فالجذر ديال المستودع. البحث على بيانات الدخول كيتحقق أولاً من البيئة، ومن بعد من ملفات المستودع، ومن بعد من ~/.abide/.env.

إلا كنت كتستعمل Vercel AI Gateway، حدّد AI_GATEWAY_API_KEY بلاصة مفتاح TypeSafe. بيانات الدخول ما كتقبلش عبر خيارات سطر الأوامر وما كتتسجّلش.

الخطوة 2: ثبّت خطافات الوكيل

من داخل المستودع ديالك، هيّئ Abide:

npx @coldtea/abide init

إلا ما حدّدتيش اسم الوكيل، init كيثبّت Abide فكل وكيل مدعوم كيلقاه. وتقدر حتى تستهدف تكامل واحد بشكل صريح:

npx @coldtea/abide init claude
npx @coldtea/abide init codex
npx @coldtea/abide init opencode

• Claude Code: كيتزاد التكامل فـ ~/.claude/settings.json.
• Codex: كيتزاد التكامل فـ ~/.codex/hooks.json.
• OpenCode: كيتثبّت الملحق فـ ~/.config/opencode/plugins/abide.js.

زيد --project ملي بغيتي تثبيت على مستوى المستودع يقدرو الزملاء ياخذوه مع checkout:

npx @coldtea/abide init claude --project

Codex كيحتاج خطوة موافقة إضافية. شغّل Codex، دخل لـ /hooks، وقبل إدخالات خطافات Abide الأربعة. Codex كيطلب هاد الموافقة مرة وحدة على كل خطاف جديد.

الخطوة 3: جمّع قواعد المستودع

شغّل وكيل البرمجة ديالك بشكل عادي. فبداية أول جلسة، Abide كيتحقق واش ملفات التعليمات تبدلات. من بعد، الوكيل كيجمع التعليمات المنطبقة فـ .abide/rubric.json وكيبلغك شنو لقا.

وتقدر حتى تجمع القواعد قبل ما تبدا جلسة جديدة:

abide compile

دير commit لـ .abide/rubric.json إلا بغيتي معيار المستودع القابل للفرض يكون باين وقابل للمراجعة من طرف الفريق. كل حكم كيعرف قاعدة فهاد الملف وكيقتبس تعليمة المصدر اللي تشتق منها.

الاستعمال الأساسي

خلّي Abide يفحص تعديلات الوكيل تلقائياً

من بعد التهيئة، شغّل claude ولا codex ولا opencode بحال العادة. ما كايناش حاجة لخدمة منفصلة خدامة فالخلفية. لنفترض أن تعليمة كتقول إن نقاط نهاية API خاصها تستعمل Yup وما خاصهاش تتحقق من المدخلات يدوياً. إلا كتب الوكيل حارساً يدوياً، Abide يقدر يرجّع رسالة بحال هادي:

Abide: هاد التعديل باين كيخرق واحد القاعدة من تعليمات هاد المستودع.
- القاعدة "api-validation-uses-yup" من ~/.codex/AGENTS.md فالسطر 65:
  "ملي كتكتب نقاط API، ما تكتبش التحققات ديال الإدخال بيدك.
  استعمل Yup (برسايل واضحة ديال التحقق) + رجوع بكري فمعالج API".
  (0.86)
صلّح apps/web/src/pages/api/logout.ts دابا، ومن بعد كمّل المهمة.

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

تحقّق يدوياً من التعديلات اللي ما تزادتش للـ commit

استعمل check باش تقيّم التعديلات الحالية اللي ما تزادتش للـ commit بنفس الطريقة اللي كتخدم بها الـ hooks:

abide check

وتقدر حتى تعطي المسارات ملي بغيتي تضيق نطاق التحقق:

abide check apps/web/src/pages/api/

دير تدقيق للكود الموجود

الأمر audit كيقيّم الملفات الموجودة بحال إلا تخلقات دابا. هادشي مفيد ملي كتضيف Abide لمستودع خدام من قبل:

abide audit src/

الخرج فيه ملخص حسب القاعدة ولائحة منظمة حسب الملف. الـ README كايقول باللي تدقيق 33 مسار API فواحد تطبيق Next.js حقيقي خدا تقريباً 12 ثانية وكلّف تقريباً سنت واحد، مع العلم أن النتائج الفعلية كتختلف حسب المستودع والقواعد.

راجع نشاط القواعد

شغّل أمر التقرير باش تشوف القواعد ديالك، شكون منها خدم، وشكون عمره خدم:

abide report

باش تاخذ خرج مقروء آلياً، زِد --json. خرج JSON متوفر حتى مع check وaudit وbench وcalibrate.

فهم توقيت القواعد والأحكام

كل قاعدة مْصَيّبة كتخدم فواحد من جوج المراحل:

• مرحلة التعديل: كتخدم من بعد كل تعديل فردي وكتقيّم داك الجزء المعدّل.
• مرحلة الدورة: كتخدم مرة وحدة فالنهاية ديال الدورة وكتقيّم الفرق كامل مقارنة مع اللقطة اللي تاخذات فبداية الدورة.

التقييم على مستوى الدورة مهم فالأسئلة اللي ما يمكنش نجاوبو عليها غير من أول تعديل، بحال واش الوكيل زاد وظيفة ما طلبهاش المستخدم. فالنهاية ديال الدورة، Abide كيطبّق حتى قواعد مرحلة التعديل على التغييرات اللي تخلقات بأوامر shell.

الأحكام مقسّمة لنطاقات ديال الاحتمال:

• 0.8 ولا كثر: كيتعطى للوكيل التعليم باش يصلّح المخالفة.
• من 0.5 حتى أقل من 0.8: كيبان تنبيه، ولكن ما كيتعطاش للوكيل التعليم باش يصلّح.
• أقل من 0.5: ما كيبان والو.

مسارات متقدمة

عاير القواعد باستعمال تاريخ Git

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

abide calibrate

Abide كيستعمل عشرين جزء معدّل حديث فهاد العملية، ويقدر يطفي القواعد اللي ما كتخدمش مزيان. راجع النتيجة قبل ما تعتمد على rubric جديدة مْصَيّبة وسط الفريق.

ضبط القواعد اللي عمرها خدامة

من بعد ما تحدد القواعد غير الفعالة، استعمل tune باش تخلي الوكيل يعاود يكتبها:

abide tune

حيت كل إدخال فـ rubric كيقتبس التعليمات الأصلية ديالو، تقدر ترجع الحكم المشكوك فيه للصياغة اللي سبباتو. تحسين التعليمات الأصلية كيخلي التحقق المقابل أوضح غالباً.

عاود شغّل جلسات الوكيل السابقة

استعمل replay باش تقيّم الجلسات القديمة ديال واحد من الوكلاء المدعومين:

abide replay claude
abide replay codex
abide replay opencode

هادشي يقدر يعاونك تقيّم rubric مقابل خدمة دازت من قبل، بلا ما تبقى كتسنى مخالفات مستقبلية.

قِس التأخير والمصاريف محلياً

شغّل أمر benchmark باش تقيس الأداء والتكلفة فالجهاز ديالك:

abide bench

المستودع كايذكر باللي التحقق من 13 قاعدة كيستعمل تقريباً من 1,000 حتى 1,600 من توكنات الإدخال، وكيكلّف تقريباً من $0.00004 حتى $0.00007 لكل تحقق، وكيحتاج تقريباً 300 ميلي ثانية فـ Jev. هاد الأرقام تقاست مباشرة مقابل TypeSafe وقد تختلف، لذلك الـ benchmark المحلي هو الدليل الأحسن للإعداد ديالك.

استعمل النطاقات باش تبقى الأسئلة مرتبطة بالسياق

القواعد فـ .abide/rubric.json تقدر تتضمن نطاقات مبنية على glob. استعمل هاد النطاقات ملي كتكون التعليمات كتطبّق غير على ملفات معيّنة. مثلاً، قواعد التحقق تقدر تكون خاصة بمسارات API، بينما قواعد التنسيق خاصها تقتصر على ملفات stylesheets. النطاقات الضيقة كتقلل الأحكام اللي ما عندهاش علاقة وكتخلي فهم النتائج أسهل.

الخصوصية والتصرف فحالة الفشل

الأسطر اللي تبدلات كيتصيفطو لـ TypeSafe باستعمال المفتاح ديالك، مع طلب عدم الاحتفاظ بأي بيانات فكل استدعاء. الـ README كايذكر باللي البيانات ما كتتصيفطش لسيرفر تابع لـ Abide.

الـ hooks ديال Abide مصممين باش ما يوقفوش جلسة الوكيل. مسارات الـ hooks كتخرج بنجاح، وكتستعمل حدّاً زمنياً صارماً، وكتطبع غير داكشي اللي كيتسناه المضيف. إلا ما كان حتى مفتاح ولا كانت الشبكة ما خداماش، التعديل كيكمل بلا تحقق. التحقق اللي ما تدارش كيتكتب فـ .abide/events.jsonl، وabide report كيدخلو فالإحصائيات ديالو.

حيد Abide

حيد Abide من كل وكيل تْثبّت فيه:

abide uninstall

باش تحيد غير تكامل واحد، سَمّي الوكيل:

abide uninstall codex

زِد --project ملي كتكون كتحيد تثبيت على مستوى المشروع. إزالة التثبيت كتحيد غير الإدخالات ديال Abide. وكتخلي ملفات rubric و~/.abide/.env فبلاصتهم حتى تحيدهم بيدك.

الخلاصة

Abide كيحوّل تعليمات المستودع المكتوبة باللغة الطبيعية لفحوصات كتخدم طوال جلسة البرمجة بالذكاء الاصطناعي. ركّب الـ hooks المناسبة، كمّبيل وراجع .abide/rubric.json، ومن بعد استعمل الفحوصات التلقائية، والتدقيقات، والتقارير، والمعايرة، والضبط باش تبقى القواعد فعّالة. والنتيجة هي طبقة خفيفة لتطبيق المعايير اللي ما كيقدروش اللينترز التقليديين يعبّرو عليها.