.claude/ फ़ोल्डर संरचना का विश्लेषण

• .claude/ फ़ोल्डर Claude Code की मुख्य कंट्रोल डायरेक्टरी है, जो प्रोजेक्ट-विशिष्ट नियम, कमांड, परमिशन और मेमोरी स्टेट को मैनेज करती है
• CLAUDE.md Claude के व्यवहार सिद्धांतों और प्रोजेक्ट नियमों को परिभाषित करने वाली केंद्रीय फ़ाइल है, जो कई लेयर की सेटिंग्स को मर्ज करके लागू करती है
• commands/, skills/, agents/ फ़ोल्डर क्रमशः कस्टम कमांड, ऑटोमेटेड वर्कफ़्लो, और विशेषज्ञ सब-एजेंट बनाते हैं, जिससे सहयोग की दक्षता बढ़ती है
• settings.json कमांड चलाने की अनुमति और फ़ाइल एक्सेस की सीमा नियंत्रित करता है, और settings.local.json से व्यक्तिगत ओवरराइड संभव है
• पूरी संरचना Claude को प्रोजेक्ट की पहचान और नियम बताने वाले प्रोटोकॉल की तरह काम करती है, इसलिए स्पष्ट सेटिंग्स प्रोडक्टिविटी और सहयोग, दोनों को अधिकतम करती हैं

---

.claude/ फ़ोल्डर संरचना और उसके घटक

• .claude/ फ़ोल्डर Claude Code के व्यवहार को नियंत्रित करने वाली मुख्य डायरेक्टरी है, जो प्रोजेक्ट-विशिष्ट नियम, कमांड, परमिशन और मेमोरी स्टेट को मैनेज करती है
• प्रोजेक्ट रूट में मौजूद फ़ोल्डर में टीम-स्तरीय सेटिंग्स शामिल होती हैं और उसे Git में commit किया जाता है
• होम डायरेक्टरी (~/.claude/) का फ़ोल्डर व्यक्तिगत सेटिंग्स और सेशन रिकॉर्ड स्टोर करता है, जिसमें ऑटोमेटिक मेमोरी और निजी कमांड शामिल होते हैं

• CLAUDE.md — Claude के लिए निर्देश पुस्तिका

  • Claude Code सेशन शुरू होने पर सबसे पहले पढ़ी जाने वाली फ़ाइल, जो Claude के व्यवहार सिद्धांतों और प्रोजेक्ट नियमों को परिभाषित करती है
  • प्रोजेक्ट रूट का CLAUDE.md टीम के साझा नियमों के लिए, ~/.claude/CLAUDE.md ग्लोबल व्यक्तिगत नियमों के लिए, और सबफ़ोल्डरों का CLAUDE.md फ़ोल्डर-विशिष्ट नियमों के लिए होता है
  • Claude कई CLAUDE.md फ़ाइलों को मर्ज करके लागू करता है
  • सुझाए गए कंटेंट में build/test कमांड, मुख्य आर्किटेक्चर निर्णय, non-intuitive constraints, naming और error handling rules आदि शामिल हैं
  • इसे 200 पंक्तियों से कम रखना सुझाया जाता है; बहुत लंबी फ़ाइल होने पर Claude की निर्देश-पालन क्षमता घट सकती है

• CLAUDE.local.md — व्यक्तिगत ओवरराइड

  • टीम के साझा नियमों से अलग व्यक्तिगत पसंद को दर्शाने वाली फ़ाइल
  • प्रोजेक्ट रूट में CLAUDE.local.md बनाने पर Claude इसे भी साथ में पढ़ता है
  • यह .gitignore में अपने-आप शामिल होती है, इसलिए repository में commit नहीं होती

• rules/ फ़ोल्डर — मॉड्यूलर नियम प्रबंधन

  • जब CLAUDE.md बड़ा हो जाए, तो उसे .claude/rules/ फ़ोल्डर में बाँटकर मैनेज किया जा सकता है
  • हर नियम फ़ाइल विषय-आधारित रूप से अलग रखी जाती है, जिससे maintenance आसान होता है
    • उदाहरण: code-style.md, testing.md, api-conventions.md, security.md
  • YAML फ्रंटमैटर के paths फ़ील्ड का उपयोग करके सिर्फ़ खास paths पर लागू होने वाले नियम तय किए जा सकते हैं
    • उदाहरण: सिर्फ़ src/api/**/*.ts path पर API नियम लागू करना
  • जिन नियमों में path नहीं दिया गया है, वे हर सेशन में हमेशा लोड होते हैं

