The old code is the spec
Tuesday, September 29, 2026
When agents migrate code, don't write a spec. The old system already is one. Port a piece, run old and new on the same real inputs, and ship only what matches. Then you review the check, not the diff.
Every migration I did by hand started the same way. Write down what the old code does. Then make the new code do that.
The writing-down part took longest. And it was always incomplete.
The spec already exists
The old code runs. It handles every case it has ever met, including the ones nobody remembers.
So it is the spec. The most complete one you will ever have.
An agent ports one piece. Then the old piece and the new piece get the same real inputs, anonymized. If the outputs match, the port is right. If they don't, the difference is the bug.
Review the check, not the diff
A migration diff is too big to read. Nobody reads it. People skim it, and skimming is how the bug gets through.
A comparison is small. It says which cases ran and which matched. That is what a person reviews.
It has one trap. The harness fakes the services the code talks to, and a fake that accepts what the real service rejects will pass a port that fails on its first real call. So every fake has to reject what the real thing rejects.
And a case that never ran is not a pass. If a comparison skips cases, the piece isn't done.
Ship on evidence, not on time
A ported piece goes live behind a flag. The flag starts at a sliver of traffic and only rises after enough requests succeed. Not after a day. After evidence.
Most errors show up in that first sliver, where they are cheap.
Where the person goes
An agent can port, compare and propose. It doesn't merge, and it doesn't raise a flag on its own.
Those are the steps that can't be undone. They are the whole job left for a person.
If you have a migration you keep postponing, that is what a Fleet is for.