matklad’s Way of Learning Architecture — Not Books but a Large Codebase, and the Channel We Are Losing in the LLM Era

The real path by which a senior engineer acquired architectural intuition was not a single book but the hours spent directly running a large codebase. So in the age when LLMs write the code, through what channel will juniors acquire that intuition — or does the intuition itself disappear?

Opening — A Systems Engineer Has Published His Own Learning Method

On May 12, 2026, Aleksey Kladov (handle: matklad) posted “Learning Software Architecture” on his blog. He does not write on behalf of any company. But noting who he has been changes the weight of the piece. He was an early maintainer of IntelliJ Rust, he designed rust-analyzer from scratch at JetBrains, and he now works as a systems engineer on TigerBeetle, a distributed accounting database. He is also the author of pieces that systems-programming circles have all encountered at one point or another — “Why an IDE?”, “Notes on a Smaller Rust,” “How to Test.” In other words, he speaks with the authority of someone who has built large codebases from end to end.

The post is short and candid in a way that does not match that authority. He writes that the starting point was a physics PhD student asking him “how should I learn software design?” His answer, summarized: books were of almost no help. Design lectures in school were no different. What actually taught him was the architectural responsibility he was thrown into during the IntelliJ Rust years, and the mistakes he made then were the real textbook. The reassuring fact, he adds, is that “software engineering is simple enough that an inquisitive mind can figure it out from first principles.”

This piece reached the Hacker News front page on May 12 with 547 points and over 100 comments. The reason for the crowd is simple. Everyone has seen this scene. Clean Architecture, Domain-Driven Design, Designing Data-Intensive Applications, A Philosophy of Software Design sit on the bookshelf. But when it actually comes to deciding which PR to merge, where to draw a module boundary, which dependency to cut, no page of any of those books opens. The decision comes from someone’s scar that says “I built something like this before and it blew up.” matklad’s piece is the retrospective in which the scar’s owner himself recounts where the scar was made.

The problem is that placing this retrospective in the coordinates of 2026 raises another question. The channel through which matklad acquired his scars — the thousands of hours spent reading and modifying a large codebase by hand — is, at this moment, narrowing fast. In an era when Cursor and Claude Code and ChatGPT Codex are becoming the first reader and the first author of code, where do juniors get the time to chew on a large codebase and make scars? This piece tries to look at both questions together.

Section 1 — Not Books but Code: The Learning Path matklad Recommends

First, follow matklad’s piece precisely. He divides learning material into two layers. The first is articles and talks. What he recommends most strongly are not books. Gary Bernhardt’s talk “Boundaries,” Pieter Hintjens’s ØMQ guide, Jamii’s “Reflections on a Decade of Coding,” Ted Kaminski’s blog, and his own “How to Test.” All of them are short pieces in which one person’s concrete experience is generalized.

Books come second. The two he names are Software Engineering at Google and John Ousterhout’s A Philosophy of Software Design, but his treatment of the latter is lukewarm — “people recommend it widely but it didn’t change anything for me.” He is, in other words, somewhat skeptical of the whole “architecture book” industry.

What, then, actually taught him? His self-diagnosis converges on two things. One is the experience of being made responsible for architecture during the IntelliJ Rust and rust-analyzer years and making bad decisions himself. “What actually taught me was that I was wedged — accidentally — into the position of architectural lead at IntelliJ Rust, and so I had no choice but to make mistakes firsthand.” The other is what he sees as the meta-principle of learning: the belief that software engineering is a simple domain, and that an inquisitive mind can figure out answers starting from first principles.

Combine the two and the outline of the learning path he recommends takes shape. Books < articles and talks < reading and modifying a large codebase yourself < being end-to-end responsible for a system you built with your own hands. Books give you vocabulary. Articles and talks add a mental model or two. But real intuition — which PR is risky, which dependency will become a bill in five years, which abstraction will not explode — grows only when you operate something you wrote yourself.

This diagnosis is not his alone. The most upvoted comment under his piece is deepsun’s: “The best way to learn architecture is to: 1. Maintain a large enough project. Not create, but support. 2. Do it for at least a couple or few projects.” He adds, “It’s visible especially at Google: those who built something new get promoted, and those who maintained do not. So the best architect candidates inside the company are often the outside consultants who came in to take over the project everyone else has left.” Heavily cynical, but the pattern he names is familiar.

In another comment, miki123211 recommended the book series Architecture of Open Source Applications. “Each chapter is written by the project’s own maintainer, so you learn not only what the architecture is but the constraints — usually history and changing vision — that produced that architecture.” This comment maps neatly onto matklad’s claim. If there is anything to learn from a book, it is not abstract principles but a maintainer’s self-account of “why this particular codebase looks the way it does.”

