ليش بيبني الشي الغلط، وكيف Spec Kit بيمنعه؟
لما تكتب «ابنيلي تطبيق لتنظيم الصور» برومت واحد، Claude بيعبّي الفراغات لحاله: بيختار تقنيات، بيفترض ميزات، وبيبني كل شي مرة وحدة. بتكتشف الغلط بالآخر، وبتعيد البرومت 5 مرات. Spec Kit بيقلب الترتيب: المواصفات أول (شو ولمين وليش)، وبعدها الخطة (بأي تقنيات)، وبعدها المهام، وآخر شي الكود. كل مرحلة بتطلّع ملف بتقراه وبتعدّله قبل ما يكمّل.
أمر للتثبيت، أمر لإنشاء المشروع، وبعدها بتفتح Claude Code عادي.
قبل ما تبلّش: Python وuv وClaude Code
| بدك | التفاصيل |
|---|---|
| Claude Code | مثبّت وداخل بحسابك. لسا ما ثبّتّه؟ دليل التثبيت من الصفر. |
| Python | نسخة 3.11 أو أحدث. |
| uv | مدير حزم Python اللي بيثبّت Spec Kit. الأوامر تحت. |
| النظام | Mac أو Linux أو Windows. |
Mac / Linux: تثبيت uv
curl -LsSf https://astral.sh/uv/install.sh | sh
Windows — PowerShell: تثبيت uv
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
سكّر الـ terminal وافتح واحد جديد، وتأكد: uv --version.
ثبّته وابدأ مشروع (أو ضيفه لمشروع موجود)
مشروع جديد: ثبّت الأداة، اعمل المشروع باسمك مع تكامل Claude، وافتح Claude Code جوّاه:
uv tool install specify-cli
specify init my-project --integration claude
cd my-project
claude
مشروع موجود: من مجلد المشروع (بعد ما تعمل commit لشغلك):
specify integration install claude
أو بالطريقة العامة: specify init --here --force --integration claude (الـ --force بيسمح له يشتغل بمجلد مش فاضي، وممكن يستبدل ملفات Spec Kit القديمة بس، مش ملفات تطبيقك).
شو بيصير بعد الأمر؟
- بيعمل مجلد
.specify/فيه القوالب والسكربتات المشتركة. - بيضيف الأوامر كـ skills لـ Claude Code بمسار
.claude/skills/speckit-<command>/SKILL.md. افتحclaudeجوّا المجلد واكتب/speckitوبتشوفها كلها. - اختياري: لو ما بدك Claude يشغّل أوامر Spec Kit لحاله (بس لما تكتبها إنت)، ضيف للـ init:
--integration-options="--no-model-invocation".
التحديث لاحقاً:
uv tool upgrade specify-cli
specify integration upgrade claude
كلها بتنكتب جوّا محادثة Claude Code، وحدة وحدة، وبتقرأ الملف اللي طلع قبل ما تكتب التالية.
الأوامر بالترتيب جوّا Claude Code
| الأمر | شو بيعمل | الملف |
|---|---|---|
/speckit-constitution | مبادئ المشروع: جودة الكود، الاختبارات، البساطة. مرة وحدة لكل مشروع، وكل المراحل بعدها بتنفحص عليها. | ملف الدستور |
/speckit-specify + الوصف | المواصفات بكلامك: شو بدك، لمين، وليش. بدون تقنيات. | spec.md + قائمة فحص |
/speckit-clarify | اختياري: بيسألك أسئلة محددة عن النقاط الناقصة وبيدخّل أجوبتك بالمواصفات. | يحدّث spec.md |
/speckit-plan + التقنيات | الخطة التقنية: اللغة، الإطار، قاعدة البيانات، وين بينحفظ شو. | plan.md وملفات التصميم |
/speckit-checklist | اختياري: قائمة فحص لجودة المتطلبات، إنت بتعلّم عليها. | قوائم فحص |
/speckit-tasks | بيقسّم الخطة لمهام صغيرة مرتّبة حسب الاعتماد. | tasks.md |
/speckit-analyze | اختياري: تقرير بالتناقضات والفجوات بين المواصفات والخطة والمهام. ما بيعدّل شي. | تقرير بس |
/speckit-implement | بينفّذ المهام بالترتيب. لو في بنود بقائمة الفحص مش معلّمة، بيسألك قبل ما يكمّل. | الكود |
/speckit-converge | بيقارن الكود بالمواصفات والخطة والمهام. لو لقى فجوات بيضيف مهام جديدة. كرّر implement ثم converge لحد ما يكتب Converged. | يضيف لـ tasks.md |
المسار القصير اللي بالريل: specify ← plan ← tasks ← implement. والدستور مرة وحدة قبلهم، وconverge بالآخر عشان تتأكد إنه ما نسي شي.
مثال مواصفات جاهز (انسخ وجرّب)
نفس مثال GitHub الرسمي (منظّم صور) بس بالعربي وبشروط عربية. بـ Claude Code اكتب الأمر، وبعده الصق النص بنفس الرسالة:
أ) الدستور (مرة وحدة):
/speckit-constitution
مبادئ المشروع: كود بسيط وواضح أهم من الذكاء، اختبار لكل ميزة قبل ما تعتبرها خلصت، بدون مكتبات خارجية إلا لما يكون في سبب مكتوب، وكل الواجهات بالعربي مع دعم RTL.
ب) المواصفات (شو بدك، بدون تقنيات):
/speckit-specify
ابنِ لي تطبيق ويب لتنظيم صور المحل. المستخدم بيرفع صور، وبتتجمّع بألبومات حسب التاريخ تلقائياً. كل ألبوم إله معاينة مربّعات، وبقدر أسحب صورة من ألبوم لألبوم. ما بدي حسابات مستخدمين بالمرحلة الأولى. الواجهة عربية RTL، وبتشتغل من الموبايل.
ج) الخطة (التقنيات بس):
/speckit-plan
استعمل Vite مع JavaScript عادي بدون إطار. خزّن الصور محلياً على الجهاز، وبيانات الألبومات بـ SQLite. بدون أي خدمة خارجية أو سحابة بالمرحلة الأولى.
د) المهام ثم الكود ثم الفحص (بدون نص إضافي):
/speckit-tasks
/speckit-implement
/speckit-converge
- إنت /speckit-specify + الوصف. بتفتح spec.md وبتصحّح أي افتراض غلط.
- إنت /speckit-plan + التقنيات. بتقرأ plan.md.
- Claude /speckit-tasks بيطلّع قائمة مهام مرتّبة. بتشيل اللي مش لازم.
- Claude /speckit-implement بيبني مهمة مهمة، و/speckit-converge بيقارن بالمواصفات لحد ما يكتب Converged.
الإضافات: تصليح الأعطال وتقييم الفكرة
Spec Kit إله إضافات بتنزّلها من الـ terminal، وبتظهر أوامر جديدة جوّا Claude Code:
تصليح عطل بنفس الأسلوب (تقييم ← تصليح ← اختبار):
specify extension add bug
/speckit-bug-assess "Submitting an empty password crashes the login form." slug=login-crash
/speckit-bug-fix slug=login-crash
/speckit-bug-test slug=login-crash
تقييم فكرة قبل ما تبني (بتطلع بقرار: كمّل، وضّح، أو وقّف):
specify extension add assess
/speckit-assess-intake "Let users work offline and sync when they reconnect." slug=offline-mode
/speckit-assess-research slug=offline-mode
/speckit-assess-define slug=offline-mode
/speckit-assess-shape slug=offline-mode
/speckit-assess-decide slug=offline-mode
الوصف بين علامات التنصيص بتقدر تكتبه بالعربي، والـ slug خلّيه بالإنجليزي بدون مسافات (اسم الملف).
أخطاء شائعة
| الغلطة | بدالها |
|---|---|
| بتكتب التقنيات بـ specify | المواصفات للـ «شو ولمين وليش». التقنيات مكانها /speckit-plan. لو خلطتهم بيبني على افتراضات مبكرة. |
| بتكتب الأوامر كلها ورا بعض | أمر، اقرأ الملف، عدّل، وبعدها الأمر التالي. هاد كل الفرق عن البرومت العادي. |
| بتوقف بعد implement | /speckit-converge هو اللي بيكتشف المهام اللي انحذفت أو انبنت ناقصة. كرّره لحد Converged. |
| بتشغّله بمشروع موجود بدون commit | اعمل commit أو branch أول. --force ممكن يستبدل ملفات Spec Kit القديمة. |
| specify: command not found | سكّر الـ terminal وافتح جديد بعد تثبيت uv. ولسا؟ شغّل uv tool update-shell وافتح terminal جديد. |
| الأوامر مش ظاهرة بـ Claude Code | تأكد إنك فتحت claude جوّا مجلد المشروع نفسه، وإن مجلد .claude/skills/ فيه speckit-…. ولسا؟ specify integration upgrade claude. |
| مواصفات بصفحتين | فقرة أو فقرتين بتكفي، و/speckit-clarify بيسألك عن الباقي. المواصفات الطويلة بتتناقض مع حالها. |