How to Write a CLAUDE.md That Actually Works (Based on Real Research)

Watch on YouTube

Now Playing

Transcript

299 segments

0:00

عندما تستخدم Cloud Code،

0:01

يمكنك وضع ملف في

0:03

مستودعك يسمى cloud.md.

0:04

يستخدم CodeX ملف agents.md،

0:06

ومعظم وكلاء البرمجة

0:07

الآخرين لديهم ملف

0:08

تعليمات مشابه على

0:09

مستوى المستودع.

0:10

لنفترض أن هذه واجهة

0:11

برمجة تطبيقات

0:12

للمدفوعات. Node، و

0:13

TypeScript، و Postgres. في

0:15

اليوم الأول، يحتوي

0:16

ملفك على ثلاث قواعد.

0:17

استخدم PNPM، ولا تستخدم

0:19

NPM أبداً. لا تقم

0:20

بتعديل أي شيء في

0:21

المجلد الذي تم إنشاؤه

0:22

. قم بتشغيل PNPM test قبل

0:24

أن تقول إن المهمة قد

0:25

انتهت. وهذا ملف جيد.

0:27

يقرأه الوكيل قبل أن

0:29

يبدأ العمل. وتلك

0:30

الأسطر الثلاثة توفر

0:31

عليك وقتاً حقيقياً.

0:32

الآن، إليك نفس الملف

0:34

بعد 18 شهراً. 29 قاعدة،

0:36

وستة أقسام، بعضها

0:38

كتبته أنت، ومعظمها لم

0:39

تكتبه. وأراهن أنه لم

0:41

يقم أحد في الفريق

0:42

بحذف سطر واحد منه على

0:44

الإطلاق. الآن، هناك

0:50

ورقة بحثية جديدة بقلم

0:52

كوشال تشاكرابورتي

0:53

قيست هذا عبر ما يقرب

0:54

من 2000 مستودع. في

0:56

المتوسط، تتضاعف هذه

0:57

الملفات أكثر من ثلاث

0:58

مرات خلال عمرها

0:59

الافتراضي. وهناك

1:00

تكلفة حقيقية لذلك.

1:02

توصي وثائق Anthropic

1:03

نفسها بإبقاء cloud.md أقل

1:05

من 200 سطر. لأن الملفات

1:07

الأطول تستهلك المزيد

1:08

من السياق وتقلل من

1:09

مدى موثوقية اتباع

1:10

النموذج لها. إذاً،

1:11

لماذا لا يقوم أحد

1:13

بتنظيفها؟ إضافة

1:14

قاعدة أمر سهل. يفسد

1:15

الوكيل شيئاً ما،

1:16

فتكتب سطراً واحداً،

1:18

ثم تقوم بالحفظ. حذف

1:19

أحدها وظيفة مختلفة

1:20

تماماً. انظر إلى هذا

1:22

السطر في المتفرقات.

1:23

أضف دائماً سطراً

1:24

جديداً في نهاية ملفات

1:25

التكوين التي يتم

1:26

إنشاؤها. هل لا تزال

1:27

بحاجة إليه؟ ليس لديك

1:29

أدنى فكرة. أضافه شخص

1:30

ما بعد أن حدث عطل ما.

1:32

ربما تم استبدال تلك

1:33

الأداة. ربما لم يكن

1:34

الأمر مهماً أبداً. لا

1:36

يوجد أحد ممن يمكنه

1:37

إخبارك بذلك لا يزال

1:38

يعمل هنا. ولا يمكنك

1:39

اختبار هذه القواعد

1:40

واحدة تلو الأخرى

1:41

لأنها قد تتداخل. انظر

1:42

إلى هاتين القاعدتين

1:43

الخاصتين بقاعدة

1:43

البيانات. إحداهما

1:44

تقول إن كل عملية

1:45

كتابة متعددة الجداول

1:46

يجب أن تستخدم معاملة (

1:47

Transaction). والأخرى تقول

1:48

إن عمليات الدفع

1:49

وإدخالات دفتر

1:50

الأستاذ يجب أن تُكتب

1:51

في نفس المعاملة.

1:52

القاعدة الثانية

1:53

مغطاة بالفعل من قبل

1:54

الأولى. لذا، احذف

1:55

أياً منهما ولن ينكسر

1:57

شيء. احذفهما معاً وقد

1:58

يتركك وقت التوقف بنصف

1:59

عملية الدفع فقط

2:00

مكتوبة. وهذه هي

2:01

المشكلة برمتها في سطر

2:03

واحد. الإضافة أمر غير

2:05

مكلف. لكن إثبات أن

2:06

الحذف آمن ليس كذلك.

2:07

لذا، لا يقوم الناس

2:08

بتقليم هذه الملفات.

2:10

إنهم يجرفونها

2:10

بالكامل. في هذه

2:11

المجموعة من البيانات

2:12

، معظم القواعد التي

2:13

تختفي لا تتم إزالتها