A user named CSMastermind, in a more direct vein, posted a “cheat sheet” of 12 rules. Good design is the consistent presence of one idea throughout. Generalize that and the goal is to minimize surprise. If the system allows it, people will do it. A solution that starts with “if everyone just does it this way” is not a solution. Separate the part that transforms data from the part that uses it. Data models outlive code. Coupling is the root of most evil. Version control is unavoidable. Make state explicit. Every piece of information should have a single source of truth. Spend more time on naming. If testing is hard, the design is wrong. Every undocumented decision will be regretted. Communication is a tax, and you have to justify it before paying.

Read through CSMastermind’s list and what “books” promise becomes clear. The promise is to compress aphorisms like these into one volume. But aphorisms are aphorisms, not intuition. Reading the sentence “if testing is hard, the design is wrong” and, upon seeing a PR, instantly suspecting “this would be hard to test — is the module boundary drawn wrong here?” are completely different cognitive activities. What closes the distance between them — per matklad’s answer — is not a book but time.

Section 2 — Conway Wins: The Substance of Architecture rust-analyzer Showed

Far more interesting than the book recommendations in matklad’s piece is one paragraph. He writes that “the quality gap between industrial software and academic software comes not from a knowledge gap but from a difference in incentive structures.” The code a PhD student writes under “I need to ship a paper in three months” and the code a single team maintains for five years on the same compiler — the difference between them is not algorithms or design patterns. It is the difference in whose time has been arranged to go where.

He borrows a line from neugierig that is sharp. “We talk about programming like writing code, but code matters less than architecture, and architecture matters less than social issues.” This is the practical version of Conway’s Law. The shape of a system reflects the communication structure of the organization that builds it. So the real architecture problem is not module boundaries but the question of which person is set up to spend which time.

The most concrete instance of this insight is rust-analyzer, which matklad himself built. He writes that he intentionally designed rust-analyzer with two tiers of quality bar. The core of the compiler — parser, type inference, name resolution — demanded a very high bar of quality, minimal dependencies, and a fast test suite. That way, the set of people who can touch the core stays small and regressions are hard to introduce. But the slots where “a weekend volunteer” can come in and add one or two features — auxiliary analyses or supplementary intention features — were deliberately placed in isolated modules and wrapped with catch_unwind guards so a crash cannot leak into the core. He did not enforce perfectionism on these modules. When they break, the break is isolated.

This decision is not mere modularization. It is a sociological decision about “what kind of people you make gather.” The strict bar at the core gathers full-time systems engineers; the forgiving bar of the isolated periphery gathers weekend contributors. The two groups can live in the same repository without colliding. The result is that rust-analyzer became not “a project that requires JetBrains full-time staff teaching everything at once” but “a project to which many people can contribute in many different time units.”

matklad adds a caveat. “It is common for an experimental architecture meant to solve today’s problem to become a permanent constraint tomorrow.” This shows that he is not bragging about the decision but recalling it as part of the scar he carries. Even if the two-tier design turned out to be a good choice, the decision itself becomes permanent and ties the hands of the next generation of maintainers. Architecture is not a picture you draw on a clean blackboard. It is always redrawn on top of lines someone else has already drawn.

This is where books teach poorly. Clean Architecture says “dependencies should point inward.” But at the moment of deciding where to cut a dependency, the real pressure is two-fold. First, who will maintain this module? Second, what reward structure are those people living in? Books do not answer these two questions. The answer is always inside the history of that codebase.

ah1508 extended the same texture in the comments. He recommends giving juniors not adjectives like “clean code” or “beautiful code” but a clear goal list. Is it maintainable, performant and scalable, efficient, resilient, observable, testable, secure, readable to a new developer joining tomorrow. “Each criterion balances against the others, and the more criteria you have, the easier it is to make a good choice when you hesitate.” This too maps onto matklad’s diagnosis. Good architecture does not reduce to aphorisms. It is the ability to call the names of trade-offs precisely.

CSMastermind’s closing line therefore compresses everything. “The job of an engineer at any level is to use rules of thumb to solve problems for which there is incomplete information.” This is what the word intuition ultimately means. Information is always incomplete, and the decision always has to be made now. What fills the gap between them is experience. Books compress that experience; they do not replace it.

Section 3 — The Narrowed Channel of the LLM Era: Where Will Juniors Get Their Scars?

The real reason matklad’s piece reached the front page in May 2026 is not that a systems engineer’s learning retrospective is novel. It is that the learning channel his retrospective points to is narrowing fast right now.

