إنتقل إلى المحتوى الرئيسي
متوسط

التطوير المبني على المواصفات مع Spec Kit

البرمجة الارتجالية — "ابنِ لي لوحة تحكم"، وتقبّل أيًّا كان ما يُعاد إليك — تعمل بشكل رائع حتى تكبر الميزة. عندها ينحرف الوكيل: ينسى قرارًا سابقًا، أو يعيد اختراع دالة، أو يطرح شيئًا يعمل تقنيًا لكنه ليس ما قصدته. التطوير المبني على المواصفات (SDD) هو الحلّ الذي انتشر بين أوساط البرمجة الوكيلية في 2026: بدلًا من التعامل مع الموجّه باعتباره قابلًا للرمي، تجعل مواصفة مكتوبة وقابلة للمراجعة هي مصدر الحقيقة وتدع الوكيل يولّد الشيفرة انطلاقًا منها.

تحوّل Spec Kit مفتوح المصدر من GitHub هذه الفكرة إلى سير عمل ملموس يمكنك تشغيله داخل Claude Code اليوم.

What you'll learn
  • فهم ما هو التطوير المبني على المواصفات والمشكلة التي يحلّها
  • اجتياز مراحل Spec Kit: الدستور ← التحديد ← التخطيط ← المهام ← التنفيذ
  • تثبيت أداة Specify CLI وربطها داخل Claude Code
  • معرفة بوّابات الجودة الاختيارية (التوضيح، التحليل، قائمة التحقق)
  • تحديد متى يستحق SDD العبء الإضافي ومتى تتخطّاه

لماذا المواصفات وليس مجرّد موجّهات​

الموجّه يختفي لحظة انتهاء الدور. أما المواصفة فهي مُنتَج: يمكن قراءتها ومراجعتها في طلب سحب وتصحيحها وإعادة تشغيلها. هذا التحوّل الوحيد يصلح الطرق الثلاث التي تنحرف بها عمليات البناء الوكيلية الكبيرة:

  • الانحراف — يناقض الوكيل قرارًا سابقًا لأن لا شيء دوّنه. المواصفة هي الذاكرة.
  • الغموض — "اجعله لطيفًا" يعني عشرة أشياء مختلفة. إجبار المتطلبات على هيئة نثر يُبرز الثغرات قبل وجود الشيفرة، حيث يكون إصلاحها رخيصًا.
  • الفروق غير القابلة للمراجعة — من الصعب الحكم على طلب سحب مُولَّد من 2000 سطر. المواصفة + الخطة المراجَعتان تجعلان الفرق متوقّعًا بدلًا من أن يكون مفاجئًا.

النموذج الذهني: النيّة هي الشيء عالي القيمة والدائم؛ والشيفرة مُنتَج لاحق وقابل لإعادة التوليد. SDD هو ابن العمّ المنضبط لـPlan Mode الخاص بـ Claude Code — خطّط أولًا، ثم ابنِ — موسّعًا إلى ميزة كاملة ومحفوظًا في ملفات داخل مستودعك.

سير عمل Spec Kit​

ينظّم Spec Kit الميزة كخطّ أنابيب قصير من أوامر الشرطة المائلة. كل واحد منها يكتب مُنتَجات Markdown داخل مستودعك (تحت .specify/)، فتكون كل مرحلة قابلة للفحص وخاضعة للتحكم بالإصدارات.

Guided walkthrough1 of 5
  1. شغّل /speckit.constitution مرة واحدة لكل مشروع. يكتب المبادئ الحاكمة — نمط الشيفرة، حدّ الاختبارات، الثوابت المعمارية غير القابلة للتفاوض — في .specify/memory/constitution.md. تُفحَص كل مرحلة لاحقة مقابله، فهو حاجز الحماية الدائم لديك (اعتبره ملف CLAUDE.md مركّزًا على المبادئ).

بوّابات الجودة الاختيارية​

ثلاثة أوامر إضافية تُحكم الحلقة عندما تكون الميزة عالية المخاطر:

  • /speckit.clarify — يستجوب المواصفة بحثًا عن المناطق غير المحدّدة بدقّة ويطرح عليك أسئلة موجّهة قبل التخطيط. الأفضل تشغيله مباشرة بعد specify.
  • /speckit.analyze — يتحقق متقاطعًا من المواصفة والخطة والمهام بحثًا عن الاتساق وثغرات التغطية.
  • /speckit.checklist — يولّد قائمة تحقق للتحقق بحيث يكون "المُنجَز" مُعرَّفًا وقابلًا للاختبار.
Pro tip
  • شغّل /speckit.clarify قبل /speckit.plan — إصلاح الغموض أرخص ما يكون قبل تثبيت المعمارية.
  • تعامل مع كل مُنتَج مُولَّد كأنه طلب سحب: اقرأه، صحّحه، وعندئذٍ فقط انتقل إلى المرحلة التالية.
  • أودِع مُنتَجات .specify/ — فهي السجلّ القابل للمراجعة للنيّة الكامنة وراء الشيفرة.

