Too Big to Work – Building Effective Internal Developer Platform Abstractions

Part of a "Software Engineering Enchiridion"

Sep 18, 2025

(Image: The garden in “The Goethe House” in Frankfurt. A garden to grow ideas in.)

I learned this lesson the hard way. One morning the entire team arrived to do an early demo to our stakeholder to be met with a surprise: nothing worked. The pipelines were red, the latest build wouldn't even boot, so we did what all great teams go and do: Stop and fix NOW.

We stopped, and then stopped some more. Our code was an unrecognisable mess. There were hierarchies of classes no one recognised. Base classes with names like "A" that seemed to come from some documented pattern no one had ever encountered. We were lost in our own code, and the demo was coming.

The commit log was our only friend. A quick glance and we saw that one team member, a known "hero" sadly, had been committing until 3am. A host of commits. A confusion of commits. There were probably other compound verbs to describe it, most of which are not printable.

Revert. We went back to something we recognised again as our software. Fortunately it was enough to do the demo. We managed to get back to something we recognised just in time. Then there were strong words with the 3am Hero Developer. The excuse: "Better abstractions". A better hierarchy. A web of abstractions that would allegedly simplify the codebase.

A harsh lesson all round. Abstractions are tricky, but they can be a great tool for reducing cognitive load. If, and only if, they are tuned right.

And never when introduced as a massive web of abstractions, at 3am...

Building Effective Internal Developer Platform Abstractions

The human brain is a miser. It hoards attention like a miser hoards gold. Every stray detail burns fuel. Every loose end rattles in the mind. In software, the worst theft is cognitive theft: being forced to care about things that have nothing to do with your actual work. Developers come to build features for users, not to moonlight as part-time Kubernetes whisperers. Yet too many internal developer platforms demand this split life.

A good platform makes you forget. That’s the point. Forgetting, here, is freedom. A developer should not need to rehearse the entire ritual of networking, load balancing, and secret management just to ship a line of business logic. Platforms exist to help engineers ignore—safely, deliberately, and with taste. Abstraction is the mechanism of forgetting.

But abstraction is a sharp blade. Wielded well, it cuts through noise. Wielded poorly, it cuts your hands. Richard Gabriel, in Patterns of Software, laid out the terms. Abstraction is not magic dust sprinkled on complexity. It is the process of finding the common shape across many messy instances and then giving a way to specify the variations.

Two conditions: pattern and variation. That’s it. The elegance of the idea hides the labor of “anticipating all purposes and forgetting all purposes.”

An Anti-Pattern Vignette
Picture this: a bank’s platform team builds “The Framework.” That’s what they call it, half-jokingly, half-seriously, as if it were *the* solution to end all solutions. It has layers. It has sub-layers. It has a YAML schema so dense it looks like the Dead Sea Scrolls. You don’t deploy services anymore—you “declare intents,” feed them into The Framework, and hope it spits out something that runs.
At first, management loves it. “We’ve standardised everything!” they beam. But developers are cursing under their breath. They can’t ship without first fighting the abstraction, memorising its quirks, or pinging the one guy who actually understands it. Instead of hiding infrastructure, the framework has swallowed the infrastructure whole and trapped the developers inside.
So what happens? Teams route around it. They roll their own scripts. They sneak in Terraform. They cut holes in the walls of The Framework just to get real work done. The abstraction becomes the enemy. The cathedral stands, but empty.
This is the fate of abstractions too big to work.

Back to the point: abstractions should be modest. Shallow and composable, not deep and hierarchical. A deep hierarchy of abstractions is like a Russian doll set designed by sadists: each layer hides the one beneath but demands you twist open all of them to find the core. You don’t get simplicity. You get a labyrinth.

Compression is a different beast, though often mistaken for abstraction. Compression is when the meaning of a part is larger than the part itself, when each word hums with resonance from its surroundings. Done right, compression makes systems habitable: you arrive at a piece of code and it welcomes you, shows you around, lets you settle in. Done wrong, compression suffocates.

Habitability is what matters most for internal developer platforms. If your abstractions are too clever, too layered, too “visionary,” you will destroy it. Developers won’t live in your platform. They’ll camp outside, hacking crude workarounds just to avoid your grand design. People ignore monolithic abstractions not because they’re lazy, but because they’re human. As Christopher Alexander put it, when people feel they are just cogs, stripped of responsibility, they stop caring.

Here’s the principle: build small, shallow, composable abstractions. Keep hierarchies thin. Grow slowly, piecemeal , not through wholesale invention. Build your platform as a set of small steps, rather than a horrid beautiful-in-concept-only grand design.

Build for the common, shared needs: what every team touches, what no one can escape. Don’t try to abstract the rare, the domain-specific, the “clever” edge case. Leave those raw. Let them be solved close to the ground, not smothered under platform ambition.

If you build a “web of abstractions,” you will strangle habitability. If you build an orchard of small, shallow trees, you will have something that lives, breathes, and can be pruned.

The real work is restraint. Not building the cathedral. Not pulling every knob and lever into your API. Not trying to “anticipate everything.” The job is less romantic: build the smallest thing that lets developers forget the right things. Then stop.

Maxim

Too big to work: a web of abstractions collapses under its own weight.

Rationale

Abstractions exist to free mental energy. When too large or deep, they demand more attention than they save, eroding the crucial quality of habitability in your internal developer platform and code.

Practices

Abstract only what is truly common across teams or domains
Design shallow, composable abstractions.
Use parameters for controlled variation minimally and being ware of leaking implementation details.
Grow abstractions incrementally through repair, not wholesale reinvention.