שם תיקייה אינו זהות של פרויקט
נתיב תיקייה הוא מסלול. הוא אומר לכלי היכן הפרויקט נמצא כרגע. זהות של פרויקט היא דבר אחר.
זהות חייבת לשרוד את השינויים הנפוצים הבאים:
- שינוי שם התיקייה
- העברת הפרויקט בין מכונות
- שכפול (cloning) של ה-repo לנתיב חדש
- שימוש במספר checkouts של אותו פרויקט
אם הזהות תלויה בנתיב, פעולות אלו הופכות למסוכנות. הנתיב עשוי לעבוד, אך הוא נכשל בהוכחה שהפרויקט הוא אכן אותו פרויקט. זה הופך אותו למפתח גרוע לאחסון מצב (state).
אני משתמש בעיצוב מפוצל עם APC ו-APX כדי לפתור זאת.
APC מטפל בחוזה הפרויקט (project contract). הוא נמצא בתוך ה-repository. APX מטפל במצב הריצה (runtime state). הוא נמצא מחוץ ל-repository.
APC משתמש בקבצים ספציפיים כדי ליצור עוגן יציב:
- AGENTS.md עבור חוזה השורש
- .apc/project.json עבור מטא-דאטה של הפרויקט
- .apc/agents/*.md עבור הגדרות סוכנים (agents)
- .apc/mcps.json עבור רמזי MCP
הקובץ .apc/project.json הוא זעיר. הוא מכיל שם ו-ID יציב. הוא משמש כסימון (marker), ולא כקובץ קונפיגורציה גדול.
APX משתמש בקובץ זה כדי לחבר checkout חי לרשומה עמידה. נתיבים עוזרים ל-APX למצוא את הפרויקט. המטא-דאטה עוזר ל-APX לשמור על יציבות הפרויקט ברגע שהוא מוצא אותו.
עיצוב זה שומר על ה-repo נקי. נתוני ריצה (runtime data) כמו יומני סשנים (session logs) והיסטוריית הודעות נשארים באחסון של APX. הם אינם מלכלכים את היסטוריית ה-git שלך.
כשאתה מסתמך על נתיבים, אתה נתקל בכשלים הבאים:
- נתיבים משתנים
- המצב (state) נשבר
- הכלי מבצע ניחושים שגויים
- אתה מבלה זמן בפתרון באגים (debugging) בשמות במקום בבנייה
זהות יציבה מסירה את הרע הזה. היא הופכת את סקירות הקוד (code reviews) לקלות יותר. אתה רואה עובדות על הפרויקט ב-diffs שלך במקום פלט ריצה מקרי.
הגבול הוא פשוט:
- AGENTS.md: מה הפרויקט מצפה לו
- .apc/project.json: מה הפרויקט הוא
- ~/.apx/: מה קרה בזמן שעבדו עליו
פרויקט זקוק לעוגן יציב אחד. נתיב התיקייה תנודתי מדי. סביבת הריצה (runtime) רועשת מדי. חוזה repo בתוספת קובץ מטא-דאטה הוא הגודל הנכון.
Source: https://dev.to/tecnomanu/a-folder-name-is-not-a-project-identity-4eca
Optional learning community: https://t.me/GyaanSetuAi