التطوير بالتعاون مع Claude Code: TypeSafe Agent Skill
غطّت الدروس الثلاثة الأولى الأنماط المعمارية الرسمية الأربعة: الأسئلة المتوازية والتوسع التخميني، والتوجيه الذكي، والتقييم المركّب. وكما ذُكر في مقدمة المرحلة، يعالج الدرس 4 المشكلة الأخيرة: من يكتب هذه الأكواد.
الجواب الرسمي: الـ coding agent الخاص بك يكتبها — بشرط أن تثبّت عليه TypeSafe Agent Skill، وهو skill رسمي يحزم أنواع أسئلة TypeSafe وأنماط البنية وأساليب كتابة الطلبات في سير عمل الـ agent. كما يفكّك هذا الدرس مفهومًا خاطئًا شائعًا: Jev ليس بديلًا عن النموذج الكامن خلف Claude Code. المدة الإجمالية 10 دقائق.
ماذا ستستطيع أن تفعل بعد إتمام الدرس
- تثبيت TypeSafe Agent Skill في Claude Code بأمرين، وبقية الـ agents (Codex وغيره) بأمر
npxواحد، مع شرح طريقة التحديث والتحديث التلقائي - استخدام 3 من أمثلة الـ prompt الرسمية لتشغيل الـ agent: استكشاف المشروع لإيجاد نقاط الدمج، وإجراء تجارب منخفضة التكلفة بمفتاح الـ API الخاص بك، واقتراح خطط إعادة الهيكلة بالاستناد إلى الـ cookbook الرسمي
- توضيح تقسيم العمل بين Jev والـ coding agent: الـ agent يكتب الكود، وJev يتخذ القرارات داخل الكود — لا يوجد أي إعداد يُستبدل فيه النموذج الكامن خلف الـ agent بـ Jev
- تنظيم تكامل Jev وفق مبدأ «الأسئلة والعتبات في ملف واحد»، بحيث تكون مخرجات الـ agent قابلة للمراجعة والتعديل التعاوني
- استخدام مسارات استكشاف الأخطاء الرسمية لـ 5 مشكلات شائعة لتحديد الأعطال: الـ skill لا يُحمَّل، اختلاق الحقول، توجيه لا يطابق التوقعات…
المأزق الذي أنت فيه الآن
- طلبت من Claude Code ربط Jev بالمشروع، لكنه لم يقرأ الوثائق وكتب مباشرة: أسماء الحقول مختلقة (مثلًا قراءة
.confidenceمن إجابة Noul — علماً بأن Noul لا يملك هذا الحقل أصلًا)، فتفشل العملية فور التشغيل. ألصقت له نصف صفحة من الوثائق، فيصلّح موضعًا ليختلق آخر - أنا متحمس لـ Jev بوصفه «سريع ورخيص وتأتي إجاباته مع احتمالات»، وأريد إيجاد نقاط الدمج في مشروعي، لكن الوثائق الرسمية تتجاوز مئة صفحة ولا أدري من أين يجعل الـ agent يبدأ القراءة؛ وحين أختار وأترجم بنفسي إلى الـ prompt، أفوّت دائمًا قواعد جوهرية
- لا أجرؤ على إطلاق الـ questions التي يكتبها الـ agent: أوصاف الخيارات غامضة، وسؤال واحد يحشو ثلاثة قرارات، والعتبات مكتوبة بشكل اعتباطي. الكود يعمل لكن الإجابات غير مستقرة؛ وعند المراجعة تكون تعريفات الأسئلة مبعثرة في خمسة ملفات يصعب تتبعها
متى تستخدم هذه الحيلة
عندما تحتاج إلى:
- جعل الـ agents مثل Claude Code وCodex يكتبون مباشرةً كود استدعاء Jev صحيحًا — دون لصق الوثائق في السياق في كل مرة
- الفحص المنهجي للمشروع الحالي: أي التحليلات المعقدة وجداول الكلمات المفتاحية والأساليب الاستدلالية الهشة يمكن استبدالها بسؤال مُنمَّط واحد
- جعل الـ agent يتحقق تجريبيًا من صياغة الأسئلة عبر الـ API الحقيقي، بدلًا من الادعاء الجزافي بأنه «من المفترض أن يعمل»
ولا تريد:
- إطعام الوثائق يدويًا: يستهلك السياق، ولا يكتمل أبدًا
- تصحيح الحقول المختلقة والاستخدامات المتقادمة التي يخترعها الـ agent مرارًا وتكرارًا
- استلام كود تكامل مبعثر فيه تعريفات الأسئلة في كل مكان ولا يستطيع أحد مراجعته
هذا بالضبط سيناريو الاستخدام المذكور في SKILL.md: عند بناء أو مراجعة أو تصحيح أكواد تستدعي TypeSafe؛ أو عند استبدال «LLM prompt ثم تحليل»، أو مطابقة الكلمات المفتاحية، أو الأساليب الاستدلالية الهشة بسؤال مُنمَّط؛ أو عند التفكير الاستكشافي في أين يمكن إدخال «المنطق السليم القابل للبرمجة» في تطبيقك.
🎒 التحضير قبل البدء
- قراءةمقدمة مرحلة سير العمل الفعال: معرفة أن هذا الدرس هو الدرس 4 في المرحلة ويعالج مسألة «من يكتب الكود»
- تثبيت Claude Code، أو أي coding agent آخر تستخدمه (Codex أو Cursor أو opencode وغيرها) — هذا الدرس لا يعلّم تثبيت الـ agent نفسه
- لإجراء تجربة الخطوة 4: أن يكون
TYPESAFE_API_KEYمن درس الطلب الأول ما يزال صالحًا؛ إن لم يكن لديك واحد، أنشئه على console.typesafe.ai/keys - يُفضَّل أن يكون لديك مشروع حقيقي بين يديك — فـ prompt المثال في الخطوة 3 مصمم ليجعل الـ agent يحلل كودك أنت
الفكرة الجوهرية
**لنبدأ بتصحيح موضع Jev. ** تذكر في وثائق coding-agents بوضوح منذ البداية: Jev ليس بديلًا مباشرًا عن الـ LLM الكامن خلف Claude Code أو Cursor أو opencode أو Copilot أو Muse Spark أو Grok Bot أو أدوات مشابهة؛ تستخدم الـ coding agent كالمعتاد، وتجعله يكتب كودًا «يستدعي Jev لاتخاذ القرارات».
Jev هو System One نموذج قرار: لا يولّد نصوصًا ولا يكتب كودًا ولا يحاور، بل يجيب فقط على أسئلة مُنمَّطة. النص الرسمي الحرفي: لا يوجد model: "jev-latest" مثل هذا الإعداد الذي يحوّل وكيل البرمجة الخاص بك إلى وكيل مدفوع بـ Jev — فالنظامان يحلّان مشكلتين مختلفتين.
إذن ماذا يثبّت TypeSafe Agent Skill؟ ليس تغيير النموذج، بل تزويد الوكيل بالسياق. التعريف الرسمي للـ skill: منح وكيل البرمجة سياقًا كاملًا حول واجهة TypeSafe API — أنواع الأسئلة، وأنماط البنية، وأفضل ممارسات تنظيم الطلبات. إضافة إلى «دليل live docs»: يطلب SKILL.md صراحةً من الوكيل اعتبار docs.typesafe.ai المصدر الموثوق لصياغة الطلبات وSDK والحدود (limits)، بدلًا من الاعتماد على ذاكرة التدريب.
| بُعد المقارنة | وكيل بدون skill | وكيل مثبَّت عليه skill |
|---|---|---|
| حقول API | يكتبها من الذاكرة، وقد يخترع أسماء الحقول | يكتبها وفق أنواع الأسئلة الرسمية؛ وإذا لم يتأكد يراجع live docs |
| تصميم الأسئلة | prompt واحد يحشر كل الأحكام، يُخرج JSON ثم يُحلَّل | حكم واحد لكل سؤال، الإجابة مُنمَّطة، والكود يتفرّع مباشرة |
| البنية | يكتب كيفما يخطر بباله | منظَّمة وفق الأنماط الرسمية: أسئلة متوازية، بوابات (gating)، جمع الدرجات |
| طريقة التحقق | افتراض أنه «من المفترض أن يعمل» | اختبار فعلي للـ API، مع الاحتفاظ بـ payload لكل حالة |
الفلسفة الجوهرية التي يعلّمها الـ skill للوكيل: الأحكام تُعطى لـ Jev، والقرارات تبقى في الكود. يتعامل SKILL.md مع كل قرار كجدول حقائق (truth table):Jev يزوّد بالمدخلات («هل يبدو العميل محبطًا؟»، «عن أي منتج تتحدث هذه الرسالة؟»)، ويحمل الكود المنطق الذي يربط المدخلات بالأفعال. وعلى العكس، الأسئلة التي تجعل Jev يقرر مباشرة («هل يجب تصعيد هذه التذكرة؟»، «ماذا يفعل الوكيل في الخطوة التالية؟») تشير إلى أن السؤال مطروح في الطبقة الخاطئة — فكّك القرار إلى الأحكام التي يعتمد عليها، واكتب القرار نفسه في الكود، ليكون مرئيًا وقابلًا للاختبار. كود الدروس الثلاثة الأولى كله بهذا الشكل: Jev يعطي intent وcomplexity، وif/elif يحدد التوجيه.
إذا أتيت بتوقعات أخرى، فقدّمت الجهة الرسمية جدول مقارنة إضافيًا:
| ما كنت تنوي… | الطريقة الصحيحة |
|---|---|
| جعل وكيل البرمجة أفضل في كتابة كود يستدعي TypeSafe | تثبيت TypeSafe agent skill (هذا الدرس) |
| استخدام Jev في التطبيق الذي تبنيه للتوجيه والتصنيف والتقييم وحواجز الحماية | ابدأ من الطلب الأول، وللأنماط راجع الدروس الثلاثة الأولى من هذه المرحلة |
| استبدال النموذج الكامن خلف وكيل البرمجة | Jev لا يقوم بذلك. استمر في استخدام وكيل برمجة LLM، واستخدم Jev بشكل منفصل حيث يحتاج المنتج إلى قرارات سريعة ومعايَرة ومهيكلة |
| تجربته دون كتابة كود Jev | افتح Playground (console.typesafe.ai/playground)، والصق state مع سؤال |
تابعني خطوة بخطوة
الخطوة 1: تثبيت TypeSafe Agent Skill
لماذا: عندما لا يكون الوكيل قد قرأ وثائق TypeSafe، فلا خيار أمامه سوى كتابة الاستدعاءات من ذاكرة التدريب، فيسهل عليه اختراع أسماء الحقول خطأً. الـ skill يُدخل خبرة التكامل الرسمية دفعة واحدة إلى سير عمل الوكيل، وتُبنى جميع الخطوات اللاحقة على ذلك.
الطريقة A (موصى بها): إضافة Claude Code
claude plugin marketplace add typesafe-ai/skills
claude plugin install typesafe@typesafe-aiيفترض أن ترى: انتهاء الأمرين بشكل طبيعي دون أخطاء. لا تقدّم الوثائق الرسمية نصًا محددًا للمخرجات، ومعيار التحقق من نجاح التثبيت هو الخطوة التالية.
الطريقة B: وكلاء آخرون (مثل Codex، عبر skills.sh)
npx skills add typesafe-ai/skills --skill typesafe-aiاختر عند المطالبة الوكيل الذي تستخدمه. يُثبَّت افتراضيًا في المشروع الحالي؛ ولإتاحته عالميًا أضف -g.
الطريقة C: دع الوكيل يثبّته بنفسه
الصق هذا الـ prompt الرسمي للوكيل كما هو، وسيحدد البيئة بنفسه وينفّذ:
Install the TypeSafe skill. If you're in Claude Code, run `claude plugin marketplace add typesafe-ai/skills`, then `claude plugin install typesafe@typesafe-ai`. If you're in another agent, run `npx skills add typesafe-ai/skills --skill typesafe-ai` and select your agent. Use one installation method. You can read the skill directly at https://github.com/typesafe-ai/skills/blob/main/skills/typesafe-ai/SKILL.md (raw: https://raw.githubusercontent.com/typesafe-ai/skills/main/skills/typesafe-ai/SKILL.md). Then use the TypeSafe skill when working on this project.::: تحذير ⚠️ اختر طريقة واحدة فقط تنبّه الجهة الرسمية صراحةً: خلط عدة طرق يولّد نسخًا مكررة (duplicate copies). في حال التثبيت اليدوي، انسخ مجلد skills/typesafe-ai بالكامل (مع الملفات المرجعية) إلى مجلد skills الخاص بالوكيل. :::
- استخدمت طريقة تثبيت واحدة فقط
الخطوة 2: الاستدعاء بالاسم للتأكد من تحميل الـ skill
لماذا: التثبيت ≠ أن يستخدمه الوكيل تلقائيًا. طريقة الاستخدام الرسمية هي «ذكره بالاسم في الـ prompt» — قول "use the TypeSafe skill" يعمل مع أي وكيل؛ كما تتيح إضافة Claude Code استدعاء الأمر مباشرة.
أدخل في Claude Code ما يلي:
/typesafe:typesafe-aiأو اكتب في رسالة إلى وكيل آخر:
Use the TypeSafe skill when working on this project.يفترض أن ترى: ظهور سياق TypeSafe في رد الوكيل — ذكر state وquestions وأنواع الأسئلة مثل Choice/Score/Noul، أو مبادرته بقراءة الوثائق الحية docs.typesafe.ai. يحدد SKILL.md الـ live docs كمصدر موثوق لصياغة الطلبات والحدود، فالوكيل المثبَّت عليه الـ skill يراجع أولًا ثم يكتب، بدلًا من الاختلاق مباشرة.
لم يُحمَّل؟ خطوتان رسميتان للاستقصاء: تأكد أن أمر التثبيت ثبَّت للوكيل الذي تستخدمه فعلًا (تُطلب منك الاختيار عند التثبيت بالطريقة B) ← أعد تشغيل الوكيل وحاول مجددًا.
- في رد الوكيل سياق عن أنواع الأسئلة / state / questions، لا ارتجال حر
الخطوة 3: استخدام الـ prompt الرسمي النموذجي لجعل الوكيل يحدد نقاط الدمج في مشروعك
لماذا: أفضل بداية ليست أن تخبر الوكيل أين يتكامل مع Jev، بل أن يجدها الوكيل المزوَّد بالـ skill بنفسه. تصنّف الجهة الرسمية هذا بأنه «a good prompt to start with».
في مجلد مشروعك، أرسل هذا إلى الوكيل (النص الرسمي الأصلي):
Using the TypeSafe skill, explore the project and find opportunities for using
intelligent judgement to stand in for complex parsing or other fragile code.يفترض أن ترى: أن يمسح الوكيل الكود، ويشير إلى مواضع التحليل الهش وجداول الكلمات المفتاحية والقواعد الاستدلالية (heuristics)، ويقترح ما يمكن استبداله بـ «سؤال مُنمَّط + قرار في الكود».
معيار الحكم على جودة المقترحات هو جدول الحقائق نفسه من الفكرة الجوهرية: المقترح الجيد يبدو مثل «أضِف هنا سؤال Choice / Noul، ويتفرّع الكود وفق الإجابة»؛ أما إذا اقترح الوكيل «دع Jev يقرر ما إذا كانت التذكرة ستُصعَّد»، فهذا دفع للقرار نحو النموذج — يقول SKILL.md صراحةً إن مثل هذا السؤال مطروح في الطبقة الخاطئة، فاطلب منه تفكيكه إلى أحكام ثم التعديل.
- مقترحات الوكيل على شكل «إضافة أحكام وتفرّع في الكود»، لا «دع Jev يقرر»
الخطوة 4: جعل الوكيل يجري تجارب منخفضة التكلفة ويقترح خطة إعادة الهيكلة مقارنةً بالـ cookbook
لماذا: إيجاد المواضع مجرد خطة. الخطوة 3 من سير عمل الـ skill هي «probe the live API» — التحقق من صياغة الأسئلة بطلبات حقيقية حتى يطابق سلوك التطبيق التوقعات. قدّمت الجهة الرسمية promptين جاهزين.
صدّر المفتاح أولًا (إن لم يكن لديك واحد، أنشئه على console.typesafe.ai/keys):
export TYPESAFE_API_KEY="<你的API Key>"الـ prompt التجريبي (النص الرسمي الأصلي):
Using the TypeSafe skill, run some experiments using the TypeSafe API key that I've
exported to `TYPESAFE_API_KEY`. Propose changes based on the most promising results.ينبغي أن ترى: أن الوكيل يطلب إذنك أولًا — إذ يفرض SKILL.md عليه الحصول على موافقتك أولًا، وشرح البيانات التي سيتم إرسالها (خاصة البيانات الشخصية أو الخاصة بالخصوصية)، والإفصاح عن أنه سيستخدم مفتاحك، قبل أن يرسل أي طلب اختباري. سيستخدم الاختبار حالات تمثيلية + حالات صعبة + حالات سلبية إجابتها «لا»، مع الاحتفاظ بحمولة الطلب الكاملة لكل حالة، وأخيرًا يقترح تعديلات بناءً على النتائج الأكثر وعدًا.
ثم اطلب من الوكيل مقارنة الكود بكتاب الطهي الرسمي للعثور على فرص إعادة الهيكلة (النص الرسمي):
Using the TypeSafe skill, analyze my code and see if there are any applicable
cookbooks (https://docs.typesafe.ai/cookbooks) that show how I could
refactor my code to be less fragile or complex.ينبغي أن ترى: أن الوكيل يشير إلى أمثلة من كتاب الطهي الرسمي تشبه كودك — مثل استخراج البريد الإلكتروني/رقم الهاتف الهش الذي يقابل استخراج القيم المُحلَّلة مسبقًا، ومنطق التوزيع المعقد الذي يقابل توجيه النوايا — ويقدم خطة لإعادة الهيكلة وفق أنماط كتاب الطهي. التطبيق الكامل لهذه الأمثلة هو مرحلةالسيناريوهات العملية.
💡 ميزانية التجارب والأمان
النص الحرفي في SKILL.md: TypeSafe رخيص جدًا، فميزانية صغيرة تكفي لمسافة طويلة جدًا (a little can go a very long way). أعطِ الوكيل حدًا أقصى لميزانية التجارب، وتأكد من أن بيئة تشغيله تستطيع الوصول إلى نقطة نهاية API. عند الكتابة في كود الإنتاج، تتطلب قواعد التكامل في skill بقاء المفتاح على جانب الخادم.
- الوكيل حصل على إذني قبل إرسال الطلبات، وشرح البيانات التي سيتم إرسالها
الخطوة 5: اجمع الأسئلة والعتبات في ملف واحد وسلّمه للمراجعة البشرية
لماذا: الوكيل يكتب الكود بسرعة، لكن الجهة الرسمية تنبه إلى أن «الوكلاء ليسوا بارعين في كتابة الأسئلة» — صياغة الأسئلة ووصف الخيارات والعتبات هي الأجزاء التي تحتاج أكثر ما تحتاج إلى رقابة بشرية في التكامل، وهي أيضًا الأجزاء التي تُعدَّل أكثر من غيرها عند المراجعة. بجمعها في ملف واحد، يصبح لتحريرك التعاوني مع الوكيل نقطة ارتكاز.
مثلًا اجمع أسئلة التوجيه من درسالتوجيه الذكي في questions.py (تُتبع البنية طريقة كتابة صفحة الأنماط الرسمية):
# questions.py —— 所有问题与阈值集中在这里;改措辞、调阈值只动这个文件
from typesafe_sdk import Choice, Score
ROUTING_QUESTIONS = {
"intent": Choice(...), # 完整定义见「智能路由」课第 1 步
"complexity": Score(...),
}
# 阈值也收在这里:兜底线与各动作的风险阈值分开
CONFIDENCE_FLOOR = 0.5 # 分类兜底:低于它先转人工
TRANSFER_THRESHOLD = 0.85 # 高危动作:过了它才免确认自动执行مبادئ التعاون الأربعة الرسمية (agent-skill.md «Good vibe coding principles»):
- ناقش الخطة مع الوكيل حتى تتضح تمامًا أولًا — استخدم أمثلة الـ prompt أعلاه كنقطة بداية
- قبل البدء في التنفيذ، يراجع الإنسان الخطة أولًا ويتأكد من أنها منطقية
- الثوابت (الأسئلة والعتبات) تُجمع في مكان واحد لتسهيل المراجعة؛ الوكيل لا يجيد كتابة الأسئلة، والتوقع هو تحرير تعاوني
- لا تتعامل مع تأكيدات الوكيل كحقائق — شجّعه على التحقق من فرضياته
ينبغي أن ترى: ملفًا منفصلًا في المشروع يحتوي على جميع تعريفات الأسئلة وثوابت العتبات. الوكيل عند تعديل منطق الأعمال لاحقًا لا يلمسه؛ وعند ضبط صياغة الأسئلة، تراجع أنت diff لهذا الملف وحده.
- الأسئلة والعتبات في ملف واحد؛ أراجع خطة الوكيل أولًا قبل أن أدعه يبدأ العمل
نقطة تحقق ✅
- أستطيع أن أشرح موقع Jev داخل coding agent: ليس النموذج الكامن وراءه، بل محرك اتخاذ القرارات في الكود الذي يكتبه الوكيل
- داخل Claude Code يمكن استدعاء skill عبر
/typesafe:typesafe-ai؛ وفي الوكلاء الآخرين يعمل ذكر "use the TypeSafe skill" صراحةً في الـ prompt - جربت واحدًا على الأقل من أمثلة الـ prompt الرسمية الثلاثة: العثور على نقاط الاندماج / تشغيل التجارب / المقارنة مع كتاب الطهي
- الأسئلة والعتبات مجمعة في ملف واحد، وتعديل الصياغة يقتصر عليه وحده
- عندما يختلق الوكيل حقولًا، أعرف أن ردة الفعل الأولى هي تحديث skill ثم إعادة المحاولة
تنبيهات العثرات الشائعة
❌ ثبّتّ skill لكن الوكيل لا يستخدمه
الظاهرة: بعد تثبيت الإضافة، يستمر الوكيل في الارتجال عند كتابة كود Jev. مسار التشخيص الرسمي: داخل Claude Code استدعِ /typesafe:typesafe-ai مباشرة؛ الوكلاء الآخرون اذكر "use the TypeSafe skill" صراحةً في الـ prompt. إن لم ينجح ذلك، تأكد من أنك اخترت الوكيل الهدف الصحيح عند التثبيت، ثم أعد تشغيل الوكيل.
❌ الوكيل يختلق حقول الطلب/الاستجابة
الظاهرة: ظهور حقول في الكود غير موجودة في الوثائق — مثل قراءة .confidence من إجابة Noul، بينما لا يملك Noul سوى قيمة noul في نطاق 0–1. التشخيص الرسمي: skill قديم (stale skill). حدّثه بطريقتك في التثبيت ثم أعد المحاولة:
claude plugin marketplace update typesafe-ai
claude plugin update typesafe@typesafe-aiثم أعد تشغيل Claude Code أو نفّذ /reload-plugins. وللراحة يمكنك تفعيل التحديث التلقائي: /plugin → Marketplaces → typesafe-ai → Enable auto-update. لمن ثبّت عبر skills.sh استخدم npx skills update؛ ولمن نسخ يدويًا، استبدل الدليل كاملًا بأحدث إصدار من GitHub.
❌ النتائج لا تطابق التوقعات، فتشك في النموذج أولًا
الظاهرة: التصنيف أو التوجيه يبدأ في إصدار أحكام خاطئة. ترتيب التشخيص الرسمي هوفحص الأسئلة والعتبات أولًا: العتبة المرتفعة جدًا تسبب سلبية كاذبة (ما كان ينبغي أن يعمل تلقائيًا لم يعمل)، والمنخفضة جدًا تسبب إيجابية كاذبة (ما لا يُوثق به يُسمح له بالمرور)؛ بعد ذلك اجعل الأسئلة أكثر تحديدًا. تفاصيل موسعة فيتنبيهات العثرات في درس التوجيه الذكي.
❌ وضع عتبات confidence في كل مكان
تذكير رسمي: إذا كان كل ما يهمك هو اختيار الخيار الأمثل، خذ مباشرة الإجابة ذات أعلى confidence؛ وإذا كانت لديك حاجة إلى خوارزمية إحصائية محددة، فينبغي استخدام probabilities. هذه النقطة موسعة بالفعل فيدرس التوجيه الذكي، فلا تكرار.
❌ كود TypeSafe الذي يكتبه الوكيل يصعب مراجعته
الظاهرة: عند المراجعة تتناثر تعريفات الأسئلة في خمسة ملفات، وتحتاج إلى وقت طويل لجمع مجموعة كاملة من العتبات. التوصية الرسمية: أكثر ما ينبغي للإنسان مراجعته هو صياغة الأسئلة وثوابت العتبات، فاجمعها فيملف كود واحد دون حاجة للتنقل بين الملفات — وهذا بالضبط ما تفعله الخطوة 5.
تقنيات متقدمة (اختيارية)
اقرأ SKILL.md نفسه. skill هو ببساطة ملف Markdown من 288 سطرًا (بترخيص MIT، github.com/typesafe-ai/skills)، بأربعة أجزاء جوهرية: طبقات الحكم واتخاذ القرار (جدول الحقيقة)، و«اختبار الإنسان» لتصميم state (بالنظر إلى هذا الـ state وحده، هل يستطيع شخص ذكي الإجابة بسرعة بالحدس؟)، وقواعد صياغة الأسئلة (حكم واحد لكل سؤال؛ أسماء الخيارات يجب أن تصف المحتوى، لأن معرف السؤال لا يُرسل إلى النموذج)، وتفسير الإجابات (نادرًا ما يُستخدم confidence كبوابة، وعتبات البداية لـ Noul 0.7/0.3، والنظر إلى توزيع Score). معظم القواعد وردت في الدروس السابقة (Noul، Confidence)، وما تبقى ويستحق قراءته كاملًا هو «قائمة الأعلام الصفراء».
استخدم ترتيب التشخيص الخماسي من skill لمواجهة «الإجابة تبدو خاطئة». ترتيب الفحص في SKILL.md: ① الحمولة المرسلة فعليًا → ② هل يجتاز الـ state اختبار الإنسان → ③ هل توجد الإجابة الصحيحة فعلًا بين الخيارات → ④ هل يمكن تقسيم السؤال إلى أسئلة أصغر → ⑤ الصياغة. إن استمر الخطأ بعد فحص كل ذلك، فتش في نقاط الضعف المعروفة للنموذج: Jev 1.13 دليل العثرات.
تعرّف على «الأعلام الصفراء» (prompt gymnastics). الأعلام الصفراء التي تسردها الجهة الرسمية: معايير مثبتة خصيصًا لحالات اختبار معينة، وإضافة شرط فرعي مع كل حالة تفشل، وتحفظات تبرر غرابات النموذج، وعتبات مضبوطة على حالات بعينها، واختبارات تؤكد احتمالات دقيقة، وكود يتجاوز الإجابات سرًا. هذه النزعة نحو «صياغات مكتوبة لانتزاع قيم بعينها» تنهار أمام المدخلات الجديدة وإصدار النموذج التالي؛ والإصلاح البنيوي أولًا — state أفضل، أو أسئلة مستقلة مفصولة، أو تعديل الكود.
خلاصة الدرس
✅ TypeSafe Agent Skill يُثبَّت بأمرين في Claude Code (claude plugin marketplace add typesafe-ai/skills → claude plugin install typesafe@typesafe-ai)؛ الوكلاء الآخرون بأمر واحد npx skills add؛ اختر طريقة واحدة فقط لتجنب النسخ المكررة.
✅ تقسيم العمل بين Jev و coding agent: الوكيل يكتب الكود، وJev يتولى الحكم داخل الكود؛ لا يوجد تكوين model: "jev-latest" يحوّل الوكيل إلى وكيل مدفوع بـ Jev.
✅ ثلاثة أمثلة prompt رسمية: استكشاف المشروع للعثور على نقاط الاندماج، وتشغيل تجارب رخيصة باستخدام TYPESAFE_API_KEY، والمقارنة مع كتاب الطهي لاقتراح إعادة الهيكلة.
✅ مبادئ التعاون: مراجعة الخطة قبل التنفيذ؛ جمع الأسئلة والعتبات في ملف واحد؛ الوكيل لا يجيد كتابة الأسئلة، والتوقع تحرير تعاوني؛ لا تتعامل مع التأكيدات كحقائق.
✅ تشخيص خمس مشكلات شائعة: لا يُحمَّل → اذكره بالاسم / تحقق من الهدف / أعد التشغيل؛ يختلق حقولًا → حدّث skill؛ لا يطابق التوقعات → افحص العتبات والأسئلة أولًا؛ اختيار الأمثل فقط → لا تضع عتبات؛ صعوبة المراجعة → ركّز الثوابت.
مرجع سريع للأوامر الأساسية:
| العنصر | الأمر / الطريقة | المصدر |
|---|---|---|
| Claude Code التثبيت | claude plugin marketplace add typesafe-ai/skills → claude plugin install typesafe@typesafe-ai | docs/agent-skill.md |
| التثبيت في agent آخر | npx skills add typesafe-ai/skills --skill typesafe-ai (الافتراضي على مستوى المشروع، -g على المستوى العام) | كما أعلاه |
| Claude Code الاستدعاء | /typesafe:typesafe-ai (يعمل مع أي agent: اذكر "use the TypeSafe skill") | كما أعلاه |
| تحديث الإضافة | claude plugin marketplace update typesafe-ai → claude plugin update typesafe@typesafe-ai، أعد التشغيل أو /reload-plugins | كما أعلاه |
| تحديث skills.sh | npx skills update | كما أعلاه |
| التحديث التلقائي | /plugin → Marketplaces → typesafe-ai → Enable auto-update | كما أعلاه |
| مستودع الـ skill | github.com/typesafe-ai/skills (رخصة MIT؛ 2026-11-03 تم التحقق: SKILL.md 288 سطرًا، مطابق حرفيًا للنسخة المتاحة عبر الإنترنت) | تم التحقق بالجلب في الوقت الفعلي |
استعراض الدرس التالي
بعد إتمام التدريب على الأنماط الأربعة، أصبح بإمكان الـ agent كتابة الشيفرة نيابةً عنك أيضًا. المحطة التالية هي نقل هذه المنظومة كاملة إلى مشروع حقيقي — سيناريوهات عملية: اختر مسارك، وهي 15 حالة كاملة مستخلصة من cookbook الرسمي.
ستتعلم:
- اختيار الحالات وفق المسار: كل حالة تمثل الشكل الكامل لـ «تصميم state + مشكلة مُنمّطة + قرار برمجي»
- حواجز حماية LLM: فحص أمني شامل لرسائل الدخل والخرج في تطبيق LLM في طلب واحد
- التحقق من الاستشهادات، وفحص مقاطع RAG كيفية تنفيذ مهام بهذا المستوى الإنتاجي
- كيفية الدمج بين أوضاع الدروس الثلاثة الأولى داخل كل حالة