خلّي Agent ديال البرمجة يرسم البروتوتايب قبل ما يكتب الكود باستعمال smyw: دليل كامل للتثبيت والمراجعة والتعليقات

شنو هو smyw

smyw، اللي كيعني “show me you want”، هو skill موجه لـ Agent ديال البرمجة، وكيخدم مع Claude Code وDeepSeek Harness وغيرهم من Agents اللي كيدعمو SKILL.md. كيخلي الـ Agent، قبل ما يبدل الصفحات أو مسارات التفاعل أو الواجهات بين الواجهة والخلفية، يقرا الكود، ويكتب spec منظم، ومن بعد يولد prototype فـ HTML بملف واحد يمكن يتحل بلا إنترنت.

هاد الـ prototype ماشي التصميم البصري النهائي، ولكن wireframe منخفض الدقة كيوضح مكونات الموديولات، أماكنها، العلاقات ديال التفعيل، والتغييرات فالوظائف. التنفيذ الرسمي خاصو يبقى تابع لقواعد التصميم الموجودة فالمشروع.

شنو المشكل اللي كيحلّو

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

1. المستخدم كيقدم المتطلب الوظيفي.
2. الـ Agent كيقرا كود المشروع وكيولد spec.json.
3. سكريبت البناء كيتحقق من spec وكيخرج preview.html.
4. المستخدم كيشوف، كيشرح، كيجر وكيضيف ملاحظات على الحل فالمتصفح.
5. المستخدم كينسخ الملاحظات وكيرجعها للمحادثة.
6. الـ Agent كيطبق الملاحظات وكيولد نسخة جديدة من الـ prototype.
7. من بعد ما كيأكد المستخدم الحل، الـ Agent كيبدا يكتب الكود.

الهدف الأساسي ديال smyw ماشي يعوض أدوات التصميم، ولكن يخلي المستخدم وAgent ديال البرمجة يوصلو لفهم مشترك قبل التنفيذ على “شنو خاصو يتبدل، فين يتحط، وكيفاش يتفعل”.

الوظائف الأساسية

الترقيم والمقارنة بين قبل ومن بعد

الـ prototype كيرسم الشاشة كاملة حسب التخطيط الحقيقي ديال الصفحة، وكيستعمل الألوان باش يميز التغييرات: الأصفر كيعني تعديل، الأخضر كيعني إضافة، والأحمر كيعني حذف. غير الموديولات اللي تبدلات فالطبقة الخارجية ديالها كيتعطى ليها رقم، باش مايبانوش علامات مكررة بزاف على العناصر الداخلية.

ملي كتضغط على رقم فاللوحة أو على لائحة التغييرات فالجهة اليسرى، اللوحة كتركز على المنطقة المعنية، والجهة اليمنى كتعرض wireframe جزئي قبل وبعد التغيير، والاختلافات بين الحقول، وشرح الـ Agent، ومكونات الكود، والدوال أو الواجهات المرتبطة.

إلا كان الموديول كامل مضاف جديد، خانة “قبل التغيير” فالتفاصيل غادي تبين أن الموديول ماكانش موجود من قبل، والأزرار والنصوص اللي داخلو ما غاديش يتعطاو ليها أرقام وحدة بوحدة.

التعبير بدقة على نقل المكونات

ملي كيتنقل مكون من بلاصة لبلاصة أخرى، المكان القديم كيبان فيه “إخراج” باللون الأحمر، والمكان الجديد كيبان فيه “إدخال” باللون الأخضر. السجلين كيقدرو يقفزو واحد للآخر، باش يتأكد المستخدم بلي ماشي حذف وإضافة جديدة ماعندهاش علاقة.

النوافذ المنبثقة والقوائم والمحتوى القابل للتوسيع

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

القوائم متعددة المستويات كتتقسم حتى هي للوحات متجاورة. المحتوى اللي كيتوسع فبلاصتو كيخلي فصفحة الأصل خانة بنفسجية بخط متقطع، كتوضح فين غادي يبان من بعد التوسيع. خطوط الانتقال بين الصفحات وتبديل الحالات كتكون مخبية افتراضياً، وتقدر تشوفها ملي كتختار العناصر المعنية، أو تفتحها كاملة من خلال “جميع الخطوط”.

وضع العرض القابل للنقر

ملي كتضغط على “▶ عرض” فالجهة الفوقانية على اليمين، الـ prototype كيخبي إطارات التغيير وكيحاكي الاستعمال الحقيقي فشاشة وحدة. يقدر يعرض فتح القوائم، خروج الأدراج، فتح النوافذ المنبثقة، تبديل حالة الأزرار والانتقال بين الصفحات.