شغّله مع Claude Code​

يأتي Spec Kit مع أداة سطر أوامر، Specify، تُنشئ سقالة أوامر الشرطة المائلة داخل مشروعك. وهو يدعم أكثر من 30 وكيل برمجة، ومن بينها Claude Code.

Guided walkthrough1 of 3
  1. استخدم uv لتثبيتها من المستودع. (مطلوب Python + uv.)

Install the Specify CLI (uv)

uv tool install specify-cli --from git+https://github.com/github/spec-kit.git

Scaffold spec-driven workflow into a project

# new project
specify init my-feature

# or in the current repo
specify init --here

Then, inside Claude Code, run the pipeline

/speckit.constitution Establish principles: TypeScript strict, tests for every public function, no secrets in code.
/speckit.specify Build a CSV export for the reports page: users pick a date range and download a CSV of matching rows.
/speckit.clarify
/speckit.plan Next.js App Router, server action for the query, stream the CSV; no new dependencies.
/speckit.tasks
/speckit.implement
Watch out
  • تتغيّر راية اختيار الوكيل الدقيقة لـ specify init بين الإصدارات — راجع دليل البدء السريع في README بدلًا من نسخ راية بشكل أعمى.
  • لا يلغي SDD الحاجة إلى التحقق: اقرأ الشيفرة المُولَّدة وشغّلها. المواصفة تجعل الفرق قابلًا للمراجعة، لا صحيحًا تلقائيًا.
  • لا تضع أبدًا أسرارًا أو بيانات اعتماد في المواصفة أو الخطة أو الدستور — فهي تُودَع كأي ملف آخر.

متى تستخدمه (ومتى لا)​

يبادل SDD المراسم المسبقة بالتحكّم. تلك المبادلة تستحق العناء حين يكون العمل كبيرًا أو غامضًا أو يجب أن يراجعه آخرون — وعبءٌ صرف حين لا يكون كذلك.

What you'll learn
  • لجأ إلى SDD: الميزات الحديثة من الصفر، عمليات البناء متعددة الملفات، أي شيء يجب أن يراجعه زميل، أو عمل ستسلّمه لأسطول من الوكلاء الفرعيين.
  • تخطَّ SDD: السكربتات لمرة واحدة، الإصلاحات الصغيرة، الشيفرة الاستكشافية القابلة للرمي — موجّه بسيط أو Plan Mode أسرع.
  • العمل على الشيفرة القائمة يصلح أيضًا: وجّه /speckit.specify نحو تحسين لقاعدة شيفرة قائمة، لا للمشاريع الجديدة فقط.
SDD at a glance
اضغط Enter أو مفتاح المسافة لقلب البطاقة. استخدم مفتاحي السهمين الأيسر والأيمن للتنقل بين البطاقات.تم إظهار المصطلح.
1 / 5

اختبر نفسك​

Check yourself

0/3
  1. ما الفكرة الجوهرية للتطوير المبني على المواصفات؟
  2. أي مرحلة من Spec Kit يجب أن تلتقط مكدّس التقنيات والمعمارية؟
  3. متى لا يستحق التطوير المبني على المواصفات العبء الإضافي؟
Key takeaways
  • يجعل التطوير المبني على المواصفات مواصفةً قابلة للمراجعة — لا الموجّه — مصدر الحقيقة، قاتلًا الانحراف والغموض والفروق غير القابلة للمراجعة.
  • يجلب Spec Kit من GitHub (أداة Specify CLI) نهج SDD إلى Claude Code كأوامر شرطة مائلة /speckit.*.
  • خطّ الأنابيب هو constitution ← specify ← (clarify) ← plan ← (analyze) ← tasks ← (checklist) ← implement، وكل منها يكتب مُنتَجات قابلة للفحص.
  • أبقِ الماذا/اللماذا في المواصفة والكيف في الخطة؛ وراجع كل مُنتَج كأنه طلب سحب قبل المضيّ.
  • استخدمه للميزات الكبيرة أو الغامضة أو المراجَعة؛ وتخطّاه للعمل القابل للرمي — ودائمًا تحقّق مع ذلك من الشيفرة المُولَّدة.

التالي​

  • Plan Mode — الحلقة المدمجة الأخفّ "خطّط قبل أن تبني"
  • Slash Commands — كيف تتوافق أوامر /speckit.* مع نظام أوامر Claude Code
  • CLAUDE.md & Memory Files — فكرة المبادئ-كذاكرة الكامنة وراء الدستور
  • Subagents — سلّم قائمة مهام مراجَعة إلى أسطول من الوكلاء
  • Coding & Software Development — عقلية تحقّق-من-كل-شيء التي يعتمد عليها SDD

المصادر وقراءات إضافية​