استخدام OpenSpec ضمن فريق

كل ما ورد في الأدلة الأخرى يعمل بنفس الطريقة سواء كنت تعمل منفردًا أو ضمن فريق مكون من عشرين شخصًا. ما يتغير عند العمل ضمن فريق هو الأسئلة المتعلقة بالجوانب المحيطة: أين توجد الـ specs، كيف يراجع أعضاء الفريق الخطة، وكيف يتناسب كل هذا مع سير عمل طلبات السحب (pull-request) الذي نستخدمه بالفعل؟

الإجابة المختصرة: التغيير (change) هو مجرد ملفات، ولا يتعامل OpenSpec أبدًا مع git. لذلك فهو يتناسب مع سير عملك الحالي بدلاً من استبداله. توضح هذه الصفحة الاتفاقيات التي تعمل بشكل جيد.

قاعدة واحدة: OpenSpec لا يتعامل مع git

يقرأ OpenSpec ويكتب ملفات Markdown عادية داخل المجلد openspec/. لا يقوم أبدًا بعملية commit أو إنشاء فروع (branches) أو دفع (push) أو سحب (pull) تغييرات في مشروعك — ولا يستنسخ (clone) أو يزامن (sync) مخزنًا (store) المخزن من تلقاء نفسه. هذا يعني أن:

• تقوم بعمل commit للمجلد openspec/ كما تفعل مع أي مصدر آخر. تعتبر الـ specs والتغييرات النشطة (active changes) والأرشيف (archive) جزءًا من سجل مشروعك. (نعم، قم بعمل commit للمجلد بالكامل — راجع الأسئلة الشائعة (FAQ).)
• التغيير (change) هو مجلد تقوم بإدارة إصداراته (version) له كما تفعل مع الكود البرمجي. openspec/changes/add-dark-mode/ هو مجرد ملفات موجودة على فرع (branch).
• كل ما يلي هو اتفاقيات وليس إلزامًا. لن يجبرك OpenSpec على القيام بهذه الطريقة؛ إنما يتناسب معها بشكل سلس فقط.

سير العمل اليومي

سير العمل الذي يثبت نجاحه يعرّف التغيير مقابل فرع وطلب سحب (pull request):

git switch -c add-dark-mode        ابدأ فرعًا كما تفعل عادةً
   │
/opsx:propose add-dark-mode        صياغة الخطة (proposal + specs + tasks)
   │
مراجعة الخطة                    تقرأه قبل أي كود برمجي — راجع مراجعة التغيير (Reviewing a Change)
   │
/opsx:apply                        بنائه؛ artifacts + التغييرات البرمجية معًا
   │
git commit && open a PR            يحتوي طلب السحب (PR) على spec delta والكود البرمجي معًا
   │
يراجعها زميل الفريق ويدمجها
   │
/opsx:archive                      دمج delta داخل specs/، ونقل التغيير إلى archive/

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

مراجعة الـ specs في طلب السحب (pull request)

هنا يشعر الفريق بالعائد. عندما يتضمن طلب السحب (PR) فرق المواصفة (delta spec) الخاص بالتغيير، يحصل المراجع على شيء لا يقدمه له الفرق الخام (raw diff) أبدًا: عبارة بلغة بسيطة توضح الغرض من هذا التغيير، قبل أن يقرأ سطرًا واحدًا من الكود البرمجي.

ترتيب جيد للمراجعة للمراجع:

1. اقرأ ملف proposal.md — هل هذه هي المشكلة والنطاق الصحيحان؟
2. اقرأ delta الموجود داخل مجلد specs/ — هل تم تعريف "الانتهاء من العمل" (done) بشكل صحيح؟ (هذه هي عملية المراجعة السريعة التي تستغرق دقيقتين من مراجعة التغيير، والآن تحدث داخل طلب السحب (PR).)
3. ثم اقرأ فرق الكود البرمجي (code diff) — هل يلبي تمامًا تلك المتطلبات؟