2:14

واحدة تلو الأخرى.

2:15

إنها تتلاشى عندما

2:16

يعيد شخص ما كتابة

2:17

معظم الملف دفعة واحدة

2:18

. ثم تنمو وتعود من

2:20

جديد. في المتوسط،

2:21

أسرع حتى مما نمت في

2:22

المرة الأولى. والورقة

2:24

البحثية لديها اسم

2:25

للمشكلة الأساسية.

2:26

التذكر الكارثي. أنت

2:28

تلتزم بقاعدة ليس لأنك

2:30

تعلم أنها ضرورية، بل

2:31

لأنك لم تعد تتذكر سبب

2:33

إضافتها، وحذفها يبدو

2:34

محفوفاً بالمخاطر.

2:35

وهذا يشير إلى حل بسيط

2:37

للغاية. اكتب السبب.

2:39

ليس تعليمات أخرى

2:40

للنموذج. بل ملاحظة

2:42

للشخص التالي الذي

2:43

يفتح هذا الملف. في

2:44

تجربة الورقة البحثية

2:45

، انتهى الأمر

2:46

بالعملاء الذين سجلوا

2:47

سبباً لكل قاعدة بحجم

2:48

ملف قريب من الحجم

2:50

الصحيح. أما أولئك

2:51

الذين لم يفعلوا، فقد

2:52

استمروا في تكديس

2:53

القواعد. نفس المهمة،

2:54

ونفس الملاحظات. الفرق

2:55

الوحيد كان فيما إذا

2:57

كان السبب قد بقي

2:58

محفوظاً. و Claude code يدعم

2:59

بالفعل نسخة عملية

3:00

لهذه الصيانة البشرية.

3:02

يتم حذف تعليق HTML على

3:04

مستوى الكتلة داخل

3:05

Claude.md قبل إدراج الملف

3:07

في سياق Claude. لذا،

3:09

يمكنك ترك التبرير

3:10

لفريقك دون أن تستهلك

3:11

تلك الملاحظات السياق

3:12

عند تحميل الملف بشكل

3:13

طبيعي. إليك قاعدة

3:14

معاملات مع تعليق

3:16

فوقها. حادثة الفشل 412،

3:18

سبتمبر. مهمة الدفع

3:20

التي كتبت في جدول

3:21

المدفوعات انتهت

3:23

مهلتها قبل أن تكتب في

3:24

إدخالات السجل، وتركت

3:25

1300 صف يتيم استغرق

3:27

إصلاحها يومين. لماذا

3:28

تساعد هذه القاعدة؟

3:30

وضع كلتا الكتابتين في

3:31

معاملة واحدة يعني أن

3:32

كلاهما يتم اعتماده أو

3:33

لا يتم أي منهما. وما

3:35

هي النتيجة؟ لقد نجحت.

3:37

لا توجد صفوف يتيمة

3:38

منذ 11 شهراً. الفشل،

3:40

السبب، النتيجة. هذه

3:42

الثلاثة هي ما وجدته

3:43

التجارب يُحدث فرقاً

3:44

حقيقياً. وأنا أضيف

3:46

مرجع التعليق أيضاً.

3:47

وهذه عادتي الشخصية

3:48

وليس نتيجة لتجربة

3:49

Peverse. الآن، هناك جزء

3:51

ثانٍ لهذا الأمر، وهو

3:52

بنفس القدر من الأهمية

3:54

. التعليقات الجيدة لن

3:55

تنقذك إذا استمررت في

3:56

حل كل مشكلة بإضافة

3:57

سطر آخر إلى هذا الملف.

3:59

وتوثيق Tropic واضح

4:00

تماماً بشأن ما يجب

4:02

وضعه وأين. لذا، دعني

4:03

أطبقه على مستودع

4:04

المدفوعات الخاص بنا.

4:05

ملف Cloud.md مخصص للأشياء

4:06

المتعلقة بالمشروع

4:07

بالكامل التي يحتاج

4:08

Cloud لمعرفتها مراراً

4:09

وتكراراً. أشياء مثل

4:10

مدير الحزم المستخدم،

4:12

كيفية تشغيل

4:12

الاختبارات، اتفاقيات

4:14

الفريق المهمة، أو

4:15

القرارات المعمارية

4:16

غير الواضحة من الكود.

4:17

إذا كان بإمكان Cloud

4:19

استنتاج شيء ما بمجرد

4:20

قراءة المستودع،

4:21

فربما لا تحتاج إلى

4:22

وضعه هنا. إذا كانت

4:23

القاعدة تهم فقط جزءاً

4:24

واحداً من قاعدة الكود

4:25

، فيجب أن تكون قاعدة

4:26

مرتبطة بالمسار بدلاً

4:27

من ذلك. قاعدتا

4:28

المعاملات الخاصتان

4:29

بنا تهمان فقط ضمن

4:30

المدفوعات المصدرية.

4:31

ضعهما في ملفات قواعد

