CLAUDE.md कैसे लिखें: Claude Code के लिए व्यावहारिक टेम्पलेट

तीसरी बार भी pull request में वही टिप्पणी आई: सही feature बदल गया, लेकिन test command नहीं चला, migration भी अनजाने में edit हो गई, या mobile layout देखना छूट गया। हर session की शुरुआत में लंबा prompt दोहराने पर भी यह समस्या लौटती रहती है। ऐसे में कमी Claude Code की क्षमता में नहीं, repository के स्थायी कामकाजी नियमों में हो सकती है।

एक उपयोगी CLAUDE.md काम शुरू होने से पहले जरूरी commands, edit की सीमाएं और review की शर्तें बताता है। इसमें पूरी company wiki या README चिपकाने की जरूरत नहीं है। इस लेख में आप जानेंगे कि file में क्या रखें, सुरक्षा के लिए क्या अलग लागू करें और एक चलते हुए Node.js checker से नियमों की जांच कैसे करें।

इस लेख का सार

CLAUDE.md में वे निर्णय लिखें जो उसके दायरे के लगभग हर task में दोबारा काम आते हैं। शुरुआत के लिए ये पांच बातें पर्याप्त हैं:

• CLAUDE.md, Claude Code को लगातार मिलने वाला मार्गदर्शन है; यह access control नहीं है।
• साझा नियम repository root में, निजी notes CLAUDE.local.md में और खास paths के नियम .claude/rules/ में रखें।
• इसे लगभग 200 lines से कम रखें। लंबी पृष्ठभूमि के बजाय file paths, commands और pass conditions लिखें।
• सुरक्षा संबंधी रोक को केवल वाक्य में न छोड़ें; permissions और hooks से भी लागू करें।
• नए नियम को team standard बनाने से पहले किसी छोटे, वास्तविक task पर परखें।

पहले दिन आदर्श document बनाने की कोशिश न करें। पिछली तीन reviews में दोहराई गई टिप्पणियां लिखें और उनमें से केवल वे फैसले रखें जिनकी अगली बार फिर जरूरत पड़ेगी।

Claude Code को क्या सौंपें और इंसान क्या तय करे

Repository में लिखा निर्देश और तकनीकी permission boundary अलग समस्याएं हल करते हैं। Claude Code मौजूदा code खोज सकता है, तय सीमा में बदलाव कर सकता है, बताए गए checks चला सकता है और diff समझा सकता है। Product policy, production release और ग्राहक, पैसे, privacy या कानून से जुड़े फैसले इंसान के पास रहने चाहिए।

निर्णय	Claude Code को सौंपें	इंसान के पास रखें
जांच	संबंधित files, पुराने patterns और tests खोजना	customer या contract data देखने की अनुमति तय करना
implementation	बताए गए scope में code और tests बदलना	pricing, authorization, legal या customer policy बदलना
verification	lint, type check, tests और build चलाना	acceptance criteria और release approval तय करना
रखरखाव	बदली files और बाकी risks की report देना	permanent repository rule जोड़ना या हटाना

CLAUDE.md मूल रूप से कहता है, “इन बातों को इस क्रम में देखो।” यह destructive command को असंभव नहीं बनाता। git push --force, production database access या secret वाली files को वास्तव में रोकना हो तो permission deny rules या PreToolUse hook लगाएं। Enforcement की अलग परत Claude Code permissions guide में विस्तार से समझाई गई है।

लिखने से पहले सही scope चुनें

File कहां रखी है, इससे तय होता है कि निर्देश कहां लागू होंगे। Root का CLAUDE.md team के साझा project rules के लिए है। ~/.claude/CLAUDE.md user के सभी projects पर लागू होता है। Machine-specific निजी notes के लिए CLAUDE.local.md ठीक है और इसे gitignore करना चाहिए। बड़ी repository में nested files और path-scoped rules गैरजरूरी निर्देश लोड होने से बचाते हैं।

repo/
  CLAUDE.md                  # team के साझा, छोटे नियम
  CLAUDE.local.md            # निजी notes; .gitignore में जोड़ें
  .claude/
    rules/
      api.md                 # केवल API files के नियम
  packages/
    admin/
      CLAUDE.md              # यह subtree पढ़ने पर जुड़ने वाले निर्देश

