استخدام OpenSpec في مشروع قائم

أنت لا تقوم بتوثيق قاعدة الكود بالكامل من البداية. أنت تكتب المواصفات فقط لما أنت على وشك تغييره. هذه هي أهم نقطة يجب معرفتها عند تبني OpenSpec في مشروع موجود، ولهذا السبب تم بناء OpenSpec ليكون مناسبًا للمشاريع القائمة (brownfield-first).

قد يكون أحد المخاوف الشائعة كالتالي: "عمر تطبيقي 80,000 سطر. هل يجب علي كتابة مواصفات لكل شيء قبل أن يصبح OpenSpec مفيداً؟" الإجابة هي لا. أنت تكره هذا، ونحن كذلك. يقوم OpenSpec بتنمية مواصفاتك تغييرًا تلو الآخر. التغيير الأول يوثق الجزء الذي يمسه، والتغيير التالي يوثق جزئه، ومع مرور الأشهر، تمتلئ مواصفاتك بشكل طبيعي حول العمل الذي تقوم به فعلاً.

يوضح هذا الدليل كيفية البدء من اليوم الأول دون محاولة "غمر المحيط" (boiling the ocean).

النسخة التي تستغرق ثلاثين ثانية

$ cd your-existing-project
$ openspec init          # adds openspec/ and your AI tool's commands

بعد ذلك، في الدردشة الخاصة بالذكاء الاصطناعي:

/opsx:explore            # optional: have the AI read the area you'll touch
/opsx:propose <a real, small change you actually need>
/opsx:apply
/opsx:archive

الآن، تصف مواصفاتك بالضبط الجزء من النظام الذي لمسه التغيير، ولا شيء أكثر. هذا صحيح. لقد انتهيت من القلق بشأن الـ 80,000 سطر المتبقية.

لماذا يعتبر النهج القائم على الفروقات (delta-first) هو الحل الكامل

تُكتب تغييرات OpenSpec كفروقات (deltas): ADDED، وMODIFIED، وREMOVED. يصف الفارق ما يتغير بالنسبة للسلوك الحالي، وليس النظام بأكمله.

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

لذلك، فإن دليل openspec/specs/ لا يبدأ كاملاً ومكتملًا. إنه يبدأ شبه فارغ ويستمر في التراكم. كل تغيير مؤرشف يدمج فروقه (delta) بداخله. تصبح مواصفات auth/ شاملة فقط بعد أن تكون قد أجريت عدة تغييرات تتعلق بالمصادقة، وهذا هو الوقت الذي تريدها فيه شاملة بالضبط.

إذا كنت ترغب في معرفة الآليات الأعمق، راجع Concepts: Delta Specs.

أول تغيير لك على قاعدة كود حقيقية

اختر شيئًا صغيرًا وحقيقيًا. ليس لعبة، وليس إعادة كتابة. إنه تغيير كنت تخطط للقيام به هذا الأسبوع على أي حال. التغييرات الصغيرة الأولى تعلمك سير العمل بمخاطر منخفضة.

الخطوة 1: دع الذكاء الاصطناعي يقرأ المنطقة ذات الصلة. هنا يأتي دور /opsx:explore في مشروع غير مألوف أو كبير الحجم. وجهه نحو الجزء الذي أنت على وشك لمسه ودعه يرسم خريطة لكيفية عمل الأشياء قبل اقتراح أي شيء.

You: /opsx:explore

AI:  What would you like to explore?

You: I need to add rate limiting to our public API, but I'm not sure
     how requests currently flow through the middleware.

AI:  Let me trace it... [reads the router, middleware stack, and config]
     Requests hit Express, pass through auth middleware, then your
     controllers. There's no rate-limiting layer today. The cleanest
     insertion point is a middleware right after auth. Want me to scope it?

لاحظ أن الذكاء الاصطناعي يفهم الآن هيكلك الفعلي، لذا فإن الاقتراح الذي يكتبه سيتناسب مع الكود الخاص بك، وليس قالبًا عامًا. في قاعدة كود كبيرة، هذه العادة الواحدة توفر أكبر قدر من المتاعب. راجع Explore First.

الخطوة 2: اقترح التغيير. يلتقط الاقتراح ومواصفة الفارق (delta spec) هذا التغيير فقط.

You: /opsx:propose add-api-rate-limiting

الخطوة 3: البناء والأرشفة باستخدام /opsx:apply و/opsx:archive، تمامًا مثل أي تغيير آخر. بعد الأرشفة، سيكون لديك مواصفة حقيقية لسلوك تحديد المعدل (rate-limiting) الخاص بك، مولودة من تغيير كنت بحاجة إليه على أي حال.

هل تفضل جولة إرشادية؟ استخدم onboard

إذا كنت تفضل مشاهدة الدورة بأكملها تحدث على الكود الخاص بك مع السرد القصصي، فإن الأمر الموسع /opsx:onboard يفعل ذلك بالضبط: فهو يمسح قاعدة الكود بحثًا عن تحسين صغير وآمن، ثم يرشدك عبر اقتراح التغيير وبنائه وأرشفته، موضحاً كل خطوة.

