Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.karpathy.phronesisagent.com/llms.txt

Use this file to discover all available pages before exploring further.

The Karpathy guidelines are a starting point, not a final word. They are intentionally general so you can drop them into any project — but the most effective setup merges them with rules specific to your codebase, tech stack, and team conventions. You own the CLAUDE.md file; treat the Karpathy section as a foundation and build on top of it.

​
Adding project-specific rules

After placing the Karpathy guidelines in your CLAUDE.md, add a ## Project-Specific Guidelines section below them. Claude Code reads the entire file and the sections compose naturally — the general rules apply everywhere, and your project rules narrow behavior for your context. 
## Project-Specific Guidelines

- Use TypeScript strict mode
- All API endpoints must have tests
- Follow the existing error handling patterns in `src/utils/errors.ts`
You can be as specific as your project needs. Common things to capture:
  • Language and compiler settings — TypeScript strict mode, Python version, lint rules
  • Test requirements — which endpoints need coverage, which test framework to use
  • Patterns to follow — link to existing files that demonstrate the right approach
  • Patterns to avoid — naming anti-patterns, deprecated modules, banned dependencies
The most useful project-specific rules reference actual files in your repo. “Follow the error handling in src/utils/errors.ts” is far more actionable than “handle errors consistently.”

​
Tradeoff: caution over speed

The Karpathy guidelines bias toward caution. They ask the model to surface assumptions, ask clarifying questions, and make minimal changes — all of which add friction to interactions. That friction is worthwhile for non-trivial work where mistakes are costly to undo. For simple tasks — a typo fix, an obvious one-liner, renaming a variable — applying full rigor is unnecessary overhead. Use judgment. The goal is reducing costly mistakes on complex work, not slowing down everything.
If you find the guidelines too conservative for your workflow, add a line in your project-specific section such as “For single-line changes, skip the planning step and implement directly.”

​
When guidelines conflict with project needs

Any rule in the Karpathy section can be overridden or relaxed in your project-specific section. The file is plain Markdown and there is no enforcement mechanism — the model reads both sections and applies them together. A later, more specific rule naturally takes precedence over an earlier, more general one. For example, if your project uses a code generator that produces verbose boilerplate you want preserved: 
## Project-Specific Guidelines

- Do not simplify or condense generated files in `src/generated/` — they are
  machine-produced and changes will be overwritten on the next build.
This relaxes the “Simplicity First” principle for a specific directory without removing it globally.

​
Option A: using the Claude Code plugin

When you install via the Claude Code plugin marketplace, the Karpathy rules are loaded globally across all your projects. In that case, your local CLAUDE.md is for project-specific rules only — you do not need to copy the Karpathy text into it.
With the plugin installed, Claude Code merges the plugin-provided rules and your local CLAUDE.md automatically. Keep your local file focused on what is unique to this project.
The plugin installation commands are: 
/plugin marketplace add forrestchang/andrej-karpathy-skills
/plugin install andrej-karpathy-skills@karpathy-skills
After installation, create or edit your project’s CLAUDE.md to contain only project-specific sections — no need to duplicate the four principles.