طريقة العمل
كيف أسلّم المشاريع — workflow مبني على المواصفات لوكلاء الذكاء الاصطناعي
بنيت workflow يقسّم ملف Figma وتحليل الأعمال إلى حزم صغيرة، حزمة لكل ميزة، ثم ينفّذ وكيل ذكاء اصطناعي كل حزمة وفق قواعد معمارية لا يستطيع تجاوزها. أستخدمه في مشاريعي وعلّمته لمطوّرين آخرين.
لماذا بنيته
اطلب من وكيل ذكاء اصطناعي أن يبني module الطلبات، وستحصل على كود يبدو معقولًا لكنه لا يطابق التصميم ولا قواعد العمل. وكل جلسة تخترع معماريتها الخاصة، فلا تشبه الميزة العاشرة الميزة الأولى.
المشكلة في الغالب ليست في النموذج، بل في المدخلات. ملف Figma كامل ووثيقة تحليل طويلة أكبر وأكثر غموضًا من أن يُنفَّذ منهما مباشرة، سواء كان المنفّذ وكيلًا أو إنسانًا.
لذلك يفعل الـ workflow شيئين: يقسّم المشروع إلى قطع صغيرة لا تترك مجالًا للتخمين، ويعطي الوكيل قواعد ثابتة من أول ميزة إلى آخر ميزة.
المرحلة الأولى: من التصميم والتحليل إلى حزم الميزات
سحب ملف Figma بصيغة JSON
سكريبت يستدعي Figma API ويحفظ الملف الخام.
اختزاله إلى spec
سكريبت ثانٍ يُبقي ما يحتاج الـ Backend إلى معرفته (الشاشات والحقول والمسارات) ويحذف بيانات الرسم.
التقسيم حسب الـ actor
العميل، ومقدّم الخدمة، والمندوب، والمشرف. يُقسَّم ملف الـ spec وتحليل الأعمال معًا، فيصبح لكل actor ملف شاشاته وملف قواعد عمله.
تقسيم كل actor إلى ميزات
ثلاث جلسات منفصلة للوكيل، لكل جلسة مهمة واحدة: المسح والفهرسة، ثم استخراج الأجزاء، ثم بناء الحزم.
حزمة لكل ميزة
الشاشات وقواعد العمل وأمر التنفيذ في مجلد واحد مرقّم.
تحتوي حزمة الميزة على ثلاثة ملفات:
- شاشات هذه الميزة، كجزء مقتطع من ملف الـ spec.
- قواعد العمل الخاصة بهذه الميزة، كجزء مقتطع من التحليل.
- أمر التنفيذ: ما المطلوب بناؤه، وعلى أي ميزات يعتمد، ومن أين جاء كل متطلب.
قاعدتان مكتوبتان في كل حزمة. إذا تعارض التصميم مع تحليل الأعمال فالتحليل هو المرجع. ولا يحق للوكيل أن يخترع قاعدة عمل غير موجودة في الحزمة. وكل حقل وكل قاعدة يحمل وسمًا يبيّن هل مصدره التحليل أم التصميم.
المرحلة الثانية: تنفيذ الميزة
المشروع نفسه يحمل القواعد. أسمّي الملف الرئيسي «الدستور». يقع في نحو 1,500 سطر ويثبّت ما لا ينبغي أن يختلف بين ميزة وأخرى: الطبقات، والتسمية، وشكل الـ DTOs والـ requests، وشكل الاستجابة الموحّد، والترجمات، وتوثيق الـ API، وأداء الاستعلامات، وبيانات الـ seeders.
قرار واحد يُتخذ مرة واحدة لكل مشروع ثم يُقفل: هل يستخدم الكود طبقة repository أم مسارًا أخفّ من الـ service إلى الـ model مباشرة. يسأل الوكيل عند أول ميزة، ويسجّل الإجابة، ولا يسأل بعدها.
لبناء ميزة أكتب اسم مجلدها ثم كلمة «نفّذ».
قراءة الحزمة والدستور ثم فتح branch
البناء بترتيب ثابت
Migrations ثم enums ثم DTOs ثم repositories ثم services ثم requests ثم resources ثم controllers ثم routes.
مزامنة مجموعة الـ API بعد كل endpoint
لا يستمر العمل حتى يوجد الـ request في المجموعة المشتركة.
شاشات لوحة التحكم، والترجمات، و feature tests، وتوثيق الـ API
تشغيل بوابة الجودة
قائمة تحقق من نحو 25 بندًا. كل بند غير محقَّق يُصلَح قبل اعتبار الميزة مكتملة.
Commit ثم push ثم فتح merge request
بعدها تنتقل الحزمة إلى مجلد المنتهي، فتبقى قائمة الميزات المفتوحة هي دائمًا قائمة العمل المتبقي.
اسم المجلد نفسه مع كلمة «راجع» يشغّل وضعًا مختلفًا. يقارن الوكيل الكود الموجود بالحزمة وبالدستور، ويعيد كتابة ما يخالف القواعد، وينشئ ما ينقص. وهذا يجعل الـ workflow صالحًا لمشروع مبني نصفه بالفعل.
ما أضفته في أحدث مشروع
في Al-Kout أبقيت على حزم الميزات وغيّرت طريقة قيادة العمل.
- دورات التسليم. تُجمَّع الميزات في دورات. تبدأ كل دورة بوكيل تخطيط يكتب خطة: الكيانات المشتركة، وآلة الحالات، وترتيب الـ pull requests، وسيناريو القبول، وقائمة أسئلة موجّهة إليّ. أجيب عن كل الأسئلة دفعة واحدة قبل كتابة أي كود.
- وكلاء منفصلون للتخطيط والتنفيذ والمراجعة. لا يراجع وكيل عمله بنفسه.
- الفرز قبل الكود. الحزمة التي تصف هيكل تنقّل أو ميزة واجهة فقط تُصنَّف كمرجع للـ Frontend، ولا يُكتب لها كود Backend.
- سجل واحد للعمل المؤجَّل. لكل تأجيل متفق عليه معرّف وسبب ووصف لما تبقّى. ولا يحق للوكيل أن يسجّل موافقة لم أعطها.
- Skills. ثلاثة عشر إجراءً صغيرًا قابلًا لإعادة الاستخدام، مثل إنشاء DTO أو إنشاء repository أو مراجعة endpoint.
أين أبقى أنا في الدورة
قاعدتان أهم من الباقي:
- السؤال الذي لا تغطيه الخطة يوقف العمل. الوكيل يسأل ولا يفترض.
- لا يُدمج شيء دون قرار صريح مني.
وفيما عدا ذلك التقسيم بسيط. أنا أختار المعمارية وأكتب القواعد. أنا أجيب عن أسئلة العمل. أنا أراجع كل pull request وأشغّل مجموعة الاختبارات كاملة بنفسي. والوكيل يكتب الكود بترتيب لا يتغيّر.
ماذا أنتج
- Msane، أول مشروع كامل يُبنى بهذه الطريقة: سوق B2B سُلِّم في نحو سبعة أسابيع ونصف بمطوّر Backend واحد.
- Al-Kout: 123 حزمة ميزة لثلاثة أنواع من المستخدمين، سُلِّمت في ثماني دورات خلال أربعة أسابيع، مع نحو 1,800 دالة اختبار.
- علّمت الـ workflow لمطوّرين آخرين واستخدموه بعدها في مشاريعهم.
ما الذي لا يحلّه
السرعة تنقل نقطة الاختناق إلى مكان آخر. تصبح المراجعة هي الخطوة البطيئة، ويجب أن تبقى دقيقة. والربط مع الخدمات الخارجية مثل بوابات الدفع ومزوّدي الـ SMS ما زال ينتظر الحسابات وبيانات الاعتماد والاختبار على الخدمة الحقيقية. والكود الصحيح في الاختبارات ما زال يحتاج إلى التحقق على قاعدة بيانات حقيقية تحت حمل متزامن.