Theo-brainUnofficial. Not affiliated with Theo or t3.gg.
Sign inYou
28:36
0:00

Stop Pretending You Understand Your Codebase

Sunday, Sep 6 · 29 min · about 8 min to read

Theo-brain watched all 29 min

Theo agrees with Sean that nobody fully understands a large codebase. Good engineers rely on intuition for where things belong, not memory of every file. For agent work: treat each new agent thread as a capable newcomer, set up the code so a newcomer can find things, and know roughly how the big pieces and data flow fit together rather than every detail.

Briefing is enoughThe notes cover the main points and practical steps, so you can skip the video unless you want the full discussion.

Tap any time to jump the video there.

Key takeaways

A good codebase is not one where everyone knows where everything is. It is one where people can quickly find the right place for something. The best engineers have intuition for how good software is laid out, not a memory of every file.

work in that codebase, too. A good codebase is not one where every single person at the company knows where everything is. A good codebase is one where it doesn't really matter that much. What matters is that people can find the right place for something relatively quickly. I'm talking about

AI agents mean 100% staff turnover all the time. Every new thread (a fresh chat session with the agent) forgets everything the last one learned. It is like hiring a new developer each time, which works well only if the codebase is set up for newcomers.

to remember is that agents are 100% turnover constantly because every time you start a new thread, all the things the previous thread do are gone. It's like you're starting with a fresh developer every time you open a new thread. And that is awesome if you set

Theo is converting the T3 Code mobile app to Swift UI, Apple's native framework, without reading the code. What carried him was not implementation details but knowing where things live and how data moves between the parts of the system.

the most part, I have not had to understand the implementation details of the mobile app at all in order to do something like this. But my understanding of where things are overall and how data gets to and from

Theo shares Sean's view that AI models are a double-edged sword. They make it harder to build a detailed mental model of the software, but they let you build a partial one quickly and use it well. He calls it a trade-off he is still thinking through.

tools, LMS are a double-edged sword. They make it harder to construct a detailed mental theory of the software, but they allow you to build a partial theory quickly, and they can help you leverage that partial theory more effectively. This is a complex trade-off that Shawn is still thinking about. I will say that I am as well. Setting LMS

Three skills here are new to you.

Treat every agent thread as a new hire New

What it is
Set up your codebase so a very capable developer who has never seen it can still do useful work right away. Each agent session starts with no memory of earlier ones.
Why Theo cares
He says this challenge is part of why he enjoys coding this new way. Working out what a smart newcomer needs is both fun and rewarding.
How to try it
  1. Open a fresh agent thread and watch where it gets lost or makes wrong guesses.
  2. Ask your agent to reorganize code so things sit where a newcomer would look for them.
challenge in a way. And this is part of why I've been liking coding this new way so much is it's fun to try and figure out what it takes to make a new developer who's incredibly capable but doesn't know your codebase yet be able to act in meaningful ways as effectively as possible. It's like a fun rewarding

Use AI to learn an unfamiliar codebase New

What it is
When you take over code nobody remembers, ask an AI questions about it and have it check its answers against how the code actually behaves.
Why Theo cares
He thinks AI has made getting up to speed on old code much easier. The AI lacks the original team's history, but it has their output, which is often enough.
How to try it
  1. Ask your agent to explain one flow from start to finish before changing anything.
  2. Have it verify each answer against the actual code rather than trusting its first explanation.
Yes. All true. And I'll hold my AI takes for a bit, but I'll drop the hint here that I think AI has made this a lot easier. Not the maintaining the legacy codebase part, but the ramping your own knowledge up about it by just asking questions and having a thing that can go verify the like way it responds to it.

Steer a port by pointing at the original New

What it is
When an agent is rebuilding an app on another platform, fix bugs by telling it how the feature works in the existing version and asking it to copy that behavior.
Why Theo cares
While porting T3 Code mobile, this fixed almost everything. Only one or two bugs needed more, such as project selection for new threads.
How to try it
  1. When the new version misbehaves, describe how the old version handles that case.
  2. Tell the agent to mirror that behavior in the new code.
