Scaling Claude Code: Best Practices for Large Codebases

We examine Claude’s agentic search that traverses live codebases in real time, using grep and LSP, anchored by a harness of per-directory rules and plugins. We contrast this with traditional RAG, explore memory-efficient 'skills' via progressive disclosure, and discuss the human governance needed to keep AI aligned as models evolve. We also pose a provocative question: will future codebases be designed for AI readability as much as human readability?

Note:  This podcast was AI-generated, and sometimes AI can make mistakes.  Please double-check any critical information.

Sponsored by Embersilk LLC

Transcript

SPEAKER_01 0:00

So on my first day, my very first engineering job, um, I was just dropped headfirst into this million-line legacy code base.

SPEAKER_00 0:08

Aaron Ross Powell Oh man, that is rough.

SPEAKER_01 0:10

Yeah. I spent like three hours just trying to find where a single variable was defined.

SPEAKER_00 0:15

Aaron Powell It is terrifying when you realize the map you were given doesn't match the actual terrain you were standing on.

SPEAKER_01 0:20

Exactly. I felt like I needed a pirate's treasure map and I don't know, a machete just to navigate the folder structure.

SPEAKER_00 0:27

Aaron Powell That is basically a rite of passage at this point.

SPEAKER_01 0:30

Right. Well, today we are looking at how we're solving that problem at scale, not just for human developers, but actually for AI.

SPEAKER_00 0:37

Aaron Powell, which is such a massive shift in how we work.

SPEAKER_01 0:40

It really is. But before we get into all that, if you need help with AI training, automation, software development, or uh uncovering where AI agents can actually make an impact for your business, check out Embersilk.com. Embersilk has you covered.

SPEAKER_00 0:54

So our mission for this deep dive is to figure out how AI doesn't get lost in those million-line jungles.

SPEAKER_01 0:59

Yeah, we've pulled from technical documentation and engineering blogs about Claude Code to see how it navigates these massive enterprise environments.

SPEAKER_00 1:08

So how does an AI look at a sprawling code base differently than, say, older tools?

SPEAKER_01 1:14

Well, older tools mostly rely on something called RAG, you know, retrieval augmented generation.

SPEAKER_00 1:18

Aaron Powell Right, where they bake your entire code base into a centralized index.

SPEAKER_01 1:22

Aaron Ross Powell Exactly. But the problem is, at an enterprise scale with hundreds of developers pushing updates constantly.

SPEAKER_00 1:29

That index is just instantly out of date.

SPEAKER_01 1:31

Oh, totally. You ask the AI a question and it retrieves a module that somebody deleted like three days ago.

SPEAKER_00 1:37

Aaron Powell So Array is kind of like trying to navigate a growing city using like a printed map from last year.

SPEAKER_01 1:43

Aaron Powell That is a great way to put it. But Claude uses what is called agentic search. It doesn't rely on a static index at all.

SPEAKER_00 1:49

Okay, so how does it work then?

SPEAKER_01 1:51

It actually operates locally on the live code base, just like a human developer would. It uses tools like grep to rapidly search through your raw text files.

SPEAKER_00 2:00

Oh, so it's reading them and following references in real time.

SPEAKER_01 2:02

Right. It's working from the exact reality of the code in that specific second.

SPEAKER_00 2:07

Aaron Powell Wow, it's like dropping a scout with a live GPS directly into the terrain.

SPEAKER_01 2:11

Aaron Powell That makes perfect sense. Yeah. But I mean, dropping a scout into the wild only works if they actually know the rules of survival.

SPEAKER_00 2:17

Aaron Powell Which brings us to what the sources call the harness. The harness. Okay, what is that?

SPEAKER_01 2:22

Because Claude is exploring live terrain, you have to equip it with the right context. So the harness starts with Heli AEA.md files.

SPEAKER_00 2:31

And those give directory-specific instructions, right?

SPEAKER_01 2:34

Exactly. So a cliety.md file in your database folder might say, you know, always use the new v2 connection pool and never v1.

SPEAKER_00 2:41

Oh, so the AI instantly knows the local conventions.

SPEAKER_01 2:44

Right. And it avoids a critical mistake. And then uh you add LSP.

SPEAKER_00 2:48

The language server protocol. Yeah.

SPEAKER_01 2:50

Which means instead of just matching basic text strings, quad gets symbol level precision. Aaron Powell Okay.

SPEAKER_00 2:55

Meaning it actually understands the code's logic and structure.

SPEAKER_01 2:59

Aaron Powell Exactly. It accurately traces how functions connect across entirely different files. And I assume Teams can package all this into plugins, right? So a new engineer on day one gets the exact same setup.

SPEAKER_00 3:12

Yep. Good workflows don't just stay isolated as you know tribal knowledge anymore.

SPEAKER_01 3:17

Wait, let me push back here for a second, though. If we load Cloud up with hundreds of clickaue.md files, custom tools, and plugins.

SPEAKER_00 3:25

Sounds like a lot of data.

SPEAKER_01 3:26

Yeah. You won't just hit a memory limit? Like how does it not drown in context before it it even writes a single line of code?

SPEAKER_00 3:33

Aaron Powell Well, that's where skills come in. Skills are these reusable chunks of expertise, um, like a specific security review protocol.

SPEAKER_01 3:41

Okay, but how does that actually help the memory issue?

SPEAKER_00 3:43

Aaron Powell They use progressive disclosure. The AI basically doesn't load everything into its working memory all at once.

SPEAKER_01 3:49

Aaron Powell Oh, I see. It only pulls that security skill into memory when it detects it's actually working on a security-related task.

SPEAKER_00 3:55

Exactly. So the technical setup is highly efficient. But from our sources, even the best technical harness fails without the right human management behind it.

SPEAKER_01 4:03

Aaron Powell Right, which is a crucial point for you, the listener, especially if you are managing projects or teams right now.

SPEAKER_00 4:10

Yeah. Successful deployments now require an agent manager or a directly responsible individual. You really need a human centralizing these conventions.

SPEAKER_01 4:19

Aaron Powell And they have to audit their AI configurations pretty often, right? Like every three to six months.

SPEAKER_00 4:24

They do, yeah. Mostly because the AI models are evolving so rapidly.

SPEAKER_01 4:27

Aaron Powell But why exactly do old rules break new models?

SPEAKER_00 4:31

Aaron Powell Well, think of it like training wheels. An older, less capable AI model needed strict, you know, step-by-step prompts to avoid making mistakes.

SPEAKER_01 4:41

Right. That makes total sense.

SPEAKER_00 4:43

But if you force a newer, highly capable model to follow those same rigid steps, you actually constrain its ability to solve problems creatively.

SPEAKER_01 4:52

So the old training wheels prevent the new bike from going fast.

SPEAKER_00 4:55

Exactly. Which means as AI becomes more autonomous, human governance actually becomes more important.

SPEAKER_01 5:00

We are stepping up into these crucial management roles, really defining the guardrails.

SPEAKER_00 5:04

Right. Which actually leaves me with a thought for you to mull over.

SPEAKER_01 5:07

Go for it.

SPEAKER_00 5:08

If AI tools are increasingly navigating and writing our code like human developers, will future massive code bases be designed primarily for AI readability rather than human readability.

SPEAKER_01 5:20

Oh wow. That is a fascinating concept to imagine. It is just such an inspiring time to be in tech.

SPEAKER_00 5:25

It really is.

SPEAKER_01 5:26

We are looking at a future of profound human AI collaboration where we can tackle massive global engineering challenges together. If you enjoyed this podcast, please subscribe to the show. Hey, leave us a five star review if you can. It really does help get the word out. Thanks for tuning in.