أساس الهندسة: الـ codebase الذي تعدّله بثقة

بين يدي فريقك playbook الـ map-the-codebase والـ code-review والـ git-workflow — الوصفات المجرّبة لأخذ جولة، ومراجعة diff، والالتزام النظيف. هذه الوحدة طبقة أعلى من الوصفة: هنا تُتقن الوثائق الثلاث التي يرثها كل pull request وكل refactor وكل migration — الخريطة الحقيقية للـ codebase، وسياق المشروع الذي يجعل Claude شريكًا هندسيًا أحدّ، وانضباط الـ commit الذي يُبقي git blame جديرًا بالقراءة — تبنيها لـ codebase حقيقي، وتثبت، أمام معايير حقيقية، أنك قادر.

هذه هي الوحدة الأولى من مسار الهندسة المعتمَد، وقد تعمّدنا إبقاءها مفتوحة: اقرأها وأنجِز تكليفها، وستعرف بنفسك ماذا يساوي هذا العمق قبل أن تُلحق فريقًا ببقية المسار.

كل قرار هندسي لاحق — مراجعة الـ PR، والـ refactor، والـ migration، وجلسة التشخيص — إنما هو سحبٌ من ثلاثة أرصدة: هل تفهم النظام فعلًا قبل أن تمسّه، وهل عند Claude سياق المشروع الذي يعينك به بدل النصائح العامة، وهل التاريخ الذي تتركه وراءك مقروء للمهندس الذي يرثه بعد سنة. ومعظم الفرق لم تودِع في الثلاثة شيئًا، فتعيد كل مراجعة كود شرح الأعراف من أولها، ويلقي Claude محاضرة عن الـ framework بدل تسمية مسارات ملفاتكم الفعلية، ويكون git blame جدارًا من «fix stuff» لا يُبنى عليه شيء. الأساس هو حيث تملأ الأرصدة الثلاثة مرة واحدة.

لماذا الأساس هو أعلى استثمار مردودًا في مسار الهندسة

البرمجيات تتصدّع في صمت، افتراضًا غير موثّق بعد افتراض. يفتح مهندس جديد repo فيُترك يخمّن أي الملفات يهمّ، لأن الـ README يصف المعمارية القديمة ولم يكتب أحد ما الذي تغيّر. وتبدأ جلسة Claude بـ prompt فضفاض فتعود بوصف framework عام، لأن المشروع لا يملك CLAUDE.md يقول أي الملفات وأي الأعراف وأي الأوامر هي الحقيقية. ويصل PR للمراجعة فلا يستطيع أحد أن يقول لِمَ تغيّر سطر، لأن رسالة الـ commit هي «update auth» ومتنها فارغ — وبعد ستة أشهر حين يكسر ذلك التعديل شيئًا، يكون git blame هو أثر الخبز الوحيد وهو يقود إلى لا شيء.

ثلاث وثائق تسدّ الثغرات الثلاث. ملف ARCHITECTURE.md يحسم ما هو الـ codebase فعلًا — الوحدات العليا، وكيف يجري الطلب من الـ route إلى قاعدة البيانات، وأين يسكن التعقيد الحامل، والألغام التي تُعرف قبل مسّ أي شيء. وملف CLAUDE.md يحسم ما الذي يعرفه Claude عن مشروعك — الـ stack، والأعراف، وأوامر الاختبار، وما لا يُمسّ، والسياق الذي تحتاجه محادثة جديدة لتعطيك نصيحة تخصّ مشروعك لا محاضرة من كتاب. وعرف الـ commit يحسم ما الذي يقوله التاريخ — عنوان ومتن يشرح لماذا لزم التعديل، كي يفهم مهندس المستقبل القارئ لـ git blame القصدَ، لا التسلسل الزمني وحده.

