forrestchang/andrej-karpathy-skills

⭐ 123,023  ·  None  ·  GitHub Repo

A single CLAUDE.md file to improve Claude Code behavior, derived from Andrej Karpathy's observations on LLM coding pitfalls.

1-Sentence Summary

A single CLAUDE.md file encoding Karpathy's wisdom to stop LLM agents from overcomplicating your code.

🔥 Key Capabilities & USP

• Think Before Coding — Forces the LLM to explicitly state assumptions, consider multiple interpretations, and push back on ambiguous or bad requests. Solves the pain point of agents blindly executing flawed instructions without critical thought.
• Simplicity First — Mandates minimum code that solves the exact problem with zero speculative features, abstractions, or unnecessary flexibility. Directly combats the #1 LLM pitfall: overengineering trivial solutions into complex frameworks.
• Surgical Changes — Restricts edits strictly to what the user requested, preventing the agent from "improving" adjacent code, refactoring unrelated functions, or deleting pre-existing dead code. Eliminates the frustration of finding your project subtly rewritten.
• Goal-Driven Execution — Transforms imperative tasks into verifiable goals with success criteria and verification loops. Leverages the LLM's strength at iterating toward specific targets rather than following brittle step-by-step instructions.

USP: This isn't another prompt template—it's a behavioral constitution derived directly from Andrej Karpathy's specific critiques of LLM coding failures, packaged as a one-file drop-in for Claude Code and Cursor.

Technical Architecture

Component	Description
Core File	Single CLAUDE.md file containing four behavioral principles as structured markdown
Plugin System	Installable via Claude Code's plugin marketplace (/plugin marketplace add forrestchang/andrej-karpathy-skills)
Per-Project Mode	Directly appended to any project's existing CLAUDE.md via curl
Cursor Support	Alternative rule file format for Cursor IDE compatibility
Dependencies	Zero — no packages, no runtime, no build step

The architecture is intentionally minimal: a configuration file that modifies agent behavior at the instruction-following layer, not the model layer. It works by overriding Claude Code's default action tendencies with explicit guardrails.

Quick Start Guide

Option A: Claude Code Plugin (recommended for global use)

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

Option B: Per-project CLAUDE.md (new project)

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

Option C: Per-project CLAUDE.md (append to existing)

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

Pros, Cons & Use Cases

Pros

• Directly addresses known LLM coding pitfalls — not generic advice, but specific behavioral constraints that prevent the most common and costly mistakes
• Trivial installation — one curl command or two plugin commands; no config files, no dependencies, no learning curve
• Dual ecosystem support — works with both Claude Code and Cursor out of the box
• Caution-biased design — reduces costly mistakes by default, which is the right tradeoff for non-trivial projects

Cons

• Slows down trivial tasks — the full reasoning and verification rigor is overkill for simple scripts or throwaway code
• Requires user judgment — you need to know when to disable or bypass the guidelines for speed-critical work
• Ecosystem lock-in — only works with Claude Code and Cursor; no support for Copilot, Codeium, or other coding agents

Who should NOT use this?

• Developers doing rapid prototyping or exploratory coding where speed and iteration frequency matter more than correctness
• Teams using non-Claude coding agents (GitHub Copilot, Amazon Q, Codeium) — this file is ignored by those tools
• Developers who want their LLM agent to aggressively refactor and improve code quality across the project

Ideal Use Cases

• Production codebases where an LLM agent making wrong assumptions could introduce subtle bugs or break existing functionality
• Legacy code maintenance where surgical, minimal changes are critical to avoid cascading failures
• Onboarding new LLM agents to a complex project — the guidelines act as a behavioral contract that prevents the agent from "learning" bad patterns
• Code review automation where you want the agent to explain its reasoning before making changes

Community & Activity

With 123,023 stars, this project has clearly struck a nerve in the developer community. That level of adoption signals that Karpathy's observations about LLM coding pitfalls resonated deeply, and this implementation provides the missing piece: actionable enforcement. The project was last updated on 2026-05-10, indicating active maintenance and relevance. The community momentum suggests this is becoming a de facto standard for Claude Code behavioral guidelines—a testament to the power of shipping a single, well-crafted file that solves a universal pain point.