Launch पर Claude Code current directory और उसके parent directories की लागू files पढ़ता है। Nested CLAUDE.md तब लोड होता है जब Claude उस subtree की files पढ़ता है। इसलिए हर package का विवरण root में भरने के बजाय उसके पास रखना बेहतर है।

@docs/project-map.md जैसा import व्यवस्था साफ करता है, लेकिन context नहीं बचाता; imported content भी launch पर लोड होता है। Root file में हमेशा जरूरी निर्णय रखें और बाकी विवरण का path दें, ताकि जरूरत पड़ने पर ही पढ़ा जाए। Windows पर Claude Code सीधे CLAUDE.md पढ़ता है, AGENTS.md नहीं। दोनों साझा करने हों तो symlink पर निर्भर रहने के बजाय @AGENTS.md import स्पष्ट रूप से लिखें।

शुरुआत के लिए CLAUDE.md टेम्पलेट

Commands और change rules एक screen में समझ आने चाहिए। नीचे का template “साफ code लिखो” जैसे अस्पष्ट निर्देश से बचता है और paths, checks, exclusions तथा final report को नाम से बताता है। Team चाहें तो आसपास की व्याख्या हिंदी में लिख सकती है; commands और headings वही रखें जिन्हें checker देखता है।

# Project Instructions