إلا ضغطتي على منطقة ماكتقبلش التفاعل، جميع البلايص اللي ممكن تنقر عليها دابا غادي تومض بإطار أزرق، والجهة اليسرى غادي تعرض العمليات الممكنة. وضع العرض كيدعم الرجوع، البدء من الأول، والتبديل بين “قبل التغيير” و“بعد التغيير”.

التعديل المباشر وتجميع الملاحظات

• تعديل البنية: جرّ المكونات باش تبدل الترتيب أو الحاوية اللي تابعين ليها، وعدل النص، النوع، العرض والترتيب.
• تبديل الشكل: حوّل موديول داخل الصفحة لنافذة منبثقة، قائمة منسدلة، درج أو فقاعة، والنظام غادي يولد زر التفعيل والخطوط.
• التراجع والإعادة: كيدعم استعمال Ctrl أو Command مع Z للتراجع على العملية.
• ملاحظات على العناصر: زيد ملاحظة لعنصر معين من فئات بحال المكان، التفاعل، نوع المكون، الستايل، النص أو نقص فوظيفة.
• مستوى الملاحظة: تقدر تعلم الملاحظة بأنها “خاصو يتبدل”، “اقتراح” أو “سؤال”.
• الملاحظات العامة: سجل ملاحظات على الستايل، الاتجاهات المرجعية، وجاوب على أسئلة التأكيد اللي حددها الـ Agent من قبل.
• إرجاع التصحيحات: تعديلات البنية كتترسل غير على شكل تصحيحات كتحدد العناصر بالـ ID، وكتزاد فآخر الملاحظات، بلا ما تحتاج ترجع الحل كامل.

التحضير قبل التثبيت

بناء prototype ديال smyw كيحتاج غير Node.js 18 أو نسخة أحدث، والمشروع بحد ذاتو ماكيحتاجش خادم ومافيهش تبعيات وقت التشغيل. أولاً تأكد من نسخة Node.js:

node --version

إلا كنتي باغي تشغل اختبارات end-to-end ديال المستودع أو تعاود تولد screenshots، خاصك حتى تثبت Google Chrome. إلا كان التثبيت فمسار غير افتراضي، تقدر تحددو من خلال متغير البيئة CHROME.

تثبيت skill ديال smyw

الخطوة الأولى: نسخ المستودع

git clone https://github.com/nishuzumi/show-me-you-want-skill.git
cd show-me-you-want-skill

الخطوة الثانية: حط skill فبلاصة يقدر الـ Agent يقراها

مستخدمو Claude Code يقدرو ينشئو رابط رمزي عام، باش جميع المشاريع يقدرو يستعملو smyw:

ln -s "$PWD/skills/smyw" ~/.claude/skills/smyw

إلا كان الـ Agent كيقرا مجلد skills عام، تقدر حتى تربطو بـ:

ln -s "$PWD/skills/smyw" ~/.agents/skills/smyw

إلا بغيتي تفعلو غير فمشروع معين، نسخو لمجلد skill المحلي ديال داك المشروع:

cp -r skills/smyw <المشروع ديالك>/.claude/skills/smyw

من بعد التثبيت، تقدر تطلب من الـ Agent شي حاجة غادي تبدل الواجهة أو الواجهات، أو تقول ليه مباشرة: “خرج ليا prototype الأول باش نشوفو.”

شغل مثال المستودع الأول

المستودع فيه جوج أمثلة HTML واجدين، وماكاينش داعي تشغل خادم، غير حلهم مباشرة فالمتصفح:

• skills/smyw/examples/helpdesk-ai/preview.html: مثال كامل فشاشة وحدة لإضافة اقتراحات أجوبة بالذكاء الاصطناعي لمنصة خدمة الزبناء.
• skills/smyw/examples/task-tags/preview.html: مثال متعدد الصفحات كيعرض إضافة صفحة كاملة وحذف صفحة كاملة.

من بعد ما تبدل spec ديال المثال، تقدر تعاود تولد المعاينة بالأمر التالي:

node skills/smyw/scripts/build.mjs skills/smyw/examples/helpdesk-ai/spec.json

نتيجة البناء هي ملف واحد بالواجهة فقط، ويمكن يتحل ويتراجع بلا إنترنت.

الاستعمال الأساسي من المتطلب حتى الـ prototype

الخطوة الأولى: شرح المتطلب للـ Agent

حاول توضح الهدف التجاري والقيود، ولكن ماشي ضروري تحدد من الأول جميع تفاصيل الواجهة. مثلاً:

بغيت نزيد اقتراح جواب بالذكاء الاصطناعي فتفاصيل تذكرة خدمة الزبناء. قرا الصفحة الحالية والواجهات الأولاً، وماتكتبش الكود مباشرة؛ استعمل smyw وخرج prototype باش نأكد مدخل الدرج، مسار تعويض الجواب والواجهات المعنية.

