yongol — عارضة السفينة للبرمجيات السحابية المبنية بالذكاء الاصطناعي

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

إذا كنت تعاني من مشكلة الذكاء الاصطناعي الذي يُعيد كتابة كودك، إذا انهارت البرمجة الحدسية عند 200 نقطة نهاية، إذا كنت تريد نقل هدف عمل الذكاء الاصطناعي من الكود إلى المواصفات — yongol هو تلك العارضة.

نقطة النهاية رقم 200

تبني SaaS بالبرمجة الحدسية. في البداية يكون سريعاً. 5 جداول، 12 نقطة نهاية — عشرون دقيقة ويعمل.

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

أثبت تقرير DORA 2025 ذلك تجريبياً — أدوات الذكاء الاصطناعي تزيد الإنتاجية بنسبة 2-18%، لكنها في الوقت نفسه تزيد معدل فشل التغييرات وإعادة العمل^[1]. الذكاء الاصطناعي هو “مرآة ومُضاعِف” يُضخّم نقاط ضعف العمليات الحالية.

ليس لأن النموذج غبي.

القرارات والتنفيذ

ثلاثة أشياء متشابكة في الشفرة المصدرية:

• قرارات المستخدم — هذا العمود BIGINT، نقطة النهاية هذه للمالك فقط، الترقيم بالمؤشر.
• منطق الأعمال — التسعير، تدفقات العمل، قواعد دورة الحياة.
• تفاصيل التنفيذ — أسماء المتغيرات، ترتيب استدعاء المكتبات، تغليف الأخطاء.

عندما يقرأ الذكاء الاصطناعي هذه الشفرة، لا يستطيع التمييز بين سطر هو قرار وسطر هو تفصيل. لذا عند “إعادة الهيكلة” أو “التنظيف”، يُعيد كتابة القرارات بصمت ظناً منه أنها تفاصيل. لا ينتبه المستخدم إلا بعد أن يختل السلوك فعلاً. في 1972، قال Parnas “أخفِ قرارات التصميم المرجّح تغييرها خلف واجهات”^[2] — كان يخاطب البشر. لكن الآن بعد أن أصبح الذكاء الاصطناعي يحرر الشفرة، ما لم يوجد التمييز بين القرارات والتفاصيل في الوسيط نفسه، فلا أحد — بشراً كان أو نموذجاً — يستطيع الحفاظ عليه.

هذا هو سبب انهيار البرمجة الحدسية عند 200 نقطة نهاية. نموذج أكبر لن يحل المشكلة. الوسيط — الشفرة الخام — لا يحفظ القرارات ببساطة. كل نموذج يصطدم بالجدار نفسه في النهاية.

العارضة

العارضة هي أول عظمة توضع عند بناء السفينة. تحمل ثقل الهيكل، وتمنع التمايل الجانبي، وكل بنية أخرى تُبنى فوقها. سفينة بُنيت بدون عارضة تطفو في المياه الهادئة لكنها تتشوه عندما تأتي الأمواج.

SaaS مبني بالبرمجة الحدسية كذلك. يطفو عندما يكون صغيراً. يتشوه عندما يكبر.

yongol هو عارضة SaaS المبني بالذكاء الاصطناعي.

Harness with reins — ليس نموذجاً أكبر، بل لجاماً أدق. مُدقق حتمي يحكم على كل مخرج، وسقاطة تفرض التقدم، والآلة تقرر ما إذا كانت المهمة قد أُنجزت.

أخرِج القرارات من الشفرة

جوهر yongol بسيط. افصل القرارات عن الشفرة.

عشر مواصفات تصريحية (SSOT) كل منها يتولى مسؤولية واحدة:

ثمانية من العشرة معايير صناعية (OpenAPI، SQL، sqlc، Rego، Mermaid، Hurl، YAML). فقط SSaC وSTML لغتان أنشأهما yongol. ما يجب على الذكاء الاصطناعي تعلمه من الصفر يُقلّل إلى الحد الأدنى.

