Bringing an AI coding assistant into a codebase that's been developed for years by a rotating cast of engineers is a different problem than starting fresh on a new project. The conventions exist, but a lot of them live in people's heads, not in the code itself. Here's a practical process for closing that gap.
Step 1: Audit what's actually undocumented
Before writing a single rule, spend time identifying what a new human engineer would need explained that isn't obvious from reading the code. Why does this service have an unusual retry pattern. Why is there a seemingly redundant validation layer in two places. Which directories are actively maintained and which are legacy code nobody wants touched. This audit is the actual hard work; writing the file afterward is comparatively easy.
Step 2: Interview the people who'd normally onboard a new hire
Whoever currently walks new engineers through the codebase's quirks has most of the knowledge you need. A short conversation focused specifically on "what do you always end up explaining that isn't written anywhere" surfaces exactly the kind of tribal knowledge an assistant needs and can't infer from the code alone.
Photo by Walls.io on Pexels
Step 3: Start with boundaries, not style
For an established codebase, the highest-value first pass isn't style preferences, it's boundaries. Which files or directories require human approval before touching, database migrations, auth, billing. Which patterns look reasonable but are actually deprecated and shouldn't be extended further. Getting these wrong costs real incidents; style violations cost review comments.
Step 4: Run a supervised trial before trusting it broadly
Once you have a first-pass instructions file, give the assistant a handful of representative tasks under close supervision, reviewing every change carefully rather than assuming the file is sufficient. This surfaces gaps quickly: places where the assistant's default behavior conflicts with an unwritten convention the file didn't yet capture.
Treat each surfaced gap as a signal to add a specific rule, not as a one-off correction to be repeated verbally next time. This is the step that turns a generic-sounding instructions file into one genuinely tailored to your specific codebase's quirks.
Step 5: Expand gradually, don't front-load everything
Resist the urge to write an exhaustive file covering every conceivable edge case before the assistant has touched any real code. A shorter file covering the highest-stakes boundaries and most commonly needed context, expanded deliberately as new gaps surface through actual use, tends to work better than an enormous upfront document that's mostly speculative and hard to keep accurate.
The Anthropic documentation on Claude Code frames the instructions file this way too, as something that evolves alongside actual usage rather than a document meant to be complete on day one.
Step 6: Assign ownership before the file goes stale
An onboarding-phase instructions file gets a lot of attention initially and then, without an assigned owner, tends to drift out of date as the codebase changes. Assigning responsibility for keeping it current, ideally to whoever already owns architectural decisions, prevents the file from becoming actively misleading six months after the initial onboarding effort.
Common mistakes teams make during this process
A few patterns show up repeatedly, and they're worth cross-checking against general onboarding guidance like Google's engineering practices documentation, which covers a lot of the same "make the tacit knowledge explicit" territory for human engineers. Skipping the interview step and writing the file purely from reading code, which misses the reasoning behind unusual decisions entirely. Writing an exhaustive file upfront that nobody has time to verify is accurate. And treating the onboarding as a one-time project rather than an ongoing process that continues to surface gaps for months after the initial rollout.
Version control history is worth mining too. GitHub's blame and history tooling can help trace why an unusual pattern was introduced in the first place, which is often faster than tracking down the original engineer, especially on a codebase that's had significant turnover.
Handling codebases with genuinely inconsistent history
Established codebases, especially ones that have changed hands across several teams, often contain multiple competing patterns for the same problem, three different approaches to form validation, two separate HTTP client wrappers, because different eras of the team made different choices and nobody fully migrated the old code. This is one of the trickiest onboarding situations, because there's no single "correct" pattern to document, only a current preferred one and legacy examples that shouldn't be extended further.
The instructions file needs to be explicit about this distinction rather than silent on it: name the current standard clearly, and separately note that older code may show a different pattern that shouldn't be copied into new work even though it exists elsewhere in the same codebase. Without this explicit call-out, an assistant reading nearby legacy code as an example will often reasonably match the pattern it sees locally, propagating exactly the inconsistency you're trying to phase out.
Using the assistant itself to help with the audit
Once a first-pass instructions file exists, the assistant can actually help extend it. Asking it to summarize patterns it notices across a directory, or to flag places where it found conflicting conventions while working, surfaces gaps a human audit might miss, especially in large codebases where no single person has read every file. Treat this as a lead to verify, not a rule to add automatically, since the assistant's summary of "what it noticed" still needs human judgment about which observation is actually worth codifying.
This becomes a genuinely useful ongoing habit rather than a one-time onboarding step: periodically asking the assistant what inconsistencies or ambiguities it's run into recently is a cheap way to surface instructions file gaps before they cause a real mistake.
Budgeting realistic time for this process
Teams often underestimate how long a thorough onboarding pass takes on a codebase with real history, treating it as an afternoon task rather than the multi-week process it usually is for anything beyond a small project. A more realistic estimate involves an initial week for the audit and interviews, a couple of weeks of supervised trial runs with real tasks, and then ongoing refinement for a month or two as gaps continue to surface through actual use. Planning for this timeline upfront prevents the common failure mode of writing a rushed first draft and declaring the onboarding complete before it's actually been tested against real work.
What good onboarding looks like after a few months
By the time an assistant has been working in a codebase for a few months under this kind of process, the instructions file should reflect real, hard-won lessons rather than generic advice, specific enough that a new human engineer reading it would also learn something genuinely useful about the codebase's non-obvious decisions. That convergence, a file useful to both the assistant and a human, is a good sign the onboarding process actually worked.
For the deeper framework on writing and maintaining that file well beyond the initial onboarding push, 137foundry.com's guide to instructions files covers structure, specificity, and long-term maintenance in full.
Top comments (0)