كيف تبني حزام تطوير (harness) للتطوير بمساعدة الذكاء الاصطناعي: قابلية الصيانة والأمان والتنقل بين المساعدين

يكثر الحديث عن النموذج الذي ينبغي اختياره وعن طريقة كتابة موجّه (prompt) جيد. لكن الفارق في الميدان لا يُحسم هنا. فريقان يستخدمان النموذج نفسه يحصلان على نتائج متباينة جداً بحسب حالة المشروع الذي يسلّمانه له: توثيق معماري محدَّث أو غائب، واختبارات موثوقة أو معدومة، وأوامر بناء قابلة للتكرار أو يعرفها شخص واحد فقط، وأسرار محمية أو متروكة في ملف .env يستطيع أي أداة قراءته.

يقترح هذا المقال منهجاً لبناء هذه البيئة: حزام تطوير (harness). وهو موجّه إلى المطورين ذوي الخبرة، وقادة الفرق التقنية (Tech Leads)، والمديرين التقنيين (CTO)، ومسؤولي الهندسة الذين يريدون أن يظل التطوير بمساعدة الذكاء الاصطناعي قابلاً للصيانة، وتعاونياً، وآمناً، ومستقلاً عن أي مزوّد.

توضيح بشأن طبيعة المعلومات. أميّز بين ثلاثة مستويات، أشير إليها في النص:

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

1. فهم حزام التطوير

تعريف عملي

في سياق وكلاء التطوير (agents)، أسمّي harness كل ما يحيط بنموذج اللغة ليجعله مفيداً وقابلاً للتحكم والتكرار: التعليمات، والأدوات، والصلاحيات، والاختبارات، والإجراءات، وآليات التحقق. ليس للمصطلح تعريف معياري: إنه استعارة (الحزام الذي يجهّز ويوجّه)، ويقترح كتّاب آخرون صيغاً مختلفة منه. رأي: هذا التعريف الواسع مفيد لأنه يجبرنا على النظر إلى ما وراء الموجّه.

أربع طبقات ينبغي ألا تُخلط

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

لماذا لا يعوّض النموذج الجيد مشروعاً سيئ البنية

النموذج القوي يستدل أفضل، لكنه لا يستطيع تخمين ما لم يُكتب في أي مكان: سبب اعتماد اتفاقية معينة، أو الاعتمادية الداخلية التي لا يجوز المساس بها، أو الاختبار غير المستقر منذ ستة أشهر. في مشروع بلا اختبارات، لا يملك الوكيل أي وسيلة للتحقق من عمله: يقترح شيفرة تبدو معقولة، ويقع التحقق على المراجعة البشرية التي تصبح عنق الزجاجة. وفي المقابل، المشروع الذي يُنفَّذ فيه scripts/test.sh في دقيقتين ويفشل بوضوح يمنح الوكيل حلقة تغذية راجعة يستطيع استثمارها بمفرده.

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

2. تنظيم سياق المشروع

المبدأ: مصدر واحد للحقيقة، وقرّاء متعددون

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

العناصر المفيدة، مرتبة تقريباً بحسب مردودها:

• ملف README قصير: ما غاية المشروع، وكيف يُثبَّت، وكيف تُشغَّل الاختبارات.
• توثيق البنية المعمارية: المكوّنات ومسؤولياتها، وتدفقات البيانات، والقيود. مخطط وصفحتان خير من ثلاثين صفحة متقادمة.
• سجلات القرارات المعمارية (ADR): وثيقة قصيرة لكل قرار (السياق، الخيارات، الاختيار، العواقب). وهي ما يمنع إعادة النقاش بلا نهاية، ويمنع أن يأتي وكيل ليصحّح قراراً متعمَّداً.
• اتفاقيات الشيفرة: التسمية، وبنية الوحدات، ومعالجة الأخطاء، والتسجيل. والأفضل أن يتحقق منها linter بدل الاكتفاء بوصفها.
• بنية المجلدات: ما يوضع أين، مع المناطق التي لا يجوز تعديلها (الشيفرة المولَّدة، والاعتماديات المنسوخة).
• إجراءات البناء والاختبار والنشر: في صورة سكربتات خاضعة لإدارة الإصدارات (scripts/)، لا فقرات تُنسخ.
• إدارة الاعتماديات والإصدارات: ملفات القفل، وسياسة التحديث، وإصدارات بيئة التشغيل المطلوبة.

