# Karpathy-Inspired Claude Code Guidelines Administrator & Developer Guide

## 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

```text
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:

```text
/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:

```bash
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.

### Related Project

The README references [Multica](https://github.com/multica-ai/multica), described as an open-source platform for running and managing coding agents with reusable skills, by the same author.

---

_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. Unofficial; not affiliated with or reviewed by the project._