## Project map
- App: Next.js 15 + TypeScript
- API: src/app/api/**
- Database schema: prisma/schema.prisma
- Tests: Vitest for units, Playwright for checkout

## Commands
- Install: npm ci
- Type check: npm run typecheck
- Unit tests: npm test
- Lint: npm run lint
- Build: npm run build

## Change rules
- Follow nearby code before adding a new abstraction.
- Do not change auth, billing, or migrations unless the task names them.
- When an API handler changes, update validation and tests together.
- Never place secrets in code, fixtures, logs, or screenshots.

## Review checklist
- Run the checks related to the changed files.
- Test an error path as well as the happy path.
- Report changed files, commands run, and skipped checks.

“ठीक से test करें” के बजाय npm test लिखें। “पुराना design मानें” के बजाय “API response के लिए src/lib/api-response.ts इस्तेमाल करें” लिखें। Verify होने वाला निर्देश अलग लोगों को एक ही निष्कर्ष तक पहुंचाता है।

तीन स्पष्ट Use case

नीचे agency review, SaaS contact form और content publishing के तीन काम हैं। हर उदाहरण में input, मिलने वाला output और इंसान की अंतिम जांच अलग रखी गई है। किसी नियम को CLAUDE.md में स्थायी बनाने से पहले इसी तरह छोटे task पर उसका असर देखें।

Use case 1: Agency में बार-बार आने वाली review टिप्पणी घटाना

Website agency में हर client के CSS naming, image size और browser support अलग हो सकते हैं। सभी projects के लिए बड़ी style guide डालने के बजाय उस repository में बार-बार लागू होने वाले 3 से 5 नियम रखें।

Input: पिछली तीन reviews की टिप्पणियां, target files, मौजूदा lint और build commands।

Output: इस्तेमाल किए गए पुराने components, बदले गए pages, चलाए गए checks और अभी न जांची गई browser conditions की concise report।

इंसान की जांच: Design intent, image rights, CTA copy और mobile का अंतिम दृश्य। नियम काम कर रहा है या नहीं, यह जानने के लिए बदलाव से पहले और बाद की 10 reviews में return count तुलना करें।

Use case 2: SaaS का contact form सुरक्षित रूप से बदलना

Form का UI ठीक होने पर भी validation, notification email या error path छूट सकता है। CLAUDE.md में लिखें कि form बदलने पर कौन-सी schema, API handler, template और test साथ देखनी है।

Input: Form component, input schema, API handler, notification template और existing tests।

Output: Valid submission और invalid input के tests, error messages तथा बदली settings की list। Personal information logs में न जाने की जांच भी report में हो।

इंसान की जांच: कौन-सा personal data लेना उचित है, retention period, mail recipient और production release। केवल conversion rate नहीं, failed submissions और support time भी देखें।

Use case 3: Content site पर publication omissions रोकना

Article सही होने पर भी description, internal link, image या mobile layout छूटे तो search traffic और ad revenue दोनों प्रभावित होते हैं। Publication conditions को छोटी checklist बनाएं।

Input: MDX file, frontmatter schema, internal links, build command और target URL।

Output: Description length, broken links, code blocks, build result और देखे गए URLs की list।

इंसान की जांच: विषय की accuracy, search intent, ads के बीच readability और publish decision। PV के साथ search clicks, engaged reading और CTA clicks को weekly compare करें।

चलने वाले code से CLAUDE.md की जांच

नीचे का Node.js script file की line count, जरूरी headings और कुछ सामान्य secret patterns जांचता है। इसे check-claude-md.mjs नाम से save करें और Node.js 20 या उसके बाद के version में चलाएं।

import { readFile } from "node:fs/promises";

const filePath = process.argv[2] ?? "CLAUDE.md";
const text = await readFile(filePath, "utf8");
const lines = text.split(/\r?\n/);
const lineCount = text.endsWith("\n") ? lines.length - 1 : lines.length;

// Pass localized H2 names as the third argument, separated by "|".
const requiredHeadings = (
  process.argv[3] ?? "Commands|Change rules|Review checklist"
)
  .split("|")
  .map((heading) => heading.trim())
  .filter(Boolean);
const h2Headings = new Set();
let fenceMarker = null;

for (const line of lines) {
  const fenceMatch = line.match(/^\s*(`{3,}|~{3,})/);
  if (fenceMatch) {
    const marker = fenceMatch[1];
    if (fenceMarker === null) fenceMarker = marker;
    else if (marker[0] === fenceMarker[0] && marker.length >= fenceMarker.length) fenceMarker = null;
    continue;
  }
  if (fenceMarker !== null) continue;

  const heading = line.match(/^##\s+(.+?)\s*$/)?.[1];
  if (heading) h2Headings.add(heading);
}

const secretPatterns = [
  ["AWS access key", /AKIA[0-9A-Z]{16}/],
  ["GitHub token", /gh[pousr]_[A-Za-z0-9]{20,}/],
  ["assigned secret", /\b(api[_-]?key|password|token)\s*[:=]\s*["'][^"'\n]{8,}["']/i],
];

const failures = [];
if (lineCount > 200) failures.push(`too many lines: ${lineCount} (max 200)`);
if (requiredHeadings.length === 0) failures.push("required heading list is empty");

for (const heading of requiredHeadings) {
  if (!h2Headings.has(heading)) failures.push(`missing h2: ${heading}`);
}

for (const [label, pattern] of secretPatterns) {
  if (pattern.test(text)) failures.push(`possible secret: ${label}`);
}

if (failures.length > 0) {
  console.table(failures.map((problem) => ({ problem })));
  process.exitCode = 1;
} else {
  console.log(`CLAUDE.md check passed: ${lineCount} lines`);
}

Local machine और CI दोनों में command एक ही रखी जा सकती है:

node check-claude-md.mjs CLAUDE.md
# हिंदी H2 headings होने पर
node check-claude-md.mjs CLAUDE.md "कमांड|बदलाव के नियम|समीक्षा सूची"

यह complete secret scanner नहीं है। इसे GitHub secret scanning या dedicated scanner के साथ चलाएं। कोई credential मिले तो केवल visible line हटाना पर्याप्त नहीं; जरूरत के अनुसार history साफ करें और credential revoke भी करें।

Pitfall: लंबी file, अस्पष्ट नियम और गलत security भरोसा

Pitfall 1: हर review के बाद file बढ़ती जाती है। कारण यह है कि हर comment को दोबारा आने की संभावना देखे बिना permanent rule बना दिया जाता है। सुधार: केवल repeated decisions जोड़ें, पहले stale commands हटाएं और package-specific detail को package के पास ले जाएं।

Pitfall 2: निर्देश verify नहीं हो सकता। “Quality बनाए रखें” या “existing design follow करें” pass condition नहीं बताते। सुधार: target path, exact command, expected exit status, browser width या test name लिखें। नया teammate भी उसी नतीजे तक पहुंचना चाहिए।

Pitfall 3: सुरक्षा सिर्फ prose पर टिकी है। “Production को कभी न छुएं” लिखने से तकनीकी barrier नहीं बनता। सुधार: dangerous command patterns को permission deny rules में रखें और deterministic block के लिए PreToolUse hook इस्तेमाल करें। CLAUDE.md में कारण और approved alternative लिखें।

Pitfall 4: imports छिपा हुआ documentation dump बन जाते हैं। कारण यह भ्रम है कि imported files context खर्च नहीं करतीं। वे launch पर लोड होती हैं। सुधार: root में छोटा decision rule रखें और detail का path या URL दें।

Document को पुराना होने से कैसे बचाएं

CLAUDE.md के बदलाव को code change की तरह review करें: diff देखें, checker चलाएं और एक representative task पर परिणाम जांचें। जिस command, path या architecture का अस्तित्व नहीं रहा, उसका rule भी हटाएं।

हर महीने ये चार सवाल पूछना पर्याप्त है: कौन-सी review टिप्पणी दो बार आई, कौन-सा rule दो तरह से समझा गया, कौन-सा path या command पुराना हुआ, और कौन-सी warning को permission या hook में बदलना चाहिए। उपयोगी metric token count नहीं, बल्कि review return, merge से पहले पकड़े गए failed checks और basic बातें फिर समझाने में लगे minutes हैं।

अक्सर पूछे जाने वाले प्रश्न

CLAUDE.md कितनी लंबी होनी चाहिए?

कोई सख्त content limit नहीं है, लेकिन official guidance लगभग 200 lines से कम रखने की सलाह देती है। करीब 100 lines से शुरू करें। Package-only बातें nested CLAUDE.md या .claude/rules/ में ले जाएं।

क्या /compact के बाद भी निर्देश रहते हैं?

Root CLAUDE.md compaction के बाद context में फिर डाला जाता है। Nested और path-scoped instructions matching files पढ़ने पर फिर लोड होते हैं। इसलिए लंबे समय तक जरूरी निर्णय chat पर छोड़ने के बजाय file में रखें।

Auto memory और CLAUDE.md में क्या अंतर है?

CLAUDE.md इंसानों द्वारा लिखे और maintain किए गए shared instructions रखता है। Auto memory Claude द्वारा local तौर पर दर्ज debugging discoveries और preferences रखती है। Shared commands और boundaries CLAUDE.md में रहें; local finding को team rule तभी बनाएं जब इंसान review करे।

पहले version में क्या लिखना चाहिए?

Install, test और build के commands, protected areas की एक list और final report में मांगी जाने वाली चीजें लिखें। एक वास्तविक task चलाएं और केवल वही missing decision जोड़ें जिससे observable rework हुआ।

अपने project का तैयार template बनाएं

CLAUDE.md reliable workflow का केवल एक हिस्सा है। Permissions, tests, handoff और review को भी उसी सीमा से मेल खाना चाहिए। अपनी repository में लगाने योग्य checklists और exercises के लिए ClaudeCodeLab की सामग्री सूची में उपयुक्त resource चुनें।

वास्तव में जांचा गया परिणाम

22 जुलाई 2026 को इस लेख के check-claude-md.mjs को दो temporary fixtures पर चलाया गया। जरूरी headings वाले 10-line valid sample ने exit code 0 और pass message दिया। एक heading हटाकर test token डालने वाले negative sample ने exit code 1 दिया और तीन findings दिखाईं: missing heading तथा दो secret-pattern matches।

Review में JavaScript syntax, official-source URLs, internal links, frontmatter, अंतिम results section और केवल एक primary commercial CTA भी जांचे गए। शुरुआत अपने CLAUDE.md पर checker चलाकर करें और पहली reported समस्या सुधारें। व्यवहार की पुष्टि Claude Code के official documentation में memory, context window, settings और hooks से की गई है।