Reading Systems Faster Than You Write Them

Reading Systems Faster Than You Write Them is a claim about ratios. Comprehension was already most of the working day when writing code was expensive, and writing code got cheap while comprehension did not. So the reading half now decides whether the writing half is safe, and it is a trainable skill rather than a talent people either have or lack.

Key takeaways

• Xia and colleagues, publishing in IEEE Transactions on Software Engineering, instrumented 78 professional developers over 3,148 working hours and found about 58% of working time went on program comprehension. That study is from 2017 and pre-dates AI assistants, which is exactly why it is useful as a baseline.
• Reading order beats reading speed. Boundaries, then the data model, then the failure paths, then the history: each layer makes the next one interpretable, and skipping one produces a confident wrong conclusion rather than a slower right one.
• Qiao and colleagues, in a November 2025 preprint, found that working with an assistant in brownfield code speeds up task completion while producing measurably shallower understanding of the underlying logic, and that how a developer accepts, modifies or rejects suggestions predicts who benefits.
• Comprehension debt is a named concept with a definition: the gap between what a team knows about its codebase and what it needs to understand to maintain and modify it. Ahmad's EASE 2026 paper names four accumulation patterns, from a study of 621 diaries by 207 undergraduate students.
• Instrumentation is a reading instrument, not just an operations tool. A system that can be asked what it did is a system that can be read in an afternoon rather than a fortnight.

Read this beside Chapter 3, which argues that comprehension sits in the durable layer, and before Chapter 5, which is about not losing it. If you are assembling context for an agent rather than for yourself, the same ordering problem appears as the context-assembly argument.

A bug report says duplicate charges. Three in a month, no pattern anybody can see. The change that caused it is nine months old and passed review at the time.

Two engineers open the code. One reads the function, decides it looks correct, and starts adding log lines. The other spends forty minutes drawing the path from the payment webhook to the ledger write, finds two retry layers that each consider themselves the outermost, and stops looking.

The second engineer did not read faster. She read in the right order. The details here are composited from ordinary production shapes rather than one system, and the shape is exact.

Comprehension was already most of the day

Before arguing about what changed, establish the baseline, because the baseline is already surprising to most people.

Xia, Bao, Lo, Xing, Hassan and Li published a field study in IEEE Transactions on Software Engineering measuring what professional developers actually spend time on. They instrumented 78 professionals across 3,148 working hours, across applications rather than only inside the editor, and found that roughly 58% of working time went on program comprehension activities.

That study is from 2017. Flagging its age is the point rather than a disclaimer: it measures the world before assistants, which makes it the baseline any claim about change has to be measured against.

Now apply the obvious arithmetic. If generation was the smaller share of the day and its cost fell sharply, the comprehension share rose. A model reading code for you does not reduce the understanding a human needs before signing a change. DORA's 2025 finding that adoption relates negatively to delivery stability is what it looks like when that understanding gets skipped.

Reading order beats reading speed

People try to get faster at comprehension by reading more code per hour. That is the wrong variable.

Two strategies exist and both are legitimate. Top-down starts from the entry point and follows the flow, and it is fast when the system has a shape. Bottom-up starts from a specific line and builds outward, and it is what you fall back to when nothing has a shape.

Each one lies in a characteristic way. Top-down makes you believe the code does what its names say, because you never open the function that is misnamed. Bottom-up makes you believe a detail is important because you found it first, and you can spend a day on a branch that never executes.

The fix is a fixed order rather than a preferred strategy. Boundaries first, then the data model, then the failure paths, then the history. Each layer makes the next interpretable, which is why the order is worth being rigid about.

The trade-off measured in brownfield code

There is direct evidence on what assistance does to comprehension, and it is uncomfortable in a useful way.

Qiao, Shihab, Haque and Hundhausen, in a preprint from November 2025, studied developers working with GitHub Copilot in brownfield code, meaning an existing codebase rather than a fresh one. They report that assistance accelerates task completion while producing measurably shallower understanding of the underlying logic, and that behavioural patterns in how suggestions are accepted, modified or rejected predict who benefits.

That is a preprint and I am using it for the direction of the trade-off rather than for an effect size. The direction is the actionable part. Faster completion and shallower understanding is a trade, and a trade is fine when you know you are making it and dangerous when you think the speed came free.

The predictor finding is the more useful half. Developers who modify suggestions before accepting them are engaging with the logic, and developers who accept wholesale are not. That is a behaviour you can observe in yourself this afternoon.

Comprehension debt, named and defined

The concept that gives this failure a vocabulary is recent and worth adopting.

Muhammad Ovais Ahmad's paper for EASE 2026, published in April 2026, defines comprehension debt as the growing gap between what a team knows about its codebase and what it needs to understand to maintain and modify it. It argues the debt resides in collective cognition rather than in the code. The study analysed 621 reflective diaries from 207 undergraduate students over eight weeks, so the population is students on projects rather than professionals in production. Take the vocabulary and the mechanism from it. Not a rate.

