CLAUDE.md Best Practices: real projects के लिए practical template

CLAUDE.md हर session में project structure, commands और rules दुबारा समझाने से बचाता है। लेकिन यह security policy नहीं है और इसमें सारी documentation paste करना अच्छा pattern नहीं है।

Team rules छोटे और verify करने लायक होने चाहिए; personal preferences local रहें; hard restrictions permissions और hooks में लागू करें। यह लेख बताता है कि CLAUDE.md में क्या रखना चाहिए और क्या बाहर रखना चाहिए, ताकि beginner भी practical तरीके से शुरू कर सके.

Goal है copy-paste template देना और team review के लिए file को maintainable रखना.

Core idea: CLAUDE.md is guidance, not enforcement

Team rules छोटे और verify करने लायक होने चाहिए; personal preferences local रहें; hard restrictions permissions और hooks में लागू करें। Official docs के अनुसार CLAUDE.md contextual guidance है, Auto memory local learnings रखती है, settings client behavior configure करती हैं, और hooks lifecycle events पर commands चलाते हैं.

Mechanism	Role	Best for
CLAUDE.md	Human-written persistent guidance	Conventions, architecture, verification commands
Auto memory	Claude’s local learned notes	Debugging insights, preferences, repeated discoveries
settings / permissions	Client configuration and permission rules	Allow, deny, extra directories
hooks	Commands run at lifecycle events	Blocking risky actions, verification, formatting

Where to place CLAUDE.md files

Claude Code working directory से ऊपर की ओर CLAUDE.md और CLAUDE.local.md पढ़ता है. Root rules session start में आते हैं; nested rules related files पढ़ने पर आते हैं.

repo/
  CLAUDE.md                 # shared project guidance
  CLAUDE.local.md           # personal, gitignored
  .claude/
    rules/
      api.md                # path-scoped rule
  packages/admin/CLAUDE.md  # loaded when this subtree is read

What to keep in always-loaded memory

Always-loaded memory में build commands, tests, architecture boundaries, naming rules, forbidden patterns और review gates रखें. Secrets, long logs, meeting notes, one-off plans और raw research बाहर रखें.

• Keep build, test, lint, type-check, and release verification commands.
• Keep edit boundaries, non-edit boundaries, naming rules, and review gates.
• Do not keep secrets, long meeting notes, historical logs, or one-off task instructions.
• Do not paste entire official docs. Keep the URL and the decision rule.

Copy-paste CLAUDE.md template

नीचे का template छोटा है ताकि context heavy न हो. इसे project के हिसाब से बदलें और हर rule को verify करने लायक रखें.

# Project Instructions

## Project map
- App: Next.js 15 + TypeScript
- API: src/app/api/**
- DB: Prisma schema in prisma/schema.prisma
- Tests: Vitest for units, Playwright for critical browser flows

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

## Change rules
- Prefer small edits that follow existing patterns.
- Do not change auth, billing, or migrations without explicit task scope.
- When editing API handlers, update validation and tests in the same pass.
- Before final response, report commands run and any skipped verification.

## Review checklist
- No secrets in code, logs, fixtures, or screenshots.
- Error paths are tested, not only the happy path.
- Public copy and docs use the same terminology as the UI.

Use imports and .claude/rules carefully

@path imports organization के लिए ठीक हैं, token बचाने के लिए नहीं. Imported content भी context में आता है. बड़े project में stale content हटाएँ और path rules को .claude/rules/ में रखें.

# CLAUDE.md

Read the short project overview in @docs/project-map.md.
Do not import long meeting notes here.

## Compact Instructions
- Preserve current objective, files changed, tests run, and unresolved risks.
- Drop raw command output unless it explains a failure.

---
paths:
  - "src/api/**/*.ts"
---

# API rules
- Validate request bodies with Zod.
- Return typed error responses.
- Add or update tests for every changed handler.

Three practical use cases

1. सबसे ज्यादा फायदा onboarding, bug fixing और content workflow में मिलता है जहाँ rules बार-बार repeat होते हैं। Onboarding में project map और verification commands सबसे पहले लिखें.
2. Bug fixing में reproduction command, log location और minimal test command दें.
3. Content workflow में tone, internal links और quality gates CLAUDE.md में रखें; long notes Obsidian या docs में रहें.

Failure cases and pitfalls

1. Common failure है पूरा README import करना, vague rules लिखना, और security को सिर्फ CLAUDE.md में मान लेना. Fix है only always-needed rules रखना.
2. “clean बना दो” की जगह exact command और file boundary लिखें.
3. Hard security के लिए permissions और PreToolUse hooks चाहिए; CLAUDE.md अकेला enough नहीं है.

Team maintenance rule

CLAUDE.md तभी update करें जब same mistake repeat हो, review comment repeat हो, command बदले, या architecture boundary बदले.

# quick review before changing CLAUDE.md
rg -n "TODO|deprecated|temporary|secret|password|token" CLAUDE.md .claude/rules
git diff -- CLAUDE.md .claude/rules

Next step and monetization path

पूरे workflow के लिए इसे Obsidian integration, token optimization और consultation page से जोड़ें। Full workflow के लिए Obsidian, token optimization और consultation page से जोड़ें. Related articles: Obsidian workflow, productivity tips, permissions guide, and consultation page.

What was verified

यह update official memory, context window, settings और commands docs पर आधारित है. Official references: memory, context window, settings, and commands.