بني خدمات خلفية متوقعة مولّدة بالذكاء الاصطناعي مع kybes

شنو كيدير kybes

kybes هو إضافة ديال Claude Code كتولّد كود backend متوقّع انطلاقاً من مخططات قواعد البيانات بصيغة YAML. كيوحّد المجلدات، سميات الملفات، ميثودات المستودعات، التحقّق، التصفح بالصفحات، المعاملات، الفهارس، والاختبارات فمشاريع C# وPython وTypeScript وJava.

عوض ما تطلب من وكيل ديال الذكاء الاصطناعي يتفكّر وثيقة ديال البنية، kybes كيفرض البنية عن طريق التوليد الحتمي، وكلاء مخصّصين، قواعد مرتبطة بالمجلدات، hooks، وفحوصات CI. نفس المخطط كينتج خرج مولّد مطابق حرفياً للبايتات فالمشاريع المختلفة.

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

كيفاش كتخدم البنية المولّدة

على حساب كل جدول، kybes كينشئ جوج طبقات ديال النماذج:

• model/generated/<Table> فيها الكيانات المولّدة، عمليات CRUD، العلاقات، الاستعلامات المصرّح بها، التصفح بالـ cursor، والتحقّق. هاد الملفات كيتعاود توليدها وما خاصهاش تتعدّل.
• model/<Table> هي البلاصة الآمنة للميثودات المخصّصة. C# كتستعمل partial class، بينما Python وTypeScript وJava كيستعملو طريقة مبنية على subclass.

المشروع النموذجي كيضم حتى JSON Schemas مولّدة، PostgreSQL DDL، تحليل الفهارس، فهرس ديال ملفات النماذج، وملفات مولّدة للتحقّق.

ثبّت kybes

التثبيت عبر Claude Code

من Claude Code، زِد الـ marketplace وثبّت الإضافة:

/plugin marketplace add ivandilelio/kybes
/plugin install kybes@kybes

داخل المشروع المستهدف، طلب من Claude Code يجهّز kybes فهاد المشروع. المهارة kybes:kybes-init كتسولك على لغات النماذج اللي محتاج، وكتنشئ الإعدادات، قواعد المسارات، تعليمات CLAUDE.md، scaffold اختياري، وworkflow ديال CI.

الـ hooks كيبقاو غير مفعّلين فالمستودعات اللي ما تدارش ليها التهيئة.

التثبيت من سطر الأوامر

تقدر حتى تنسخ المستودع وتشغّل المثبّت:

git clone https://github.com/ivandilelio/kybes
kybes/install.sh --target /path/to/project --scaffold --examples \
  --model-langs csharp,python,typescript,java

المثبّت idempotent. من بعد ما ينسخو الزملاء مشروع مهيّأ، غير خاصهم يشغّلو tools/kybes/setup.sh مرة وحدة.

تأكّد من المتطلبات

الـ hooks والمولّد محتاجين python3 غير بالمكتبة القياسية. أما runtimes المولّدة فمحتاجين dependencies ديال اللغة المناسبة:

• C#: net8.0، وEntity Framework Core 8، وprovider بحال Npgsql.
• Python: Python 3.9 ولا أحدث وSQLAlchemy 2.
• TypeScript: TypeORM، وreflect-metadata، وخاص خيارات المترجم experimentalDecorators وemitDecoratorMetadata يكونو مفعّلين.
• Java: Jakarta Persistence 3.1، وHibernate 6.2 ولا أحدث، وJackson لأعمدة json.

عرّف مخطط ديال قاعدة البيانات

أنشئ ملف YAML تحت schemas/db. المثال التالي كيعرّف جدول ديال الطلبات فيه رقم طلب فريد، علاقة إجبارية مع الزبون، استعلام مصرّح به، وتصفح بالـ cursor قابل للترتيب:

table: Ordini
columns:
  - { name: Id, type: uuid, primary_key: true }
  - { name: Numero, type: string, length: 20, required: true, unique: true }
  - { name: ClienteId, type: uuid, required: true }
  - { name: Data, type: date, required: true }
relations:
  - { name: Cliente, kind: many_to_one, target: Clienti, foreign_key: ClienteId }
queries:
  - name: DelClienteDal
    where: [ClienteId, { column: Data, op: gte, param: DaData }]
    order_by: [{ column: Data, dir: desc }]
pagination:
  default_order: [{ column: Data, dir: desc }]
  sortable: [Data, Numero]

