· claude code · setup guide · april 2026 ·

कैसे लिखना a CLAUDE.md that दरअसल works (2026 guide)

// figure CLAUDE.md building block diagram

// FILED Claude Code// SOURCE Septim Labs// PERMALINK /blog/how-to-write-claude-md-2026.htmlcite this →

Published April 20, 2026 · by Septim Labs · 9 min read

TL;DR

A CLAUDE.md is a plain text file Claude Code पढ़ता है at the start of हर session — अगर it is vague, too long, या missing key sections, Claude ignores it consistently और silently.
The 10-block structure below (prime directive through session hygiene) is what we चलती हैं on हर Septim project; it keeps Claude on-task के बिना re-explaining anything across sessions.
The five failure modes — context bloat, vague rules, no tool allowlist, no kill-switch guidance, no session-hygiene — account for most of the complaints you see on r/ClaudeAI और r/LocalLLaMA.

1. क्या a CLAUDE.md is — और why yours शायद does नहीं work

कब you open Claude Code, it looks for a CLAUDE.md file in your working directory (and up the directory tree) और loads it into context before your पहले message. The Anthropic documentation describes it as the place you लिखना down "what you'd otherwise re-explain." That definition is accurate लेकिन undersells the failure surface.

"Instructions you लिखना to give Claude persistent context"

— Anthropic Claude Code documentation (docs.claude.com →)

The problem is that CLAUDE.md content is delivered as context, नहीं enforced configuration. The docs are direct about this: "Claude पढ़ता है it और tries to follow it, लेकिन there is no guarantee of strict compliance, especially for vague या conflicting instructions." The file is नहीं a rules engine. It is a memo. कैसे you लिखना a memo determines whether the reader acts on it.

Three things make most CLAUDE.md files fail in practice:

They are written once, कभी नहीं updated. Rules drift out of sync के साथ the actual stack. Claude encounters contradictions between the file और reality, picks one arbitrarily, और the user concludes "Claude doesn't follow instructions."
They are written for a human reader, नहीं a language model. Narrative paragraphs के साथ soft qualifiers ("try to use...", "generally prefer...") are नहीं instructions. They are suggestions, और Claude treats them as such.
They do नहीं बताना Claude what to do when the instructions चलती हैं out. No prime directive means Claude defaults to its own judgment on edge cases — which is अक्सर fine, लेकिन occasionally catastrophic for your repo.

The official docs recommend targeting under 200 lines per file और using markdown headers और bullets to group related instructions. That is the right frame: short, structured, specific. The 10-block structure below operationalizes it.

2. The 10-block structure we इस्तेमाल at Septim

Every CLAUDE.md on a Septim project has these 10 sections, in this order. Each has a specific job. Sections in the wrong order या merged साथ में produce worse adherence क्योंकि Claude scans structure वही way readers do.

Block 01

Prime directive

One sentence. The single decision rule Claude applies when nothing else in the file covers the situation. Ours: "Goal: revenue. Constraint: don't go to jail." This sounds extreme लेकिन it removes an entire category of Claude pausing to ask permission for obvious moves. Your version might be "ship working code over perfect code" या "never modify production data के बिना explicit confirmation."

Block 02

Stack rules

Exact tools, versions, और how Claude should इस्तेमाल them. Not "we इस्तेमाल Next.js." Instead: "Stack is Next.js 16 App Router. No Pages Router. Tailwind for styling. Framer Motion for animation. If you ज़रूरत state, इस्तेमाल Zustand — नहीं Redux, नहीं Context. Stripe SDK v3 only." Claude hallucinates outdated API patterns when it doesn't have this.

Block 03

Guardrails

Constraints on Claude's behavior in this project. These are the rules that fire when Claude would otherwise make a technically correct लेकिन project-wrong choice. Example from our files: "Never चलती हैं git push के बिना confirmation. Never इस्तेमाल git add . — stage files by name. Never suggest paid external services; हर solution must be free." Guardrails are where you prevent the expensive mistakes.

Block 04

Do-not list

Explicit prohibitions, separate from guardrails. Guardrails shape behavior; the do-not list hard-stops it. From our Septim files: "Do नहीं भेजना cold email to addresses you have नहीं verified exist. Do नहीं re-open the Septim Gauge vertical. Do नहीं amend existing commits — create new ones." This block is where you put the decisions that were made by a human और should नहीं be revisited.

Block 05

File hygiene

कहाँ things live और what they are named. Every Septim project has this block. Example: "All API routes live in /api/. Blog HTML files live in /blog/. Client-facing config in /lib/config.ts, कभी नहीं inline. No env vars hardcoded anywhere, इस्तेमाल process.env.VARNAME के साथ a fallback error." Without this, Claude makes files wherever they fit the current task, और the repo fragments.

Block 06

