· claude code · setup guide · april 2026 ·

How to write a CLAUDE.md that actually works (2026 guide)

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

TL;DR

A CLAUDE.md is a plain text file Claude Code reads at the start of every session — if it is vague, too long, or missing key sections, Claude ignores it consistently and silently.
The 10-block structure below (prime directive through session hygiene) is what we run on every Septim project; it keeps Claude on-task without 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 and r/LocalLLaMA.

1. What a CLAUDE.md is — and why yours probably does not work

When you open Claude Code, it looks for a CLAUDE.md file in your working directory (and up the directory tree) and loads it into context before your first message. The Anthropic documentation describes it as the place you write down "what you'd otherwise re-explain." That definition is accurate but undersells the failure surface.

"Instructions you write to give Claude persistent context"

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

The problem is that CLAUDE.md content is delivered as context, not enforced configuration. The docs are direct about this: "Claude reads it and tries to follow it, but there is no guarantee of strict compliance, especially for vague or conflicting instructions." The file is not a rules engine. It is a memo. How you write a memo determines whether the reader acts on it.

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

They are written once, never updated. Rules drift out of sync with the actual stack. Claude encounters contradictions between the file and reality, picks one arbitrarily, and the user concludes "Claude doesn't follow instructions."
They are written for a human reader, not a language model. Narrative paragraphs with soft qualifiers ("try to use...", "generally prefer...") are not instructions. They are suggestions, and Claude treats them as such.
They do not tell Claude what to do when the instructions run out. No prime directive means Claude defaults to its own judgment on edge cases — which is often fine, but occasionally catastrophic for your repo.

The official docs recommend targeting under 200 lines per file and using markdown headers and 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 use 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 or merged together produce worse adherence because Claude scans structure the same 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 but it removes an entire category of Claude pausing to ask permission for obvious moves. Your version might be "ship working code over perfect code" or "never modify production data without explicit confirmation."

Block 02

Stack rules

Exact tools, versions, and how Claude should use them. Not "we use Next.js." Instead: "Stack is Next.js 16 App Router. No Pages Router. Tailwind for styling. Framer Motion for animation. If you need state, use Zustand — not Redux, not 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 but project-wrong choice. Example from our files: "Never run git push without confirmation. Never use git add . — stage files by name. Never suggest paid external services; every 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 not send cold email to addresses you have not verified exist. Do not re-open the Septim Gauge vertical. Do not amend existing commits — create new ones." This block is where you put the decisions that were made by a human and should not be revisited.

Block 05

File hygiene

Where things live and 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, never inline. No env vars hardcoded anywhere, use process.env.VARNAME with a fallback error." Without this, Claude makes files wherever they fit the current task, and the repo fragments.

Block 06

Review policy

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

Block 07

Test policy

The exact test command and the trigger conditions. "Run npm test before every 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 next task — do not skip."

Block 08

Deploy style

How you deploy and any manual steps in the chain. Ours: "Deploy is vercel --prod from the project root. If the Vercel CLI OOMs, use vercel deploy --prebuilt with the build artifact. Do not deploy if there are uncommitted changes. After deploy, verify at the production URL before closing the task." Claude will improvise a deploy path if you do not give it one.

Block 09

Commit style

Format, scope, and 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 use --no-verify unless the user explicitly asks."

Block 10

Session hygiene

When to compact, when to start fresh, and any known session-size limits. From our own CLAUDE.md: "Run /compact every ~2 hours of heavy work. If a session transcript grows past ~20 MB on-disk JSONL, start fresh and link back to this file. The last session crashed at 33 MB (STATUS_BREAKPOINT). Don't let it repeat." This is the block nobody writes until they lose work.

Want this done for your codebase, not just described?

Septim Session is a one-hour working engagement. We audit your existing CLAUDE.md (or create one from scratch), wire up the 10-block structure for your specific stack, and deliver a working file you can use immediately. $149.

Book Septim Session $149 → Agents Pack $49 →

3. Five failure modes to avoid

These are not hypothetical. Each one is a pattern pulled from threads on r/ClaudeAI, r/LocalLLaMA, and 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 and reduce adherence." We have seen files at 600+ lines that contradicted themselves four times over. Claude does not skip sections — it reads everything and reconciles conflicts with its own judgment. If you would not re-read a section of your file before every session, it probably should not be there. Split large files using @path imports or .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 not fail visibly — Claude acknowledges them and proceeds with its own interpretation. You will not know the rule failed until you see output you did not 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 use shell commands, read files, write files, run tests, and more. If your CLAUDE.md does not specify which tools Claude may use freely versus which require confirmation, Claude defaults to proceeding on most things. This is fine in a sandbox. In a project with production Stripe webhooks and a live database, "run the migration" is not a command you want auto-executed. Block 06 (review policy) and Block 04 (do-not list) together cover this — but only if you write them explicitly.

Failure mode 4: no kill-switch guidance

What should Claude do when it hits a situation it cannot resolve? Most CLAUDE.md files are silent on this. Claude then picks the most confident-looking option and keeps going. The better pattern: a short escalation ladder in your prime directive. "If uncertain, ask. If blocked on a tool permission, stop and describe what you need." This does not eliminate Claude judgment errors, but 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, earlier 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 not be in the active context window by hour three. The Anthropic docs confirm: "Project-root CLAUDE.md survives compaction" — but only if you actually compact. Block 10 (session hygiene) is not optional for anyone running long sessions.

4. A paste-ready CLAUDE.md template

Sixty lines. Every block labeled. Replace the placeholder values with your own stack. This is 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.