4:33

مقيدة بهذا المسار،

4:34

وسيدخلان في السياق

4:35

فقط عندما يقرأ Cloud

4:36

الملفات المطابقة. إذا

4:38

كان إجراءً متعدد

4:39

الخطوات، فهذه مهارة.

4:41

سير عمل ترحيل الإنتاج

4:42

المكون من خمس خطوات

4:43

لدينا هو مهارة، وليس

4:44

مجرد خمس نقاط إضافية.

4:46

وإذا كان يجب تشغيل

4:47

أمر ما في نقطة محددة،

4:48

فاستخدم خطافاً (hook).

4:50

ملف Cloud.md هو سياق،

4:52

وليس وسيلة إنفاذ.

4:53

يقرؤه كلاود ويحاول

4:55

اتباعه. تعمل خطافات

4:56

الأوامر تلقائيًا عند

4:58

حدث دورة الحياة، بغض

4:59

النظر عما يقرره كلاود

5:00

. الآن، هناك فخ واحد

5:02

يستحق المعرفة. تقسيم

5:04

ملف ضخم إلى استيرادات

5:05

مسارات التطبيق

5:07

يساعدك في تنظيمه،

5:08

لكنه لا يوفر أي سياق

5:09

لأن الملفات

5:10

المستوردة تُحمل عند

5:12

التشغيل. قواعد رمز

5:13

المرور هي التي تبقى

5:15

فعليًا خارج السياق

5:16

حتى الحاجة إليها.

5:17

وتحذيران سريعان قبل

5:19

أن ننتهي. التعليق

5:20

الغامض لا يفيد كثيرًا

5:22

. انظر إلى أسفل هذا

5:23

الملف. تمت إضافته

5:24

لإصلاح مشكلة رأيناها

5:26

سابقًا. في التجارب،

5:27

كان أداء تعليقات كهذه

5:28

مساويًا لعدم كتابة أي

5:30

تعليق على الإطلاق.

5:31

لذا، إذا سجلت ما

5:32

جربته، سجل النتيجة

5:33

أيضًا. بخلاف ذلك، أنت

5:35

تترك للمشرف التالي

5:36

تخمينًا غير مؤكد.

5:38

والتعليق دليل، وليس

5:39

إثباتًا. إنه يخبرك

5:41

بما يجب عليك الذهاب

5:42

للتحقق منه. لا يخبرك

5:43

بأن الحذف آمن. لذا،

5:45

أبقِ شخصًا في الصورة

5:46

قبل إزالة أي شيء،

5:47

خاصة فيما يتعلق

5:48

بالدفع أو الأمان أو

5:49

الامتثال. وملف cloud.md

5:51

هو جزء واحد فقط من كود

5:52

السحابة. القواعد،

5:54

والمهارات، والخطافات

5:55

، والوكلاء الفرعيون،

5:56

والذاكرة، هناك

5:57

الكثير لاستخدام هذا

5:58

بشكل صحيح. وأنا أجهز

5:59

دورة متقدمة كاملة حول

6:00

كود السحابة حيث

6:01

سنستعرض كل هذا بشكل

6:02

صحيح ونبني مشاريع

6:03

حقيقية به. لذا، اشترك

6:04

إذا كنت تريد اللحاق

6:06

بذلك عند صدوره. لكن،

6:07

في الوقت الحالي، ابدأ

6:09

بأمرين. احتفظ فقط

6:10

بالتعليمات التي

6:11

تنتمي حقًا إلى هنا.

6:12

وعندما تضيف قاعدة،

6:14

اكتب سبب وجودها.

6:15

تنتهي الورقة بسؤال

6:17

جيد. إذا كانت

6:18

الإنجليزية هي الكود

6:19

الجديد، فلماذا لا

6:20

نملك تعليقات حتى الآن

6:21

؟ في كود السحابة،

6:22

أصبح لدينا ذلك جزئيًا

6:23

الآن. الآلية موجودة

6:24

بالفعل. العادة هي

6:26

الجزء الصعب. أراكم في

6:28

المرة القادمة.

Interactive Summary

Ask follow-up questions or revisit key timestamps.

يتناول الفيديو مشكلة تضخم ملفات التعليمات البرمجية مثل cloud.md التي يستخدمها وكلاء البرمجة مثل Claude Code. يوضح الفيديو كيف تتراكم القواعد غير الضرورية بمرور الوقت نتيجة "التذكر الكارثي" وعدم وجود توثيق لأسباب إضافتها، مما يجعل صيانتها صعبة ومحفوفة بالمخاطر. يقدم الفيديو حلولاً عملية مثل كتابة أسباب إدراج كل قاعدة باستخدام تعليقات HTML، وتقسيم القواعد بناءً على المسارات، واستخدام خطافات الأوامر (hooks) والمهارات بدلاً من تكديس التعليمات في ملف واحد لضمان الحفاظ على كفاءة سياق عمل الوكيل.