"Yeah, but this wouldn't work on my codebase."

The developer leans back and starts listing. It's a CodeIgniter and Symfony hybrid. The routing was rewritten in 2018 by someone who left. The auth layer is custom. There's a shared session mechanism nobody fully understands but everyone's afraid to touch.

They're not wrong. Legacy codebases are messy. No two are alike. But here's what that developer just did without realising it.

They gave an onboarding.

The new hire test

When a new developer joins the team, nobody hands them the code and says, "figure it out." Someone senior sits with them and transfers tribal knowledge. "Don't touch the payment module." "The tests in /legacy are flaky, run them twice." "The config is split across three files because of the 2019 migration."

That conversation is onboarding. The developer objecting that their codebase is too complex for AI is giving exactly the same onboarding they'd give a new hire. Same information, same "let me tell you about the weird stuff" energy. The only difference: a human remembers the conversation. An AI forgets it the moment the session ends.

So the onboarding has to be written down. A claude.md, a .cursorrules, whatever your tool reads automatically. An instruction file is an onboarding document for a team member that reads it every single time. Because it's starting fresh every morning.

Start with the complaints

Most teams don't have an onboarding doc. No problem. Start with one question: "What would you tell a new developer on their first day?"

Every answer is an instruction file entry. "The test suite takes 40 minutes, just run the unit tests." "We tried to migrate to Laravel in 2021, it's half done, don't ask." Complaints, warnings, war stories. The most valuable context you can give an AI, because it's the context that prevents expensive mistakes.

Everybody knows this stuff. Until somebody leaves. Or until you onboard an AI and realise nobody ever wrote any of it down.

After the onboarding

Once the context exists, the rest is a boring, disciplined sequence. Document the structure by letting AI explore the codebase. It maps framework boundaries, entry points, and configuration quirks without getting bored or skipping files. Test against existing behaviour, not how the code should work, but what it actually does. Refactor in small, tested, reversible steps. Split it into the smallest tasks possible. Not "upgrade the framework." Fifty well-defined steps.

Don't skip to refactor. You wouldn't let a new hire rewrite a critical module on their first day. Without context, the AI will normalise things that are intentional. Without tests, there's no safety net. The sequence exists because each step de-risks the next.

The real bottleneck

The developer who says "you haven't seen my codebase" is telling you three things. That the codebase is complex. That they understand the complexity. And that they haven't externalised that understanding.

That last one is the bottleneck. Not AI capability. Not codebase complexity. Tribal knowledge that lives in someone's head and nowhere else. It was a problem before AI showed up. AI just makes it visible, because AI is the new hire that asks for the onboarding doc and finds an empty page.

Write it down. Let the AI read what you just said out loud. That's step one. That was always step one.