Big Idea

The argument in one line.

AI coding tools accelerate software entropy by multiplying shallow modules, requiring human engineers to act as strategic architects who enforce deep module boundaries and explicit testing seams.

Who This Is For

Read if. Skip if.

READ IF YOU ARE…

Engineers watching their codebase degrade into a fragile ball of mud after heavy use of AI coding assistants.
Tech leads trying to structure Claude Code or autonomous agent workflows around robust architectural boundaries.
Developers who want practical, repeatable criteria for refactoring legacy code into testable, high-leverage abstractions.

SKIP IF…

You only write greenfield throwaway prototypes where long-term maintainability and regression testing do not matter.
You expect autonomous AI agents to make high-level architectural trade-offs without human oversight.

TL;DR

The full version, fast.

AI code generation dramatically speeds up development while accelerating software entropy, scattering uncoordinated logic across shallow modules. Fixing this requires treating LLMs as tactical sergeants guided by a human strategic general. By running an architectural evaluation skill in Claude Code, engineers discover duplicate logic and missing seams across their repository. The human then refactors these into deep modules that conceal extensive implementation behind minimal interfaces, unlocking locality for maintainers and leverage for callers.

Free for members

Chat with this breakdown — free.

Sign in and you get 23 free chat messages on us — ask for the hook, quote a framework, find the exact transcript moment, generate a markdown action plan. Bring your own key when you want unlimited.

Create a free account →

Chapters

Where the time goes.

00:00 – 00:46

01 · AI and Software Entropy

Explains how AI rapid code production accelerates software entropy, turning clean codebases into tangled balls of mud.

00:46 – 01:42

02 · A Shared Vocabulary for Architecture

Introduces the improve-codebase-architecture skill and why establishing precise shared definitions with an LLM is essential.

01:42 – 02:40

03 · Deep vs Shallow Modules

Breaks down module composition into interface versus implementation, referencing John Ousterhout's design philosophy.

02:40 – 03:31

04 · Measuring Interface Depth and Leverage

Contrasts deep modules that hide complexity against shallow modules that leak complexity to callers.

03:31 – 04:43

05 · Seams and Adapters for Testing

Explains how identifying architectural seams enables testable adapters like clocks and fakes without slowing execution.

04:43 – 05:26

06 · Locality vs Leverage

Defines locality for maintainers and leverage for callers as the two essential metrics for architectural health.

05:26 – 07:22

07 · Automated Codebase Audit

Runs the skill on a 1,500-commit repository in Claude Code to find uncoordinated logic and missing seams.

07:22 – 08:53

08 · The Socratic Grilling Session

Engages in interactive grilling with the agent to define concrete TypeScript types and unify fragmented domain ordering.

08:53 – 11:19

09 · Tactical Agents and Strategic Engineers

Frames the engineer as the strategic general directing the tactical LLM sergeant, especially when rescuing legacy code.

Atomic Insights

Lines worth screenshotting.

AI assistants accelerate software entropy because each localized edit ignores the architectural coherence of the entire codebase.
A deep module hides massive internal implementation behind a compact, simple interface, maximizing leverage for callers.
Shallow modules expose complex interfaces with trivial internal logic, forcing callers to understand internal plumbing.
Seams are the boundaries where module interfaces live, serving as the required insertion points for integration and unit tests.
Adapters allow concrete implementations to satisfy seam interfaces interchangeably in production and test environments.
Deep modules produce locality for maintainers by concentrating related logic, state changes, and bug fixes into a single file.
Deep modules produce leverage for callers by providing expansive capabilities per unit of interface they are required to learn.
Autonomous agents operate as tactical sergeants capable of fast code edits, but they require a strategic general to make system-level design calls.
Legacy codebases are simply bad codebases filled with shallow modules that lack a safety harness of tests.
Refactoring parallel frontend and backend ordering logic behind a unified domain seam eliminates desynchronization bugs.

Takeaway

Architectural depth turns tactical AI slop into durable software.

WHAT TO LEARN

Autonomous agents excel at tactical implementation but create architectural chaos unless human developers define shared domain vocabulary, enforce deep module boundaries, and guard every seam with tests.

01AI and Software Entropy

AI generation accelerates software entropy by making micro-changes without global context, degrading systems into unmaintainable mud.

02A Shared Vocabulary for Architecture

Establish a shared architectural glossary with your LLM to eliminate misunderstandings around modules, interfaces, and seams.

03Deep vs Shallow Modules

Prioritize deep modules that hide complex behaviors behind minimal interfaces, avoiding shallow modules that leak internal state.

