Jesse A. Green / notebook

Live demo: the DocCompiler guide library as a static, read-only snapshot (October 2026). No backend, no accounts, nothing to submit.

Karpathy-Inspired Claude Code Guidelines Administrator & Developer Guide

Generated May 2026 from forrestchang/andrej-karpathy-skills at 2c60614

AI-generated documentation. The library is checked by sampling (three repositories so far); this guide was not individually reviewed. Verify against the project before relying on it.

Repository page User Guide Markdown file Upstream on GitHub

1. Architecture Overview

Karpathy-Inspired Claude Code Guidelines is a documentation-only project that provides behavioral rules for Claude Code, packaged as both a Claude Code plugin (skill) and a standalone CLAUDE.md file. There is no runtime code, no dependencies, and no build system. The project consists entirely of Markdown files that Claude Code reads to modify its behavior during coding sessions.

Project Structure

Component Path Role
Core guidelines CLAUDE.md The behavioral rules Claude Code reads and follows
Plugin manifest skills/karpathy-guidelines/SKILL.md Plugin metadata and skill definition for Claude Code's plugin system
Examples EXAMPLES.md Before/after code comparisons demonstrating each principle
README README.md Project description, installation instructions, principle explanations

Repository Layout

andrej-karpathy-skills/
  CLAUDE.md                              # Core guidelines (the product)
  EXAMPLES.md                            # Detailed code examples
  README.md                              # Project documentation
  skills/
    karpathy-guidelines/
      SKILL.md                           # Claude Code plugin definition

Technology Stack

Layer Technology
Content format GitHub-Flavored Markdown
Distribution Claude Code plugin system, raw GitHub file download
License MIT
Version control Git / GitHub

How It Works

The project operates through Claude Code's context injection mechanism. When Claude Code starts a session, it reads the CLAUDE.md file from the project root (or loads the skill via the plugin system). The guidelines become part of Claude's instruction context for that session, modifying its behavior according to the four defined principles.

There is no executable code. The "architecture" is purely a set of Markdown documents that influence LLM behavior through prompt engineering.

2. System Requirements

Requirement Detail
Claude Code Any version supporting CLAUDE.md or the plugin/skill system
Disk space Less than 50 KB total
Dependencies None
Runtime None --- these are static Markdown files

3. Configuration Reference

This project has no configuration files, environment variables, or runtime settings. The guidelines are entirely self-contained in the Markdown files.

SKILL.md Metadata Fields

The plugin manifest at skills/karpathy-guidelines/SKILL.md uses YAML front matter:

Field Value Purpose
name karpathy-guidelines Plugin identifier in the Claude Code plugin system
description Behavioral guidelines to reduce common LLM coding mistakes... Shown in plugin listings
license MIT License declaration

Note

The SKILL.md file contains the same four principles as the root CLAUDE.md but is formatted with front matter metadata for the Claude Code plugin system.

4. Deployment & Distribution

As a Claude Code Plugin

The project is distributed through Claude Code's plugin marketplace. Users install it with two commands:

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

The plugin system handles distribution. No server infrastructure is required.

As a Standalone File

Users can download CLAUDE.md directly from GitHub:

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

This relies on GitHub's raw file serving. No additional hosting is needed.

Versioning

The project does not use semantic versioning or tagged releases. Users get the latest version from the main branch. Changes take effect the next time Claude Code loads the CLAUDE.md file or plugin skill.

5. Operations

Maintenance

Since this is a static documentation project, operational maintenance is minimal:

  • Content updates: Edit the Markdown files and push to main
  • Plugin updates: Changes to skills/karpathy-guidelines/SKILL.md propagate through the plugin system
  • Consistency checks: Ensure CLAUDE.md, SKILL.md, and README.md stay in sync --- they contain overlapping content

Important

The root CLAUDE.md and skills/karpathy-guidelines/SKILL.md contain the same four principles. When updating one, update the other to maintain consistency.

Content Synchronization

Three files contain the four principles in varying levels of detail:

File Content Level Audience
CLAUDE.md Full guidelines with tradeoff note Claude Code (machine-readable)
skills/karpathy-guidelines/SKILL.md Full guidelines with YAML front matter Claude Code plugin system
README.md Expanded explanations with rationale Human readers (GitHub)

The EXAMPLES.md file is standalone and referenced only from README.md.

6. Performance

Not applicable. This project contains no executable code. Performance considerations are limited to:

  • Context window usage: The CLAUDE.md file is approximately 1.5 KB, which is negligible in Claude's context window
  • Plugin loading: The skill loads once at session start with no measurable overhead

7. Security

Threat Model

This project has a minimal attack surface:

  • Supply chain: If the GitHub repository is compromised, malicious instructions could be injected into the CLAUDE.md file, potentially directing Claude to write insecure code or exfiltrate data
  • Plugin system: Users who install via the plugin marketplace trust that the plugin content has not been tampered with

Mitigations

  • The repository is public on GitHub, allowing community review of all content
  • MIT license allows forking and independent verification
  • The guidelines contain only behavioral instructions, no executable code
  • Users can review the full content before installation (4 small Markdown files)

Warning

As with any Claude Code plugin or CLAUDE.md file, review the content before installing. Malicious guidelines could instruct Claude to introduce vulnerabilities or exfiltrate sensitive information from your codebase.

8. Developer Internals

Design Philosophy

The project follows the principle of minimal viable documentation. Each file serves a specific purpose:

  1. CLAUDE.md is the product --- the actual guidelines Claude reads
  2. SKILL.md is the distribution wrapper --- makes it installable as a plugin
  3. EXAMPLES.md is the teaching material --- shows the guidelines in action
  4. README.md is the marketing --- explains why the guidelines exist

The Four Principles in Detail

The guidelines are derived from Andrej Karpathy's observations about LLM coding behavior, posted on X. Each principle maps directly to a specific failure mode:

Principle Failure Mode Addressed Key Behavioral Change
Think Before Coding Wrong assumptions, hidden confusion, missing tradeoffs Forces explicit reasoning and clarification requests
Simplicity First Overcomplication, bloated abstractions, speculative features Enforces minimum viable code
Surgical Changes Orthogonal edits, drive-by refactoring, style drift Restricts changes to requested scope only
Goal-Driven Execution Vague implementation without verification Requires testable success criteria

Content Patterns

The EXAMPLES.md file uses a consistent pattern for each example:

  1. User request --- what was asked
  2. Wrong approach (with code) --- what unconstrained LLMs typically do
  3. Problems --- specific issues with the wrong approach
  4. Correct approach (with code) --- what the guidelines produce
  5. Explanation --- why the correct approach is better

This pattern is repeated across all four principles with 1-3 examples each.

Contributing

To modify the guidelines:

  1. Edit the relevant Markdown file(s)
  2. Ensure consistency across CLAUDE.md, SKILL.md, and README.md
  3. If adding a new principle or modifying existing ones, update EXAMPLES.md with corresponding before/after examples
  4. Test by using the modified CLAUDE.md in a real Claude Code session and verifying the behavioral change

Potential Improvements

Based on analysis of the repository structure:

  • Versioning: The project could benefit from tagged releases so users can pin to a specific version of the guidelines
  • Testing: There is no automated way to verify the guidelines produce the desired behavioral changes. A test suite with prompt/response pairs could validate effectiveness
  • Metrics: The README lists qualitative signals ("fewer unnecessary changes in diffs") but no quantitative metrics for measuring guideline effectiveness
  • Localization: The guidelines are English-only. Multi-language versions could expand reach

9. Integration Points

Claude Code Plugin System

The project integrates with Claude Code through the plugin/skill system:

  • Marketplace registration: forrestchang/andrej-karpathy-skills is the marketplace identifier
  • Skill name: karpathy-guidelines is the installable skill
  • Loading mechanism: Claude Code reads the SKILL.md content and injects it into the session context

CLAUDE.md Convention

The project leverages Claude Code's convention of reading CLAUDE.md from the project root at session start. This is a standard Claude Code feature, not specific to this project.

The README references Multica, described as an open-source platform for running and managing coding agents with reusable skills, by the same author.