ثلاثة ملفات يحتاجها monorepo بـ Angular قبل أن يكتب الوكيل سطراً

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

1. الملف الذي يجب أن يقرأه

يقرأ كل وكيل ملف تعليمات على مستوى المشروع قبل أن يبدأ العمل، ولكل أداة ملفها الخاص: CLAUDE.md و GEMINI.md و .github/copilot-instructions.md و .cursor/rules/. ومعظمها يقرأ الآن AGENTS.md أيضاً. وتترك فرق كثيرة هذه الملفات فارغة، أو تلصق فيها ملف README، أو تكتب أربع نسخ تتباعد مع الوقت.

اكتب ملفاً واحداً هو AGENTS.md، واجعل كل ملف خاص بأداة سطراً واحداً يحيل إليه. في المستودع التجريبي يتكوّن CLAUDE.md من @AGENTS.md والكتلة التي تضيفها أدوات Nx، ويطلب GEMINI.md من الوكيل أن يقرأ AGENTS.md ويتبعه قبل أي شيء آخر. مصدر واحد للحقيقة، لأي وكيل. أما إضافات كل أداة، مثل الصلاحيات أو الخطافات (hooks)، فتذهب إلى إعدادات تلك الأداة نفسها، أما القواعد فتبقى في مكانها.

لست مضطراً إلى كتابة الجزء الخاص بـ Angular بنفسك، ففريق Angular ينشره: ملف best-practices.md على angular.dev/ai، ومهارات للوكلاء (agent skills) في angular/skills. وفي المستودع التجريبي توجد هذه المهارات في .agents/skills/، وهو مجلد يقرؤه عدة وكلاء، كما رُبطت مهارات Angular و Atlas داخل .claude/skills/ من أجل Claude Code. ولا يحتفظ ملف AGENTS.md لديك إلا بما لا يمكن لفريق Angular أن يعرفه: حدودك، والكود القديم (legacy) لديك، وتعريفك لكلمة «منجَز».

ما يُكتب فيه قصير وملموس، وأغلبه نواهٍ. فالوكيل لا يحتاج إلى رؤيتك المعمارية، بل يحتاج إلى السياج. وهذا مختصر من ملف AGENTS.md في المستودع التجريبي:

# Atlas Bank: قواعد للوكلاء البرمجيين (مقتطف)
 
## البنية
- libs/domain         TypeScript خالص، بلا أي استيراد من Angular
- libs/data-access/*  stores وخدمات؛ يمكنها استيراد domain
- libs/ui             للعرض فقط؛ لا تستورد data-access أبداً
- libs/feature/*      ميزات لها مسارات (routes)؛ يمكنها استيراد ui و data-access و domain
 
## لا تفاوض فيها
- المكوّنات الجديدة standalone وتستخدم signals. لا NgModules جديدة.
- لا تعدّل libs/legacy/** أبداً إلا إذا نصّ ملف المهمة على migrate. غلّفه.
- عبور حدود مكتبة يتطلب رابطاً إلى ADR في طلب الدمج (PR).
 
## قبل أن تقول إنك انتهيت
- npm run lint:arch   يجب أن ينجح
- npm run test        يجب أن ينجح دون تعديل التحققات (assertions)
- لا يتجاوز الـ diff ‏300 سطر، إلا إذا رفع ملف المهمة هذا السقف

كلمة واحدة هنا تستحق سطراً. الـ ADR هو سجل القرار المعماري (architecture decision record)، أي ملاحظة قصيرة مؤرَّخة تشرح سبب وجود حدّ ما. وحين تطلب من الوكيل أن يضع رابطاً إليه، فأنت تطلب منه أن يبرّر العبور، وهو في الغالب عاجز عن ذلك، وهذا بالضبط هو المقصود.

2. الملف الذي يجب أن يجتازه

التعليمات مجرد اقتراحات، أما الأمر الذي يفشل فليس كذلك. والحدود نفسها تصبح قاعدة lint، عبر @nx/enforce-module-boundaries في مساحة عمل Nx، أو عبر Sheriff في مشروع Angular CLI عادي. وهذا من إعدادات ESLint في المستودع التجريبي:

// eslint.config.mjs (مقتطف)
const depConstraints = [
  { sourceTag: 'type:domain', onlyDependOnLibsWithTags: ['type:domain'] },
  { sourceTag: 'type:data-access', onlyDependOnLibsWithTags: ['type:data-access', 'type:domain'] },
  { sourceTag: 'type:ui', onlyDependOnLibsWithTags: ['type:ui', 'type:domain'] },
  { sourceTag: 'type:feature', onlyDependOnLibsWithTags: ['type:feature', 'type:ui', 'type:data-access', 'type:domain'] },
];
// ...
'@nx/enforce-module-boundaries': ['error', { depConstraints }],

الآن يستطيع ملف القواعد أن يقول «شغّل lint:arch قبل أن تنتهي»، والوكيل الذي يشغّله يعيد المحاولة في الغالب حتى ينجح. وهكذا تحوّلت عبارة «من فضلك احترم المعمارية» إلى أمر يفشل.

انقر للتكبير

استيراد من data-access داخل مكوّن ui، فيرفضه البناء قبل أن يضطر مراجع إلى رفضه.

3. الملف الذي يجب أن يبقى داخله

الملف الثالث خاص بكل مهمة، لا بالمستودع كله: الطلب مكتوباً قبل أن يقرأه الوكيل، مع نطاق، وما هو خارج النطاق، وشرط «تكتمل حين». قد يكون تذكرة Jira، أو issue على GitHub بعناوين ثابتة، أو ملف Markdown في docs/tasks/. الشكل لا يهم. المهم جملة واحدة:

النطاق: libs/feature/accounts فقط. تكتمل المهمة حين ينجح lint:arch والاختبارات، ويكون الـ diff أقل من 300 سطر.

سقف الحجم هو الجزء الأكثر تأثيراً. فالوكلاء بارعون في تلبية القيود الصريحة، وسيئون جداً في تخمين القيود الضمنية. وحين تتضمّن المهمة الرقم 300، يفشل diff يتجاوز ألف سطر بكثير في شرط «تكتمل حين» قبل أن يقرأه أحد.

شغّله مرة كل ربع سنة. هذه القائمة هي قائمة الأعمال المؤجلة (backlog) لملف قواعدك.

ما الذي يتغيّر حين توجد الملفات الثلاثة

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

مع بداية الأسبوع

• اكتب AGENTS.md في نحو صفحة واحدة، معظمها «لا ... أبداً». واجعل كل ملف أداة يحيل إليه.
• حوّل قائمة البنية إلى قاعدة lint، وأضف lint:arch إلى شروط «منجَز».
• ضع سقفاً للحجم في المهمة التالية التي تسلّمها إلى وكيل.

تمرين: الوحدة 1 في المستودع التجريبي. ابدأ دون الملفات: git switch track1/m1-start. ثم المهمة نفسها مع الملفات: git switch -c m1/you main. الحل المرجعي: origin/track1/m1-solution. استخدم الوكيل الذي تفضّله.

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

المسار 1، الجزء 2 من السلسلة المجانية المرافقة لورشة سريع وآمن: الذكاء الاصطناعي في قاعدة كود Angular الخاصة بك.