04Measuring Interface Depth and Leverage

Leverage represents how much functionality a caller accesses relative to the cognitive burden of the interface.

05Seams and Adapters for Testing

Locate architectural seams across components so interchangeable adapters can substitute fake implementations during automated testing.

06Locality vs Leverage

High locality groups frequently changing dependencies together, containing future bugs and maintenance overhead within one module.

07Automated Codebase Audit

Use diagnostic agent skills to audit repos for duplicate parallel implementations across frontend and backend tiers.

08The Socratic Grilling Session

Subject candidate refactorings to grilling rounds with the model to interrogate domain edge cases before modifying files.

09Tactical Agents and Strategic Engineers

Act as the strategic general who establishes boundaries, delegating execution to the LLM tactical sergeant.

Glossary

Terms worth knowing.

Deep Module: A software component that hides substantial implementation complexity behind a small, simple interface.
Shallow Module: A component whose interface is relatively complex compared to the minimal behavior or logic it provides.
Seam: A place in a codebase where program behavior can be altered or observed without modifying the calling code, typically used for testing.
Adapter: A concrete implementation that fulfills an interface contract at a defined architectural seam.
Software Entropy: The tendency of a software system to become increasingly disorderly, coupled, and difficult to modify over time.

Resources

Things they pointed at.

02:58bookA Philosophy of Software Design

03:24toolTanStack Query

05:44tooleffect.ts

07:55toolSandcastle

Quotables

Lines you could clip.

00:09

“AI has simply accelerated software entropy.”

Direct counter-narrative to hype about instant code generation.→ TikTok hook↗ Tweet quote

03:15

“depth, the amount of behavior a caller can exercise per unit of interface that they have to learn.”

Concise definition of Ousterhout's software design principle.→ newsletter pull-quote↗ Tweet quote

09:34

“I think of agents as really, really good tactical programmers.”

Sharp mental model defining what AI agents are good for versus where they fail.→ IG reel cold open↗ Tweet quote

The Script

Word for word.

Read-along

Don't just watch it. Burn it in.

See every word as it's spoken — crank it to 2× and still catch all of it. The same dual-channel trick behind Amazon's Kindle + Audible.

metaphor

You've probably seen the thousands of LinkedIn CEO posts saying that code is cheap and they can move faster than ever before. But what's happening is that AI has simply accelerated software entropy. In other words, codebases are falling apart faster than they ever have before.

Because every time that you make a change that doesn't take into account the entire codebase, you are likely to introduce little things, weird things that make the codebase harder to change. And over time, that just snowballs and snowballs until you end up with a huge of mud.

Sloppy, sloppy mud that is incredibly hard to reverse if you don't know how to do it. I've made a video about this before, introducing folks to the idea of deep modules. And that video focuses more on prevention, how you can prevent your setup from getting to that point.

Let's now focus on the cure, how you can take a code base that feels like it's beyond repair and rescue it. And you can do that with some good old software fundamentals, as well as my improved code base architecture skill. We're going to be walking through what this skill does, revisiting some of the terms we looked at in the other video.

And then we're going to take that and apply it to a real code base. And this, by the way, is part of my GitHub skills repo, which is currently sitting at 41 .5k stars. Bonkers.

Now, one of the things that I added to this improve code base architecture skill recently was a glossary of terminology. Having a shared vocabulary with the AI is super important because it means that you can talk using the same language. You can understand what each other's language is, and you can be a lot more precise with what you're asking for.

This terminology here is super... duper useful. And I'm going to spend a portion of this video going through what each of these terms actually mean.

Honestly, just understanding this stuff at a deep level will make you a better software developer. So let's get started by talking about modules. A module is a unit of something in your application.

It could be a bunch of React components that all fit together to form a page. It could be a bunch of functions inside your application that are entirely responsible for authentication. Or it could simply be the logger that you've chosen, like a login to the console, login to a file.

or log into a third -party service. In a good code base, these modules talk to each other and they talk to each other via their interfaces. An interface is everything a caller must know to use the module correctly.

For instance, if it's an authentication module, then it might have a sign -in method. It might have a sign -out method. And these methods are the interface to that module.

The methods are not the only thing that's important. The interface also includes kind of nebulous information about how to call the module. So perhaps it's documentation too.

The implementation is then what's inside. the module, what it actually does when you call sign in or sign out. And so this is the core primitive that we're talking about, the modules that have interfaces and implementations scattered throughout your application.

These modules can either be deep modules or they can be shallow modules. A deep module hides lots of implementation behind a relatively simple interface. A shallow module has a complex interface and kind of not much implementation actually behind it.

