Theo reads Sean Goedecke's essay live and argues that in any codebase big enough to matter, nobody, including you, fully understands it.
Posted
today
Duration
Format
Reaction
educational
Views
101.7K
1.7K likes
57 · 43
Big Idea
The argument in one line.
In codebases large enough to matter, nobody, not even the best engineers, fully understands the code, so the real skill is building a workable partial theory and acting on it with confidence rather than chasing total knowledge.
Who This Is For
Read if. Skip if.
READ IF YOU ARE…
A developer on a large, high-turnover codebase who feels guilty for not knowing where everything is.
An engineer trying to decide whether AI coding tools are eroding or freeing up their understanding of their own code.
Someone weighing whether to push for a full rewrite of a legacy system.
A senior engineer looking for language to explain why partial understanding isn't a moral failure.
SKIP IF…
You work solo on a small side project where full understanding of the code is realistic and expected.
You want a hands-on tutorial about a specific coding technique. This is a mindset and career-philosophy video, not a how-to.
TL;DR
The full version, fast.
Nobody, not even the best engineers, fully understands the codebases that matter most: operating systems, GCC, or systems at companies like Twitch and Amazon. Reacting live to Sean Goedecke's essay 'In Defense of Not Understanding Your Codebase,' Theo argues that in sufficiently large systems, everyone operates with an incorrect theory of the program, and that's fine. Full rewrites fail because irreproducible edge cases live in the running system, not the code, so a lost team can't just start over. Tools like TypeScript, and now AI agents, let you offload pieces of that understanding so your brain is free for higher-level judgment. The skill worth building isn't total knowledge, it's a strong intuition for where things belong and the confidence to make an educated guess and live with the consequences.
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.
The hot take that opens the video: the codebases that matter most (operating systems, platforms, Postgres) are never fully understood by anyone, and the industry's myth of the super-genius who knows the whole codebase is false.
02:24 – 03:58
02 · Sponsor break: Depot
Depot CLI sponsor read: shared Docker build caching, faster CI, and a one-command way to run Claude Code in an isolated remote sandbox via 'depot claude'.
03:59 – 08:31
03 · Reading Sean's core argument
Theo reads Sean Goedecke's essay: engineers on small, low-turnover codebases assume full understanding is required; engineers on large, high-turnover codebases know it isn't. Theo backs the second group, then reads Sean's rebuttal of Peter Naur's 'Programming as Theory Building', which claims a program with no living 'theory' should be scrapped and rebuilt from scratch.
08:32 – 13:54
04 · Why full rewrites fail
Two reasons a from-scratch rewrite doesn't work: large systems accumulate irreproducible quirks and edge cases (the XKCD-style spacebar-heating joke), and abandoned systems get revived all the time by rebuilding understanding one flow at a time. Theo goes on a tangent about a DM from someone who used a hallucinated Gemini rant to justify rewriting T3 Chat, VS Code, and Cursor in Rust without understanding what he was replacing.
13:55 – 19:28
05 · Everyone operates on an incorrect theory
The video's central line: in sufficiently large codebases everyone works with an incorrect theory of the program. Theo tells a story about a senior Twitch engineer who didn't know he had to run the GraphQL codegen command, then explains how TypeScript freed his brain from manually checking types, and why compilers are rewritable (verifiable tests) while user-facing products aren't.
19:28 – 21:43
06 · Theory building is one tradeoff among many
Sean's list of ordinary things that already erode a complete theory of the codebase, other people writing code, legal compliance, turnover, security patches, dependencies, none of which are considered bad. LLMs get filed under the same tradeoff, not singled out as uniquely corrosive.
21:44 – 24:23
07 · Pure vs. impure engineering
Sean's framework: pure engineers chase a perfect technical solution (open source, game engines); impure engineers solve a real business problem efficiently (most paid work). Theo says the contradiction, that what feels like 'real engineering' and what actually earns money rarely overlap, explains a lot of bad Twitter arguments.
24:23 – 26:31
08 · Reading the comment section
Theo reacts to Lobsters and Hacker News comments on Sean's post, including a dismissive one calling Sean's writing 'vocabulary explainers.' Theo pushes back hard, arguing that knowing what your tech leads and managers are talking about is a real, non-controversial engineering skill.
26:31 – 28:36
09 · AI at 10,000x scale, and closing
Theo reads a tweet arguing AI-generated code volume will make full understanding impossible and hands-off vibe coding the default, then shares his own experience rewriting the T3 Chat mobile app in SwiftUI without reading a single line of the original code, steering it entirely from intuition built elsewhere in the codebase.
Atomic Insights
Lines worth screenshotting.
If you fully understand every line of the codebase you work in, you're probably not working on anything that matters much.
Nobody, not even the best engineers at companies like Twitch or Amazon, understands 100% of a codebase with hundreds of millions of lines.
What separates good engineers isn't memorizing every file, it's a strong intuition for where things belong in a well-architected system.
A good codebase isn't one where everyone knows where everything is, it's one where that doesn't matter because anyone can find the right place quickly.
AI coding agents represent 100% team turnover on every single new thread, since each new conversation starts with zero memory of what came before.
You can't rebuild a large software system from scratch because it accumulates thousands of undocumented quirks and edge cases that only the running system remembers.
A successful rewrite never replaces the old system in one move, it carves the old codebase into small chunks and rewrites one chunk at a time.
In sufficiently large codebases, everyone operates with an incorrect theory of the program, and being effective means acting anyway with grit and confidence.
TypeScript's real value isn't catching bugs, it's freeing up the brain space you used to spend manually checking types, so you can make bigger decisions faster.
Rewriting a compiler is realistic because its inputs and outputs are verifiable with tests, rewriting a user-facing product is not, because you can't test that a user's expectations still hold.
Every choice that erodes your perfect mental model of the code, like new hires, security patches, or dependencies, isn't automatically bad, maintaining a theory of the codebase is just one value traded off against others.
Pure engineers want an accurate mental model because it feels like real engineering, but impure engineers who solve real business problems efficiently are the ones companies actually pay for.
The contradiction fueling most bad engineering arguments online is that what makes you feel like a good engineer and what makes you valuable to a business have almost no overlap.
As AI multiplies how much code gets written, codebases will get too large for anyone to hold in their head, making largely hands-off vibe coding the likely default.
You can rewrite a system in a new stack without reading a single line of the old code, if your intuition about failure modes and data flow comes from having worked in the broader system.
Takeaway
Partial understanding isn't a failure, it's how big systems actually get worked on.
WHAT TO LEARN
In any codebase large enough to matter, nobody has a complete mental model, so the transferable skill is building a workable partial theory and acting on it with confidence.
01Nobody understands the important codebases
The bigger and more important a codebase is, the less likely anyone fully understands it, so stop treating partial understanding as a personal failure.
A good codebase design makes full understanding unnecessary, because anyone can find the right place for something quickly without knowing everything else.
03Reading Sean's core argument
AI coding agents are effectively 100% team turnover on every new thread, so set up your codebase to onboard a knowledgeable-but-amnesiac developer every single session.
A team that loses its shared understanding of a program can't just fall back on the code itself to rebuild that understanding overnight.
04Why full rewrites fail
Large systems accumulate irreproducible edge cases and quirks that live only in the running system, which is why full from-scratch rewrites almost always fail.
A rewrite that actually works starts by working inside the existing system first, then carves it into small chunks and replaces one chunk at a time.
Be skeptical of a rewrite pitch that isn't grounded in first understanding why the original system is slow or broken.
05Everyone operates on an incorrect theory
Everyone in a big enough codebase operates on an incorrect theory of the program, so being effective means taking a confident, educated guess instead of waiting for certainty.
Tools like TypeScript, linters, and AI checks aren't a threat to your understanding, they free up brain space you were spending on tedious manual checks so you can make bigger decisions.
You can only realistically test a full rewrite end-to-end when the inputs and outputs are verifiable, like a compiler, not when real users' expectations are the spec.
06Theory building is one tradeoff among many
Anything that erodes a perfect mental model of your code, new hires, security patches, dependencies, compliance requirements, isn't automatically bad, it's a normal tradeoff against other values.
LLMs aren't a uniquely dangerous threat to code understanding, they're one more item on a list of ordinary things that already limit it.
07Pure vs. impure engineering
Notice the gap between the engineering work that feels prestigious (a perfect mental model) and the work that actually gets you paid (shipping a real business outcome efficiently).
Most side-project and open-source work exists precisely because it lets engineers chase the 'pure' understanding their day job can't afford to prioritize.
09AI at 10,000x scale, and closing
You can rewrite a system in an unfamiliar stack without reading the old code line by line, as long as your intuition about failure modes and data flow comes from having worked in the broader system.
As AI multiplies how much code gets written, expect codebases to outgrow anyone's ability to hold them in their head, making hands-off, judgment-driven workflows the norm rather than the exception.
Glossary
Terms worth knowing.
Theory of the program
An engineer's intuitive mental model of how and why a system works, which can only ever be partially captured by the code or its documentation.
Programming as Theory Building
Peter Naur's 1985 paper arguing that the real product of programming is the programmer's mental theory of the system, not the code itself.
Pure engineering
Work focused on solving a technical problem as perfectly as possible, common in open-source projects, valued for craft rather than business payoff.
Impure engineering
Work focused on solving a real-world business problem as efficiently as possible, the kind of work most paid engineering jobs actually require.
Vibe coding
Building software by directing an AI coding agent through natural-language instructions with little or no manual reading of the generated code.
03:59linkSean Goedecke - 'In Defense of Not Understanding Your Codebase'
09:45linkPeter Naur - 'Programming as Theory Building'
21:44linkSean Goedecke - 'Pure and Impure Software Engineering'
18:23linkSean Goedecke - 'Nobody Knows How Large Software Projects Work'
Quotables
Lines you could clip.
13:55
“In sufficiently large codebases, everybody operates with an incorrect theory of the program.”
the single banger line of the whole video, quotable standalone with zero setup→ TikTok hook↗ Tweet quote
26:02
“If you cannot work with your team and your users to solve real problems for people, you're worse than an LLM now.”
blunt callout that lands without context→ IG reel cold open↗ Tweet quote
09:30
“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.”
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.
17px
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 code base 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 technologies and frameworks and libraries we use, things like Postgres 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 code base always. And those people feel like they exist. But I'm going to be real with you.
They don't. 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, 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 code base.
And importantly, as less familiar people work in that code base too. A good code base is not one where every single person at the company knows where everything is. A good code base 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 this today because of another Sean article. I've loved everything he has written so far, and I have a feeling I'm going to 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, 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. There are even more where I don't understand jack fucking shit. 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 taboo topic where it comes up a lot, but the conversation we have isn't actually about the thing. 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.
I'm spending half the time waiting for Docker to build. 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. Depot's here to solve all of those problems from where you run your agent.
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.
So everyone gets way faster builds across all platforms. And when I say way faster, I mean it up to 40 times faster for real world Docker builds. That's why companies like PostHog, PlanetScale, 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. 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. If you've been annoyed with your Docker build times or struggling to find a place to run your agents, look no further than soydiv .link slash depot.
I really love how Sean opened this here in defense of not understanding your code base with a good question to start too. As a software engineer, how well do you have to understand your own code base? This seems like a simple question, like every dev should understand their code base.
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 Redis 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 that people who work on large codebases with high turnover teams, like the Google Web Search backend or GitHub itself, would say, obviously, you can't understand it completely. 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 overrepresented 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. 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. 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 Sean goes with this. Against programming as theory building.
Oh boy. The best articulation of the quote, you have to understand your code base side is Peter Knorr's famous paper, Programming as Theory Building. I like this paper, but I think it goes too far in that direction.
Knorr'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 producing. But apparently it's a level the other direction. 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. This will 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.
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 code bases for agents, you already know this.
There is no magic solution where everything you need to know about the code base can be written as prose and 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 code base, just your general experience, but is also tuned to the specific code base 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.
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 fun challenge in a way.
And it's a 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 code base yet, be able to act in meaningful ways as effectively as possible. It's like a fun, rewarding thing.
Apparently, Sean agrees with what Norris 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. Re -establishing the theory of a program merely from the docs is strictly impossible. Therefore, the existing program text should be discarded and the new form programmer team should be given the opportunity to solve the given problem afresh.
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 stuff. This is not realistic, but okay. Well, I'll put my AI spin on this in a little bit.
Let's keep reading for now. Sean says that anyone who's been an effective software engineer at a large company knows that Knorr is dead wrong about this. There's at least two reasons why.
First off, you simply can't rebuild large software systems from scratch. Sufficiently large systems, if they have users, contain thousands of weird cases and quirks that cannot be re -implemented. Even a team that's intimately familiar with the system couldn't do it.
There's just too much stuff to juggle. I'm going to guess that the weird cases is an XKCD link to the spacebar thing. Am I right?
No, I am not. Ooh, 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 SaaS 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 may not be on this video. Changes in version 10 .17.
The CPU no longer overheats when you hold down the spacebar. 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 re -enable the spacebar heating. 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 code base. 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.
I love the callout Sean has here, that a successful rewrite always starts by carving out the existing code base 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. Absolutely true. I am the person who often comes in is like, no, fuck this rewrite.
But even then, if like you can't change the existing code base, I'm hesitant. When I'm coming in to do this type of rewrite, I almost always start by working on the existing code base for a bit to get a feel for what is and isn't working, what does and doesn't matter, how the team works, what they like and don't like. You absolutely should have a good enough understanding of a code base 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.
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. 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. And it was a hallucinated slop Gemini 3 .1 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 Codex or Cloud Code in the Electron app would result in a new Electron app spawning. which is just so hilarious and fundamentally wrong. And you can guess what he did at the end.
He plugged his own absolute shit 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 going to rewrite this and make it way better, feel more like the Gemini guy than somebody who actually understood the code base.
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 dumbasses 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 programmers should just rewrite everything.
Abandoned systems are revived all the time. And a tech company with hundreds of millions of lines of code and thousands of engineers, it's not uncommon for a code base 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 code base 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. It takes time, but building a new theory of the code base 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 code base part, but the ramping your own knowledge up about it by just asking questions and having a thing that can go verify the way it responds to it. 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 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 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.
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.
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 and some complaints like trying to get help fixing it.
And then everybody was debugging, assuming something was deeper and broken because this is one of the smartest people at the company. 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 and I think he deleted the original thread. But like, 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 stop you from actually getting shit 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 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 pass 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 code base less, that I'm not deeply introspecting every time I call a function to make sure it expects exactly what I'm passing it. But on the other hand, I am now so unburdened 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 linter, an artificial intelligence coming in and checking, anything you can do to free your brain of the tedious bullshit and the details is probably not 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 shit. 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 code base this big. 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 code base that existed before they even started writing code. 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. Nobody understands it 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 Sean 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.
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 Programming, 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 Noor writes about a large program, he's not talking about tens of millions of lines of code. Noor's first example of a large program is a 200 ,000 line industrial monitoring program.
And his second example is a compiler. In 1987, the first version of the compiler GCC was about 100 ,000 lines of code. Now in 2015, GCC is over 14 million lines.
i can believe that rewriting one or two hundred thousand lines of code is relatively straightforward particularly if you get to reuse existing tests not so for one or two million again yes compilers are easier here because you have verifiable inputs and outputs so you can make some pretty brutal end -to -end tests that will guarantee in most cases things are handled this is a big part of why the bun rewrite and 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 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.
LLMs 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, LLMs 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 Sean is still thinking about. I will say that I am as well.
Setting LLMs 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 code base. One, other people being allowed to write code in your code base.
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. But I hope we would all agree that these things, despite affecting your understanding of your code base, are obviously not bad. Like most things in software, maintaining a theory of the code base 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 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 code base 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. Why high profile externer 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. Those types of things are pure. And then impure 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 raises up because he says that almost all engineers, particularly pure engineers, prefer to maintain an accurate mental model of their software. 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 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 types of pure engineering things and they will shit all over the devs on the other side i like this framing here We all want to be pure engineers, but since some are and some aren't, the conversation often erodes to bullshit.
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. In order to do engineering work where they can maintain an accurate neural theory of their code base, 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.
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. 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.
The music of the post got tagged as vibe coding because of one short, simple paragraph mentioning LLMs a bit. 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. Sean wanted to fill another niche.
Another comment offers the second comparison of him with Seth Gooden that he's seen. Godek doesn't quite write the adenine sound bites that Seth Godin 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 am incredibly confident that whoever wrote this comment doesn't have a job. 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 because 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.
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 LLM now.
Period. I 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 ,000x's the amount of code? Codebases are going to be so large, it will be even more impossible.
Therefore, vibe coding fully hands -off will be the default. Everyone who 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, and React Native over to SwiftUI, and I have not read a single line of the code. 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. 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 this isolated thing that is 60 ,000 plus lines of Swift slop that I haven't read a single line of.
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. Like in the description if you want to check out his other posts.
all really good this is a fun one for me because on one hand i understand my code base is 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 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.
The Hook
The bait, then the rug-pull.
Theo opens with a hot take: the bigger and more important a codebase is, the less likely anyone, including you, actually understands all of it. He spends the next 28 minutes reading Sean Goedecke's essay live and defending the engineers who've made peace with that.
Frameworks
Named ideas worth stealing.
08:32list
Two reasons full rewrites fail
Large systems accumulate irreproducible quirks and edge cases no one can fully re-implement
Abandoned systems get revived all the time, so 'nobody understands it' isn't a reason to scrap it
Sean Goedecke's rebuttal to Peter Naur's claim that a lost 'theory of the program' means the code should be discarded and rebuilt from scratch.
Steal forany internal argument for or against a full rewrite proposal
21:44model
Pure vs. impure engineering
Pure engineering: solving a technical problem as perfectly as possible
Impure engineering: solving a real-world business problem as efficiently as possible
Explains why solo game devs, open-source purists, and big-tech engineers clash, and why some engineers love AI-assisted work while others resent it.
Steal fordiagnosing why an engineering disagreement on a team keeps going in circles
CTA Breakdown
How they asked for the click.
VERBAL ASK
28:11next-video
“Like in the description if you want to check out his other posts.”
Soft, single-line nod to the essay's author at the very end rather than a hard subscribe pitch.
Add Modern Creator as a preferred source and Google shows you more of our breakdowns in Search, Top Stories, and AI Overviews. It only changes what you see, and you can undo it in your Google settings anytime.
Add to Preferred SourcesOpens your Google source preferences with us pre-loaded. Tick the box and you're done.
A developer who shipped 89 merged PRs in 24 hours breaks down Claude Fable 5.1's pricing, benchmarks and real-world coding behavior against Fable 5 and GPT-5.6 Sol.
Boris Cherny said coding is solved. Matt Pocock called it VC-funded bullshit. Theo argues they're both right, because they're using the word coding to mean two different things.
Theo spends a week testing two rival "skills" repos for AI coding agents, Matt Pocock's 215,000-star collection and Cursor engineer Lauren's PStack, and finds the real value in a handful of specific files, not the whole install.
Theo reacts line-by-line to Boris Cherny's post arguing that automation — CLAUDE.md rules, lint checks, CI — matters more than ever in the agent era, not less.
Theo runs OpenAI's GPT-5.6-Sol through Claude Code instead of Codex and gets visibly better designs and cheaper orchestration — then reads Codex's system prompt on camera to find out why.
00:32
00:53
01:15
01:36
01:57
02:19
02:40
03:23
03:45
03:58
04:49
05:11
05:32
05:53
06:15
06:36
06:58
07:19
07:41
08:02
08:45
09:06
09:30
09:52
10:11
10:32
10:54
11:15
11:37
11:58
12:20
12:41
13:02
13:24
13:45
14:28
14:50
15:11
15:33
15:54
16:15
16:37
16:58
17:20
17:41
18:03
18:24
18:46
19:07
19:50
20:11
20:33
20:54
21:37
21:59
22:20
22:42
23:03
23:24
23:46
24:29
24:50
25:12
25:33
25:55
26:17
26:38
27:20
27:42
27:54
28:25
55:06
33:48
38:21
19:12
30:48
30:09