PullMD Part 2: From Spec to Running Container – Simply Explained
By mid-morning of March 2, I had a clear plan written down for the little tool I wanted to build. Architecture, the way it should talk to the world, the shape of the output — all decided.
That same evening I asked Claude Code (the assistant that writes code for me) to go ahead and build it. I expected the first thing it would do was set up a basic web server. What actually happened was different — and that difference is what this whole piece is about.
Tests first — that evening of March 2
A spec, for context, is a blueprint. It says what the tool should do, not how. I gave Claude Code the blueprint and stepped back.
Within half an hour, four test files existed on my computer. No actual program code yet — just four little files whose job is to check whether the program works correctly once it exists.
That order surprised me. Most of the time you write the thing first and the tests later, if at all.
The first file checked something most people would consider boring: how the tool handles the addresses you give it. Strip away the tracking junk that gets attached to links. Send anyone who arrives at the old version of the site to the current one. Make sure a slash at the end of the address is always there. Seven small checks like that.
The second file made sure the part that actually fetches content was tested without ever going out to the real internet — it used a pretend response instead. The third file tested a backup plan, in case the normal way of fetching ever stopped working. And the fourth one did make real calls out to the internet, but only when I explicitly switched that mode on — so my everyday test runs stayed fast.
Read together, those four files describe more than a tool. They describe an architecture: three levels of fallback if something goes wrong, careful address handling before anything starts, a clear split between fast checks and slow ones.
The tests were the architecture. The actual program code came afterwards, fitting into the shape the tests had already carved out.
Putting it in a sealed box (March 4)
Two days later, the tool moved into what is called a container. Think of it as a sealed shipping box that contains the program plus everything it needs to run — no surprises about which version of which library is installed where. You hand the box to any computer, the computer opens it, the program inside just works.
The setup itself is unremarkable. A standard recipe for the kind of program I was writing. Nothing fancy — no hidden helper, no second moving part. One small, lean box.
The box also got a few labels. Those labels tell my home server which web address to put the tool behind, and ask it to take care of the security certificate automatically. That part of my setup is the same for everything I run at home — a small piece of plumbing that handles all the boring bits so I don’t have to think about them.
The phone trick (March 8)
Six days after the box was running, the part I had actually built the whole thing for arrived.
On the morning of March 8, two icons in the right size for phones appeared on the server. They were Reddit-orange — a quiet little detail that, looking back, told the whole truth about what the tool was at that moment: a Reddit tool, full stop. A few hours later, the favicon (that tiny picture you see in browser tabs) was added.
Then came the trick that made the whole thing feel like magic.
A PWA, short for Progressive Web App, is a website that behaves like a real app on the phone. You can install it. It sits on your home screen with an icon. And — this is the important part — it can register itself as a place to receive things from other apps.
In plain words: open any app on the phone, find an interesting post, tap “Share.” A long list of apps shows up — messengers, mail, the usual. My little tool appears in that list too. Tap it, and a moment later you have the post’s text on screen as plain Markdown, which is just very simple formatted text that I can paste into a chat or note.
The first time it actually worked on my phone
I remember the exact moment. I was reading a long thread about a problem I was trying to solve. Tapped “Share.” Chose my own tool from the list. A short pause — and there it was. Clean text on the screen. No menus, no popups asking about cookies, no sidebar of unrelated stuff. Just the post and the replies, neatly indented to show who answered whom.
What surprised me wasn’t that it worked. It was how much faster it was than I had imagined. The old way took several taps and switches between apps. The new way was one tap and the text was just there.
That kind of difference sounds tiny on paper. In daily life it’s the difference between a tool you actually use and one you keep forgetting exists.
Why this worked at all
The blueprint was clear enough that Claude Code could turn it into tests on its own. It wasn’t guessing. It had real decisions to anchor onto.
And those tests earned their keep over the weeks that followed. Every time I changed something — the way addresses were handled, the layout of the output, the backup logic — one of the tests would fail first. That told me what would have quietly broken, before it ever reached the real world.
If you ever try this approach yourself: bring a clear blueprint, ask for tests first, and the result is much better than you would expect.
What happened next
For three weeks, the tool ran quietly. It was mine alone. It only handled one kind of website. It only worked on my phone. Then, one morning in mid-March, I wrote a single sentence into a Claude Code session — and that sentence changed the project completely. The next piece picks up from there. → Part 3: Beyond Reddit, Beyond Readability
Part 2 of 9 in the PullMD series.
← PullMD Part 1: Ctrl+A and the Junk Context | PullMD Part 3: Beyond Reddit, Beyond Readability →