كل SSOT يحتوي على القرارات فقط. لا تفاصيل تنفيذ. الذكاء الاصطناعي يحرر SSOTs؛ yongol generate يُصيّر الشفرة منها. القرارات تعيش دائماً في SSOTs؛ الشفرة إسقاط قابل للتخلص منه.

فرض التناسق

القرارات الآن موزعة عبر عشرة ملفات، فقد تظهر تناقضات. DDL يقول BIGINT لكن OpenAPI يقول string؟ SSaC يعلن @auth لكن Rego ليس فيه قاعدة مطابقة؟ مخطط الحالة فيه انتقال لكن SSaC ليس فيه دالة مقابلة؟

SSOT متناقض هو قرار فاسد. مهما كانت الشفرة نظيفة، إذا تعارضت القرارات فالسلوك يختل.

yongol validate يلتقط ذلك.

✓ manifest        ✓ openapi_ddl       ✓ ssac_rego
✓ openapi         ✓ openapi_ssac      ✓ ssac_authz
✓ ddl             ✓ hurl_openapi      ✓ ssac_sqlc
✓ query           ✓ hurl_statemachine ✓ ddl_statemachine
✓ ssac            ✓ hurl_manifest     ✓ ddl_rego
✓ statemachine    ✓ openapi_manifest  ✓ rego_manifest
✓ rego            ✓ ssac_ddl          ✓ stml_openapi
✓ hurl            ✓ ssac_statemachine
✓ funcspec        ✓ ssac_func

0 errors, 0 warnings

يتحقق أولاً من كل SSOT على حدة، ثم يُجري فحوصات متقاطعة بين الطبقات. حوالي 287 قاعدة تفحص كل مرجع رمزي عبر جميع SSOTs العشرة. إذا وُجد تناقض واحد، يُرفض التجميع. أشارت المراجعة المنهجية لـ Torres وآخرين^[3] إلى أن معظم أدوات إدارة النماذج تتعامل فقط مع التناسق داخل نموذج واحد، تاركةً التحقق المتقاطع بين نماذج متغايرة كمشكلة مفتوحة — yongol validate يملأ تلك الفجوة بالضبط.

الذكاء الاصطناعي يكتب بحرية. إن خرج عن القضبان يلتقطه validate فوراً. حرية على القضبان.

yongol next — أمر السقاطة

بينما يعرض yongol validate كل الأخطاء دفعة واحدة، يعرض yongol next الأخطاء واحداً تلو الآخر. هذه هي السقاطة.

$ yongol next specs/

[ERROR] DDL-003: users.id must be BIGINT, got INT
  file: specs/db/users.sql:2
  ▶ Fix this error. Then run `yongol next specs/`.

التعليمة الوحيدة التي يحتاجها عميل الذكاء الاصطناعي هي جملة واحدة: “نفّذ yongol next specs/ وأصلح الأخطاء حتى تصبح 0.”

أصلح الخطأ فيظهر التالي. مرّر الكل فيتوقف:

$ yongol next specs/

✓ All validations passed. 0 errors.

لا يعلن العميل “انتهيت”. الآلة تحكم بـ “لا يزال هناك متبقٍ” أو “نجح الكل”. العميل لا يملك سلطة حكم الإنهاء.

إنشاء المشروع وإدارة الميزات

yongol init

يولّد تلقائياً هيكل SSOT من features.yaml.

yongol init Myapp features.yaml "My workflow automation SaaS"
cd Myapp && yongol validate specs     # 0 errors

يُولَّد manifest، وأكواد operationId الأولية في OpenAPI، وملفات SSaC الأولية، وقواعد تخويل Rego، واختبارات smoke في Hurl، وإعدادات sqlc دفعة واحدة. يبدأ المشروع في حالة نجاح yongol validate منذ البداية.

yongol features add / remove

إضافة أو إزالة ميزات:

yongol features add new_features.yaml         # توليد أكواد SSaC أولية لـ operationIds جديدة
yongol features remove ExportWorkflow --yes    # حذف operationId + أكواد SSaC الأولية

yongol import

توليد حزم عميل Go من مواصفات OpenAPI خارجية (Stripe, GitHub, إلخ):

yongol import https://api.stripe.com/openapi.yaml ./external/

استدعاء الدوال المولّدة في SSaC بـ @call <pkg>.<Func>({...}).

operationId هو حجر الأساس

كيف تربط عشر طبقات معاً؟ بمعرّف PascalCase واحد.

أدخل operationId ExecuteWorkflow:

── Feature Chain: ExecuteWorkflow ──

  OpenAPI    api/openapi.yaml                POST /workflows/{id}/execute
  SSaC       service/workflow/execute_workflow.ssac   @get @empty @auth @state @call @publish @response
  DDL        db/workflows.sql                CREATE TABLE workflows
  DDL        db/execution_logs.sql           CREATE TABLE execution_logs
  Rego       policy/authz.rego               resource: workflow
  StateDiag  states/workflow.md              diagram: workflow → ExecuteWorkflow
  FuncSpec   func/billing/check_credits.go   @func billing.CheckCredits
  FuncSpec   func/billing/deduct_credit.go   @func billing.DeductCredit
  FuncSpec   func/worker/process_actions.go  @func worker.ProcessActions
  FuncSpec   func/webhook/deliver.go         @func webhook.Deliver
  Hurl       tests/scenario-happy-path.hurl  scenario: scenario-happy-path.hurl

من مواصفات API إلى مخطط قاعدة البيانات، من سياسة التخويل إلى انتقالات الحالة، من تنفيذ الدوال إلى سيناريوهات الاختبار — الطوبولوجيا الكاملة لميزة واحدة على شاشة واحدة. عشرات عمليات grep تُستبدل بأمر واحد.

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

SSaC — لماذا لغة مخصصة

ثمانية من SSOTs العشرة في yongol هي معايير صناعية. فقط SSaC (Service Sequences as Code) وSTML أنشأهما yongol. SSaC يلتقط قرارات تدفق الخدمة.

الفراغ الذي يملأه SSaC. انظر إلى طيف الأدوات التصريحية: في طرف تقع معايير العقود (OpenAPI، SQL، Rego) — تعلن ماذا لكن ليس بأي ترتيب. في الطرف الآخر تقع بيئات تشغيل سير العمل (Temporal، Inngest، Restate) — تلك شفرة. القرارات وتفاصيل التنفيذ تعود للاندماج في الملف نفسه. SSaC يجلس في الفراغ بينهما: “داخل نقطة نهاية واحدة، ماذا يحدث، بأي ترتيب، مع أي حراس.”

SSaC يحتوي على 16 تعليقاً توضيحياً إجمالاً. يمكن تعلمه من دليل صفحة واحدة.

قائمة التعليقات التوضيحية الكاملة لـ SSaC

مثال SSaC — AcceptProposal

تخويل + آلتا حالة مزدوجتان + ضمان + طابور:

package service

import "github.com/org/project/internal/billing"

// @get Proposal p = Proposal.FindByID({ID: request.id})
// @empty p "Proposal not found" 404
// @get Gig gig = Gig.FindByID({ID: p.GigID})
// @empty gig "Gig not found" 404
// @auth "AcceptProposal" "gig" {ResourceID: request.id} "Forbidden" 403
// @state proposal {status: p.Status} "AcceptProposal" "Cannot accept" 409
// @state gig {status: gig.Status} "AcceptProposal" "Cannot accept on gig" 409
// @put Proposal.UpdateStatus({ID: p.ID, Status: "accepted"})
// @put Gig.AssignFreelancer({ID: gig.ID, FreelancerID: p.FreelancerID, Status: "in_progress"})
// @call billing.HoldEscrowResponse escrow = billing.HoldEscrow({GigID: gig.ID, Amount: gig.Budget})
// @publish "proposal.accepted" {GigID: gig.ID, FreelancerID: p.FreelancerID}
// @get Proposal updated = Proposal.FindByID({ID: p.ID})
// @response { proposal: updated }
func AcceptProposal() {}

