Let the Codebase Guide the AI

Point, Don't Explain

The most effective approach I've found for working with AI on existing codebases: don't explain how things work. Show it.

Instead of telling AI "we use a repository pattern with dependency injection and our services follow this structure," point it to an existing service that does something similar. AI reads the code, picks up the patterns, and follows them.

This works because AI is excellent at pattern matching. Give it an example and it replicates the style, structure, and conventions. Give it an explanation and it interprets your words through its training data -- which may not match your codebase at all.

The Three Pieces

Context: What Are We Building?

Point AI to existing documentation about the project. Architecture docs, READMEs, design documents -- whatever explains what the system does and where the new work fits in.

AI needs the bigger picture. Not just "add a new endpoint" but "add a new endpoint in a system that does X, where this endpoint fits into workflow Y." Without this, AI builds something that works in isolation but doesn't fit the system.

Tests: When Are We Done?

Existing tests serve as a regression safety net -- they ensure AI doesn't break what already works. New tests get written first. Before AI writes any implementation, you define what success looks like.

Examples: How Do We Build It?

This is the key insight. Instead of explaining how to implement something, point AI to existing code that does something similar.

"Look at how the user service handles authentication. Do the same thing for the payment service."

"Follow the pattern in the orders package for how we structure our handlers."

AI reads the existing code and replicates the approach. It picks up code structure, naming conventions, error handling patterns, how dependencies are wired, how tests are structured, the idioms your team uses. You don't have to explain any of this. The code explains itself.

Why This Works

Every codebase develops its own way of doing things. These conventions aren't always documented. They live in the code.

When you explain things in words, AI interprets through its training data. It might implement a "repository pattern" differently than your codebase does. It might handle errors the way Spring does when you're using Express. When you point to existing code, it follows your conventions. Not the internet's.

The biggest risk with AI on existing codebases is introducing a second way to do the same thing. Two patterns for error handling. Two approaches to validation. Pointing to examples keeps everything aligned.

The Compounding Effect

Every piece of well-written code becomes an example for future work. Good patterns propagate -- AI picks them up and replicates them across new features, new services, new modules. The codebase teaches consistency by existing.

But it compounds in both directions. Let AI write sloppy code and merge it, and that sloppy code is now an example too. The next session might point to it. Bad patterns propagate just as easily as good ones.

This is why code review still matters even when AI writes everything. You're not just reviewing for correctness -- you're curating the examples that will guide all future development. Like mentoring a junior developer, you lead by example. Except this junior never internalizes the lessons.

The Permanent Onboarding Problem

A junior developer learns. After you point them to the user service a few times, they internalize the patterns. They stop asking. They know where to look without being told.

AI doesn't. Every session starts from zero. You point it to the same examples, the same documentation, the same patterns -- every time. It never learns where to look on its own. It never internalizes your conventions. You are permanently onboarding it.

The distinction matters: knowledge transfers, but experience doesn't. You can share what you learned -- the patterns, the conventions, the constraints -- but the process of having learned it, the context that makes it stick, remains yours. AI receives the knowledge each session but never has the experience. It can follow the pattern you show it without understanding why that pattern exists, which means it can't adapt when the pattern doesn't quite fit. Every session, you're transferring knowledge to something that will never convert it into understanding.

This is why documentation matters more than you think. If your patterns live only in your head, you're repeating yourself every session. If they live in documents -- architecture guides, project context, what you're building and why -- you just point AI to them and move on.

Every piece of documentation you maintain is a session you don't have to spend re-explaining. The upfront cost pays for itself the third or fourth time you point AI to it instead of typing the same guidance again.

And AI can create this documentation as a byproduct of work. When AI learns something about your codebase during a session -- a pattern it picked up, a convention it figured out, a constraint it ran into -- have it write that down. It's creating a persistent memory for itself. Not learning, not internalizing -- just leaving notes for the next session to pick up.

When This Doesn't Work

This approach assumes you have existing code worth following.

If your codebase is a mess, AI will replicate the mess. If your patterns are inconsistent, AI will pick up the inconsistency. You're telling it "do it like we do it here," and if how you do it here is bad, you'll get more bad code faster.

It also assumes the existing code is relevant. If you're building something genuinely new -- something with no analog in the codebase -- you don't have examples to point to. You're back to explaining.

But most work on existing codebases isn't genuinely new. It's "another service like the ones we have." It's "a new feature that follows the same patterns." For that kind of work -- the majority of it -- the codebase itself is the best guide you can give AI.