How do I onboard an AI coding assistant to a legacy codebase?

Why legacy codebases defeat stock AI

Legacy codebases are not just old — they are dense with implicit knowledge. Why does the billing module use a ten-year-old ORM? Because the migration broke reconciliation in 2019. Why does the auth layer triple-check permissions? Because of an incident in 2017. None of this is in the code. A stock AI assistant reads the code, sees the workarounds, and proposes to "clean them up" — introducing the same bugs you fought a decade ago. Onboarding has to surface the implicit layer first.

Ingest the repo as a graph

Step one is structural. bRRAIn's Code Sandbox parses the repo into an AST-annotated graph inside the POPE compute layer — Files, Functions, Calls, Tests, Owners, Modules. The agent now has a traversable map of the codebase it did not train on. The Consolidator keeps the graph current as new commits land. This gives the agent structural awareness, but it does not yet give it the "why" behind the structure — that is the next step.

Extract implicit decisions into explicit ADRs

Step two is historical. A senior engineer and the agent walk the graph together, hunting for workarounds, comments with dates, and suspicious patterns. Each one becomes a candidate ADR: the historical context, the attempted alternatives, the reason the current shape survived. The Document Portal is where these ADRs land. The Handler then reads them at inference, so future proposals respect the hard-won constraints rather than cheerfully undoing them.

The Librarian role accelerates the whole thing

Doing this manually takes months; doing it with a certified Librarian takes weeks. bRRAIn's Care Analyst certification in the bRRAInCare path covers the curation discipline — prioritising which decisions to formalise, interviewing graybeards, turning tribal knowledge into graph nodes. The Librarian is the bridge between the codebase's implicit history and its explicit memory. Once that history is captured, the AI assistant operates on the same footing as a senior hire on day three instead of day three hundred.

Relevant bRRAIn products and services

• Document Portal — landing zone for ADRs extracted from legacy code.
• Code Sandbox — parses the repo into a structural graph the agent can walk.
• POPE Graph RAG / Memory Engine — stores ADRs and the code graph so implicit history becomes queryable.
• Care Analyst certification — formal role for the Librarian who curates legacy knowledge.
• bRRAInCare path — broader track covering maintenance and care analyst roles.
• Handler — applies extracted constraints so the agent respects hard-won legacy decisions.