Editorials

When the Codebase Speaks, Most Teams Aren’t Listening

Three symptoms that look like people problems but are always architecture problems.

Photo by Roger Brown on Pexels

You can feel it before you can name it. A pull request that should take an afternoon stretches into two days. A bug fix in one service breaks something in another. A new developer joins the team, and after three weeks of onboarding, they still can’t make a change without asking someone where things live.

The instinct is to blame the team. They’re not moving fast enough. They need more documentation. They should pair more. But I’ve seen this pattern across enough systems now — different teams, different stacks, different continents — to recognize it for what it is.

The codebase is speaking. Most teams aren’t listening.

Symptom vs diagnosis: what looks like a people problem is usually an architecture problem

In medicine, differential diagnosis is the process of distinguishing a particular disease from others that present with similar symptoms. A patient with chronic fatigue might have anemia, depression, thyroid dysfunction, or sleep apnea — same symptom, four different root causes, four different treatments. Treating the…