I have never written production software. I have, however, spent years telling other people what’s wrong with theirs. So naturally, I decided to build an app.
Here’s my resume for the job. I know enough about requirements, product design, instructional design, and the ways software projects quietly fall apart to be genuinely dangerous, and nowhere near enough to be useful at a keyboard. That gap is where it gets interesting. I can tell you what a product should do, where the plan is thin, and which cheerful assumption is going to bite someone in month three. I cannot, on my own, build the thing and prove it works. I know just enough to get into trouble.
So I went looking for some, with ChatGPT and Claude Code as accomplices.
I wanted a project I actually found interesting, and one with nothing riding on it: not a product, not anything tied to my day job. Something fun to get my hands dirty with, where nobody would care if it never made a dime.
What I landed on was a digital split-flap display, the kind of mechanical arrival board that used to clatter away in train stations and airports. I’ve always wanted one. The physical versions cost about as much as a used car, which is a lot to pay for the pleasure of watching letters flip. So, not wanting to spend a lot of money on a novelty device, I decided to fake it and emulate the look and the movement of a flip board on a monitor or TV. The application needs to display messages, animate individual character tiles, manage content, support external data sources, and eventually run on both Windows and Raspberry Pi.
The idea was easy to explain. Turning it into a package an AI coding system could actually implement was the hard part, and where being dangerous started to matter.
I didn’t start by asking for code
My first real decision was to use ChatGPT for product definition and documentation before letting Claude Code write anything.
It’s tempting to describe an application in a paragraph, hand it to a coding model, and see what comes back. That’s fine for a small demo. It’s not a great way to build a tool with multiple applications, persistent data, authentication, configuration, API integrations, animation rules and rendering, installation requirements, and a roadmap.
I talked the product through with ChatGPT across several conversations. We worked over the product vision, system architecture, functional requirements, user interface, data model, APIs, animation behavior, installation, nonfunctional requirements, and future capabilities.
Those conversations became a Software Requirements Specification. The SRS ran to about 40 pages and described two applications: a full-screen Display App, and a Control App for configuring and managing it. Later, with the milestone plan, schemas, and development rules stacked on top, the whole package came to around 60 pages.
The requirements got specific: a configurable tile grid, independent tile movement, randomized animation completion, optional mechanical sound, administrator login, content scheduling, fallback messages, diagnostics, and support for external information providers. It also had to stay local and offline-first while leaving room for a hosted, multitenant version down the road.
That specificity is the whole point. “Create a split-flap display” is an idea. “Each tile begins from its current character position, cycles independently, and completes within a randomized timing range” is something a developer can build and test.
ChatGPT was best as a structured review partner
One of the most useful things I did was ask ChatGPT to work from several professional perspectives at once.
I didn’t want a document that only thought about visible features. I wanted it reviewed from product, engineering, database, user experience, security, testing, and deployment angles. ChatGPT was good at surfacing requirements I hadn’t considered, especially when I named the perspective explicitly and asked it to explain why each missing item mattered.
I also had it stop and ask clarifying questions before drafting a major section, so its assumptions didn’t get buried inside polished prose.
A reusable version of one of those prompts:
Act as a senior product manager, software architect, database designer, UX designer, security analyst, and QA lead. Review the proposed application from each perspective. Identify missing requirements, contradictions, untestable statements, and assumptions. Recommend one preferred approach where the evidence supports it. Before drafting, ask only the clarifying questions required to proceed.
It worked because it set the roles, the review criteria, and the expected behavior before ChatGPT wrote a word.
Another prompt focused on requirements completeness:
Review the current SRS against everything discussed in this project. Identify any missing requirement, inconsistency, duplicate requirement, or term used in more than one way. For each finding, provide the exact proposed text, the section where it belongs, and the reason for the change. Do not expand the product scope.
That last sentence mattered. Without it, an AI system will treat every review as an invitation to redesign the product.
The SRS was only the start
A human-readable requirements document wasn’t enough on its own. Claude Code also needed smaller, implementation-focused files, placed where it could find and use them.
ChatGPT helped me create or define a supporting package: a milestone plan for sequencing, a SQLite schema and initial migration, JSON schemas for the playback manifest and display status, valid and invalid schema fixtures, animation defaults, content-provider decisions, an installer decision guide, a UI review checklist, and a development standards library. Most were Markdown, with SQL and JSON where it made sense.
The goal was to give Claude Code more than a broad specification. It needed explicit engineering rules, file locations, data contracts, test examples, and an implementation order.
A representative prompt:
Using the approved SRS as the authoritative source, create the supporting Markdown, SQL, and JSON documents required for Claude Code to implement the application. Do not add product requirements. Each document must state its purpose, inputs, outputs, dependencies, authoritative sources, completion criteria, and files it is allowed to affect. Use consistent terminology and identifiers across the entire package.
This was one of the strongest parts of the process. The SRS explained the product. The supporting files turned parts of it into artifacts closer to code. Here’s an overview of the project file-tree:
What went well
The process forced decisions I would otherwise have put off: whether the display dimensions were fixed or configurable, whether authentication was required in the first release, how realistic the animation should be, whether content providers were built in or treated as plugins, and whether a future hosted version should shape the initial data model.
ChatGPT was also good at turning conversational decisions into structured requirements. I could describe the behavior I wanted in plain language, then ask for precise, testable wording:
Convert the following product behavior into mandatory engineering requirements. Use clear “shall” statements, define defaults separately from configurable values, identify edge cases, and include acceptance criteria. Preserve my intent. Do not introduce unrelated capabilities.
Another habit that helped was asking for surgical edits instead of broad rewrites:
Make only the changes listed below. Do not revise, reorganize, shorten, expand, or reformat any other content. Preserve all existing requirement identifiers and section numbering. After the update, compare the revised document with the prior version and report every changed location.
That cut down the unwanted rewriting. It didn’t eliminate it.
The last practice worth mentioning was asking ChatGPT to review the package as a system, not a pile of separate documents:
Prompt: Regenerate and normalize the package. Compare every file with the approved SRS and with every document it depends on. Check terminology, identifiers, paths, defaults, data structures, requirements, milestones, and technology decisions. Correct contradictions without adding new scope. Perform separate structural, cross-document consistency, and usability reviews before presenting the final package.
Far more useful than “Does this look good?”
What needed improvement
Any single answer was usually fine. The hard part was holding consistency across a long project spread over many conversations and document versions.
Requirements piled up gradually. Some were discussed in one thread, revised in another, and folded into a Word document in a third. I’d sometimes ask ChatGPT to look across the project and confirm every discussed document was present. It could give a useful answer, but I learned not to treat conversational memory as a configuration-management system.
Version control was a problem too. File names like “Revised,” “Updated,” and “Updated_Final” made sense when I created them and told me nothing later about which version was authoritative. Anyone who has ever saved a file called “Final_v3_actual” knows exactly where this goes. More than once I had to tell ChatGPT which document was current and instruct it to leave everything else alone.
There were flat-out output errors. At one point I questioned whether a revised Word document had actually gotten longer after a new roadmap section went in. The download still ended on page 40, the same length as before, and ChatGPT’s first answer about the page count was wrong, delivered with the same confidence it uses for the correct ones. Elsewhere in the documentation work, some generated Word files came out truncated.
Those were useful reminders. A confident statement from an AI system isn’t verification. I still had to open the files, check the last page, compare sections, and confirm the promised content was actually there.
Repeated review instructions created their own false comfort. “Perform three reviews” beats asking for none, but the count isn’t the point. A review needs explicit criteria, authoritative sources, and evidence of what was checked. Three vague reviews can miss the same thing three times.
The work only got more controlled once I added real project-governance instructions: one master plan, an authority hierarchy for documents, a decision log, a glossary, a content inventory, a traceability matrix, a risk register, and a deferred-topics register. I should have put those in place before the SRS grew large. Filing this one under “things being dangerous teaches you.”
What I’d do differently
This part is the recommendation, not a reconstruction of how tidily the project actually went.
I’d begin with a project charter and a document map before drafting the SRS, and assign one authoritative document to each major subject, deciding up front which files may repeat information and which should reference it instead.
I’d create stable identifiers early for requirements, decisions, risks, interfaces, and milestones, and keep a simple manifest listing every package file with its purpose, owner, status, version, dependencies, and sources.
Most of all, I’d require traceable validation instead of general assurances. A better final-review prompt would be:
Validate the delivery package against the approved content inventory and traceability matrix. For every promised deliverable, confirm the file exists, opens correctly, contains all required sections, and aligns with its authoritative sources. List missing content, conflicting requirements, orphaned requirements, unreferenced decisions, invalid paths, and inconsistent identifiers. Do not report the package as complete unless every validation check passes.
And I’d bring in real source control much earlier. ChatGPT can draft and compare documents, but Git or something like it should be the thing that records what changed. File names shouldn’t carry that weight.
The larger lesson
By the end, the part worth keeping was smaller than a 40-page SRS and harder to put in a template: fluent output is not controlled engineering, and it is easy to spend weeks confusing the two.
ChatGPT earned its place because it helped me think across disciplines, translate ideas into requirements, catch omissions, build supporting artifacts, and assemble a package Claude Code could use. It gave a nondeveloper access to analysis and documentation that would normally take several specialists.
What it didn’t do was remove the need for product judgment, change control, version management, testing, or human review. If anything it raised the stakes on all of them, because AI can produce more content, faster, than a person can casually verify.
For nondevelopers, instructional designers, and product managers, that’s the real opening. You don’t have to become a senior software engineer before you can define a useful product or take a serious part in building it. You do have to bring the skills good project work already runs on: clear objectives, structured requirements, controlled scope, explicit decisions, testable outcomes, and careful review.
The sequence that actually worked went like this: I defined the product, ChatGPT helped me make the definition precise, the documentation package held the implementation in bounds, Claude Code built inside those bounds, and I stayed on the hook for deciding whether the result was correct. There was no magic in it, just ordinary project work run with much faster tools.
I’ve since loaded the package into Claude Code. I had Claude Code do a full architectural review of the package. It found some issues and inconsistencies. We fixed these, and only then did it start building. After a few days, there’s a functional application running, and I’m amazed at how it’s going. If watching someone who can spec software but not code it build a real app with AI sounds like a slow-motion car accident you’d enjoy, follow along. The next installment, when the code exists and promptly starts misbehaving, is right here.
Read more: Enough to Be Dangerous: Getting a Project Ready for Claude Code Before Writing Any Code