Codebase-in-a-Box — المشروع الختامي لمسار الهندسة

أكملت الوحدات الخمس. بنيت وثائق الأساس، وأدرت مراجعة بعين الخصم بنتائج متحقَّق منها، وشحنت ميزة خلف حزمة خضراء، وأعدت الهيكلة بأمان ببرهان قبلُ/بعدُ، ونفّذت migration بقرارات موثَّقة. المشروع الختامي هو حيث تدير الخمس على codebase واحد، في مشروع واحد، فتصير قوسًا واحدًا متماسكًا لا خمس مهارات متفرقة.

ليس هذا اختبارًا قصيرًا. إنه مشروع هندسي كامل — خمسة نواتج تُظهر الوثائق والحُكم الذي وراءها معًا، على codebase إما لك وإما لـ«ميزان».

مشروع الختام — codebase واحد، القوس كاملًا

مشروع Codebase-in-a-Box يمشي الحركات الهندسية الخمس من أولها إلى آخرها على codebase واحد. وكل ناتج يرث وثائق سابقه: الـ CLAUDE.md من الأساس يشحذ المراجعة وprompt الميزة؛ وعرف الـ commit من المراجعة يسري على commits الميزة والـ refactor؛ وحزمة الاختبارات من شحن الميزة هي حزام أمان الـ refactor؛ والـ working tree النظيف من الـ refactor هو الشرط المسبق للـ migration.

جِئ بالـ codebase الخاص بك — هذه نصيحتنا للفرق، لأن الوثائق التي تنتجها بنية حقيقية يواصل فريقك استعمالها بعد المشروع. الـ ARCHITECTURE.md يصير الوثيقة التي يقرؤها موظفكم القادم؛ والـ CLAUDE.md يصير السياق الذي ترثه كل جلسة Claude لاحقة؛ ومراجعة الـ PR هي PR حقيقي كنت تحتاج مراجعته أصلًا؛ والميزة تذكرة حقيقية كنت ستشحنها؛ والـ refactor هو الملف الذي يلتفّ حوله الفريق كله في صمت؛ والـ migration هي التغيير القابع في الـ backlog منذ ربع سنة. المشروع الختامي مصمم ليكون عائدًا من اليوم الأول.

وMizan Engineering هو الـ codebase النموذجي إن أردت التعلم على أرض محايدة أولًا. السيناريو الكامل معروض في قسم نموذج الإجابة من هذا الدليل: شركة SaaS خليجية لمسك الدفاتر مسجَّلة في الإمارات يدير فريقها الهندسي تحديث وحدة الفوترة — توثيق الـ repo لموظف جديد، ومراجعة PR الـ Stripe webhook، وشحن ميزة فاتورة الـ PDF، وإعادة هيكلة دالة توليد الفواتير، والـ migration من moment.js إلى date-fns.

حزمة نواتجك

خمس وثائق، codebase واحد. افتح مجلد المشروع في Claude Desktop وفيه CLAUDE.md، ووافق على كل قراءة من نافذة Ask permissions، واعمل داخل المحادثة — لا حاجة إلى terminal للأساس والمراجعة والتخطيط؛ وتشغيل الاختبارات وأوامر git هي خطوات مسار الـ Power Track.

حزمة نواتج Codebase-in-a-Box

1. ARCHITECTURE.md + CLAUDE.md  (و1 — الأساس)
   - ARCHITECTURE.md: البنية العليا بمسارات حقيقية، ومسار ممثِّل
     واحد مُتتبَّع من أوله إلى آخره بأسماء file:function، والألغام
     مسمّاة
   - CLAUDE.md: الـ stack، والأوامر بالحرف، والأعراف الأساسية،
     وقائمة ما-لا-يُمسّ؛ وقسم السياق الثنائي اللغة لمنتجات سوق
     المنطقة

