Hey!

Chris here. Welcome to Blueprint—the newsletter to help you build a winning engineering team.

Chris here. Welcome to Blueprint—the newsletter to help you build a winning engineering team.

I've been doing a lot of AI days with customers lately. These are 3- or 4-hour sessions where I sit on a call with their lead engineer and the team, and I solve a problem live with them.

The feedback is always the same: "You lit my brain on fire." The AI tools and workflows I show them always create feelings of incredible productivity and excitement.

So they run out and start generating enormous amounts of code.

This is great, until they inevitably hit a wall trying to ship it because nobody fully understands what got built.

Comprehension is now the bottleneck that productivity once was.

Let me show you exactly how we fix that at Surton. 👇️ 

📒 DEEP DIVE

The 3-Step Framework for Understanding Any Codebase

How to get total clarity on any messy codebase before writing a single line of code.

Every time I go into a new code repository, I start with the same 3 steps.

And believe it or not, they don't include debugging, refactoring, or even writing code.

I always start by building context.

Here's what's happening right now across the engineering world: AI can generate thousands of lines of code in minutes. Engineers are getting this incredibly fast feedback loop where they feel like they're making massive progress.

Then they try to ship it to production and realize someone has to validate that everything actually works.

Suddenly, you're staring at a mountain of code that nobody fully understands.

That's why I've developed a 3-step process that I run every single time I touch a new codebase.

These steps have become non-negotiable for my team, and they're the reason we can move fast with AI without creating chaos.

Let me walk you through them.

Step One: Map the System

We start with a detailed prompt whose core instruction is simple: "Look over this entire codebase and build an architecture.md file that describes where files go in different directories for different purposes."

This creates a structural map. It reveals where aspects like documentation, scripts, and configuration files live.

If you have eight top-level directories in your repo, this document explains what each one is for.

At this stage, we're not asking it to fix anything or build anything new. We're teaching the AI how to see the system.

This is essential because you can't leverage what you don't understand, and you can't understand what you can't see clearly.

Step Two: Define What Must Be Known

Once the architecture document exists, I run the 2nd prompt. The core instruction here is, "Go look at that architecture file and come back with a detailed guide list. You're making a list of all the guides that any engineer would need to deeply understand this codebase. You're not writing any guides yet—just the list."

This guide list is essentially a detailed checklist. It identifies every section of documentation that needs to exist, and it cites which specific files you'd need to examine to write each guide.

As with step 1, this generates an output that becomes input for the next step.

Step Three: Write Everything, Then Read Everything

Only now do I have the AI write the actual guides with a prompt that basically instructs the AI to "Go look at the guide list, supplement with the architecture document, and write every single guide on that list."

When this step finishes, you have 100s of pages of engineering documentation. Clear, structured, comprehensive.

But here's where people make a mistake.

They think the AI doing the work means they don't have to do anything. They'll just give the AI access to these guides and let it reference them as needed.

That's not how this works.

I tell every engineer on my team, "Go make a coffee and read every single one of these guides, cover to cover. You're not allowed to take another step until you've read them all."

This is the step that makes the difference between having a good relationship with AI and a bad one. You just used AI to build what would have taken months in about 30 minutes.

That's insane value.

But the puppet master still needs to understand what's going on before controlling the puppets.

Reading the documentation is the entire point of this whole process.

And here's the other thing I tell people: Don't read in silence.

Have the guides open on one screen and your AI tool on another screen. As you're reading, ask questions like you're sitting with the senior engineer who wrote the documentation:

"I don't understand this. What is this?" or "Can you explain Redis streams to me in 5 sentences?"

This unlocks hyper-learning—and it makes you the kind of engineer who can use these tools to their full potential.

Why This Process (Still) Needs to Exist

Despite how powerful AI is today, you still need to understand what the next best thing is that your business needs. These tools can't answer that question without you.

If it gets something slightly wrong early on, you're building abstractions on top of faulty assumptions. And those errors get amplified over time.

As you're reading through the documentation, you might find mistakes. You can catch them, fix them, and update the guides. That process of reading, questioning, and correcting is what builds real understanding.

I can't imagine a world where we don't want really well-documented codebases. At least not until AI gets infinitely better than us at judgment and decision-making.

Until then, we still need to read this stuff.

BEFORE YOU GO…

This 3-step system allows you to create shared understanding at scale.

I can embed 25 years of engineering wisdom into English-language prompts, and now 10, 100, or 1,000 engineers can use that knowledge.

It's a superpower—but only if those engineers actually understand what they're building.

So before you ask AI to build for you, make sure everyone and everything understands what you've already built.

Talk soon,

Chris.