Pit of Success

The API/language-design member of the good-defaults family (Good defaults): design so correct usage requires no effort — you fall into the right way.

Definition

Coined in the .NET design context (Rico Mariani), popularized by Jeff Atwood (CodingHorror): the opposite of a “pit of despair.” In a pit-of-success API, the natural, lazy, obvious call is the correct one — and the wrong thing to do is hard. Atwood’s test: if developers must read your docs to avoid breaking themselves, the API is a pit, not a success.

In practice

The classic example is garbage collection in C#/Python/Go: memory management happens automatically, so manual memory leaks — the pit of despair of C/C++ — are designed out, not documented out. You cannot fall wrong because the wrong hole no longer exists.

Captures

• Rico Mariani — The Pit of Success — the origin essay (wayback-recovered; Medium WAF-walled)
• CodingHorror — Falling into the Pit of Success — Atwood’s popularization

Distinction from the Golden Path

Same philosophy (Good defaults), different altitude: the Pit of Success works at the call site (each API usage falls right); the Golden Path (Golden Path) works at org scale (the platform paves one route for everyone). A golden path is a pit dug once by a platform team.

Vault kin

• jnsahaj’s pit-of-success skill (skills (OSS)) — the concept as an agent skill: “review or refactor code so the correct behavior is the default path; use when APIs, setters, hooks have footguns where a natural call bypasses required semantics.” The philosophy now audits the code agents write.
• Vibecoding vs AI engineering / KISS lane — designing-out failure modes is the KISS argument at API level.
• Default-deny permissions + curated tool lists — pit-of-success for LLMs: the lazy path for the model is the safe path.

Practice

• The lazy-call test: what does the lazy, natural call do? If it’s wrong, the design is wrong.
• Prefer designing-out failure modes over documenting them (GC vs “remember to free”).
• Footgun audit: enumerate the calls that compile but bypass required semantics — each one is a pit.