What this is
I build with an AI assistant daily. The interesting part isn’t that it writes code — it’s what had to be built around it before that was safe.
An index, not a memory
Every project and every machine is described in a separate repo that gets read at the start of each session: what exists, where it runs, which ports are taken, what’s already reusable. Not for me — for the assistant. Without it, a fresh session has no idea the thing it’s about to build already exists on another machine, or that the port it picked is in use. It’s the single most valuable thing I maintain.
Instruction files with one job each
Each project has a file addressed to the assistant rather than to a reader, and its rule is that it contains no facts about the system — only orientation and working rules. Facts live in documents that own them. That separation exists because the alternative was tested and failed.
The rules came from an audit, not from theory
I had the assistant audit its own documentation. It found the same fact stated in three places and a README describing the project as it had been several features earlier. Three rules came out of it:
- Update every document a change touches, in the same commit. The one most often skipped.
- Correct a false sentence; never add a truer one beside it. A reader can’t tell which of two contradicting statements is current.
- Record what was measured, not what was intended. If it wasn’t tested, say so plainly.
Nothing is committed without me looking at it
The assistant prepares the commit, shows the diff, and waits. Secrets get scanned by reading the real values and searching for them — not by eyeballing the diff — with a leak-detection hook as a second check, never a replacement.
Destructive things get a dry run first
The message cleaner shipped defaulting to dry-run with deletion disabled, so neither a missing config nor a typo could arm it. Anything that deletes files prints what it would delete and waits.
What I learned
The copy gets fact-checked. The project list on this site was AI-drafted and needed correcting — several entries had been extrapolated from a one-line description rather than real notes, and those never made it onto the site. That’s the honest shape of this: it drafts fast and confidently, including when it’s wrong.
The real failure mode is never bad code, which you notice immediately. It’s confident documentation quietly drifting out of sync with the code, which you don’t.