يجب أن يظل APC آمناً عند النسخ، ويجب أن يظل APX محلياً على الجهاز
حدد مكان البيانات من خلال طرح سؤال واحد.
هل ستظل هذه البيانات صالحة بعد إجراء عملية نسخ (clone) جديدة على جهاز آخر؟
إذا كانت الإجابة نعم، ضعها في APC. إذا كانت لا، ضعها في APX.
هذه القاعدة تحافظ على نزاهة بنيتك البرمجية (stack). يظل APC قابلاً للنقل، بينما يظل APX مفيداً على الجهاز الذي يقوم بالعمل. عندما تتداخل هذه الطبقات، يصبح من الصعب مشاركة المشاريع وصعوبة مراجعتها.
APC هو عقد المشروع (project contract). أما APX فهو بيئة التشغيل (runtime).
بيانات APC آمنة عند النسخ. يجب أن يتمكن مطور آخر أو جهاز آخر من قراءتها فوراً بعد عملية git checkout. كما يجب أن تكون قابلة للمراجعة في git.
أمثلة جيدة لـ APC:
• AGENTS.md لعقود المستودع (repo contracts)
• .apc/project.json لهوية المشروع
• .apc/agents/ لأدوار الوكلاء (agent roles)
• .apc/skills/ للمهارات القابلة لإعادة الاستخدام
• .apc/mcps.json للتلميحات المشتركة
بيانات APX محلية على الجهاز. تبقى هذه البيانات على الجهاز أو يتم إعادة بنائها هناك. إنها حالة التنفيذ (execution state)، وليست سياقاً قابلاً للنقل.
أمثلة جيدة لـ APX:
• إعدادات وقت التشغيل (Runtime config) في ~/.apx/config.json
• أوضاع الأذونات المحلية
• الجلسات وسجلات الرسائل
• التخزين المؤقت المحلي (Local caches)
• الأسرار الخاصة بكل جهاز (Per-machine secrets)
لا ينبغي للمستودع أن يفرض الإعدادات المحلية لشخص ما على الجميع.
عندما يظل APC آمناً عند النسخ، يمكنك مراجعة هيكل المشروع دون ملفات مخفية. يمكنك إجراء مقارنة (diff) للتعليمات بدلاً من مطاردة الآثار الجانبية (side effects).
عندما يظل APX محلياً على الجهاز، تتكيف بيئة التشغيل دون تغيير المشروع. قد يستخدم جهاز ما وضع أذونات مختلفاً، بينما يحتفظ جهاز آخر بسجل تاريخ أطول، ومع ذلك يظل عقد المشروع كما هو.
قبل إضافة ملف جديد، اطرح هذه الأسئلة الثلاثة:
- هل تحتاج كل أداة متوافقة إلى قراءة هذا؟ ضعه في APC.
- هل يصف المشروع بدلاً من وصف الجهاز؟ ضعه في APC.
- هل يعتمد على بيانات اعتماد محلية أو تنفيذ حديث؟ ضعه في APX.
أمثلة: • دور وكيل جديد؟ APC. • رمز (token) بوت تلغرام؟ APX. • ملاحظة حول قواعد مراجعة المشروع؟ APC. • سجل لآخر محادثة؟ APX.
يحمل APC ما ينجو من عملية النسخ. ويحمل APX ما يهم فقط على الجهاز الحالي. هذه القاعدة البسيطة تحافظ على استقرار النظام.
المصدر: https://dev.to/agentprojectcontext/apc-should-stay-clone-safe-apx-should-stay-machine-local-59n9
مجتمع تعليمي اختياري: https://t.me/GyaanSetuAi