شحن الميزات: spec ثم خطة ثم بناء ثم إثبات ثم commit — بهذا الترتيب

بين يدي فريقك playbook الـ ship-a-feature — الوصفة المجرّبة لكتابة spec، وأخذ الخطة أولًا، وترك Claude ينفّذ، وإثبات السلوك الجديد بالاختبارات، والالتزام في دفعات نظيفة. هذه الوحدة طبقة أعلى من الوصفة: هنا تُتقن لماذا تسبق كل خطوة تاليتها — الـ spec الذي يعطيك معايير الاختبار، والخطة التي تلتقط المنهج الخاطئ وهو ما يزال نثرًا، والتنفيذ الذي يُثبَت لا يُفترَض، والـ diff الذي تقرؤه بوصفك صاحب التوقيع — وتثبت، أمام معايير حقيقية، أنك تمسك الحلقة كلها.

«الخطة التي لم تقرأها diff ستضطر إلى تفكيكه.» قيمة plan mode كلها تتبخر إن اعتمدت الخطة دون قراءة، وقيمة الـ spec كلها تتبخر إن لم تُردّ الاختبارات إليه. والحسّ الذي تعلّمه هذه الوحدة هو معرفة أين يقع الأثر الأكبر في الحلقة وما الذي يُتحقق منه عند كل بوابة.

الـ spec — معايير قابلة للاختبار، لا نثر إنشائي

الـ playbook يطلب «4–6 معايير قبول مصوغة عباراتٍ قابلة للاختبار». الإتقان هو الحسّ الذي يفصل معايير تستطيع تحويلها إلى اختبارات عن أخرى تبدو دقيقة وليست كذلك.

• المعيار القابل للاختبار يسمّي النتيجة الملحوظة. «تُولَّد فاتورة الـ PDF» غير قابل للاختبار — لا يقول كيف ستعرف أنها وُلّدت، ولا بأي صيغة، ولا أي خطأ يعود إن فشل التوليد. أما «‏POST إلى ‎/invoices/:id/pdf‎ يعيد 200 مع Content-Type: application/pdf ومتن الـ PDF خلال ثانيتين؛ وإن فشل التوليد يعيد { error: 'pdf_generation_failed', code: 'PDF_ERR' }» فقابل للاختبار — إنه اختبار تستطيع كتابته الآن.
• قائمة خارج-النطاق تعمل عملًا حقيقيًا. تسمية ما لن تبنيه الآن أرخص طريقة لوقف scope creep. «خارج النطاق: ملفات PDF محمية بكلمة مرور، ومقاسات صفحات مخصصة، والتصدير الدفعي» تعني أن Claude لا يضيف حماية كلمة المرور في صمت «ما دمنا هنا». قائمة اللا-أهداف هي العقد الذي يمنع ميزة الملفين من أن تصير ميزة تسعة ملفات.
• معايير القبول هي مصدر الحقيقة الذي ترثه الاختبارات. حين تكتب الاختبارات في الخطوة الرابعة، تختبر على المعايير التي كتبتها في الأولى — لا على التنفيذ الذي خرج. إن لم تستطع ردّ كل اختبار إلى معيار، فالاختبارات تختبر الكود، لا الميزة.
• الـ spec الذي لا تستطيع صوغه معاييرَ لم يُعرَّف بعد. إن وجدت نفسك تتعثر في كتابة معايير قبول قابلة للاختبار، فالإشارة أن الميزة لم تتحدد بما يكفي للبناء — لا أن تبدأ الكتابة وتكتشف في الطريق. «لست متأكدًا كيف يبدو الاكتمال» مشكلة spec، لا مشكلة تنفيذ. احسمها نثرًا قبل أن يُكتب سطر.

مراجعة الخطة — حيث يقع الأثر الأكبر

الـ playbook يقول: استعمل plan mode وراجع الخطة قبل الاعتماد. الإتقان هو الحسّ وراء شكل المراجعة النافعة — ونمط الفشل هنا معاملة الاعتماد إجراءً شكليًا.