إبقاء التعليمات قصيرة والإحالة إلى الباقي

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

يتكرر عيبان:

1. ملف تعليمات تحوّل إلى سلة مهملات: بدأ بقواعد قليلة، ثم أضيف إليه سجل قرارات، وحالة تقدم، وملاحظات ترحيل. ما هو صحيح في لحظة معينة (كحالة ترحيل جارٍ مثلاً) لا مكان له في سياق دائم: يتقادم، ويقرؤه النموذج على أنه حقيقة.
2. تعدد مصادر الحقيقة: المعلومة نفسها منسوخة في أماكن عدة، وتتباعد مع الوقت. وحين تتناقض وثيقتان، يختار الوكيل إحداهما دون أن يعلم أحد.

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

الحذر من التوثيق الذي يولّده الذكاء الاصطناعي

كتابة التوثيق بواسطة مساعد أمر مغرٍ، وهو مفيد غالباً كمسوّدة أولى. الخطر هو الحلقة المغلقة: وكيل يقرأ توثيقاً أنتجه وكيل آخر دون تحقق، ويعامله كحقيقة ثابتة. ممارسة: ضع علامة على حالة ما هو مولَّد («لم يُعَد التحقق منه»)، واجعل إنساناً يراجع ما يُتخذ مرجعاً، وفضّل الوثائق القصيرة القابلة للتحقق والمرتبطة بمالك.

3. قابلية الصيانة والعمل التعاوني

اتفاقيات مشتركة للبشر والوكلاء

الهدف أن يشبه أي تعديل بقية الشيفرة، سواء كتبه شخص أم وكيل. ويتحقق ذلك باتفاقيات صريحة، وقابلة للتحقق الآلي قبل كل شيء: أداة تنسيق، وlinter، وفحص أنواع، واختبارات. القاعدة المكتوبة التي لا يراقبها شيء مجرد اقتراح. أما القاعدة التي يفرضها CI فهي حقيقة واقعة.

ضبط التعديلات الآلية

يميل الوكلاء إلى الإفراط: إعادة تنسيق ملف كامل، وإعادة تسمية عَرَضاً، و«تحسين» شيفرة مجاورة. وينتج عن ذلك فروق (diff) يصعب مراجعتها وتعارضات في الدمج. وهذه بعض الممارسات التي تحدّ من هذا الانحراف:

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

نقطة تحقق واحدة، خاضعة لإدارة الإصدارات، يستدعيها CI والوكلاء بالطريقة نفسها، تجنّب التباين بين «ما يفعله الوكيل محلياً» و«ما يتحقق منه CI»:

#!/usr/bin/env sh
# scripts/check.sh : التحقق نفسه للبشر والوكلاء وCI
set -eu
scripts/lint.sh          # التنسيق، قواعد الأسلوب، الأنواع
scripts/test.sh          # اختبارات الوحدة والتكامل
scripts/scan-secrets.sh  # كشف الأسرار (الأداة حسب اختيارك)

Git والمراجعات والاختبارات كشبكة أمان

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

ولتفادي التعارض بين التعديلات البشرية والمولَّدة، تنطبق القواعد نفسها المعتمدة في الفرق: فروع قصيرة العمر، وعمليات rebase أو دمج متكررة، وملكية واضحة لمناطق الشيفرة، وعدم ترك جلسة وكيل طويلة معزولة تعمل على ملفات يعدّلها آخرون.

ضمان الاستمرارية حين يتسلّم العمل شخص آخر

لا يملك الوكيل ذاكرة موثوقة من جلسة إلى أخرى، وقد يستأنف مطور عملاً بدأه غيره. وفي الحالتين، ما يتيح الاستئناف مكتوب: وصف المهمة، وحالة التقدم، والقرارات المتخذة، وما تبقى. ممارسة: ملف متابعة قصير لكل مهمة طويلة (في طلب الدمج أو في التذكرة، لا في محادثة)، مع الأوامر التي تعيد إنتاج الحالة الراهنة. المحادثة ليست توثيقاً: القرارات الدائمة يجب أن تستقر في المستودع أو في أداة التذاكر.

4. الأمان وحماية البيانات الحساسة

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

الأسرار