• commands/ फ़ोल्डर — कस्टम slash commands

  • .claude/commands/ फ़ोल्डर की हर Markdown फ़ाइल slash command (/) के रूप में रजिस्टर होती है
    • उदाहरण: review.md → /project:review, fix-issue.md → /project:fix-issue
  • ! बैकटिक सिंटैक्स से shell command के execution result को Claude prompt में insert किया जा सकता है
    • उदाहरण: !git diff main...HEAD
  • $ARGUMENTS वेरिएबल का उपयोग करके कमांड चलाते समय arguments पास किए जा सकते हैं
    • उदाहरण: /project:fix-issue 234 → GitHub issue 234 की सामग्री अपने-आप लोड
  • प्रोजेक्ट कमांड टीम के साथ साझा होते हैं, जबकि व्यक्तिगत कमांड ~/.claude/commands/ में स्टोर होकर सभी प्रोजेक्ट्स में उपलब्ध रहते हैं

• skills/ फ़ोल्डर — ऑटो-रन वर्कफ़्लो

  • यह कमांड जैसा ही, लेकिन अपने-आप ट्रिगर होने वाला वर्कफ़्लो है
  • Claude बातचीत का विश्लेषण करके उपयुक्त स्थिति में इसे अपने-आप चलाता है
  • हर skill को सबफ़ोल्डर के SKILL.md में परिभाषित किया जाता है, और YAML फ्रंटमैटर से trigger conditions और allowed tools तय किए जाते हैं
    • उदाहरण: security-review skill सुरक्षा-संबंधित बातचीत में अपने-आप चलती है
  • skill फ़ोल्डर में DETAILED_GUIDE.md जैसी सहायक डॉक्युमेंट या template फ़ाइलें भी शामिल हो सकती हैं
  • व्यक्तिगत skills ~/.claude/skills/ में स्टोर होकर globally उपलब्ध रहती हैं

• agents/ फ़ोल्डर — विशेषज्ञ sub-agents

  • .claude/agents/ फ़ोल्डर में विशिष्ट भूमिका निभाने वाले sub-agent (persona) परिभाषित किए जाते हैं
  • हर agent के पास अलग system prompt, model, और tool access permissions होती हैं
    • उदाहरण: code-reviewer.md, security-auditor.md
  • tools फ़ील्ड से उपलब्ध tools सीमित करके सुरक्षा और role separation लागू की जा सकती है
  • model फ़ील्ड से काम के अनुसार Claude model (जैसे Haiku, Sonnet, Opus) चुना जा सकता है
  • ज़रूरत पड़ने पर Claude उस agent को अलग context में चलाकर सिर्फ़ उसका सारांश रिपोर्ट करता है

• settings.json — परमिशन और प्रोजेक्ट सेटिंग्स

  • .claude/settings.json Claude की कमांड execution permissions और file access scope को परिभाषित करता है
  • $schema फ़ील्ड VS Code जैसी जगहों पर auto-completion और validation सपोर्ट देती है
  • allow सूची auto-approved commands, और deny सूची पूरी तरह ब्लॉक किए गए commands तय करती है
    • उदाहरण: अनुमति — Bash(npm run *), Read, Write, Edit
    • ब्लॉक — Bash(rm -rf *), Bash(curl *), .env फ़ाइल पढ़ना
  • सूची में न होने वाले commands चलाने से पहले यूज़र से पुष्टि माँगी जाती है
  • व्यक्तिगत परमिशन बदलाव .claude/settings.local.json में स्टोर होते हैं और Git में शामिल नहीं होते

