# سير عمل التوثيق لعملاء LLM
SUMMARY: كيف يوثّق وكيل LLM عمله: الذكريات، وسجلات العمل، وسجلات التغيير، ورسائل الإيداع.

KEY CONTEXT:
وثّق أثناء العمل، لا في نهاية الجلسة. ثلاث طبقات:
1) POST /memory لكل حقيقة دائمة، أو قرار، أو خطأ، أو بيانات اعتماد.
2) POST /worklog/:task_id للتقدم لكل مهمة (start/progress/error/close).
3) سجل تغيير تقليدي + رسائل إيداع لتغييرات الكود.
الحقيقة التي لا تُخزَّن لم تحدث أبدًا — الجلسة التالية لن تعرفها.

سير عمل التوثيق لعملاء LLM
وكلاء LLM مصابون بالفقدان افتراضيًا: كل جلسة تبدأ من الصفر. الشيء الوحيد الذي يعبر حدود الجلسة هو ما خزّنته في نظام خارجي. التوثيق ليس بروتكراتية — إنه الطريقة التي تبقى بها نفسك عبر الجلسات.
الطبقات الثلاث
| الطبقة | أين | ماذا | متى |
|---|---|---|---|
| Memory |  | حقائق دائمة، قرارات، أخطاء، بيانات اعتماد | لحظة تعلّمك لها |
| Worklog |  | تقدم المهمة، أخطاء، محطات | بعد كل خطوة ذات معنى |
| Changelog |  في المستودع + إيداع | تغييرات مرئية للمستخدم | مع كل تغيير في الكود |
الطبقة 1: الذكريات
خزّن ذكرى عندما تكون الحقيقة جديدة، لا عند نهاية الجلسة. الجلسات تنهار؛ نوافذ السياق تفيض؛ «سأكتبها لاحقًا» حقيقة لم تحدث أبدًا.
اختر الفئة الصحيحة:
-  — من أنت، دورك، أشقاؤك
-  — حالة المشروع وقراراته
-  — ما الذي سار خطأً والدروس (الفئة الأكثر قيمة)
-  — كيف يُفعل شيء ما (قوائم خطوات، أوامر)
-  — رموز، نقاط نهاية، مسارات (لا في المحادثة أو الكود أبدًا)
-  — حالة جلسة تستحق الانتقال
استخدم  بصدق (1.0 = موثّق، 0.5 = افتراض) ووسّم باتساق — تُجد الذكريات بالوسم والمفتاح، لا بالنثر.
[CODE BLOCK]
الطبقة 2: سجلات العمل
سجل العمل هو دفتر تقدم مهمة واحدة. يجيب عن «ما الذي حدث بالضبط أثناء الحل؟» لكل قارئ مستقبلي — بما في ذلك أنت في المستقبل.
[CODE BLOCK]
قاعدة الإبهام: إدخال واحد لكل قرار أو اكتشاف، لا لكل ساعة. الأخطاء تدخل السجل فورًا — إنها الإدخالات الأكثر نفعًا لاحقًا.
الطبقة 3: سجل التغيير والإيداعات
تغييرات الكود هي توثيق أيضًا:
- رسالة الإيداع: ما تغيّر ولماذا، مع مرجع المهمة/المستخدم بين قوسين. السطر الأول أقل من 72 حرفًا، بصيغة الأمر.
- CHANGELOG.md: إدخال واحد لكل تغيير مرئي للمستخدم، مجمّع كـ Added / Changed / Fixed / Removed، مع الإصدار والتاريخ.
الإصلاح بلا إدخال في سجل التغيير غير مرئي لكل من لم يقرأ الفرق.
الأنماط المضادة
- إفراغ الذاكرة في نهاية الجلسة. السياق مفقود حينها — خزّن باستمرار.
- ذكريات نثرية. «ربما كانت مسألة قاعدة البيانات في مكان ما في الإعدادات» لا تُجد. استخدم مفاتيح دقيقة ووسومًا وبنية محتوى.
- إعادة محاولة صامتة. كل محاولة فاشلة تدخل سجل العمل؛ وإلا كررها الوكيل التالي.
- المحادثة كمخزن. سجل المحادثة ليس قاعدة معرفة — استخرج الحقائق الدائمة إلى ذكريات.
حلقة كاملة
1. تعلّم شيئًا →  (الآن)
2. ابدأ مهمة → 
3. كل خطوة/خطأ → 
4. غيّر الكود → إيداع + إدخال في CHANGELOG
5. أنهِ → 
6. علّم المهمة كمنجزة → 
تستطيع الجلسة التالية — أو وكيل أخ يتولى مهمتك — إعادة بناء كل شيء: قائمة المهام تقول ماذا، وسجل العمل يقول كيف، والذكريات تقول لماذا.