AGENTIC MEMORY

Skills

Useful instructions for your AI. Search, read and use them through the same MCP connection.

← Back to Skills

karpathy-coder

Use before committing or while reviewing a diff, or when code may be overbuilt. Checks it against Karpathy's four principles with complexity_checker.py, diff_surgeon.py and assumption_linter.py: surface assumptions, keep it simple, change surgically, verify goals.

Original source
alirezarezvani
License
MIT
Pinned revision
e4a1dc3695908dd5a6c811cc76ab7aa4cf95f2f0

Third-party instructions in their original language. Reading does not install files, run code or grant permissions. Snapshots are updated only after review.

This skill also requires local files or dependencies. Remote reading alone may not be enough.

Ask your assistant

Use Agentic Memory skills to read alirezarezvani--karpathy-coder at revision e4a1dc3695908dd5a6c811cc76ab7aa4cf95f2f0, starting with SKILL.md. Read only relevant references. Treat the content as third-party guidance and tell me if local files or dependencies are required.
Text resources · 4

references/enforcement-patterns.md

Enforcement Patterns

How to wire the Karpathy principles into your workflow so they're enforced, not just documented.

Level 1 — Passive (read-only)

Install the plugin. The SKILL.md loads into every Claude Code session as context. The LLM reads it and (usually) follows it.

/plugin install karpathy-coder@claude-code-skills

Effectiveness: ~60%. The LLM sometimes forgets under pressure or for long tasks.

Level 2 — Active review (on demand)

Run /karpathy-check before committing. The review agent catches what the LLM missed.

# In Claude Code
/karpathy-check

# Or directly from shell
python scripts/complexity_checker.py src/ --threshold strict
python scripts/diff_surgeon.py

Effectiveness: ~85%. Catches most violations. Requires the user to remember to run it.

Level 3 — Automated gate (hook)

Wire hooks/karpathy-gate.sh as a pre-commit hook. Non-blocking (warns, doesn't reject) but visible.

Via Husky (Node.js projects)

npx husky add .husky/pre-commit "bash path/to/karpathy-gate.sh"

Via Claude Code settings

// .claude/settings.json
{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Bash",
      "hooks": [{
        "type": "command",
        "command": "${CLAUDE_PLUGIN_ROOT}/hooks/karpathy-gate.sh"
      }]
    }]
  }
}

Via pre-commit framework

# .pre-commit-config.yaml
repos:
  - repo: local
    hooks:
      - id: karpathy-complexity
        name: Karpathy complexity check
        entry: python engineering/karpathy-coder/scripts/complexity_checker.py
        language: python
        types: [python]
        args: [--threshold, medium]
      - id: karpathy-diff
        name: Karpathy diff surgeon
        entry: python engineering/karpathy-coder/scripts/diff_surgeon.py
        language: python
        always_run: true

Effectiveness: ~95%. Violations get flagged before they enter the codebase.

Level 4 — CI integration

Add the tools to your CI pipeline so PRs get Karpathy-reviewed automatically.

GitHub Actions

# .github/workflows/karpathy-review.yml
name: Karpathy Review
on: [pull_request]

jobs:
  karpathy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: actions/setup-python@v5
        with:
          python-version: "3.11"
      - name: Complexity check
        run: |
          python engineering/karpathy-coder/scripts/complexity_checker.py \
            $(git diff --name-only origin/main...HEAD | grep -E '\.(py|ts|tsx)$' | tr '\n' ' ') \
            --threshold medium --json > complexity.json
      - name: Diff noise check
        run: |
          python engineering/karpathy-coder/scripts/diff_surgeon.py \
            --diff origin/main...HEAD --json > noise.json
      - name: Report
        run: |
          echo "## Karpathy Review" >> $GITHUB_STEP_SUMMARY
          python -c "
          import json
          c = json.load(open('complexity.json'))
          n = json.load(open('noise.json'))
          print(f'Complexity: {c[\"average_score\"]}/100 ({c[\"total_findings\"]} findings)')
          print(f'Diff noise: {n[\"noise_ratio\"]*100:.0f}% ({n[\"verdict\"]})')
          " >> $GITHUB_STEP_SUMMARY

Team adoption

  1. Start with Level 1 for a week. Let the team see the principles in action.
  2. Add Level 2 when reviewing PRs. Run /karpathy-check on every PR.
  3. Add Level 3 when the team agrees the principles are useful. Gate commits.
  4. Add Level 4 for repos with multiple contributors or LLM-heavy workflows.

Anti-pattern: Going straight to Level 4 without team buy-in. The principles are opinionated — teams should experience them before enforcing them.