TL;DR
Andrej Karpathy (OpenAI co-founder, ex-Tesla AI Director) shared his frustrations with AI coding agents. Someone turned his observations into 4 actionable principles in a single CLAUDE.md file. 14,500+ GitHub stars. 30-second install.
The Problem: Karpathy's 4 Observations
After delegating 80% of his coding to AI agents in late 2025, Karpathy posted his findings on X (75M+ views):
1. Wrong Assumptions
"The model makes assumptions on your behalf and just runs with them. It doesn't manage confusion, doesn't seek clarification, doesn't surface inconsistencies, doesn't present trade-offs, doesn't push back when it should."
2. Over-Engineering
"Over-complicates code and APIs, inflates abstractions, doesn't clean dead code... implements 1,000 lines when 100 would do."
3. Unrelated Changes
"Changes/deletes code or comments orthogonal to the task due to lack of understanding."
4. Missing Declarative Approach
"LLMs are great at looping until they achieve a specific goal. Don't tell them what to do—give them success criteria and watch."
The Solution: 4 Principles in CLAUDE.md
The andrej-karpathy-skills project encodes these into a CLAUDE.md file that Claude Code reads on every session:
Principle 1: Think Before Coding
- State assumptions explicitly
- If multiple interpretations exist, present them (don't silently pick one)
- Push back if there's a simpler way
- If confused, stop and ask
Principle 2: Simplicity First
- No features beyond what's requested
- No abstractions for one-time code
- No unrequested "flexibility" or "configurability"
- If 200 lines can be 50, rewrite
- Test: "Would a senior engineer say this is overkill?" → simplify
Principle 3: Surgical Changes
- No "improving" adjacent code, comments, formatting
- No refactoring what isn't broken
- Match existing style (even if you disagree)
- Dead code: mention, don't delete
- Only clean up orphans YOUR changes created
- Test: every changed line traces to user request
Principle 4: Goal-Driven Execution
| Instead of | Say |
|---|---|
| "Add validation" | "Write a test for invalid inputs and make it pass" |
| "Fix the bug" | "Write a reproduction test and make it pass" |
| "Refactor X" | "Ensure tests pass before and after" |
Strong success criteria = LLM loops independently. Weak criteria = constant clarification needed.
Install (30 seconds)
Option A: Claude Code Plugin
/plugin marketplace add forrestchang/andrej-karpathy-skills
/plugin install andrej-karpathy-skills@karpathy-skills
Option B: Direct download
curl -o CLAUDE.md https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md
Why This Matters
The takeaway isn't just about this specific project. It's that system-level constraints beat ad-hoc prompting. A CLAUDE.md file runs on every Claude Code session automatically. No need to remember to prompt these principles every time.
14,500 stars on a single markdown file tells you something: in the age of agentic engineering, your system prompt IS your engineering skill.
Have you tried this or a similar approach? Drop your experience in the comments.
Top comments (0)