I didn't go to a university for computer science. I have a B.Tech in Geophysics.
What I know about software, I built by reading. Documentation, source code, GitHub issues, changelogs, RFC threads that went nowhere, blog posts from 2014 that were half-wrong but made me think. No bootcamp. No structured curriculum. Just me, a browser, and the actual material.
When I was learning Cloudflare Workers, I didn't have a course. I had the Workers docs, the Wrangler changelog, and a broken deployment I had to debug at 1am. I read the binding configuration docs three times before I understood why my KV namespace wasn't resolving. I followed a GitHub issue thread from 2022 to understand a Wrangler behavior that was never in the official docs at all.
That's how I know what I know. Not from a summary. From sitting with the material until something clicked.
I'm watching that process disappear.
we're calling it productivity
The pattern I keep seeing: not "I read the docs and I'm confused about this section" but "give me the code for X." Not "I traced through the source and found this behavior" but "what does this function do."
Understanding is optional now. Just get the output.
We didn't just change how we find answers. We changed what we think the goal is. The goal used to be comprehension. Now it's output. And we're calling the shift efficiency.
It isn't. It's debt.
You can generate a working circuit breaker implementation without understanding what a half-open state is or why it exists. It works in your test environment. It fails in a specific edge case under load six weeks later, and you have nothing to reach for because you never built the mental model. You got the conclusion without the construction. The what without the why.
The why is the only part that matters.
Reading documentation builds a mental model through contact with the actual material — the tradeoffs the API design is managing, the edge cases in a footnote you almost skipped, the why behind the what. The confusion you feel reading a complex RFC is where the learning happens. Friction is where understanding gets built.
When I built Bookmark Brain — a RAG system on 55,000+ of my own X bookmarks — I had to actually understand how Cloudflare Vectorize works under the hood. Not just the API surface. The embedding dimensions, the index behavior, the query distance metrics and what they mean for retrieval quality. I read the HNSW paper. I read source-adjacent documentation. I sat with confusion long enough for it to become comprehension.
That comprehension is now load-bearing in production. If something breaks at 2am, I have a model to reach for.
If I had prompted my way to a working demo, I'd have a demo. I wouldn't have a system I can reason about.
the split already showing in codebases
Who still reads and who doesn't — that's the divide forming. Not senior vs junior, not experienced vs beginner.
It shows in code review. The developer who read the ORM documentation sees in thirty seconds why a query is going to cause N+1 issues. The developer who generated the code can't, because they never built the model that lets you see it.
It shows in architecture. The developer who read the Kafka docs actually understood consumer group behavior, partition assignment, offset management. When the system needs to scale, that developer has something to reach for. The one who learned Kafka from summaries has vocabulary but no structure underneath it.
It shows most brutally in debugging. Debugging is almost entirely a function of your mental model. Without one, you're just changing things and hoping.
AI cannot hold the architecture. It doesn't see the big picture across your codebase. I've watched an AI-generated caching layer get shipped clean, pass every test, and take down production three weeks later because nothing in the code — or in the person who merged it — understood what would happen when two requests raced to invalidate the same key. The human in the loop has to hold that. Which requires a mental model. Which comes from reading, not prompting.
what we're trading without noticing
I've watched developers ship auth systems they can't reason about. Caching layers they can't explain. Queue implementations that work until they don't, and when they don't, there's nothing to reach for except opening a new chat window.
That's not a tool problem. That's a reading problem.
Same tool, two developers. One uses it to understand — asks why the code works, what the tradeoffs are, what breaks under load. One uses it to avoid understanding — takes the output, ships it, moves on. Completely different results six months later when the system needs to change.
That's the line. Not whether you use AI. Whether you're using it to understand or to avoid understanding.
The developers I watch compound over time aren't moving fastest. They're the ones who still read. The actual changelog. The actual query planning documentation. The actual source when something doesn't make sense. They're building a compounding mental model that prompting cannot replicate.
The ones who stopped reading are building something too. API surface knowledge and output patterns, without structural understanding underneath. It doesn't show until the system needs to change.
for self-taught developers specifically
Documentation made self-taught viable. Open-source code you could read. Stack Overflow threads with timestamps, disagreements, edits that showed how understanding evolved. Blog posts from engineers explaining not just what they did but why.
That curriculum is still there. I still use it. I just don't know how many people coming up behind me are.
I built what I've built by reading things that confused me until they didn't. That's not a talent. It's a practice. One I watch developers trade away every day for the feeling of moving faster, without noticing that what they're trading is the actual skill.
The mental model you build from reading documentation at 1am, frustrated, reading the same section three times — that's not a tax on your productivity. That's the thing that makes you irreplaceable when the system breaks.
When you skip it, you skip the thinking. And you won't know you skipped it until you're in production with nothing to reach for.
AI helped me research, structure, and edit this piece. The arguments, the examples, and the opinions are mine. So is whatever's wrong with them.
Top comments (64)
Wholly agree, and that's why, in my opinion (and I've been beating this drum more than once lately ...) it's a false dichotomy to state (as I often see):
"with AI coding tools, it's less about memorizing syntax, and more about system thinking and architecture"
Taken at face value, this is true - there's not that much value in memorizing facts (syntax etc) for the sake of it - but I'm still calling "false dichotomy", because one doesn't develop "system thinking" or "architecture" skills in a vacuum - it's developed by being "hands on" ...
The 'old way', where we were craftsmen/women meticulously putting solutions together, was typically the way to develop those skills ...
So I'm kind of concerned that we're losing that "craft" aspect that formed the foundation for the higher level skills ...
So I'm just saying: keep writing some of the code (especially the more 'interesting' parts) yourself!
leob — that's the part I left implicit: "system thinking" isn't a separate skill that replaces syntax-level grinding, it's what that grinding turns into once your hands have done it enough times you stop consciously tracking it...
Exactly - that's what I meant with "false dichotomy" ... and purely the syntax is indeed the low-level (and less interesting) part, but understanding the minutiae of how an ORM works and how to apply its best practices, or (on a higher level) understanding the principles of HTTP, databases, concurrency - you can't really review what AI has generated, or spot its flaws, without the background knowledge or insight ...
(actually I might have to qualify that last part a bit, because nowadays there are AI code review tools which are pretty amazing - but for now, "human" checks are still valuable, or else we're just completely navigating on auto pilot)
Leo even the good AI review tools are pattern-matching against known failure shapes not against your specific production traffic at 2am; the checks that catch a subtle N+1 or a race condition usually come from someone who's been paged for one before.
I believe you, but the really good ones (at least the one(s) I know) seem to have an uncanny ability to "grok" your complete codebase, and to "understand" the relations between the various parts - AND to spot pretty subtle "edge cases", like race conditions, N+1 issues, security issues, and various "non happy path" scenarios - I was pretty heavily blown away by what it was capable of ...
But, obviously "it all depends" - YMMV, and like I said a "human" check is still very valuable ...
leo, grokking relations across a whole codebase is a genuine leap, no argument there. But spotting a race condition and understanding why it matters aren't the same move: one's pattern recognition over a wider context window, the other requires knowing what actually breaks, and for whom, when it fires.
When it flagged one, did it tell you which invariant would fail, or just that concurrent access existed?
Well, it makes suggestions (about potential issues), which can be correct, or incorrect - the final call regarding whether what the tool says makes sense or not is to the developer! But it's pretty detailed in its elaboration about why it thinks there might be an issue, so it's often a good starting point for further investigation ...
My take on it is that it can definitely be helpful, especially when working with a large legacy codebase, or with big PRs, where finding these kind of subtle bugs might be like the proverbial needle in a haystack - and of course "it never sleeps, never gets tired", and you can ask it for a 20th review of that 5000 lines chunk of code, while the human reviewer would already have checked out with eyes glazing over ;-)
But yes, of course it's just a tool, and not the gospel - but I was pretty impressed, and I think it's definitely useful ...
leo , the "never gets tired" part is the real find here, more than the codebase-grokking. That's an attention problem, not an understanding problem: the bottleneck was never that bugs are hard to find, it's that human reviewers run out of focus before they run out of code.
But endless passes only help if someone can still tell which of the 20 flagged issues actually matters and that judgment call is still gated by knowing the codebase, not by how many times the tool re-reads it.
Has it ever been confidently detailed about a legacy quirk that turned out to be wrong?
The final judgement call is still 100% on the human developer - it's just a tool which helps finding needles in haystacks (and never gets tired doing so) ...
Does it sometiimes generate "false positives" - sure it does, but the "noise to signal" ratio tends to be pretty good - if the majority of the things it flags would be "noise", then I wouldn't consider it useful ...
It's just a tool, which does not replace human developers ('manual' reviews are still incredibly useful, and are surfacing a different category of issues), but can augment and empower them - just the way it should be ...
It's a good example of AI being useful for much more than purely generating code - I'm convinced that AI will be most powerful when embedding it sensibly/holistically in all stages or aspects of the development lifecycle ...
leo , curious what the false positive rate actually looked like for you, concretely . a number or two would do more than the general case.
False positives? Way below 50% - actually it doesn't often call out things which are completely wrong, more often it's a matter of an issue being a bit marginal ("not important enough to bother"), or based on "real world" knowledge we can tell "this will never happen" - that's really where the human makes the judgement call ...
But more often than not (I'd say in around half the cases) it warrants a good look, or a piece of follow-up investigation, or a decision to be made (by a human) ...
But, I only have experience with it in the context of one (pretty big, pretty complex) codebase - the results might be totally dependent on a number of factors which I'm unaware of - like I said, "YMMV" ...
curious what the false positive rate actually looked like for you, concretely .a number or two would do more than the general case
Do u know what this post reminded me of?
one of the guys had wrote an post about an essay from anthropic, which was about their 80% increase of ai usage in programming.
the main thing i learned from that VERY interesting post which i cant seem to find was that what matters is understanding the algorithms and the system behind everything.
like the devs at anthropic spend more time doing algorithms and solving dept problems than writing code.
this whole post reminded me of that. i think with the rise of ai, understanding and dept has become SO MUCH more important. its a shame that all the people dont really understand that. (maybe a bonus for us ,who do understand? lol)
btw awesome post. i actually am self tonight too but i never really had habits of checking docs, i was more like read everything everywhere at stackoverflow geeksforgeeks realpython and ....
after some time i learned they were this things called docs and i was like "MAGIC"!
Mythorian — that "MAGIC" moment when you found docs after years of forum-hopping is basically the whole post in miniature: the material was always there, you just hadn't found the direct route to it yet...
Have 100% seen this at work. An entire prototype built by two people using AI. One having zero programming experience and the other, apparently fully abandoning software engineering for Claude-Engineering.
I'm now working on organizing it.
Mike — that's the actual split worth noticing: neither of the two people who built it are the ones stuck organizing it now, which means the cost of skipping the model just got handed to you.
Yup! This is the first time in my career (15 years as a paid professional dev) that I've been given the... "here is a turd, catch" throw over the fence. The big issue I'm seeing is that it isn't just a handful of tech debt issues. Its like... everything. Nothing was built with any level intelligent cohesion. It has I think 4 custom rolled http calls to LLM streaming endpoints, where a single function using langchain would have been.... by far a better approach.
Exactly what you are describing is happening to my ex-now-company the last 6 months. I have never felt before more discouraged and disappointed to code. Everywhere a slop. A "mediocre enough" is okay to ship.
Alexandra — "mediocre enough" is the tell: that's not a taste problem, it's what happens when whoever's approving the PR can't tell the difference between fast-and-shallow and actually correct anymore.
Did that standard shift come from new leadership or did it drift in slowly while everyone was heads-down shipping and nobody noticed the bar move??
Mike — 4 separate reimplementations of the same HTTP call is the actual diagnostic, more than the tech debt itself. That's what it looks like when nobody held the whole system in their head at once — probably four different chat sessions, each solving it fresh with zero awareness the other three existed.
Were all 4 written in the same sprint, or spread out enough that whoever wrote #4 genuinely didn't know #1 was already there?
In my company happened the latter. The drift started happening from January. In the last months very few people challenged the mediocre solutions, and who ever did was the not-fun-at-parties-person
Alexandra — "not-fun-at-parties-person" is doing a lot of work in that sentence. That's the actual mechanism, more than the January timeline: once pushing back gets coded as a personality trait instead of a function, the standard doesn't get defended anymore, it just erodes quietly because nobody wants to be that person twice. Is that person still there holding the line, or did they eventually stop bothering too?
Whoever was holding the line was fired yesterday pretty much
@dannwaneri whole system in their head. That's normally me, but I would say that it was no-one. Only the concept of the system (and the end functionality) was held by the "CTO" (the non-dev coder). However, what REALLY tipped me off was one day he was having issues, so I went over to his desk to help him. And i said... "yeah just drop down onto the CLI and run the command".
He had no idea how to do that. (Was using Claude Code within VS Code).
It was like a mv command or something.
I thought "whoa, I've never seen this before."
To answer your question, no, nobody knew there were 4 copies. Let alone was actually reviewing the code. There was... I kid you not, a single index.html file for a "frontend" that was 14000 lines long.
Let that marinate for a little while....
Regarding the conversations on standards. Yeah, the person that was leading our team was a non-dev with no concept of standards. I'm a very high standards kind of person. I watched, the obvious leadership blunder where "if the leader doesn't do it, nobody else will."
So I've waited until he's out of the way so I could pick up the pieces. Also "blew the whistle" to the various other managers going "this p-o-s, could collapse this whole project concept."
Yeah but the AI bros are aggressive in making you leave the understanding and give in everything to AI.
This misguides most of the beginners
Debajyati , the aggression's easy to spot; harder is that it works on beginners specifically because they don't yet have the mental model to know what they skipped.
Vibe coding enthusiasts talk a lot about "guardrails" and test-driven development these days. But even 100% test coverage (of the source code) does not imply anticipating and testing every run-time situation and edge case.
I encounter mostly poor docs. Life is short, memory is ephemeral so pouring over poor docs seems under-leveraged.
It’s easy to preach reading docs but also easy to overlook aspects. If you love to read docs and discussions, I say do it. If you don’t do something you love instead.
Steve , That's actually in the piece: when the Wrangler docs didn't cover it, I read a two-year-old GitHub issue thread instead, so "docs" was never really the requirement, real material was.
This hits hard. The shift from "comprehension" to "output" is exactly the wrong tradeoff, and most people don't even realize they're making it.
I've seen the same pattern: someone ships a feature using a library, it breaks in production, and they can't debug it because they never read the docs — they just asked ChatGPT for the code. The fix usually takes 3x longer than if they'd spent 30 minutes reading the actual documentation first.
The irony is that reading docs IS the productivity hack. Understanding the system means fewer debugging sessions, fewer production fires, and less dependency on AI for things you should know yourself.
The failure mode you're describing has a worse floor under it. You assume the developer who prompted their way to a caching layer at least knows they have a caching layer. Give it a few weeks. I've opened source I didn't recognize, decided some teammate wrote it, run git blame, and found the teammate was me. Three commits deep. Very confident at the time. No memory of any of it.
So the mental model doesn't just fail to form. Sometimes it forms, goes load-bearing, and then evaporates anyway. The code sits there working until it doesn't, and the person best positioned to reason about it, the one who actually built it, is now a stranger to it holding the same empty chat window as everyone else.
Which means the reading list you're defending is longer than you're letting on. It now includes my own changelog. The docs I skipped hardest, it turns out, were the ones I wrote.
I work on embedded database systems for robots, and this hits differently when your code runs on hardware with no internet access. There's no "just ask Claude" at 2am when a drone's IMU buffer is corrupting because you misunderstood the DMA alignment requirements. You either read the reference manual or you don't ship.
The friction you described, sitting with confusion until it becomes comprehension, that's the entire job when you're debugging something that can't phone home. No LLM can look at your oscilloscope trace.
That said, I do think AI changes what's worth reading deeply. I'd rather spend my friction budget on understanding WAL recovery semantics than memorizing serde derive macro syntax. The docs I still read cover to cover are the ones where getting it wrong means data loss, not a compile error.
Friction budget is the right unit, and naming it as a budget is the part most of these threads skip. Everyone agrees reading matters; almost nobody admits it's rivalrous. You have a finite amount of sit-with-confusion in a day, so "read the docs" was never the real instruction. The real instruction is choose which confusion is load-bearing, and that choice is the thing nobody audits. WAL recovery semantics over serde derive macros is a good call precisely because you can say why one earns the budget and the other doesn't. The failure mode isn't skipping the reading, it's spending the budget on whatever confused you most recently instead of whatever will page you at 2am.
The robots detail sharpens it in a way the cloud examples can't. When the system can't phone home, the mental model isn't a nice-to-have you can reconstruct from a chat window later, it's the only copy. Which means the thing you chose not to understand at build time is a decision you already made about what you're willing to be blind to at 3am over a corrupt IMU buffer, you just made it implicitly, by where the budget didn't go. Same shape as the rest of this: the dangerous gap isn't the one you can see, it's the one you never priced.
The docs point hits harder now because AI makes shallow understanding feel productive for longer. You can generate working snippets without ever learning the system boundary, but the bill comes due when debugging starts. Reading docs is not nostalgia; it is how you learn what the tool refuses to abstract away.
Some comments may only be visible to logged-in visitors. Sign in to view all comments.