Interface Driven Development

In a team, waiting costs more than the coding does. Everyone starts from their own piece, builds it properly, and only then asks how it connects to the rest. It feels productive because everybody is busy. Then integration arrives and somebody has been stuck for a week and a half on a question that could have been settled in five minutes on day one.

My rule of thumb: agree on the interface first. Before anyone writes the part they find interesting, write down what goes in and what comes out. Names, shapes, units, what happens when it fails. The contract, not the thing behind it.

The useful part is that the moment I know what your piece will hand me, I can stop waiting for you. I can write against it, stub it out, test my own half, and be wrong about my own half in a way that's cheap to fix. You get the same from me. Nobody sits on their hands, and nobody has to guess and then find out in week three that they guessed badly.

Of course the specifics move. They always move. The first numbers are guesses and half of them turn out too strict or too loose the moment anyone builds anything real. That back and forth isn't wasted work; it's most of the work. What matters is that the interface is what gets attention early, instead of being the thing we get to once the fun part is done.

I explain this with a bike, because "define your service boundaries" makes people nod while picturing nothing at all. Boxes and arrows on a whiteboard aren't something anyone has ever held. A bike is.

Say three people are building one: wheels, frame, and brakes with all the mounting. The wheel person doesn't need a finished frame to build a wheel. They need the dropout spacing and the axle standard, and that's about it. The brake person doesn't need a finished wheel either, only where the mounts sit and what surface the pads will press against. Agree on those few numbers, then hand each other the cheapest possible version of just that part: a bare hub on an axle, a length of tube with the mounts welded on, a chunk of rim. Now everyone can test against something real instead of against an assumption. The hub is ugly and it's not the hub that ships. Doesn't matter. It has the right dimensions, and that was the whole job.

The other half of this is accepting that the filling-in never ends. A wheel can always be lighter, truer, better under load. Same with any service: there's always another index, another cache, another retry path, another edge case someone will raise in review. That work has no natural end, which is why it can't be the thing standing between other people and their progress. At some point the wheel is round enough and holds the weight, and that's good enough. Get the interface out early and keep polishing behind it.

The part people resist is that going interface-first costs you something. You stop what you were doing, you write down the boring bit that unblocks someone else, and it isn't the best hour of your day. That's a small loss and it's a real one. It's only a bad deal if you're the only one doing it. When everyone works this way, you give up half a day here and there and every other person on the team unblocks you first. I'll take that trade every time, and I think most people would if they saw the second half of it.

Yes, it means your internals stay ugly for a while. Nobody's looking at them anyway; they're using the interface.