{"id":46,"date":"2026-06-16T10:18:22","date_gmt":"2026-06-16T01:18:22","guid":{"rendered":"https:\/\/sr-works.net\/blog-en\/?p=46"},"modified":"2026-06-16T10:18:22","modified_gmt":"2026-06-16T01:18:22","slug":"when-i-had-ai-write-requirements-it-took-5-revisions","status":"publish","type":"post","link":"https:\/\/sr-works.net\/blog-en\/when-i-had-ai-write-requirements-it-took-5-revisions\/","title":{"rendered":"When I Had AI Write Requirements, It Took 5 Revisions"},"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 2)<\/p>\n\n\n\n

\n\n\n\n

Last time, I wrote about how, in order to escape data-migration hell, I decided to build a tool to solve that hell myself. This time is the next step: the stage of deciding “so what, exactly, am I going to build?” It’s a record of someone with zero programming experience attempting what’s called a requirements definition, together with AI.<\/p>\n\n\n\n

To get to the point: the first version (Rev.0) ended up being almost entirely rewritten. From there I went through five more revisions before finally reaching a state where I could think, “Okay, this looks ready to move on to design.” You might assume that since I was working with AI, a perfect requirements document would pop out on the first try \u2014 but that wasn’t the case at all, and that’s the theme of this installment.<\/p>\n\n\n\n

What Is a Requirements Definition, Anyway?<\/h2>\n\n\n\n

I’m a little embarrassed to admit it, but before I started development, the term “requirements definition” was something I’d only vaguely heard of. How it differs from a “specification,” how it differs from a “design document” \u2014 honestly, I don’t think I could have explained any of it cleanly.<\/p>\n\n\n\n

To put it simply in my own current understanding, a requirements definition is the work of deciding, in words, “what to build and what not to build.” “How to build it” comes one step later (that’s design), and the concrete code comes at the very end. The order goes requirements \u2192 design \u2192 implementation, gradually raising the resolution stage by stage.<\/p>\n\n\n\n

Even when you have AI do the development in the style called vibe coding, if this “what to build” is fuzzy, what the AI produces comes out fuzzy too. Sure, the human only has to give instructions in plain language \u2014 but if that language is vague, you end up with a mountain of rework. This is one of the parts where, even leaning on AI, the human still has to do the thinking.<\/p>\n\n\n\n

So, to begin with, I used an AI system other than Claude to write up Rev.0 of the requirements document. The reason I started with a different AI was simply that I’d had a project going on over there earlier, and in the flow of things I just kept writing with that same AI. There was no deeper meaning to it.<\/p>\n\n\n\n

Rev.0 Had Sky-High Resolution on the Problem Alone<\/h2>\n\n\n\n

Rev.0 of the requirements document was packed with the concrete hardships I’d experienced during data migration. What traps lay in moving files between the iMac and the MacBook Pro. The macOS-specific issue of purgeable space. The matter of iCloud-synced placeholders whose actual contents hadn’t been downloaded. How invisible files like .DS_Store<\/code> become noise. How rsync<\/code> spits out tens of thousands of log lines you can’t read. How a multi-terabyte hash comparison takes who-knows-how-many hours.<\/p>\n\n\n\n

Reading it back, it was certainly a document that conveyed “this person really did struggle.” But flip that around, and you could just as easily say it was “a memo of grievances with a feature list stapled on” \u2014 the solution side was quite rough.<\/p>\n\n\n\n

For example, the processing flow was laid out in a straight line: “GUI input \u2192 pre-check \u2192 rsync \u2192 analysis \u2192 judgment \u2192 copy \u2192 output.” At a glance it looks tidy, but what if rsync fails? What if the NAS disconnects partway? What if you run out of space? What if the user cancels midway? \u2014 these “things go wrong” branches were almost entirely absent.<\/p>\n\n\n\n

Once Rev.0 was more or less written, the worry “is this actually any good?” welled up. I have no experience to judge quality myself, so my only option was to have someone review it. So, even though it was technically a separate project, I decided to ask Claude to review it too.<\/p>\n\n\n\n

“High Resolution on the Problem, but a Rough Solution”<\/h2>\n\n\n\n

When I pasted in Rev.0 and asked for a review, the overall verdict that came back was exactly that: “The resolution on the problem is very high, but the resolution on the solution is still rough.” The wording was gentle, but in essence it meant “you can see the problem clearly, but the part about how to solve it is hazy.”<\/p>\n\n\n\n

The specific points Claude raised were, roughly, as follows.<\/p>\n\n\n\n

First, there was no definition of the target user. Whether the user is an engineer or a general user completely changes the UI you should build and the granularity of error handling \u2014 that was the point. My own attitude had been more like “as long as I can use it, that’s fine,” but I was told that if I had any intention of selling it, who uses it is the single most important thing. Fair enough.<\/p>\n\n\n\n

Next, the reliance on rsync was too heavy. The rsync bundled with macOS is an old version with idiosyncratic log output, and it behaves differently from the newer rsync you install via Homebrew. The developer can’t control which rsync version is in the user’s environment. And if you’re going to distribute it as a commercial tool, making users install rsync separately isn’t realistic. \u2014 These were all things I only noticed once they were pointed out. It was simply that I happened to be using rsync on my own machine, so I’d written everything around rsync without really thinking about it.<\/p>\n\n\n\n

There was also the point that priorities and the scope of an MVP (minimum viable product) weren’t defined. Rev.0 had a lot of features lined up, but “which to build first and which to put off” hadn’t been decided. For someone with zero programming experience like me, trying to build every feature all at once is an almost guaranteed path to collapse.<\/p>\n\n\n\n

Error handling, test strategy, the performance problem of hash comparison, how to handle iCloud placeholders \u2014 these “things you’ll struggle with once you start building” were almost entirely missing from Rev.0.<\/p>\n\n\n\n

Incidentally, my mood when I got this review is a little hard to put into words, but it was something like a messy blend of “yeah, I figured,” a slight deflation at “I never could have caught this myself,” and the relief of “but I’m glad it was pointed out.” I knew from books that there’s apparently a “review culture” in the programming world, but I think this was the first time I’d experienced firsthand an AI giving me a genuine, proper review.<\/p>\n\n\n\n

From Rev.1 to Rev.5 \u2014 What Changed Across Five Revisions<\/h2>\n\n\n\n

From here it became a back-and-forth of critiques and fixes. I’d reflect the feedback in Rev.1, ask for another review, and the next round of feedback would come out. Reflect that, and the next round would come out again. I repeated this up to Rev.5.<\/p>\n\n\n\n

As for the big changes: first, I broke free of the rsync dependency. In its place, I switched to an original comparison method that completes using only Python’s standard library. Concretely, it’s a three-stage approach: first narrow down candidates by file name and size, then quickly narrow further using a hash of just the first few kilobytes of a file (called a partial hash, apparently), and finally confirm with a full hash. With this method, even with 100,000 files, the number you actually take a full hash of works out to just a few hundred to a few thousand.<\/p>\n\n\n\n

Next, the structure of three modes solidified. The original Rev.0 was vaguely “a tool to compare and tidy up,” but over the course of the revisions it split into three: an Exploration mode, a Quick mode, and a Full-inspection mode. Exploration mode is for getting a bird’s-eye view of the whole disk to grasp “what is where”; Quick mode finds duplicate candidates fast; Full-inspection mode takes its time to judge with certainty. The idea is that users pick the mode according to their own situation.<\/p>\n\n\n\n

I also defined the user tiers in three levels: Tier A (general users who don’t know rsync), Tier B (intermediate, who understand concepts like hashing and diff comparison), and Tier C (advanced, who understand even file-system behavior). And I settled on the policy: “design the UI so that Tier A never gets lost, while giving the internal design robustness that can withstand even Tier C.”<\/p>\n\n\n\n

And \u2014 this is something I’d like to devote a whole article to later \u2014 the design philosophy of “never delete files” also solidified during these revisions. Even when it finds duplicate files, this tool never presses a “delete” button. Instead, it moves them to a quarantine folder called “removed.” If the user later thinks “actually, I want that back,” they can restore it. Guaranteeing this “reversibility” was my top priority, because I myself feared accidental deletion more than anything.<\/p>\n\n\n\n

Having the AI Critique Me Was the Requirements Definition<\/h2>\n\n\n\n

Looking back after five revisions, the work I was doing felt less like “writing a requirements document” and more like “having the AI critique me, and answering those critiques.”<\/p>\n\n\n\n

I’d have Claude read the rough draft I, the human, had written, have it point out the problems, give my own answers to those points, and reflect them in the document \u2014 that was the cycle I kept turning. The AI didn’t write the requirements document all by itself. The closest description is that the AI functioned as an excellent critic.<\/p>\n\n\n\n

When you have AI write something, it tends to become “an agreeable partner who goes along with anything.” But for “finding the holes” work like a requirements definition, a partner who tells you the hard-to-hear things is actually more valuable. If you explicitly ask “please review this strictly,” the AI duly switches into a sharp-tongued mode. Not letting it flatter you may be one of the knacks for using it well.<\/p>\n\n\n\n

Also \u2014 this is something I noticed only after writing all the way to Rev.5 \u2014 once the document’s volume passed a certain point, the other AI I’d been using started handling it unreliably. Whether it was that it couldn’t read the whole document, it would forget things it had supposedly decided in the first half, or it would dredge up issues that had already been resolved, with increasing frequency. This is a matter of a technical constraint called the “AI’s context window,” which I’ll write about in a bit more detail next time.<\/p>\n\n\n\n

Around this time, I began to think seriously about switching over to Claude in earnest. There are several reasons, but it would get long, so I’ll save it for next time.<\/p>\n\n\n\n

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

Next time, I’ll talk about the second half of the requirements work \u2014 the road from Rev.6 to Rev.7. How I decided to “switch” from the other AI to Claude, how Claude’s “Project Knowledge” feature helped, and the story of “clean deferral” \u2014 handing off issues that couldn’t be settled during requirements to the next phase as “Appendix C.” In the end, the requirements document became a document of over thirty chapters. When I started writing Rev.0, I never imagined someone with zero programming experience would end up compiling such a document together with AI.<\/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\n\n\n

<\/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 2) Last time, I wrote about how, in order to escape data-migration hell, I decided to build a tool […]<\/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-46","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\/46","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=46"}],"version-history":[{"count":2,"href":"https:\/\/sr-works.net\/blog-en\/wp-json\/wp\/v2\/posts\/46\/revisions"}],"predecessor-version":[{"id":48,"href":"https:\/\/sr-works.net\/blog-en\/wp-json\/wp\/v2\/posts\/46\/revisions\/48"}],"wp:attachment":[{"href":"https:\/\/sr-works.net\/blog-en\/wp-json\/wp\/v2\/media?parent=46"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/sr-works.net\/blog-en\/wp-json\/wp\/v2\/categories?post=46"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/sr-works.net\/blog-en\/wp-json\/wp\/v2\/tags?post=46"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}