ابنِها مرة واحدة وسيرثها كل عمل لاحق: أرفق ARCHITECTURE.md مع جلسة تشخيص فيتتبع Claude مسار الاستدعاء الفعلي بدل أن يخمّنه؛ وضع CLAUDE.md في جذر المشروع فتصير كل مراجعة وكل refactor وكل prompt ميزة خاصةً بمشروعك فورًا لا عامة؛ واتبع عرف الـ commit فيستطيع من يصل بـ bisect إلى commit لك بعد سنة أن يبني على ما يجد. لهذا كانت هذه الوحدةَ الأولى. إن قفزت عنها، فكل ما سيفعله Claude أنه يعينك على التحرك أسرع داخل نظام لا تفهمه — وهذا أسوأ، لا أحسن، لأن الأخطاء تتراكم في كل ما بعدها.

خريطة المعمارية — ملفات حقيقية أو محاضرة عن الـ framework

الـ playbook يعطيك prompts الخريطة. الإتقان هو الحسّ الذي يفصل خريطة تستعملها فعلًا عن أخرى تقرؤها مرة وتحفظها في الأدراج — ونمط الفشل يكاد يكون واحدًا دائمًا: خريطة تصف الـ framework عندك بدل الـ codebase عندك.

• ملفات حقيقية وإلا فلم يحدث شيء. «يمرّر التطبيق الطلبات الواردة عبر طبقة middleware إلى منطق الأعمال ثم إلى قاعدة البيانات» وصفٌ لكل تطبيق Node.js كُتب في التاريخ. الخريطة الحقيقية تسمّي الملفات: «src/routes/invoices/create.ts يتلقى مسار POST /invoices؛ يتحقق من الحمولة في src/lib/invoice-validate.ts، ويستدعي src/lib/invoice.ts لتوليد المستند، ويكتب إلى Supabase عبر src/lib/db.ts، ويصفّ بريدًا عبر src/lib/mailer.ts». هذا تتبّع يستطيع مهندس جديد أن يحمله في رأسه ويهتدي به. وكل ما دونه محاضرة عن الـ framework.
• مسار حقيقي واحد، من أوله إلى آخره. أثمن قسم في ARCHITECTURE.md ليس قائمة الوحدات — بل تتبّع طلب واحد ممثِّل من نقطة الدخول إلى الاستجابة. اختر المسار الأهم (التسجيل، أو إنشاء الفاتورة، أو توليد التقرير) وامشِ كل ملف وكل دالة يلمسها، بالترتيب. ذلك التتبع هو ما يحوّل الخريطة إلى شيء تستعمله وأنت تشخّص.
• سمِّ الألغام. كل codebase فيه ألغامه: الدالة المتزامنة التي ستحجب، والافتراض الضمني أن user.id عدد صحيح، والجدول بلا قيود foreign-key الذي لا يحفظ اتساقه إلا طبقة التطبيق. الـ ARCHITECTURE.md الذي يسمّيها قبل أن يكتشفها أحد بالطريقة الموجعة يدفع سلفًا أسبوع التشخيص الذي وفّره للتوّ.
• الخريطة هي ما يرثه Claude في كل ما بعدها. أرفق ARCHITECTURE.md مع جلسة تشخيص — «هذه المعمارية؛ المستخدمون يبلّغون عن خطأ في انتهاء الجلسة، تتبّع منطق انتهاء الجلسة» — فيتتبع Claude مساراتك الفعلية، لا مسارات framework عام. ملف واحد، يُكتب مرة، يجعل كل جلسة تشخيص تبدأ من النظام الحقيقي لا من إعادة بنائه.

ملف CLAUDE.md — سياق المشروع الذي يجعل كل محادثة أحدّ

الـ playbook يذكر CLAUDE.md بوصفه تنويعة. الإتقان هو الحسّ الذي يفصل CLAUDE.md يغيّر فعلًا طريقة عون Claude لك عن آخر يعيد صياغة الـ README بشكل مختلف — ونمط الفشل يكاد يكون دائمًا: طموح بلا تحديد.

