مستودع واحد. عقل مشترك واحد.

دليل عملي لذاكرة ذكاء اصطناعي مشتركة بين أفراد فريق التطوير.

المشكلة: معرفة فريقك عالقة داخل سجلات المحادثة

Git يزامن الشيفرة المصدرية. لكنه لا يزامن ما تعلمه الذكاء الاصطناعي أثناء كتابتها.

معظم فرق التطوير اليوم تعمل مع مساعدين برمجيين يعتمدون على الذكاء الاصطناعي، ومعظمها تستخدم أكثر من واحد. مطور يفضل Claude Code، وآخر يعمل في Cursor، وثالث يشغل Codex. كل مساعد يبني نموذجا خاصا للمشروع داخل سجل محادثته وحده: أي المقاربات رفضت من قبل، ولماذا ثبت مسار معين على وضع واحد، وأي إعادة هيكلة تبدو بريئة ثم تتسبب في عطل. الشيفرة تصل إلى المستودع. الفهم لا يصل أبدا.

الأعراض مألوفة لكل من يعمل بهذه الطريقة: المتطلبات نفسها تشرح من جديد في كل جلسة، ومساعدون مختلفون يقترحون بنى متعارضة، وقرارات يعاد فتحها لأن سبب اتخاذها لم يعد موثقا، والألغام نفسها يكتشفها كل شخص من جديد. في فريقي، وبمراجعة تاريخنا، شحن صنف واحد من أخطاء الصلاحيات ست مرات منفصلة خلال أربعة أشهر. في كل مرة كان المطور والوكيل اللذان أصلحاه يتعلمان الدرس. ثم تختفي المعرفة في سجل محادثة، وتعيد الميزة التالية إدخال الخطأ نفسه.

السبب الجذري بسيط في صياغته. الفرق تؤرشف نسخ شيفرتها وتوثيقها وبنيتها التحتية. لكنها لا تؤرشف القرارات الهندسية، ولا البدائل المرفوضة، ولا مبررات التنفيذ، ولا المعرفة التي يراكمها مساعدوها. هذا الدليل يعالج ذلك بملفات عادية وبنظام إدارة النسخ الذي تملكه أصلا.

المبدأ: أودع العقد، لا الآلة

لم توحد Docker بيئات التشغيل بتشغيل خدمة مزامنة. وحدتها بملف نصي مودع. ملف docker-compose.yml ينتقل مع المستودع، وكل جهاز يفسره بالطريقة نفسها. تحولت مشكلة البيئة إلى مشكلة عقد ملفات، وحل Git مسألة التوزيع مجانا.

الذاكرة المشتركة للذكاء الاصطناعي لها الشكل نفسه تماما. القطعة الناقصة هي عقد ملفات يقرأه كل وكيل عند بداية الجلسة ويكتب إليه قبل نهايتها. Git هو ناقل التوزيع أصلا، ولا حاجة إلى أي بنية تحتية جديدة.

كل ما يلي مشتق من هذه الفكرة الواحدة.

ما هو موجود فعلا (حتى يوليو 2026)

لست مضطرا لاختراع الأعراف. أربع لبنات تهم هنا:

البنية ذات الطبقات الثلاث

الطبقة الأولى: القواعد. ملف AGENTS.md مرجعي واحد لكل مستودع. نظرة عامة على البنية، وأوامر البناء والاختبار، والأعراف، ومعايير المراجعة، وعقد الجلسة الوارد في هذا الدليل. محتوى ثابت يتغير نادرا.

الطبقة الثانية: المعرفة المتطورة. مجلد .ai/ مودع في المستودع يحمل حالة العمل: ما يجري الآن، والقرارات، والمشكلات المعروفة، والدروس. يتغير أسبوعيا أو يوميا، ويؤرشف ويراجع مثل الشيفرة تماما.

الطبقة الثالثة: الشخصية. مسارات الجهاز، والتفضيلات الخاصة، وبيانات الاعتماد، والذاكرة المحلية لكل مساعد. مستثناة من Git، لا تودع ولا تشارك أبدا.

الفصل مهم لأن الطبقات الثلاث تختلف في معدل التغير وفي مستوى الثقة. خلطها هو تحديدا كيف تتقادم ملفات التعليمات، وكيف تنتهي الأسرار داخل تاريخ Git.

ملاحظة أخيرة قبل التطبيق: الذاكرة المشتركة تخدم البشر بقدر ما تخدم الوكلاء. المطور الجديد يرث ذكاء المشروع المتراكم بقراءة مجلد صغير واحد، بدل تجميع المعرفة الشفهية محادثة بعد محادثة.

                        repository
   +--------------------------------------------------+
   |                                                  |
   |   AGENTS.md   rules + the session contract       |
   |       ^                                          |
   |       |  one-line shims (CLAUDE.md, ...)         |
   |                                                  |
   |   .ai/        evolving shared memory             |
   |               STATE.md, decisions/, lessons...   |
   |                                                  |
   |   src/        the code itself                    |
   |                                                  |
   +--------------------------------------------------+
        ^                 ^                 ^
        |                 |                 |
   Claude Code         Cursor            Codex
        |                 |                 |
   every agent reads at session start,
   writes back before session end

