~/wiki
Récent+ Ajouter

Karpathy-Inspired Claude Code Guidelines

Mis à jour le 2026-04-14Confiance : high
claude-guidelinesllm-codingcode-qualityandrej-karpathy

A practical implementation of andrej-karpathy's observations about LLM coding pitfalls, packaged as guidelines for improving Claude Code behavior. Created by Forrest Chang as a single CLAUDE.md file that addresses common issues in LLM-generated code.

Origin and Problem Statement

Based on Karpathy's insights about LLM coding problems:

  • Models make wrong assumptions and run with them without checking
  • They don't manage confusion, seek clarifications, or surface inconsistencies
  • They overcomplicate code with bloated abstractions
  • They change/remove code orthogonal to the task without understanding

The Four Core Principles

1. Think Before Coding

Addresses: Wrong assumptions, hidden confusion, missing tradeoffs

Implementation:

  • State assumptions explicitly - if uncertain, ask rather than guess
  • Present multiple interpretations - don't pick silently when ambiguity exists
  • Push back when warranted - if simpler approach exists, say so
  • Stop when confused - name what's unclear and ask for clarification

2. Simplicity First

Addresses: Overcomplication, bloated abstractions

Implementation:

  • No features beyond what was asked
  • No abstractions for single-use code
  • No "flexibility" or "configurability" that wasn't requested
  • No error handling for impossible scenarios
  • Test: Would a senior engineer call this overcomplicated?

3. Surgical Changes

Addresses: Orthogonal edits, touching code you shouldn't

When editing existing code:

  • Don't "improve" adjacent code, comments, or formatting
  • Don't refactor things that aren't broken
  • Match existing style, even if you'd do it differently
  • Test: Every changed line should trace directly to user's request

4. Goal-Driven Execution

Addresses: Lack of verifiable success criteria

Transform imperatives into verifiable goals:

  • "Add validation" → "Write tests for invalid inputs, then make them pass"
  • "Fix the bug" → "Write a test that reproduces it, then make it pass"
  • "Refactor X" → "Ensure tests pass before and after"

Installation Methods

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

Per-Project CLAUDE.md

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

# Existing project (append)
curl https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md >> CLAUDE.md

Key Architectural Insight

Leverages Karpathy's observation: "LLMs are exceptionally good at looping until they meet specific goals... Don't tell it what to do, give it success criteria and watch it go."

This shifts from imperative instructions to declarative goals with verification loops - a fundamental change in how to interact with coding LLMs.

Success Indicators

Guidelines are working when you observe:

  • Fewer unnecessary changes in diffs
  • Fewer rewrites due to overcomplication
  • Clarifying questions before implementation
  • Clean, minimal PRs without drive-by refactoring

Trade-offs

These guidelines bias toward caution over speed. For trivial tasks, use judgment - the goal is reducing costly mistakes on non-trivial work, not slowing down simple changes.

Integration

Designed to merge with project-specific instructions. Can be combined with existing CLAUDE.md files or used as foundation for team coding standards.

See also