• لا تضع أي سر في موجّه أو ملف تعليمات أو مستودع. يشمل ذلك كلمات المرور، والرموز (tokens)، ومفاتيح API، والشهادات، ومحتوى ملفات .env. ما يُرسل إلى نموذج خارجي يخرج من نطاقك؛ وما يُودَع في commit يبقى في السجل التاريخي.
• أدر الأسرار خارج المستودع: مدير أسرار، أو متغيرات يحقنها CI أو بيئة التشغيل، وملفات .env.example بلا قيم حقيقية في المستودع.
• لا تترك على جهاز العمل إلا ما تحتاجه المهمة. جهاز تطوير يحوي ملفات بيئة الإنتاج يمنح كل أداة تعمل عليه وصولاً إلى الإنتاج.
• أضف فحصاً لكشف الأسرار في CI، وقبل الـ commit إن أمكن.

موثّق: يتيح Claude Code منع قراءة مسارات محددة عبر قواعد رفض في ملفات إعداداته (مثل Read(./.env)). ويوضح التوثيق أن ملفاً من نوع .claudeignore لا أثر له، وأن قواعد الرفض هذه لا تغني عن عزل على مستوى نظام التشغيل، لأنها لا تغطي كل وسائل الوصول إلى ملف (برنامج يطلقه shell مثلاً). ممارسة: عامل قواعد الأداة كطبقة أولى لا كضمان.

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

{
  "permissions": {
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)"
    ]
  }
}

الحد الأدنى من الصلاحيات

ممارسة: طبّق مبدأ أقل الامتيازات على الوكلاء كما تطبقه على أي حساب خدمة.

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

موثّق: يقيّم Claude Code قواعد الرفض وطلب التأكيد أياً كانت استجابة الـ hook، ويستطيع الـ hook تشديد القواعد لكنه لا يستطيع رفع رفض. وتتيح الـ hooks (قبل تنفيذ أداة مثلاً) إضافة ضوابط مبرمجة. وتتوفر في أدوات أخرى آليات مماثلة بأشكال مختلفة: اقرأ توثيقها ولا تفترض تكافؤها.

الاعتماد البشري للعمليات الحساسة

رأي: حدّد كتابةً قائمة العمليات التي تتطلب اعتماداً بشرياً صريحاً، واجعل آلية تقنية تفرضها (طلب تأكيد، أو صلاحية مرفوضة افتراضياً)، لا مجرد جملة في ملف تعليمات. ومثال نموذجي وشائع: أمر نشر في الإنتاج موجود في المشروع ويستطيع الوكيل تشغيله دون تأكيد لأن أحداً لم يفكر في منعه.

MCP والإضافات والأدوات الخارجية

تمنح خوادم MCP والإضافات الوكيل قدرات جديدة: الوصول إلى قواعد البيانات وواجهات API والمتصفحات. وكل منها يوسّع سطح الهجوم.

• عامل خادم MCP كأنه شيفرة تنفّذها بصلاحيات المستخدم: تحقق من المصدر، والصلاحيات المطلوبة، والصيانة.
• ضع قائمة الخوادم المسموح بها تحت إدارة الإصدارات للمشروع، وتجنّب الإضافات الشخصية المفروضة ضمنياً على الزملاء.
• ضع حقنَ الموجّه (prompt injection) في حسبانك: وكيل يقرأ صفحة ويب أو تذكرة أو ملفاً من طرف ثالث قد يصادف فيها تعليمات خبيثة. وكلما قلّت صلاحياته قلّ خطر هذه التعليمات.

ضمانات البنية التحتية والضمانات التصريحية

هذا هو التمييز الأهم في هذا القسم. ضمان البنية التحتية يفرضه نظام لا يتحكم فيه النموذج: حساب بلا صلاحية كتابة على الإنتاج، أو شبكة تحجب الاتصالات الصادرة، أو حاوية بلا وصول إلى الأسرار، أو CI يرفض الدمج. أما الضمان التصريحي فهو جملة تطلب من النموذج أن يتصرف على نحو معين: «لا تقرأ ملفات .env أبداً»، «لا تنشر دون موافقة». الثاني مفيد لتوجيه السلوك، لكنه لا يمنع شيئاً: قد يتجاهله النموذج، أو يسيء تفسيره، أو يفقده حين يُقتطع السياق. وفي كل قاعدة يكلّف خرقها غالياً، ابحث عن صيغتها في البنية التحتية.

الشيفرة السرية والأدوات الخارجية