حفظ الملف باسم schemas/db/Ordini.yaml. أي تغيير فالمخطط كيطلّق إعادة التوليد للغات المهيّأة، كيحدّث فهرس النماذج، وكيعاود يحسب توصيات الفهارس.

استعمل API المولّد

بالنسبة للمخطط المثال، kybes كيولّد نفس الإمكانيات ديال المستودع فكل لغة. التسمية كتتبع الاصطلاحات ديال اللغة المستهدفة:

• القراية بالمفتاح: GetByIdAsync فـ C#، وget_by_id فـ Python، وgetById فـ TypeScript ولا Java.
• التصفح بالـ cursor: ListPageAsync، ولا list_page، ولا listPage.
• البحث بعمود فريد: FindByNumeroAsync، ولا find_by_numero، ولا findByNumero.
• البحث بالمفتاح الأجنبي: ListByClienteIdAsync، ولا list_by_cliente_id، ولا listByClienteId.
• الاستعلام المصرّح به: ListDelClienteDalAsync، ولا list_del_cliente_dal، ولا listDelClienteDal.

الـ API المولّد كيوفّر حتى عمليات التحقق من الإنشاء والتحديث والحذف، وaccessors ديال العلاقات، وصفحات مبنية على الـ cursor ممثّلة بطلب وبصفحة فيها العناصر وcursor التالي.

صرّح بالاستعلامات عوض ما تكتب الولوج للبيانات فالـ handlers

حط شروط الاستعلام المدعومة فالمخطط عوض ما تستورد ORM ولا database driver داخل Lambda ولا service ولا controller. kybes كيدعم operators من بينها eq، ne، lt، lte، gt، gte، in، prefix، وis_null.

المولّد كينشئ ميثود ديال المستودع وكيحلّل مسار الولوج ديالها. فالمثال، شروط المفتاح الأجنبي والتاريخ كتوصل لفهرس على (ClienteId, Data). القرار كيتسجّل فـ db/generated/indexes.md.

زِد سلوك مخصّص للنموذج

ملي كتكون الميثودات اللي كتتولّد ما كافياش، زيد الميثودات المخصّصة فملف الموديل اللي ماشي مولّد، بحال model/Fornitori.py ولا الملف المكافئ فاللغة المختارة. ما تبدّلش فالتنفيذ المولّد.

الميثودات المخصّصة ما خاصهاش تتصادم مع سميات الميثودات المولّدة. وخصّها حتى هي تيست موثّق فـ tests/custom/ قبل ما تسالي الخدمة. الصيغة المتوقعة لمعرّف التيست هي TC-<Table>-….

خلّي الولوج للبيانات داخل طبقة الموديل. الهاندلر خاصو يعيّط لميثود مولّدة ولا مخصّصة فالموديل، وما ينشئش الاستعلام ديالو ديال SQLAlchemy ولا Entity Framework ولا TypeORM ولا Hibernate.

فهم ضوابط kybes

الهوكس ديال kybes كيتشغلو طوال مسار التطوير. قبل أي كتابة، يقدرو يمنعو استيرادات ORM ولا درايفر قاعدة البيانات من برا الموديل، والتعديلات فالملفات المولّدة، وفولدرات الموديل غير الصالحة، وتصادمات الميثودات، والأسرار المكتوبة بشكل واضح.

من بعد الكتابة فالسكيما، kybes يقدر يعاود يولّد الموديلات، يشغّل اللينترات، ويبلّغ على مشاكل المعمارية. قبل الإكمال، الآݣون الرئيسي وكل subagent خاصهم يدوزو فـ architecture check وgenerator check وverification script وأوامر التيست ديال المشروع.

الفحوصات الافتراضية قبل التوقّف كتشمل:

• arch_check، بما فيه اكتشاف البلوكات المكرّرة اللي فيها تمانية ديال السطور ولا كثر.
• gen --check باش يتأكّد باللي المخرجات المولّدة محيّنة.
• verify.py لتيستات الموديل وعتبات التغطية حسب ASIL.
• أوامر التيست الخاصة بالمشروع.

نفس الفحوصات كيتشغلو فـ CI باستعمال --strict. القواعد تقدر تتضبط على block ولا warn ولا off فـ .claude/kybes.config.json. الآݣون ما مسموحش ليه يبدّل فهاد الملف ديال الإعدادات.

استعمل الترانزاكسيونات والصفحات والإندكسات بأمان

