playbook

ارسم خريطة codebase لم ترَه من قبل

وجّه Claude إلى repo غير مألوف واحصل على جولة راسخة — الـ modules الحقيقية، وكيف يتدفّق request، وأين تعيش الأجزاء المخيفة — بالإنجليزية البسيطة، مسمّيًا ملفات موجودة فعلًا.

سهل ~15 دقيقة

متى تلجأ إلى هذا

وظيفة جديدة، أو repo جديد، أو مجرّد ركن من المنتج لم تلمسه قط. الـ README متأخّر بثلاث إعادات كتابة، ومن كتب الـ auth flow غادر قبل شهرين. عادةً هذا يومٌ كامل من الـ grep والتخمين. أنت لا تحتاج Claude ليكتب الكود — تحتاجه ليقرأ أربعين ملفًا أسرع منك ويخبرك الحقيقة عمّا هو موجود فعلًا.

جهّز هذا أولًا

الـ repo نفسه — افتح Claude Code في المجلد الجذر للمشروع كي يقرأ ملفاتك الحقيقية، لا ذاكرته عن شكل المشاريع المشابهة *عادةً*.
نقطة دخول ملموسة واحدة تهمّك: route، أو فعل مستخدم، أو CLI command — «ماذا يحدث حين يُسجّل مستخدم» تتفوّق على «اشرح الكود».

الـ workflow

01
اطلب الخريطة، لا محاضرة

ابدأ واسعًا. أنت تريد الشكل العام والأسماء الحقيقية للملفات، كي تعرف أين تضع يديك قبل أن تتعمّق.
أنت تطلب
```
اقرأ هذا الـ repo وأعطني الخريطة: الـ modules العليا، وكيف يتدفّق request فعلًا من الـ route إلى الـ database، وأين يعيش الـ authentication. بالإنجليزية البسيطة، وسمِّ الملفات الحقيقية — لا تعطني محاضرة عامة عن الـ framework.
```
ما تحصل عليه جولة راسخة — src/routes/ ← middleware/auth.ts ← الـ session store — مسمّيةً ملفات موجودة. الآن تعرف الهيكل العظمي.

إن بدأ يصف نسخة عامة من الـ framework الخاص بك بدل ملفاتك الفعلية، فهو لم يقرأ الـ repo — تأكّد أنك فتحت Claude Code في المجلد الجذر للمشروع.
02
تعقّب مسارًا حقيقيًا واحدًا من البداية للنهاية

اختر التدفّق الذي يهمّك فعلًا واجعله يمشي المسار كاملًا. هنا تتحوّل الخريطة الغامضة إلى شيء تستطيع تغييره.
أنت تطلب
```
امشِ بي عبر ما يحدث بالضبط حين يُسجّل مستخدم: أي ملفات تعمل، وبأي ترتيب، وأين تنتهي البيانات. سمِّ كل ملف والـ function داخله، ونبّه إلى أي شيء فاجأك.
```
ما تحصل عليه تعقّب مرتّب — handler ← validation ← إنشاء المستخدم ← session — مع مؤشّرات file:function، إضافةً إلى ملاحظة عن أي شيء غير بديهي (side effect خفي، أو queue، أو write ثانٍ).
03
اعثر على الألغام قبل أن تلمس أي شيء

قبل أن تغيّر كودًا لم تكتبه، اسأل عمّا هو هشّ. أرخص أن تسمعه الآن من أن تكتشفه في الـ production.
أنت تطلب
```
لو اضطُررت لتغيير الـ signup flow الأسبوع القادم، ما الذي سيعضّني؟ أشِر إلى الأجزاء المترابطة بإحكام (tightly-coupled)، والافتراضات الضمنية، والأجزاء بلا tests، وأي شيء يبدو حامِلًا للأثقال لكن بلا توثيق.
```
ما تحصل عليه قائمة مخاطر قصيرة — «إرسال البريد الإلكتروني متزامن (synchronous) وسيُعطِّل التنفيذ»، «هذا يفترض أن users.id هو int»، «لا tests تغطّي مسار البريد الإلكتروني المكرّر» — كي تدخل وعيناك مفتوحتان.

اجعله ملكك

**onboarding زميل:** اطلب ملف ARCHITECTURE.md — «اكتب خريطة من صفحة واحدة لهذا الـ repo يستطيع موظّف جديد قراءتها في يومه الأول» — وأدرجه في الـ repo كي لا يبدأ الشخص التالي من الصفر.
**repo كبير:** استعِن بـ subagent للقراءات الواسعة («ابحث في الـ repo كله عن كل مكان نقرأ فيه من الـ database») كي لا يزاحم الحفرُ العميق الـ context الذي تحتاجه للعمل الفعلي. انظر /features/subagents/.

انتبه إلى

إنه يقرأ، لا يُملي وحيًا — تحقّق بنفسك من الادّعاءين أو الثلاثة التي توشك أن تتصرّف بناءً عليها بفتح الملفات. المؤشّر الخاطئ الواثق يبقى خاطئًا.
إن كان الـ repo ضخمًا، فقد يلخّص الأجزاء التي اطّلع عليها عيّنةً ويقدّمها على أنها الكل. اسأل «ما الذي *لم* تقرأه؟» لتجد النقاط العمياء.

ستحصل في النهاية على في خمس عشرة دقيقة تنتقل من «لم أرَ هذا الكود قط» إلى خريطة ذهنية حقيقية — الـ modules، ومسار request كامل واحد، والأجزاء الهشّة — ستبقى تستخدمها طوال الأسبوع.

اطلب الخريطة، لا محاضرة

تعقّب مسارًا حقيقيًا واحدًا من البداية للنهاية

اعثر على الألغام قبل أن تلمس أي شيء