The client had Python scripts. They did real work, which was never in question, and that work was to continue. The job was to turn them into an application, a processing service with a proper structure and an API at the front. My job was to lead that conversion.
At Subvisual, we adopted AI quite early, we are about as close to AI-native as any studio can rightfully claim to be. I did most of this work in an AI tool, with a model that is a couple of generations old by now. It was impressive by the standards of the time, and I was using it extensively. The scripts became an object hierarchy inside a FastAPI service, and the service ran. The work that was being done continued being done and what was required of me was completed successfully. It was done fast, it met all requirements, it tested well, and I shipped it feeling fine.
01 · Onboarding
Then came the onboarding
The client's team was taking over parts of the codebase, and I was the one explaining it. Somewhere in that session I realised I couldn't. Not completely. I was fuzzy on parts of the request lifecycle. I couldn't defend some of the choices in the hierarchy, the exact shape their scripts had become, because I hadn't made those choices. I had approved them, I was aware of them, but I didn't make them and had no real rationale as to the why of things.
To add insult to injury, the question that really caught me sideways was an exceedingly easy one: how do I add a new recorder? A recorder is one of the device types the service ingests data from; supporting a new one is routine work. The answer was somewhere in code I had reviewed and merged myself. I just couldn't walk them through it.
I stopped the session and told them how it had been built: an AI did the typing, I directed it. The client, thankfully, was already quite familiar with AI-assisted coding, and the trust was there, so they pivoted right alongside me to turn the rest of the onboarding into a joint exploration, reading the codebase together. I could explain the inheritance, the flow, the pieces where I had given the orders. The gaps were quite predictable. They were exactly the decisions I had only approved.
02 · Judgment
We have been warned
It's an old programming industry adage: your technical judgment decays when you stop touching the code. This was usually applied to more senior devs that moved to managerial positions. I ran straight into the updated version for the AI age. I never stopped touching the code. I touched it more than ever, at a speed I had never worked at before, and my judgment decayed anyway. The understanding never came from the typing, so watching something else type wasn't going to produce it.
What changed in between wasn't a single thing. Coding agents matured, and with them came a way of working that treats the agent as something you onboard rather than something you prompt: an AGENTS.md with the project's conventions, skills and commands for the repeatable work, context written down where the agent can find it on its own. Setting that up for my projects forced me to organise the work itself. Then I started preparing a talk about exactly this, and having to explain the method to a room full of people helped me sharpen some of my intuitions about how to adapt to a new way of working without throwing the baby out with the bathwater.
03 · Rework
So now we must fix it
Six months after the refactor I went back. I needed the second pass to look nothing like the first. Fool me once, etc. Right?
So, before touching any code, I wrote down what I knew and read until I knew what I didn't know. I only stopped when I could write down everything: the architecture, the conventions, the one test file that hangs if you run it directly. Then I audited the codebase and filed what I found instead of fixing it on sight; eight issues went into the tracker in one sitting. I fixed them the week after.
The first pass had produced documentation too. Thirty markdown files of it, with quick starts and dependency diagrams and an archive folder. Amusingly enough, none of it could answer the recorder question. The second pass cut all that material down to eight files that are actually useful. Documentation for the next developers and for the next AI agents, which need the same thing people do: a codebase that explains itself.
Both rounds used the same kind of tooling, what changed was me, and the requirements I decided on. The quality of what an agent gives you has more to do with the state of the project than with the wording of the request.
Writing this article now made me realise how much my role changed these past couple of years.
04 · Rules
The speed is real, our job is to not crash
The speed is real, and it is easy to be dazzled by it. My rule now is the one I broke: I will no longer put my name on anything I can't explain. Documentation stopped being an afterthought. I now write it with intent and purpose for the people and for the agents that now work alongside them. Documentation and knowledge are the rails all this speed runs on.
I can walk someone through adding a recorder now. It takes a couple of minutes.