I Inherited the Company's Most Complex System, and I Didn't Know the Domain

Two years and three months in, past the new-hire stage and settled enough to think I'd settled in, I watched the migration lead leave the company. The most complex system he'd been holding passed straight to me. There was a handover document, but it sketched only the broad shape and none of the detail, and even that broad shape wasn't something you could pick up coming to the domain cold. The real trouble was that I had never once worked in that domain. Two years on the job, and faced with this system I was a beginner.

The legacy alone was no small thing. It had been piling up for more than three years, touched by so many hands, and it carried plenty of backstory. The part that threw me most: a BFF whose only job was to hand values down to the screen was doing money calculations inside itself, the kind the backend should have owned. Sales commission applied, settlement amounts computed, the kind of calculation where a single won out of place is unacceptable, sitting in the layer that draws the screen. Someone with no room to touch the backend must have bolted it onto the BFF to get through the day, and it was never removed; it passed to the next person, and the one after that, until where the logic belonged and where it actually ran had come apart. So just working out what ran, where, and how was itself the job.

On top of that, the new project I was picking up was already nearly 60% built, and none of it by my hand. The job itself went past moving data into a new container: the DB schema had to be torn out and rebuilt from the ground up. After a few days reading code, I summed the situation up like this:

I didn't know the legacy, I didn't know the new project I was inheriting, the schema was changing at its root, and I was no expert in this domain.

Two of us on it, counting me, and a target of three or four months. After a few days wrestling with it I reached one conclusion: human hands alone couldn't finish it in time, and without putting AI on it properly it wasn't possible at all. Leaning hard on AI was entirely my own call. No policy had come down from above.

The four weeks I handed off#

The trouble was that setting the direction also fell to me. Not knowing the domain, I didn't know what to ask the AI for, so for days on end my instructions came down to little more than 'just try something.' When the one giving the orders doesn't know the destination, no real direction can come of it.

The result was what you'd expect. The AI invented field names that didn't exist with full confidence, attached state values that were nowhere in the system without blinking, and I'd burn a whole day digging through code to check whether any of it was real. It produced things without pause, and almost none of it was usable. Four weeks went by that way, and all I had burned was tokens.

Looking back, the cause was plain. When someone who doesn't know the domain also hands the AI the direction, the two of them spin in place side by side. That only sank in after I'd burned the whole four weeks. With no one holding the big picture, the AI fills the empty seat with things that were never true, and filtering out the falsehoods it makes lands right back on me.

The map first#

So I turned the whole way I used the AI on its head. Instead of having it build something, I first had it explain this domain to me. There was nothing you could call documentation, so only one path was left: feed it the legacy source in full and have it write back what the code actually did as a human-readable spec. The AI worked backward from the code, pulling out the conditions under which a product's state moved and where it moved to, and drew them as a state-transition diagram. Traps you'd never meet without opening the code yourself (a field written as CSV on save but read as JSON on lookup) surfaced one by one along the way. As hundreds of source files were distilled into a dozen-odd domain documents, the one actually learning the domain wasn't the AI. It was me.

Drawing the map, I finally saw why this domain was so hard. When a product changed its nature in the legacy — when an item held on consignment moved to purchase, the company buying it in — the legacy minted a whole new product under a fresh code and left the old one sitting where it was. The new system, by contrast, kept the same product and changed only the state inside it. One and the same event, handled by two worldviews in exactly opposite ways.

So this migration was less about moving data from one container to another than about translating the sentences of one worldview into the sentences of another. The whole resale domain (authentication, product, shipping, settlement, returns) was tangled together this way, a complexity that would take anyone walking in cold a long while just to understand. Letting the AI reverse-engineer that complexity out of the code, I got up to speed on it far faster than I would have alone. Around this time the AI worked as an onboarding tool, easing me in.

Fast, and wrong#

Resetting the direction didn't make things smooth right away. One evening I handed the AI the wrong scope, set a job running, and went home; the next morning I opened it to find a thousand-plus lines of new code stacked up. At a glance it looked plausible enough, but the direction itself was off, and after a few hours studying it I threw the whole thing out and started over. The AI is fast in the right direction, and exactly as fast in the wrong one. Wrong direction just means it has gone that much farther out. Throwing away a night's labor in the morning was the price of having let go of the wheel.

After burning four weeks#

What those four weeks left me was one thing: the recognition that the person who should have held the direction was me from the start, and I had pushed even that onto the AI. But I couldn't very well donate four weeks like this to every project, so I began building, with my own hands, something that would keep the AI from tripping over the same spot again and again. What that something caught, I wrote up in Part 2.