2. مراجعة PR متحقَّق منها  (و2 — محرّك جودة الكود)
   - مراجعة منظّمة بالأبعاد (الصحة، والحالات الحدّية، والأمن،
     والتشغيل)
   - كل نتيجة جوهرية متحقَّق منها على أسطر بعينها؛ والنتائج
     الزائفة مُسقَطة صراحةً
   - اختبار فاشل واحد لكل خطأ مؤكَّد
   - التعديل ملتزَم في دفعات نظيفة بمتون لماذا

3. ميزة مشحونة  (و3 — شحن الميزات)
   - spec بمعايير قبول قابلة للاختبار وقائمة خارج-النطاق
   - خطة رُوجعت قبل أول سطر
   - تنفيذ باختبارات تُردّ إلى المعايير
   - commits نظيفة بمتون لماذا

4. refactor آمن ببرهان  (و4 — التغيير الآمن)
   - حزمة خضراء قبلُ؛ وrefactor خطواتٍ منفصلة؛ وحزمة خضراء بعدُ
   - كل خطوة diff وcommit مستقلان
   - لا تغيير سلوك مخلوط
   - وصف PR يشرح المشكلة البنيوية التي أُصلحت

5. migration بقرارات موثَّقة  (و5 — النقلة الكبرى)
   - مسح blast radius مصنَّف بالتعقيد
   - التحويل الآلي منفصل عن الحالات المقررة
   - لكل حالة صعبة خياراتها ومفاضلاتها والمنطق الفعلي وراء القرار
     المتخذ
   - الحزمة خضراء في الختام

6. تأمّل  (نصف صفحة)
   - فقرة: أين أعان Claude وما الذي جعله أسرع
   - فقرة: أين كان حُكمك الهندسي هو المُدخل الجوهري — اللحظة التي
     أخطأ فيها ناتج الأداة والتقطتَها، أو القرار الذي احتاج سياق
     مجال لم يكن عند Claude
   - شيء واحد ستفعله بطريقة مختلفة في المرة القادمة

المعايير الرئيسية

خمسة أبعاد. درجة كل بُعد مستوفٍ / قريب / ليس بعد. و«قريب» في أي بُعد يعني إعادة التسليم، لا النجاح. و«مستوفٍ» في الخمسة ينال الاعتماد.

المعايير الرئيسية — اعتماد «الهندسة مع Claude»

1. وثائق الأساس حقيقية
   ARCHITECTURE.md يتتبع مسارًا حقيقيًا بمسارات ملفات وأسماء دوال.
   وCLAUDE.md يضم الأوامر بالحرف والأعراف الفعلية وما-لا-يُمسّ.
   ولفرق المنطقة: السياق الثنائي اللغة مسمًّى. والوثيقتان ممّا
   يثبّته فريق ويحتفظ به، لا مما يُكتب للتمرين.
2. جودة المراجعة مُثبَتة
   التأطير بعين الخصم استُعمل. وكل نتيجة جوهرية متحقَّق منها على
   أسطر بعينها. والنتائج الزائفة مُسقَطة صراحةً. واختبار فاشل واحد
   لكل خطأ مؤكَّد. وتاريخ الـ commits قابل للملاحة: همّ واحد لكل
   commit بمتن لماذا.
3. الميزة بدأت بالـ spec
   الـ spec معاييره قابلة للاختبار (نتائج ملحوظة، لا أوصافًا
   إنشائية). والخطة رُوجعت قبل كتابة الكود. والاختبارات تُردّ
   واحدًا لواحد إلى المعايير. والـ diff قُرئ كاملًا قبل الهبوط.
4. الـ refactor آمن ببرهان
   أخضر قبلُ، أخضر بعدُ — معروضان لا مُدّعيان. وخطوات منفصلة،
   رُوجعت كلٌّ قبل بدء التالية. ولا تغيير سلوك مخلوط. ووصف الـ PR
   يشرح القصد البنيوي، لا الـ diff.
5. الـ migration أمينة
   مسح الـ blast radius يصنّف الاستخدامات بالتعقيد. والحالات
   الصعبة مؤشَّر عليها، لا محوَّلة في صمت. ولكل حالة مؤشَّر عليها
   قرار موثَّق بمنطقه — لا TODO فحسب. والحزمة خضراء في الختام.

