التطوير المدفوع بالمواصفات: OpenSpec و Spec Kit

يقلب التطوير المدفوع بالمواصفات حلقة prompt-and-pray المعتادة: تكتب مواصفة دقيقة — متطلبات وقصص مستخدم ومعايير قبول — ووكيل الترميز ينشئ الخطة والمهام والكود من تلك الوثيقة. المواصفة وليس سجل الدردشة هي ما تراجع وتبقى في المستودع بعد الكود يُشحن. OpenSpec و GitHub Spec Kit هما صندوقا أدوات مفتوح المصدر يربطان سير العمل هذا إلى Claude Code و Cursor وغيرهما من الوكلاء عبر أوامر مائلة ويمشي هذا المختبر كليهما end to end على ميزة صغيرة: تحديد معدل نقطة نهاية API.

ما التطوير المدفوع بالمواصفات يغيره فعلاً

في جلسة وكيل عادية تكتب تعليماً الوكيل يحرر الملفات وتراجع الفرق الناتجة. كل شيء افترضه حول النطاق والحالات الحدية ومعالجة الأخطاء بقي ضمنياً في الموجه وتعرف فقط خطأ بقراءة الكود.

التطوير المدفوع بالمواصفات (SDD) يُدرج وثيقة بين التعليمات والكود: مواصفة تنص على ما تفعله الميزة وقائمة سيناريوهات يجب أن تكون صحيحة (معايير القبول). تراجع تلك الوثيقة أولاً؛ فقط بعد ذلك يحول الوكيل الكود إلى خطة وقائمة مهام وكود. بوابة المراجعة تتحرك من “هل هذا الفرق صحيح” إلى “هل هذه المواصفات صحيحة” ومواصفات أقصر بكثير للفحص من فرق تلمس عشرات الملفات.

يطبق كلا الصندوقان أدناه هذا الشكل — اقترح/حدد خطة تنفيذ تحقق — كأوامر مائلة يشغلها الوكيل في محادثته الخاصة. تثبت CLI فقط الأداة وملفات الأوامر؛ الوكيل يشغل كل خطوة أخرى.

OpenSpec: التثبيت والاقتراح → التطبيق → حلقة الأرشيف

OpenSpec يأتي كثنائي واحد بدون اعتماد Node.js. اختر مسار تثبيت واحد:

# macOS and Linux
curl -fsSL https://raw.githubusercontent.com/Fission-AI/OpenSpec/main/scripts/binary/install.sh | sh

# Windows PowerShell
irm https://raw.githubusercontent.com/Fission-AI/OpenSpec/main/scripts/binary/install.ps1 | iex

# Alternative: npm (needs Node.js 20.19.0+) or Homebrew
npm install -g @fission-ai/openspec@latest
brew install openspec

هيّئ داخل مشروعك:

cd your-project
openspec init                        # interactive tool picker
openspec init --tools claude,cursor  # set up specific tools, no prompts

openspec init يكتب مجلد openspec/ ويطبع أي تهجي أمر مائل أدواتك المختارة تستخدم — الاسم الكنسي هو /opsx:propose لكن Cursor و Copilot تقرآه كـ /opsx-propose و Amazon Q كـ @opsx-propose و Codex كـ $openspec-propose. الملف الشخصي الافتراضي يعطي ثلاثة أوامر: /opsx:explore (ممر تفكير بدون مخاطر قبل الالتزام بخطة) /opsx:propose <change-name> (ينشئ openspec/changes/<change-name>/ مع proposal.md و specs/ مجلد و design.md و tasks.md) /opsx:apply (ينفذ المهام) و /opsx:archive (يُنقل المجلد إلى openspec/changes/archive/<date>-<change-name>/ ويدمج deltas المواصفات في مشروع openspec/specs/ مجلد).

ملف شخصي موسّع يُضيف /opsx:new و /opsx:continue و /opsx:ff و /opsx:verify و /opsx:bulk-archive و /opsx:onboard عبر openspec config profile بالإضافة إلى openspec update الذي يُحدّث ملفات الأوامر المثبتة أيضاً بعد ترقية CLI.

