Karpathy-Inspired Coding Agent Guidelines

A practical instruction pack that makes coding agents more reliable, simpler, and less destructive.

<a href="./README.md">English</a> · <a href="./README.zh.md">简体中文</a>

> Not affiliated with or endorsed by Andrej Karpathy.

A small instruction pack for coding agents, inspired by public observations from Andrej Karpathy about LLM coding pitfalls.

Why This Exists

Most coding agents fail in the same predictable ways:

They make silent assumptions.
They overengineer straightforward tasks.
They modify unrelated code while fixing one issue.
They execute without clear, testable success criteria.

This repo gives you one coherent fix: a concise behavior contract plus tooling that keeps every distribution format in sync.

The 4 Principles

| Principle | Prevents | | --- | --- | | Think Before Coding | Silent assumptions, hidden confusion, missing tradeoffs | | Simplicity First | Premature abstraction, bloated implementations | | Surgical Changes | Drive-by edits, style drift, unrelated refactors | | Goal-Driven Execution | Vague implementation without verification |

Install

Option A: Claude Code Plugin (recommended)

Add marketplace:

/plugin marketplace add forrestchang/andrej-karpathy-skills

Install plugin:

/plugin install andrej-karpathy-skills@karpathy-skills

Option B: CLAUDE.md (per project)

New project:

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

Existing project (append):

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

Cursor Support

This repository ships a committed Cursor project rule at .cursor/rules/karpathy-guidelines.mdc, so the guidelines apply automatically when opened in Cursor.

See CURSOR.md for setup and contributor workflow.

Canonical Source and Sync Model

To prevent drift across files, guideline content is centralized and generated:

Canonical content: docs/guidelines.md
Generator: scripts/sync_guidelines.py
Validator: scripts/validate.py

Generated targets:

Supported Coding-Agent Targets

The canonical guideline body is stored in:

docs/guidelines.md

Generated targets:

CLAUDE.md (Claude Code project instructions)
.cursor/rules/karpathy-guidelines.mdc (Cursor rules)
.github/copilot-instructions.md (VS Code Copilot repository instructions)
skills/karpathy-guidelines/SKILL.md (skill-style distribution)

Do not edit generated bodies directly. Edit docs/guidelines.md, then run:

python3 scripts/check.py

Using with VS Code Copilot

This repository includes Copilot custom instructions at:

.github/copilot-instructions.md

VS Code and GitHub Copilot use this file as repository-level guidance for chat and coding tasks. It is generated from docs/guidelines.md; do not edit it directly.

After changing the canonical guideline file, run:

python3 scripts/check.py

Optional reusable prompt files live in:

.github/prompts/repo-repair.prompt.md
.github/prompts/verify-change.prompt.md
.github/prompts/surgical-edit.prompt.md

Development

The canonical guideline body lives in:

docs/guidelines.md

After editing it, regenerate derived files:

python3 scripts/sync_guidelines.py

Check sync and validation:

PYTHONDONTWRITEBYTECODE=1 python3 scripts/sync_guidelines.py --check
PYTHONDONTWRITEBYTECODE=1 python3 scripts/validate.py
PYTHONDONTWRITEBYTECODE=1 python3 -m unittest discover -s tests -p "test_*.py"
PYTHONDONTWRITEBYTECODE=1 python3 scripts/validate.py

Or run the full sequence with one command:

python3 scripts/check.py

Build and verify a release archive end-to-end:

python3 scripts/package_release.py

This creates dist/SKILL-MD-main-fixed.zip, extracts it to a temporary directory, and reruns scripts/check.py against the extracted copy.

Release checklist

Before publishing a release ZIP:

PYTHONDONTWRITEBYTECODE=1 python3 scripts/check.py
PYTHONDONTWRITEBYTECODE=1 python3 scripts/package_release.py

Output: dist/SKILL-MD-main-fixed.zip

Source archive vs release archive

Do not commit generated release archives under dist/.

Use these commands by intent:

Release archive (generated + self-verified):

PYTHONDONTWRITEBYTECODE=1 python3 scripts/package_release.py

Source archive prep (clean generated artifacts first):

PYTHONDONTWRITEBYTECODE=1 python3 scripts/clean.py

Pre-commit validation:

PYTHONDONTWRITEBYTECODE=1 python3 scripts/validate.py

PYTHONDONTWRITEBYTECODE=1 prevents Python from creating __pycache__ and .pyc files, which are intentionally rejected by repository validation.

This checks plugin JSON, Cursor frontmatter, required guideline sections, canonical body sync, and forbidden outdated wording/patterns.

The generated files are:

CLAUDE.md
.cursor/rules/karpathy-guidelines.mdc
.github/copilot-instructions.md
skills/karpathy-guidelines/SKILL.md

Optional lint tooling

This repo includes optional Trunk configuration under .trunk/. It is not required to use or contribute to the instruction package.

Required checks use only the Python scripts:

PYTHONDONTWRITEBYTECODE=1 python3 scripts/check.py

Trunk is separate local tooling for contributors who want additional linting. It is not wired into CI. Trunk execution is not verified in this environment.

What Good Looks Like

A healthy setup typically produces:

Smaller, more focused diffs.
Blocking clarifying questions only when required for correctness.
Explicit assumptions when they affect implementation.
Verification commands before completion claims.
Clear reports of changed files, verification results, and remaining failures.

For concrete before/after examples, see EXAMPLES.md.

Repository Layout

.
├── CLAUDE.md
├── CURSOR.md
├── EXAMPLES.md
├── README.md
├── README.zh.md
├── docs/
│   └── guidelines.md
├── scripts/
│   ├── check.py
│   ├── clean.py
│   ├── package_release.py
│   ├── sync_guidelines.py
│   └── validate.py
├── skills/
│   └── karpathy-guidelines/
│       └── SKILL.md
├── tests/
│   └── test_validate_and_sync.py
├── .claude-plugin/
│   ├── marketplace.json
│   └── plugin.json
├── .cursor/
│   └── rules/
│       └── karpathy-guidelines.mdc
├── .github/
│   ├── copilot-instructions.md
│   ├── prompts/
│   │   ├── repo-repair.prompt.md
│   │   ├── verify-change.prompt.md
│   │   └── surgical-edit.prompt.md
│   └── workflows/
│       └── validate.yml
└── .trunk/
    └── trunk.yaml

License

MIT — see LICENSE.

andrej-karpathy-skills

Summary

Install to Claude Code