الخطوة الثانية: راجع spec والمعاينة اللي تولدات

الـ Agent غادي يحفظ الحل المنظم فمجلد بحال التالي:

.smyw/<التاريخ>-<الاسم>/spec.json

من بعد كيستعمل build.mjs باش يتحقق من الملف ويولد preview.html. منين تحل المعاينة، راجع بهاد الترتيب:

1. استعمل “ملاءمة” الأول باش تدخل اللوحة كاملة فنافذة العرض.
2. تأكد واش إطارات التغيير الصفراء والخضراء والحمراء موافقة للمتطلب.
3. نقر بالتتابع على لائحة التغييرات، وراجع المقارنة بين قبل وبعد وتغييرات الحقول.
4. شوف واش المكونات والدوال والواجهات المرتبطة مطابقة للكود الحالي.
5. حل “تغييرات المسار” و“تغييرات الخلفية”، وراجع التأثير بين الطبقات.
6. دخل لوضع العرض، وجرب فعلياً القوائم والنوافذ المنبثقة والأدراج وأزرار الحالات.

الخطوة الثالثة: عدل الحل وزد الملاحظات

إلا ماكانتْش البنية كما متوقع، بدل لـ“تعديل الحل”، وجر المكونات مباشرة، أو حوّل المحتوى الداخلي لنافذة منبثقة. بالنسبة للملاحظات اللي مايناسبهاش التعديل المباشر، اختار العنصر وزد ملاحظة، وحدد الفئة والأولوية.

من الأفضل تميز بوضوح بين ثلاثة أنواع ديال الملاحظات:

• خاصو يتبدل: مشكل خاصو يتحل قبل التنفيذ.
• اقتراح: الـ Agent يقدر يقيم واش يعتمد عليه، وإذا ماعتمدوش خاصو يشرح علاش.
• سؤال: خاصو يتجاوب ويتوضح الأول، ومن بعد يتقرر كيفاش يتعدل الحل.

الخطوة الرابعة: نسخ الملاحظات وإرجاعها للـ Agent

دخل لصفحة “الملاحظات”، زيد ملاحظات الستايل العامة، وجاوب على الأسئلة اللي باقية للتأكيد، ومن بعد نقر على “نسخ الملاحظات”. لسق Markdown اللي تولد فمحادثة الـ Agent.

غالباً الـ Agent غادي يحفظ الملاحظات فـ feedback-v<N>.md، ومن بعد يشغل:

node skills/smyw/scripts/apply-feedback.mjs .smyw/<dir>/feedback-v1.md .smyw/<dir>/spec.json
node skills/smyw/scripts/build.mjs .smyw/<dir>/spec.json

apply-feedback.mjs كيدير نسخة احتياطية من spec القديم، وكيطبق التصحيحات الموجودة فالملاحظات وكيزيد رقم النسخة. إلا كانت نسخة الملاحظات ماشي مطابقة للـ spec الحالي، السكريبت غادي يرفض التطبيق، باش مايغطيش على حل أحدث.

الخطوة الخامسة: أكد الحل قبل ما تبدا البرمجة

راجع النسخة الجديدة من الـ prototype، وتأكد بلي جميع الملاحظات اللي “خاصها تتبدل” تطبقات، والأسئلة تجاوب عليها. منين مايبقى حتى مشكل، نقر على “أكد الحل، يمكن نبداو الخدمة”، ومن بعد خلي الـ Agent يدخل لمرحلة التنفيذ الرسمية.

فهم البنية الأساسية ديال spec

smyw كيستعمل شجرة وحدة باش يوصف الواجهة قبل وبعد التغيير. كل عقدة كتحدد التغيير من خلال change، بينما التفاعل والحالات كيتوصفو بواسطة on وhidden وstates.

{
  "id": "reply",
  "type": "form",
  "label": "جاوب الزبون",
  "component": "<ReplyBox>",
  "change": "modified",
  "before": { "label": "جاوب" },
  "children": [
    {
      "id": "reply-quick",
      "type": "select",
      "text": "جواب سريع",
      "change": "removed"
    },
    {
      "id": "reply-polish",
      "type": "button",
      "label": "صقل بالذكاء الاصطناعي",
      "change": "added",
      "fn": "openDraftDrawer({ mode: \"polish\" })",
      "on": [
        { "action": "open", "target": "ai-drawer" }
      ]
    }
  ]
}

هاد المثال كيبين باللي عنوان فورم الجواب تبدّل من “جاوب” لـ“جاوب الزبون”، والجواب السريع اللي كان من قبل تحيّد، وتزاد زر كيفتح درج الذكاء الاصطناعي. component كيشير لمكوّن الكود، وfn كيمثّل السلوك المرتابط ولا بلاصة مؤقتة للواجهة البرمجية.

