البدء السريع

أول تغيير لك، من الفكرة إلى الأرشفة، في مشروع جديد أو قائم.

قبل أن تبدأ، تحتاج إلى واجهة سطر الأوامر (CLI) على جهازك (التثبيت) وتهيئة OpenSpec في مشروعك (إعداد مشروعك).

البدء من مشروع فارغ

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

Help me explore a task tracker from scratch. I have not picked a stack. Compare the options and help me choose the first behavior to build.

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

نظرة عامة على الحلقة

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

flowchart LR
    explore["1 · Explore<br/>think it through together"] --> propose["2 · Propose<br/>agent drafts the plan"]
    propose --> review["3 · Review<br/>you correct the plan"]
    review --> apply["4 · Apply<br/>agent builds, task by task"]
    apply --> archive["5 · Archive<br/>specs absorb the change"]
    archive -. "next change" .-> explore

كل مطالبة أدناه تُكتب في محادثة الذكاء الاصطناعي الخاصة بك، نفس المكان الذي تطلب منه الكود. الأمثلة تستخدم لغة بسيطة لتعمل عبر الأدوات. يمكنك أيضًا استدعاء مهارة مباشرة؛ تختلف الصيغة حسب الأداة (الأدوات المدعومة).

الخطوة 1: الاستكشاف

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

Help me explore how rate limiting should work in this app.

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

ابقَ هنا طالما تحتاج المشكلة. عندما يبدو الشكل صحيحًا، سلّم المهمة:

Propose the change we just discussed.

هذا السطر يبدأ الاقتراح نيابةً عنك، حاملًا كل ما استقررت عليه. تخطَّ المطالبة الأولى في الخطوة 2.

الخطوة 2: الاقتراح

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

Propose a change to add rate limiting.

يسأل الوكيل عما يحتاج إليه، ثم يكتب مجلد التغيير:

openspec/changes/add-rate-limiting/
├── proposal.md    why, and what changes
├── specs/         what "done" means, as testable requirements
├── design.md      technical decisions (only when the change needs one)
└── tasks.md       the implementation checklist

لا كود بعد. الاقتراح يتوقف عند الخطة.

الخطوة 3: المراجعة وتصحيح الخطة

أصلح الخطة بينما لا تزال كلمات ولم يُبنَ شيء بعد. اقرأ بهذا الترتيب:

• proposal.md: هل هذه هي المشكلة الصحيحة، بالحجم الصحيح؟
• specs/: القراءة الأعلى قيمة. هل تقبل هذه المتطلبات كمكتملة؟
• tasks.md: هل تغطي المهام المواصفات، ولا شيء أكثر؟

لإصلاح شيء ما، أيٌّ من الطريقتين ينجح:

• عدّل الملف بنفسك. الملفات عبارة عن Markdown عادي، والملفات هي الخطة.
• أخبر وكيلك بما هو خطأ ("المواصفة تفتقد حالة عدم المصادقة"). سيقوم بمراجعة الملفات.

الخطوة 4: التطبيق

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

Apply the add-rate-limiting change.

يقرأ الوكيل مجلد التغيير، ثم يعمل من خلال tasks.md، مع تحديد كل مهمة عند إنجازها.

• انقطعت الجلسة، أو خرجت من السياق؟ افتح جلسة جديدة واطلب التطبيق مرة أخرى. سيستأنف من أول مهمة غير محددة.
• اتضح أن الخطة خاطئة؟ أصلح الملفات (بأي طريقة من الخطوة 3)، ثم تابع التطبيق.
• التقدم موجود في مربعات الاختيار في tasks.md. لا توجد حالة مخفية.

الخطوة 5: الأرشفة

