Abstraction

“All non-trivial abstractions, to some degree, are leaky.” — Joel Spolsky

Understand This First

• Shape – recognizing the shape of a system helps you choose the right abstractions.

Context

Software systems are too complex to hold in your head all at once. Abstraction is the tool that lets you ignore what doesn’t matter right now so you can focus on what does. It operates at the architectural scale, though every level of software construction depends on it. When you call a function without reading its source, use a library without studying its internals, or prompt an AI agent without knowing how it tokenizes your words, you’re relying on abstraction.

Problem

How do you manage complexity that exceeds what a single person (or a single agent context window) can hold at once?

Forces

• Real systems contain more detail than anyone can reason about simultaneously.
• Hiding detail makes things simpler, but hiding the wrong detail causes surprises.
• Too many layers of abstraction make it hard to understand what is actually happening.
• Too few layers force you to think about everything at once.

Solution

Create boundaries that separate what something does from how it does it. An interface is the visible face of an abstraction: it tells you what you can do. The implementation behind it is the hidden body: it handles how. A good abstraction has a stable, understandable interface that you rarely need to look behind.

The art is in choosing what to hide. A database abstraction that hides the query language is useful; one that hides whether your data is persisted is dangerous. The right level of abstraction depends on who the consumer is and what decisions they need to make.

In agentic coding, abstraction determines how much an AI agent needs to know to do useful work. If your codebase has clean abstractions, you can point an agent at a single module and say “implement this interface.” Without them, the agent needs to understand the whole system, which may exceed its effective context.

How It Plays Out

A team builds a payment processing system. They create a PaymentGateway interface with methods like charge and refund. Behind it, one implementation talks to Stripe, another to PayPal. The rest of the codebase only sees the interface. When a new payment provider comes along, they add a new implementation without changing anything else.

An AI agent is asked to write tests for a service that sends emails. The service depends on an EmailSender interface. Because the interface abstracts away the actual sending, the agent can write tests using a simple mock. It doesn’t need to understand SMTP, API keys, or retry logic. The abstraction makes the agent’s job tractable.

Consequences

Good abstractions multiply productivity. They let teams work in parallel on different parts of a system, let agents operate on bounded slices of a codebase, and make code reusable across contexts.

But every abstraction is a bet that certain details won’t matter to the consumer. When that bet is wrong and the abstraction leaks, the resulting confusion can be worse than having no abstraction at all. You now have to understand both the abstraction and the reality it was hiding. The cost of a bad abstraction isn’t just complexity; it’s misleading complexity.

Related Patterns

• Uses: Interface — an interface is the visible face of an abstraction.
• Enables: Module, Component — abstraction is what makes modular design possible.
• Related to: Boundary — every abstraction implies a boundary.
• Depends on: Shape — recognizing the shape of a system helps you choose the right abstractions.
• Enables: Separation of Concerns — you separate concerns by abstracting them behind boundaries.