قم بتشغيل الأوامر الموسعة أولاً:

$ openspec config profile      # select the expanded workflows
$ openspec update              # apply them to this project

ثم في الدردشة:

/opsx:onboard

إنها ألطف مقدمة ممكنة على مشروع حقيقي، وستترك لك تغييرًا أصيلاً (صغيرًا) يمكنك الاحتفاظ به أو التخلص منه. راجع Commands: /opsx:onboard.

"لكن لدي بالفعل وثائق متطلبات"

ربما لديك PRD (وثيقة متطلبات المنتج)، أو SRS (وثيقة مواصفات المتطلبات)، أو مواصفة رسمية، أو نماذج TLA+. هذا جيد. أنت لا تستوردها بالكامل، ولا تتخلص منها أيضًا.

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

السبب الصريح: مواصفات OpenSpec مصممة عمدًا لتكون موجهة نحو السلوك ومحددة النطاق للتغييرات. إن PRD المكون من 40 صفحة هو مُنتج مختلف وله وظيفة مختلفة. فإن إجبار تحويل دفعة واحدة يميل إلى إنتاج مواصفة كبيرة وقديمة لا يثق بها أحد. السماح للمواصفات بالنمو من التغييرات الحقيقية يحافظ على دقتها.

You: /opsx:explore
You: Here's the section of our PRD about checkout. I'm implementing the
     "guest checkout" requirement next.
     [paste the relevant requirement]
AI:  [reads it, asks clarifying questions, then helps scope a change]
You: /opsx:propose add-guest-checkout

تنظيم المواصفات في قاعدة كود كبيرة

تعيش المواصفات تحت openspec/specs/، ومجمعة حسب النطاق (domain): وهي منطقة منطقية تتوافق مع الطريقة التي يفكر بها فريقك في النظام. لست مضطرًا لتصميم التصنيف بأكمله مقدمًا. أنشئ مجلد نطاق عندما يتطلب أول تغيير لك في تلك المنطقة ذلك.

الطرق الشائعة لتقسيم النطاقات:

• حسب مجال الميزة: auth/، payments/، search/
• حسب المكون (component): api/، frontend/، workers/
• حسب السياق المحدد (bounded context): ordering/، fulfillment/، inventory/

اختر ما يجعلك أنت أو أي شخص جديد يهز رأسه موافقًا. يمكنك التحسين لاحقاً. راجع Concepts: Specs.

المستودعات المتعددة (Monorepos) والعمل الذي يمتد عبر مستودعات

بالنسبة للمستودع المتعدد (monorepo)، فإن أبسط نموذج هو وجود دليل openspec/ واحد في جذر المستودع، مع نطاقات تتطابق مع الحزم أو الخدمات الخاصة بك. هذا يغطي معظم الفرق.

إذا كان عملك يمتد حقًا عبر مستودعات متعددة (أو عدة حزم تعتبرها منفصلة)، فإن OpenSpec يحتوي على ميزة تجريبية هي المخازن (stores): حيث يعيش التخطيط في مستودع مستقل يمكن لأي من مستودعات الكود الخاصة بك الرجوع إليه، بحيث لا يضطر الخطة إلى العيش داخل مجلد openspec/ الخاص بمستودع واحد. إنها ميزة تجريبية، لذا تعامل مع أوامرها وحالتها على أنها قيد التطور. ابدأ بـ Stores User Guide للحصول على النموذج العقلي وأبسط مسار مفيد.

بعض التحذيرات الصادقة

• قاوم الرغبة في ملء الفراغات (back-fill) كل شيء. إن كتابة مواصفات للكود الذي لا تقوم بتغييره تبدو منتجة وعادةً ما تكون كذلك، لكنها ليست كذلك. تصبح تلك المواصفات قديمة، لأن شيئًا لا يجبرها على تتبع الواقع. دع التغييرات الحقيقية تقود مواصفاتك.
• اجعل التغييرات المبكرة صغيرة. فإن تغييراتك القليلة الأولى هي بقدر ما تتعلق بتعلم الإيقاع بقدر ما تتعلق بالشحن (shipping). النطاق الضيق يجعل الدورة سريعة والدروس رخيصة.
• قم بالالتزام بـ openspec/ في git. مواصفاتك وأرشيفك ينتميان إلى نظام التحكم بالإصدار بجانب الكود الذي تصفه.
• أعطِ الذكاء الاصطناعي سياقًا. على قاعدة كود كبيرة ذات اصطلاحات قوية، املأ openspec/config.yaml في قسم context: حتى يحترم كل اقتراح المكدس (stack) والأنماط الخاصة بك. راجع Customization.

إلى أين تذهب بعد ذلك

• Explore First - العادة الأساسية لفهم الكود قبل تغييره
• Getting Started - الدليل الكامل للتغيير الأول
• Editing & Iterating on a Change - تعديل التغييرات أثناء التعلم
• Concepts: Delta Specs - لماذا تجعل الفروقات العمل في المشاريع القائمة نظيفًا
• Customization - علّم OpenSpec اصطلاحات مشروعك