फ़ोल्डर का नाम प्रोजेक्ट की पहचान नहीं है

फ़ोल्डर पाथ एक रास्ता है। यह किसी टूल को बताता है कि प्रोजेक्ट अभी कहाँ स्थित है। प्रोजेक्ट की पहचान (identity) इससे अलग होती है।

पहचान को इन सामान्य बदलावों के बावजूद बना रहना चाहिए:

  • डायरेक्टरी का नाम बदलना
  • प्रोजेक्ट को मशीनों के बीच ले जाना
  • रेपो को नए पाथ में क्लोन करना
  • एक ही प्रोजेक्ट के कई चेकआउट का उपयोग करना

यदि पहचान पाथ पर निर्भर करती है, तो ये कार्य जोखिम भरे हो जाते हैं। पाथ काम कर सकता है, लेकिन यह यह साबित करने में विफल रहता है कि प्रोजेक्ट वही है। यह स्टेट (state) को स्टोर करने के लिए एक खराब की (key) बना देता है।

मैं इसे हल करने के लिए APC और APX के साथ एक स्प्लिट डिज़ाइन का उपयोग करता हूँ।

APC प्रोजेक्ट कॉन्ट्रैक्ट को संभालता है। यह रिपॉजिटरी में रहता है। APX रनटाइम स्टेट को संभालता है। यह रिपॉजिटरी के बाहर रहता है।

APC एक स्थिर एंकर (stable anchor) बनाने के लिए विशिष्ट फ़ाइलों का उपयोग करता है:

  • रूट कॉन्ट्रैक्ट के लिए AGENTS.md
  • प्रोजेक्ट मेटाडेटा के लिए .apc/project.json
  • एजेंट डेफिनिशन के लिए .apc/agents/*.md
  • MCP हिंट्स के लिए .apc/mcps.json

.apc/project.json फ़ाइल बहुत छोटी होती है। इसमें एक नाम और एक स्थिर ID होती है। यह एक मार्कर है, कोई बड़ी कॉन्फ़िग फ़ाइल नहीं।

APX एक लाइव चेकआउट को एक टिकाऊ रिकॉर्ड से जोड़ने के लिए इस फ़ाइल का उपयोग करता है। पाथ APX को प्रोजेक्ट खोजने में मदद करते हैं। मेटाडेटा APX को प्रोजेक्ट मिलने के बाद उसे स्थिर रखने में मदद करता है।

यह डिज़ाइन रेपो को साफ़ रखता है। सेशन लॉग और मैसेज हिस्ट्री जैसे रनटाइम डेटा APX स्टोरेज में रहते हैं। वे आपके git इतिहास को गंदा नहीं करते हैं।

जब आप पाथ पर निर्भर होते हैं, तो आपको इन विफलताओं का सामना करना पड़ता है:

  • पाथ बदल जाते हैं
  • स्टेट टूट जाता है
  • टूल गलत अनुमान लगाता है
  • आप निर्माण करने के बजाय नाम डीबग करने में समय बिताते हैं

एक स्थिर पहचान इस शोर (noise) को खत्म कर देती है। यह कोड रिव्यू को आसान बनाती है। आप अपने diffs में आकस्मिक रनटाइम आउटपुट के बजाय प्रोजेक्ट के तथ्य देखते हैं।

सीमा सरल है:

  • AGENTS.md: प्रोजेक्ट क्या अपेक्षा करता है
  • .apc/project.json: प्रोजेक्ट क्या है
  • ~/.apx/: उस पर काम करते समय क्या हुआ

एक प्रोजेक्ट को एक स्थिर एंकर की आवश्यकता होती है। फ़ोल्डर पाथ बहुत अस्थिर (volatile) है। रनटाइम बहुत शोर भरा है। एक रेपो कॉन्ट्रैक्ट और एक मेटाडेटा फ़ाइल सही आकार है।

Source: https://dev.to/tecnomanu/a-folder-name-is-not-a-project-identity-4eca

Optional learning community: https://t.me/GyaanSetuAi