OpenSpec

البدء ​

يشرح هذا الدليل كيفية عمل OpenSpec بعد تثبيته وتهيئته. للحصول على تعليمات التثبيت، راجع ملف README الرئيسي أو دليل التثبيت. هل أنت جديد في مجموعة الوثائق هذه؟ يوفر الصفحة الرئيسية للوثائق خريطة شاملة لكل شيء.

أين أكتب هذه الأوامر؟ في مكانين، والخلط بينهما هو أكثر الأخطاء شيوعاً في البداية.

  • تعمل أوامر openspec ... (مثل openspec init) في طرفية (Terminal) جهازك.
  • تعمل أوامر /opsx:... (مثل /opsx:propose) في محادثة مساعد الذكاء الاصطناعي، في نفس المربع الذي تطلب منه فيه كتابة الكود.

لا يوجد "وضع تفاعلي" منفصل لبدء التشغيل. فقط اكتب الأمر المكون من شرطة مائلة (/) في المحادثة وسيتولى المساعد باقي الخطوات. شرح كامل: كيف تعمل الأوامر.

أول خمس دقائق لك ​

الحلقة الكاملة، مع تسمية كل خطوة حسب المكان الذي تحدث فيه:

text
TERMINAL   $ npm install -g @fission-ai/openspec@latest
TERMINAL   $ cd your-project && openspec init
AI CHAT      /opsx:explore                    (اختياري: فكر في الأمر أولاً)
AI CHAT      /opsx:propose add-dark-mode      (يقوم الذكاء الاصطناعي بصياغة الخطة؛ تقوم بمراجعتها)
AI CHAT      /opsx:apply                      (يقوم الذكاء الاصطناعي ببنائه)
AI CHAT      /opsx:archive                    (تم تحديث المواصفات، وتم حفظ التغيير)

خطوتان في الطرفية للإعداد، ثم تعيش داخل المحادثة. يوضح بقية هذا الدليل ما تفعله كل خطوة وما ستراه.

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

غير متأكد مما تريد بناؤه بعد؟ ابدأ بـ /opsx:explore. إنه شريك تفكير بدون مخاطر يقرأ قاعدة الكود الخاصة بك، ويزن الخيارات، ويحول الفكرة الغامضة إلى خطة ملموسة، وكل ذلك قبل وجود أي وثيقة أو كود. عندما تصبح الصورة واضحة، يقوم بتسليم العمل إلى /opsx:propose. هذه هي أفضل عادة للعمل مع ذكاء اصطناعي قد يبني الشيء الخطأ بثقة. انظر دليل الاستكشاف.

كيف يعمل ​

يساعدك OpenSpec ومساعدك البرمجي القائم على الذكاء الاصطناعي على الاتفاق على ما يجب بناؤه قبل كتابة أي كود.

المسار السريع الافتراضي (الملف الشخصي الأساسي):

text
/opsx:explore ──► /opsx:propose ──► /opsx:apply ──► /opsx:sync ──► /opsx:archive
   (اختياري)

ابدأ بـ /opsx:explore عندما تكون تحدد ما يجب فعله، أو انتقل مباشرة إلى /opsx:propose عندما تعرف بالفعل. خيار الاستكشاف موجود في الملف الشخصي الافتراضي، لذا فهو متاح دائماً عندما تحتاج إليه.

المسار الموسع (اختيار سير العمل المخصص):

text
/opsx:new ──► /opsx:ff or /opsx:continue ──► /opsx:apply ──► /opsx:verify ──► /opsx:archive

الملف الشخصي العالمي الافتراضي هو core، والذي يتضمن propose، explore، apply، update، sync، و archive. يمكنك تمكين أوامر سير العمل الموسعة باستخدام openspec config profile ثم openspec update.

ما ينشئه OpenSpec ​

بعد تشغيل openspec init، يكون لديك هيكل المشروع التالي:

openspec/
├── specs/              # المصدر الوحيد للحقيقة (سلوك نظامك)
│   └── <domain>/
│       └── spec.md
├── changes/            # التحديثات المقترحة (مجلد واحد لكل تغيير)
│   └── <change-name>/
│       ├── proposal.md
│       ├── design.md
│       ├── tasks.md
│       └── specs/      # مواصفات جزئية (ما يتغير)
│           └── <domain>/
│               └── spec.md
└── config.yaml         # تكوين المشروع (اختياري)

مجلدان رئيسيان:

  • specs/ - المصدر الوحيد للحقيقة. تصف هذه المواصفات كيف يعمل نظامك حالياً. مرتبة حسب المجال (مثلاً specs/auth/، specs/payments/).

  • changes/ - التعديلات المقترحة. يحصل كل تغيير على مجلد خاص به يحتوي على جميع الوثائق ذات الصلة. عند اكتمال التغيير، تندمج مواصفاته في دليل specs/ الرئيسي.

فهم الوثائق (Artifacts) ​

يحتوي كل مجلد تغيير على وثائق توجه العمل:

الوثيقةالغرض
proposal.mdالـ "لماذا" و "ماذا" - يلتزم بالنية والنطاق والأسلوب
specs/مواصفات جزئية تظهر المتطلبات المضافة/المعدلة/المزالة
design.mdالـ "كيف" - النهج التقني وقرارات الهندسة المعمارية
tasks.mdقائمة مراجعة التنفيذ مع مربعات اختيار

