Back to Blog
4 min read

Design Through Dialogue

The best design in a recent 118-commit migration on IcePets didn't come from a spec. It came from about eight terse review comments and an AI agent that made each round cheap enough to keep iterating. How a tiny feature converged on a better design, and the transferable rule that fell out of it.

Listening · Design Through Dialogue

Part of a big migration I've been running on IcePets, the Laravel and Vue virtual-pet game I build, was a small feature: unlocking an avatar when a player opens a "Suspicious Present." One little thing. It took roughly eight cycles of back-and-forth with the AI agent doing the implementation, and it's the clearest example I have of how design actually happens in an AI-assisted codebase, which is not the way people assume.

I don't hand the agent a finished spec. I react to what it builds. It proposes, I drop a short directional comment, it adjusts, and the design converges through the dialogue. The agent's real job in that loop isn't to be right the first time. It's to make each round cheap, small commits, runnable samples, so we can iterate fast enough that converging beats specifying.

"Show me the code"

The starting point was smelly: a hardcoded map from item to avatar buried inside a bespoke unlock action, plus a second, parallel action for database-linked avatars. Two things doing almost the same job, one of them with a lookup table stapled on.

My first move wasn't to describe the design I wanted. It was "give me sample code." I've learned I won't approve an approach in the abstract, because in the abstract everything sounds fine. Show me the actual shape it takes in the actual code and I can tell immediately whether it's right. With an AI agent that can produce that sample in seconds, "show me the code" stops being a big ask and becomes the fastest steering tool I have.

Converging, one comment at a time

From there it went in short steps, each a reaction to the last. Make it a specific "a suspicious present was used" event instead of a map. If the player already has the avatar, they don't get it again, so the grant has to be idempotent. Recording that the item was used is not the same thing as consuming it, so split those. You still have the bespoke action, kill it, make this an event. There should be an itemOpened() hook on the base openable class, and the present is just an openable with a subclass. The subclass should call the parent so the shared open behaviour still runs.

None of that was planned up front. Each line was me looking at what existed and nudging it one step better. Where it landed: the Suspicious Present is now a normal openable that goes through the generic open flow, consume plus record-use, like everything else. Its handler subclass fires a "used" event, and a listener grants the avatar. No bespoke action, no hardcoded map. Cleaner than anything I would have specced at the start, because I couldn't have seen it from the start.

The rule that fell out

Then the other avatar type came up, the database-linked one, and the agent proposed the same treatment: fire an event, grant in a listener. That felt wrong, and forcing myself to say why produced the most useful line of the whole project:

If using the item exists to produce X, then X is the core action. If X is a bonus layered on top of some other core action, X is a side effect, and it belongs in a listener.

The Suspicious Present is opened to open it, the fun is the opening, and the avatar is a bonus on top, so the avatar is a side effect and goes in a listener. But an avatar-unlock item exists purely to unlock the avatar. That is the point. So it's the core action, not a listener hanging off some other action. Same feature on the surface, opposite correct design, and the deciding question is just "is this the point, or a bonus?" That rule now settles every future "using item X also does Y" question on the team, which is worth far more than the one feature that produced it. It travels well past this codebase, so I gave it its own post.

Reviewers read threads, not commits

One more lesson, cheap but real. At one point I told the agent "you didn't touch this," and it had, the change was just on a line the review thread wasn't anchored to, so I never saw it in the conversation I was actually reading. That's not a code gap, it's a communication gap. Reviewers reason about threads and behaviour, not your commit graph. Making the change isn't the job. Making the change visible in the place the reviewer is looking is the job, and an agent that quietly does the right thing in the wrong place still reads as not having done it.

The throughline: good design here was never specced, it was steered. That only works if iteration is genuinely cheap and someone is holding the standard on every cycle. The AI made the cycles cheap. I held the standard. Between those two, a hardcoded map became a pattern the whole codebase can lean on.

Share this article

Want to Work Together?

Let's discuss how I can help with your project.

Get in Touch