نفس الإجراءات موجودة كأوامر طرفية مفيدة للسيناريو أو فحص التغيير بدون فتح الوكيل:

openspec list                    # active changes
openspec list --specs            # specs with requirement counts
openspec show add-rate-limit --diff   # requirement diffs for one change
openspec validate add-rate-limit      # check one change's artifacts
openspec validate --all               # check everything
openspec archive add-rate-limit -y    # CLI equivalent of /opsx:archive

GitHub Spec Kit: دستور حدد خطة مهام تنفيذ تقارب

Spec Kit CLI بيثون مثبت مع uv:

uv tool install specify-cli
specify init my-project --integration claude
cd my-project

--integration claude يستهدف Claude Code؛ استبدله بـ copilot أو مفتاح وكيل آخر مدعوم. لـ Claude Code يكتب التثبيت ملف مهارة واحد لكل أمر تحت .claude/skills/speckit-<name>/SKILL.md يُستدعى كـ /speckit-specify و /speckit-plan وهكذا — النموذج مع الواصلة وليس /speckit.specify الموثق Spec Kit يستخدم كترميز محايد. Codex يستخدم $speckit-specify؛ Kimi يستخدم /skill:speckit-specify.

شغّل هذه واحدة تلو الأخرى في محادثة الوكيل اقرأ كل نتيجة قبل التالي:

/speckit-constitution Create principles focused on code quality, testing, and maintainability.
/speckit-specify Limit requests on POST /api/orders to protect the order service from bursts.
/speckit-plan Node.js with an in-memory token bucket per API key, no new infrastructure.
/speckit-tasks
/speckit-implement
/speckit-converge

/speckit-constitution يشغل مرة واحدة لكل مشروع ويسجل المبادئ التي تفحص كل خطوة لاحقة ضدها. /speckit-specify يُحول وصفاً بلغة طبيعية إلى spec.md — متطلبات وقصص مستخدم وليس stack التكنولوجيا. /speckit-plan ينشئ plan.md حيث يكون stack التكنولوجيا. /speckit-tasks ينشئ ترتيب معتمد tasks.md مقسماً إلى Setup و Foundational ومرحلة واحدة لكل قصة مستخدم ثم Polish. /speckit-implement ينفذ tasks.md بالترتيب ويُنتج كود تطبيق فقط. /speckit-converge يفحص النتيجة ضد كل ثلاثة artifacts؛ إلحاق فقط الكتابة الممكنة تحت قسم “Convergence” إذا وجدت فجوات ويُبلّغ Converged عندما لا شيء بقي.

ثلاث بوابات جودة اختيارية تُدرج في التسلسل الكامل (دستور → حدد → وضّح → خطة → قائمة تحقق → مهام → تحليل → تنفيذ → تقارب): /speckit-clarify يطرح حتى خمس أسئلة مستهدفة حول مناطق غير محددة بشكل كافٍ ويكتب الإجابات مرة أخرى في spec.md؛ /speckit-checklist ينشئ قائمة تحقق مملوكة من المراجع تختبر المواصفات نفسها للاكتمال؛ /speckit-analyze ممر قراءة فقط بتقرير تضارب عبر ثلاثة artifacts قبل تنفيذ أي شيء.

Spec Kit يتتبع ميزة “نشطة” عبر .specify/feature.json وليس فرع git الخاص بك. امتدادان مجمعان يتبعان نفس النمط: specify extension add bug يُضيف /speckit-bug-assess و /speckit-bug-fix و /speckit-bug-test مع التقارير تحت .specify/bugs/<slug>/؛ specify extension add assess يُضيف تدفق فكرة خمس خطوات تقييم تحت .specify/assessments/<slug>/.

OpenSpec مقابل Spec Kit في لمحة

اختر OpenSpec لحلقة خفيفة بحرية القفز في مقترح mid-implementation. اختر Spec Kit لتسلسل أكثر صرامة محقق بدستور مكتوب وفحص تناسق تلقائي قبل كتابة الكود.