• ~/.claude/ फ़ोल्डर — ग्लोबल सेटिंग्स और मेमोरी

  • ~/.claude/CLAUDE.md सभी प्रोजेक्ट्स पर लागू होने वाले व्यक्तिगत निर्देश रखता है
  • ~/.claude/projects/ में प्रोजेक्ट-विशिष्ट सेशन रिकॉर्ड और ऑटोमेटिक मेमोरी स्टोर होती है
    • Claude द्वारा सीखे गए commands, patterns और structural insights बने रहते हैं
    • /memory कमांड से इन्हें देखा और बदला जा सकता है
  • ~/.claude/commands/, ~/.claude/skills/, ~/.claude/agents/ ग्लोबल व्यक्तिगत commands, skills और agents का स्टोरेज हैं

• पूरी संरचना का उदाहरण

  your-project/  
  ├── CLAUDE.md  
  ├── CLAUDE.local.md  
  └── .claude/  
      ├── settings.json  
      ├── settings.local.json  
      ├── commands/  
      ├── rules/  
      ├── skills/  
      └── agents/  
  ~/.claude/  
  ├── CLAUDE.md  
  ├── settings.json  
  ├── commands/  
  ├── skills/  
  ├── agents/  
  └── projects/  
  

• शुरुआती सेटअप के चरण

  • चरण 1: /init कमांड से बेसिक CLAUDE.md बनाएं और केवल मुख्य बातें रखें
  • चरण 2: .claude/settings.json लिखें और execution allow/deny rules परिभाषित करें

  • चरण 3: अक्सर इस्तेमाल होने वाले वर्कफ़्लो (जैसे: कोड रिव्यू, इश्यू सुधार) के अनुसार कमांड जोड़ें

    • चरण 4: अगर CLAUDE.md बड़ा हो जाए, तो उसे .claude/rules/ में बाँट दें
    • चरण 5: ~/.claude/CLAUDE.md में व्यक्तिगत पसंद के नियम जोड़ें

मुख्य इनसाइट्स

• .claude/ फ़ोल्डर Claude को प्रोजेक्ट की पहचान और नियम बताने वाला प्रोटोकॉल है
• CLAUDE.md सबसे महत्वपूर्ण फ़ाइल है, और इसे जितना स्पष्ट परिभाषित किया जाए, Claude की प्रोडक्टिविटी उतनी अधिकतम होती है
• बाकी घटक इसे सपोर्ट करने वाली optimization layers हैं, जिन्हें धीरे-धीरे बढ़ाया जा सकता है
• स्पष्ट सेटिंग्स से Claude के correction requests कम होते हैं और सहयोग अधिक कुशल बनता है

अतिरिक्त चर्चा

• settings.json की deny list मानव उपयोग के लिए सुरक्षित हो सकती है, लेकिन agent mode में Bash access के कारण अतिरिक्त सुरक्षा की ज़रूरत होती है
• OneCLI नेटवर्क स्तर पर credentials tokens को बदलने वाली proxy layer देता है, जिससे secrets के उजागर होने से बचाव होता है
• आगे चलकर agent mode के लिए अलग .claude settings (rules, permissions, skills separation) की ज़रूरत उठाई गई है
• नवीनतम दस्तावेज़ों के अनुसार commands और skills का एकीकरण हो चुका है, इसलिए .claude/commands/deploy.md और .claude/skills/deploy/SKILL.md दोनों समान रूप से /deploy कमांड बनाते हैं, जबकि skills अतिरिक्त सुविधाएँ (सहायक फ़ाइलें, auto trigger आदि) सपोर्ट करती हैं

[GN⁺]

Hacker News टिप्पणियाँ