• الخطة رخيصة؛ والـ diff ليس كذلك. تصحيح منهج خاطئ في فقرة يكلّف دقيقة. وتفكيك diff خاطئ من 300 سطر يكلّف أمسية. قيمة plan mode كلها أنك تُخطئ المنهج بثمن بخس، نثرًا، قبل أن يوجد أي كود. ومراجعة خطة لا تعترض على شيء ليست مراجعة؛ إنها شعيرة. اقرأها قراءة مراجعة تصميم — «هذا يمسّ مسار المصادقة، لا تفعل»، «ضع هذا خلف الـ flag الموجود»، «افصل الـ migration» — وقلها قبل الاعتماد.
• للخطط أنماط فشلها الخاصة. «الملفات التي ستُمسّ: [قائمة بكل ملفات الـ repo]» خطة ستنتج diff لا تستطيع مراجعته. و«لا ذكر لاستراتيجية اختبار» خطة ستنتج كودًا بلا اختبارات. و«تعدّل مسار المصادقة» في ميزة لا شأن لها بالمصادقة خطة تُعاد. قراءة الخطة تعني فحص النطاق (هل يطابق الـ spec؟)، والمنهج (هل هذا هو التجريد الصحيح؟)، واستراتيجية الاختبار (أين تذهب الاختبارات وماذا تختبر؟).
• تصحيح الخطة هو أعلى دقيقة مردودًا في الحلقة. الخطة التي تمسّ الوحدة الخطأ، أو تقترح التجريد الخطأ، أو تفوّت خطر التزامن، تُصحَّح بجملة واحدة وهي نثر. ومتى صارت diff، اقتضى تصحيحها قراءة كل سطر تغيّر، وفهم ما بناه التجريد الخاطئ، ثم تفكيكه. الدقيقة التي تنفقها في نقد الخطة تساوي ساعة فيما بعدها.
• الخطة تحرس التنفيذ. لا تقل «الخطة تبدو صحيحة، امضِ» وأنت لم تقرأها. أنت تعتمد المنهج، لا النبرة. ومتى اعتُمدت الخطة، فالتنفيذ الذي يليها هو الخطة التي وقّعت عليها — فإن عاد الـ diff خاطئًا، فالمشكلة بدأت في مراجعة الخطة.

التنفيذ — اقبل أو ارفض أولًا بأول، لا في النهاية

الـ playbook يذكر أن التعديلات في Claude Desktop تصلك diffs مرئية تقبلها أو ترفضها. الإتقان هو انضباط استعمال تلك الحلقة استعمالًا صحيحًا — لا الختم على جدار الكود في النهاية.

• راجع كل diff قبل قبوله. نموذج «الـ diff وهو يُبنى» وُجد لسبب: أنت صاحب التوقيع على كل سطر، وقبول diff لم تقرأه هو عين كتابة كود لم تقرأه. في Claude Desktop يهبط كل تعديل diff مرئي في لوحة الملفات — اقرأه واقبله أو ارفضه قبل أن يمضي Claude.
• إن انحرف diff عن الخطة، فارفضه الآن. إن أدخل تعديلٌ كودًا لم يكن في الخطة، أو مسّ ملفًا لم تذكره، أو غيّر سلوكًا خارج نطاق الـ spec — ارفضه واشرح السبب. لا تقبله على نية إصلاح لاحق. «أقبل الآن وأصلح لاحقًا» هي كيف تتضخم النطاقات وتخرج الـ diffs عن السيطرة.
• الخطة هي spec الـ diff. كل تعديل في التنفيذ ينبغي أن يُردّ إلى خطوة في الخطة. وما جاء في diff ولم تذكره الخطة فهو إما ثغرة فيها (اعتمادية فائتة) وإما إضافة غير مخطط لها (scope creep). سمِّ أيّهما قبل أن تقرر القبول.

الاختبارات — «نجحت» ليست «اكتملت»

الـ playbook يطلب اختبارات تثبّت السلوك الجديد على كل معيار قبول. الإتقان هو الحسّ الذي يفصل اختبارات تثبت الميزة عن أخرى تكتفي بالنجاح.