16 سطراً. 10 تعليقات توضيحية. آلتا حالة، تخويل، ضمان، حدث طابور، استجابة — كل قرار مرئي، كل تفصيل غائب.

اختبار الأداء: ZenFlow

ZenFlow — SaaS أتمتة سير عمل متعدد المستأجرين.

النتيجة النهائية: 32 نقطة نهاية، 14 جدولاً، 47 طلب Hurl. نجحت 11/11 مرحلة.

إضافة الميزات لم تُبطئ أبداً. الاختبارات الحالية لم تنكسر أبداً. جدار الـ 200 نقطة نهاية لم يكن موجوداً.

اختبار أداء Opus 4.7 — 32 نقطة نهاية، 14 جدولاً، 47 طلب Hurl، حوالي 69 دقيقة. اختبار أداء Sonnet 4.6 — 32 نقطة نهاية، 9 جداول، 37 طلب Hurl، حوالي 43 دقيقة.

yongol agent

LLM يصلح تلقائياً ملفات SSOT عبر حلقة validate-fix.

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

تُعاد أخطاء validate إلى LLM، يصلحها LLM، ويُعاد التحقق. تتكرر الحلقة حتى 0 أخطاء. يعمل حتى مع نموذج محلي 4.5B (Gemma4).

الخلفيات المدعومة: ollama (محلي)، xai (Grok)، gemini.

هل يمكن تحرير الشفرة المولّدة

نعم. yongol generate يحافظ على تعديلات المستخدم عند إعادة التشغيل:

• كل ملف مولّد يحمل تعليقاً توضيحياً //yg:checked llm=yongol-gen hash=<8hex>.
• إذا اختلف الهاش، يُعلّم الملف كـ محفوظ (preserved) ويُتجاوز في generate التالي.
• yongol status يعرض الملفات المحفوظة وانحراف العقد (أخطاء PRV-01/PRV-02).
• لتسجيل النية، أضف //yg:preserve reason="..." (اختياري). لإلغاء الحفظ، احذف الملف.

الدوال والنماذج المدمجة

الدوال المدمجة (تُستدعى عبر @call في SSaC)

النماذج المدمجة (تُهيّأ عبر manifest.yaml)

توليد تحويلات DDL تلقائياً

yongol generate يكتشف تغييرات DDL ويولّد ملفات التحويل تلقائياً.

specs/db/
└── users.sql                         # SSOT — حرّر هنا

artifacts/db/
├── .latest_schema.sql                # لقطة أساسية
└── migrations/
    ├── 0001_initial.up.sql
    ├── 0001_initial.down.sql
    ├── 0002_add_users_email.up.sql
    └── 0002_add_users_email.down.sql

التغييرات الغامضة (إعادة تسمية الأعمدة، تحويل الأنواع، ملء NOT NULL) تُوضّح بتلميحات تعليق DDL (-- @rename، -- @cast، -- @backfill، -- @data_migration، -- @allow_destructive). ست قواعد (MIG-001 إلى MIG-006) تحرس التغييرات الخطرة. التطبيق الفعلي على قاعدة البيانات يُفوّض لأدوات قياسية مثل golang-migrate، flyway، إلخ.

لماذا النموذج الأكبر ليس هو الحل

“GPT-6 سيحل هذا.”

لن يحل. المشكلة ليست ذكاء النموذج — إنها الوسيط.

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

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

LLM صغير يحرر SSOTs فقط، مع validate يقدّم ملاحظات دقيقة عند كل خطأ، يستطيع الحفاظ على نفس سلامة القرارات كنموذج أكبر بكثير يحرر شفرة خاماً. yongol يسدّ تلك الفجوة.

اختبارات وقت التشغيل

