Before Writing a Single Line of Code --- Design Documents First

 

Writing design documents for a side project? Isn't that overkill? Most developers would think so. I certainly did during my Tarot project. But for the Saju project, I created four design documents in a docs/ folder before writing a single line of code. And that decision completely changed the game for AI collaboration.

With Tarot, I Went Straight to Code

Think back to the Tarot Master project. In Part 1, I tossed an idea, explored the domain, and started coding right away. And it worked. Tarot's structure was simple enough that coding on the fly while chatting with AI did not cause problems.

But early in the Saju project, as I explored the domain with AI, I noticed something. This domain does not fit within a single conversation session. Heavenly Stems (Cheongan, 天干) and Earthly Branches (Jiji, 地支), the Five Elements (Oheng, 五行), Ten Gods (Sipsin, 十神), Hidden Stems (Jijanggan, 地藏干), Combinations and Clashes, the Twelve Life Stages. Each is an independent system, yet they are all deeply intertwined. Trying to cover all of them in one session blurs the context.

The more fundamental problem surfaces when sessions change. AI conversations are session-based. Start a new session and the previous context vanishes. With Tarot, this was not a big deal --- you can re-explain 78 cards and a few spreads in a few lines. But re-explaining Saju's domain knowledge from scratch every session? Not realistic.

Design Documents as the Solution

Design documents were the answer. If you write down domain knowledge and design decisions as documents first, those documents become "permanent context" for the AI.

The idea was simple. With domain knowledge and architecture decisions documented, a new session can begin with a single @docs/ context load, and the AI understands the full picture from the start. No more repeating "This project is a Saju analysis web app with a hybrid architecture, True Solar Time correction, and..."

This was not merely a convenience improvement. It changed the quality of AI collaboration itself. Asking code from an AI that has no context versus asking code from an AI that understands the entire architecture and domain model --- the quality difference in the output is enormous.

The Four Documents in docs/

Four core design documents went into the project's docs/ folder.

The first was the architecture document. It covers the overall system structure: a React 19 + TypeScript + Vite + Zustand frontend, a Cloudflare Workers + Groq API backend for AI interpretations, and the hybrid structure of rule-based analysis engine plus AI interpretation. How each layer communicates and how data flows between them.

The second was the domain model document. This was the most extensive --- 35 pages covering the core concepts of Saju from a developer's perspective. The attributes of all 10 Heavenly Stems and 12 Earthly Branches, the 60 Stem-Branch Cycle, the Five Elements generating and overcoming relationships, the Ten Gods classification system, Hidden Stems assignments, the Twelve Life Stages table, every combination of Combinations and Clashes. What each concept means, what data structure should represent it, and where school-specific differences exist.

The third was the calculation engine document. Manselyeok conversion logic, True Solar Time correction algorithms, DST correction, Late Night Hour handling, Solar Term-based month determination --- everything about the process of "converting a birth date and time into Four Pillars."

The fourth was the AI interpretation document. The structure for passing rule-engine analysis data to AI for natural-language interpretation generation. Prompt design, tone and depth of interpretation, structured analysis data format.

A 35-Page Domain Model

The document I poured the most effort into was the domain model --- 35 pages. For a side project, that might feel excessive. But those 35 pages contain the complete core system of Saju with nothing left out.

Why did it need to be this detailed? Saju is a system accumulated over thousands of years, packed with countless "rules." Gap (甲) is Yang Wood. Eul (乙) is Yin Wood. Gap and Gi (己) combine. In (寅), O (午), and Sul (戌) form a Three Harmony Fire combination. Each of these rules becomes a mapping table in code.

What happens if you skip the document and implement these rules one by one through AI chat? "Gap and Gi combine, right?" "Yes." "What about Eul and Gyeong?" "They combine." "And Byeong and Sin?" --- you end up asking one at a time. It is inefficient, and it is hard to maintain consistency across the whole system.

With all five Stem Combinations, four Three Harmonies, four Directional Combinations, six Six Harmonies, and six Six Clashes documented in the domain model, the AI reads it once and grasps the entire structure before writing code. It does not verify individual rules one by one --- it implements with systemic understanding.

The Magic of @docs/

The true value of design documents shows when you start a new session. You open a new conversation, load the @docs/ folder as context. In that instant, the AI understands this project's architecture, domain model, calculation logic, and AI interpretation structure.