حين يعالج نموذج أو أداة خارجية شيفرة سرية، فالمسألة تعاقدية وتنظيمية أولاً: إلى أين تُرسل البيانات، وكم مدة الاحتفاظ بها، وهل تُستخدم في التدريب، وما مستوى الخدمة (باقة مؤسسية أم استهلاكية)؟ ممارسة: صنّف الشيفرة والبيانات بحسب حساسيتها، وحدّد ما يجوز خروجه من المؤسسة، واستخدم باقات شروطها موثقة ومعتمدة من فريق الأمن لديك، وأبقِ إمكانية النشر المحلي أو الخاص للمحتويات الأكثر حساسية. وبالنسبة للبيانات الخاضعة للتنظيمات، اجعل مسؤولي الامتثال يعتمدون الاستخدام قبل النشر لا بعده.

5. التوافق بين نماذج اللغة والمساعدات

الخطر: مشروع أسير أداة واحدة

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

ما تقوله اتفاقيات الأدوات الرئيسية (أكتوبر 2026)

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

يقدَّم تنسيق AGENTS.md من قبل مروّجيه على أنه تنسيق مفتوح موجّه إلى عدة مساعدات. وتذكر عدة مصادر ثانوية أدوات أخرى تستخدمه (Cursor وAider وZed وJules وDevin)، لكنني لم أتحقق من كل واحد من هذه الادعاءات في توثيق الأداة المعنية: لا تقدّم AGENTS.md على أنه عالمي في توثيقك الداخلي قبل أن تختبر كل أداة تستخدمها. الملف ليس معياراً لمجرد أنه منتشر.

معمارية متعددة الطبقات

هذه هي المعمارية التي أوصي بها، وأقدّمها كمثال توضيحي يحتاج إلى تكييف (رأي):

1. التوثيق المشترك للمشروع، المستقل عن أي أداة: README.md، وdocs/architecture/، وdocs/decisions/. هو مصدر الحقيقة، يقرؤه البشر والوكلاء معاً.
2. التعليمات العامة للوكلاء: ملف قصير (AGENTS.md) يحتوي الأوامر وقواعد العمل والمحظورات وروابط إلى التوثيق.
3. طبقات التكييف لكل أداة: ملفات صغيرة تشير إلى التعليمات المشتركة (مثل CLAUDE.md يستورد AGENTS.md) ولا تحتوي إلا ما يخص الأداة.
4. قواعد وإعدادات خاصة بكل أداة: الصلاحيات، وhooks، وخوادم MCP المسموحة، والأوامر المخصصة، في مجلد الأداة (.claude/ و.codex/ و.gemini/ وغيرها).
5. ضوابط الأمان: كشف الأسرار، وتحليل الاعتماديات، والحد الأدنى من الصلاحيات، والاعتماد البشري للعمليات الحساسة.
6. الاختبارات الآلية وCI: حلقة التحقق المشتركة بين كل الأدوات، والوحيدة التي لا تتوقف على النموذج.
7. إجراءات الاعتماد: مراجعة الشيفرة، ومعايير إنهاء المهمة، وسجل القرارات.

الطبقات 1 و2 و5 و6 و7 قابلة للنقل بحكم بنيتها. أما الطبقتان 3 و4 فهما موضع قبول الاعتماد، لكن مع إبقائه صغيراً وموثقاً وقابلاً للاستبدال.

حدود قابلية النقل

جعل المشروع متوافقاً مع عدة مساعدات لا يضمن نتائج متطابقة. فكل نموذج يفسّر التعليمات نفسها تفسيراً مختلفاً، ويتبع القواعد الطويلة بدرجات متفاوتة من الدقة، ويدير السياق والأدوات بطريقة مختلفة. مساعدان يقرآن AGENTS.md نفسه قد ينتجان عملين مختلفين. ممارسة: تضمن قابلية النقل أن يظل المشروع مفهوماً وقابلاً للاستثمار؛ وحده التقييم على مهامك الخاصة يخبرك بالجودة التي تحصل عليها مع كل أداة (انظر القسم التالي).

ومن الضروري كذلك قبول أن بعض الميزات لا مقابل لها بين الأدوات (hooks، والوكلاء الفرعيون، والأوامر المخصصة، وصيغ الصلاحيات). والأفضل توثيق ذلك بدل محاكاة تكافؤ غير موجود.

6. التوافق مع الإصدارات السابقة والاستدامة

حزام التطوير منتج داخلي: يتطور، وقد تكسر تطوراتُه الاستخدامات القائمة. وهذه بعض الممارسات لتطويره دون مفاجآت:

• ضع التعليمات والإعدادات تحت إدارة الإصدارات في المستودع، مع مراجعة شيفرة وسجل تاريخي، كما تفعل مع الشيفرة. تغيير قاعدة هو تغيير في النظام.
• وثّق الاعتماديات على ميزات خاصة بمزوّد: أي hook، وأي أمر، وأي إصدار أدنى من الأداة. قائمة قصيرة في docs/ تكفي.
• احتفظ بمهام مرجعية: مجموعة صغيرة من المهام الممثِّلة (إصلاح خلل، وإضافة endpoint، وإعادة هيكلة وحدة، وكتابة اختبار) مع النتيجة المتوقعة وطريقة التحقق منها.
• اختبر تحديثات النموذج والأداة على هذه المهام قبل تعميمها على الفريق. قد يغيّر تبدّل الإصدار السلوك دون إنذار.
• تحقق على عيّنة ممثِّلة، لا على مثال واحد مواتٍ: التباين بين عمليات التنفيذ حقيقي.
• أبقِ إجراءات للتراجع: أن تعرف كيف تعود إلى إصدار سابق من الأداة أو من حزام التطوير، وأن تعمل دون مساعد عند الضرورة. حزام التطوير الذي يشلّ غيابُه الفريقَ خطر.
• تجنّب الاعتماديات الضمنية: لا تعوّل على صيغة أو قدرة مملوكة غير موثقة، ولا على إضافات شخصية مثبتة على جهاز واحد. ما ليس في المستودع غير موجود بالنسبة لبقية الفريق.

7. مثال عملي

بنية مشروع توضيحية

البنية التالية مثال للنقاش لا معيار. تبيّن التعليقات ما يندرج في اتفاقية موثقة للأداة وما يبقى بحاجة إلى تحقق في الإصدار الذي تستخدمه.

project/
├── README.md                  # عرض المشروع، التثبيت، تشغيل الاختبارات
├── AGENTS.md                  # تعليمات عامة، قصيرة، مشتركة
├── CLAUDE.md                  # محوّل: يستورد @AGENTS.md (اتفاقية Claude Code)
├── GEMINI.md                  # محوّل اختياري: استيراد @AGENTS.md، يُتحقق منه بحسب الإصدار
├── docs/
│   ├── architecture/          # نظرة عامة، مكوّنات، تدفقات
│   └── decisions/             # ADR: قرار واحد لكل ملف
├── tests/                     # اختبارات آلية
├── scripts/                   # setup.sh وtest.sh وlint.sh: أوامر وحيدة خاضعة للإصدارات
├── .claude/                   # settings.json: صلاحيات، hooks (خاص بـ Claude Code)
├── .codex/                    # إعداد مشروع Codex، يُتحقق منه بحسب الإصدار
└── .gemini/                   # settings.json الخاص بـ Gemini CLI، يُتحقق منه بحسب الإصدار

لا تنشئ مجلد إعدادات «تحسباً»: ملف لا تقرؤه أي أداة يعطي انطباعاً زائفاً بالأمان. ولا تضف طبقة تكييف إلا حين تُستخدم الأداة المقابلة فعلاً في الفريق، واختبر أنها تأخذها في الحسبان (بأن تطلب من الوكيل مثلاً أن يذكر القواعد التي حمّلها).

هيكل AGENTS.md

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

# Instructions pour les agents

## Contexte
Application X. Architecture : voir docs/architecture/overview.md.
Décisions structurantes : voir docs/decisions/.

## Commandes
- Installer : scripts/setup.sh
- Tests : scripts/test.sh (à lancer avant toute demande de fusion)
- Lint et types : scripts/lint.sh

## Règles de travail
- Une tâche, une branche. Pas de modification hors du périmètre demandé.
- Proposer un plan avant de modifier plus de trois fichiers.
- Ne pas reformater les fichiers non concernés.
- Toute décision d'architecture notable donne lieu à un ADR dans docs/decisions/.

## Interdits
- Ne jamais lire, afficher ni écrire de secrets (fichiers .env, clés, jetons).
- Ne jamais lancer de déploiement, de migration de données ou de suppression sans validation humaine.

يعبّر هذا الملف عن قواعد تصريحية. وفي القواعد التي تهم (الأسرار، والنشر)، ضاعفها بآلية تقنية: صلاحيات الأداة، أو حساب بلا صلاحية، أو CI مانع.

