Stop Pretending You Understand Your Codebase Transcript, AI Summary & Key Points

00:00 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. The bigger the codebase and the more important the work you're doing is, the less likely it is that you understand everything going on in it. Realistically speaking, the code bases that matter the most, the ones that power things like the operating systems we use or the platforms that we go to every day or even the foundational

00:24 technologies and frameworks and libraries we use, things like Postgress itself. Nobody understands all of the code in these things. And I feel like we pretend that's not the case. As an industry, we've always liked to think of the best programmers as these super geniuses that know exactly where everything is in the codebase always. And those people feel like they exist, but I'm going to be real with you, they don't.

00:46 What they have is different. What they have is a good intuition for where things would go. And it's not just based on memorizing where every single file is and every line of code that's in it. It comes from a higher level understanding of how good software is architected and where things should go. And with that comes certain patterns that make those developers better.

01:05 Moving things around to get stuff where it should be to make it easier to make good decisions about it as you work in this codebase. And importantly, as less familiar people 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.

01:23 What matters is that people can find the right place for something relatively quickly. I'm talking about this today because of another Shan article. I've loved everything he has written so far and I have a feeling I'm gonna love this one too. I'm guessing as to why he wrote this. My assumption would be that this came out because of people vibe coding so hard they don't know where anything is anymore.

01:42 And I'm not here to defend that. All of that said, I do have a very different relationship with my code bases than I did in the past. And my awareness of where things are in them and the actual code going in is a spectrum now that is wider than it's ever been. There are some places where I feel like I understand better than ever what's going on. But I'll be realistic here.

02:01 There are even more where I don't understand jack [ __ ] [ __ ] And I'm going to do my best to defend that, to defend the code bases where I have no idea what's going on or where anything is. And I'm going to read along with this article as we do it. I am so excited for this discussion because I feel like it's a a taboo topic where it comes up a lot, but the conversation we have isn't actually about the thing.

02:23 And I want to go into the details on how we actually use our brains to understand code. But I have to borrow your brain for a sec for a quick message from today's sponsor. Recently, I feel like my whole life is just managing servers. If I'm trying to work in parallel, I have to go spin up a bunch of boxes that can run my code. And I'm spending half the time waiting for Docker to build.

02:40 And once I have those changes ready to go, I push them up to GitHub. And now I'm sitting there waiting for the code to actually build. And it's just pulling the same code and building the same thing with one or two lines change. Okay, maybe a couple hundred. We're using agents, let's be real. But the amount of time I'm wasting just sitting there is so obnoxious that I was really thankful when I moved over to today's sponsor.

02:58 Debo's here to solve all of those problems. From where you run your agents to where your CI runs to how you're actually building from Docker in the first place. The depot CLI solves all of these problems and more. It makes it trivial to share your Docker builds and all the layers across depot's cache. Not just for you, but for your CI and for your team, too.

03:14 So, everyone gets way faster builds across all platforms. And when I say way faster, I mean it. up to 40 times faster for realworld Docker builds. That's why companies like Post Hog, Planet, Scale, Inference, and more have all made the move over. It's just so much faster for those Docker builds. Their CI is way faster, too. But what I want to talk about right now is the remote agents stuff.

03:33 Once you have their CLI set up and it has your Docker image, all of a sudden, you can just run Claude in it. You literally just run depot Claude instead of calling Claude directly. And now you have a real isolated sandbox you can get real work done in. Considering all the time I've put into managing all of my machines in order to get something similar, one command is very, very tempting.

03:51 If you've been annoyed with your Docker build times or struggling to find a place to run your agents, look no further than soy. I really love how Shawn opened this here in defense of not understanding your codebase with a good question to start, too. As a software engineer, how well do you have to understand your own codebase? This seems like a simple question, like every dev should understand their codebase.

04:10 No, not that simple at all. Let's read to see what Sean has to say. My guess is that people who work on small code bases with low turnover teams, things like a library like Reddus or a game like The Witness would probably say obviously you have to understand it completely otherwise you can't do good work. I'd also guess the people who work on large code bases with high turnover teams like the Google web search backend or GitHub itself would say obviously you can't understand it completely.

04:37 You just have to do the best you can in your local area. These are two largely different ways of programming with different methods, practices, and cultures. However, the first group is over represented in online discussions about software engineering. Woof, coming in swinging, Sean. Thank you. I want to defend the second group against the first. In many software engineering environments, there's nothing wrong with being in a state of partial understanding.