• الاختبار الذي يختبر الشيء الخطأ أسوأ من لا اختبار. الاختبار الذي يتحقق أن دالة استُدعيت (لا أن الناتج صحيح) اختبار سينجح على تنفيذ مكسور. والاختبار الذي يغطي المسار السعيد ويفوّت مسار الخطأ اختبار سيخضرّ حتى حين تكون معالجة الأخطاء خاطئة. الأخضر لا يعني الصحيح؛ يعني أن الاختبارات نجحت، لا أنها تختبر الشيء الصحيح.
• طابق الاختبارات على المعايير. بعد أن يكتب Claude الاختبارات، افحص كل واحد على معايير القبول من الخطوة الأولى. هل تستطيع ردّ كل اختبار إلى معيار؟ الاختبار الذي لا يُردّ إلى معيار إما يختبر تفصيلة تنفيذ (احذفه) وإما يختبر معيارًا نسيت كتابته (أضِف المعيار). والمعيار الذي بلا اختبار نقصٌ في التغطية، لا في المعيار.
• الحالات الحدّية التي أوحى بها الـ spec. مجموعة الاختبارات الجيدة تغطي المعايير المكتوبة والحالات الحدّية البديهية التي أوحت بها: المدخل الفارغ، وقيم الحدود، ومسار الخطأ، وحالة التزامن. ليست تلك إضافات على الـ spec؛ إنها الدقة التي كُتب بها.
• تشغيل الحزمة هو خطوة الـ Power Track. في Claude Desktop ترى الاختبارات مكتوبة وتقرؤها. أما تشغيل الحزمة كاملة (unit + E2E) فيحتاج جلسة فيها terminal — مسار الـ Power Track. إن لم تكن في جلسة terminal، فاقرأ الاختبارات بعناية، ثم شغّلها بنفسك والصق أي أحمر في محادثة Desktop؛ وسيصلح Claude من المخرجات الفعلية بالطريقة نفسها.

تكليفك

أكمِل حلقة شحن الميزة كاملة لـتذكرة حقيقية واحدة — على الـ codebase الخاص بك (وهذا ما ننصح به) أو ميزة «إرسال الفاتورة PDF» في «ميزان» المعروضة في هذه الوحدة. افتح مجلد المشروع في Claude Desktop وفيه CLAUDE.md (من الوحدة الأولى) واعمل داخل المحادثة — لا حاجة إلى terminal حتى تشغيل الحزمة.

ناتج الوحدة الثالثة — ميزة مشحونة

1. الـ spec  (نصف صفحة)
   - خلاصة من فقرة واحدة: ماذا تفعل الميزة ولمن
   - 4–6 معايير قبول عباراتٍ قابلة للاختبار (نتائج ملحوظة، لا
     أوصافًا إنشائية)
   - قائمة «خارج النطاق حاليًا» صريحة

2. خطة مراجَعة  (ظاهرة في الجلسة أو مذكرةً)
   - الخطة التي تسلّمتها، واعتراضك (ولو «اعتُمدت كما هي» بسبب)،
     والمنهج النهائي الذي وقّعت عليه
   - كحد أدنى: الملفات التي تُمسّ، والترتيب، واستراتيجية الاختبار

3. تنفيذ مع اختبارات  (الكود + ملف الاختبار)
   - تنفيذ يطابق الخطة التي اعتمدتها
   - اختبارات تُردّ إلى معايير القبول (واحدًا لواحد)
   - حزمة خضراء (أو المخرجات الحمراء وتفسيرك لما يفشل)

4. commits نظيفة + وصف PR  (‏git log + مسودة وصف الـ PR)
   - همّ واحد لكل commit بمتن لماذا (عرف الوحدة الثانية)
   - وصف الـ PR: ماذا تفعل الميزة، ومعايير القبول، وكيف اختبرتها

كيف يجري التقييم — المعايير

معايير الشحن

1. الـ spec معاييره قابلة للاختبار
   كل معيار قبول يسمّي نتيجة ملحوظة يمكن التحقق منها في اختبار.
   وقائمة خارج-النطاق حاضرة ومحددة.
2. الخطة نُقدت قبل الكود
   أثرٌ يُظهر أن الخطة قُرئت واتُّخذ فيها حكم — حتى «اعتُمدت كما
   هي» بسبب مقبولةٌ. والخطة تطابق ما بُني.
3. الاختبارات تثبّت معايير القبول
   كل اختبار يُردّ إلى معيار. والحزمة خضراء أو الأحمر مفسَّر. لا
   اختبار يختبر تفصيلة تنفيذ؛ كلٌّ يختبر نتيجة ملحوظة.
4. الـ diff قُرئ كاملًا
   لا «أقبل وأصلح لاحقًا» — كل تعديل قُرئ قبل أن يهبط. والانحراف
   عن الخطة التُقط وسُمّي.