kybes كيولّد pagination بالكورسر انطلاقاً من الترتيب الافتراضي ديال السكيما ومن الأعمدة المسموح بالترتيب بها. هادشي كينتج طلب صفحة مبني على keyset وصفحة فيها العناصر وnext cursor. صيغ الكورسر مشتركة بين اللغات المدعومة، وهادشي كيساعد الخدمات والكلينتات المختلفة يتعاملو مع بعضياتهم.

الترانزاكسيونات كتستعمل Unit of Work مع مستويات عزل لكل جدول ومعالجة أوتوماتيكية لإعادة المحاولة فحالات فشل serialization والـ deadlocks. مسارات الولوج المصرّح بها كتتحلّل باش يتحددو الإندكسات المثالية؛ الإندكسات الناقصة كتتخلق والإندكسات الزايدة كيتشار ليها. البحث بالبداية يقدر يستعمل PostgreSQL varchar_pattern_ops ملي كيكون مناسب.

ضبط تعدد المستأجرين

تعدد المستأجرين يقدر يتضبط لكل جدول باستعمال واحد من الاستراتيجيات المدعومة:

• عمود ديال المستأجر، بحيث كل ميثود مولّدة كتتصفّى وقيود uniqueness كتتحدّد لكل مستأجر.
• أمان على مستوى الصفوف فـ PostgreSQL.
• سكيما لكل مستأجر.
• قاعدة بيانات لكل مستأجر.

المستأجر كيتربط بجلسة ORM، وkybes كيولّد تيستات العزل للاستراتيجية المضبوطة.

راجع بنية المشروع المولّدة

المشروع المضبوط كيتبع بنية متوقعة:

your-project/
├── schemas/db/<Table>.yaml
├── schemas/generated/json/<Table>.schema.json
├── libs/db-models/<language>/…/model/
│   ├── <Table>.{cs,py,ts} | <Table>Repository.java
│   └── generated/
├── libs/db-models/<language>/tests/
│   ├── generated/
│   └── custom/
├── docs/generated/verification/
├── db/generated/ddl/postgres/_all.sql
├── services/<context>/{functions,ms}/
├── jobs/
├── libs/utils/
├── libs/errors/
├── frontend/
├── infra/
├── MODEL_INDEX.md
└── .claude/kybes.config.json

كلشي اللي داخل فولدر generated/ تابع لـ kybes. ملفات الموديل الأخرى، والتيستات المخصّصة، والسكيما، وكود التطبيق كيتصانو من طرف الفريق ديالك حسب القواعد المضبوطة.

تحقّق من النتيجة

المستودع فيه التحقّق من الكود المولّد، والهوكس، وSQL، والسلوك بين اللغات. التيستات كتشمل CRUD، والعلاقات، وcascades، وقيود uniqueness، والحالات الخاصة بالـ pagination، وعوامل الاستعلام، وسلوك Unit of Work.

التيستات الوحداتية المولّدة كتستخرج المتطلبات وحالات التيست من كل سكيما. مسار التحقّق كيشمل أصناف التكافؤ، والقيم الحدّية، وتخمين الأخطاء، وMC/DC لـ ASIL C وD، وقابلية التتبّع، وبوابات التغطية لكل جدول. المستودع كيتحقّق حتى باللي PostgreSQL DDL المولّد كيتحلّل بشكل صحيح، وباللي الكورسرات اللي كتنتجها لغة مدعومة يقدرو اللغات الأخرى تقبلها.

فالخدمة الحساسة للسلامة، kybes كيأتمت أجزاء من ISO 26262-6 على مستوى الوحدة البرمجية، ولكن ما كيعوّضش خطة سلامة كاملة، ولا تحليل المخاطر، ولا تأهيل الأدوات، ولا المراجعة المستقلة، ولا مسار الشهادة التنظيمية.

الخلاصة

kybes كيوفّر مسار عمل مبني على السكيما باش يسهّل إنشاء backends متوقعة بالذكاء الاصطناعي. عرّف الجداول والعلاقات والاستعلامات وpagination وقواعد tenancy مرة وحدة؛ وخلي المولّد المحدّد ينشئ الموديلات الخاصة بكل لغة، والإندكسات، وDDL، والتحقّق، والتيستات؛ ومن بعد حط السلوك المخصّص فطبقة الموديل المعتمدة.

مع آݣونات Claude Code، والهوكس وقت الكتابة، واكتشاف الكود المكرّر، والتحقّق المولّد، وفحوصات CI الصارمة، المشروع كيبقى منسجم حتى ملي كيكبر الكود وكيكبر السياق ديال الذكاء الاصطناعي. للمراجع المتعمّقة، قلّب فـ التوثيق ديال المشروع والمستودع المصدر.