andrej-karpathy-skills — Content Guide

A four-principle set of behavioral guidelines for Claude Code, distilled from Andrej Karpathy's publicly documented observations about common LLM coding failures. The collection ships as two drop-in formats — a standalone CLAUDE.md file for per-project use, and a Claude Code plugin skill for global use — plus annotated before/after examples that show each principle in action. Intended for any developer using Claude Code who wants fewer silent wrong assumptions, simpler generated code, and cleaner diffs.

What's in This Collection

Note

CLAUDE.md and skills/karpathy-guidelines/SKILL.md carry identical principle content. The only difference is the YAML front matter in SKILL.md required by the Claude Code plugin system. When the principles change, both files must be updated together to stay consistent.

How to Read / Use This

Intended path: there is no required reading order. Start with README.md for the rationale, CLAUDE.md to see the actual rules, and EXAMPLES.md for concrete before/after comparisons.

Prerequisites: Claude Code installed. No specific language or framework background is required — the guidelines are language-agnostic.

Getting the guidelines active — two methods:

Plugin (global — recommended)

/plugin marketplace add forrestchang/andrej-karpathy-skills
/plugin install andrej-karpathy-skills@karpathy-skills

Applies the guidelines across all your Claude Code projects without placing any files in them.

Standalone file (per-project)

curl -o CLAUDE.md https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md

Place at your project root. Claude Code reads it at session start. For projects that already have a CLAUDE.md:

echo "" >> CLAUDE.md
curl https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md >> CLAUDE.md

Tip

The plugin method is the right choice for developers who want the guidelines active everywhere without file management. The standalone file method works best when you need to customize the guidelines or combine them with project-specific rules.

Suggested entry points by reader type:

Tip

Read EXAMPLES.md before installing. The before/after comparisons are the fastest way to judge whether these guidelines match your workflow.

Section Walkthroughs

CLAUDE.md — The Four Principles

This is the product. Claude Code reads this file at session start and adjusts its session behavior accordingly. The file defines four named principles, each targeting a specific LLM coding failure mode:

1. Think Before Coding — Don't assume. Don't hide confusion. Surface tradeoffs.

This principle prevents silent wrong assumptions. Claude is instructed to state assumptions explicitly, present multiple interpretations when a request is ambiguous, push back when a simpler approach exists, and stop to ask rather than guess and run.

2. Simplicity First — Minimum code that solves the problem. Nothing speculative.

This principle combats overengineering. Specific prohibitions: no features beyond what was asked, no abstractions for single-use code, no speculative flexibility or configurability, no error handling for scenarios that cannot happen. If 200 lines could be 50, rewrite it.

3. Surgical Changes — Touch only what you must. Clean up only your own mess.

This principle restricts the scope of edits. When modifying existing code, Claude should not "improve" adjacent code or formatting, not refactor things that are not broken, and match existing style even when it would prefer otherwise. One exception: orphans created by Claude's own edits (unused imports, variables, functions) are cleaned up; pre-existing dead code is left alone.

4. Goal-Driven Execution — Define success criteria. Loop until verified.

This principle transforms vague instructions into verifiable goals. Multi-step tasks get an explicit plan with a verification step after each action. The canonical pattern is test-first: write a test that reproduces the bug, verify the test fails, implement the fix, verify the test passes.

Important

The principles modify Claude's behavior through context injection — there is no executable code. If Claude does not follow them after installation, the most common cause is that the CLAUDE.md file is not located at the project root, or the plugin was not installed correctly. Verify with /plugin list and confirm karpathy-guidelines appears.

The file closes with an explicit tradeoff note: these guidelines bias toward caution over speed. For trivial tasks — typo fixes, obvious one-liners — Claude should apply judgment rather than full rigor.

EXAMPLES.md — Before/After Comparisons

Each example follows a consistent five-part structure:

1. User request — what was asked
2. Wrong approach (with code) — what unconstrained LLMs typically do
3. Problems — specific issues with the wrong approach
4. Correct approach (with code) — what the guidelines produce
5. Explanation — why the correct approach is better

This pattern repeats across all four principles with one to three examples each. Representative examples:

• Think Before Coding: An "export user data" request triggers silent assumptions about format, file location, which fields to include, and scope. With guidelines, Claude lists its assumptions and asks for clarification before writing any code.

• Simplicity First: A "calculate discount" request without guidelines produces an abstract DiscountStrategy class hierarchy with dataclasses and configuration objects. With guidelines, Claude writes a single three-line function.

• Surgical Changes: A bug-fix request without guidelines also adds a docstring, changes comment wording, adds type hints, reformats whitespace, and adds unrelated username validation. With guidelines, only the specific lines that fix the bug change.

• Goal-Driven Execution: A sorting-bug fix goes test-first: reproduce the bug in a test, verify the test fails, implement the fix, verify the test passes — rather than modifying sort logic speculatively.

skills/karpathy-guidelines/SKILL.md — Plugin Definition

This file makes the guidelines installable through Claude Code's plugin/skill system. It carries the same four principles as CLAUDE.md plus YAML front matter:

The install command andrej-karpathy-skills@karpathy-guidelines derives from the GitHub repository name (andrej-karpathy-skills) and the name field in this file (karpathy-guidelines).

Warning

As with any CLAUDE.md file or Claude Code plugin, review the content before installing. Guidelines with malicious instructions could direct Claude to introduce vulnerabilities or behave insecurely during coding sessions. This collection contains no executable code; the full content of all four files is visible on GitHub before installation.

Related Resources

• Andrej Karpathy — the failure modes documented here originate from Karpathy's public writing about LLM coding behavior, particularly observations posted on X about how LLMs make wrong assumptions, overcomplicate code, and introduce orthogonal edits.
• Multica (github.com/multica-ai/multica) — an open-source platform for running and managing coding agents with reusable skills, referenced in the README as a related project by the same author (forrestchang).