largely copied from. And from that I'm usually able to steer it in the right direction. I've only had one or two bugs where I couldn't just say here's how it works in the other place. Mirror that here and it wasn't enough to solve it.

Advice

Before you consider a rewrite, understand the existing code well enough to contribute to it. Theo says AI has not changed this.

like. You absolutely should have a good enough understanding of a codebase that you can contribute to it meaningfully before you even consider a rewrite. Even with agents, I don't think AI has changed this. I fundamentally believe a core understanding is essential if you want to have any chance at rewriting the

Hand tedious checking to automation whenever you can: compilers, type checkers, linters (tools that flag sloppy code) or AI. It frees your head for better decisions.

types of wins are awesome and you should take them whenever you can. If you can free up your brain space in things that can be automated in some way, whether that is a compiler, a type checker, a llinter, an artificial intelligence

When you join a large existing codebase, go in knowing you can't know everything. Theo says expecting to know everything is one of the things he sees new developers struggle with most at their first job.

lot of people uncomfortable. It's actually one of the things that I see new devs struggle with the most when they get their first job. They go from working in code bases where they wrote every line of code and they know whereIt's way harder to jump into something like that if you expect to know everything. So go in knowing you can't.

Hot takes

If you fully understand all the code in your projects, you are probably not working on anything important.

His reasoning: The code that matters most, like operating systems, major platforms and Postgres (a widely used database), is understood in full by nobody.

I got a hot take for you guys. If you truly fully understand all of the code in the projects that you're working on, you're probably not working on things that are that important or serious. Thelike Postgress itself. Nobody understands all of the code in these things. And I feel like we pretend

Most people who come in wanting to rewrite a project are more like a guy who plugged his own Rust rewrite without understanding the original than like someone who actually understood the codebase.

His reasoning: His example: someone sent a Gemini-generated rant calling T3 Code, VS Code and Cursor doomed, then plugged his own Rust alternative built with no understanding of what it replaced. Theo says people like this make informed rewriters look worse.

you can guess what he did at the end. He plugged his own absolute slop alternative that was written in Rust with no understanding whatsoever about what he was replacing and what theproblems were. This is the average rewriter. Most people who come in, they're like, "We're gonna rewrite this and make it way better." Feel more like the Gemini guy than somebody who actually understood the codebase. And it

What feels like real engineering and what actually earns engineers their pay barely overlap.

His reasoning: He says engineers who want to feel good about their craft drift toward perfect, self-contained work. That drives much of the nasty online arguing.

opposite sides. And it's really strange that the stuff that we think makes us a good engineer and the stuff that actually puts money on the table to get us paid have almost no overlap whatsoever. And a lot of this results in

If you cannot work with your team and users to solve real problems, you are worse than an AI model now.

work with other people. If not, then your LLM is better at engineering than you are. If you cannot work with your team and your users to solve real problems for people, you're worse than an LM now. Period. Do want to call out

How Theo thought about this

He almost entirely agreed with Sean but would word it differently than 'partial understanding': the depth of your understanding should change depending on where you are. Know roughly how the big pieces fit together before changing your own section, without expecting to know every piece's inner workings.

do. I almost entirely agree here. I wouldn't necessarily word it this way as a partial understanding rather like the depth of your understanding should change depending on where you are. I think you should generally understand how the pieces come together in a big code base before you make changes inyour isolated section. Like you should know what is where to some extent, but you obviously cannot understand the inner workings of the pieces. We'll see

He judges whether a rewrite is sensible by whether behavior can be verified. Compilers have clear inputs and outputs, so tough end-to-end tests can catch breakage, which is why Bun's Rust rewrite could make sense. User-facing products don't allow that.

million. Again, yes, compilers are easier here because you have verifiable inputs and outputs. So you can make some pretty brutal endto-end tests that will guarantee in most cases things are handled. This is a big part of why the bun rewrite in Rust could make sense as well. But for things that face users,

Sign in to mark what you've watched and keep notes.

Have a question about this one? Ask about this video →

Theo Daily is unofficial and not affiliated with Theo or t3.gg. Written by Claude Opus 5.5 from each video's transcript.