05:01 In fact, in large systems, a partial understanding is the best that you can 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 in your isolated section.

05:25 Like you should know what is where to some extent, but you obviously cannot understand the inner workings of the pieces. We'll see where Shawn goes with this. Against programming as theorybuilding. Oh boy. The best articulation of the quote, you have to understand your codebase side is Peter No's famous paper, Programming is theory building. I like this paper, but I think it goes too far in that direction.

05:49 Nar's core point is that when programmers work on a program, the code is really just a byproduct, and the main product they're working on is their theory of the program. Interesting. I was assuming they were going to say the code is a byproduct and the product is the thing that they're actually like producing, but what apparently it's a level the other direction.

06:07 There's the theory of the code, then there's the code, then there's the product on top. Seems like the theory building paper is pushing you the wrong direction in my opinion. So, it'll be interesting to see where this goes. Theory of programming is made up of their intuitive sense of what's happening and why, which can only be partially captured by code or documentation.

06:26 Woof, more bangers. It is basically impossible to just write down how all of these things work. If you've tried to set up your codebases for agents, you already know this. There is no magic solution where everything you need to know about the codebase can be written as pros in code. There's a certain level of intuition you build as you work in the project about where things fail, why they might fail, what's going on, all these types of things that is historical outside of that codebase, just your general experience,

06:52 but is also tuned to the specific codebase after you spend a lot of time in it. If a developer loses the code, they could rewrite the program easily. If they lose their understanding, like if the team experienced a complete turnover, they would struggle to make sense of the code. Very true here. The important thing here 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.

07:17 It's like you're starting with a fresh developer every time you open a new thread. And that is awesome if you set things up for those agents to perform well without having this historical knowledge. But it's a it's a fun 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.

07:46 It's like a fun rewarding thing. Apparently Shawn agrees with what Nor has said so far, but he goes further than what has been said. He says the theory should not be reconstructed from the code. According to Nor, you're better off scrapping the program entirely and having a new team rebuild from scratch, building up a new theory in the process. Interesting.

08:06 Reestablishing the theory of a program merely from the docs is strictly impossible. Therefore, the existing program tech should be discarded and the new formed programmer team should be given the opportunity to solve the given problem. of huh I could be convinced there are lots of places where you cannot do this and this is what I think Sean's going to say is that large enough this is not realist I'll put my AI spin on this in a little bit for now Sean says that anyone who's been an effective software engineer at a

08:35 large company knows that no is dead wrong about this at least two reasons why you simply can't rebuild large software systems from scratch sufficiently large systems if they have users contain thousands of weird weird cases and quirks that cannot be reimplemented. Even a team that's intimately familiar with the system couldn't do it. There's just too much stuff to juggle.

08:54 I'm going to guess that the weird cases is an XKCD link to the space bar thing. Am I right? No, I am not. This wicked features article actually looks great as well. things that seem good as ideas but end up making life hell over time like new user types making sure that your SAS can be done on prem if you want to provide that sharding across many databases supporting strong data locality oh god data locality hurts me so deeply internationalization thankfully has gotten easier thanks to a sponsor that may or not be on

09:28 this video changes in version 10.17 the CPU no longer overheats when you hold down the space bar comment Longtime user 4 writes, "This update broke my workflow. My control key is hard to reach, so I hold spacebar instead, and I configured Emacs to interpret a rapid temperature rise as control. That's horrifying. Look, my setup works for me. Just add an option to reenable the spacebar heating."

09:52 Absolute classic. I bring it up here because the things in the system that might not be intended, the quirks of how it works and the patches that have been added to make something work for some random specific user, those things are wired deeply in the codebase. And if the person who understood those things is no longer there, it is very unlikely that you successfully replicate them in a fresh rewrite.

10:15 I love the call out Sean has here that a successful rewrite always starts by carving out the existing codebase into small isolated chunks then rewriting one chunk at a time. In other words, rewriting a software system involves making a bunch of changes to the old system. You can't change the old system. You certainly can't replace it with a new one.

10:33 Absolutely true. I am the person who often comes in as like no [ __ ] this rewrite. But even then, if like you can't change the existing codebase, I'm hesitant. When I'm coming in to do this type of rewrite, I almost always start by working on the existing codebase for a bit to get a feel for what is and isn't working, what doesn't matter, how the team works, what they like and don't like.

10:54 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 thing. Which is why when people come up to me and they're like, "Yo, I rewrote this thing in Rust."

