Design Before Code (I Learned This the Hard Way)

One evening, this analysis appeared in the AI chat window:

"The analyzer is returning plain text, but the orchestrator expects a structured object. The interface is mismatched."

I understood maybe half of that sentence. I knew "analyzer" and "orchestrator" were module names in my project. "Interface is mismatched" made rough sense too—one side sends one format, the other side expects another. Like a plug that doesn't fit the socket.

But what I felt in that moment wasn't technical understanding. It was something more fundamental. Ah, I need to start over.

There was a first version I called V2. Eighteen Python files. A system that monitored YouTube channels, grabbed subtitles when new videos appeared, and sent them to AI for analysis. I ran it on my own computer, and it worked. I was genuinely moved by the fact that it worked. I hadn't written a single line of code myself, yet a program was functioning.

The problems erupted when I tried to expand it into a web service.

A program running on my computer for my use alone is structurally different from a service on the internet for multiple people. Restaurant analogy: cooking for your family at home versus opening a restaurant. The recipe (core functionality) might be the same, but you need kitchen equipment, health codes, an ordering system, a register.

I asked the control tower (my name for the AI chat window) to analyze V2's structure. The diagnosis came back with six issues.

First, there was no table in the database for storing analysis results. Think of the database as an Excel file—the sheet for recording analysis results simply didn't exist. V2 saved results as individual files each time, so the sheet wasn't needed. But a web service needs to systematically store results for multiple users.

Second, there was no mechanism to distinguish users. V2 was a solo program, so the concept of "user" was unnecessary. But a web service requires knowing "this result belongs to User A, that one to User B."

Third was the problem the control tower flagged. The analyzer module finished its work and returned a blob of text. But the orchestrator module—which receives that result and passes it to the next step—expected a structured object: title, summary, key points, and related concepts each separated out. Like mailing a letter when the recipient is waiting for a package.

The other three were similar in nature. All the kind of issues that work fine solo but break when multiple people use the service.

I was rattled, honestly. It meant rebuilding something I'd spent weeks on. But there was also a strange relief. Better to know now than to launch a web service and have it blow up later.

I decided on a full V3 refactoring. Refactoring means restructuring the internals while keeping the functionality. Like redesigning the kitchen layout without changing the menu. Though in my case, it was more like demolishing the kitchen and rebuilding.

This time I did it differently. I created documents before writing a single line of code.

Architecture document—diagramming how the whole system is structured and how data flows. Build prompt—a document instructing the AI "build only this, absolutely don't touch that." Checklist—listing items to verify at each stage. Cost model—calculating how much running the AI would cost. i18n spec—what needs to differ for Korean, Japanese, and English.

Five types of documents. Documents before code.

While building the checklist, I learned how dangerous "95% complete" really is. V2 was exactly that. Core features worked. Looked about 95% done. But the remaining 5%—user distinction, data storage structure, module interfaces—blocked all progress to the next stage. Five percent was blocking one hundred percent.

Creating documents first might sound odd. Why sit writing when you need to build fast? But for someone who can't read code, documents are especially critical. Since I can't review code myself, telling the AI "build exactly as this document says" is my only quality control. If the document is precise, the code will be precise. If the document is vague, the AI will interpret on its own, and that interpretation will likely differ from my intent.

The night I restarted V3, I sat not at the terminal running code, but at the chat window refining documents. It felt unproductive. But from that point on, through the entire V3 build, the kinds of problems I'd faced in V2 never occurred again.

---

🔧 Technical Terms in This Episode

Refactoring Restructuring code's internals while keeping its functionality. Like redesigning a kitchen layout without changing the menu.

Database Table Like a sheet in an Excel file where data is stored. No sheet means nowhere to save data.

Interface The specification for how modules exchange data. Think of it as the shape of a plug and socket—if they don't match, nothing connects.

DI — Dependency Injection Like a LEGO assembly manual. A design pattern that pre-defines which parts (modules) connect to which other parts, so you can swap components without dismantling everything.

Orchestrator A conductor that coordinates the work sequence of multiple modules. "First grab the subtitles, then send to AI for analysis, then save the result."