{"id":57,"date":"2026-06-30T22:00:00","date_gmt":"2026-06-30T13:00:00","guid":{"rendered":"https:\/\/sr-works.net\/blog-en\/?p=57"},"modified":"2026-06-30T00:49:23","modified_gmt":"2026-06-29T15:49:23","slug":"the-design-phase-in-three-sessions-having-ai-design-the-architecture","status":"publish","type":"post","link":"https:\/\/sr-works.net\/blog-en\/the-design-phase-in-three-sessions-having-ai-design-the-architecture\/","title":{"rendered":"The Design Phase in Three Sessions \u2014 Having AI Design the Architecture"},"content":{"rendered":"\n
\n

This article was originally written in Japanese and translated into English with AI assistance. Please note that some expressions may carry nuances from the original Japanese.<\/em><\/p>\n<\/blockquote>\n\n\n\n

\ud83c\uddef\ud83c\uddf5 \u65e5\u672c\u8a9e\u7248\u306f\u3053\u3061\u3089 \/ Japanese version<\/a><\/em><\/p>\n\n\n\n

\n\n\n\n

Series: DataMigrator Development Journal (Part 4)<\/p>\n\n\n\n

\n\n\n\n

By the end of last time, I’d finished writing Rev.7 of the requirements document, and I was ready to advance to the design phase. This time is about that design phase.<\/p>\n\n\n\n

To get to the point: I split the design phase into three sessions total. Session 1 for the architecture, Session 2 for the database and classes, Session 3 for the GUI and tests. About eight design documents came out of it, and the total volume reached a fair thickness. I wrote all of them together with Claude. Until this period, I’d never imagined that someone with zero programming experience would end up writing an architecture design document.<\/p>\n\n\n\n

Starting by Asking the AI What Design Even Is<\/h2>\n\n\n\n

Honestly, at first I didn\u2019t quite get the difference between requirements and design. Requirements are \u201cwhat to build,\u201d design is \u201chow to build it\u201d \u2014 that\u2019s what the books say, but concretely, what am I supposed to do? \u201cHow to build it\u201d shouldn\u2019t mean the code itself, so then this something that sits one step before the code \u2014 at what level of granularity are we talking?<\/p>\n\n\n\n

When I asked Claude, the explanation that came back was roughly the following. A requirements document is a request form \u2014 \u201cplease build this\u201d \u2014 while a design document is closer to \u201cthe blueprints of a building that satisfies that request.\u201d A building\u2019s blueprints have layers \u2014 the number of floors, the room layout, the placement of pillars, the plumbing, the wiring \u2014 and each is drawn on a separate sheet. Software is the same: you need a separate design document for each layer \u2014 the overall structure (architecture), how the data is held (DB), the relationships among the parts (classes), the appearance (GUI), the method of quality verification (tests), and so on. Starting to write code only after all these design documents are in place corresponds, in building terms, to \u201cbringing in the materials only after the foundation and blueprints are done.\u201d That was the explanation.<\/p>\n\n\n\n

This explanation made me understand: \u201cAh, so that\u2019s why you split it into three sessions.\u201d Asking, in a single chat, \u201cplease write all the design documents\u201d is like suddenly telling a single architect \u201cgimme all the drawings\u201d \u2014 it\u2019s not realistic. Splitting it by layer and working through them one at a time is something I, as a human, can keep up with too.<\/p>\n\n\n\n

Session 1: Architecture<\/h2>\n\n\n\n

In the first session, I decided the skeleton of the whole software. It\u2019s the configuration known as a \u201cthree-layer architecture.\u201d You divide it into three: the GUI layer (the part that interacts with the user), the business-logic layer (the part that assembles the processing you actually want to do), and the data-access layer (the part that accesses the database and file system).<\/p>\n\n\n\n

Put like that, it just sounds like a classification, but what was interesting in this session was that the idea of a \u201cshared engine\u201d came up.<\/p>\n\n\n\n

In the requirements, I\u2019d decided to build three modes for DataMigrator (Exploration mode, Quick mode, Full-inspection mode). Naively, you\u2019d write unique processing logic for each of the three modes. But look closely, and what the three modes do has a lot in common. They all share the same skeleton: first scan the files, then take hashes, and finally group and display the results. What differs is only the parameters \u2014 things like the scan scope and the way hashes are taken.<\/p>\n\n\n\n

What Claude proposed was the policy: \u201crather than writing processing logic for each of the three modes, build just one set of shared engines (a scan engine, a hash engine, a grouping engine) and change how they\u2019re called per mode.\u201d Doing this reduces the amount of code, means a fix only needs to happen in one place when a bug appears, makes it easier to carry data over between modes, and makes it easier to merge or add modes in the future \u2014 the benefits were laid out one after another.<\/p>\n\n\n\n

At this point, I asked one question back: \u201cWhat\u2019s the benefit of going with this policy? Is it that the implementation cost is low?\u201d From the perspective of someone with no programming experience, I had an intuitive grasp that \u201cgathering similar things in one place seems good,\u201d but I didn\u2019t understand concretely what it led to.<\/p>\n\n\n\n

The answer that came back raised, beyond implementation cost, perspectives like \u201clocalization of bugs,\u201d \u201ctest efficiency,\u201d \u201ccarrying data over between modes,\u201d \u201cfuture flexibility,\u201d and \u201censuring consistency\u201d \u2014 and I remember it sinking in: \u201cah, so it has that wide an effect.\u201d For me, this single exchange was the moment that decided the direction of the entire design phase. Had I just thrown it over the wall with a \u201cleave it to the pro,\u201d I think I\u2019d probably have regretted something later.<\/p>\n\n\n\n

Session 1 also decided other things: the thread configuration (one main thread and one worker thread), the method for cancellation handling, and the method for detecting when you step into a symbolic-link loop. These were the result of crushing the architecture-related items from among the homework that had been left in Appendix C.<\/p>\n\n\n\n

Session 2: Database and Classes<\/h2>\n\n\n\n

The second session was the design of how to hold the data and of the parts.<\/p>\n\n\n\n

I decided to use SQLite for the database. For a personal tool, where the use is no more than storing file metadata and hash values, SQLite is plenty. There\u2019s no need to stand up a separate server, and the fact that it completes in a single file is a welcome thing.<\/p>\n\n\n\n

The table structure settled into five tables: a table to store the history of scan runs, a table to store information for each individual file, a table to store groups of duplicate candidates, a table for error logs, and a table for file-move logs. The structure has these five connected to one another by foreign keys.<\/p>\n\n\n\n

This gets into the weeds, but what quietly troubled me in this session was the \u201cis it okay to put two different meanings of data in the same table?\u201d problem. Quick mode\u2019s \u201cduplicate-candidate groups\u201d and Full-inspection mode\u2019s \u201cconfirmed-duplicate groups\u201d are, strictly speaking, different in meaning. The former is \u201conly the name, size, and partial hash match,\u201d while the latter is \u201cmatched completely, all the way to the full hash.\u201d Is it okay to put these in the same table, or should they be in separate tables?<\/p>\n\n\n\n

As a result of discussing it with Claude, I went with the policy of using the same table and distinguishing them with a \u201cgroup type\u201d column. The big benefit was that being able to handle them in the same table makes it easier to carry data over from Quick mode to Full-inspection mode. It\u2019s through an accumulation of small decisions like this that the design document fills up.<\/p>\n\n\n\n

On the class-design side, I defined around thirty classes: the engine family, the mode-controller family, the data-access family, the worker-thread family, the utility family, the custom-exception family. For each individual class, the role and the public methods get written out. I don\u2019t write code, but at this stage an image started to come into view: \u201cah, so this class gets called like this.\u201d I think the sensation of the software starting to move inside my head gradually began to emerge around this time.<\/p>\n\n\n\n

Session 3: GUI and Tests<\/h2>\n\n\n\n

The third session was screen design and test planning.<\/p>\n\n\n\n

In the GUI design, I defined nineteen screens: a mode-selection screen, a folder-selection screen, a progress screen during a scan, a results-display screen, a confirmation screen for deletion candidates, a settings screen, error dialogs, and other auxiliary screens. I had Claude write out the role of each screen and the flow of the main operations. I didn\u2019t draw the actual appearance as pictures \u2014 it was closer to a bulleted level of \u201cthis screen has these items lined up on it\u201d \u2014 but even so, I had the sensation of \u201cthe tool\u2019s form, as seen by the person using it\u201d gradually rising up.<\/p>\n\n\n\n

What was intriguing was that, in the middle of doing the GUI design, an idea for a new feature occurred to me. It was the thought, \u201crather than only deleting duplicate files, it might be handy to have a mode that gathers the scattered actual data into one place (consolidation into a storage folder)\u201d \u2014 a feature that hadn\u2019t been written in the requirements document.<\/p>\n\n\n\n

Naively, the proper thing would be to go back to the requirements and add it as Rev.8. But as a result of consulting Claude, we discussed \u201cis this feature high enough priority to include in the MVP,\u201d judged that it was \u201cworth including,\u201d and then took it in by adding it to the design document. Whether to strictly adhere to the requirements, or to flexibly take in improvements you notice along the way \u2014 this is a hard line to draw, but this time I chose the latter. Looking back now, I think it\u2019s one of the strengths of solo development. In a large organization, taking in a mid-stream idea like this would require meeting after meeting.<\/p>\n\n\n\n

In the test design, I defined just under eighty unit-test cases and a dozen-odd integration-test scenarios. All of these would get written during the implementation phase. At this point, I had the surprise within me of \u201cso that\u2019s how much testing you write.\u201d I came to terms with it: this is probably, in essence, the same as how there are days and days of full run-throughs before a theater performance. Going in cold without rehearsal doesn\u2019t work \u2014 on the stage or in software alike.<\/p>\n\n\n\n

After Finishing Eight Design Documents<\/h2>\n\n\n\n

After three sessions, the design documents came to eight in total: software architecture, source-code organization, GitHub repository structure, DB schema, class design, GUI design, test design, and the initial prompt for the implementation phase. On top of these, auxiliary materials such as handoff prompts between sessions and meeting notes also piled up.<\/p>\n\n\n\n

Honestly, my impression when the whole thing was finished was \u201cis this really okay?\u201d Even though I wrote it together with AI, I myself have zero programming experience. There\u2019s a limit to how well I can judge whether these design documents are of a quality that can withstand implementation. Gazing at the table of contents, I can tell it somehow looks the part, but I lack the foundational knowledge to scrutinize all the contents myself.<\/p>\n\n\n\n

Still, I couldn\u2019t very well stay stopped here, so I confirmed things up to the point of \u201cat least all the Appendix C homework is crushed, consistency with the requirements document holds, and the obvious holes have been plugged through discussion with Claude,\u201d and made the decision to advance to the next phase. If it turns out to be no good, then it\u2019s no good, and I\u2019ll fix it in the implementation phase. That kind of resignation.<\/p>\n\n\n\n

Incidentally, the time it took to write the eight design documents was, in total, I think a little over ten hours \u2014 about two to three hours per session. For someone with no programming experience to write this volume of documentation from scratch on their own would probably be impossible even with months. It\u2019s because I did it together with AI that it took only this much time. Of that, there\u2019s no doubt.<\/p>\n\n\n\n

Next Time<\/h2>\n\n\n\n

Next time, I finally enter the \u201chave AI write the code\u201d phase. But before that, one more preparation was needed. Separate from the Claude I\u2019d been using so far (the chat version used in a browser), I needed to introduce a type of Claude that runs in the terminal, called \u201cClaude Code.\u201d Starting from installing it on the Mac, having it write \u201cHello World\u201d in a practice project, understanding the security mechanisms, preparing the directory for the production project \u2014 the plain, unglamorous prep work continues. Along the way, there were a few stumbles, too: hitting Python-environment problems when I tried to run PySide6, and strange errors in GitHub authentication. Look forward to the Claude Code introduction installment.<\/p>\n\n\n\n

\n\n\n\n

About Soul Resonant Works<\/h2>\n\n\n\n

Soul Resonant Works is a solo venture developing seven local AI systems. Starting from zero programming experience, the development is progressing through collaboration with AI.<\/p>\n\n\n\n

\ud83c\udf10 Soul Resonant Works:
\u2192 https:\/\/sr-works.net\/en\/index.html<\/a><\/p>\n\n\n\n

\ud83d\udcdd This blog publishes the entire development process as a serialized journal.<\/p>\n\n\n\n

\n\n\n\n

If you found this article useful, please share it.<\/em><\/p>\n","protected":false},"excerpt":{"rendered":"

This article was originally written in Japanese and translated into English with AI assistance. Please note that some expressions may carry nuances from the original Japanese. \ud83c\uddef\ud83c\uddf5 \u65e5\u672c\u8a9e\u7248\u306f\u3053\u3061\u3089 \/ Japanese version Series: DataMigrator Development Journal (Part 4) By the end of last time, I’d finished writing Rev.7 of the requirements document, and I was ready […]<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[3],"tags":[],"class_list":["post-57","post","type-post","status-publish","format-standard","hentry","category-ai-development-journal"],"_links":{"self":[{"href":"https:\/\/sr-works.net\/blog-en\/wp-json\/wp\/v2\/posts\/57","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/sr-works.net\/blog-en\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/sr-works.net\/blog-en\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/sr-works.net\/blog-en\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/sr-works.net\/blog-en\/wp-json\/wp\/v2\/comments?post=57"}],"version-history":[{"count":1,"href":"https:\/\/sr-works.net\/blog-en\/wp-json\/wp\/v2\/posts\/57\/revisions"}],"predecessor-version":[{"id":59,"href":"https:\/\/sr-works.net\/blog-en\/wp-json\/wp\/v2\/posts\/57\/revisions\/59"}],"wp:attachment":[{"href":"https:\/\/sr-works.net\/blog-en\/wp-json\/wp\/v2\/media?parent=57"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/sr-works.net\/blog-en\/wp-json\/wp\/v2\/categories?post=57"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/sr-works.net\/blog-en\/wp-json\/wp\/v2\/tags?post=57"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}