11:14 And I'm like, "Okay, what did you do to try and fix the original first?" And they're like, "Oh, I just thought it was slow, so I rewrote it." So, I got I I've been trying to not crash out about a specific DM I got a few days ago that I read and I shouldn't have. I was curious because this individual sent me a Gemini chat share link to justify their thoughts about why T3 Code, VS Code, and Cursor were all doomed projects that had fundamental performance issues that would never be addressed.

11:41 And it was a hallucinated slop Gemini 31 Pro rant about Electron being theoretically bad if you open hundreds of Electron instances at the same time. He seemed to think that every thread you use in something like Codeex or Claude Code in the Electron app would result in a new Electron app spawning, which is just so hilarious and fundamentally wrong.

12:04 And 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 the problems 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.

12:25 And it sucks because they make people who know what they're doing that want to come in and rewrite because it makes sense to look worse because we get grouped in with these dumb asses that have no idea what they're doing. Anyways, let's go to the second reason why he doesn't agree with this statement that the new programmer should just rewrite everything.

12:44 Abandoned systems are revived all the time. In a tech company with hundreds of millions of lines of code and thousands of engineers, it's not uncommon for a codebase to have nobody left who's familiar with it. All it takes is a few people to quit at the wrong time, or for a codebase to be unmaintained for a year. Not only have I seen other teams do it, I've personally taken ownership of abandoned code bases, figured them out, and gotten to a point where I could effectively work with them.

13:09 It takes time, but building a new theory of the codebase is possible. You start by understanding one flow end to end and then you slowly branch out from there making careful changes as you go. 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.

13:38 It might not have all the historical knowledge that the previous developers did, but it has their outputs, which is often enough to carry you to a good point. Oh boy, now we're getting to more banger statements. In sufficiently large code bases, everybody operates with an incorrect theory of the program. Woo! Banger. Entirely true. Some of the best engineers I have known working in really big code bases had almost laughable misunderstandings of it that were really funny to me.

14:05 One of my favorites that I think about a lot is one of like the best full stack devs I ever worked with. The guy who like got me into Alexa and ramped me up quickly at the start of my career hit me up three-ish years later when we were still both working at Twitch. Actually, I think I hit him up because he messaged one of the shared group chats for the Twitch web app because he was getting type errors when he was trying to query data on the client.

14:27 At this point in time, he had worked a lot with the back end and the front end and built full stack stuff. But for whatever reason, he had never had to define a new query on the back end and then call it on the front end. And this would require you to run a generation command that would pull the latest schema down from the GraphQL server and then create the TypeScript definitions that were needed inside of the React code in order to call it type safe.

14:52 Somehow despite touching everything across these systems, he had never had to do that step because he just never did both at the same time. And he was really really confused why he was getting type errors in code that he knew was valid on both sides and shared a screenshot of it breaking in some complaints like trying to get help fixing it. And everybody was debugging assuming something was deeper and broken because this is one of the smartest people at the company.

15:14 I'm scared to embarrass him. So I DM him, "Yo, did you run the GraphQL gen command?" He was like, "Wait, what?" Oh yeah. I don't know how I thought the types would get to the client code, but I guess that that does need something, huh? Just ran the command all is good. And then he went I think he deleted the original thread. But like everybody in order to be highly effective, you can't know everything because the effort it takes to learn everything and the amount of your brain it takes to know everything is going to

15:41 stop you from actually getting [ __ ] done. This is actually one of the reasons I used to pitch Typescript so hard. A lot of the initial friction people were concerned about with Typescript is that it's more to learn and know and that it will take up more space in your brain. For me, it was the opposite. Since Typescript will correct you when you make small typo mistakes, when you don't use the right type for a thing, when you pass a string to a function that expects a number, it means you don't have to think about

16:07 those things yourself. And when I got more into TypeScript, I realized how much of my brain was previously stuck checking all of those things for me, making sure every time I call a function that I passed the right type. And once the type system could take that debt from me, my brain was freed of it. In some ways, that means I understand the codebase less, that I'm not deeply introspecting every time I call a function to make sure it expects exactly what I'm passing it.

16:30 But on the other hand, I'm now so unbburdened and so much of my brain has been freed that I can now make better changes more reliably and ship faster with less bugs. Those 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 coming in and checking, anything you can do to free your brain of the tedious [ __ ] and the details is probably not