• الأوامر هي أثمن السطور. «اختبارات الوحدات على Vitest والاختبارات الشاملة على Playwright. أمر اختبار الوحدات npm run test:unit وأمر Playwright هو npm run test:e2e. ومدقق الأنواع npm run typecheck.» هذا سطر CLAUDE.md يوفّر على المحادثة أن تبدأ بـ«كيف أشغّل الاختبارات؟» — Claude يعرف سلفًا. معظم ملفات سياق المشروع فيها كل شيء إلا الأوامر.
• الأعراف لا المبادئ. «لا تستعمل any في TypeScript» عرفٌ يستطيع Claude اتباعه. أما «اكتب TypeScript جيدًا» فمبدأ يعرفه Claude أصلًا. الـ CLAUDE.md للقرارات المحددة التي اتخذها مشروعك: نمط معالجة الأخطاء، وعرف التسمية، وبنية الوحدات. ما لا يصلح أن يكون قاعدة linting خاصة بمشروعك لا يحتاج غالبًا أن يكون في CLAUDE.md.
• ما لا يُمسّ لا يقل قيمة عمّا يُفعل. «لا تعدّل src/lib/db.ts مباشرة — الوصول إلى قاعدة البيانات يمرّ عبر مساعدي الاستعلام في src/lib/queries/.» هذه هي الألغام في صيغة تعليمات — تسميتها في CLAUDE.md تعني أن Claude لا يدوس عليها في refactor.
• القسم الثنائي اللغة سياقُ مشروع، لا طلبُ ترجمة. لـ codebase موجَّه لسوق المنطقة، يسمّي CLAUDE.md أي أجزاء المنتج عربية أولًا، وأي سجلّ تستعمله النصوص العربية، وأي النصوص المواجهة للعملاء تُؤلَّف (لا تُترجم)، ومن في الفريق يملك المراجعة العربية. ذلك هو السياق الذي يجعل Claude شريكًا أحدّ في منتج ثنائي اللغة؛ وبدونه يكون كل ناتج عربي تخمينًا.

انضباط الـ commit — لماذا متن الرسالة أثمن سطر في تاريخكم

الـ playbook يعطيك خطوات التجهيز والالتزام في دفعات نظيفة. الإتقان هو الحسّ الذي يفصل تاريخ commits يهتدي به مهندس المستقبل عن آخر هو تنقيب أثري — ونمط الفشل واحد دائمًا: رسائل تصف ما الذي تغيّر بدل لماذا.

• العنوان هو الخبر؛ والمتن هو القصة. «Fix session expiry bug» عنوانٌ. أما «Fix session expiry bug: كانت الـ TTL تُقرأ من الإعدادات بالمللي ثانية وتُقارَن بالثواني في session.ts:142، فتنتهي الجلسات أسرع بألف مرة من المقصود. لم يغطِّ أي اختبار هذه المقارنة — أضفت واحدًا» فذلك commit يستطيع من يصل إليه بـ bisect بعد ستة أشهر أن يتصرف بناءً عليه. المتن يجيب عن اللماذا، لا الماذا.
• همّ واحد، commit واحد، دائمًا. الـ commit الذي يصلح خطأ ويحدّث إعدادًا وينظف أسماء ثلاث دوال commit لا يستطيع أحد قراءته. حين يصل المهندس التالي بـ bisect إلى ذلك الـ commit، عليه أن يقرأ مئتي سطر ليجد أي الأشياء الثلاثة هو التعديل المعني. همّ واحد لكل commit يكلّف دقيقتين؛ ويوفّر أمسية في كل مرة يحتاج فيها أحد أن يفهم ما الذي تغيّر ولماذا.
• العرف هو المعيار. اختر صيغة — type(scope): subject بمتن «لماذا»، أو أبسط منها scope: subject — وطبّقها باتساق. الصيغة أقل أهمية من الاتساق: العرف شيء يقرأ منه المهندس الجديد رسالتين فيشتق الثالثة. وإن لم تتبع الرسائل نمطًا فليست عرفًا؛ إنها كومة رسائل.
• رسائل الـ commit توثيق تكتبه وأنت تتحرك. الـ CLAUDE.md الذي تكتبه في هذه الوحدة يخبر Claude بالعرف؛ وبعدها يصوغ Claude رسائل على الصيغة وأنت تعتمدها. الانضباط أن تعرف ما الذي تشترطه، لا أن تكتب كل حرف بنفسك.

