APC Should Stay Clone-Safe, APX Should Stay Machine-Local

החליטו לאן הנתונים שייכים על ידי שאילת שאלה אחת.

האם הנתונים האלו ישרדו שכפול (clone) חדש במכונה אחרת?

אם כן, שימו אותם ב-APC. אם לא, שימו אותם ב-APX.

הכלל הזה שומר על ה-stack שלכם אמין. APC נשאר נייד (portable). APX נשאר שימושי במכונה שמריצה את העבודה. כששכבות אלו מתערבבות, קשה לשתף פרויקטים וקשה לבצע להם ביקורת (audit).

APC הוא חוזה הפרויקט. APX הוא ה-runtime.

נתוני APC הם Clone-Safe. מפתח אחר או מכונה אחרת צריכים להיות מסוגלים לקרוא אותם מיד לאחר git checkout. הם חייבים להיות ניתנים לבדיקה ב-git.

דוגמאות טובות ל-APC: • AGENTS.md עבור חוזי מאגר (repo contracts) • .apc/project.json עבור זהות הפרויקט • .apc/agents/ עבור תפקידי סוכנים (agent roles) • .apc/skills/ עבור כישורים ניתנים לשימוש חוזר (reusable skills) • .apc/mcps.json עבור רמזים משותפים (shared hints)

נתוני APX הם Machine-Local. הנתונים הללו נשארים במכונה או נבנים מחדש בה. זהו מצב הרצה (execution state), ולא הקשר (context) נייד.

דוגמאות טובות ל-APX: • Runtime config ב-~/.apx/config.json • מצבי הרשאה מקומיים (Local permission modes) • סשנים (sessions) ויומני הודעות (message logs) • מטמון (caches) מקומיים • סודות (secrets) ספציפיים למכונה

מאגר (repository) לא צריך לכפות את ההגדרות המקומיות (local setup) של אדם אחד על כולם.

כש-APC נשאר Clone-Safe, ניתן לבחון את מבנה הפרויקט ללא קבצים נסתרים. ניתן לבצע diff להוראות במקום לרדוף אחרי תופעות לוואי (side effects).

כש-APX נשאר Machine-Local, ה-runtime מסתגל מבלי לשנות את הפרויקט. מכונה אחת משתמשת במצב הרשאה שונה, בעוד אחרת שומרת היסטוריה ארוכה יותר. חוזה הפרויקט נשאר זהה.

לפני שאתם מוסיפים קובץ חדש, שאלו את שלוש השאלות הללו:

  1. האם כל כלי תואם צריך לקרוא את זה? שימו ב-APC.
  2. האם זה מתאר את הפרויקט במקום את המכונה? שימו ב-APC.
  3. האם זה תלוי בפרטי גישה (credentials) מקומיים או בהרצה אחרונה? שימו ב-APX.

דוגמאות: • תפקיד סוכן חדש? APC. • טוקן (token) של בוט טלגרם? APX. • הערה לגבי כללי סקירת הפרויקט? APC. • יומן (log) של השיחה האחרונה? 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