These ideas are from John Osterhout's book, A Philosophy of Software Design, which I read. recommend you pick up a copy of. Deep modules are considered better than shallow modules because it hides more information away from the caller.

In other words, the person who's calling this or the function that's calling this only needs to know about this tiny little interface and they'll get access to all of this implementation. Lovely. And so that's what we describe as depth, the amount of behavior a caller can exercise per unit of interface that they have to learn.

Really good open source libraries like TanStack Query or something have really good deep modules. In other words, they're hiding a lot of complexity behind a super simple interface.

These modules then interact with each other and they have dependencies on each other. For instance this module might interact with this module here which then interacts with this module up here and this module up here and they have these dependency graphs between them. These gaps between these modules are called the seams.

It's the location at which the module's interface lives inside the application. These seams are usually where you're going to do your unit testing or your integration testing. For instance if we wanted to test this module in isolation down here, then we would add a mock or something just at this seam.

So figuring out where your seams are going to live in your application is crucial to getting a good architecture. When you find out where a seam is in your application, you need some concrete thing, a module, that satisfies that interface. This is what I'm going to call an adapter, which I'm taking from hexagonal architecture.

For instance, if you have some kind of application that depends on a clock running, then you may want to have a clock, a normal clock inside here using the actual living clock. And then inside some tests, you may want to have an adapter that is a fake clock. These both satisfy the interface of that seam.

And it means that you can use the fake clock in tests. So you don't have to literally wait two weeks for your test to finish. So that's how seams and adapters play together.

The benefit of all this is that these deep modules have two main properties or two main benefits that you get from them. But the maintainers, the people maintaining this module, they get locality. Changes to that module and bugs and all the fixes to do with them, they concentrate.

in one place in that deep module. If it's scattered around over multiple different modules, then you have low locality. You want high locality, grouping and co -locating the things that matter and that often change together.

The people using this module will get more leverage the deeper the module is. In other words, more capability per unit of interface they have to learn. And so when we're talking about improving our code bases, these are the two attributes that we're aiming at.

Right, that's enough knowledge. We know the basic terms of engagement. Now let's go and...

improve a code base. The code base we're going to look at is my course video manager code base, which is the repo of software that I'm actually using to record this video. This code base has had around 1 ,500 commits here.

And I wouldn't say it's a ball of mud, but I also wouldn't say it's perfect either. It's a React router application. It uses effect .ts under the hood.

Let's get into it. I'm going to open up a new Claude session inside here and I'm going to run my improve code base architecture skill. I'm going to turn off auto mode.

Auto mode does some funny things with these human in the loop style flows and so I don't want it on here. We can see it's going and exploring and looking through the code. That's what it's instructed to do first.

Here we go. Explore architecture for deepening opportunities. Usually a bad code base is one that has a ton of shallow modules in it or one that has very poor leverage for those modules or poor locality.

where lots of stuff is spread in lots of different places. Okay, it's come back with some candidates here. Let's bump up the screen size and...

Hopefully, Claude Code won't just destroy itself. Okay, I guess maybe we're not bumping up the screen size. Thank you for that, Claude Code.

We can see it's identified six deepening opportunities here. These candidates here are pretty hard to explain because they sort of require domain knowledge about my repo. But we can see here that it's saying that there's a concept that doesn't have a single seam.

In other words, there are two implementations of this insertion point and they live in parallel. And the seam where they must agree is untested. This essentially means that the front end could make some changes.

But the back end, because it has a separate parallel implementation, could be out of sync with it. So this, I think, is actually a really good candidate for refactoring into a single module. We gain locality.

And it says that here, we would gain locality. The interleaved clip, clip section ordering rule lives in one place. So let's go and take a look at that.

Let's actually say, yeah, I'd like to pick one here. That seems like a good candidate. So let's fire that off and see what it says.

Okay, Claude is trolling me here. It says, I'd like to pick one. I meant, I meant one.

Great. Okay. So it now has come back with, it's got concrete code on both sides to ground this and it enters a grilling session.

And in this grilling session, we can take the ideas inside here and we can start kind of talking about what a better solution would be. This is a nice sentence here. The backend has no end.

Let's not think about that too literally. What you end up doing with this skill is you end up talking about the potential proposed solution and it will then propose a shape. And once that's all done, you can take that and you can put that in as a GitHub issue.

into your issue tracker which can then be picked up by an AFK agent. You should check out my video on Sandcastle if you're interested in that. Now in the course of normal development what I would do is go through and thoughtfully answer each of these questions in turn but since I'm doing a video and this is slightly artificial I'm going to say could you just choose your recommended answers for each of these questions and that should speed us through to actually making the change or potentially creating an issue out of this.

