OpenSpec

إعداد مشروعك ​

أضف OpenSpec إلى مشروع: شغّل init، وانظر ما كتبه، وعدّله.

اختر مكان OpenSpec ​

  • في مستودعك (الافتراضي): المواصفات والتغييرات تجلس بجانب الكود الذي تصفه وتُدار معه بالإصدارات. بقية هذه الصفحة تتبع هذا المسار.
  • في مخزن: مستودع تخطيط منفصل مشترك بين المستودعات التي تستخدمه، لإعدادات متعددة المستودعات أو لإبقاء التخطيط خارج المستودع تمامًا. المخازن (تجريبي) يغطي متى يستحق الأمر ذلك وكيفية إعداده.

تهيئة مشروعك ​

مع تثبيت CLI (التثبيت)، شغّل init في جذر مشروعك. في الطرفية:

bash
cd <your-project>
openspec init

يسأل init عن أدوات الذكاء الاصطناعي التي تستخدمها، ويكتب ملفات سير العمل للأدوات التي تختارها، ويبلغك بما حصلت عليه:

OpenSpec Setup Complete

Created: Claude Code
6 skills and 6 commands in .claude/
Config: openspec/config.yaml (schema: spec-driven)

أعد تشغيل IDE الخاص بك لكي تسري الأوامر الجديدة.

إعادة تشغيل init آمنة:

  • الأدوات التي قمت بإعدادها بالفعل تطبع Refreshed بدلاً من Created.
  • تشغيل init مرة أخرى مع أداة جديدة محددة يضيف تلك الأداة.
  • علامة --tools تتخطى المنتقي (مرجع CLI).

ترحيل project.md موجود ​

لا ينسخ init ملف openspec/project.md القديم إلى config.yaml. بل يحتفظ بالملف ويطبع طلب ترحيل بمساعدة الذكاء الاصطناعي.

في محادثة الذكاء الاصطناعي الخاصة بك:

Review openspec/project.md and migrate its useful content to openspec/config.yaml.
Keep context concise: include only project-wide facts needed during artifact creation, apply, and archive.
Move artifact-specific guidance into rules for the matching artifacts.
Move guidance for apply or archive into the matching operations entry.
Leave out generic, outdated, or verbose material. Do not delete project.md.

راجع config.yaml، ثم احذف project.md عندما تكون جاهزًا.

ما يثبّته init ​

تشغيل init ينشئ شيئين في مشروعك:

  • مجلد openspec/ في جذر المستودع
  • ملفات سير العمل (المهارات والأوامر) المضافة إلى مجلد أداة الذكاء الاصطناعي الخاصة بك (.agents/، .claude/، إلخ.)

التزم بكل ذلك مثل بقية مصدرك. لا يغيّر init أي شيء آخر في مستودعك (إذا وجد بقايا من إصدار OpenSpec أقدم، فإنه يسأل قبل تنظيفها).

مجلد openspec/ ​

كل أثر OpenSpec يعيش هنا، في جذر مشروعك. إليك كيف يبدو ذلك:

openspec/
├── config.yaml     project settings and context for the AI
├── specs/          your specs (empty for now)
└── changes/        in-motion changes (empty for now)
    └── archive/    completed changes move here

إعدادات المشروع يغطي config.yaml.

ملفات سير العمل (المهارات والأوامر) ​

هذه هي سير عمل OpenSpec، الإجراءات التي ستستخدمها أثناء عملك. إليك كما هي مثبتة كمهارات، في مجلد .agents/ المشترك الذي تستخدمه معظم الأدوات:

.agents/skills/
├── openspec-explore/              think through an idea first
├── openspec-propose/              propose a change
├── openspec-apply-change/         implement a change's tasks
├── openspec-update-change/        revise a change's plan
├── openspec-sync-specs/           sync a change's spec updates into specs/
├── openspec-archive-change/       move a finished change to the archive
├── openspec-verify-change/        check the implementation matches the plan (not included by default)
└── openspec-bulk-archive-change/  archive several changes at once (not included by default)

هذه هي المجموعة الافتراضية بالإضافة إلى سير عمل اختياريين. الملفات التعريفية يسرد جميع الاثني عشر.

بشكل افتراضي، يُثبَّت كل سير عمل في شكلين:

  • مهارة (openspec-apply-change): تعليمات يلتقطها وكيلك تلقائيًا عندما تطلب العمل.
  • أمر (/opsx:apply في Claude Code): نقطة إدخال مكتوبة لنفس سير العمل، تحت اسم أقصر.

الاثنان متطابقان وظيفيًا. مهارة سير العمل وأمره يحملان نفس التعليمات.

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

بعض الأدوات تُثبَّت بشكل المهارات فقط. حيث تشغّل الأداة المهارات مباشرة، يتخطى init الأوامر ويقول ذلك (Commands skipped for: codex (uses skills)).

نفضّل المهارات ونتوقع إيقاف الأوامر في النهاية.

تغيير ما يتم تثبيته ​

المنتقي التفاعلي يغيّر شكل التسليم ومجموعة سير العمل (الملفات التعريفية). في الطرفية:

bash
openspec config profile

إليك التبديل إلى المهارات فقط:

Current profile settings
  Delivery: both

? What do you want to configure? Delivery only
? Delivery mode (how workflows are installed): Skills only

Config changes:
  delivery: both -> skills
? Apply changes to this project now? (Y/n) y

الإجابة بنعم تطبّقها على المشروع الحالي فورًا. المشاريع الأخرى ستلتقطها في عملية openspec update التالية. الإعداد عام، لكل جهاز.

Claude Code لا يعرض سير العمل ​

يحمّل Claude Code سير عمل OpenSpec من مسار واحد أو كلا المسارين التاليين في المشروع، بناءً على إعداد التسليم لديك:

  • المهارات: .claude/skills/openspec-*/SKILL.md
  • الأوامر: .claude/commands/opsx/<id>.md

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

bash
openspec update

إذا كانت ملفات الأوامر موجودة ولكن /opsx: لا يعرض أي أوامر OpenSpec، قم بتحديث Claude Code وأعد تشغيله. إذا لم تُحمَّل الأوامر بعد، قم بتمكين المهارات أيضًا. في الطرفية:

bash
openspec config set delivery both
openspec update

أعد تشغيل Claude Code، ثم شغّل /openspec-propose في محادثته. إذا كانت بعض سير العمل مفقودة فقط، غيّر ملفك التعريفي.

اكتمل الإعداد. البدء السريع يأخذ أول تغيير لك من هنا.