المستوى المطلوب، معروضًا — خلاصة «ميزان» المعمولة

لن نتركك تخمّن كيف يبدو «المستوفي». هذه خلاصة المشروع الختامي للشركة النموذجية — والمطلوب من ملفك ليس أن يشبهها، بل أن يبلغ المستوى نفسه.

Mizan Engineering — خلاصة مشروع Codebase-in-a-Box

الـ codebase: «ميزان» (شركة SaaS خليجية لمسك الدفاتر)، تحديث وحدة
الفوترة. تعريف الموظف الجديد: بلال المنصوري، مهندس backend ينضم
للـ migration وميزة الـ PDF.

الناتج 1 — وثائق الأساس
  ARCHITECTURE.md أُنتج بفتح الـ repo في Claude Desktop وتشغيل
  prompt الخريطة من الوحدة الأولى. مسار إنشاء الفاتورة مُتتبَّع من
  أوله إلى آخره: POST /invoices ← invoice-validate.ts ← invoice.ts
  ← queries/invoices.ts ← mailer.ts. وثلاثة ألغام مسمّاة: البريد
  المتزامن، وافتراض عملة AED، ولا soft-delete على جدول الفواتير.

  CLAUDE.md: الـ stack ‏(Node.js 22 / Astro 6 / Supabase / Vitest /
  Playwright)، وأربعة أوامر بالحرف، وستة أعراف منها «كل وصول لقاعدة
  البيانات عبر queries/‏»، وبندا ما-لا-يُمسّ (migrations/‏ وdb.ts)،
  وقسم ثنائي اللغة (فواتير الـ PDF العربية تُؤلَّف بسجلّ خليجي —
  لا تُترجم؛ ويُستشار @bilal-dev).

الناتج 2 — مراجعة PR: ربط Stripe webhook
  مراجعة منظّمة بالأبعاد. خطأ واحد مؤكَّد: الحمولة تُعالج قبل
  التحقق من التوقيع (stripe.ts:84 قبل :94) — ثغرة replay attack.
  تُحُقّق منه على الأسطر. وصيغ اختبار فاشل. وأُسقطت نتيجة زائفة
  واحدة (الـ allowlist موجودة عند :31–35). والتعديل التُزم في
  ثلاثة commits منطقية: إصلاح التحقق من التوقيع، واختبارات
  payment_failed الناقصة، والثوابت المستخرجة.

الناتج 3 — الميزة المشحونة: تصدير الفاتورة PDF
  الـ spec:‏ POST /invoices/:id/pdf يعيد الـ PDF خلال 3 ثوانٍ؛
  والطلبات المكررة تعيد الـ PDF المخزّن؛ والفشل يعيد PDF_ERR دون
  بريد؛ والفواتير العربية تُعرض RTL بسجلّ خليجي. الخطة رُوجعت قبل
  التنفيذ: ملفان جديدان (src/lib/pdf-generator.ts وsrc/routes/
  invoices/pdf.ts)، ومسار محدَّث، وستة اختبارات. واعتُمدت بتعديل
  واحد (نُقل التخزين المؤقت إلى طبقة الـ route لا المولّد).
  والتنفيذ طابق الخطة. والحزمة خضراء. خمسة معايير قبول، وخمسة
  اختبارات تقابلها.

الناتج 4 — الـ refactor الآمن: invoice.ts ‏(380 سطرًا ← أربع وحدات)
  الأساس: 47 اختبار وحدة خضراء، تغطية 62%. أُعيدت الهيكلة في أربع
  خطوات منفصلة (استُخرج التحقق، والحساب، والـ PDF، والبريد). كل
  خطوة diff مستقل، رُوجع والتُزم قبل التالية. الحزمة بعدُ: 67
  اختبارًا أخضر، والاختبارات الأربعة الأصلية كما هي. ولم يتغيّر
  اختبار E2E. ووصف الـ PR: المشكلة البنيوية مسمّاة (أربع مسؤوليات
  لا تُختبر معزولة)، وما أصلحه كل استخراج، وتصريح صريح بأن الأخضر
  قبلُ + الأخضر بعدُ كان البرهان.