تقدر تشوف الشرح الكامل ديال الحقول فـ spec-format.md، وقواعد تنفيذ الـAgent فـ SKILL.md.

تقنيات متقدمة للاستعمال

راقب الواجهة، المسار والجهة الخلفية فـ نفس الوقت

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

استعمل شريط الأدوات باش تفهم تأثير الكود

• حلّ “ƒ الدوال” باش تشوف السلوك ولا بلاصة الواجهة البرمجية اللي ورا العنصر.
• حلّ “المكوّنات” باش تشوف مكوّن الكود المقابل للموديول.
• حلّ “خفّي اللي ما تبدّلش” باش تركّز على النطاق المتأثر بهاد الطلب.
• إلا بغيتي تراجع العلاقة الكاملة ديال التفعيلات، حلّ “جميع الروابط”.

استعمل وضع العرض باش تتحقق من تبدّل الحالات

وضع العرض ماشي غير باش تشوف التنقل، بل مناسب حتى للتحقق من الربط بين الحالات. مثلاً، زر “بدّل فخانة الجواب” يقدر يعمّر المسودة فخانة الجواب ويسدّ الدرج. التعليقات كيتسجلو فيها أوتوماتيكياً الصفحة اللي كنت فيها، والمحتوى اللي كان محلول، وتاريخ النقرات، وهادشي كيساعد الـAgent يعاود يلقا المشكل.

خلّي المعرّفات ثابتة

التعديلات الهيكلية فالملاحظات كتتحدد بمعرّف العقدة، وداكشي علاش فالجولات المتعددة ديال التكرار خاصك تحاول تخلي معرّفات العقد الموجودة ثابتة. إلا إلا كان العنصر تحيّد ولا تبدّل المعنى ديالو بشكل كامل، ما تبدّلش المعرّف بلا سبب.

عطي أهمية للتحقق من البناء

build.mjs كيتحقق من المعرّفات المكررة، والعقد المعدلة اللي ناقصها before، واستعمال “(ما تبدّلش)” بلاصة الموديول الحقيقي، والنوافذ المنبثقة اللي ناقصها المشغّل، ومشاكل شائعة أخرى. إلا بان شي خطأ، خاصك تصلّح الـspec الأول، ومن بعد راجع النتيجة المولّدة.

تعامل مع النوافذ الضيقة وقيود البيئة المعزولة

فالنوافذ الضيقة بحال المعاينة الجانبية ديال الـAgent، كتدخل لائحة التغييرات فزر “☰ التغييرات”، والتفاصيل كتعوم فوق اللوحة. فالبيئات المعزولة والمقيّدة، المتصفح يقدر يمنع حفظ التقدم ولا النسخ الأوتوماتيكي؛ إلا فشل النسخ، الصفحة كتحدد محتوى الملاحظات أوتوماتيكياً، وساعتها ضغط على Ctrl ولا Command مع C.

تطوير المشروع واختباره

إلا بغيتي تبدّل فـsmyw راسو، تقدر تشغّل اختبارات من البداية للنهاية ولا تعاود تولّد لقطات README:

node tests/e2e.mjs
node tests/readme-shots.mjs

الاختبار كيحتاج Node.js بالإصدار 18 ولا أحدث، وGoogle Chrome. إلا ما كانش Chrome فالمسار الافتراضي، تقدر تحددو بهاد الشكل:

CHROME=/path/to/chrome node tests/e2e.mjs

المشروع خاضع لـرخصة MIT.

الخلاصة

smyw كيبدّل طريقة خدمة الـAgent ديال البرمجة من “يفهم الطلب ومن بعد يكتب الكود مباشرة” لـ“يقرا الكود الأول، كيولّد spec، كيعرض نموذج تفاعلي، كيجمع ملاحظات منظمة، ومن بعد كيبدا التنفيذ”. وكيكون مناسب خصوصاً للطلبات اللي فيها تخطيط الصفحات، النوافذ المنبثقة، تبديل الحالات، مسارات متعددة الصفحات، ولا واجهات بين الجهة الأمامية والخلفية.

بدا بالتجربة من أمثلة المستودع، وتأكد باللي الـAgent كيقدر يقرا الـskill، ومن بعد استعملو فمشروع حقيقي. باستعمال علامات التغييرات، ووضع العرض، والتحرير المباشر، والتعليقات، والملاحظات المعتمدة على الإصدارات، تقدر تنقص بزاف من سوء فهم المتطلبات، وتخلي البرمجة الرسمية مبنية على حل تم التأكد منو من قبل.