simplicity-first

Overview

AI agents trend toward complexity. They add abstractions "for flexibility," error handling for impossible cases, and configuration for things that will never change. Left unchecked, they turn 50-line solutions into 500-line systems.

This skill enforces a hard constraint: write the minimum code that solves the stated problem and nothing more.

Andrej Karpathy's observation: "They really like to overcomplicate code and APIs, bloat abstractions, don't clean up dead code... implement a bloated construction over 1000 lines when 100 would do."

When to Use

• Starting any new implementation
• When you feel the urge to add "just one more abstraction"
• When reviewing your own generated code
• When a simple task balloons into a complex solution

Process

Step 1: Define the Minimum Viable Solution

1. State what the code must do — write it as a list of requirements.
2. For each potential addition, ask: "Was this explicitly requested?"
   • If no → do not add it.
3. Write the simplest possible implementation that satisfies each requirement.

Verify: You can trace every line of code back to a stated requirement.

Step 2: Apply the Simplicity Test

1. After writing, read through the code and flag:

   • Abstractions used only once → inline them
   • Parameters never customized → hardcode them
   • Error handling for impossible scenarios → remove it
   • "Future-proofing" that wasn't asked for → delete it
   • Configuration flags for things that won't vary → remove them

2. Ask: "Would a senior engineer call this overcomplicated?" If yes, simplify.

Verify: Each abstraction is used in at least 2 places; each parameter is actually varied.

Step 3: Count the Lines

1. If your solution is more than 3× the length you'd expect for the task, something is wrong.
2. Actively look for ways to reduce line count without sacrificing readability.

Rule of thumb: If 200 lines could be 50, rewrite it.

Verify: You've made at least one active attempt to reduce complexity.