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
- Start with Level 1 for a week. Let the team see the principles in action.
- Add Level 2 when reviewing PRs. Run
/karpathy-checkon every PR. - Add Level 3 when the team agrees the principles are useful. Gate commits.
- 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.