Let’s be honest: modern LLMs write amazing code. Sometimes I look at the output and realize I couldn’t have done it better or faster myself. It hits you with this almost addictive rush of speed.
But that speed comes with a cost: you stop understanding what’s happening.
Recently, I was working on my pet project — a Telegram bot that turns articles into audio. I wanted to add one simple feature: a "Detailed Summary" mode. I threw a quick prompt at the AI:
Give users a way to get more detailed summaries
At first glance, everything looked fine. Then I tried to understand the diff.
I couldn't.
The Chaos of "Just Prompting"
I had a clean setup: all my prompts lived in a prompts.yaml file, and a PromptBuilder class would neatly assemble them. It was a predictable, single-source-of-truth system.
The agent ignored all of it. Instead of adding a template to the YAML, it shoved raw strings directly into the C# code.
It introduced if/else logic inside the builder and added extra prompt instructions as raw string literals. My architecture just left the building. Now I had two sources of truth.
But the worst part was the UX. Instead of adding a simple Telegram button to trigger the detailed mode, the AI decided that the user should manually type magic hashtags like #detailed. It chose the easiest path for the code, not the user.
The model optimized for its own convenience, not for my system. And it made dozens of decisions I never asked for.
The Spec as Anxiety Relief
I realized I was tired. Tired of holding my breath every time I hit "Apply," wondering what exactly was about to break.
At some point, I realized this isn’t just about AI being unpredictable. It’s about me not defining things clearly enough. That’s when I started using a Spec.
It’s not just a technical fix; it’s anxiety relief. When I put a Markdown file in Git between my head and the code, I can finally breathe. I’m no longer guessing what’s going to happen.
My Workflow
The Architecture Chat: I use ChatGPT to argue about edge cases. I often dictate my thoughts by voice—it's easier to "think out loud" about things like race conditions. We talk until we have a solid
feature_spec.mdfile.The Consistency Check: I make the coding agent compare the new spec with my actual repo. If the AI finds a contradiction before writing code, I’ve already won.
The Implementation: Only when the spec and architecture are aligned do I let the AI touch the code.
Same Task. Same AI. Different Outcome.
When I implemented the same feature using a spec, the result was night and day.
I explicitly defined the rules: "Use the existing YAML prompt storage. Use Telegram's native buttons. Do not force the user to type hashtags."
The agent followed the contract. This time, it created a new prompt template in the right place and implemented a clean button-based UX.
The difference wasn’t the model. It was the spec. The code remained clean, the architecture stayed intact, and I actually understood the diff.
Bottom Line
AI is a fast, but very average developer.
Without boundaries, it will pick the easiest, messiest path. It will still "work." And that's the dangerous part. You won't notice the rot until it's too late.
Stop prompting. Start defining.
How do you handle the AI's urge to "improve" your architecture without asking? Let’s discuss in the comments.
Photo: William Murphy / flickr — CC BY-SA 2.0
Top comments (0)