يمكن للمراجع الذي لا يوافق على الأسلوب المتبع التعبير عن رأيه بسهولة ضد الـ proposal، بدلاً من إعادة مناقشته عبر 300 سطر من الكود البرمجي. ضع delta spec في أعلى وصف طلب السحب (PR)، أو وجه المراجعين إلى مجلد التغيير، حتى يبدؤوا من هناك.

متى تقوم بالأرشفة (archiving)

تقوم عملية الأرشفة بدمج الـ deltas الخاصة بالتغيير داخل المجلد الرئيسي openspec/specs/ وتنقل مجلد التغيير إلى openspec/changes/archive/YYYY-MM-DD-<name>/. ونظرًا لأن مجلد specs/ هو المصدر الموثوق المشترك، فإن التوقيت مهم عند العمل ضمن فريق. هناك اتفاقيتان عمليتان:

• الأرشفة بعد دمج طلب السحب (PR) (موصى به). يحمل الفرع التغيير النشط (active change)؛ وبمجرد دمجه في الفرع الرئيسي الخاص بك، قم بالأرشفة هناك (غالبًا ما يكون ذلك عبر عملية commit صغيرة لاحقة أو تنظيف مجدول). هذا يجعل مجلد specs/ المشترك يتقدم للأمام فقط مع العمل الذي تم إصداره فعليًا.
• الأرشفة داخل طلب السحب (PR). أبسط للفرق الصغيرة: نفس طلب السحب (PR) الذي يضيف الكود البرمجي يقوم أيضًا بالمزامنة (sync) والأرشفة. المقابل لذلك هو أن فرق مجلد specs/ وفرق الكود البرمجي يظهران معًا، مما قد يجعل طلب السحب (PR) أكثر ازدحامًا بالمعلومات غير الضرورية.

اختر إحداهما والتزم بها. في كلتا الحالتين، يتأكد الأمر /opsx:archive من اكتمال المهام (tasks) ويعرض عليك المزامنة (sync) أولاً، حتى لا يتم دمج أي شيء غير مكتمل عن طريق الخطأ.

شخصان، وتغييرات متوازية

بما أن التغييرات عبارة عن مجلدات منفصلة، فلا يحدث بينها أي تعارض:

• تغييرات مختلفة، لأشخاص مختلفين — لا توجد مشكلة. add-dark-mode و rate-limit-login هما مجلدان مختلفان على فروع مختلفة؛ ولا يتأثران ببعضهما البعض حتى يتم أرشفة كلاهما.
• تغيير واحد، مالك واحد. يتعارض شخصان يقومان بتحرير نفس مجلد التغيير تمامًا كما يتعارض شخصان يقومان بتحرير نفس الملف. اجعل لكل تغيير مؤلفًا واحدًا، أو قسمه إلى تغييرين (هذا سبب آخر لـ ضبط حجم التغيير بشكل صحيح (right-size)).
• المكان الوحيد الذي يظهر فيه التعارض هو مجلد specs/. إذا كان هناك تغييران يعدلان على نفس المتطلب، فستحدث تعارضات عند أرشفة الثاني داخل ملف openspec/specs/…/spec.md — قم بحلها كما تحل أي تعارض دمج (merge conflict)، مع الاحتفاظ بالمتطلب الذي يعكس الواقع الفعلي. هذا نادر الحدوث، وهو ميزة: إنه git يخبرك أن هناك تغييرين اختلفا حول كيفية تصرف النظام.

عندما يتجاوز التخطيط حدود مستودع واحد

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

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

• مراجعة التغيير (Reviewing a Change) — عملية المراجعة السريعة، والآن موجودة داخل طلب السحب (PR) الخاص بك.
• كتابة مواصفات جيدة (Writing Good Specs) — بما في ذلك كيفية ضبط حجم التغيير بشكل صحيح ليتناسب مع فرع واحد.
• دليل المستخدم للمخازن (Stores User Guide) — تخطيط يمتد عبر مستودعات وفرق متعددة.