So it's now coming back with a proposed module shape and it's also asking to verify a particular particular part of the implementation where end is collapsed and to sketch the actual TypeScript interface. Yeah, go ahead and do both.

That sounds great. Let's ping that off and see what it says. Okay, it has figured out the implementation detail it needed and it's come back and proposed a design here.

So each of these functions are going to be essentially the... the interface for this module. And so we can talk about this with the AI and figure it out.

It's again come back with two design decisions that it wants my feedback on. And here I think you've got the flavor of how this skill works and the kind of conversations that you end up having with the AI based on this. If I want to turn this into an issue that my AFK agent picks up, I can use to PRD or to issues here.

And by the way, if you're interested in these skills that I'm talking about, then you should check out this site here, which is linked below. I'm going to be creating a real documentation site for these skills.

And for now, I have a newsletter that you can sign up to for the latest updates, as well as tips and tricks and resources for getting the most out of agents. The thing that's important to notice here is just how much this skill demands of you, the user. This is not an AFK skill that you can just sort of run and kind of like just rely on to continually improve your code base.

This requires a judgment call from you, the programmer sitting above the LLM. I think of agents as really, really good tactical programmers.

They're able to get on the ground and make changes quickly, but they need someone on the level above them who is the strategic programmer. And that's what this skill does. It allows the sergeant to go and run around the code base and look for potential improvement.

opportunities, but then you, the general, have to go and actually make the change and decide what's good for the long -term health of the codebase. I recommend that you run this skill every couple of days, really. Especially in a codebase that's fast -moving, you're going to come up with tons of opportunities for deepening the codebase.

And the deeper you get those modules, the higher leverage you're going to get out of them. And leverage as well means testing. If you have a set of really nice, clear seams in your codebase, then you're going to be able to write really nice tests around those nice deep modules.

And the better your tests are, the better the output from the agent is going to be. One final thought here is that lots of folks ask me how you would get started by using AI in a legacy code base. And a legacy code base is probably going to have a lot of shallow modules.

I mean, we talk about legacy code bases, what we really mean are bad code bases. Code bases that are hard to make changes in. And what you really need before you start making changes in a legacy code base is a harness around the code base to make sure that your changes don't mess anything up.

So for that you need tests, testing really nice deep modules that have a lot of leverage and locality. So running improved codebase architecture is a great place to start. Thanks for watching folks and I hope that answers some of your questions about how to solve this never -ending problem of AI just running away and creating terrible codebases.

I hope you enjoy the skills. Do follow the link below if you want to find more of them. So thanks for watching and I'll see you in the next one.

And what you really need before you start making changes in legacy codebases

The Hook

The bait, then the rug-pull.

LinkedIn executives celebrate cheap AI code, but uncoordinated edits accelerate architectural decay into an unmaintainable ball of mud. The antidote is not avoiding AI, but arming it with strict architectural primitives.

Frameworks

Named ideas worth stealing.

02:41model

Deep vs Shallow Modules

A deep module provides significant behavioral capabilities through a simple, compact interface, whereas a shallow module exposes a large interface for minimal underlying logic.

Steal forEvaluating whether new software components actually hide complexity or just add unnecessary indirection layers.

03:31concept

Seams and Adapters

A seam is the exact boundary where a module's interface connects with consumers, while an adapter is any concrete implementation fulfilling that seam interface in production or test environments.

Steal forStructuring mocking and testing boundaries so tests run fast without monkey-patching production code.

04:44model

Locality and Leverage

Locality guarantees that changes and bug fixes concentrate in one single place for maintainers; leverage ensures callers receive maximum utility per unit of interface learned.

Steal forReviewing pull requests to ensure changes increase caller capability while localizing downstream maintenance.

09:34model

The Tactical Sergeant vs Strategic General

Autonomous AI coding agents act as tactical sergeants executing rapid, localized edits on the ground, requiring a human strategic general to guide system boundaries and long-term codebase health.

Steal forStructuring engineering team policies around AI code review, human-in-the-loop validation, and architectural direction.

CTA Breakdown

How they asked for the click.

VERBAL ASK

09:01newsletter

“if you're interested in these skills that I'm talking about, then you should check out this site here, which is linked below. I'm going to be creating a real documentation site for these skills. And for now, I have a newsletter that you can sign up to for the latest updates”

Points to AI Hero website with an email opt-in for skill documentation, updates, and agent engineering tips.

FROM THE DESCRIPTION

PRIMARY CTAWhere the creator wants you to go next.