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, so...
For further actions, you may consider blocking this person and/or reporting abuse
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?
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?
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.
The 'conclusion without construction' framing lands hard. I see the same debt show up in embedded and edge work, except there the cost is immediate and there's no cloud to catch the fall. A circuit breaker you don't understand doesn't wait six weeks to fail on a server — on a device with no retries, no autoscale, and one shot at the control loop, it fails the first time the half-open state actually matters, and the robot just stops.
What stuck with me is that the why lives in the places nobody screenshots: changelogs, RFC threads, the footnote about the edge case. Tutorials optimize for 'make it work,' but the mental model only forms from sitting with the material that explains the tradeoff. Do you treat 'can explain the why' as a gate in your own code review, or is it something you only notice missing after an incident?
So true. Taking the lazy route and delegating the reading/summarizing to AI agents is akin to shooting ourselves in the foot. I'm guilty of this too..
But how much of that laziness stems from the knowledge that the documentation is AI generated? 😅
This hits because docs are where the system's real shape usually leaks out. AI can summarize an API, but it rarely gives you the historical reasons, edge cases, and failure modes that are buried in the docs. Skipping that layer makes people fast at snippets and slow at understanding.
The “confusion is where the learning happens” point is the part that landed for me. I’ve found that the useful loop is usually:
That’s different from “read all the docs before doing anything,” which rarely works, and also different from “ask for the answer and move on,” which skips the model-building step.
The failure is doing a lot of the teaching. The docs just become legible once you have a concrete failure to attach them to.
Anand — "the failure is doing a lot of the teaching" is the real insight in that loop, more than the five steps themselves. It's why reading docs front to back rarely works: there's nothing yet to attach the content to, so it doesn't stick.
The failure is what turns an abstract paragraph into something legible. Step 5 — explaining why the fix worked . who's that explanation for? Written down somewhere, or just the internal narration that makes sure you actually got it and didn't just get lucky??
Mostly for my (future) self, but the durable version is written down.
If I can’t write a short note like: “my model was X, the system did Y, the docs/source say Z, so the fix works because…”, I treat that as not fully understood yet.
It doesn’t need to be polished. Sometimes it’s a PR comment, sometimes a comment in the code, sometimes a README update. The useful part is making the explanation external enough that future-me or a teammate can challenge it.
Internal narration helps for sure, but it’s too easy to confuse recognition with understanding.
the circuit breaker example is the right framing. you can ship a working implementation without any model for what the half open state is protecting against, and the failure is invisible until a specific traffic shape hits it.
we have the same shape in our RAG pipeline: a reranker threshold set on "seems right," never grounded in the retrieval model. corpus expanded, recall dropped 30%, two days of debugging to find the cause. the answer was three pages into the Cohere guide.
for your Vectorize setup — cosine or dot product distance? asking because that choice is buried in an HNSW footnote, not the quick start.
This hits incredibly close to home. I skipped the traditional CS degree too, and everything I know came from that exact 1 AM struggle—staring at docs, breaking things, and forcing myself to understand why a configuration failed until the pieces finally clicked.
Seeing this process vanish in real-time is alarming. There is a massive difference between using AI as a sounding board to deepen your comprehension versus using it as a copy-paste crutch to bypass thinking entirely. The irony is that the "friction" of reading documentation isn't wasted time; it's exactly where the load-bearing mental models are built.
When you shortcut that friction for short-term output, you aren't actually scaling your productivity—you're just outsourcing your critical thinking. And the bill for that technical debt always comes due during a production outage when there's no chat box left to save you. Outstanding piece.
Documentation was my education channel when I couldn't afford to go to any training.
Assalamualaikum,
This is very relatable I’ve noticed the same thing when I stop reading docs and just rely on guesswork.
Did you find any good way to stay consistent with documentation?
Tahami — the only thing that's actually worked for me: read the section that's failing, not the whole page, and don't move on until you can explain why the code does what it does, not just that it works.
Assalamualaikum
JazakAllah khair, this is really helpful advice.
I’ve been trying to read everything at once, but focusing on the failing part makes much more sense.
I’ll start applying this approach really appreciate you sharing this!
Tahami — you'll know it's working when you catch yourself skipping a section because you already predicted what it says.
Thank you, that’s a really powerful way to look at it! I never thought about it like that before. I’ll pay more attention to when I start predicting things while reading that seems like a great sign of real understanding. Appreciate your guidance!
This hit. The circuit breaker without knowing what half-open means — that's the exact thing I keep writing about. Someone trusted the output, never built the model, and paid for it at 2am in production.
The whole post reads like a thesis statement for the series I'm working on. Every story is a production version of "you skipped the why, now you've got nothing to reach for."
The split you're calling out — who still reads and who doesn't — that's the setup for every one of these failures.
if your series is basically the incident report version of this, the interesting data point isn't that people skip the why, it's what fails when they do.
Do your cases cluster around the same categories — concurrency, auth, caching or is "nothing to reach for at 2am" just as likely no matter what the system is??
Good question. I went back and mapped them after you asked.
The spread is wider than I expected — config, monitoring, compliance, auth — each one in a different category. But here's what clusters: every single one involves a system that reported "everything is fine" right up until it wasn't.
On the three you called out specifically:
— Concurrency: there's one in my older series. AI tests configured at the 90th percentile, passed clean, hit a data race under real traffic. $700K SLA bill.
— Auth: surprisingly few so far. The closest is a story about someone taking over an AI platform through credential reuse — but that's more "access control wasn't reviewed" than a true auth failure.
— Caching: not yet. Maybe I'll find the right stratagem to write a dedicated one.
If you have time, I'd love to hear your thoughts on both my old series and the new 36 Stratagems series. Your perspective would be valuable.
xulingfeng — that clustering is the actual finding here, more than any single category: "everything is fine" isn't a status, it's the absence of anyone checking underneath. The $700K one is the sharpest example — a 90th-percentile test passing clean is exactly what you'd expect if nobody asked what the tail looked like.
Did the team have a mental model of that traffic shape before it shipped, or did the passing metric stand in for one?
Went back and read through both series after this thread — 36 Stratagems and AI, Ego & Regret. Have some real questions, will drop them once I've finished
Appreciate you reading through both — that's a lot of words to sit through 😅 Looking forward to the questions.
I think the key idea here is the mental model.
Reading builds it for humans.
AI needs an evidence-backed version of it before it can reliably reason about or change a software system.
That's how we think about Workspace Intelligence.
The “conclusion without the construction” line is the one that lands.
AI summaries are useful, but they are dangerous when they replace contact with the system’s actual constraints. Docs, RFCs, changelogs, and issue threads teach the shape of the design: what the API refuses to do, what broke before, what edge case someone fought hard enough to document.
A good use of AI here is not “skip the docs”. It is “help me interrogate the docs”: point me to the relevant section, ask what assumption I’m making, compare two footnotes, generate a test case from the warning. The mental model still has to be earned.