Review policy

Defines when Claude should proceed versus pause for human sign-off. यह है different from guardrails: guardrails prevent actions, review policy defines who decides edge cases. Ours: "Proceed on any code change to non-production files. Pause और summarize before modifying Stripe webhook handlers, the auth layer, या any file tagged # SENSITIVE in its header comment."

Block 07

Test policy

The exact test command और the trigger conditions. "Run npm test before हर commit" is a rule. "Feel free to test as you go" is not. Ours: "Run npm run build after any component change. Run npm test before any commit that touches /api/. If tests fail, fix them before moving to the अगला task — do नहीं skip."

Block 08

Deploy style

कैसे you deploy और any manual steps in the chain. Ours: "Deploy is vercel --prod from the project root. If the Vercel CLI OOMs, इस्तेमाल vercel deploy --prebuilt के साथ the build artifact. Do नहीं deploy अगर there are uncommitted changes. After deploy, verify at the production URL before closing the task." Claude will improvise a deploy path अगर you do नहीं give it one.

Block 09

Commit style

Format, scope, और any signing requirements. Example: "Commit messages: imperative mood, under 72 characters, no emoji unless the user explicitly requests it. Include a Co-Authored-By: trailer for Claude-generated commits. Never amend published commits. Never इस्तेमाल --no-verify unless the user explicitly asks."

Block 10

Session hygiene

कब to compact, when to start fresh, और any known session-size limits. From our own CLAUDE.md: "Run /compact हर ~2 घंटे of heavy work. If a session transcript grows past ~20 MB on-disk JSONL, start fresh और link back to this file. The आख़िरी session crashed at 33 MB (STATUS_BREAKPOINT). Don't let it repeat." यह है the block nobody लिखता है until they lose work.

Want this done for your codebase, नहीं बस described?

Septim Session is a one-hour working engagement. We audit your existing CLAUDE.md (or create one scratch से), wire up the 10-block structure for your specific stack, और deliver a working file you can इस्तेमाल immediately. $149.

Book Septim Session $149 → Agents Pack $49 →

3. Five failure modes to avoid

These are नहीं hypothetical. Each one is a pattern pulled from threads on r/ClaudeAI, r/LocalLLaMA, और the Anthropic community forum where developers described Claude "ignoring" their instructions. In most cases, the instructions were the problem.

Failure mode 1: context bloat

The Anthropic docs recommend targeting under 200 lines per CLAUDE.md file. Above that, "longer files consume more context और reduce adherence." We have seen files at 600+ lines that contradicted themselves four times over. Claude does नहीं skip sections — it पढ़ता है everything और reconciles conflicts के साथ its own judgment. If you would नहीं re-read a section of your file before हर session, it शायद should नहीं be there. Split large files using @path imports या .claude/rules/ subdirectories.

Failure mode 2: vague rules

The docs give a direct example: "Use 2-space indentation" works; "Format code properly" does not. Vague rules do नहीं fail visibly — Claude acknowledges them और proceeds के साथ its own interpretation. You will नहीं पता the rule failed until you see output you did नहीं want. Every instruction in your CLAUDE.md should be specific enough that you could verify it in a code review. "Keep files organized" fails this test. "API handlers live in src/api/handlers/" passes it.

Failure mode 3: no tool allowlist

Claude Code can इस्तेमाल shell commands, read files, लिखना files, चलती हैं tests, और more. If your CLAUDE.md does नहीं specify which tools Claude may इस्तेमाल freely versus which require confirmation, Claude defaults to proceeding on most things. यह है fine in a sandbox. In a project के साथ production Stripe webhooks और a live database, "run the migration" is नहीं a command you चाहिए auto-executed. Block 06 (review policy) और Block 04 (do-not list) साथ में cover this — लेकिन सिर्फ़ अगर you लिखना them explicitly.

Failure mode 4: no kill-switch guidance

क्या should Claude do when it hits a situation it cannot resolve? Most CLAUDE.md files are silent on this. Claude तो picks the most confident-looking option और keeps going. The better pattern: a short escalation ladder in your prime directive. "If uncertain, ask. If blocked on a tool permission, stop और describe what you need." This does नहीं eliminate Claude judgment errors, लेकिन it does give you a chance to catch them before they compound across ten tool calls.

Failure mode 5: no session-hygiene block

Session context is finite. As a session grows, पहले context (including CLAUDE.md content) can be displaced by conversation. If you are doing multi-hour agentic sessions, the instructions Claude read at the start may नहीं be in the active context window by घंटा three. The Anthropic docs confirm: "Project-root CLAUDE.md survives compaction" — लेकिन सिर्फ़ अगर you दरअसल compact. Block 10 (session hygiene) is नहीं optional for anyone running long sessions.

4. A paste-ready CLAUDE.md template