تكليفك

ابنِ وثائق الأساس الثلاث لـcodebase حقيقي واحد — الخاص بك (وهذا ما ننصح به: الناتج بنية حقيقية يرثها فريقك كله)، أو الشركة النموذجية «ميزان»، شركة SaaS خليجية لمسك الدفاتر مسجَّلة في الإمارات، معروضة في هذه الوحدة أدناه. افتح مجلد المشروع في Claude Desktop، ووافق على كل قراءة من نافذة Ask permissions، واعمل داخل المحادثة — لا حاجة إلى terminal.

ناتج الوحدة الأولى — أساس الهندسة

1. ARCHITECTURE.md  (صفحة واحدة)
   - الوحدات العليا بمسارات مجلداتها الحقيقية
   - مسار واحد ممثِّل مُتتبَّع من أوله إلى آخره: أي الملفات تجري،
     وبأي ترتيب، مع تسمية الدالة في كل خطوة
   - الألغام: الأجزاء الهشّة، والافتراضات الضمنية، وما لا اختبارات
     له ويبدو حاملًا

2. CLAUDE.md  (صفحة واحدة)
   - الـ stack وأوامر الاختبار والـ typecheck والـ lint وخادم التطوير
     بالحرف
   - الأعراف الأساسية (معالجة الأخطاء، والتسمية، وبنية الوحدات)
   - ما لا يُمسّ ولماذا
   - لفرق المنطقة: السياق العربي (أي الأقسام RTL، وأي النصوص
     تُؤلَّف، وأي سجلّ عربي خليجي يُستعمل)

3. مذكرة عرف الـ commit  (نصف صفحة)
   - الصيغة التي تلتزمها (type + scope + subject + متن)
   - مثالان معمولان: رسالة بعنوان وحده، ورسالة بعنوان ومتن يشرح
     اللماذا
   - قاعدة الهمّ الواحد لكل commit بمثال ظاهر

وحقيبة أدوات أساس الهندسة تعطيك قوالب جاهزة للتعبئة لكل واحدة من هذه، مع الـ prompts التي تبنيها.

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

هذا ما لا يملكه الـ playbook المجاني. تُقيَّم وثائقك الثلاث وفق خمسة معايير، درجة كل معيار مستوفٍ / قريب / ليس بعد — و«قريب» في أي معيار يعني إعادة التسليم، لا النجاح.

معايير تقييم الأساس

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

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

لن نتركك تخمّن كيف يبدو «المستوفي». هذه مقتطفات ناجحة للشركة النموذجية — والمطلوب من ملفك ليس أن يشبهها، بل أن يبلغ المستوى نفسه. (لاحظ أن الوثائق نفسها بالإنجليزية عن قصد — فهذه وثائق تعيش في الـ repo بجوار الكود، والكود وأدواته إنجليزية؛ العربية عندها قسمها المسمّى في CLAUDE.md.)

ARCHITECTURE.md — Mizan Engineering (excerpt)

## Top-level structure

src/routes/         API handlers (one file per route group)
src/lib/            Business logic (invoice.ts, mailer.ts, db.ts, queries/)
src/components/     Astro UI components
supabase/           Schema + migration files
tests/unit/         Vitest unit tests (mirrors src/lib/)
tests/e2e/          Playwright end-to-end tests

## Invoice creation — the representative flow

POST /invoices
  → src/routes/invoices/create.ts    (validates auth header, calls handler)
  → src/lib/invoice-validate.ts      (checks required fields, client exists)
  → src/lib/invoice.ts               (generates document, calculates totals)
  → src/lib/db.ts → queries/invoices.ts  (writes to Supabase invoices table)
  → src/lib/mailer.ts                (queues notification email via Resend)
  → returns { id, status: 'created' }