17:00 positive as long as your overall understanding doesn't go down in the process. And this isn't just for people working on side projects and [ __ ] This is my experience working on hundreds of millions of lines of code code bases at a place like Twitch or Amazon. And it seems to line up with Sean's experience, too, because this is the real world. You cannot know everything about a codebase this big.

17:18 You have to learn to live without the details. And this makes a 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 where everything is because it's all within their control to a codebase that existed before they even started writing code.

17:36 It's way harder to jump into something like that if you expect to know everything. So go in knowing you can't. Back to what Sean was saying here. He just opened this paragraph saying that everybody operates with an incorrect theory of the program and big enough code bases. The defining feature of modern software systems is that they're just way too big for anyone or even a whole team to keep in their head.

17:56 Nobody understands at all. It's funny. He has another separate article from last year titled, "Nobody knows how large software projects work." Accurate. very accurate. To be effective, you have to figure out a way to work with a merely partially correct theory. This is why Shawn keeps going on about taking a position in confidence. If you're not sure about something, you can't just sit back and wait for someone with a perfect understanding to come and give you the answer.

18:19 You're a competent engineer. That person is you. You have to grit your teeth, make your most educated guess, and then deal with the consequences. All bars. To be generous to the author of what was it called again? the theory of program or programming is theory building paper. It's possible that in 1985 the average size of a program was several orders of magnitude smaller than today and that when Norah writes about a large program, he's not talking about tens of millions of lines of code.

18:46 Nor's first example of a large program is a 200,000line industrial monitoring program. And his second example is a compiler. In 1987, the first version of the compiler GCC was about a 100,000 lines of code. Now in 2015, GCTC is over 14 million lines. I can believe that rewriting one or 200,000 lines of code is relatively straightforward, particularly if you get to reuse existing tests.

19:11 Not so for one or 2 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, where users interact and expect certain behaviors and for their data to be formatted a certain way and to be accessible a certain way, those types of things, you're not going to be able to test

19:39 the end to end to make sure it is still the same for people. Just not realistic. Next major point, theory building is one trade-off among many. LMS are often cited as a tool that's bad because it impedes the ordinary process of theory building. Sean thinks that's overly simplistic. Like many software 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

20:06 effectively. This is a complex trade-off that Shawn is still thinking about. I will say that I am as well. Setting LMS aside, Sean's confident that it's silly to say that anything that interferes with your theory of software must be bad. Here's a partial list of other things that make it hard to maintain a complete theory of your codebase. One, other people being allowed to write code in your codebase.

20:27 Two, having to implement legally required features like accessibility and data protection. Three, allowing your colleagues to quit jobs or move between teams. Don't forget about vacations, by the way. Four, having to upgrade software versions for security patches. And five, bringing in any libraries or other dependencies. This is a great analysis. All of these things make your understanding of your program worse.

20:52 But I hope we would all agree that these things, despite affecting your understanding of your codebase, are obviously not bad. Like most things in software, maintaining a theory of the codebase is one value among many. Sometimes it's the most important value, and you'll sacrifice other values for it. Other times you trade it off for speed or legal compliance or for political reasons or because the features you want to add sometimes require you to make things more complex or like you have to support a platform like iOS

21:22 or Android which immediately massively blows the complexity of a project. All these types of things are worth doing even if they make your own understanding of the codebase worse. Next part cites pure and impure software engineering. This is an article from over a year ago that actually looks really good. He questions why solo game devs get in fights with big tech engineers so often.

21:42 Why high-profile external hires to large companies often fizzle out? Why is AI assisted development amazing for some engineers and useless for others? It's because different engineers do different types of work. He breaks this down as pure and impure where pure engineers are interested in solving technical problems as perfectly as possible. Open- source work for libraries trying to make the best HTTP request library or the perfect game engine.

22:06 Those types of things are pure. And then mure engineering is interested in solving a real world problem as efficiently as possible. Paid tech company work is like this. Engineers are asked to deliver some project or a feature as well as they can do it by the deadline. Absolutely. He brings it up because he says that almost all engineers, particularly pure engineers, prefer to maintain an accurate mental model of their software.

22:28 It's more fun, less stressful, and it feels more like quote real engineering. This is a contradiction I had never seen anyone else point out this well that I have felt deeply and never known how to word. And I'm very thankful for you, Sean, for putting this to words. There's this really strange contradiction in most of our brains, and I'm as guilty as anyone of this where the things that feel like real engineering that make you feel like your job's important and it matters and you have this deep understanding and the