Sixty lines. Every block labeled. Replace the placeholder values के साथ your own stack. यह है what you get when you strip a Septim-reviewed CLAUDE.md down to the transportable skeleton.

CLAUDE.md — 60-line template

# CLAUDE.md
# Last updated: YYYY-MM-DD
# Project: [your project name]

# ============================================================
# BLOCK 01 — PRIME DIRECTIVE
# ============================================================
# When nothing else in this file covers the situation, apply this rule:
# [One sentence. Example: "Ship working code over perfect code."]

# ============================================================
# BLOCK 02 — STACK RULES
# ============================================================
# Framework: [e.g., Next.js 16 App Router. No Pages Router.]
# Styling:    [e.g., Tailwind CSS v4. No inline styles.]
# State:      [e.g., Zustand. No Redux, no Context.]
# Database:   [e.g., Supabase with Prisma. No raw SQL queries.]
# Auth:       [e.g., Supabase Auth. Sessions live in cookies, not localStorage.]
# Payments:   [e.g., Stripe SDK v3. Use payment links, not manual charges.]

# ============================================================
# BLOCK 03 — GUARDRAILS
# ============================================================
# - Never run `git push` without confirmation.
# - Never use `git add .` — stage files by name.
# - Never suggest paid external services.
# - Never hardcode env vars — use process.env.VARNAME with a fallback error.
# - Never modify a schema migration without human review.

# ============================================================
# BLOCK 04 — DO-NOT LIST
# ============================================================
# These are decided. Do not revisit.
# - Do not [specific forbidden action 1]
# - Do not [specific forbidden action 2]
# - Do not use --no-verify on commits.
# - Do not amend published commits — create new ones.

# ============================================================
# BLOCK 05 — FILE HYGIENE
# ============================================================
# - API routes: /api/
# - Components: /components/[FeatureName]/index.tsx
# - Config:     /lib/config.ts (no inline config)
# - Types:      /types/[domain].ts
# - Tests:      /__tests__/[filename].test.ts

# ============================================================
# BLOCK 06 — REVIEW POLICY
# ============================================================
# Proceed freely on: non-production code, new components, copy changes.
# Pause and summarize before: auth layer, payment handlers, DB migrations.
# Label any file that needs extra care with: # SENSITIVE in the header.

# ============================================================
# BLOCK 07 — TEST POLICY
# ============================================================
# Test command: npm test
# Run before: every commit touching /api/ or /lib/
# If tests fail: fix before moving on. Do not skip.
# Build check: npm run build after any component change.

# ============================================================
# BLOCK 08 — DEPLOY STYLE
# ============================================================
# Command: vercel --prod
# Pre-deploy check: no uncommitted changes.
# Post-deploy: verify production URL before closing the task.
# If CLI OOMs: use vercel deploy --prebuilt with the build artifact.

# ============================================================
# BLOCK 09 — COMMIT STYLE
# ============================================================
# Format: imperative mood, under 72 chars, no emoji unless asked.
# Trailer: Co-Authored-By: Claude [model] <noreply@anthropic.com>
# Never: --no-verify, --amend on published commits.

# ============================================================
# BLOCK 10 — SESSION HYGIENE
# ============================================================
# Run /compact every ~2 hours of heavy work.
# If session JSONL exceeds ~20 MB on disk, start fresh.
# On restart: this file re-loads automatically. No re-paste needed.

Template based on Septim Labs internal CLAUDE.md files and Anthropic Claude Code documentation.

5. When this is not enough

A well-written CLAUDE.md handles the predictable surface: stack choices, file layout, commit format, deploy steps. It does not handle the judgment layer: which tasks to prioritize, how to structure a new feature across multiple files, when a bug is severe enough to block a deploy.

For solo founders and small teams, the gap usually shows up when Claude is running unsupervised on longer agentic tasks — the kind where it is making fifteen tool calls in a row, reading and writing files across the codebase, and deciding at each step what to do next. A CLAUDE.md sets the rails. It does not drive the train.

Two things close that gap:

Septim Session ($149). A one-hour working engagement where we build the CLAUDE.md for your specific project, not the generic template above. We read your actual codebase, identify the real edge cases, and write the instructions Claude will actually follow. Includes a walkthrough of the 10-block structure applied to your stack.
Septim Agents Pack ($49). A roster of pre-built Claude sub-agent configurations (Atlas, Luca, Canon, Ember, Tally, Nova, Ward, Mira, Juno, Pip) with the CLAUDE.md patterns already wired. If you are running multi-agent workflows, this is the faster path than building from scratch.

Need your CLAUDE.md built, not described?

Septim Session: we build the file for your stack in one working session. $149. If you are running multi-agent workflows, Agents Pack includes sub-agent CLAUDE.md patterns ready to paste. $49.