5. الـ commits على العرف
   همّ واحد لكل commit، ومتن اللماذا حاضر، والرسائل على صيغة
   CLAUDE.md من الوحدة الأولى.

المستوى المطلوب، معروضًا — نموذج إجابة («ميزان»)

(الـ spec هنا بالعربية عمدًا — فهو وثيقة تصميم، والنقاش يتبع قارئه؛ ومسارات الـ API وأشكال الاستجابة والاختبارات بالإنجليزية، فالكود إنجليزي دائمًا.)

الـ spec — ميزة «إرسال الفاتورة PDF» في «ميزان»

الخلاصة: حين يطلب عميل فاتورته بصيغة PDF (عبر الـ API أو لوحة
التحكم)، تولّد «ميزان» ملف PDF يطابق عرض الفاتورة على الويب، وترفقه
برسالة Resend، وتسلّمه إلى بريد الفوترة عند العميل. والـ PDF يدعم
قالبَي الفاتورة الإنجليزي والعربي.

معايير القبول:
  1. POST /invoices/:id/pdf يعيد 200 مع Content-Type: application/pdf
     ومتن الـ PDF خلال 3 ثوانٍ لفاتورة معتادة (≤20 بندًا).
  2. GET /invoices/:id/pdf-status يعيد { status: 'ready' | 'generating'
     | 'failed', url?: string } — والـ url لا يحضر إلا حين تكون
     الحالة 'ready'.
  3. الـ PDF المرسل إلى بريد الفوترة يصل بعنوان
     "Invoice [invoice.number] from Mizan" والـ PDF مرفقًا.
  4. الفواتير العربية تُعرض RTL، بسجلّ خليجي، وبشعار «ميزان»
     العربي (src/assets/logo-ar.svg).
  5. إن فشل التوليد، يعيد الـ API ‏{ error: 'pdf_generation_failed',
     code: 'PDF_ERR' } ولا يُرسل بريد؛ ويُسجَّل الفشل في
     invoice_events بـ event_type: 'pdf_generation_failed'.
  6. الطلب المكرر للفاتورة نفسها (خلال 60 ثانية) يعيد الـ PDF
     المخزّن دون إعادة توليد.

خارج النطاق: ملفات PDF محمية بكلمة مرور، ومقاسات صفحات مخصصة،
والتصدير الدفعي، ومعاينة الـ PDF في لوحة التحكم (تذكرة مستقلة #219).

الاختبارات — «إرسال الفاتورة PDF» (مقتطف، يُردّ إلى المعايير)

// المعيار 1: يعيد PDF خلال 3 ثوانٍ
it('returns PDF body for a valid invoice within 3 seconds', async () => {
  const start = performance.now()
  const res = await POST('/invoices/inv_001/pdf', { headers: auth })
  expect(res.status).toBe(200)
  expect(res.headers.get('content-type')).toBe('application/pdf')
  expect(performance.now() - start).toBeLessThan(3000)
})

// المعيار 5: مسار الفشل
it('returns PDF_ERR and does not send email when generation fails', async () => {
  mockPdfGenerator.mockRejectedValue(new Error('render failed'))
  const res = await POST('/invoices/inv_002/pdf', { headers: auth })
  expect(res.status).toBe(500)
  expect(await res.json()).toMatchObject({ error: 'pdf_generation_failed', code: 'PDF_ERR' })
  expect(mockMailer.send).not.toHaveBeenCalled()
  expect(mockEventLog).toHaveBeenCalledWith(
    expect.objectContaining({ event_type: 'pdf_generation_failed' })
  )
})

ما الذي أثبتّه — وما التالي

باجتيازك هذه المعايير تكون قد أظهرت حلقة شحن الميزة كاملة: spec أعطاك معايير الاختبار، وخطة نقدتها قبل أن يوجد الكود، وتنفيذًا أثبتته الحزمة، وdiff ملكته سطرًا سطرًا.

الوحدة 4 — التغيير الآمن هي التالية: انضباط الـ refactor الذي يجعل التنظيف البنيوي شيئًا تقف وراءه في المراجعة، وحزمة الاختبارات حزامَ الأمان. الـ CLAUDE.md من الوحدة الأولى وعرف الـ commit من الثانية يمضيان معك إلى commits الـ refactor.