اختبارات Hurl كلها يكتبها المستخدم. اكتبها في specs/tests/ وyongol generate يعكسها إلى artifacts/tests/. أثناء التحقق، القواعد XOH-01 إلى XOH-09 تفحص Hurl متقاطعاً مع OpenAPI وآلات الحالة وmanifest.auth.

hurl --test --variable host=http://localhost:8080 artifacts/my-project/tests/*.hurl

ثلاث فئات:

• smoke.hurl — اختبارات smoke لنقاط النهاية
• scenario-*.hurl — اختبارات سيناريوهات الأعمال
• invariant-*.hurl — اختبارات الثوابت عبر نقاط النهاية

الحالة الراهنة

توليد خلفية Go+Gin: Beta — يعمل من طرف لطرف. توليد واجهة React الأمامية: Alpha (قيد التطوير).

ابدأ

الطريقة 1: تثبيت المهارة (مُوصى به)

npx skills add park-jun-woo/yongol

ثبّت مهارة yongol في عميل الذكاء الاصطناعي (Claude Code, Cursor, Copilot والمزيد). العميل يتعلم سير العمل عند التثبيت.

/yongol ابنِ SaaS مهام متعدد المستأجرين مع مصادقة وCRUD.

الطريقة 2: التثبيت المباشر

يتطلب Go 1.25+ وgcc (اعتماد cgo: pg_query_go يربط libpg_query لتحليل DDL).

git clone https://github.com/park-jun-woo/yongol && cd yongol
make install

yongol validate examples/zenflow

0 errors, 0 warnings.

وجّه ذكاءً اصطناعياً إلى هذه المواصفات واطلب منه إضافة ميزة. validate يرسم القضبان؛ الذكاء الاصطناعي يجري عليها. لا يوجد جدار.

المراجع

1. Google DORA Team. DORA State of AI-Assisted Software Development 2025. Google Cloud, 2025. dora.dev/dora-report-2025
2. David L. Parnas. “On the Criteria to Be Used in Decomposing Systems into Modules.” Communications of the ACM 15(12): 1053-1058, 1972. doi:10.1145/361598.361623
3. Weslley Torres, Mark G.J. van den Brand, Alexander Serebrenik. “A Systematic Literature Review of Cross-Domain Model Consistency Checking by Model Management Tools.” Software and Systems Modeling 20(3): 897-916, 2021. doi:10.1007/s10270-020-00834-1
4. Deepak Babu Piskala. “Spec-Driven Development: From Code to Contract in the Age of AI Coding Assistants.” arXiv:2602.00180, January 2026. arxiv.org/abs/2602.00180
5. Ehsani et al. “When AI Code Doesn’t Stick: An Empirical Study on Reverted Changes Introduced by AI Coding Agents.” MSR 2026 Mining Challenge, April 2026. 2026.msrconf.org
6. Anton Jansen, Jan Bosch. “Software Architecture as a Set of Architectural Design Decisions.” EWSA 2005, LNCS 3527, Springer, 2005. semanticscholar.org
7. Marco Brambilla, Jordi Cabot, Manuel Wimmer. Model-Driven Software Engineering in Practice. 2nd ed., Springer, 2017. doi:10.1007/978-3-031-02546-4
8. GitClear. AI Copilot Code Quality 2025. February 2025. gitclear.com

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

• SSaC — Service Sequences as Code — لغة yongol الأساسية. تعلن القرارات داخل نقاط النهاية.
• Feature Chain — تتبّع full stack بمعرّف operationId واحد — تتبّع ثماني طبقات عبر operationId واحد.
• Ratchet Pattern — كيف تجعل العميل ينهي المهمة — الأساس النظري لكيفية تغذية validate للعملاء بالملاحظات.
• شفرة السقاطة المستغلة لـ IFEval — حلقة توليد شفرة تستغل انحياز التملق، وReins.

الشفرة: github.com/park-jun-woo/yongol

سجل التغييرات