Architecture is not evaluated in isolation. It is evaluated in the context of a team.
A pattern that is elegant and well-understood by the team that designed it is often opaque to the team that inherits it. When the original architects move on — and they always do eventually — what remains is a system and the people who need to maintain it. The system’s quality, in the long term, is determined by how well that remaining team can reason about it, change it, and debug it when it fails.
What this principle changes
The principle changes the question you ask when evaluating architectural choices.
The naive question: Is this the technically optimal solution?
The better question: Is this the right solution for the team that will maintain it, over the timeframe they will maintain it?
These questions often produce different answers.
A microservices architecture may be the right long-term structure for a system that will eventually have a large team maintaining it. For a team of four maintaining a system with modest scale requirements, a well-structured monolith may allow significantly faster iteration and significantly lower operational complexity. The architectural choice that reads as technically superior in the abstract may impose a maintenance burden that exceeds its benefits.
The team capability dimension
When designing a system, the team’s current capabilities matter as much as the abstract qualities of the architecture.
This is not a static constraint. Teams grow. But growth takes time, and architecture decisions take effect immediately. A system designed for the team the organization hopes to have in three years, rather than the team it has today, will be maintained poorly for those three years while the team catches up.
The better approach: design for the team you have, with a migration path toward the architecture appropriate for the team you are building. This requires knowing explicitly what your team’s current strengths are, where the gaps are, and what the realistic growth trajectory looks like.
The documentation problem
Systems that were not designed for their maintenance team typically develop a documentation problem. The original architects write documentation that answers the questions they would have asked. The maintenance team has different questions — often more basic — that the documentation does not address.
The repair is not to write more documentation. It is to involve the maintenance team (or a representative version of it) in the design and review process, so the system is built with their questions already answered in its structure, not in a document they may or may not read.
The best documentation is architecture that is hard to misuse and easy to understand. The second best is documentation written by the people who would need it, not the people who built the system.
Humility in architecture
There is a form of architectural pride that leads to systems that are impressive to other architects and painful to everyone else. Systems that demonstrate mastery of a pattern at the expense of maintainability. Systems designed to be written about rather than maintained.
The discipline of building for the team that will maintain it requires a specific kind of humility: the willingness to choose a less sophisticated solution if that solution is more appropriate for the people who will live with it.
That is not a lowering of standards. It is a more complete accounting of what the standards should be.