अच्छा Claude.md कैसे लिखें

• LLM state सेव नहीं करने वाला function है, इसलिए CLAUDE.md हर session में Claude को codebase से परिचित कराने वाले मुख्य दस्तावेज़ की तरह काम करता है
• इस फ़ाइल में project का WHAT (structure), WHY (purpose), और HOW (working method) संक्षेप में होना चाहिए; बेवजह बहुत ज़्यादा commands डालने से performance गिर सकती है
• Claude, system message के निर्देशों के अनुसार, CLAUDE.md की सामग्री को कम प्रासंगिक मानकर अनदेखा कर सकता है
• प्रभावी फ़ाइल में केवल छोटी और व्यापक रूप से लागू होने वाली जानकारी होनी चाहिए, और विस्तृत निर्देश अलग दस्तावेज़ों में बाँटकर Progressive Disclosure तरीके से manage करने चाहिए
• CLAUDE.md agent harness का सबसे high-impact point है, इसलिए इसे auto-generate करने के बजाय सावधानी से हाथ से लिखना चाहिए

---

LLM की statelessness और CLAUDE.md की भूमिका

• LLM inference के समय fixed weights का उपयोग करता है और sessions के बीच learning या memory बनाए नहीं रखता
  • इसलिए model को codebase समझाने के लिए सारी जानकारी input tokens के रूप में देनी पड़ती है
• Claude Code जैसे coding agents में memory को explicitly manage करना पड़ता है, और CLAUDE.md एकमात्र ऐसी फ़ाइल है जो हर conversation में अपने-आप शामिल होती है
• इसी वजह से नीचे की तीन बातें अनिवार्य हैं
  1. session शुरू होने पर Claude codebase के बारे में कुछ नहीं जानता
  2. हर session में ज़रूरी जानकारी फिर से देनी पड़ती है
  3. इसके लिए मानक तरीका CLAUDE.md है

codebase onboarding: WHAT, WHY, HOW

• CLAUDE.md Claude को project समझने में मदद करने वाले onboarding document की भूमिका निभाता है
  • WHAT: tech stack, project structure, monorepo configuration आदि के ज़रिए code map देना
  • WHY: हर component के उद्देश्य और कार्य को समझाना
  • HOW: build, test, typecheck जैसी वास्तविक tasks कैसे करनी हैं, यह बताना
• लेकिन हर command को सूचीबद्ध करना अप्रभावी है, इसलिए केवल न्यूनतम आवश्यक जानकारी ही शामिल करनी चाहिए

Claude CLAUDE.md को क्यों अनदेखा करता है

• Claude Code user message में नीचे जैसा system reminder insert करता है

  IMPORTANT: this context may or may not be relevant...
  

  • इसकी वजह से Claude उस context को मौजूदा task से असंबंधित मानने पर अनदेखा कर देता है
• फ़ाइल में ऐसे निर्देश जितने ज़्यादा होंगे जो broadly applicable नहीं हैं, उन्हें अनदेखा किए जाने की संभावना उतनी बढ़ेगी
• अनुमान है कि Anthropic ने यह इसलिए जोड़ा, क्योंकि बेकार निर्देशों को अनदेखा करने पर result quality बेहतर हुई

अच्छा CLAUDE.md लिखने के सिद्धांत

Less (instructions) is more

• LLM आमतौर पर करीब 150~200 निर्देशों का स्थिर रूप से पालन कर सकता है
  • model जितना छोटा होगा, performance degradation उतनी तेज़ होगी, और multi-step tasks के लिए वह उतना कम उपयुक्त होगा
• Claude Code के system prompt में पहले से ही करीब 50 निर्देश शामिल हैं
  • इसलिए CLAUDE.md में केवल व्यापक रूप से लागू और आवश्यक निर्देश न्यूनतम रूप में होने चाहिए
• निर्देश बढ़ने पर सभी निर्देशों को निभाने की कुल गुणवत्ता समान रूप से गिरती है

फ़ाइल की लंबाई और दायरा

• LLM focused और high-relevance context में बेहतर काम करता है
• क्योंकि CLAUDE.md हर session में शामिल होता है, इसमें सिर्फ़ broadly applicable information ही रखनी चाहिए
• आम तौर पर इसे 300 lines से कम, और संभव हो तो इससे भी छोटा रखने की सलाह दी जाती है
  • HumanLayer की example फ़ाइल 60 lines से कम है

Progressive Disclosure

• बड़े projects में सारी जानकारी एक ही फ़ाइल में रखना मुश्किल होता है, इसलिए Progressive Disclosure तरीका सुझाया जाता है
  • विस्तृत निर्देश agent_docs/ फ़ोल्डर के अलग Markdown files में बाँटें
  • उदाहरण: building_the_project.md, running_tests.md, code_conventions.md आदि
• CLAUDE.md में इन फ़ाइलों की सूची और संक्षिप्त विवरण तथा ज़रूरत पड़ने पर Claude को इन्हें पढ़ने का निर्देश ही होना चाहिए
• code snippets की जगह file:line references का उपयोग करें ताकि जानकारी up-to-date रहे
• यह Claude Skills concept जैसा है, लेकिन tools के उपयोग से ज़्यादा निर्देशों के प्रबंधन पर केंद्रित है

Claude linter नहीं है

• code style guidelines को CLAUDE.md में शामिल करना अप्रभावी है
  • LLM महँगा और धीमा होता है, और linter की तुलना में कम deterministic होता है
• style rules को मौजूदा code patterns से स्वाभाविक रूप से सीखा जा सकता है, इसलिए अलग निर्देशों की ज़रूरत नहीं
• formatting के लिए auto-fix करने वाले linters (जैसे Biome) का उपयोग करें, और Claude को सिर्फ़ fixed result दें
• ज़रूरत होने पर Stop Hook या Slash Command से formatting और validation को automate किया जा सकता है

auto-generation से बचें

• /init command या auto-generation features से बना CLAUDE.md recommend नहीं किया जाता
  • क्योंकि यह फ़ाइल हर session और output को प्रभावित करने वाला high-leverage point है
• एक गलत निर्देश की एक पंक्ति भी पूरे code quality पर chain reaction जैसा बुरा असर डाल सकती है
• इसलिए हर वाक्य को सावधानी से जाँचकर हाथ से लिखना चाहिए

निष्कर्ष

• CLAUDE.md, Claude को codebase पर onboard करने वाला दस्तावेज़ है, इसलिए इसमें WHY·WHAT·HOW साफ़ तौर पर परिभाषित होने चाहिए
• निर्देशों को न्यूनतम रखें, और सिर्फ़ व्यापक रूप से लागू, संक्षिप्त सामग्री शामिल करें
• Progressive Disclosure के ज़रिए ज़रूरत की जानकारी चरणबद्ध तरीके से दें
• Claude को linter की तरह इस्तेमाल न करें; dedicated tools, hooks और command features का साथ में उपयोग करें
• auto-generation की जगह सावधानी से हाथ से लिखा गया दस्तावेज़ पूरे harness की quality को अधिकतम कर सकता है