Teach one repo, move a fleet
Teach the AI one repo's migration, validate the lesson, run it across the fleet. What it costs, what it returns, where it goes wrong.
We all know the Principal/Staff/Distinguished Engineer that has 10+ years of experience in their company (with a 20+ years experience working in tech). Whichever team they go through, it skyrockets and a lot of problems get solved...
But they are only one, and you have hundreds of repositories with dozens of teams and everyone wants to revamp/modernize their tech stack... all at the same time that someone is planning a “tech reorg” paying millions to McKinsey.
I was working with that Principal Engineer / Lead Architect in a major European airline while they were working in one problem: dozens of old Java apps that acted as a distributed monolith that they wanted to move to Java 21.
After months of struggle with the (false) promise that you feed your repositories to Claude Code and it magically vomits high-performing new code, we started to talk.
So they were struggling and arguing that fancy new AI models are not good in writing code, and that annoyed me. Because the question should be a different one: can your organization teach the AI something once and reuse that lesson? And of course, the best person to teach it is a team led by the Principal/Staff we’ve been talking about.
That lesson is the unit of scale... not the license, not the prompt. The encoded and validated lesson, the fricking pattern!!
In last week’s edition we promised to talk about architecture and “the pattern, not a pitch”. Here we are!
Issue 1 named the trap: sequencing.
Issue 2 named the destination: AI-native, not AI-ready.
Issue 3 put three bodies on the table that have to move together.
Issue 5 found Herbie: your bottleneck doesn’t burn tokens.
Issue 6 brought the peer-reviewed witness: more shipped, same typing.
The trap: changing the pattern and the version in one jump
Modernizing your architecture is a hard thing, and we don’t even need to go to Conway’s Law here. Just ask someone what they mean by modernizing an application. Is it the language change? A major version upgrade? A “more modern” pattern and saying that Saga patterns are the way forward?
For a lot of my customers they start yapping (sorry about the word) about “breaking down our monolith”. And when I ask what is bad about their monolith they start going on about deployment challenges, about the one time they had to wait 4 sprints to add a new field to the website UI or how every developer takes months to onboard to their codebase.
Peeling that onion I usually can find the core, and it’s a combination of one or more of these (coming from CTO all the way to the support team):
All changes take too long, even small/dumb ones.
Developers are afraid to touch this repo because of unforeseen changes.
No one from the tech team can estimate how long it is going to take to finish this feature, then we cannot plan it financially.
My dev team is sick and tired of maintaining this... they just want to build an “insert cool new shiny object here” and this keeps holding them back.
... anything else you can imagine that encapsulates frustration and rage and disappointment and denial and more...
Teach one, prove three, run the fleet
And I tell them the same. Funnel it out! But knowing where to start is really tricky, so what do I do: Event Storming session! Yes, this will require a newsletter on its own, but I do an event storming session (1 to 3 depending on size and problem)... that is followed by a definition with the customer on what pattern we are tackling and in which business domain.
With that in mind, we have a pattern we want to tackle. And no, you cannot just say you want to “apply strangler-fig“ to your monolith! I’m talking about something way more tangible. For this specific airline, we were talking about JRE 5 and JRE 6 upgrades to Java 21.
That is followed by a sprint. And if you are into Team Topologies I can just say this is me and the Staff/Principal Architect/Engineer (let’s call them Athena from now on!) playing the role of an Enablement Team to a 2-3 members of a Stream-Aligned team. And there I was with Athena talking to a specific team that was doing the GDS integration for airplane ticket selling.
And what do we do? Hands-on coding in pair-programming sessions with Gen-AI assisted tools - Codex, Claude Code, Kiro, GitHub Copilot or whatever rocks your boat as your coding harness. The important part here is that working in pairs (plus the AI) forces you to say your assumptions out loud, where another human can counter them... it takes time but it’s a fantastic result. For all the DDD and XP programming fans here, this is nothing new :-]
Week 1: We spent it writing and questioning the context we would feed the tool. Which code is where? What calls this? What is the latency on this? We went from our laptops individually to screen-sharing sessions on Zoom answering doubt after doubt... the 5 of us (me, Athena and the 3 developers on the GDS integration) spent one entire week having 90’ alone sessions followed by 30’-60’ calls asking each other questions, realizing assumptions were wrong, going from weird business rules into why the code is doing XYZ and banging our heads until someone would say: “Huh... I think we need to ask this to the Operations Director?” and that would park a point.
But Thiago, what is the AI usage here? Well, we rarely started from an empty canvas. Using Claude Code you can quickstart your documentation and start asking questions. Then you validate what you know. When you go into the function level that calls an endpoint to another repository, you don’t need to understand that other codebase that heavily, you can just ask about the contract and the API swagger to understand where things are going.
However, this doesn’t replace my 20+ years of experience building, debugging and operating distributed systems... on the contrary, it sped me up!
During this 1w going through this cycle we iterated several times in a tool. We would give a full agentic task to our GenAI harness with our context doc (we called it the Research Plan) and we know what we wanted to achieve: an Implementation Plan for the Java migration!
We’d review it together, find that something was missing, there were too many moving parts or a lot of handwaving... well, that meant we could improve the Implementation Plan ourselves and/or iterate again on the Research Plan.
Timebound it to 1w and voilà... we have an Implementation Plan. This plan must consist of a reduced version of the context (hello Context Engineering) and validation tasks!
Week 2: We leave it to run and push until at least 80% of it is actually solved. We end up happy with the plan and we actually manage to migrate one repo fully. Was it fully automatically? Of course not! We spent blood, sweat, tears and time making this together.
Week 3: But now we have a formula to gather context. How we build the Research Plan in the Phase 1 is streamlined into skills, prompts, scripts and more. We can apply that to another 3 repositories and by the end of the week we had clear micro-patterns and rules that were important from Java 5 to Java 21. What to do first, what to look out for and more.
So by the end of week 3 we already migrated one repo and we have the implementation plan of other 3 repositories! :-D
Weeks 4 and 5: ensuring those 3 repositories are migrated and ready to show-off.
Week 6: the “fleet management problem”... you trust the lesson is now so good that a fully-streamlined run might get to that 60-80% good enough!
Why not aim for 100%? Because raw model translation is still not something you trust unattended: Rangeet Pan, Ali Reza Ibrahimzada and colleagues at IBM Research and the University of Illinois tested LLMs translating 1,700 code samples (ICSE 2024) and got correct translations between 2.1% and 47.3%, cataloguing 15 kinds of translation bugs along the way. That is why the validation tasks travel inside the plan. They are not paranoia, they are the pattern.
So what you do? You dispatch several runs against all repos that will go through it all: gather the Research Plan, write the Implementation Plan, build the final migration run with its report and validation status. Then open the MR and say what was done...
Every team maintaining those repos will get pinged with “WTF! There is a new MR to upgrade our Java 5 to Java 21?? ofc it didn’t work fully!” and that is the goal!
Now we are underway and what seemed impossible is now several kilometers close by. The magic happens... some teams reach out and say they will start working on it, while others don’t even bother. But lots were quite receptive to an hour of us sitting with them, walking the process, and leaving them to finish what was missing.
So what, Thiago? You are telling me that after 6 weeks you were able to open a MR to all Java codebases and solve everyone’s problem???
Not at all! We were able in 6 weeks to have 3 fully migrated repositories to Java 21 and give them something that was ~70% underway. It’s a glimpse of hope!
Our team of 5 got approval from the Tech Board to fluctuate around the company and enable these other teams... at this stage I was not needed 40h/w and I was mainly coaching Athena and the other 3, plus getting engaged as a soundboard for some hairy problems.
A few weeks into that phase, we noticed that repos the teams had sized in weeks were landing in roughly half the time of their original estimates... I don’t take that number too seriously, because initial estimates in large companies are always overestimated until they receive budget, but even discounting the sandbagging it was a lot faster than if they did it without this “method”. And this is without counting the freezing time that large companies have, on planning and waiting on the decision to start (what I call the “kick-off of the kick-offs”).
Now count what this actually cost: five people, six weeks, licenses most companies already pay for, and the owning teams’ review time. No army, no SI landing party, no multi-year program slide. The expensive part was never the tooling... which brings us to where this pattern actually dies.
Where it goes wrong: nobody touches my codebase
So why doesn’t everyone do this? Because none of the fights that matter are technical.
The first fight is the fiefdom. When someone says “I don’t want others touching our codebase”, it is rarely about the code. It is about budget, headcount and team allocation, and a central team’s MR reads as a threat to all three. This is why the pattern needs sponsorship and transparency that go beyond the business unit you are working in: someone above the fiefdoms has to want the fleet moved more than any single castle wants its moat.
The second fight is the career program. Big architectural changes are career-defining projects... a new CTO arrives attached to a multi-year budget announcement, and a research-test-implement-iterate cycle kills the announcement. Some people grieve the announcement more than they want the outcome.
The third fight is with Finance, and it is the fairest of the three. The CFO needs horizons and control, and an iterative rebuild cannot promise a three-year gantt in good conscience. You still need the gantt (I’m not that naive), but it changes species: it becomes a forecast you manage through mid milestones, not a contract you defend in steering committees. More agile means more unknowns, and someone has to look Finance in the eye and say so.
None of these people are villains, by the way. The incentive system pays for programs, not for lessons.
The three-body reading
And what some teams were doing links to our 3-body problem... this airline was trying to move the architecture by forcing people to use their AI coding assistants. When usage didn’t climb, leadership came back with “we hear from everyone in the industry that code generation is so easy and cheap now... why can’t you just modernize everything?”. Then managers were asked to review token-usage per person in their 1:1 meetings. Insanity, I know.
When I left, there was another trend: Finance started pushing the opposite way, manager approval required before touching the AI harness, to staunch token usage.
What made this initiative a success was the fact that we kept the learning curve in a team. In that team we tackled the architecture problem by gathering people/political context with the Event Storming and all its pair-programming sessions. And we used AI steadily and in pairs, ensuring that no-one goes into a rabbit hole of handwaving or trying to bolt on yet another tool or trying to automate everything.
To move the architecture body we had to ensure the other two bodies (People and GenAI) were not converging to a cataclysm.
Run it on yourself
Before you buy anything or announce anything, three questions:
Can you name (at least) 10-15 libraries, repos, modules or apps that share one shape (same framework, same pattern, same pain)? If you cannot, your first problem is inventory, not AI.
Which repo is your teaching repo, and who is your Athena (the know-it all Staff/Distinguished/Principal Engineer/Architect that knows the ins-and-outs of your most feared application)? One hand-made, human-validated migration is the baseline that earns the machine its trust. If nobody in the room can produce that baseline, the model will happily invent one for you.
Can a central team open MRs on other teams’ repos... and who sponsors that conversation when a business unit says no? If either question makes the room go quiet, congratulations: you have found your real constraint, and it does not burn tokens.
The whole thing, in one line
The unit of modernization is not the program, the license or the prompt. It is a validated lesson... and lessons, unlike programs, compound.
Coming up
Next week I climb back out of the engine room. More soon. :-]
Sources
Rangeet Pan, Ali Reza Ibrahimzada, Rahul Krishna, Divya Sankar, Lambert Pougeum Wassi, Michele Merler, Boris Sobolev, Raju Pavuluri, Saurabh Sinha and Reyhaneh Jabbarvand, “Lost in Translation: A Study of Bugs Introduced by Large Language Models while Translating Code”, ICSE 2024 (peer-reviewed). https://doi.org/10.1145/3597503.3639226
Rafael Tomaz, Paloma Guenes, Allysson Allex Araújo, Maria Teresa Baldassarre and Marcos Kalinowski, FORGE 2026 (peer-reviewed; last week's spine). https://doi.org/10.1145/3793655.3793728
Martin Fowler, “Strangler Fig”, martinfowler.com, 2024 revision (practitioner essay, not peer-reviewed). https://martinfowler.com/bliki/StranglerFigApplication.html
Field numbers are from my own engagement notebook, anonymized and hedged; treat them accordingly.