As I’m working with an agent to upgrade a repo from vibe-coded to something I can understand and dig into, I am reminded that Programming is Theory Building.
By “theory” we mean: an understanding of the world, the software and how they relate that’s good enough to let us work intelligently on them, answer questions about them, and argue about them.
Like: we have a theory about what the world needs (I need to be able to comment on this HTML!), how the software meets those needs (a server injects the buttons for this), and how it’s going to meet more (let me edit the content as markdown!).
Software development is reality construction. We make something real in the world, we change what happens when I move my finger this way or click these clackety keys. Conceiving the new world (and how we get there) is programming. That work used to take more typing, more troubleshooting, and more puzzle solving. It has always been, at its core, building a theory of how a piece of the world works and how it can work.
To go from vibe-coded to programmed, I build that theory. I get the agent to start a document explaining what’s going on in that software and why. Then I iterate on that document with it until we’re in agreement. I check it against the world and what we need and what makes sense to me; it checks it against the code.
Building that document together builds the theory of this software for me. Reading it builds the theory for every agent that starts up in this repository.
Reading only that document means that the agent’s theory is shared with me. More documentation is not better! The only context I want the agent to have is documentation I’ve read and iterated on (so it’s connected to my reality) and the code (which runs, so it’s real).
The documentation I read needs to maximize its communicative power. That means diagrams, pictures, and varied structure. HTML beats markdown for this, and the agent is a whiz at writing HTML with SVG figures.
Markdown is a lot easier for me to tweak and comment in, though. I have a need to comment on HTML! And modify its content as easily as markdown. Good thing we have agents to solve this!
Here’s a skill, based on Arlo Belshee’s process, that helps an agent iterate on a document with you. The plugin includes a tool for commenting on HTML and tweaking the content. Also included is a skill for making a project overview document (like this one) as part of theory-building.
Programming is theory building more than ever. The distance from a conception of how the world can be to some new reality is so much shorter with agents! We still need to understand what we want, and conceptually how it can work, and how we’ll get there. That is still the hard part, and we get to work ever harder on it.