Reference · Engineering principles (skill)

Engineering principles

One skill. Four principles. Every change. Adapted from Andrej Karpathy’s skills (MIT) - each principle has a named test that decides pass / fail.

See it in motion

Where to find it

  • Skill: .claude/skills/karpathy-guidelines/SKILL.md
  • Summary in CLAUDE.md: the “Engineering principles” section
  • Long-form doc: /docs/engineering-principles
  • Invoked by: ship-feature + simplify skills

What it does for you

1 - Think Before Coding.State assumptions explicitly. Present multiple interpretations when the request is ambiguous. Push back when a simpler path exists. Test: did the agent surface its uncertainty, or did it pick silently and run?
2 - Simplicity First.The minimum code that solves the problem. No abstractions for single-use code. No flexibility that wasn’t requested. Test: would a senior engineer call this overcomplicated? House rule - three similar lines beat a premature abstraction.
3 - Surgical Changes.Touch only what you must. Clean up only your own mess. Remove orphans your change made unused; flag pre-existing dead code, don’t delete it. Test:every changed line traces directly to the user’s request.
4 - Goal-Driven Execution.Transform imperative tasks into verifiable goals (“add validation” → “write tests for invalid inputs, then make them pass”). Test: can the agent point at a concrete verification - a test, a CI gate, a boot smoke check - that confirms the change works?

Configure

The skill is plain markdown - open .claude/skills/karpathy-guidelines/SKILL.md and extend. The named tests live near the top of each section so they’re unmissable. Add a project-specific principle if your team has one (e.g. “Stage by explicit path”) - the skill is yours.

Use it well

Read the principles before any non-trivial change. Re-check before commit. The ship-feature skill weaves these into the orient → plan → build → verify → PR loop; the simplify skill applies them post-hoc.

Read more