تتبني الوثائق بعضها البعض:

proposal ──► specs ──► design ──► tasks ──► implement
   ▲           ▲          ▲                    │
   └───────────┴──────────┴────────────────────┘
            قم بالتحديث أثناء التعلم

يمكنك دائماً العودة وتحسين الوثائق السابقة كلما تعلمت المزيد أثناء التنفيذ.

كيف تعمل المواصفات الجزئية (Delta Specs) ​

المواصفات الجزئية هي المفهوم الرئيسي في OpenSpec. وهي تظهر ما يتغير مقارنة بمواصفاتك الحالية.

التنسيق ​

تستخدم المواصفات الجزئية أقساماً للإشارة إلى نوع التغيير:

markdown
# Delta for Auth

## ADDED Requirements

### Requirement: Two-Factor Authentication
The system MUST require a second factor during login.

#### Scenario: OTP required
- GIVEN a user with 2FA enabled
- WHEN the user submits valid credentials
- THEN an OTP challenge is presented

## MODIFIED Requirements

### Requirement: Session Timeout
The system SHALL expire sessions after 30 minutes of inactivity.
(Previously: 60 minutes)

#### Scenario: Idle timeout
- GIVEN an authenticated session
- WHEN 30 minutes pass without activity
- THEN the session is invalidated

## REMOVED Requirements

### Requirement: Remember Me
(Deprecated in favor of 2FA)

ماذا يحدث عند الأرشفة ​

عند أرشفة تغيير:

  1. يتم إرفاق المتطلبات ADDED بالمواصفة الرئيسية.
  2. تستبدل المتطلبات MODIFIED النسخة الموجودة.
  3. يتم حذف المتطلبات REMOVED من المواصفة الرئيسية.

ينتقل مجلد التغيير إلى openspec/changes/archive/ لسجل التدقيق.

مثال: تغييرك الأول ​

لنتناول إضافة الوضع الداكن (Dark Mode) إلى تطبيق.

1. بدء التغيير (الافتراضي) ​

text
You: /opsx:propose add-dark-mode

AI:  Created openspec/changes/add-dark-mode/
     ✓ proposal.md — لماذا نفعل هذا، وماذا يتغير
     ✓ specs/       — المتطلبات والسيناريوهات
     ✓ design.md    — النهج التقني
     ✓ tasks.md     — قائمة مراجعة التنفيذ
     Ready for implementation!

إذا قمت بتمكين ملف تعريف سير العمل الموسع، يمكنك أيضاً القيام بذلك كخطوتين: /opsx:new ثم /opsx:ff (أو /opsx:continue بشكل تدريجي).

2. ما يتم إنشاؤه ​

proposal.md - يلتزم بالنية:

markdown
# Proposal: Add Dark Mode

## Intent
Users have requested a dark mode option to reduce eye strain
during nighttime usage.

## Scope
- Add theme toggle in settings
- Support system preference detection
- Persist preference in localStorage

## Approach
Use CSS custom properties for theming with a React context
for state management.

specs/ui/spec.md - فرق يظهر المتطلبات الجديدة:

markdown
# Delta for UI

## ADDED Requirements

### Requirement: Theme Selection
The system SHALL allow users to choose between light and dark themes.

#### Scenario: Manual toggle
- GIVEN a user on any page
- WHEN the user clicks the theme toggle
- THEN the theme switches immediately
- AND the preference persists across sessions

#### Scenario: System preference
- GIVEN a user with no saved preference
- WHEN the application loads
- THEN the system's preferred color scheme is used

tasks.md - قائمة مراجعة التنفيذ:

markdown
# Tasks

## 1. Theme Infrastructure
- [ ] 1.1 Create ThemeContext with light/dark state
- [ ] 1.2 Add CSS custom properties for colors
- [ ] 1.3 Implement localStorage persistence

## 2. UI Components
- [ ] 2.1 Create ThemeToggle component
- [ ] 2.2 Add toggle to settings page
- [ ] 2.3 Update Header to include quick toggle

## 3. Styling
- [ ] 3.1 Define dark theme color palette
- [ ] 3.2 Update components to use CSS variables

3. التنفيذ ​

You: /opsx:apply

AI:  Working through tasks...
     ✓ 1.1 Created ThemeContext with light/dark state
     ✓ 1.2 Added CSS custom properties to globals.css
     ✓ 1.3 Implemented localStorage persistence
     ✓ 2.1 Created ThemeToggle component
     ...
     All tasks complete!

أثناء التنفيذ، إذا اكتشفت أن التصميم يحتاج إلى تعديل، قم بتحديث الوثيقة واستمر.

4. الأرشفة ​

You: /opsx:archive

AI:  Archiving add-dark-mode...
     ✓ Merged specs into openspec/specs/ui/spec.md
     ✓ Moved to openspec/changes/archive/2025-01-24-add-dark-mode/
     Done! Ready for the next feature.

أصبحت مواصفاتها الجزئية الآن جزءاً من المواصفات الرئيسية، مما يوثق كيف يعمل نظامك.

التحقق والمراجعة ​

استخدم واجهة سطر الأوامر (CLI) للتحقق من تغييراتك:

bash
# List active changes
openspec list

# View change details
openspec show add-dark-mode

# Validate spec formatting
openspec validate add-dark-mode

# Interactive dashboard
openspec view

الخطوات التالية ​