CLAUDE.md as Context Engineering: Why Karpathy's Practice Matters

At the root of any well-configured Claude Code project sits a file called CLAUDE.md. It's a plain Markdown document. It contains no executable code. It will never appear in a diff review or show up in your test suite. And yet, for any team that works with Claude Code regularly, it is arguably the most load-bearing file in the repository.

The convention — load project-level behavioral context from a root Markdown file at session start — has become standard practice fast enough that it now has its own ecosystem: template repositories, community-shared examples, skill-packaged variations. The multica-ai/andrej-karpathy-skills repo, which encodes Karpathy's LLM coding pitfall observations into an installable skill, is partly a CLAUDE.md in skill form: behavioral guidelines that apply session-wide, derived from observed failure modes.

Understanding why CLAUDE.md files are powerful requires understanding what context engineering actually is — and what it isn't.

What Context Engineering Is

In Karpathy's Software 3.0 framing (see Software 3.0: Karpathy's Framework Applied to Claude Code), the context window is RAM. What the model knows at the start of a session shapes everything it produces during that session. A bare context produces unconstrained output — technically capable but unanchored to your project's conventions, constraints, or failure modes.

Context engineering is the practice of deliberately loading that context to produce constrained, predictable, high-quality output. CLAUDE.md is the primary instrument for doing this at the project level.

The distinction from "prompt engineering" is meaningful. Prompt engineering typically refers to crafting individual instructions at the point of invocation — writing better task descriptions, few-shot examples, or chain-of-thought prompts. Context engineering is broader: shaping the behavioral environment in which all prompts execute. A well-designed CLAUDE.md means you don't have to re-specify constraints on every invocation.

What Karpathy's Guidelines Add

The karpathy-guidelines skill is a context-engineering artifact. It encodes four behavioral constraints that apply across all coding tasks: think before coding, simplicity first, surgical changes, goal-driven execution.

When installed, these constraints load into the session context at startup — the same way a root CLAUDE.md does. The effect is similar to adding the following to your CLAUDE.md (which you can do directly if you prefer not to install the skill):

• Before implementing, state your assumptions and surface ambiguity
• Write minimum code that solves the stated problem, nothing speculative
• Touch only what the request requires; don't improve adjacent code
• Convert task instructions to verifiable success criteria before starting

These four rules address what Karpathy identified as the specific failure modes LLMs exhibit during coding: overbuilding, silent assumption-making, scope creep, and vague goal specification. They're not aspirational guidelines — they're targeted patches for observed bugs in default LLM behavior.

The Specificity Principle

The most instructive thing about the karpathy-guidelines skill, for anyone designing their own CLAUDE.md, is what it doesn't include. It contains no brand guidelines, no preferred library choices, no architecture patterns, no deployment conventions. It contains only behavioral constraints that apply across all possible coding tasks.

This specificity is deliberate. A CLAUDE.md that tries to encode everything — tech stack preferences, code style, architectural principles, team norms, behavioral constraints — produces a document where everything competes for attention and the most important rules get diluted.

Effective context engineering separates concerns. Behavioral constraints belong in a persistent, project-agnostic layer (or a dedicated behavioral skill). Project-specific conventions belong in the project's CLAUDE.md. Domain knowledge belongs in domain skills. Stacking all three into a single file is the CLAUDE.md equivalent of a God class.

The karpathy-guidelines skill is valuable precisely because it's composable. Install it and it works alongside whatever project-specific CLAUDE.md you've written. The behavioral layer and the project layer don't interfere.

CLAUDE.md Design Patterns

If you're designing a CLAUDE.md for your own project, the karpathy-guidelines structure suggests some patterns worth adopting:

Name the failure mode, not just the desired behavior. "Don't add unrequested abstractions" is more actionable than "write clean code." The failure mode is specific; the remedy is obvious once the failure mode is named.

Provide a test. The karpathy-guidelines skill includes a self-test for the simplicity rule: "Would a senior engineer say this is overcomplicated?" A concrete check is more useful than an abstract principle.

Separate behavioral rules from factual context. "The primary database is Postgres, using Supabase client" is factual context. "Don't refactor code outside the scope of the current task" is a behavioral rule. Both belong in CLAUDE.md, but they operate differently — factual context informs, behavioral rules constrain.

Keep it short enough to re-read. A CLAUDE.md that runs to 400 lines is one that nobody updates and nobody trusts. The karpathy-guidelines skill is 65 lines. The entire document fits in a single screen. If your CLAUDE.md can't be read in two minutes, consider what to cut.

The Network Effect

As CLAUDE.md practice matures, something interesting is happening: the best CLAUDE.md templates are converging on similar behavioral constraints. Teams that share their CLAUDE.md files publicly — and there are now repositories tracking the best-performing examples — consistently include variants of the same four or five rules that the karpathy-guidelines skill encodes.

This convergence suggests that the karpathy-guidelines rules aren't opinionated choices — they're corrections to systematic LLM failure modes that appear reliably enough to show up in independently-developed context files. The fact that Forrest Chang derived them from Karpathy's January 2026 X post, and that similar rules appear in CLAUDE.md templates from teams with no connection to Karpathy, suggests the observations are robust.

The practice of context engineering is still early. Most Claude Code users have no CLAUDE.md at all; many who have one have one that's a copy of a template they didn't fully read. But the teams that have invested in it are consistently producing better output with less per-task friction. That's the return on context engineering: the overhead is front-loaded, and it compounds across every session.

For more on how these constraints connect to Karpathy's broader philosophy, see Karpathy's Skill Authoring Style: Distillation Over Accretion.

---

Part of the Karpathy on Claude Code series. Published 2026-05-23.