Chatting with your coding agent doesn’t scale

Large parts of the software I build these days I don’t understand and a big reason for that is due to the immense volume of code I’m outputting. However, in order to iterate on anything you need to have an understanding of the thing.

I’ve been working on an app for the past 6 months to create calisthenics workouts for my training and I started to struggle to make meaningful improvements on the generation part of the product. As the project got larger, it became harder to make improvements without having negative secondary effects. Usually this is a sign of technical debt. The real reason now is that each of us is managing far larger projects than before, and the jump from small to large happens so fast that we never build a strong understanding of what we made.

As I pondered on how to overcome this, I realised that my agent can almost do anything I ask, so I should stop unconsciously limiting myself in what I am thinking of telling my agent to do. This is a much harder thing to do than to just say it. So if I couldn’t read the code, what would I do instead? I’d ask the agent to show me, in whatever form is easiest for me (a human) to understand.

The first thing I tried was to get my agent to give me the before and after prompt changes it wanted to make. This helped and I could start iterating a bit more intelligently than just assuming the models were fixing nuanced problems correctly. This approach has very big weaknesses in that it’s only giving me a very isolated part of the software to change, and I’m only viewing this part as opposed to the entire system. So I moved up a layer.

I asked my agent to teach me how everything works through some artifact that it determines is the best way to represent the internals and logic of how creating a workout works in my product. It created a beautiful artifact that showcased flow charts, prompts verbatim, example user prompts, structured outputs, and business logic in the form of tables. I could see everything all at once.

Almost instantaneously I found numerous things that were bad about the design of the internals. Through a flow chart, I was able to notice a redundant request asking AI to filter down an exercise list based on injury history, and through the structured output I noticed that the output included sets, reps, weight, and rest, all of which, for this project, were an over-optimisation and bad product decisions. I would have never caught or changed these if I was doing things the old-fashioned way, aka reading code or conversing with my coding agent. But it was all very clear when viewing things holistically through a website.

This requires a level of trust in my agent that it represents everything accurately. It might feel uncomfortable at first. Six months ago or more there was a lot of back and forth that went into creating artifacts that explained how software systems worked. The latest generation of models (e.g. Astra, Fable) have made this more of a one-shot problem.

A big part of being a software engineer is being a tool user, and AI is the highest leverage most powerful tool we have ever had our hands on.