Comprehension as an Architectural Characteristic: A System That Is Not Understood Cannot Evolve Safely
In the world of software architecture, comprehension is a vital yet often overlooked aspect. It's the understanding that a team has of the system they're building, and it's crucial for the system's ability to evolve safely and adapt to changing requirements. Without comprehension, a system is like a ship without a captain - it drifts aimlessly, and its evolution becomes a risky endeavor.
The Comprehension Problem
Imagine a seasoned team working on a complex system. When a production incident occurs, the team often spends more time figuring out how the system works than actually fixing the bug. This is because the understanding of the system is siloed, held by a few individuals rather than shared across the team. As Peter Naur argued, the system includes the theory and not just the code. How widely and durably that theory is held across the team is a property of the system itself.
Three Forces That Erode Comprehension
- Centralized Decision-Making: In complex systems, decisions are often made by a few people, creating bottlenecks and knowledge silos. This siloed approach can lead to a lack of shared understanding, as teams may understand their local sub-domains but struggle to grasp the global picture.
- Team Churn: When team members leave, they take their knowledge and understanding with them. New hires must rebuild the theory from scratch, often relying on artifacts that record the what rather than the why. This can lead to tactical patches rather than systemic improvements.
- Generative AI: AI has commoditized code generation, but it hasn't replaced the need for comprehension. In fact, it has accelerated the erosion of comprehension. As AI matures and delivery pressures increase, engineers may struggle to understand their own code, leading to comprehension debt.
Detecting and Measuring Comprehension Loss
Architects and technical leaders can monitor several key indicators to detect and measure comprehension loss. These indicators include:
- Pull Request (PR) Metrics: Large PR sizes, agentic code reviews, and review dysfunction can indicate a breakdown in shared understanding. Enforce thresholds and track waivers to ensure knowledge flow.
- Degree of Authorship (DOA): A high DOA implies knowledge concentration around a few individuals. Monitor DOA using tools like git-truck to expose single points of failure.
- Onboarding Time: The time it takes for new hires to become productive is a proxy for system comprehensibility. Track onboarding times and encourage new engineers to log confounding issues.
The Comprehension Checkpoint
The human review is a comprehension checkpoint, not a quality gate. It's where the team validates, strengthens, and disseminates the comprehension attained before code generation. This process ensures that humans remain in control of the system, preventing the statistically default design that AI might produce.
Sustaining the Shared Model
Individual comprehension is necessary but not sufficient. When sub-systems communicate and teams interact, the divergence of mental models becomes expensive. Bounded context seams are critical areas where comprehension must be shared. Use tools like ADRs and context maps, but ensure knowledge flow through deliberate team topologies and decentralized architectural decision-making.
Engineering Comprehension Deliberately
Treating comprehension as an architectural characteristic means giving it the attention it deserves. Monitor leading indicators, automate fitness functions, and establish practices that hold the line. By making comprehension deliberate at the seams and core domains, teams can ensure that their systems evolve safely and effectively.
In conclusion, comprehension is a vital architectural characteristic that enables evolutionary architecture. By recognizing and addressing the forces that erode comprehension, teams can build systems that adapt safely and thrive in a rapidly changing landscape.
