الدرس 4. القرارات خارج الكود — yongol والتحكم الإعلاني الشامل

نصائح ذهبية — هذا كل ما تحتاج معرفته

في الدرس 3 تعلمنا منع الانحراف باختبارات Hurl وGit. يكفي حتى 50 endpoint. لكن مع زيادة الحجم تظهر مشكلة جديدة. تطلب “نظّف الكود” فيعتبر AI قرارك تفصيلاً ويكتب فوقه.

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

تثبيت yongol:

للوكيل: “npx skills add park-jun-woo/yongol ثبّت”

لنصنع ميزة Login إعلانياً:

للوكيل: “أعلن ميزة Login كـ SSOT”

سينشئ AI مواصفات API، مخطط DB، تدفق الخدمة، سياسة التفويض، وسيناريوهات الاختبار تلقائياً.

للوكيل: “شغّل yongol validate وأوصل الأخطاء لصفر”

عند ظهور أخطاء يصلحها AI بنفسه. 287 قاعدة تتحقق تبادلياً بين 10 مواصفات. عندما تكون جميع العلامات خضراء، الاستعداد لتوليد الكود مكتمل.

yongol حالياً لمشاريع Go فقط. لكن مبدأ “إخراج القرارات من الكود والتحقق التبادلي لكشف التناقضات” مستقل عن اللغة. واختبارات Hurl من الدرس 3 تعمل بالفعل بغض النظر عن اللغة.

تجربة سريعة

ثبّت yongol skill للوكيل:

للوكيل: “npx skills add park-jun-woo/yongol ثبّت”

للوكيل: “أعلن ميزة Login كـ SSOT”

سينشئ AI 5 ملفات: specs/api/openapi.yaml, specs/db/users.sql, specs/service/auth/login.ssac, specs/policy/authz.rego, specs/tests/scenario-login.hurl.

للوكيل: “شغّل yongol validate specs/”

إذا خرج 0 errors نجحت.

لنصنع تناقضاً عمداً:

للوكيل: “غيّر حقل email إلى mail في OpenAPI”

للوكيل: “شغّل yongol validate specs/”

سيظهر خطأ مثل “في OpenAPI الحقل mail لكن في DDL الحقل email”. إذا نظرت لطبقة واحدة لا يوجد خطأ. عند التقاطع بين طبقتين يظهر التناقض.

للوكيل: “أصلح أخطاء validate”

يوحّد AI أسماء الحقول. validate مرة أخرى. 0 errors.

لماذا يجب أن تأمر بهذه الطريقة

10 أنواع SSOT — كل منها مسؤول عن اهتمام واحد

yongol يفصل قرارات البرنامج إلى 10 مواصفات إعلانية (SSOT: مصدر واحد للحقيقة). كل مواصفة مسؤولة عن اهتمام واحد.

لا تحتاج لحفظ هذه الأسماء. مجمّعة حسب الدور تصبح بديهية:

ما يعرّف البيانات:

ما يعرّف السلوك:

ما يتحقق:

ما يعرّف الواجهة:

10 أنواع تبدو كثيرة؟ لا داعي للقلق. ثلاث حقائق يجب معرفتها:

أولاً، 8 من 10 معايير صناعية. OpenAPI, SQL, sqlc, Rego, Mermaid, Hurl, YAML — معايير يستخدمها المطورون المحترفون، لكنك لن تستخدمها مباشرة. AI يعرفها. ما أنشأه yongol جديد هو SSaC (تدفق الخدمة) وSTML (الواجهة) فقط.

ثانياً، لا تحتاج لتعلمها. AI يعرفها. أنت تقول “اصنع ميزة التسجيل” وAI يحرر 10 مواصفات. أنت ترى النتيجة فقط.

ثالثاً، yongol حالياً لمشاريع Go فقط. لكن المبدأ — إخراج القرارات من الكود والتحقق التبادلي لكشف التناقضات — مستقل عن اللغة.

operationId — مفتاح واحد يربط جميع الطبقات

10 مواصفات منفصلة ستكون فوضى. يجب ربطها. كيف؟

باسم واحد.

ضغطة زر واحدة ترسل طلباً واحداً للخادم. كل طلب يُسمى endpoint.