الأرشفة تقوم بأمرين: تحدّث مواصفاتك الرئيسية بمتطلبات التغيير، وتنقل مجلد التغيير إلى مجلد الأرشيف (في /openspec/changes/archive/*).

عندما يتم تحديد كل مربع في tasks.md، في محادثة الذكاء الاصطناعي الخاصة بك:

Archive the add-rate-limiting change.

تتبّع ما تفعله الأرشفة خطوة بخطوة:

## The finished change
> Implementation is done. The delta spec (what this change adds) still sits inside the change folder; specs/ doesn't know about rate limiting yet.
  openspec/
  ├── specs/                                   (no rate-limiting spec yet)
  └── changes/
      └── add-rate-limiting/
          ├── proposal.md
          ├── tasks.md                         every box checked
          └── specs/
              └── rate-limiting/
                  └── spec.md                  the delta: ADDED requirements

## Requirements land in specs/
> Each requirement in the delta lands in the main spec: added ones append, modified ones replace their old version. A new capability gets a new spec file.
  openspec/
  ├── specs/
+ │   └── rate-limiting/
+ │       └── spec.md                          gains "Requirement: Rate limiting"
  └── changes/
      └── add-rate-limiting/
          └── specs/
              └── rate-limiting/
                  └── spec.md                  the delta, source of the merge

## The folder moves to archive/
> The whole change folder, delta included, moves into the archive under a date prefix. Nothing is deleted.
  openspec/
  ├── specs/
  │   └── rate-limiting/
  │       └── spec.md
  └── changes/
-     └── add-rate-limiting/
+     └── archive/
+         └── 2026-08-08-add-rate-limiting/
+             ├── proposal.md
+             ├── tasks.md
+             └── specs/rate-limiting/spec.md

## Specs describe the system as built
> changes/ is clear for the next change. specs/ is the source of truth for what the system does; archive/ is the history of how it got there.
  openspec/
  ├── specs/
  │   └── rate-limiting/
  │       └── spec.md                          the spec as built
  └── changes/
      └── archive/
          └── 2026-08-08-add-rate-limiting/

Git هو أمر منفصل. التزم بمجلد التغيير مع الكود، ولا يتغير أي شيء آخر في سير عملك.

الاحتفاظ بالتغييرات المؤرشفة أو حذفها

openspec/changes/archive/ يحتفظ بالاقتراح والتصميم والمهام والدلتا لكل تغيير مكتمل. في تدفق الأرشفة أعلاه، تكون الدلتا قد حدّثت بالفعل openspec/specs/.

• احتفظ بمجلد التغيير بالكامل عندما تريد سجلًا مكتفيًا بذاته في النسخة الحالية من المستودع.
• احذف مجلد specs/ الخاص بتغيير مؤرشف عندما يكون Git هو سجل مواصفاتك. التزم بالأرشيف أولاً، ثم احذف openspec/changes/archive/<change>/specs/. يبقى الاقتراح والتصميم والمهام في النسخة الحالية. لا يزال openspec validate --archived يعمل لأنه يتحقق من اكتمال المهام، وليس من الدلتا المطبقة.
• احذف مجلد التغيير بالكامل فقط عندما لم تعد بحاجة إلى اقتراحه أو تصميمه أو سجل مهامه في النسخة الحالية. لا تتغير المواصفات الحالية، لكن openspec validate --archived والبحث في النسخة الحالية لن يشمل ذلك التغيير بعد الآن.

WARNING

احتفظ بالتزام الأرشيف في تاريخ مستودعك إذا أردت أن يحتفظ Git بالملفات المحذوفة. دمج التزام الأرشيف والتزام التنظيف معًا يزيل تلك اللقطة الوسيطة.

لا يقوم OpenSpec بحذف التغييرات المؤرشفة تلقائيًا ولا يوفر إعدادًا للاحتفاظ.

المضي قدمًا

• مواصفات الدلتا: كيفية كتابة تغييرات السلوك في مواصفة دلتا.
• الملفات الشخصية: سير عمل اختيارية خارج المجموعة الأساسية (التحقق قبل الأرشفة، التخطيط التدريجي).

أدلة متقدمة

لم تُكتب بعد؛ أدلة نخطط لإضافتها:

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