الناتج 5 — الـ migration:‏ moment.js ← date-fns
  مسح الـ blast radius: ‏74 استخدامًا، مصنَّفة (62 آلية / 9 حالات
  مناطق زمنية صعبة / 3 غير معتادة). المرور الآلي: 62 تحويلًا في
  commit واحد، كلها على مثال .format()‎ المنجَز يدويًا. الحالات
  الصعبة: 9 استخدامات utcOffset()‎ مؤشَّر عليها؛ كلٌّ موثَّقة
  بخياريها (date-fns-tz في مقابل حساب الإزاحة اليدوي) والقرار
  المتخذ (حساب UTC+4 اليدوي بمنطقه: توقيت الخليج بلا توقيت صيفي،
  وdate-fns-tz تعقيد لا لزوم له لإزاحة ثابتة). والحالات الثلاث غير
  المعتادة: تعليق الـ SQL تُرك كما هو (لا منطق)، والاستيراد
  الديناميكي نُقل إلى أعلى الملف، واختبار Playwright حُدّث إلى
  صيغة date-fns. والحزمة خضراء بعد الجميع.

التأمّل:
  جعل Claude مسحَ الـ blast radius — إيجاد 74 استخدامًا وتصنيفها
  عبر 23 ملفًا — عملَ عشرين دقيقة بعد أن كان نصف يوم من grep
  والقراءة. والتأطير بعين الخصم أخرج مشكلة ترتيب التحقق من التوقيع
  التي ما كنت لألتقطها في جولة مهذبة. وفي ميزة الـ PDF، وضعت الخطة
  المقترحة أولًا توليدَ الـ PDF داخل معالج الـ route (مخالفةً عرف
  فصل المسؤوليات في CLAUDE.md) — تلك هي اللحظة التي التقطت فيها
  الخطة خاطئةً وصححتها قبل أن يوجد أي كود.

  الحُكم الهندسي الذي كان عليّ تقديمه: قرار migration الـ
  utcOffset()‎. فالمنطق بأن توقيت الخليج بلا توقيت صيفي وأن حساب
  UTC+4 اليدوي صحيح يستلزم معرفة سياق العمل (فوترة الخليج على
  توقيت +4 دائمًا) — وليس ذلك ممّا يعرفه Claude بلا سياق المجال.
  وذلك هو القرار الذي تفحصه المعايير.

  في المرة القادمة: أكتب CLAUDE.md قبل أول جلسة Claude على الـ
  codebase، لا بعد جولة التعارف. فناتج وحدة الأساس أنفع ما يكون
  حين يكون حاضرًا من أول prompt.

ما الذي يناله من يكمل

اجتز الأبعاد الخمسة وتكون قد نلت اعتماد «الهندسة مع Claude» — اعتمادًا قابلًا للتحقق على ‎/cert/[your-id]‎ يشهد أنك أدرت القوس الهندسي كاملًا:

• تستطيع تعريف موظف جديد (أو نفسك) في codebase لا تعرفه، وإنتاج الوثائق التي تعرّف من بعده أسرع.
• تستطيع إدارة مراجعة كود بعين الخصم تصطاد الخطأ الحقيقي وتُسقط النتائج الزائفة، وتترك تاريخًا يهتدي به المهندس التالي.
• تستطيع شحن ميزة تبدأ بالـ spec، وتُراجَع خطتها، وتُثبَت بالاختبارات، وتُلتزم بنظافة.
• تستطيع إعادة الهيكلة بأمان — ببرهان قبلُ/بعدُ — لا برجاء.
• تستطيع إدارة migration على مستوى الـ repo تحوّل الآلي وتُظهر ما يحتاج حُكمًا، بقرارات موثَّقة لا تخمينات صامتة.

تلك هي الممارسة الهندسية التي يعلّمها هذا المسار. والاعتماد يشهد أنك تستطيع إظهارها، لا وصفها فحسب.