To restate: the path by which matklad acquired intuition was the time he spent personally writing, fixing, and being responsible for a large codebase. But the reason GitHub traffic has grown 30x since December 2025 is not that humans are writing 30x more code. It is that coding agents like ChatGPT Codex, Claude Code, and Cursor have begun writing the first lines and first PRs of code on humans’ behalf. The subject that first meets code is shifting from human to agent. This change steals exactly that much time from “the time a junior spends manually chewing on a large codebase and earning scars.”

That this is not mere nostalgia is confirmed by ramon156’s candid comment. “I would like to spend my time more on gaining a mental model of the projects I work on, but I get very demotivated if I start disliking things.” The line he added captures the mood of the era well. “I already spend 40 hours a week staring at the most boring project I can imagine.” This sentiment is universal. Chewing on large code is fundamentally boring. That is what gives a scar its value, and people do not actively choose scars.

LLMs precisely reduce that boredom. When adding a new module, instead of fitting the whole structure of this codebase into your head, you can ask “add this function in the same pattern.” The result usually works. Because it works, it merges. Because it merges, when the next similar thing comes, you use the same channel again. Repeat this cycle enough and work flows without your having to hold the whole codebase in your head. While it flows, intuition does not grow.

Those who recognize this risk are exploring new learning channels. One candidate is “pair code review with AI.” A person opens a PR and asks the AI, “where does this PR diverge from the existing conventions of this codebase, and what burden will it create in five years?” While the model answers, the person compares their own intuition against the model’s. Run well, it has the effect of the model showing you part of the scar in advance. Run badly, it becomes a new kind of book-learning in which you memorize the model’s answers.

Another candidate is “mandatory refactoring time for AI-generated code.” That is, every LLM-generated piece of code that goes into production has to pass through a stage where a human reads it whole and rewrites it. This is the deliberate return of part of the LLM productivity gain as a learning cost. But for the company this policy is a cost, and for the employee this policy is boredom. The probability of natural adoption on either side is not high.

A third candidate is “deliberately picking large pre-LLM codebases to read.” The Architecture of Open Source Applications series miki123211 recommended is one example. matklad’s own rust-analyzer is another. Long-running projects like the Linux kernel, PostgreSQL, SQLite, Redis, CPython carry the traces of decisions made long before LLMs appeared, and those traces still work. If a junior wants the intuition of a large codebase, beyond the codebase of their own employer, they need to deliberately pick one or two such projects and read them from the maintainer’s vantage point. The learning path matklad’s piece points at is, in the end, this kind of self-imposed discipline.

0xbadcafebee’s comment adds a good metaphor to all of this. “Software architecture is like plumbing design. Very important, but we don’t live inside the plumbing — we live inside the house the plumbing is in. If the plumbing doesn’t account for the rest of the house, you get a very expensive repair.” Architecture is not its own end but a supporting structure that lets the house — the business, the team, the users — live. What LLMs do in this metaphor is lay the plumbing faster; they do not decide the shape of the house. If the plumbing is laid fast while the intuition that decides the shape of the house is lost, a very expensive repair arrives as a bill five years later.

Conclusion — Books Are Vocabulary, the Codebase Is the Scar

Return to the opening question. What was the real path by which a senior engineer acquired architectural intuition, and where does the junior get that intuition in the LLM era?

The first half of matklad’s May 12 answer is clear. Books give vocabulary. Articles and talks add a mental model or two. But intuition — the immediate sense of which PR is risky, which dependency becomes a bill, which social incentive determines which module boundary — grows only out of the time spent personally responsible for a large codebase. The order he recommends is books < articles < reading a large codebase < running your own system. If what Clean Architecture promises is intuition itself, matklad’s diagnosis says that promise is overstated. A book cannot give you a scar. Scars are made by cutting yourself.

The second half is what he does not answer directly, and what we have to answer. In the age when LLMs write code, the junior’s channel of scars narrows. This is not a question of morality but of arithmetic. The less time humans spend writing the same volume of PRs, the less time humans spend acquiring scars. The result will arrive a generation later. When it arrives, there is no guarantee it will not be expensive.

The available answer, in the end, is deliberate self-discipline. Not letting the AI do it from start to finish, reading what the AI wrote in full, picking large open-source codebases and reading them from the maintainer’s perspective, and setting aside time to consciously collide your own intuition against the model’s. matklad’s piece is one of the best texts in defense of that time. “Software engineering is simple enough that an inquisitive mind can figure it out from first principles.” His “simple” is consolation, but the act of re-deriving that simplicity for yourself happens only to a person who is curious. LLMs make that curiosity easier to dull. To hold architectural intuition in this era, you have to consciously protect curiosity. Books are vocabulary. A large codebase is a scar. Deliberately leaving room on your own calendar for the time to make scars — that is the real homework matklad of May 2026 has left us.