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/anti-patterns.md

Anti-Patterns Gallery

Before/after examples for each of the 4 Karpathy principles. Use these to calibrate your reviews.

Principle #1 — Think Before Coding

Silent assumption: scope

Request: "Add a feature to export user data"

Bad: Immediately writes a function that exports ALL users as JSON to disk, picks column names, and adds CSV support.

Good:

Before implementing, I need to clarify:
1. Which users — all? current tenant? filtered?
2. Which fields — some may be sensitive (PII)
3. Format — JSON, CSV, or API endpoint?
4. Destination — file download, S3, or API response?

Simplest: add an API endpoint returning paginated JSON for authenticated admins.
Want me to go with that, or do you need something different?

Silent assumption: interpretation

Request: "Make the search faster"

Bad: Adds Redis caching, async queries, AND database indexes in one commit.

Good:

"Faster" could mean:
- Lower latency per query (add indexes, ~2h)
- Higher throughput under load (add async, ~4h)
- Faster perceived speed (progressive loading, ~3h)

Current: ~500ms p50. Which dimension matters most?

Principle #2 — Simplicity First

Over-abstraction

Request: "Add a function to calculate discount"

Bad (150 lines):

class DiscountStrategy(ABC):
    @abstractmethod
    def calculate(self, amount: float) -> float: ...

class PercentageDiscount(DiscountStrategy): ...
class FixedDiscount(DiscountStrategy): ...

@dataclass
class DiscountConfig:
    strategy: DiscountStrategy
    min_purchase: float = 0.0
    max_discount: float = float('inf')

class DiscountCalculator:
    def __init__(self, config: DiscountConfig): ...
    def apply_discount(self, amount: float) -> float: ...

Good (3 lines):

def calculate_discount(amount: float, percent: float) -> float:
    return amount * (percent / 100)

Add the Strategy pattern when you actually have multiple discount types. Not before.

Speculative features

Request: "Save user preferences to database"

Bad: Adds caching, validation, merge mode, notification system, and a PreferenceManager class.

Good:

def save_preferences(db, user_id: int, preferences: dict):
    db.execute("UPDATE users SET preferences = ? WHERE id = ?",
               (json.dumps(preferences), user_id))

Principle #3 — Surgical Changes

Drive-by refactoring

Request: "Fix the bug where empty emails crash the validator"

Bad diff (touches 15 lines, only 2 fix the bug):

  def validate_user(user_data):
-     # Check email format
+     """Validate user data."""           # ← docstring added (not asked)
+     email = user_data.get('email', '').strip()
      ...
+     if len(username) < 3:               # ← username validation (not asked)
+         raise ValueError("Username too short")

Good diff (touches 3 lines, all fix the bug):

  def validate_user(user_data):
-     if not user_data.get('email'):
+     email = user_data.get('email', '')
+     if not email or not email.strip():
          raise ValueError("Email required")
-     if '@' not in user_data['email']:
+     if '@' not in email:

Style drift

Request: "Add logging to the upload function"

Bad: Changes quote style, adds type hints, adds docstring, reformats boolean logic.

Good: Adds import logging, logger = logging.getLogger(__name__), and 3 logger.info/error calls. Matches existing single-quote style. Doesn't touch anything else.

Principle #4 — Goal-Driven Execution

Vague vs concrete

Request: "Fix the authentication system"

Bad plan:

1. Review the code
2. Identify issues
3. Make improvements
4. Test the changes

Good plan:

Specific issue: users stay logged in after password change.

1. Write test: change password → old session should be invalid
   verify: test fails (reproduces bug)
2. Invalidate all sessions on password change
   verify: test passes
3. Check edge: multiple active sessions, concurrent changes
   verify: additional tests pass
4. Run full auth test suite
   verify: all green, no regressions

Missing final verification

Bad: "I've added rate limiting. It should work."

Good: "Rate limiting added. Verified: sent 11 requests → first 10 got 200, 11th got 429. Existing tests still pass."

Quick-reference decision table

| Situation | Principle | Action | |---|---|---| | Ambiguous requirement | #1 Think | List interpretations, ask | | "I need a class for this" | #2 Simplicity | Can it be a function? | | "While I'm here, I'll fix this too" | #3 Surgical | Mention it, don't fix it | | "This should work" | #4 Goals | What test proves it? | | User explicitly asked for abstraction | #2 relaxed | Build the abstraction | | User said "refactor this file" | #3 relaxed | Broader changes are OK | | One-liner fix, obvious correctness | all relaxed | Use judgment |