The vibecoding project I could not explain to anyone else
I built something with an AI agent over a weekend. It worked. I was thrilled. Then a friend asked me how it worked and I realized I could not answer.
Not because it was complicated. Because I genuinely did not know. I had described what I wanted, the model had produced it, I had tested the surface, and I had never gone underneath. The whole thing was a black box I had asked a machine to fill.
That moment scared me more than any bug. A product you cannot explain is a product you cannot fix, extend, or defend. And more importantly it is a product you cannot learn from, because the thing you were supposed to learn was the part you skipped.
I still vibecode. But I have added a rule. Before I consider something done, I have to be able to explain the main pieces to another person without looking at the code. If I cannot, I am not done, I am just lucky.
Have you ever built something you could not explain? And did you go back to learn it or just move on?
Replies
I like that rule. A version that works for me is keeping the main ideas of the system as a few one sentence rules at the top of the project notes, written for a human, not for the agent. For my app three of them carry most of the design: only official APIs, the client never grants itself anything (credits are written only by the backend), and a song run is one document the app listens to, never a loop that rechecks everything. If I can explain those three, I can explain the app to a friend, and when the agent proposes something that breaks one of them, I notice even without reading every line.