التطبيق خطوة بخطوة

الخطوة 1: أنشئ AGENTS.md

انقل تعليمات الوكيل الحالية لديك، أيا كان الملف الذي تعيش فيه اليوم، إلى ملف AGENTS.md في جذر المستودع. أبقه تحت بضع مئات من الأسطر: ما هو المشروع، وكيف يبنى ويختبر، والأعراف غير القابلة للتفاوض، وعقد الجلسة من الخطوة الخامسة. في المستودع الموحد، يدعم المعيار ملفات AGENTS.md متداخلة؛ الأقرب يفوز، فتستطيع المشاريع الفرعية أن تحمل خصوصياتها.

الخطوة 2: اربط كل أداة به

الأدوات التي تقرأ AGENTS.md أصلا لا تحتاج شيئا. أما البقية فأنشئ لها وسيطا لا نسخة:

# CLAUDE.md (entire file)
@AGENTS.md

All project instructions live in AGENTS.md, the cross-tool
canonical file. Do not add instructions here.

القاعدة هي مصدر حقيقة واحد مع مؤشرات رفيعة، لا ملفات متوازية أبدا. ملفا تعليمات ينحرفان عن بعضهما أسوأ من ملف واحد ناقص.

الخطوة 3: جهز هيكل مجلد ‎.ai/‎

.ai/
  STATE.md         <- THE handoff. Current state, in-flight work,
                      next steps, open questions. Rewritten at the
                      end of every session, never appended.
                      Capped at ~100 lines.
  INDEX.md         <- one line per file below
  architecture.md  <- how the system hangs together, and WHY
  conventions.md   <- evolving patterns not yet stable enough
                      for AGENTS.md
  known-issues.md  <- live landmines, each entry dated
  lessons.md       <- failures already paid for
  decisions/
    ADR-001-....md <- one decision per file: context, decision,
    ADR-002-....md    consequences, rejected alternatives.
                      Immutable once accepted; superseded,
                      never edited.

قاوم الرغبة في إضافة ملفات أخرى. الملفات المتداخلة التي تحمل الحقيقة نفسها في مكانين تعني انحرافا مضمونا. إذا كان بإمكان ملفين أن يحملا حقيقة واحدة، فلديك ملف زائد.

الخطوة 4: ابذر المحتوى، ولا تطلقه فارغا أبدا

قاعدة المعرفة الفارغة تعلم الفريق أن يتجاهلها. اقض أول نصف يوم في ترقية معرفة موجودة سلفا: شرح البنية الذي تعيد كتابته كل مرة، والقرار الذي دافعت عنه ثلاث مرات، وتقارير ما بعد الأعطال، والألغام التي يتجنبها الجميع. اطلب من مساعدك أن يصوغ مسودة المحتوى الأولي من سجل محادثاتك، ثم اختصره بيدك. نظف أثناء العمل؛ الخطوة السابعة من قائمة البدء تغطي ما يجب ألا يدرج أبدا.

الخطوة 5: اكتب عقد الجلسة داخل AGENTS.md

ثلاث نقاط آمرة. وثائق السياسات الطويلة يتجاهلها كل وكيل؛ العقود القصيرة تتبع.

1. بداية الجلسة: اقرأ .ai/STATE.md ثم .ai/INDEX.md. لا تفتح بقية الملفات إلا عند الحاجة. لا تحمل المجلد كله في السياق أبدا.
2. أثناء العمل: حين تتخذ قرارا أو تصطدم بلغم، حدث الملف المقابل في .ai/ ضمن الفرع نفسه الذي يحمل تغيير الشيفرة. القرارات تصبح ملف ADR جديدا.
3. نهاية الجلسة: أعد كتابة STATE.md: ما أنجز، وما هو قيد التنفيذ، وما التالي، والمخاطر، والأسئلة المفتوحة. خمس دقائق، لا مقالا.

أتمت البداية حيثما تسمح أدواتك. يدعم Claude Code مثلا خطافات الجلسة، فيمكن حقن STATE.md في كل جلسة تلقائيا:

#!/bin/bash
# session-start hook: surface the shared memory
STATE="$PROJECT_DIR/.ai/STATE.md"
if [ -f "$STATE" ]; then
  echo "-- Shared project memory: .ai/STATE.md --"
  cat "$STATE"
  echo "-- Full index: .ai/INDEX.md. Rewrite STATE.md before finishing. --"
fi

أما الأدوات التي لا تملك خطافات فتعتمد على التعليمة داخل AGENTS.md نفسه، وهي تحمله في كل جلسة على أي حال.

الخطوة 6: اجعل المراجعة تفرض ذلك

أضف خانة اختيار واحدة إلى قالب طلبات الدمج لديك:

- [ ] .ai/ updated (STATE.md / ADR / known-issues) or N/A