المختبر: حدد حد معدل ينشئ الخطة ينفذ مراجعة

الميزة: حدد POST /api/orders إلى 20 طلب لكل دقيقة لكل مفتاح API إرجاع 429 مع رأس Retry-After عندما يتجاوز المتصل.

الخطوة 1 — اكتب معايير القبول أولاً مستقل عن أي أداة

قبل لمس أمر مائل اكتب قصة المستخدم ومعايير القبول بلغة عادية — هذه الوثيقة التي ستراجع فعلاً وThe input كلا الأداتين تحتاج.

## User story

As an API consumer, I need predictable rate limiting on order creation
so a retrying client cannot overload the order service, and so I know
exactly when to retry.

## Acceptance criteria

### Scenario: under the limit
- GIVEN an API key with fewer than 20 requests in the current minute
- WHEN it sends POST /api/orders
- THEN the request is processed normally

### Scenario: over the limit
- GIVEN an API key with 20 requests already counted in the current minute
- WHEN it sends one more POST /api/orders
- THEN the response is 429 with a Retry-After header in seconds

### Scenario: window resets
- GIVEN an API key that was rate-limited in the previous minute
- WHEN a new minute window starts
- THEN its next request is processed normally

الخطوة 2 — حوّله إلى صيغة المواصفات للأداة

مع OpenSpec شغّل /opsx:propose add-rate-limit والوكيل يصيغ openspec/changes/add-rate-limit/ لك. استبدل مسودة specs/ المُنتجة بسيناريوهات خاصة بك مترجمة إلى قواعد متطلبات OpenSpec:

## ADDED Requirements

### Requirement: Order creation rate limit
The orders API SHALL limit POST /api/orders to 20 requests per minute
per API key and SHALL reject requests over that limit with 429.

#### Scenario: Over the limit
- **WHEN** an API key sends a 21st request within the same minute
- **THEN** the API responds 429 and includes a Retry-After header in seconds

#### Scenario: Window resets
- **WHEN** a new minute window starts for a previously limited key
- **THEN** that key's next request is processed normally

مع Spec Kit شغّل /speckit-specify والصق قصة المستخدم والسيناريوهات كالحجة. إذا كان السيناريو غامضاً للوكيل — لكل مفتاح API أو لكل IP؟ — شغّل /speckit-clarify قبل المضي قدماً؛ هذا بالضبط الغموض الذي بُني للقيام به.

الخطوة 3 — خطط نفذ مراجعة ضد المواصفات

OpenSpec: حرّر design.md إذا كان لديك تفضيل تقني ثم /opsx:apply لتنفيذ. Spec Kit: /speckit-plan مع قيودك التقنية ثم /speckit-tasks ثم /speckit-implement.

ثم راجع ملف المواصفات بجانب الفرق سيناريو بسيناريو: هل الطلب 21 يحصل على 429؟ هل Retry-After يحتوي على عدد ثوان؟ هل يُعيّد المفتاح بعد انقضاء الإطار الزمني؟ احتفظ بالاختبارات في الحلقة — انظر TDD workflow with an AI agent. مع Spec Kit شغّل /speckit-converge وتوقع Converged؛ مهام مُلحقة تعني سيناريو مفقود وليس bug أداة. مع OpenSpec شغّل openspec validate add-rate-limit قبل /opsx:archive بحيث المواصفات المؤرشفة والكود المشحون يتطابقان. فقط عندئذ أرشّف أو تقارب التغيير — نفس آلية أمر مائل كلا الصندوقان يستخدمان مغطاة في custom commands lab.

المزالق

مواصفات غامضة تُنتج كود غامض. “Add rate limiting” ليست مواصفات — لا رقم لا إطار زمني لا عقد استجابة. بدون تلك الوكيل يختلقها مراجعتك ليس لها شيء ملموس للفحص ضده.