• AI एजेंट toolkit बनाना कुछ वैसा लगता है जैसे परफेक्ट productivity setup खोज रहे हों
  ब्लॉग पोस्ट और YouTube देखकर लोग रूटीन बनाते हैं, लेकिन आखिर में साधारण to-do list के साथ लगातार काम करने वाला व्यक्ति ज़्यादा आगे निकल जाता है
  मेरे अनुभव में Plain Claude से plan बनवाना, review करवाना और फिर execute करवाना अभी भी सबसे अच्छा काम करता है

  • बड़े codebase या distributed system में कहानी अलग होती है
    एजेंट data पाइप करता है, requests बनाता है, system को trace करता है और code अपडेट करता है — ये technical skills development efficiency को बहुत बढ़ा देते हैं
    1 करोड़ lines के codebase में productivity काफ़ी बढ़ी, और उसमें actual code generation का हिस्सा 5% भी नहीं था
    ज़्यादातर फ़ायदा testing और verification के लिए toolchain जल्दी बनाने की क्षमता से आया
  • बहुत से लोग इस जाल में फँसकर पैसे खर्च कर रहे हैं
    असल में अगर आपको क्या चाहिए यह साफ़ पता हो और आप उसे अच्छी तरह बता सकें, तो AI से भी बहुत काम हो सकता है
    ज़्यादातर लोगों को यह नहीं पता होता। इसलिए उससे plan बनवाने की प्रक्रिया समझ पाने का shortcut बन जाती है
  • मैं PM के रूप में चाहता हूँ कि एजेंट समय बचाए और output का compounding effect दे
    लेकिन हर session में context दोहराना और .md files कॉपी करना अक्षम लगता है
    अभी लक्ष्य यही repetition हटाना है।
    जानना चाहता हूँ कि लोग context जमा करने वाले ‘context bank’ को कैसे manage करते हैं — जैसे “मेरी role, product ownership, latest docs” जैसी बेसिक जानकारियाँ
    documents में duplicate और outdated चीज़ें बहुत हैं, इसलिए पूरे Drive को सीधे connect भी नहीं कर सकता
    सोच रहा हूँ कि अगर दो बार से ज़्यादा वही context दोहराया जाए तो Skill file बनानी चाहिए, या documents इकट्ठा करके एक folder में manage करने चाहिए
  • मेरा अनुभव भी ऐसा ही रहा। काम के दौरान बने artifacts ज़्यादातर फेंक दिए जाते हैं
    over-configuration quality को गिरा देती है और loop problems पैदा करती है
    model लगातार बेहतर हो रहे हैं, इसलिए पहले ज़रूरी रही instructions अब उल्टा performance में बाधा बन सकती हैं
    मैंने यह भी सुना कि Anthropic टीम हर 30 दिन में claude.md reset करती है
  • दूसरी तरफ़, मैं एक ऐसे project पर काम कर रहा हूँ जिसमें local accounting API integrate करनी है, और यह पूरी तरह custom API है जिसे LLM नहीं जानता
    इसलिए मैंने Claude से MCP server बनवाया, और अब वह accounting tasks को automate कर रहा है
    month-end close के बाद Claude से key tasks निकालकर Skill बनवाई, तो वह लगभग junior accountant की तरह काम करने लगा
    custom MCP और Skill सच में बहुत उपयोगी लगे

• ऐसा लगता है कि बहुत से लोग agentic coding शुरू करने से पहले ही एक बहुत बड़ी setup wall खड़ी कर लेते हैं
  लेकिन शुरुआत में खाली .claude और AGENTS.md से शुरू करके खुद इस्तेमाल करना सीखना सही है

  • मेरा तो मानना है कि सिर्फ़ अपने बनाए हुए skills ही इस्तेमाल करने चाहिए
    दूसरों के बनाए skills अंधाधुंध install करने से nondeterminism बढ़ती है और context window भी बर्बाद होती है
    अपवाद के तौर पर मैं सिर्फ़ playwright-cli जैसा external install recommend करूँगा
  • बड़े teams में कुछ तय guardrails (rules) ज़रूरी होते हैं
    उदाहरण के लिए, इस rule की तरह preconditions check करवाएँ तो setup ज़्यादा stable रहता है
    security team को भी शायद ऐसा approach पसंद आए
    मैंने भी rules define करके Claude को GPG signature के बिना commit न करने के लिए सेट किया है
    हालाँकि ऐसे rules स्थिर नहीं होते, इन्हें लगातार evolve होना चाहिए
  • यह लेख कोई विशाल setup थोपने के लिए नहीं है
    बल्कि यह बार-बार छोटे से शुरू करो और छोटा रखो पर ज़ोर देता है
    beginner भी AGENTS.md में बस कुछ lines जोड़ दें तो AI user intent को बेहतर समझ लेता है
    simple setup से AI malfunction काफ़ी कम हो जाता है
  • अकेले code संभालना और team के साथ shared project संभालना पूरी तरह अलग बात है
    अगर हर developer agentic tools इस्तेमाल करे, तो collaboration का तरीका ही बदल जाता है
  • पहले सिर्फ़ plan mode इस्तेमाल करें, 90% समस्याएँ वहीं हल हो जाती हैं
    model आगे बढ़ने के साथ ऐसी complex setup discussions शायद अगले 1 साल में ज़्यादातर ग़ायब हो जाएँगी

