هل أحتاج إلى تجهيز أي شيء قبل البدء، أم أستطيع فتح الـ repo مباشرةً؟

افتح المجلد الجذر للمشروع في Claude Desktop — هذا هو الشيء الوحيد الذي يهمّ، ولا يحتاج Terminal. بدونه يقرأ Claude ذاكرته التدريبية عن شكل الـ repos المشابهة، لا ملفاتك الفعلية. اجهّز نقطة دخول ملموسة واحدة (route، أو فعل مستخدم، أو CLI command) كي يكون السؤال الأول محدّدًا لا «اشرح الـ codebase كله».

كيف أعرف أن Claude قرأ ملفاتي فعلًا ولم يُهلوِس بنية معقولة؟

اطلب منه تسمية ملفات وfunctions محدّدة، ثم تحقّق بنفسك من اثنين أو ثلاثة منها في الشجرة الفعلية. إن كانت مسارات الملفات التي يذكرها غير موجودة أو أسماء الـ functions خاطئة، فهو يصف نسخة عامة من الـ framework لا الـ repo الخاص بك — تأكّد أن المجلد الجذر المفتوح في Claude Desktop هو مجلد المشروع، لا مجلد أعلى منه أو مجاور (أو، في مسار Power Track، أنك شغّلت claude من المجلد الجذر).

هل يمكنني استخدام هذا على monorepo ضخم بمئات الـ modules؟

نعم، لكن استعِن بـ subagent للقراءات الواسعة كي لا يزاحم البحث العريض الـ context الذي تعمل فيه. اطلب من Claude «ابحث في الـ repo كله عن كل مكان نقرأ فيه من الـ database» عبر subagent، ثم استخدم النتائج لتضييق نطاق محادثة رسم الخريطة على المناطق التي تهمّك فعلًا.

ماذا لو أردت توثيق الخريطة لاستخدامها في onboarding زميل؟

اطلب من Claude كتابة ملف ARCHITECTURE.md — «اكتب خريطة من صفحة واحدة لهذا الـ repo يستطيع موظّف جديد قراءتها في يومه الأول» — ثم أدرجه في الـ repo. الخريطة التي حصلت عليها للتوّ هي الخام؛ والـ ARCHITECTURE.md هو الأثر الذي يعني أن الشخص التالي لن يبدأ من الصفر.

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

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

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

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

الـ repo نفسه — في Claude Desktop، افتح المجلد الجذر للمشروع كي يقرأ Claude ملفاتك الحقيقية، لا ذاكرته عن شكل المشاريع المشابهة عادةً. (مسار Power Track: تشغيل claude في المجلد الجذر من الـ Terminal يفعل الشيء نفسه.)
نقطة دخول ملموسة واحدة تهمّك: route، أو فعل مستخدم، أو CLI command — «ماذا يحدث حين يُسجّل مستخدم» تتفوّق على «اشرح الكود».

الـ workflow

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

افتح المجلد في Claude Desktop واسأل في المحادثة — قراءة repo لا تحتاج Terminal. ابدأ واسعًا: أنت تريد الشكل العام والأسماء الحقيقية للملفات، كي تعرف أين تضع يديك قبل أن تتعمّق.

أنت تطلب

اقرأ هذا الـ repo وأعطني الخريطة: الـ modules العليا، وكيف يتدفّق request فعلًا من الـ route إلى الـ database، وأين يعيش الـ authentication. بالإنجليزية البسيطة، وسمِّ الملفات الحقيقية — لا تعطني محاضرة عامة عن الـ framework.

ما تحصل عليه جولة راسخة — src/routes/ ← middleware/auth.ts ← الـ session store — مسمّيةً ملفات موجودة. الآن تعرف الهيكل العظمي.

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

اختر التدفّق الذي يهمّك فعلًا واجعله يمشي المسار كاملًا. هنا تتحوّل الخريطة الغامضة إلى شيء تستطيع تغييره.

أنت تطلب

امشِ بي عبر ما يحدث بالضبط حين يُسجّل مستخدم: أي ملفات تعمل، وبأي ترتيب، وأين تنتهي البيانات. سمِّ كل ملف والـ function داخله، ونبّه إلى أي شيء فاجأك.

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

قبل أن تغيّر كودًا لم تكتبه، اسأل عمّا هو هشّ. أرخص أن تسمعه الآن من أن تكتشفه في الـ production.

أنت تطلب

لو اضطُررت لتغيير الـ signup flow الأسبوع القادم، ما الذي سيوقعني في مشكلة؟ أشِر إلى الأجزاء المترابطة بإحكام (tightly-coupled)، والافتراضات الضمنية، والأجزاء بلا tests، وأي شيء يبدو أساسيًّا يعتمد عليه الكثير لكن بلا توثيق.

ما تحصل عليه قائمة مخاطر قصيرة — «إرسال البريد الإلكتروني متزامن (synchronous) وسيُعطِّل التنفيذ»، «هذا يفترض أن users.id هو int»، «لا tests تغطّي مسار البريد الإلكتروني المكرّر» — كي تدخل وعيناك مفتوحتان.

اجعله ملكك

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

انتبه إلى

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

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

أسئلة يطرحها الناس

هل أحتاج إلى تجهيز أي شيء قبل البدء، أم أستطيع فتح الـ repo مباشرةً؟: افتح المجلد الجذر للمشروع في Claude Desktop — هذا هو الشيء الوحيد الذي يهمّ، ولا يحتاج Terminal. بدونه يقرأ Claude ذاكرته التدريبية عن شكل الـ repos المشابهة، لا ملفاتك الفعلية. اجهّز نقطة دخول ملموسة واحدة (route، أو فعل مستخدم، أو CLI command) كي يكون السؤال الأول محدّدًا لا «اشرح الـ codebase كله».
كيف أعرف أن Claude قرأ ملفاتي فعلًا ولم يُهلوِس بنية معقولة؟: اطلب منه تسمية ملفات وfunctions محدّدة، ثم تحقّق بنفسك من اثنين أو ثلاثة منها في الشجرة الفعلية. إن كانت مسارات الملفات التي يذكرها غير موجودة أو أسماء الـ functions خاطئة، فهو يصف نسخة عامة من الـ framework لا الـ repo الخاص بك — تأكّد أن المجلد الجذر المفتوح في Claude Desktop هو مجلد المشروع، لا مجلد أعلى منه أو مجاور (أو، في مسار `Power Track`، أنك شغّلت `claude` من المجلد الجذر).
هل يمكنني استخدام هذا على monorepo ضخم بمئات الـ modules؟: نعم، لكن استعِن بـ subagent للقراءات الواسعة كي لا يزاحم البحث العريض الـ context الذي تعمل فيه. اطلب من Claude «ابحث في الـ repo كله عن كل مكان نقرأ فيه من الـ database» عبر subagent، ثم استخدم النتائج لتضييق نطاق محادثة رسم الخريطة على المناطق التي تهمّك فعلًا.
ماذا لو أردت توثيق الخريطة لاستخدامها في onboarding زميل؟: اطلب من Claude كتابة ملف `ARCHITECTURE.md` — «اكتب خريطة من صفحة واحدة لهذا الـ repo يستطيع موظّف جديد قراءتها في يومه الأول» — ثم أدرجه في الـ repo. الخريطة التي حصلت عليها للتوّ هي الخام؛ والـ `ARCHITECTURE.md` هو الأثر الذي يعني أن الشخص التالي لن يبدأ من الصفر.