إعداد المشروع

اجعل سير العمل يخطط للتغييرات بالطريقة التي تريدها بأسطر قليلة في config.yaml.

يخبر ملف openspec/config.yaml سير العمل بكيفية رغبتك في تخطيط التغييرات.

على سبيل المثال، الإعداد التالي يحدّث قواعد الإنشاء لمخرجات tasks.md:

rules:
  tasks:
    - End every task with a commit

عندما يعمل الوكيل، يستمد من هذه القواعد ويضمن أن تنتهي كل مهمة بخطوة commit.

حافظ على القواعد قصيرة. كل ما هنا يصل إلى سياق الوكيل، والقواعد المطوّلة قد تجعل المخرجات أسوأ.

كيف يعمل

يحتوي config.yaml على تعليمات يتلقاها الوكيل عند إنشاء المخرجات أو العمل من خلال سير العمل.

إليك ما يحدث في كل تشغيل:

1. تشغّل سير عمل (مثلاً /openspec-propose).
2. يستدعي الوكيل أمر openspec instructions.
3. يقرأ الأمر السياق والقواعد من config.yaml.
4. تُدمج تعليمات OpenSpec المدمجة مع تخصيصاتك في مطالبة واحدة للوكيل.
5. يتبع الوكيل تلك المطالبة لكتابة المخرجات.

على سبيل المثال، مع حقل context والقاعدة من أعلى هذه الصفحة، إليك ما يعيده أمر openspec instructions لملف tasks.md (مقتطع ومشروح):

<artifact id="tasks" change="add-dark-mode" schema="spec-driven">

  <!-- من config.yaml: context -->
  <project_context>
    Designs and tasks must cover Windows, macOS, and Linux
    Write all artifacts in Spanish
  </project_context>

  <!-- من config.yaml: قواعد tasks -->
  <rules>
    - End every task with a commit
  </rules>

  <!-- من OpenSpec: التوجيه المدمج -->
  <instruction>
    ...how to write a good tasks.md...
  </instruction>

  <template>
    ...the tasks.md structure to fill in...
  </template>

</artifact>

يصل إعدادك أولاً، ثم تعليمات OpenSpec المدمجة والقالب. القواعد تُضاف إلى المدمجة ولا تحل محلها أبداً. تنتقل التعديلات على config.yaml إلى الوكيل في التشغيل التالي.

الحقول

ثلاث حقول تحدد ما يتلقاه الوكيل. العقد الدقيق لكل حقل (الأنواع، الحدود، التحقق) موجود في إعداد المشروع (config.yaml).

الحقل	ما يفعله	يُحقن في
context	تعليمات يتلقاها الوكيل دائماً	كل شيء: كل المخرجات، apply، archive
rules	تعليمات إضافية لمخرجات واحدة	إنشاء تلك المخرجات فقط
operations	توجيه لكيفية تنفيذ خطوة سير العمل	apply و archive فقط

الحقول الأخرى في config.yaml (schema، store، references) تحدد المخطط المستخدم وجذر OpenSpec للمشروع. صفحة العقد تغطيها.

العمود الأخير دقيق، لذا يصل الحقل فقط إلى الخطوات المذكورة فيه. على وجه الخصوص، verify لا يتلقى rules أبداً. فهو يتحقق من التنفيذ مقابل المخرجات كما كُتبت.

context

context هو الخلفية التي يتلقاها الوكيل عند إنشاء مخرجات أو تطبيق المهام أو أرشفة تغيير.

context: |
  We ship cross-platform. Designs and tasks must cover Windows, macOS, and Linux
  Write all artifacts in Spanish

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

لغة أخرى: نظراً لأن context يصل إلى كل المخرجات، يمكنك إضافة Write all artifacts in Spanish. لتوجيه الوكيل لكتابة مخرجات الاقتراح والمواصفات والتصميم والمهام بالإسبانية.

rules

ترتبط rules بمخرجات واحدة، مفهرسة بمعرف المخرجات. كل سطر يُضاف إلى التوجيه المدمج لتلك المخرجات:

rules:
  proposal:
    - Keep proposals under 500 words
  tasks:
    - Every UI task includes a Playwright test

تبقى الاقتراحات قصيرة الآن، ويخطط tasks.md دائماً لاختبارات المتصفح. كل مخرجات أخرى تبقى دون مساس.

operations

توجّه operations كيفية تنفيذ الوكيل لـ apply و archive، بدلاً من ما تقوله المخرجات:

operations:
  apply:
    guidance:
      - Run the linter before marking a task complete
  archive:
    guidance:
      - Summarize what shipped before archiving

أثناء apply، يشغّل الوكيل linter أثناء إكمال المهام. أثناء archive، يختم بملخص.

عندما لا يكون config.yaml كافياً

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