Interactive client documentation: a proof of concept I ended.
A system meant to answer clients’ questions about their own stores from three sources at once: our handover documents, the platform’s help articles, and the code of their store. Agents built it; I specified it, verified it, and ended it when it became more machinery than the problem deserved.
What needed
solving.
Clients act as content admins on the Shopify stores we build, but they can’t always tell how a feature was put together, and the documents handed over at launch start going stale the week after. One client was working from a Word “admin guide” that frustrated everyone, and there was no budget for another software subscription. The goal was a way for a client to say what they wanted to do and get instructions for it, on demand, without slowing down the delivery team.
What I decided,
and why.
- 01
One application for every client, reading three sources: our handover documents, Shopify’s own help articles, and that client’s theme code. Without the code it could only describe generic Shopify.
- 02
Rent the database instead of fighting the existing server. The shared host ran a Postgres version too old for vector search and couldn’t be upgraded, so I compared four options and consolidated on one managed database: one datastore, one query language, no cross-store joins to keep consistent.
- 03
Agents build, I verify. I don’t write application code; I read it well enough to follow it and ask hard questions about it. Three AI agents, scoped by epic, did the building. Reading the whole system rather than one ticket at a time, I found a database rule that still pinned an embedding model we had already decided against. Nothing failed in testing; it would have rejected every record on the first real run.
What shipped,
and what isn’t proven.
The foundation phase closed and was verified: a managed database, the app running on its own address, a deploy loop proven by watching a push change the live app, and a five-page internal wiki. The product claim never was: answer quality, fewer client questions and time saved were never measured. I ended development because keeping the index current costs compute permanently, the app was growing into a product of its own, and the capability was commoditizing. The need is now met by static help pages with ordinary search, which AI writes and updates whenever a feature ships.
What I’d do
differently.
I optimized for the wrong cost. Saving a modest monthly fee cost a database evaluation, a design I threw away, and a connection failure; paying for a managed database from the start would have been cheaper on any honest accounting. I should also have tested the shape of the solution with a hand-built mock-up and no infrastructure at all, and written the decisions down before the agents started instead of discovering them afterward.