في تطبيق full-stack وحدة الميزة هي API endpoint. يضغط المستخدم زراً فيُستدعى API، الذي ينفذ منطق الخدمة، يقرأ DB، يتحقق من الصلاحيات، وينقل الحالة. نقطة بداية هذا التدفق هي operationId.

operationId واحد يربط جميع الطبقات العشر. هذا هو سبب تسمية yongol له حجر الأساس (keystone).

yongol validate — 287 قاعدة تكشف التناقضات

فصلنا القرارات في 10 ملفات، فقد تحدث تناقضات بينها.

• DDL يقول BIGINT لكن OpenAPI يقول string؟
• SSaC يعلن @auth لكن لا توجد قاعدة مقابلة في Rego؟
• مخطط الحالة فيه انتقال لكن لا توجد دالة مقابلة في SSaC؟

yongol validate يكتشف هذا. يفحص جميع الروابط بين 10 مواصفات. ~287 قاعدة. إذا وُجد تناقض واحد يرفض توليد الكود.

القيمة الفريدة لـ yongol validate هي هذا التحقق التبادلي. الأدوات الحالية ترى طبقتها فقط.

4.5B نموذج محلي أيضاً يصل لصفر أخطاء

validate يكتشف. لكن هل يجب أن يصلح الإنسان؟

لا. AI يفعل.

yongol agent specs/ --model ollama:gemma4:e4b --max-rounds 20

هذا الأمر الواحد يجعل AI يكرر: validate → فحص الخطأ → إصلاح → validate مرة أخرى → إصلاح مرة أخرى. حتى صفر أخطاء.

نتائج التجربة: Login endpoint واحد، نماذج مختلفة تكتب 9 ملفات SSOT:

نموذج محلي 4.5B يعمل. تكلفة صفر. بدون إنترنت.

لماذا تنجح النماذج الصغيرة؟ لأن تغذية validate الراجعة حقيقة حتمية. “line 41: field name mismatch” — ليست رأياً. حقيقة. لا مجال للتملق. “نعم، سأصلح” ويصلح.

ذكاء النموذج ليس المحدد، بل دقة التغذية الراجعة.

المعيار: ZenFlow — 32 endpoint في 69 دقيقة

ليس نظرياً. قياس فعلي.

ZenFlow — SaaS أتمتة سير عمل متعدد المستأجرين. بُني بالكامل بـ yongol.

النهائي: 32 endpoint, 14 جدول, 47 طلب Hurl. 11/11 مرحلة ناجحة.

الأهم ليس “69 دقيقة”. بل أن السرعة لم تتباطأ مع إضافة الميزات. الميزة الأولى 13 دقيقة، الحادية عشرة 4 دقائق. ظاهرة “جدار 200 endpoint” لم تحدث. الاختبارات الحالية لم تنكسر.

الملخص — ما يجب تذكره من هذا الدرس

1. القرارات والتفاصيل مختلطة في الكود. AI لا يميّز بينهما. هذا هو السبب الجذري للانحراف.
2. أخرج القرارات من الكود. 10 مواصفات إعلانية (SSOT) كل منها مسؤول عن اهتمام واحد. 8 من 10 معايير صناعية.
3. operationId هو حجر الأساس. اسم واحد يخترق 10 طبقات.
4. 287 قاعدة تكشف التناقضات بين الطبقات. الأدوات الحالية ترى طبقتها فقط.
5. نموذج 4.5B يصل لصفر أخطاء. ذكاء النموذج ليس المحدد، بل دقة التغذية الراجعة.

مقالات ذات صلة

• yongol — عارضة AI للبرمجة كخدمة
• SSaC

سلسلة دروس Reins Engineering الكاملة

مصادر الأدلة

• معيار ZenFlow — 32 endpoint في 69 دقيقة، 14 جدول، 47 طلب Hurl. 11/11 مرحلة ناجحة
• تجربة نماذج yongol agent — Grok 4.3 (صفر أخطاء)، Gemini 2.5 Flash (جولة واحدة)، Gemma4 4.5B (جولة واحدة)، Qwen3 8B (جولة واحدة)
• yongol validate — 287 قاعدة، تحقق تبادلي بين 10 SSOT
• مقارنة حجم كود SaaS متوسط — SSOT 12,500 سطر مقابل كود التنفيذ 100,000 سطر (ضغط سياق ~10 أضعاف)