In this state, when you request "implement the Ten Gods analysis function," the AI already knows: that Ten Gods classifies the Yin-Yang and Element relationship between the Day Stem and every other character into 10 categories; that same Element means Companion, the Element I generate means Output, the Element that generates me means Resource; that matching Yin-Yang polarity means "Indirect" while opposing polarity means "Direct." The domain model document contains all of this.

Without documents? "Do you know what Ten Gods are?" "Yes, Ten Gods are..." "If the Day Stem is Gap (甲) and the other character is Byeong (丙), what is it?" "Food God." "Why?" "Gap is Yang Wood, Byeong is Yang Fire, Wood generates Fire so it's Output, and Yang meets Yang so..." This back-and-forth repeats every session. Loading documents eliminates this repetition.

Per-Session Repetition vs. Document-Based Context

Let me make the comparison more concrete.

Working without documents: New session starts. Explain project overview (5 minutes). Explain current task context (5 minutes). Explain decisions from previous sessions (5 minutes). Begin actual work. That is 15 minutes of context-setting per session. And those explanations are never quite perfect --- you forget things, you misremember.

Working with documents: New session starts. Load @docs/ (1 minute). One line: "Last session I implemented up to Combinations and Clashes; this session I want to tackle the Twelve Life Stages." Begin actual work. Context-setting done in 2 minutes. And since everything is in the documents, nothing gets left out.

The Saju project took dozens of sessions to complete. Saving 13 minutes per session, compounded over dozens of sessions, adds up to a significant amount of pure time savings. But the bigger benefit is context quality. Verbal explanations per session produce incomplete, inconsistent context. Loading documents delivers complete, consistent context every time.

How Documents Improve Code Quality

I realized that design documents do more than save time around the midpoint of the project.

When AI writes code with the full architecture in mind, each function's interface naturally aligns with the overall structure. The data shape returned by the Five Elements analysis function connects seamlessly with the Ten Gods analysis function's input. Each module is not "a piece built in isolation, ignorant of the whole" but "a puzzle piece shaped to fit its exact place in the whole."

This is true when humans write code too. A module written by a developer who does not know the overall design versus one written by a developer who does --- the quality differs. The same principle applies to AI. The difference is that AI, once given the documents, understands them "completely," making the effect even more dramatic than with humans.

Writing Design Documents Together with AI

One important point: I did not write these four documents alone. I wrote them with AI.

Take the domain model as an example. The process looked like this: First, I ask AI to explain the core concepts of Saju. Based on that explanation, AI drafts the document. I read the draft, ask questions where I do not understand, and request additional information from a developer's perspective. AI produces a revision. Iterating through this process yielded 35 pages.

The process itself was domain learning. Writing the documents forced me into a deep understanding of Saju's system. Understanding the domain thoroughly before writing code --- that is the hidden advantage of "design documents first."

Tarot vs. Saju: Why the Approach Must Differ

With Tarot, going straight to code worked well. With Saju, a documents-first approach was necessary. This difference stems from domain complexity.

Tarot's domain knowledge fits comfortably in a single conversation session. 78 cards, upright/reversed, three spread types. Saju's domain knowledge is difficult to convey even across multiple sessions. An "external memory" in the form of documents is necessary.

The lesson from this experience: the methodology for AI collaboration should vary by project. Excessive documentation for a simple project is overengineering. Proceeding without documentation on a complex project means repeating the same explanations inefficiently. Domain complexity determines the approach.

What I Learned Along the Way

First, design documents are simultaneously "documentation for humans" and "permanent context for AI." This dual role gives documentation new value in the AI era.

Second, the more complex the domain, the more important it is to document before coding. The writing process itself is domain learning, and the finished documents become context for every future session.

Third, writing documents together with AI produces faster and more systematic documentation than writing alone. AI supplies domain knowledge; I structure it from a developer's perspective.

Next Up

Design documents are complete. It is finally time to write code. The first task: expressing 10 Heavenly Stems and 12 Earthly Branches as TypeScript types. What design decisions were needed to "translate" a thousand-year-old Yin-Yang and Five Elements system into a modern programming language, and how I handled the first school-of-thought divergence in code --- Part 4 continues the story.