karpathy-minimalism

スキル 4：ミニマリズムとエージェントネイティブ設計（极简主义 + 代理原生设计）

出典：https://x.com/karpathy/status/2036487306585268612 | https://x.com/karpathy/status/2021694437152157847 litellm サプライチェーン攻撃（約28k件の「いいね」） | 243行の純粋な Python 製 GPT（約25k件の「いいね」）

基本原則

依存関係はすべて負債です。理解していない抽象化はすべてリスクです。

Karpathy のルール：コア機能を純粋な Python で200行以内に実装できるなら、そうしましょう。3つの関数を使うためだけに、推移的依存関係を47個インストールするパッケージを導入してはいけません。

さらに、LLM エージェントが摩擦なく使えるよう、すべてを設計しましょう。CLI 優先、Markdown で構造化、隠れた仕組みはゼロです。

ミニマリズムの判断ツリー

何かを pip install または npm install する前に：

Q1: Can I implement the core function in < 300 lines?
    → YES: Write it. Paste below as reference.
    → NO: Continue to Q2

Q2: Does this package have < 5 transitive dependencies?
    → YES: OK to use, but pin the version
    → NO: Continue to Q3

Q3: Is this a well-known, audited package (requests, numpy, etc.)?
    → YES: Use it, but still pin version
    → NO: STOP. Either find a simpler alternative or implement yourself.

依存関係監査プロンプト

プロジェクトに何かを追加する前に、これを実行してください：

Audit this dependency for supply chain risk:

Package: [PACKAGE_NAME] v[VERSION]

1. List ALL transitive dependencies (not just direct)
2. Check for recent security advisories
3. Identify any dependencies that are maintained by a single person with < 100 GitHub stars
4. Check if the package does any network calls on import
5. Check if install scripts run arbitrary code (setup.py, postinstall hooks)

Risk score: LOW / MEDIUM / HIGH
Recommendation: USE / AVOID / IMPLEMENT_YOURSELF

「Yoink」パターン（Karpathy の用語）

パッケージをインストールする代わりに、必要な関数だけをコピーします：

Given this package: [PACKAGE_URL or PASTE CODE]

Extract ONLY the function(s) I need for: [SPECIFIC_USE_CASE]

Requirements:
- Pure Python (stdlib only, no imports except builtins + [ALLOWED_STDLIB])
- Under [N] lines
- Add a comment: "# yoinked from [source] on [date]"
- Include a docstring explaining what it does

I need: [SPECIFIC_FUNCTION_NAME or DESCRIPTION]

エージェントネイティブ設計の原則

すべてを LLM エージェントにとって読みやすくしましょう：

❌ エージェントに不向き	✅ エージェントネイティブ
GUI 専用ツール	明確なフラグを備えた CLI
隠れたキーのある JSON 設定	コメント付きの YAML または Markdown 設定
モノリシックな関数	小さく、名前が付いていて、単一の目的を持つ関数
エラー：「問題が発生しました」	エラー：「ステップ3に失敗しました：X を想定していましたが、Y が返されました。次をお試しください：[提案]」
あらゆる場所での相対パス	明示的な絶対パス
状態を持つ副作用	IO が明示された純粋関数

最小実装テンプレート

「yoink」する場合や、一から実装する場合：

#!/usr/bin/env python3
"""
[FUNCTION_NAME] — minimal implementation
yoinked/inspired from: [SOURCE]
date: [DATE]
dependencies: none (stdlib only)

Usage:
    python3 [filename].py [args]
    
Or import:
    from [filename] import [function]
"""

# ---- core implementation ---- (~100 lines max for core logic)

def [function](input):
    """
    [One sentence description]
    
    Args:
        input: [type and description]
    Returns:
        [type and description]
    """
    # implementation
    pass


# ---- CLI entry point ----
if __name__ == "__main__":
    import sys
    if len(sys.argv) < 2:
        print("Usage: python3 [filename].py [input]")
        sys.exit(1)
    result = [function](sys.argv[1])
    print(result)

243行の GPT から得られる教訓

Karpathy は、要点を示すために、純粋な Python 243行で GPT の学習と推論を完全に実装しました。抽象化されたものを使うことより、コアを理解することのほうが重要です。

定期的に使うあらゆるツールに、これを適用してください：

Implement a minimal version of [TOOL/CONCEPT] from scratch.

Requirements:
- Pure Python, stdlib only
- Under 300 lines
- Must demonstrate the core algorithm (not just wrap an API)
- Include inline comments explaining WHY each step works

This is for learning, not production.
Start with the simplest possible working version.

セキュリティ衛生チェックリスト

Before adding any dependency:
- [ ] Checked PyPI/npm for recent security advisories
- [ ] Verified maintainer is active (last commit < 6 months)
- [ ] Reviewed install scripts (setup.py, package.json scripts)
- [ ] Pinned exact version: package==1.2.3 (not ~=1.2)
- [ ] Checked transitive dep count (pip show --files or npm ls --all)
- [ ] Considered: can we implement this in < 200 lines instead?

For existing projects:
- [ ] Run: pip-audit or npm audit
- [ ] Check for packages not in requirements.txt (pip freeze vs requirements diff)
- [ ] Verify no packages make network calls on import

ワークフロー

ワークフローに属します：アイデアからリリースまで（ステップ3）

位置	上流	下流
ステップ3（スリム化）	karpathy-agentic-engineering（実装後）	karpathy-supply-chain-hygiene（セキュリティレビュー）

全体の流れ：idea-files → agentic-engineering → minimalism → supply-chain-hygiene → vibe-to-agentic

プロンプトの契約

Audit this project/code for dependency minimalism: <PASTE_CODE_OR_DESCRIBE>. For each dependency: 1) Is it needed? What specific feature does it provide? 2) Can it be replaced with < 200 lines of stdlib code? 3) How many transitive deps does it pull in? 4) Risk score (LOW/MED/HIGH). Then produce a minimized version plan: what to keep, what to yoink, what to rewrite. Output a dependency budget: max N packages, each justified.

検証チェックリスト

• すべての依存関係に導入する理由がある（「便利だから」ではない）
• 200行未満で実装できるものには「yoink 可能」の印が付いている
• 推移的依存関係の合計数が予算内に収まっている
• コアロジックが、削除される可能性のあるパッケージに依存していない
• エージェントが標準ライブラリだけの環境でコア機能を実行できる
• CLI の入口がシンプルで明確（追加のツールなしで使える）