The Problem

Claude Code and similar LLM coding agents frequently make silent assumptions, overengineer solutions, and modify code unrelated to the task. Andrej Karpathy documented these failure modes in a widely-shared post; this repo packages his observations into a single CLAUDE.md file that steers agent behavior.

What This Does

The repository is three Markdown files, no code. CLAUDE.md defines four behavioral principles for Claude Code: Think Before Coding (surface assumptions, push back), Simplicity First (no speculative abstractions), Surgical Changes (touch only what the task requires), and Goal-Driven Execution (tests-first, verifiable success criteria). A copy of the same content lives in .claude/skills/karpathy-guidelines.md for the alternative installation path, and README.md documents both.

The entire value is the prompt text itself. There is no logic, no runtime, nothing to execute.

How It Is Wired

There is no control flow to trace. The repository contains no entry points, no functions, no external effects. The wiring is installation-dependent:

  • Option A: copy CLAUDE.md into a project root. Claude Code reads it automatically on session start.
  • Option B: place karpathy-guidelines.md under .claude/skills/ to make it available as a skill.

The README.md install commands reference forrestchang/andrej-karpthy-skills (note the typo in the repo name) rather than this fork, so the curl URLs in the README will fail against this repository. Use the files directly.

How To Use It

Setup: clone the repository and copy the file into your project:

git clone https://github.com/moses-y/andrej-karpathy-skills
cp andrej-karpathy-skills/CLAUDE.md /path/to/your/project/

Configuration: none. The file is plain Markdown with no variables or placeholders.

Running it: start a Claude Code session in the project directory. The agent reads CLAUDE.md automatically; no further action required.

Real-World Use

Drop CLAUDE.md into a codebase where an agent has been making unwanted edits. The next session begins with the agent constrained to state assumptions before coding, avoid speculative abstractions, and leave adjacent code untouched. For a team, commit the file to the repo so every contributor's agent session inherits the same guardrails.

Code Health & Issues

Static analysis of this repository found:

  • Medium - no test files - repository-wide. Expected for a documentation-only repo; nothing to test.
  • Medium - no CI/CD pipeline - no .github/ or CI config. Again expected; there is no build step.
  • Medium - no LICENSE file - root. This is the real concern. The upstream repo is MIT-licensed, but this fork carries no license, so redistribution rights are unclear.

One additional observation: the README's install commands point at forrestchang/andrej-karpthy-skills, which is misspelled and does not match this repository's URL. Copy the files manually rather than trusting the curl commands.

The Bottom Line

A useful, well-written prompt file that translates Karpathy's critique into actionable agent instructions. It does exactly one thing and does it clearly. The missing license is the only substantive issue — if you plan to redistribute this, clarify licensing first. For anyone using Claude Code on real codebases, the four principles are worth adopting.