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

 (humanlayer.dev)
78 पॉइंट द्वारा GN⁺ 2025-12-01 | 1 टिप्पणियां | WhatsApp पर शेयर करें
  • 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 को अधिकतम कर सकता है

संबंधित पढ़ाई

1 टिप्पणियां

 
GN⁺ 2025-12-01
Hacker News राय

  • Claude अक्सर CLAUDE.md में दिए गए निर्देशों को नज़रअंदाज़ कर देता है
    फ़ाइल में किसी खास काम से असंबंधित जानकारी जितनी ज़्यादा होती है, Claude के उन निर्देशों का पालन न करने की संभावना उतनी बढ़ जाती है
    एक दोस्त ने Claude से कहा था कि वह उसे “Mr Tinkleberry” कहकर बुलाए, और जब भी Claude यह भूल जाता था, तब समझ आ जाता था कि वह फ़ाइल को नज़रअंदाज़ कर रहा है

  • मैं पहले से Table-of-Contents approach इस्तेमाल करता रहा हूँ
    काम के हिसाब से निर्देशों को अलग-अलग markdown फ़ाइलों में बाँट देता हूँ, और CLAUDE.md में सिर्फ उनकी सूची और छोटा-सा विवरण रखता हूँ
    इससे context window साफ़-सुथरी रहती है
    मेरी example फ़ाइल यहाँ देखी जा सकती है

    • मैंने भी यही तरीका आज़माया था, लेकिन नतीजे काफ़ी अस्थिर रहे
      Claude शायद ही कभी उन दूसरी document फ़ाइलों को वास्तव में पढ़ता था

  • मुझे लगा कि Claude को बहुत ज़्यादा context देने पर गुणवत्ता उल्टा गिर जाती है
    इसलिए मैं हमेशा कोड के दो version रखता हूँ

    1. comments और whitespace के बिना original code
    2. comments वाला code
      LLM को मैं सिर्फ पहला version देता हूँ
      मुझे लगता है कि Compute बनाम information ratio ही असली बात है। compute सीमित होता है
    • मेरा भी कुछ ऐसा ही अनुभव रहा, लेकिन बार-बार दोहराई जाने वाली बातों को Claude notes फ़ाइल में रखने से efficiency बढ़ गई
      सब कुछ डालने की ज़रूरत नहीं होती, लेकिन core information डालने का ROI काफ़ी अच्छा था
      Claude सामान्य projects में तो अच्छा काम करता है, लेकिन नए framework या tools पर अक्सर उलझ जाता है
    • आपने कहा कि आप कोड के दो version रखते हैं, तो उनकी consistency कैसे manage करते हैं, यह जानना चाहूँगा
      क्या edits के बाद comments और whitespace हटाने के लिए कोई script इस्तेमाल करते हैं?
    • मेरा मानना है कि document फ़ाइलों में information density ऊँची रखनी चाहिए
    • आपने कहा कि LLM को comments वाला version नहीं देते, तो व्यवहार में आप यह कैसे करते हैं, यह जानना चाहूँगा
    • आख़िरकार attention सीमित होती है। context ज़्यादा भर देने से फोकस बिखर जाता है

  • सच कहें तो इस तरह की जटिल सेटिंग के बिना भी एक समाधान है
    वह है कोड को साफ़-साफ़ documenting करना
    हर फ़ाइल क्या करती है, यह संक्षेप में लिख दें, वही अपने-आप prompt का काम करता है
    README.md का सक्रिय रूप से इस्तेमाल करना चाहिए
    LLM पहले से public information पर trained हैं, इसलिए कुछ नया ईजाद करने की ज़रूरत नहीं है

    • लेकिन AI के लिए documentation लिखते समय मानव पाठकों के लिए लिखी जाने वाली documentation से अलग तरीका चाहिए
      सिर्फ “कोड को अच्छी तरह document करो” वाली सलाह इस संदर्भ में फिट नहीं बैठती
    • मुझे भी लगता है कि AI community कई बार ज़रूरत के बिना पहिया फिर से बना रही है
      README अच्छा है, लेकिन CLAUDE.md का मक़सद अलग है
      उदाहरण के लिए Claude/agents.md में यह सुविधा है कि किसी खास directory तक पहुँचने पर वह अपने-आप context में insert हो जाता है
      जटिल codebase में context management कहीं ज़्यादा महत्वपूर्ण है
    • CLAUDE.md सिर्फ documentation नहीं है, बल्कि model के initial prompt को customize करने का काम करता है
      इसलिए “prompt ठीक से लिखो” जैसी सलाह असली मुद्दे को मिस करती है
    • उदाहरण के लिए “database queries हमेशा index का इस्तेमाल करें” जैसा नियम कहाँ लिखा जाए?
      अगर उसे README में लिखेंगे, तो वह आख़िरकार CLAUDE.md जैसी ही भूमिका निभाने लगेगा
      CLAUDE.md का उद्देश्य यह है कि Claude को हर बार सारे documents फिर से न पढ़ने पड़ें, इसलिए ज़रूरी जानकारी पहले से दे दी जाए
      इंसान चीज़ें याद रखता है, लेकिन Claude हर task पर भूल जाता है, इसलिए re-onboarding कम करने वाली संरचना चाहिए

  • ईमानदारी से कहूँ तो अगर AI infrastructure सेट करने के लिए इतना सब करना पड़े, तो मुझे लगता है कि मैं खुद coding कर लूँ तो बेहतर है

    • लेकिन style से जुड़ी settings एक बार कर दी जाएँ तो उन्हें दोबारा इस्तेमाल किया जा सकता है
      मैं common rules और project-specific rules को अलग रखकर manage करता हूँ
    • लेख में बताई गई setup कुछ घंटों में पूरी हो जाती है
      AI का इस्तेमाल न करना बस productivity loss है
    • शुरुआती setup का ज़्यादातर हिस्सा LLM से भी करवाया जा सकता है
    • सच में, इसमें इतना बड़ा effort नहीं लगता। समस्या tools को ज़रूरत से ज़्यादा optimize करने की चाहत है
    • असली बात यह है कि लागत बार-बार लगने वाली है या एक बार की
      अगर setup सिर्फ एक बार करना है, तो उसमें निवेश करना पूरी तरह उचित है
      “setup झंझट वाला है” कहना कुछ वैसा ही बहाना है जैसा debugger setup से बचने वाले लोग देते हैं

  • मैं तो बस ज़रूरी कोड copy करके chat window में paste करता हूँ और बातचीत की तरह इस्तेमाल करता हूँ
    आजकल models काफ़ी बेहतर हो गए हैं, इसलिए .md फ़ाइलों के बिना भी काफ़ी अच्छे नतीजे मिल जाते हैं
    ये फ़ाइलें थोड़ा-बहुत सुधार ज़रूर दे सकती हैं, लेकिन मुझे नहीं लगता कि ये 100x productivity का कोई जादू हैं

    • लेकिन यह एक अलग use case है
      यहाँ चर्चा उस स्थिति की हो रही है जहाँ Claude पूरे feature implementation या bug fix खुद कर रहा हो
    • मेरा भी अनुभव कुछ ऐसा ही है। मैंने एक बार CLAUDE.md बनाया था, लेकिन अब इस्तेमाल नहीं करता
      बस ज़रूरी context दे दो, वह काफ़ी अच्छा काम करता है। यह थोड़ा bikeshedding जैसा लगता है
    • फिर भी database tables या columns की सूची जैसी चीज़ें पहले से व्यवस्थित रख दी जाएँ, तो दोहराव कम हो सकता है

  • मैं Claude से CLAUDE.md खुद लिखवाता हूँ
    अगर उसे बता दिया जाए, “README.md यूज़र्स के लिए है, CLAUDE.md तुम्हारे लिए,”
    तो वह “हमेशा API docs चेक करो” जैसे निर्देश भी अपने-आप update कर देता है
    कोई जादुई prompt जानना ज़रूरी नहीं, बस नतीजे अच्छे आने चाहिए

    • लेकिन इस बात पर संदेह है कि AI द्वारा खुद लिखे गए निर्देश इंसान द्वारा लिखे गए निर्देशों से बेहतर होते हैं, इसका कोई सबूत है भी या नहीं
      ऐसा नहीं लगता कि AI के पास खुद को सबसे बेहतर तरीके से prompt करने की कोई खास वजह है