APC باید Clone-Safe (ایمن در برابر کلون) بماند، APX باید Machine-Local (مختص به ماشین) بماند
با پرسیدن یک سوال، تصمیم بگیرید که دادهها متعلق به کجا هستند.
آیا این دادهها پس از یک کلون تازه روی یک ماشین دیگر، همچنان معتبر و قابل استفاده باقی میمانند؟
اگر بله، آن را در APC قرار دهید. اگر خیر، آن را در APX قرار دهید.
این قانون باعث شفافیت استک (stack) شما میشود. APC قابل حمل (portable) باقی میماند. APX در ماشینی که کار را اجرا میکند، کاربردی باقی میماند. وقتی این لایهها با هم ترکیب شوند، اشتراکگذاری و بازرسی (audit) پروژهها دشوار میشود.
APC قرارداد پروژه است. APX زمان اجرا (runtime) است.
دادههای APC با کلون کردن ایمن هستند. یک توسعهدهنده یا ماشین دیگر باید بلافاصله پس از یک git checkout بتواند آنها را بخواند. این دادهها باید در git قابل بازبینی باشند.
نمونههای خوب APC:
• AGENTS.md برای قراردادهای مخزن (repo)
• .apc/project.json برای هویت پروژه
• .apc/agents/ برای نقشهای ایجنت
• .apc/skills/ برای مهارتهای قابل استفاده مجدد
• .apc/mcps.json برای راهنماییهای مشترک
دادههای APX مختص به ماشین هستند. این دادهها روی همان ماشین باقی میمانند یا در همانجا بازسازی میشوند. اینها وضعیت اجرا (execution state) هستند، نه یک بافت (context) قابل حمل.
نمونههای خوب APX:
• تنظیمات زمان اجرا در ~/.apx/config.json
• حالتهای دسترسی محلی
• نشستها (sessions) و لاگهای پیام
• کشهای محلی
• اسرار (secrets) مختص به هر ماشین
یک مخزن (repository) نباید تنظیمات محلی یک نفر را به بقیه تحمیل کند.
وقتی APC با کلون کردن ایمن میماند، میتوانید ساختار پروژه را بدون فایلهای پنهان بررسی کنید. میتوانید به جای دنبال کردن اثرات جانبی (side effects)، دستورالعملها را با diff مقایسه کنید.
وقتی APX مختص به ماشین میماند، زمان اجرا بدون تغییر در پروژه، خود را تطبیق میدهد. یک ماشین از حالت دسترسی متفاوتی استفاده میکند، در حالی که ماشین دیگر تاریخچه طولانیتری را نگه میدارد. قرارداد پروژه ثابت میماند.
قبل از اضافه کردن یک فایل جدید، این سه سوال را بپرسید:
۱. آیا هر ابزار سازگاری نیاز به خواندن این دارد؟ آن را در APC قرار دهید. ۲. آیا این فایل به جای ماشین، پروژه را توصیف میکند؟ آن را در APC قرار دهید. ۳. آیا این فایل به اعتبارنامههای (credentials) محلی یا اجرای اخیر وابسته است؟ آن را در APX قرار دهید.
مثالها: • یک نقش جدید برای ایجنت؟ APC. • توکن ربات تلگرام؟ APX. • یادداشتی درباره قوانین بازبینی پروژه؟ APC. • لاگ آخرین گفتگو؟ APX.
APC آنچه را که پس از کلون کردن باقی میماند حمل میکند. APX آنچه را که فقط در ماشین فعلی اهمیت دارد حمل میکند. این قانون ساده باعث منطقی ماندن سیستم میشود.
Source: https://dev.to/agentprojectcontext/apc-should-stay-clone-safe-apx-should-stay-machine-local-59n9
Optional learning community: https://t.me/GyaanSetuAi