CLAUDE.md Best Practices: Karpathy's 4 Principles + 6 Ready-to-Use Templates

Originally published on AI Workflow Pro CLAUDE.md Best Practices: Karpathy''s 4 Principles + 6 Ready-to-Use Templates (2026) Empty or stuffed with boilerplate - both end the same way. Weeks spent auditing real files on GitHub, from 185K-star behavioural principles to a maintainer's commit rules. Four-layer scope, five teardowns, six templates by role, and an anti-pattern audit for business process automation. Copy Borrowed procedure documents fail in a predictable way: half the lines were written for somebody else's constraints, so people stop trusting any of it. A boutique law practice that copies a large firm's intake checklist gets six steps referencing departments it does not have, and within a month the checklist is decoration. Rule files for business process automation go the same way - most people either leave the file empty or paste in boilerplate they cannot defend line by line. This article takes apart five real files in public use, then hands over six templates sorted by role so you start from one that matches your actual work. Your CLAUDE.md is either empty or stuffed with /init boilerplate. Both produce the same result: Claude Code forgets your preferences the moment a new session starts. I spent weeks auditing real CLAUDE.md files across GitHub — from Karpathy's 185K-star behavioral principles to Anthropic's own internal config to Dan Abramov's commit message constraints. The pattern became obvious: most people either write too much (and Claude ignores half of it) or write things Claude already knows from reading the codebase. This guide does two things. First, I break down what actually works in five high-profile CLAUDE.md files and why. Then I hand you six complete templates — frontend dev, backend dev, solo founder, content creator, data analyst, and student — so you can copy the one that fits and start shipping. What you get: The four-layer scope system and how Claude actually loads your config Five real-world CLAUDE.md teardowns with full analysis Six ready-to-use templates organized by role The router pattern for projects that outgrow a single file An anti-pattern checklist to audit your existing setup Why Does CLAUDE.md Matter More Than Any Other Config? Claude Code starts every session with a blank slate. The architecture discussion from yesterday, the code style you corrected for an hour, the deployment gotcha only you know about — all gone. CLAUDE.md is the only file that loads automatically into every session. Each rule you write works for you even when you say nothing. HumanLayer founder Kyle put it well — a single bad line in CLAUDE.md cascades like dominoes: One wrong instruction -> Every research step follows the wrong lead -> Plans built on bad research drift further -> Code written from drifted plans breaks in production The reverse holds too. One correct line saves time across every session and every task. Think of CLAUDE.md as the onboarding doc you write for a new teammate. Write it well, and they ramp up fast with fewer mistakes. Write it too long or too vague, and they skip it entirely — worse than having no doc at all. How Does Claude Code Actually Load Your CLAUDE.md? Before you write anything, understand the mechanics. Everything below comes directly from Anthropic's official documentation . What Are the Four Scope Layers? Most people think CLAUDE.md is a single file at the project root. It is actually a layered system. Claude Code loads four layers at startup, in order: Layer Location Who uses it Managed policy /Library/Application Support/ClaudeCode/CLAUDE.md (macOS) Entire organization User instructions ~/.claude/CLAUDE.md You personally, across all projects Project instructions ./CLAUDE.md or ./.claude/CLAUDE.md Team-shared, committed to Git Local instructions ./CLAUDE.local.md You personally, current project only, not in Git All four layers stack — later layers do not override earlier ones. Subdirectory CLAUDE.md files are smarter: they load only when Claude reads files from that directory. Why Does Claude Sometimes Ignore Your Rules? CLAUDE.md is not a hard command. It is injected as a "user message" into the conversation. When injected, Claude Code attaches a system reminder that says roughly: "This context may or may not be relevant to your current task. Only reference it when actually relevant." Claude decides which rules apply. The longer your file and the more irrelevant content it contains, the higher the probability that useful rules get skipped. I hit this myself running a multi-project knowledge base with Claude Code. My CLAUDE.md grew past 400 lines and Claude started ignoring database conventions while editing frontend components. The fix: split domain-specific rules into .claude/rules/ with paths: constraints so they only load when Claude touches matching files. Common trap: You write an entire database design spec in CLAUDE.md. Claude edits a React component and skips all of it. Not a bug — Claude judged those rules irrelevant to the current task. Solution: put module-specific rules in .claude/rules/ with paths: fields to scope them. What Should You Include (and Exclude)? Anthropic's best practices doc gives a practical checklist: Include: Build commands Claude cannot guess from code (e.g., pnpm test:e2e --filter=@app/web) Code style deviations from conventions (e.g., your team bans default exports) Test runner and framework details Branch naming conventions and PR habits Why you made an architecture decision (not just "use X" but "use X because Y") Dev environment quirks (e.g., must source a specific env file first) Counter-intuitive gotchas Exclude: Things Claude can infer from code — you have tsconfig.json, so "this project uses TypeScript" adds zero value Standard language conventions — Python uses snake_case by default Large API docs — link to them, do not paste them in Frequently changing info — you will forget to sync CLAUDE.md and create stale instructions File-by-file code descriptions — Claude reads directory structure on its own "Please write high-quality code" — this instruction is unverifiable and changes nothing If a rule matters enough, prefix it with IMPORTANT or YOU MUST to add weight. But do not overuse emphasis — when every rule screams IMPORTANT, none of them are. What Do the Best CLAUDE.md Files Actually Contain? Five real-world configs, fully analyzed. Every file comes from a public repository. Case 1: Karpathy's Four Principles (185K Stars) Andrej Karpathy — former Tesla AI director, OpenAI co-founder. His behavioral principles, collected in this GitHub repository , earned over 185,000 stars, making it the most widely shared single CLAUDE.md file. It contains zero project information. The entire file does one thing: constrain how the AI thinks. The four principles distilled: Think before you code — State assumptions. List multiple interpretations. Propose simpler alternatives. Stop and ask when something is unclear. Simplicity first — Solve with minimum code. No features nobody asked for. No abstractions for one-time code. No "flexibility" or "configurability" nobody requested. If 200 lines can become 50, rewrite. Gut check: would a senior engineer look at this and think it is over-engineered? Surgical changes — Touch only what must change. No drive-by refactors. No formatting fixes on adjacent code. Match existing style. Clean up orphaned references your change created, but leave pre-existing dead code alone. Every diff line must trace back to the user's request. Goal-driven execution — Convert tasks into verifiable goals ("add validation" becomes "write test, then make it pass"). Multi-step tasks get a plan with verification at each step. These four principles belong in your global ~/.claude/CLAUDE.md so they apply to every project automatically. Case 2: Anthropic's Own claude-code-action (42 Lines) Anthropic's claude-code-action CLAUDE.md is what their own team uses in production. The most valuable section is "Gotchas" — six traps that come from actual development experience: Strict TypeScript enables noUnusedLocals and noUnusedParameters — unused variables break the build GitHubContext is a discriminated union type — you must narrow with isEntityContext() before property access Token revocation lives in action.yml's always() step — moving it to run.ts means it never executes on process crash The catch block in run.ts uses prepareCompleted to distinguish preparation-phase from execution-phase failures action.yml outputs reference Step IDs (steps.run.outputs.*) — changing a Step ID without updating references breaks the pipeline Integration tests live in a separate repo — this repo only has unit tests Notice: every single gotcha describes something that actually went wrong. These are not hypothetical rules invented in advance. Case 3: Dan Abramov's overreacted.io (52 Lines) React core developer Dan Abramov wrote a CLAUDE.md for his personal blog overreacted.io . The standout feature is commit message constraints with explicit positive and negative examples: Wrong: "Refactor component for improved maintainability" Right: "Extract date formatting to lib/formatDate.ts" He does not just tell Claude how to write code. He tells Claude how to communicate about code — down to filename-level specificity. Case 4: Vercel's next-devtools-mcp (118 Lines) Vercel's next-devtools-mcp represents enterprise engineering standards. The core strategy: freeze the most common operations into standard step sequences. Adding a new tool, adding a new resource, adding a new prompt — each operation has deterministic steps. Claude never guesses which files to modify: Create file in src/tools/ (export inputSchema/metadata/handler) Register in src/index.ts tools array Build and test This removes the entire class of errors where Claude changes the right code in the wrong file. Case 5: Karpathy's llm-council (133 Lines) Karpathy's own project llm-council has a detailed project-level CLAUDE.md — completely different from his four principles. It describes every backend file's key functions, the three-stage pipeline architecture, anonymization strategy for peer review, and four common traps. The takeaway: the four principles handle thinking habits (global), while llm-council's CLAUDE.md handles project-specific context (project-level). Karpathy uses both. What Two Patterns Emerge? Dimension Behavioral constraints Project context Examples Karpathy's four principles Anthropic / Vercel / Dan Abramov Location ~/.claude/CLAUDE.md (global) ./CLAUDE.md (project-level) Content Thinking habits, simplicity, change discipline Architecture, commands, gotchas, conventions Length 30-65 lines 55-130 lines Use both. They complement each other. What Can We Learn From Other Community CLAUDE.md Files? The English-language cases above are well known. But developers across the broader community have produced equally instructive configs. overtrue — The Safety-First Approach The author of EasyWeChat, a major Laravel developer, published a CLAUDE.md with six sections, each solving a specific class of problem: Hard prohibitions: No git reset/revert/rebase/restore. No rm -rf. Every git operation requires user permission first. Core beliefs: Incremental progress over big-bang rewrites. Study existing patterns before implementing. Pragmatic over dogmatic. Implementation flow: Understand → Test (red) → Implement (green) → Refactor → Verify → Update TODO → Commit. After 3 failed attempts, stop and explain. Compiler error handling: Never delete code to bypass compiler errors. Correct path: error → understand root cause → research fix → apply. Every rule maps to a concrete problem that actually happened. "Never delete code to bypass compiler errors" exists because Claude literally did that. Consensus From the Developer Community Several high-engagement posts converge on the same insights: "Start with an empty file." Developer Chen Cheng (610 likes on X) advises: do not start with a template. Start blank. Every time you repeat a correction to Claude, write it into CLAUDE.md. The file you build this way has zero wasted lines. "400 lines to 150. Everything improved." Axel Bitblaze (1,900 likes) used Claude Code for two months straight. His CLAUDE.md ballooned to 400 lines and Claude started randomly ignoring rules. He cut it to 150 lines and compliance jumped back up. "Apple ships CLAUDE.md internally." In 2026, Apple accidentally shipped internal CLAUDE.md files in a Support App update (13,500 likes on X), confirming their teams use Claude Code for app development. Apple pushed an emergency patch to remove the files. Four Anti-Patterns Worth Memorizing From a 2,100-star best practices doc: Do not front-load restrictions. Add rules one by one as Claude makes actual mistakes. Do not blindly @ reference files. Every @-referenced file loads into context every session. Write when to read the file and what to get from it. Do not say only "never do X" — give the alternative. "Never use Redux" leaves Claude guessing. "Never use Redux; use Zustand" resolves the ambiguity. If your CLAUDE.md needs half a page to explain a CLI tool, the tool needs simplification. Write a bash wrapper instead of a manual in CLAUDE.md. What Patterns Make a CLAUDE.md Actually Work? After studying dozens of real configs, four patterns hold: Effective CLAUDE.md files are short. React.dev: 42 lines. Karpathy: 65 lines. Anthropic: 42 lines. overtrue: under 100 lines. None exceeded 200 lines. Effective CLAUDE.md files grow from real mistakes. Boris Cherny (Claude Code core author) runs the simplest process: every time Claude makes an error, someone writes "don't do that" into CLAUDE.md. He calls this compound interest engineering — the file improves over time, and Claude's error rate drops continuously. Effective CLAUDE.md files use two layers. Global for thinking style (Karpathy's four principles). Project-level for concrete context (commands, architecture, gotchas). Two layers, zero overlap. Effective CLAUDE.md files waste no words. They skip what Claude can infer from code, skip standard conventions, skip "please write quality code." The test for every line: if I delete this, will Claude actually make a worse mistake? If not, delete it. How Should You Structure a CLAUDE.md for Your Role? Six templates below. All follow the same structure: identity and context first, working method second, constraints embedded in each rule (not listed separately), and delivery standards last. This ordering mirrors how Claude processes context — role first, then behavior, then specifics. Frontend Developer Template # [Project Name] ## Stack - Next.js 15 App Router + React 19 + TypeScript strict (no Pages Router / any / @ts-ignore) - Styling: Tailwind CSS v4 (no CSS Modules / styled-components / inline style objects) - State: Zustand (no Redux) - Package manager: pnpm (no npm / yarn) ## Commands - `pnpm dev` — development server - `pnpm build` — production build - `pnpm test` — run tests - `pnpm typecheck && pnpm lint` — must pass before every commit ## Code Conventions - Functional components + hooks only. Max 200 lines per file - Props interfaces: named `{ComponentName}Props`, always exported - Named exports everywhere (exception: page.tsx / layout.tsx) - Commit messages: state what changed and why. Never write "refactor for better maintainability" ## Gotchas - `src/lib/auth.ts` session logic looks simplifiable — do not touch it. It handles three edge cases; removing any one breaks production auth - Database migration files are immutable once committed — create a new migration instead Backend Developer Template # [Project Name] ## Stack - Python 3.12 + FastAPI (no Flask / Django) - Database: PostgreSQL + SQLAlchemy async (no sync sessions) - Package manager: uv (no pip / poetry / conda) - Type hints: mandatory on all function signatures (params + return) ## Commands - `uv run uvicorn app.main:app --reload` — dev server - `uv run pytest -x -q` — tests (stop on first failure) - `uv run ruff check . && uv run ruff format --check .` — lint + format check - `uv run alembic upgrade head` — apply migrations ## Architecture - `app/` — application code; `app/api/` — route handlers; `app/models/` — SQLAlchemy models; `app/services/` — business logic - All database queries go through services, never in route handlers directly - Background tasks use `app/tasks/` with Celery (no inline async background) ## Conventions - Endpoints return Pydantic response models, never raw dicts - Errors raise custom exceptions from `app/exceptions.py` — caught by global handler - Environment config: `app/config.py` reads from `.env` via pydantic-settings (no os.getenv scattered in code) ## Gotchas - `alembic/versions/` migration files are immutable after merge to main - The `/health` endpoint bypasses auth middleware intentionally — do not add auth - Rate limiting on `/api/v1/generate` is set at 10 req/min per user — changing it requires updating both middleware and docs Solo Developer / One-Person Company Template # [Business Name] ## Business Overview - Product A: [name + positioning + stack] (primary revenue) - Product B: [name] (side project) - Content channels: Newsletter, blog, social - Revenue: subscription + one-time purchases - Product-specific rules live in each product's own CLAUDE.md. This file governs cross-product decisions only. ## Working Principles - Incremental changes over big rewrites - Use existing tools — auth/payments/email/storage go through SaaS APIs - Change one thing at a time. Confirm it works before changing the next - After 3 failed attempts, stop and explain what is blocking - State your plan before executing. Wait for confirmation - Validate before building: minimum viable test of every idea - Priority: acquisition > retention > monetization ## Safety Boundaries - `git reset` / `revert` / `rebase` / `rm -rf` — never execute - Secrets go in environment variables or credential manager. Never hardcode - Production database: no CLI write operations - Deleting files or directories: inform and get confirmation first - Paid operations (sending email, calling paid APIs, deploying to production): confirm first ## Decision Framework (in order) 1. Can I validate this in under 1 hour? If yes, try it now 2. Is it reversible? If yes, move fast 3. How large is the blast radius? If it only affects me, do it 4. Is there a simpler approach? If yes, switch Content Creator Template # [Brand Name] ## Identity - Positioning: [one sentence] - Audience: [age range + background] - Tone: professional but not academic, opinionated but not combative - First person: "I" (never "the author" / "we" / "this article will show you") - Banned words: synergy, leverage, unlock, game-changer, deep dive, paradigm shift ## Creation Workflow 1. **Topic evaluation** — answer three questions: why would the reader care, what unique angle do I bring, is the timing right 2. **Research** — finish reading before writing, never research mid-draft 3. **Outline** — list H2s first, each H2 answers one specific reader question. No drafting until outline is confirmed 4. **First draft** — prioritize completeness over polish 5. **Self-review** — for each paragraph ask "what would the reader miss if I deleted this?" For each data point ask "what is the source?" 6. **Final draft** — trim, polish, add image placement notes ## Writing Rules - Conclusion first. Setup never exceeds 3 sentences - Data and examples over opinions and adjectives - Technical terms: explain once on first use, then use directly - One idea per paragraph - If you can say it in one sentence, do not write a paragraph ## Quality Checklist - [ ] Readable in a single pass without re-reading - [ ] Every claim has supporting evidence - [ ] First three lines make a stranger want to keep reading - [ ] Image positions are marked - [ ] Zero banned words Data Analyst Template # [Project Name] ## Methodology - Look at data before choosing methods: run descriptive statistics and distribution plots first, then select the approach - Normality test (Shapiro-Wilk) is the fork: normal → parametric tests, non-normal → non-parametric - Multiple comparisons require correction (Bonferroni or FDR) - Effect sizes and confidence intervals over p-values alone - One chart, one question ## Data Management - Raw data: `data/raw/` (read-only, never modified) - Processed data: `data/processed/` - Every processing step logged in `data/processing_log.md` (what was done, how many rows affected, missing value strategy + rationale) - Variable names: snake_case, self-explanatory (`user_age` not `ua`) - Parameters in `config/` files, never hardcoded - All paths relative ## Visualization - Chart type follows data relationship: trend → line, comparison → bar, distribution → histogram/boxplot, relationship → scatter, composition → stacked bar (pie chart only with 5 or fewer categories) - Visual parameters centralized in `config/plot_style.py` - Scientific bar charts include error bars (label SD or SEM) - Every chart needs: title, axis labels with units, legend ## Reporting - APA format: `M = 3.45, SD = 1.23, t(58) = 2.41, p = .019, d = 0.82` - State direction: "Group A scored significantly higher than Group B" not "the difference was significant" - Decimals: 2 places for values, 1 place for percentages, consistent throughout ## Reproducibility - Every script: header comment with input/output/purpose - Random seed: 42 everywhere - Dependencies locked in `pyproject.toml` managed by uv - Anyone running `uv run python scripts/{name}.py` must get identical output - Exploration: Jupyter notebooks. Final deliverables: `.py` scripts Student / Beginner Template # My Learning Projects ## How I Want to Learn - Explain what the code does before writing it - Show me the simplest version first, then add complexity one layer at a time - When I make a mistake, explain what went wrong and why — do not silently fix it - Use comments generously in code examples - If I ask for something beyond my current level, say so and suggest what to learn first ## My Current Stack - Python 3.12 (learning) - VS Code - Git basics (commit, push, pull — I do not know rebase yet) ## Rules - No advanced patterns I have not learned yet (no decorators, metaclasses, or async until I ask) - Variable names must be descriptive (`student_name` not `sn`) - Every function gets a docstring - Suggest breaking the task into smaller steps when it gets complex ## When I Get Stuck - Ask me what I think the error means before giving the answer - Point me to the relevant documentation section - If I have been stuck for 3 rounds, give me the direct answer with a full explanation What Do All Six Templates Share? Every template follows the same order: Who you are / big picture — Claude understands context first How you work — workflow, methodology, decision framework Boundaries embedded in rules — "use uv (no pip/poetry/conda)" packs both the do and the don't into a single line What to do when stuck — flag uncertainty, stop after N attempts, ask Delivery standard — what "done" looks like Constraints sit inside rules rather than in a separate "prohibited" block at the top. A CLAUDE.md that opens with a wall of "never do A, never do B, never do C" signals "this user cares about me not making mistakes" rather than "here is what this project needs." Context first, constraints inline — that matches how Claude processes instructions. When Should You Switch From One File to a Router Architecture? Small projects: one CLAUDE.md file handles everything. When rules exceed 200 lines, switch to a router pattern. Single-File Pattern project-root/ └── CLAUDE.md AGENTS.md) for cross-tool compatibility. Does CLAUDE.md support non-English languages? Fully. CLAUDE.md is a standard Markdown file with no language restriction. Declare your interaction language at the top: "Interaction language: English" or any language you prefer. The most important step is the one only you can take. Open your project, create an empty CLAUDE.md, and start using Claude Code. Every time it makes a mistake, add one line. After a week, that file will outperform any template — because every rule in it comes from your own experience. — Leo Published in: Technology , Agentic Coding , Beginner , Claude Code Author Download more icon variants from https://tabler-icons.io/i/brand-youtube I take real work from real industries and rebuild it with AI agents — the setup, the failures, the numbers. View articles Why Does CLAUDE.md Matter More Than Any Other Config? How Does Claude Code Actually Load Your CLAUDE.md? What Do the Best CLAUDE.md Files Actually Contain? What Can We Learn From Other Community CLAUDE.md Files? What Patterns Make a CLAUDE.md Actually Work? How Should You Structure a CLAUDE.md for Your Role? When Should You Switch From One File to a Router Architecture? How Do You Build a CLAUDE.md From Zero in One Week? What Does a Before-and-After Rewrite Look Like? What Are the Six Most Common CLAUDE.md Mistakes? How Do CLAUDE.md, Skills, and Hooks Work Together? Quick Audit Checklist Related Reading Ready-to-Use Prompt: Author a Tight CLAUDE.md for Your Role Frequently Asked Questions