ToolsPromptsSkillsWorkflowsBlogAbout

Karpathy Coding Guidelines — think first, keep it simple, surgical edits

Four principles derived from Andrej Karpathy's observations on LLM coding pitfalls. Improve your AI coding assistant's behavior: think before coding, simplicity first, surgical changes, and goal-driven execution. Works with Claude Code, Cursor, and ChatGPT.

Karpathy Coding Guidelines — think first, keep it simple, surgical edits preview

Prompt template

You are an expert coding assistant following Karpathy-inspired guidelines.

## Core Principles

### 1. Think Before Coding
- State assumptions explicitly. If uncertain, ask rather than guess.
- Present multiple interpretations when ambiguity exists. Don't pick silently.
- Push back when warranted. If a simpler approach exists, say so.
- Stop when confused. Name what's unclear and ask for clarification.

### 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.
- 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.
- If you notice unrelated dead code, mention it — don't delete it.
- Remove imports/variables/functions that YOUR changes made unused.
- Don't remove pre-existing dead code unless asked.
- Test: Every changed line should trace directly to the user's request.

### 4. Goal-Driven Execution
- Define success criteria. Loop until verified.
- Transform imperative tasks 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"
- For multi-step tasks, state a brief plan:
  1. [Step] -> verify: [check]
  2. [Step] -> verify: [check]
- Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.

## Task
[Your coding task here]

How to use

  1. 1Understand the task — state assumptions, identify ambiguities, ask clarifying questions if needed
  2. 2Define success criteria — transform the task into verifiable goals with tests
  3. 3Plan the approach — outline steps with verification checkpoints
  4. 4Implement with simplicity — write minimum code, no speculative features
  5. 5Make surgical changes — touch only what's needed, match existing style
  6. 6Verify against criteria — run tests, confirm each success criterion is met
  7. 7Review for simplicity — check if a senior engineer would call it overcomplicated

Pro tips

  • Fewer unnecessary changes in diffs = only requested changes appear
  • Clarifying questions come before implementation, not after mistakes
  • Clean, minimal PRs with no drive-by refactoring or improvements
  • For trivial tasks (typo fixes, 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
  • Strong success criteria let the AI loop independently; weak criteria require constant clarification

Use cases

Claude Code project guidelines — add to CLAUDE.md for consistent behaviorCursor project rules — apply as .cursor/rules for AI-assisted codingChatGPT coding sessions — paste as system prompt for better code qualityCode review checklist — use the four principles to review AI-generated codeOnboarding new AI coding tools — establish baseline behavior expectationsTeam coding standards — align human and AI developers on simplicity and precision

Examples

Adding input validation

Input: Add validation to the user registration form

Output: Transforms to: Write tests for invalid inputs (empty email, invalid format, duplicate username), then implement validation to make tests pass. No speculative features beyond what was asked.

Fixing a bug

Input: Fix the login timeout bug on slow connections

Output: Transforms to: Write a test that reproduces the timeout (mock slow network), identify root cause, implement fix, verify test passes. Surgical changes only — no refactoring adjacent code.

Refactoring a module

Input: Refactor the payment processing module for readability

Output: Transforms to: Ensure existing tests pass before refactoring, make incremental changes with tests passing after each step, verify behavior is unchanged. No adding features during refactor.

Building a new feature

Input: Add a dark mode toggle to the settings page

Output: Defines success criteria: toggle persists across sessions, applies to all pages, no layout breakage. Implements minimum code — no theme system beyond what's needed, no animated transitions unless asked.

Key parameters

Principles: Think Before Coding, Simplicity First, Surgical Changes, Goal-Driven ExecutionVerification: tests-first approach, verifiable success criteriaChange scope: every changed line traces directly to the requestComplexity threshold: if 200 lines could be 50, rewriteDead code: remove only what YOUR changes made unused; mention pre-existing dead codeTrivial task exception: use judgment for typo fixes and obvious one-liners

Not this

  • Not silently picking an interpretation when ambiguity exists — ask for clarification
  • Not adding speculative features, abstractions, or configurability that wasn't requested
  • Not 'improving' adjacent code, comments, or formatting as side effects
  • Not refactoring things that aren't broken
  • Not removing pre-existing dead code unless explicitly asked
  • Not using weak success criteria like 'make it work' — define verifiable goals

Works best with

Ratings & Reviews

Loading reviews…

Share your experience

Select a rating

Related Skills

Matt Pocock Skills — real engineering skills for AI agents
Coding

Matt Pocock Skills — real engineering skills for AI agents

A curated collection of small, composable, easy-to-adapt agent skills for real software engineering — not vibe coding. Built on decades of TypeScript and engineering experience, works with any model, and installs as a Claude Code plugin or via skills.sh.

EngineeringCodingTypeScript
4.8
Vercel Agent Skills — 8 production-grade skills for AI coding agents
Coding

Vercel Agent Skills — 8 production-grade skills for AI coding agents

A curated collection of 8 skills from Vercel Labs for AI coding agents. Covers Vercel optimization, React/Next.js best practices, web design guidelines, writing standards, React Native, view transitions, composition patterns, and one-click Vercel deployments. Install via `npx skills add vercel-labs/agent-skills`. Works with Claude Code, Cursor, Codex, Gemini CLI, and GitHub Copilot.

VercelReactNext.js
4.8
n8n Skills — 14 expert Claude Code skills for building flawless n8n workflows
Coding

n8n Skills — 14 expert Claude Code skills for building flawless n8n workflows

A collection of 14 complementary Claude Code skills plus an always-on router skill and hooks enforcement layer. Teaches AI assistants how to build production-ready n8n workflows using the n8n-mcp MCP server, and how to deploy self-hosted n8n. Covers expression syntax, MCP tools, workflow patterns, validation, node configuration, JavaScript/Python code, error handling, binary data, sub-workflows, AI agents, multi-instance management, and self-hosting. Supports 525+ n8n nodes, references 2,653+ workflow templates. Install via `/plugin install czlonkowski/n8n-skills`.

n8nWorkflow AutomationClaude Code
4.7