• ~/.claude/projects folder ही वास्तव में दिलचस्प हिस्सा है

• मेरे लिए जितनी कम अनावश्यक settings रहीं, उतने अच्छे results मिले
  लोग documentation को ज़रूरत से ज़्यादा prescribe करते हैं, लेकिन AI एक काबिल मगर तनावग्रस्त वयस्क जैसा है
  उसे बहुत ज़्यादा instructions दें, तो वह उल्टा और मूर्ख हो जाता है

• यह लेख वास्तविक अनुभव से ज़्यादा generated लगता है
  Claude.md छोटा होना चाहिए, बस कुछ links डालना काफ़ी है
  context बढ़ते ही performance गिरती है, इसलिए planning और implementation को अलग रखना चाहिए और हर बार reset करना चाहिए

  • शुरुआत Claude की writing style से इतनी मिलती है कि लगा सीधे Claude से ही पूछ लेना चाहिए था
  • skills और commands के बीच फ़र्क थोड़ा उलझाने वाला है
    यह साफ़ नहीं है कि skills हमेशा context में रहते हैं और commands सिर्फ़ manual invocation पर चलते हैं या नहीं

• अच्छा होता अगर सभी model providers एक standard file set share करते
  तब Claude, Codex, Cursor और Opencode के बीच switch करना आसान होता

  • लेकिन model और harness का combination results पर बहुत असर डालता है
    एक ही prompt पर भी हर model अलग तरह से react करता है, इसलिए prompt tuning model के हिसाब से अलग होनी चाहिए
  • एक agents.md बनाकर Claude.md से उसे reference करा सकते हैं, और folders के बीच symlink (sync) से जोड़ सकते हैं
    यह perfect नहीं है, लेकिन काफ़ी अच्छा काम करता है
  • अभी का समय शुरुआती browser era जैसा है। standardization न होने की वजह से AJAX जैसी innovations आई थीं
    इसलिए आज की यह विविधता उल्टा सकारात्मक भी है
  • मैं फिलहाल इस समस्या के लिए dotagents by Sentry इस्तेमाल कर रहा हूँ
  • मुझे नहीं लगता कि model providers के पास switching आसान बनाने की कोई ख़ास वजह है

• Claude Fast का वैकल्पिक दस्तावेज़ बहुत उपयोगी है
  मुझे समझ नहीं आता कि .claude folder definition से किसी को दिक्कत क्यों होगी
  आप main agent से files सीधे लिखवा सकते हैं, बार-बार update करवा सकते हैं, और self-improving system बना सकते हैं
  अभी .claude खुद को replicate करता है, evaluate करता है और update करता है — यानी मैं code नहीं लिख रहा, बल्कि .claude को code कर रहा हूँ

  • संक्षेप में, CLAUDE.md कोई साधारण document नहीं बल्कि Claude का operating system है
    मतलब ऐसा system बनाना जो behavior define करे, knowledge को skills में delegate करे, और समय के साथ खुद को बेहतर बनाता जाए

• एक कम जानी-पहचानी रुकावट यह है कि अगर Claude से file modify करवा भी लें, तो उसे दोबारा पढ़ने के लिए साफ़-साफ़ न कहें तो बदलाव लागू नहीं होते
  उदाहरण के लिए अगर CLAUDE.md नया लिखा गया है, तो Claude को नए instructions पहचानने के लिए उसे reload करना पड़ेगा

• ~/.claude/plans folder में plan mode चलाने पर बनी plan files सेव होती हैं
  मैं इस directory को अक्सर खोलकर backup या reference के लिए इस्तेमाल करता हूँ

• मैंने setup को global MCP servers और composite agent के इर्द-गिर्द बनाया है
  हर MCP server अपना tool set define करता है, और agent उसके भीतर autonomously काम करता है
  .agent.md बस available tools बताने वाला document है, complex setup की ज़रूरत नहीं
  skills या reusable prompts मुझे कम value वाले लगते हैं
  model पहले से काफ़ी smart हैं, इसलिए असल ज़रूरत orientation की है