Description
A developer asks an assistant to add a discount to the payment module. To write one function it reads the order module for the shared types, the inventory module for the stock check, the notification module for the event contracts. What comes back compiles, passes the existing tests, and quietly depends on a function that was deprecated last quarter. Nobody had written the deprecation down and the boundary did not enforce it. A new engineer would have walked into the same wall. That is not a tooling failure, it is a structural one.
Most of the effort in changing software goes on reading what is already there before anything can be changed. Engineers pay that cost once and then stop paying it: familiarity with a module settles into memory, so the second visit is cheaper than the first. A model gets no such discount. Every session is a first encounter, and everything it needs in order to understand has to fit into the context it can hold at that moment.
This is where a module boundary stops being an architectural preference. It is the context boundary. A well-bounded module hands a model a few hundred lines that explain themselves. An entangled one hands it everything the module depends on, and the research on long context is consistent: accuracy falls as the input grows, and it keeps falling even when retrieval is perfect and nothing irrelevant is present. Code that looks alike across a boundary and behaves differently is worse than noise, because it misleads with confidence, and coupled modules produce exactly that.
Then there is the direction of travel. Repositories that adopted an assistant saw a burst of output that faded within a few months and a rise in complexity that did not. Complexity is not free: work in a module slows sharply as it becomes harder to understand, for people and for agents alike, and the refactoring that used to push back is itself in decline. So the question this dimension asks is not whether your modules are elegant. It is whether anything in your system knows how tangled the worst of them is, and whether that number costs anybody anything when it moves the wrong way.
The five levels
One question decides which rung you are on: does the system itself act on this, or does a human have to choose to? Each rung carries a tell: the thing that would settle it, so the score is something you checked rather than something you agreed with.
- 1
Blind
Nobody knows how entangled the modules are. Complexity is not measured anywhere, so the only signal is which parts of the system people avoid. There is no number, which means there is nothing to argue about and nothing to improve against. The complexity is real, and the only place it is ever mentioned is the estimate.
The tellAsk for a coupling or complexity number for any module in your scope, not the worst one. If nobody can produce one for any of them, the worst module is not only unmeasured, it is unidentified.
- 2
Tacit
A few engineers carry that knowledge. They know which module is dangerous to change before a weekend, and they compensate with familiarity that took months to build. New joiners get none of that, and neither does an agent, which starts from nothing every single session. The module is not simple; it is familiar.
The tellName who you would give a change in your worst module to. If the honest answer is two people, and both have been here for years, the structure is understood only by them, and nothing in the module says it.
- 3
Visible but inert
Complexity is computable and somebody computed it. There is a dashboard, a quality gate report, a number quoted in retrospectives. Nothing in the pipeline cares. A change that makes a module worse merges exactly as fast as one that makes it better, so the measurement records the decline rather than resisting it.
The tellFind the module with the worst score on your dashboard, then read the last ten changes that landed in it. If not one review mentions the score, and none was sent back because of it, the score is decoration.
- 4
Acted on
Coupling and complexity carry a budget the build enforces. A change that pushes a module past the threshold flags or fails on its own, before review, without depending on anyone paying attention that day. The budget gets argued about in the open, which is what happens once a number finally costs something.
The tellFind the last change that pushed a module past your threshold. Something automatic refused it, and it refused because of the number, not because a reviewer decided to push back that day.
- 5
Durable
The budget holds while the system grows. New modules arrive already inside it, thresholds are revisited deliberately rather than raised in a hurry the night before a release, and bringing a module back under budget is planned work with a name on it rather than somebody's weekend.
The tellLook at how the thresholds have moved over the last year. Tightened, or held with dated exceptions, is durable. Thresholds quietly raised each time they blocked a release leave the same practice with nothing left to enforce.
What this dimension rests on
The five levels are observed, from client engagements, and no paper produced them. What the research below establishes is why this dimension is worth scoring at all. No links: the citations carry enough to find them, and they stay findable after a link would have rotted.
He, Miller, Agarwal, Kaestner and Vasilescu, Speed at the Cost of Quality: How Cursor AI Increases Complexity (MSR 2026)
Compared repositories that adopted an AI coding tool against matched controls, and found the velocity gain faded within months while the increase in code complexity stayed.
Rando et al., LongCodeBench: Evaluating Coding LLMs at 1M Context Windows (2025)
Tested code comprehension and bug fixing as the context grows, and found accuracy collapsing rather than tapering. How much a model has to read to change one thing is not a minor inconvenience.
Where this came from
This dimension has a published article behind it, written from client engagements rather than from a greenfield repository.
Read the article on Cognitive load per module →
How to climb this dimension is not written yet. It is the next thing this page grows, and saying so is more useful than a paragraph of generic advice.