Now you can ship software you don't understand

Sean Goedecke has an essay called You can’t design software you don’t work on. He argues that good design in a large codebase depends on concrete details of the system, and that the only people who know those details are the ones working on it. In practice, he says, that almost always means being an active contributor.

That used to be a safe assumption, because you found out quickly if you didn’t understand a system. You couldn’t ship anything. Now you can ship a lot in a codebase you barely understand, and you find out much later. Sometimes someone else finds out first.

Contributing used to require understanding

It used to be hard to make your first real change to a system. You had to find where things lived, figure out why they were built that way, run the code, and break a few things. None of that was the point. You just wanted to ship. But by the time you had, you’d learned a lot about the system, because there was no way to contribute without it. And when you didn’t understand something, you found out right away.

So output was a decent signal. When a teammate had shipped a lot of good work in some part of the codebase, you could trust them with the risky change there. They’d learned the system along the way.

Now the two have come apart

Today you can open a codebase you’ve never seen, describe what you want, and get a reasonable-looking change in an hour. The code compiles and the tests pass. You can keep doing that for a while.

The problems show up later. Maybe as a bug a customer hits, that someone else gets paged for, that is hard to understand and difficult to fix.

What used to catch it

A few things used to catch a lack of understanding early. You got stuck, or you had to ask someone who knew the system, or a reviewer who knew it pushed back on your change. All of that happened before anything shipped, and the only people who noticed were you and maybe whoever was helping you.

Agents remove most of these checks. You rarely get stuck, and you can ask the agent instead of a person. Review still happens, but it’s weaker than it was. The PR looks clean, and the reviewer is often leaning on an agent too. Nothing has really replaced those checks.

It’s cheap to build an alternative

Agents also make it cheap to build a replacement. If an existing system is confusing, it’s now easier to prototype a new one than to learn why the old one works the way it does. This is what Sean called designing to the problem. It used to take weeks, so people mostly didn’t. Now it takes a day, and the result looks clean because it hasn’t run into any of the cases the old system already handles.

The replacement might be the right call. But if you skip understanding the old system, you throw away what it knows, including things nobody has noticed yet, like the fact that you were using a tool wrong.

GitHub replacements are a good example. Plenty of people have built one with agents, and they look fine until they hit the complexity that GitHub has spent years getting right. One that is different is Cursor’s Origin. The engineer behind its Git storage, Vicent Martí, spent years at GitHub working on these exact problems. As he puts it in his writeup, Origin is “the result of many decades of experience building these same systems.”

Catching it earlier

One way to move the discovery back to the start is to put the knowledge into the codebase, so people don’t have to carry it. Lauren Tan’s recent talk about shipping 2,500 pull requests in a month is mostly about this. She took what she knew about her system and encoded it into types, lint rules and tools, so that agents could work safely without her.

I think Lauren’s approach is mostly right, and most teams should do more of it. But it can only capture what someone thought to capture. A lot of what I’ve learned about our systems is from conversations - with coworkers, vendors, customers - that don’t fully make their way into the codebase. Maybe these could be written down better, but there’s often a lot of open-endedness to these conversations that makes them less like documentation and more like notes. They benefit from follow-ups when someone else works with them.

A simple rule

Sean ended his essay by saying that whoever designs a system should be responsible for whether it works. Mitchell Hashimoto has made a similar point about working with agents. If you ship a change, you should be able to explain it to a coworker without asking the agent. I think the most important part of his challenge is that it’s pulling in another coworker. Explaining a change to someone who knows the system is when the valuable follow-up questions and missing information come up.