This site was mine alone for eight years. These days I'm not the only one who works on it, and the thing that changed most wasn't the code.
A while ago I started building here alongside an AI assistant. I expected it to make me faster. What I didn't expect was that it would force me to write down how I think, and that the writing would end up mattering more than any single afternoon of code.
You can actually see the moment it began. For years the changes to this site were named the way you name things when no one is watching: Save my work, add lang switcher, fix stuff. Then, almost overnight, every change started arriving in the same careful shape, each one a small labelled promise about exactly what it did and why.
That wasn't a new tool doing it for me. It was me starting to work in a way a collaborator could follow, because for the first time the collaborator wasn't only future me.
I had to write down how I think
Working with an assistant broke a habit I didn't know I had. For years the reasons things were built the way they were lived nowhere but my head. Why this pattern and not that one, which shortcuts were fine and which would come back to bite me, where the sharp edges were. None of it was written down, because I never needed to tell anyone. I just knew.
An assistant knows none of that. It reads the code, not the years of decisions behind it. So the only way to get help that fit the project instead of fighting it was to make the unwritten rules written. I started keeping a manual: not documentation for users, but an operating manual for whoever, or whatever, works on the site next.
It started as a single short page of ground rules. It did not stay that way.
The core page is now surrounded by a dozen companion files, one for each part of the site that got complicated enough to deserve its own chapter. Together they run well past five hundred lines, and every one of them is written for a reader who is precise, tireless, and completely without context unless I give it.
Here is the part I didn't see coming: writing all of that down made me a better engineer on this project, before the assistant read a word of it. You cannot write a clear rule for a decision you only half understand. Explaining myself to a machine kept forcing me to actually decide what I believed.
It grew with the work, not ahead of it
The manual didn't arrive fully formed. It grew the way scar tissue does, one lesson at a time. Every time I got something wrong, or the assistant confidently did the wrong thing because I'd never told it the right one, that became a new line in the manual. Traps I fell into once are now written down so neither of us falls into them again.
When a section got too heavy, I split it out into its own file, so the everyday rules stay short and the deep detail is one click away when it's actually needed. I gave myself one hard rule above all the others: if a change makes anything in the manual wrong, the manual gets fixed in the same breath as the code. Documentation that lies is worse than none, and the fastest way to get there is to let it drift.
That single rule is what turned the manual from a nice idea into something I can trust. It stays true because keeping it true is part of the work, not a chore saved for later that never comes.
Then the site started using AI too
For a long time AI was only in how I built the site. At some point it crossed over into what the site does. A couple of small features now lean on a language model themselves: one makes up a fresh little daily puzzle, another writes up the case for and against an idea as a research aid, each with a plain, boring fallback for when the clever part isn't available.
I even added a page that lets a machine read the site the way a person reads the front door, and a quiet meter that counts how much thinking the AI parts actually cost me. None of it is the point of the site. It's there because building it taught me how these things behave when they meet real users, real edge cases, and a real bill, which is exactly the kind of thing I no longer get to learn by accident in my day job.
The point
I thought bringing an AI into a personal project would be a story about speed. It turned out to be a story about clarity.
The assistant is useful, but it isn't the thing I'll keep. The thing I'll keep is the manual: the written-down version of how I think about this codebase, dragged out of my head by the simple need to explain myself to something that couldn't guess. It outlives every session, every tool, and every version of the assistant.
That's the part worth passing on. The real work of building with AI wasn't learning to prompt it. It was learning to say plainly what I'd always just known.
Top comments (0)