Write code, not specs

In the before times, code was supposed to be self documenting. If it was good code, you could look at it and understand what it did.

Does that still matter? I think so.

For most of my projects I’ve maintained specs. Tried to get the agent to follow them. Carefully documented bits of English language functionality that described the system.

But that just means I have two systems. One imprecise. The other extremely precise. And now I have to maintain both.

Now instead I write code. I establish the patterns. Within those areas, I have a high degree of trust in agent automation. Outside this carefully tilled garden, my trust diminishes. Trusting an agent here tends to be brittle. It requires high levels of detail and attention.

At that frontier, I’m moving more and more to a system where I just write some code. With the agent in tutor/reviewer mode, I establish a pattern of what I expect. I get more detail oriented. I think about the interfaces. Where I expect specific functionality to go. And write code until it works. The only way to develop this ‘taste’ is to do some of the work.

What about the requirements? All the expected functionality?

That’s what tests do. (Remember this lesson from the before times?) I’d rather have executable language build the project than spec-based suggestions. At a certain level of maturity, the tests become the code.

When I trust a few tests actually test something, then I let an agent write more while I watch it like a hawk.

This gives me a gradually expanding surface of trust. Some areas I trust the agent to be extremely automated (and I’m protected against any stupid human changes). Other, newer areas, I want to be slower, careful, and gradual. I want to be thoughtful about the details.

Then I push the frontier out gradually, maintaining a high level of precision and quality. Maintaining my own human context of the system along with the agent’s. Eventually the agent maintains 99% of the system - but I still have my long-running context of how it works.

In the end this may be as much about preference. My ability to pay attention is better served solving technical problems than writing specs, tabbing to social media, and coming back lost 15 minutes later. No matter how much better the agent gets at coding + debugging, I have the long term context. I’m responsible. My attention becomes the precious resource here.

Using coding agents isn’t a higher level of abstraction, it’s building a factory. You can’t build a factory without designing and hand-crafting prototype parts. Only then can you build up to higher levels of automation. You know how to establish quality assurance for each stage. You know what ‘good’ is from the completed car down to the drive train, transmission, gears, nuts, and bolts.

A well running factory requires a mechanic’s skills. Not because even 0.001% of cars have some manual, human intervention. But because touching some cars improves the factory, develops tastes, and keeps the team obsessed with quality.

Feel proud of touching code, it means you care how the factory works.