The four accumulation patterns it names are recognisable in professional teams, which is why the vocabulary travels even when the sample does not.

Ahmad also names a mitigating pattern worth stating: assistance used as a comprehension scaffold, meaning asking the model to explain the existing system rather than to write the next part of it. That is the same tool pointed in the other direction.

The drill: one request, end to end, in writing

Here is the practice I would give anyone joining a system, and the only reason it feels slow is that it is the first thing that has ever been measured.

Take one real request. Not a class of requests, one: a specific user action with a specific identifier. Trace it from the first byte at the edge to the last durable write, and write down every hop, every process boundary and every store it touches.

At each hop, answer four things in writing. What owns retries here. What the invariant on the data is at this point. What happens if this hop times out halfway. And why any surprising branch exists, which usually means finding the commit.

Two hours of that beats two weeks of reading files in alphabetical order. It also produces an artifact the team did not have, which is the fastest way a new joiner earns standing, and Chapter 8 is what that standing turns into.

Instrumentation is a reading instrument

The habit that separates people who read systems quickly from people who read code quickly is that the first group runs the system while reading it.

A trace across services answers in seconds what static reading answers in an hour, and it answers correctly, because it reports what happened rather than what the code appears to say. Logs with correlation identifiers do the same for asynchronous paths, which is where reading fails most often.

So treat missing instrumentation as a comprehension problem rather than an operations problem. When you cannot see a request cross a boundary, the cost is not only slow incident response. It is that nobody on the team can build an accurate model of the system, so everybody works from a slightly wrong one.

Adding a trace to a path you are about to change is usually a half-day and it pays back inside the same week. I would rather join a mediocre codebase with good instrumentation than an elegant one with none.

The order comprehension fails when you skip a step

This is judgement rather than a published result, and it is specific enough to disagree with.

In my experience comprehension fails in a fixed order. Skip the boundary map and you assume the wrong component owns a behaviour, which is how two services both retry. Skip the data model and you assume an invariant that the schema does not enforce, which is how duplicates appear. Skip the failure paths and you treat the happy path as the path, which is how timeouts become data corruption. Skip the history and you delete the odd-looking code that was preventing the bug you are about to reintroduce.

Those four failures have a common signature: high confidence, fast delivery, and an incident two months later that nobody connects to the change. That signature is why I distrust my own speed on unfamiliar systems.

The counter-practice is cheap. Write down the assumption you are relying on before you write the code, in one sentence, and check it against the system rather than against the code.

The objection: nobody funds a week of reading

Correct, and nobody is being asked to.

The drill above is two hours, not a week, and it is done in service of a change you were already assigned. The comparison is not reading against shipping. It is two hours of ordered reading against the three days that a wrong assumption costs when it surfaces in production, plus the review time it consumes, plus the trust it spends.

There is a second, more political answer. What gets funded is what leaves an artifact. A request trace written into the repository, a boundary diagram in the README, a decision record explaining an invariant: these are outputs, and they are easier to defend in a standup than "I spent the morning reading".

In my experience the teams that treat comprehension as unfunded overhead are the same teams whose incident reviews keep concluding that somebody misunderstood the system. That conclusion is a budget line. It just gets charged to a different quarter.

Chapter summary

Comprehension was already the majority of the working day before assistants existed, with Xia and colleagues instrumenting 78 professional developers across 3,148 working hours and finding roughly 58% of time going to program comprehension, a 2017 figure that predates assistants and is therefore the right baseline. Generation got cheap and comprehension did not, so the ratio moved further the same way. Reading order beats reading speed: top-down reading makes you believe the names, and bottom-up reading over-weights whatever you found first. The fix is a fixed sequence of boundaries, then data model, then failure paths, then history, because each layer makes the next interpretable. Qiao and colleagues' November 2025 preprint reports that assistance in brownfield code accelerates completion while producing measurably shallower understanding, and that modifying suggestions before accepting them predicts who benefits. Ahmad's EASE 2026 paper defines comprehension debt as the gap between what a team knows about its codebase and what it must understand to change it, naming black-box acceptance, context mismatch, dependency-induced atrophy and verification bypass, on a population of 207 undergraduates rather than professionals. The practice is one real request traced end to end in writing, answering at each hop who owns retries, what the invariant is, what a mid-flight timeout does and why odd branches exist. Missing traces are a comprehension problem rather than an operations one. And comprehension fails in a fixed order when steps are skipped, with a signature of high confidence, fast delivery and an incident nobody connects back to the change.

Comprehension is also the thing most at risk from the tool that makes writing cheap, and the risk is measurable rather than moral. Chapter 5 is Working With Agents Without Deskilling, which is where the aviation research, the automation-bias literature and a randomised trial converge on the same uncomfortable conclusion.