22:50 things that bring real value as engineers, the things that make you actually worth employing and doing this for a living are almost 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 horrible conversations and a lot of shitty dialogue in places like Twitter because the people who want to feel good about their engineering will lean towards these

23:21 types of pure engineering things and they will [ __ ] all over the devs on the other side. I I like this framing here. We all want to be pure engineers, but since some are and some aren't, the conversation often erodess to [ __ ] He says that this desire is why many engineers take up open source projects in their spare time in order to work on small code bases by themselves.

23:42 In order to do engineering work where they can maintain an accurate nor theory of their codebase, they have to work on these small side things. Sean doesn't think there's anything wrong with that, and I agree. However, at work, you're paid to do a job. In other words, they pay you money to adopt their set of engineering values. It's hopefully well understood that however much you might personally care about performance, sometimes you have to write slow code at your job.

24:04 For example, if you have to get a project done on time or to accommodate some awkward requirements. Maintaining a theory of the code base is the same kind of thing. He has some stuff here about the comments he got in other places that I think is actually very good. First, he is annoyed at lobsters because this site and this board is admittedly quite cringe at times.

24:25 One interesting comment points out that the ability to reason locality about code with partial understanding has been a core goal of CS from the beginning. This is also a good description of what he was trying to get into in his previous article, how good engineers write bad code at big companies. It's amusing that the post got tagged as vibe coding because of one short simple paragraph mentioning LLM a bit.

24:44 He didn't tag it as AI and I agree with him. This is not a post about AI. This is reality. The hacker news comment pissed me off even more though. He said that the top comments are a genre that he expected, which is, "Wait, this situation sucks. Why isn't the blog post about how much this sucks?" Well, there's plenty of posts like that already. Shawn wanted to fill another niche.

25:05 Another comment offers a second comparison of him with Seth Guden that he's seen. God doesn't quite write the Adenine sound bites that Seth Goden does, but neither does he write anything of engineering use, just vocabulary explainers for people who want to know kind of what their tech leads and line managers are talking about. I I am incredibly confident that whoever wrote this comment doesn't have a job.

25:27 I I would bet a lot of money on it. I like Sean's response here, too. This comment is skewed by what people see of his work. for example, not the posts that discuss engineering topics cuz these ones aren't the ones that perform particularly well on HN. And second, and this is an important call out, he thinks that wanting to know what your tech leads and line managers are talking about is important.

25:48 Yeah, the person who gives you the work that you're doing should be understandable by you. You should know what your team is asking for. This isn't some crazy controversial thing that real engineers don't have to deal with. Real engineers know how to 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.

26:14 Period. Do want to call out one of the tweets he mentioned where people talked more about the article. This one from Nick is very good and I think points roughly where we're going. You can't keep an entire program in your head. So, what happens when AI 10,000xes the amount of code? code bases are going to be so large it will be even more impossible.

26:34 Therefore, vibe coding fully hands-off will be the default. Everyone says otherwise is wrong and human brains won't keep up. The engineer must learn to work with a mental labyrinth with only imperfect information. I'm getting a taste of this right now because I've been rewriting the T3 code mobile app in React Native over to Swift UI and I have not read a single line of the code.

26:53 My intuition on what it gets wrong comes from the failure cases I see when I'm using it and my understanding of how it works in the other system that it's 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.

27:14 It's actually kind of weird which cases this fails at. It's weird stuff like project selection for new threads. For 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 the different places, where it comes from, how it's sourced, what failure cases exist, all of that knowledge I've built through working on the rest of T3 code has applied and been super helpful in

27:44 this isolated thing that is 60,000 plus lines of Swift slop that I haven't read a single line of. So, absolutely agree here. This is where we're probably going. As always, thank you to Sean for writing yet another awesome article. This has quickly become one of my favorite blogs in all of software dev. I appreciate you a ton. Link in the description if you want to check out his other posts.

28:02 They're all really good. This is a fun one for me cuz on one hand, I understand my code bases better than ever. And on the other, I feel like I'm understanding them less and less, too. And finding that balance has been really fun for me. It's almost like being a new developer again in a lot of ways that are actually really rewarding and resulting in fun workflows that are shipping real software.

28:20 It's it's a fun time to be a dev. I know it's scary and stressful, but when you lean in a bit, the things you can do right now are so cool. And I hope that this way of thinking helps encourage you rather than discourage you about where we're all going as an industry. Let me know how y'all feel. And until next time, peace nerds.