انجراف المواصفات: الوكيل يحرّر المواصفات ليطابق كوده الخاص. إذا كان الشغيل الذي كان من المفروض أن يكتب الكود أيضاً بصمت أعاد كتابة متطلب في spec.md فهذا المتطلب الآن يصف ما بناه الوكيل وليس ما طلبت. الفرق ملفات المواصفات بعد كل /opsx:apply أو /speckit-implement شغيل وليس فقط كود التطبيق.

أخضر /speckit-converge أو تنظيف /opsx:apply ليست المراجعة. /speckit-converge فقط يفحص artifacts أعطاه؛ سيقول Converged على مواصفات سيئة تم تنفيذها بشكل متسق. قراءة سيناريو بسيناريو في الخطوة 3 أعلاه هي الجزء لا استبدال فحص آلي له.

تشغيل كلا الصندوقان في نفس المستودع بدون اختيار واحد كمصدر الحقيقة. OpenSpec يكتب إلى openspec/؛ Spec Kit يكتب إلى .specify/. وكيلك ليس له طريقة لمعرفة أيهما تكريم التغيير المعطى — قرر لكل مشروع وليس لكل جلسة.

تخطي /speckit-clarify أو openspec validate لأن الميزة تبدو صغيرة. محدّد 20 طلب لكل دقيقة له قرارات غير معلنة — لكل مفتاح أو لكل IP نافذة ثابتة أو متزلجة — الرخيصة للحل قبل التخطيط وغالية للعثور عليها بعد /speckit-implement بالفعل اختار إجابة.

الأسئلة الشائعة

ما هو التطوير المدفوع بالمواصفات مع وكلاء ترميز ذكاء اصطناعي؟

إنه سير عمل حيث تكتب مواصفة أولاً — المتطلبات وقصص المستخدم ومعايير القبول كسيناريوهات ملموسة — ووكيل الترميز ينشئ الخطة والمهام والكود من تلك الوثيقة. تراجع المواصفة قبل وجود أي كود بدلاً من مراجعة الفرق بعد الوكيل بالفعل خمّن النية.

كيف يختلف OpenSpec عن GitHub Spec Kit؟

OpenSpec يأتي كثنائي واحد بحلقة افتراضية خفيفة: اقترح تطبيق أرشيف. GitHub Spec Kit CLI بيثون (مثبتة مع uv) بتدفق أطول مرحلة-بوابة — دستور حدد خطة مهام تنفيذ تقارب — بالإضافة إلى اختيار اختياري وقائمة تحقق وتحليل جودة. يفضل OpenSpec التكرار على أي artifact في أي وقت؛ يفضل Spec Kit تسلسل أكثر صرامة محقق.

ما أمر OpenSpec الدقيق لبدء تغيير جديد؟

في محادثة الوكيل اكتب /opsx:propose <change-name> (Cursor و GitHub Copilot تهجي /opsx-propose و Amazon Q تستخدم @opsx-propose و Codex يستخدم $openspec-propose). من محطة طرفية بدلاً من الوكيل openspec new change <change-name> ينشئ نفس المجلد بدون الذهاب عبر الوكيل.

أي أمر Spec Kit يكتب الكود فعلاً؟

/speckit-implement هو الأمر الوحيد الذي ينفذ tasks.md وينتج كوداً يشغل كل مرحلة بترتيب الاعتماد. /speckit-specify و /speckit-plan و /speckit-tasks فقط تُنتج قطع Markdown (spec.md و plan.md و tasks.md)؛ /speckit-converge يفحص النتيجة بعد ذلك وفقط يُلحق مهام جديدة لا يحرر الكود.

هل أحتاج إلى Python ل OpenSpec أو Spec Kit؟

يحتاج GitHub Spec Kit Python 3.11+ وأداة uv مثبتة مع uv tool install specify-cli. ثنائي OpenSpec standalone هو ثنائي واحد بدون متطلب Node.js؛ مسار npm الخاص به (npm install -g @fission-ai/openspec@latest) يحتاج Node.js 20.19.0 أو أعلى وصيغة Homebrew أيضاً متاحة.