before you hire coding agent
Bringing an AI agent to work on a mature project is, in essence, not so different from onboarding a new junior developer.
You have to explain everything.
You have to show them where things live.
You have to provide context.
And most importantly: you need documentation that is easy to find… and actually kept up to date.
👉 What do you do with a junior?
You walk them through the project structure.
You give them a tour of the repo.
You explain the conventions: “we use X here, Y over there, and please don’t ask why this folder is called final_v2_new.”
You show examples. You pair program. You review their code.
The junior doesn’t yet know how all of this holds together.
You do. So you teach them.
👉 What do you do with an AI agent?
Pretty much the same thing.
The agent has no access to your team’s tribal knowledge.
It doesn’t know that module A talks to module B through a weird convention introduced five years ago by someone who has since disappeared.
It doesn’t know where to look.
It needs READMEs. ADRs. Comments in the code. Examples of similar tasks. Clear rules and conventions.
Without that, the output will be mediocre.
And that’s not the model’s fault.
👉 Docs are not a luxury
Ever heard:
“Documentation? Everyone knows how this works.”
Or:
“Oh, that part was written by Dave. Dave doesn’t work here anymore.”
Exactly.
Everyone knows.
Except the AI agent.
A junior, with enough support, will probably understand the system after a month.
An agent starts from scratch every time.
If it can’t find clear documentation, whether that’s in the repo, Confluence, or a bunch of well-maintained .md files, it has one option left:
Yolo. Guess.
And yolo’ing your way through a legacy system is a very efficient way to create even more legacy.
⸻
If you don’t have time for documentation, an AI agent in a legacy codebase will struggle for exactly the same reason a junior without onboarding would.
You either invest in context; docs, rules, examples… or you keep agentic coding for greenfield projects.
Both approaches are perfectly valid.
Just don’t expect magic without doing the ground work.