دورة عمل من ثماني مراحل

1. فهم السياق. يقرأ الوكيل (أو المطور) README والبنية المعمارية والقرارات ذات الصلة، ويلخّص فهمه. يُصحَّح سوء الفهم في هذه المرحلة، لا داخل الـ diff.
2. تحديد النطاق. المطلوب، وما هو خارج النطاق، ومعايير القبول.
3. وضع خطة. الملفات المعنية، والخطوات، والمخاطر، والاختبارات المراد إضافتها. تُعتمد الخطة قبل كتابة أي شيفرة.
4. تعديل الشيفرة. بخطوات صغيرة، على فرع مخصص، مع تشغيل الاختبارات أولاً بأول.
5. تشغيل الفحوص. الاختبارات، وlint، والأنواع، وكشف الأسرار، عبر سكربتات المشروع. الفشل يُقرأ ولا يُلتفّ عليه.
6. فحص الـ diff. قراءة متأنية لكل ما تغيّر، بما في ذلك ما لم يُطلب. تُزال التغييرات الخارجة عن النطاق.
7. الاعتماد. مراجعة شيفرة يجريها إنسان، مع شرح لما أُنجز ولما لم يُتحقق منه.
8. توثيق القرارات المفيدة. ADR إذا اتُّخذ خيار هيكلي، وتحديث للتوثيق إذا تغيّر سلوك، ومذكرة استئناف إذا استمر العمل.

8. قائمة التحقق من نضج حزام التطوير

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

السياق والتوثيق

• يتيح README تثبيت المشروع واختباره دون مساعدة خارجية.
• البنية المعمارية موثقة ومؤرَّخة، ولها مالك محدد.
• القرارات الهيكلية مدوَّنة (ADR).
• ملف تعليمات الوكلاء قصير ويحيل إلى التوثيق، بلا سجل ولا حالة تقدم.
• كل معلومة مهمة موجودة في مكان واحد فقط.
• التوثيق المولَّد بالذكاء الاصطناعي محدَّد ويراجعه إنسان قبل أن يُعتبر موثوقاً.

الجودة والتعاون

• أمر واحد يشغّل الاختبارات، وآخر يشغّل lint والأنواع.
• ينفّذ CI هذه الفحوص ويمنع الدمج عند الفشل.
• يعمل الوكلاء على فروع مخصصة، ولا يعملون أبداً على الفرع الرئيسي.
• يمرّ كل تعديل عبر مراجعة شيفرة بشرية.
• تُرصد التغييرات الخارجة عن النطاق وتُزال في المراجعة.
• تترك المهمة الطويلة مذكرة استئناف خارج المحادثة.

الأمان

• لا أسرار في المستودعات ولا في الموجّهات ولا في ملفات التعليمات، مع كشف آلي.
• لا يصل الوكلاء إلى أسرار الإنتاج ولا إلى ملفات البيئة المقابلة لها.
• صلاحيات الوكلاء في حدها الأدنى وخاضعة لإدارة الإصدارات.
• العمليات التي لا رجعة فيها (النشر، والحذف، والإرسال) تتطلب اعتماداً بشرياً مفروضاً تقنياً.
• قائمة خوادم MCP والإضافات المسموح بها معروفة ومراجَعة.
• القواعد الحرجة تقوم على ضمان في البنية التحتية، لا على مجرد تعليمة.
• شروط معالجة البيانات من قبل الأدوات الخارجية معتمدة للشيفرة السرية.

قابلية النقل والاستدامة

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

قراءة النتيجة

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

خاتمة

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

المراجع وحالة المعلومات

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

• Claude Code، الذاكرة وملفات التعليمات: https://code.claude.com/docs/en/memory
• Claude Code، الصلاحيات: https://code.claude.com/docs/en/permissions
• OpenAI Codex، التعليمات عبر AGENTS.md: https://developers.openai.com/codex/guides/agents-md
• Gemini CLI، ملفات GEMINI.md: https://geminicli.com/docs/cli/gemini-md
• Cline، التخصيص: https://docs.cline.bot/customization

المعلومات المتعلقة بـ Roo Code، وبقائمة الأدوات المتوافقة مع AGENTS.md، وبأولوية إعدادات Codex مصدرها جزئياً مصادر ثانوية، وقد أشير إليها بوصفها كذلك في النص. التوصيات المعلَّمة بـ رأي شخصية.