andrej-karpathy-skills

AI-Teaching-Assistant-1 Coding Guidelines

Behavioral guidelines combining project-specific rules for AI-Teaching-Assistant-1 with universal LLM coding principles derived from Andrej Karpathy's observations on common LLM coding pitfalls.

English | 简体中文

The Problems (from Andrej Karpathy)

"The models make wrong assumptions on your behalf and just run along with them without checking. They don't manage their confusion, don't seek clarifications, don't surface inconsistencies, don't present tradeoffs, don't push back when they should."

"They really like to overcomplicate code and APIs, bloat abstractions, don't clean up dead code... implement a bloated construction over 1000 lines when 100 would do."

"They still sometimes change/remove comments and code they don't sufficiently understand as side effects, even if orthogonal to the task."

The Solution

Four universal principles + project-specific rules, merged into one coherent set:

Layer	What it provides
Project context	5 bases, working scope, no-touch zones
Core rules	Base flow, reuse-first, surgical changes, simplicity, clean code
Workflow	ANALYZE → WEB SEARCH → PLAN → IMPLEMENT → VERIFY
Base-specific	FastAPI patterns / Vue 3 patterns
Bug-fix	Test-first verification loop

The Four Universal Principles (Karpathy)

1. Think Before Coding

Don't assume. Don't hide confusion. Surface tradeoffs.

• State your assumptions explicitly. If uncertain, ask.
• Present multiple interpretations — don't pick silently when ambiguity exists.
• If a simpler approach exists, say so. Push back when warranted.
• Stop when confused. Name what's unclear, then ask.

2. Simplicity First

Minimum code that solves the problem. Nothing speculative.

• 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.
• If 200 lines could be 50, rewrite it.

The test: Would a senior engineer say this is overcomplicated? If yes, simplify.

3. Surgical Changes

Touch only what you must. Clean up only your own mess.

• 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.
• Remove only YOUR orphans (imports/variables your changes made unused).

The test: Every changed line should trace directly to the user's request.

4. Goal-Driven Execution

Define success criteria. Loop until verified.

Transform every task 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"

For multi-step tasks, state a plan with verification for each step:

1. [Step] → verify: [check]
2. [Step] → verify: [check]

Install

Option A: Claude Code Plugin (recommended)

From within Claude Code:

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

Option B: CLAUDE.md (per-project)

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

Using with Cursor

See CURSOR.md for Cursor setup, using the rule in other projects, and Claude Code vs Cursor differences.

Key Insight

From Andrej:

"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."

The "Goal-Driven Execution" principle captures this: transform imperative instructions into declarative goals with verification loops.

How to Know It's Working

• Fewer unnecessary changes in diffs — Only requested changes appear
• Fewer rewrites due to overcomplication — Code is simple the first time
• Clarifying questions come before implementation — Not after mistakes
• Clean, minimal PRs — No drive-by refactoring or "improvements"

Tradeoff Note

These guidelines bias toward caution over speed. For trivial tasks (simple typo fixes, obvious one-liners), use judgment — not every change needs full rigor.

The goal is reducing costly mistakes on non-trivial work, not slowing down simple tasks.

License

MIT