Design Documents First — A Game Changer in the AI Era

 

Write the document before writing a single line of code. Every developer knows the principle; few actually follow it. But working with AI, I discovered this isn't just a best practice — it's a productivity multiplier. Especially in a complex domain like Four Pillars of Destiny (Saju), the gap between having and not having design documents was night and day.

The Tarot Approach — Conversation to Code

Let's look back at the Tarot project. The workflow went like this: chat with AI about "how should we structure the data for 78 cards?", AI proposes something, and you immediately translate it into code. If it works, move to the next feature. If there's a problem, continue the conversation and iterate.

This approach was fast and intuitive. For Tarot's complexity level, it worked fine. 78 cards, fixed interpretation texts, relatively straightforward reading logic. The entire structure fit in my head, so conversational development maintained consistency.

But the cracks appeared when the Saju project began. Heavenly Stem (Cheongan) and Earthly Branch (Jiji) calculations, Ten Gods (Sipsin) relationships, combinations and clashes, 12 Life Stages, Hidden Stems (Jijanggan), chart patterns, Favorable Element (Yongsin). All of these elements interlock with each other, and maintaining context through conversation alone in such a domain was impossible.

The Moment I Hit the Wall

Early in the Saju project, I tried the same conversational approach. Chat with AI, "Let's implement the Ten Gods calculation logic," and AI generates code. But in the next session, when I said "Let's add Hidden Stems analysis," AI sometimes proposed a structure inconsistent with the previous session's Ten Gods logic.

The reason was simple. AI conversation context has limits. What decisions were made in previous sessions, how data structures were defined, why a particular approach was chosen — this information vanishes in new sessions. Code tells you "what" but not "why."

In Tarot, this wasn't a big deal. The structure was simple enough that code alone conveyed context. In Saju, it was different. "Why we defined Indirect Seal this way in the Ten Gods table" can't be read from code. The decision's background, the alternatives considered, the school-of-thought differences — only documents can capture this context.

The Birth of docs/

So I created the docs/ folder. It started as "something to reference later," but its role steadily grew.

The folder accumulated a variety of documents: domain model definitions, data structure specifications, design decision records for each feature, school-of-thought calculation differences, API specs, UI flows. All documents were written in Markdown — a format equally readable by humans and parseable by AI.

The key insight was that these documents served a dual purpose: "human documentation" and "AI context." I needed to be able to read them weeks later and understand "why it was designed this way," and AI needed to be able to load them and grasp the full project context.

For example, the Ten Gods relationship specification included: the definition of Ten Gods, calculation rules for each, differences across schools of thought, the chosen method and rationale, and paths to related code files. Loading this single document gave AI complete understanding of "how this project handles Ten Gods," enabling it to write or modify related code in full alignment with the existing codebase.

Loading @docs/ — AI Codes with Full Context

The practical workflow transformed. Before implementing any new feature, I load the relevant design documents into AI. "Read and understand these documents, then implement this feature."

For example, when building Compatibility Analysis (Gunghap): first, load the Ten Gods specification, Five Elements generation/destruction rules, and combination/clash rules. Then request: "Implement the logic for analyzing compatibility between two charts." AI already knows how the project defines Ten Gods, what rules govern Five Elements relationships, so it generates code consistent with the existing codebase.

In the old approach, I'd explain every session: "Ten Gods are calculated like this, Five Elements have this relationship, our project uses this structure." With design documents, that explanation becomes unnecessary. Load the docs. Done.

The productivity difference was visceral. The 10-15 minutes per session spent re-establishing context vanished. And the consistency issues caused by slightly different explanations each time were eliminated.

Three Practical Benefits of Design Documents

Here are the three benefits I experienced firsthand.

First, structured thinking. The act of writing a document organizes your thoughts. When you outline "what factors matter in compatibility analysis" as a document, design gaps surface before you write any code. The "oh, I forgot this" moments during implementation decrease dramatically.

When you jump straight to coding, it's easy to get trapped in "just make it work." Writing the document first lets you separate "what to build" from "how to build it." This separation makes a substantial difference in design quality.

Second, persistent AI context. Conversations vanish when a session ends; documents persist. When you reopen the project next week, or when maintenance is needed three months later, loading the documents lets AI immediately grasp the full project context. This is essentially "long-term memory for AI."

For a project like Saju where domain knowledge is vast, the value of persistent context is immense. Imagine the difference between re-explaining the Five Elements mappings, Ten Gods calculation rules, and school-of-thought differences every session versus loading a document once.

Third, a foundation for team scaling. This is currently a solo project, but if another developer joins in the future, these documents become onboarding material. When a new developer joins a code-only project, they figure out "why the code is structured this way" by digging through the code. Design documents slash that time dramatically.

And this applies equally to AI team members. Opening a new AI session is like a new team member joining. The most efficient way to brief that team member is design documents.

"Clearly Defining What to Build"

If you asked me what the most important skill is for developers in the AI era, I wouldn't say "coding ability." I'd say "definition ability" — the ability to clearly define what to build.

AI excels at "how." "Implement the Ten Gods calculation logic" produces good code. But "what" must be determined by humans. Which rules govern Ten Gods calculation, which school of thought to follow, how to handle edge cases.

Design documents are the tool for recording this "what" clearly. The more precise the document, the higher AI's implementation quality. Vague instructions produce vague results; clear definitions produce clear results. This is also the essence of prompt engineering.

The ROI of Design Documents Scales with Domain Complexity

Writing design documents has a cost. It takes time. It feels slower than jumping straight to code. That's why many developers skip it.

But the return on this investment (ROI) scales exponentially with domain complexity.

In a simple domain like Tarot, you can get by without documents. The entire structure fits in your head. The investment may not pay back much.

In a complex domain like Saju, documents are essential. The entire structure doesn't fit in your head, and it doesn't fit in AI's context window all at once either. Without documents, you pay the cost of reconstructing context every session, and the risk of consistency breaking grows. The initial cost of writing documents is far less than the recurring cost of not having them.

In my experience with this project, the time invested in the docs/ folder paid back roughly 3-5x. If writing a document took 2 hours, that document saved 6-10 hours in subsequent implementation and maintenance.

The Document-First Development Workflow

The finalized workflow:

Step 1, problem definition. Write one paragraph about what feature you're building and why. Step 2, domain research. Chat with AI to understand the domain's rules and exceptions. Step 3, design document. Write the data structure, calculation rules, UI flow, and exception handling approach. Step 4, document review. Load the document into AI and ask "Are there any gaps in this design?" Step 5, implementation. Write code with AI based on the document.

Steps 1 through 3 consume 60% of total time. Code writing is 40%. Compared to traditional development where coding is 80%+, the ratio is completely inverted.

But this inversion actually improved overall productivity. When design is solid, implementation has fewer wrong turns, fewer bugs, and less refactoring.

What This Process Taught Me

First, design documents benefit the writer most. It feels like you're writing for others, but the writing process is where your own thinking gets organized the most.

Second, documents in the AI era serve a dual audience — human and AI. Documents that are understandable to humans and serve as valid context when loaded into AI. Satisfying both simultaneously is the key.

Third, the next evolution beyond "vibe coding" is "vibe design." If vibe coding is writing code with AI, then organizing design with AI and implementing based on that design is the next level. The paradigm shift isn't about generating code faster — it's about thinking more clearly before code is written.

Coming Up Next

Part 19's story concludes our methodology discussion. Part 20, the final installment, looks back at the full journey from Tarot to Saju. What AI did well, what humans had to do, and the biggest thing AI changed in a 28-year development career. The series finale awaits.