## Landmines

- mailer.ts sends email synchronously inside the route handler — a Resend
  timeout will block the HTTP response. No test covers the timeout case.
- invoice.ts assumes client.currency is 'AED'. Multi-currency is in the DB
  schema but not handled in the calculation logic.
- The invoices table has no soft-delete. audit log in invoice_events is the
  only recovery path.

CLAUDE.md — Mizan Engineering (excerpt)

## Commands

npm run test:unit     # Vitest unit tests (fast, no DB)
npm run test:e2e      # Playwright E2E (requires dev server)
npm run typecheck     # tsc --noEmit
npm run dev           # Astro dev server at localhost:4321

## Conventions

- All DB access goes through src/lib/queries/ — never call supabase directly
  from a route handler or component
- Error responses use { error: string, code: string } — no raw throws that
  reach the client
- Async functions always have explicit return types

## Do not touch

- supabase/migrations/ — use `supabase migration new` to add migrations.
  Never edit existing migration files.
- src/lib/db.ts directly — extend queries/ instead

## Bilingual context

Product is bilingual EN + AR. Arabic sections: invoice PDFs, client emails,
src/content/ar/ UI strings.
AR strings are authored in Gulf Arabic register — not translated from English.
Flag Arabic-language changes to @bilal-dev for review.
RTL layout: src/styles/global.css uses logical CSS properties — never use
physical left/right in new styles.

Commit convention — Mizan Engineering (excerpt)

Format: type(scope): subject (50 chars max)
        <blank line>
        Body: why this change was needed (not what it does).
        One concern per commit — never mix bug fix with refactor.

Example 1 (subject only, for a trivial change):
  chore(deps): bump Resend SDK to 2.1.0

Example 2 (with body, for anything a reviewer would question):
  fix(invoice): correct AED rounding on totals above 10,000

  Supabase stores amounts as integers (fils). The calculation rounded
  before multiplying by 100, introducing a 1-fils error on totals
  above AED 10,000. Fixed order-of-operations and added a unit test
  for the boundary value.

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

باجتيازك هذه المعايير تكون قد أنجزت ما لا يستطيع المسار المجاني أن يشهد لك به: بنيت أساسًا هندسيًا حقيقيًا بمستوى احترافي، وأظهرت الحسّ المهني الذي وراءه. هذه هي مرحلة الأساس من اعتماد «الهندسة مع Claude».

من هنا يحوّل المسار الأساس إلى ممارسة هندسية عاملة، وكل وحدة تُقيَّم بالطريقة نفسها:

• الوحدة 2 — محرّك جودة الكود: المراجعة بعين الخصم وانضباط الـ commit النظيف — الحركتان اللتان تُبقيان الـ codebase مقروءًا وقابلًا للمراجعة.
• الوحدة 3 — شحن الميزات: حلقة «الـ spec أولًا، والخطة قبل الـ diff» التي تشحن الميزات خلف حزمة خضراء بلا مفاجآت.
• الوحدة 4 — التغيير الآمن: انضباط الـ refactor الذي يجعل التنظيف البنيوي شيئًا تقف وراءه في المراجعة.
• الوحدة 5 — النقلة الكبرى: منهج الـ migration الذي يحوّل التسعين بالمئة الآلية ويرفع العشرة الصعبة إلى حُكمك.

لكن قبل ذلك، اجعل ما بنيته قابلًا لإعادة الاستخدام: خذ حقيبة أدوات أساس الهندسة — قالب CLAUDE.md، وقالب ARCHITECTURE.md، ومكتبة الـ prompts التي يثبّتها فريقك ويرثها. وإن كنت تطرح هذا على فريق هندسي كامل، فـدليل تشغيل الهندسة مع Claude هو طبقة الأذونات والحدود والمراجعة التي تقوم تحت كل ما سبق.