يتعامل المراجعون مع ملف STATE.md متقادم كما يتعاملون مع اختبار فاشل. وإذا كنت تشغل مراجعا آليا لطلبات الدمج، أضف AGENTS.md و .ai/** إلى المسارات التي يراقبها، وتحقق من الملف الذي يقرؤه ليفهم سياق المشروع. أثناء انتقالي أنا، نبه المراجع الآلي إلى أنه كان يقرأ ملف التعليمات القديم، وهو الملف الذي كان الوسيط الجديد قد اختصره للتو إلى سبعة أسطر. سطر واحد مغفل كان سيضعف كل مراجعة قادمة بصمت. الذاكرة المشتركة أثر من الدرجة الأولى؛ والذاكرة الخاطئة تستحق التدقيق نفسه الذي تستحقه الشيفرة الخاطئة.

قواعد التشغيل التي تبقيها موثوقة

• كل ادعاء مؤرخ. أي شيء يستشهد بالشيفرة يحمل تحذيرا ضمنيا: هذه ملاحظة في لحظة بعينها، تحقق منها قبل الاعتماد عليها.
• الحذف أفضل من التحديث، والتحديث أفضل من الإضافة. المشكلات المحلولة تحذف، لا توسم بأنها أصلحت وتبقى. وملف STATE.md يعاد كتابته، ولا ينمو.
• تغييرات الذاكرة ترافق طلب دمج الشيفرة. وتنال المراجعة نفسها، لأن مدخل ذاكرة خاطئا خلل يصيب كل جلسة قادمة لكل مطور.
• حدود الحجم تفرض التشذيب: ملف STATE.md تحت 100 سطر تقريبا، وملفات المواضيع تحت 150، والمجلد كله تحت 15 ملفا. بلوغ الحد علامة على أن النظام يعمل، لا أنه يفشل.
• موضوع واحد لكل ملف. تبقى تعارضات الدمج نادرة وتافهة، حتى مع عمل عدة أشخاص بالتوازي.

ما لا يدخل الذاكرة المشتركة أبدا

• الأسرار والمفاتيح والتوكنات وبيانات الاعتماد. بلا استثناءات، بما في ذلك أمثلة "لمرة واحدة فقط". أضف فحصا في التكامل المستمر لأي نص يشبه المفتاح إن استطعت.
• البيانات الشخصية للمستخدمين أو العملاء، بأي صورة، بما فيها الأمثلة التي تبدو مجهولة الهوية.
• أي شيء يمكن اشتقاقه من الشيفرة أو تاريخ Git. تاريخ التنفيذ مكانه رسائل الإيداع ووصف طلبات الدمج. الذاكرة تحمل "لماذا"، لا نسخة مكررة من "ماذا".
• التفضيلات الشخصية ومسارات الأجهزة. هذه الطبقة الثالثة، مستثناة من Git.
• نصوص المحادثات الخام. ملخصات فقط. السجلات تتقادم، ولا أحد يشذبها.

أنماط الفشل الشائعة وعلاجها

متى تنتقل إلى خدمة ذاكرة

اكتب شرط الترقية مسبقا كي لا يتخذ القرار في لحظة إحباط: أكثر من خمسة مطورين تقريبا، أو اليوم الذي يتوقف فيه البحث النصي عبر خمسة عشر ملف markdown عن إيجاد الأشياء. عندها تستحق خدمة ذاكرة عبر MCP، بتضميناتها واسترجاعها الدلالي، بنيتها التحتية، وتصبح ملفاتك المودعة بذرتها الأولى بدل أن تكون جهدا ضائعا.

وحتى ذلك اليوم، العقل المشترك مجلد من ملفات markdown، يراجع مثل الشيفرة، ويوزع عبر Git. الحيلة المملة نفسها التي أصلحت البيئات قبل عقد: أودع العقد، لا الآلة.

قائمة البدء السريع

1. أنشئ AGENTS.md في الجذر: نظرة عامة على المشروع، وأوامر البناء والاختبار، والأعراف، وعقد الجلسة.
2. اربط الأدوات غير الأصلية بوسطاء استيراد من سطر واحد. مصدر حقيقة واحد ومؤشرات رفيعة.
3. جهز .ai/: STATE.md و INDEX.md و architecture.md و conventions.md و known-issues.md و lessons.md و decisions/.
4. ابذره من المعرفة الموجودة. لا تطلقه فارغا أبدا.
5. أضف عقد الجلسة ذا النقاط الثلاث إلى AGENTS.md؛ وأتمت بداية الجلسة حيثما تدعم أداتك الخطافات.
6. أضف خانة .ai/ updated or N/A إلى قالب طلبات الدمج؛ ووجه أي مراجع آلي إلى AGENTS.md و .ai/**.
7. افحص بحثا عن الأسرار والبيانات الشخصية قبل أول إيداع، ومع كل تغيير في الذاكرة بعده.
8. اكتب شرط التوسع، ثم توقف عن التفكير في خدمات الذاكرة حتى يتحقق.

علمنا Git أن نؤرشف نسخ الشيفرة.
وقد يعلمنا الذكاء الاصطناعي أن نؤرشف نسخ المعرفة الهندسية.

مراجع مفيدة: مواصفة AGENTS.md وقائمة الأدوات الداعمة، ومنهجية بنك الذاكرة، ونقاش AGENTS.md في Claude Code حيث يوثق جسر الاستيراد.