I ran engineering organisations of 40 to 45 engineers across multiple enterprise implementations. I've built architectures from scratch and inherited ones mid-flight. I've onboarded teams into systems they didn't design and kept delivery moving while the architecture evolved underneath. The system design mattered — but the thing that determined whether the architecture actually held was whether the people building inside it understood the reasoning behind the decisions, not just the decisions themselves.
This article is about what I learned doing that. Not the technical patterns — those are well documented elsewhere — but the organisational practices that made the difference between an architecture that guided 40 engineers and one that 40 engineers slowly dismantled through well-intentioned local decisions.
The mental model problem
When you're a team of five or ten, architecture is a shared understanding that lives in the room. Everyone was there when the decisions were made. Everyone knows why the service boundaries are where they are, why this integration is synchronous and that one is event-driven, why the domain model is shaped the way it is. When someone makes a design decision, it's informed by the full context.
At 40 engineers, that breaks down completely. The team that built the original architecture has moved on to other parts of the system — or left the organisation entirely. New engineers join and inherit a system they didn't design, with decisions they don't have context for. They see the “what” clearly enough: here are the services, here are the contracts, here's how data flows. What they don't see is the “why.” Why is the pricing domain separate from the product catalogue? Why does the order service own the fulfilment state machine rather than a dedicated fulfilment service? Why does this integration use a synchronous call when everything else is event-driven?
Without the “why,” engineers make reasonable decisions that contradict the architectural intent. Not because they're careless, but because they're working from incomplete context. They draw a new service boundary that makes sense for their feature but breaks the domain model. They introduce a synchronous call into an event-driven flow because it solves their immediate problem. They copy a pattern from one part of the system where it's appropriate into another part where it isn't.
Any one of these decisions is small. At scale, they compound. I've watched it happen. It's not a failure of talent or discipline. It's a failure of context.
Architecture decision records changed everything
The single most effective practice I adopted was architecture decision records — short, written documents that capture not just what was decided, but why, and what alternatives were considered and rejected.
The format is simple. A title, the context that prompted the decision, the options we considered, the decision we made, and the consequences we expected. Each one is a page or less. They live in the codebase alongside the code they govern, not in a wiki that nobody reads.
What made these transformative wasn't the format. It was what they did to the organisation. When a new engineer joined the team and asked “why does this work this way?”, the answer wasn't a tribal knowledge conversation that depended on who happened to be available. It was a document they could read independently, at their own pace, with the full reasoning laid out. When a tech lead proposed a change to an existing pattern, the discussion started from the original decision record: “Here's why we made this choice. Has the context changed enough to justify a different one?”
That second use was the more valuable one. But without a record of the original reasoning, you can't have that conversation productively. You're arguing about whether to change a decision without understanding why it was made. I've sat in too many meetings like that. They generate heat without light.
The discipline of writing decision records also improved the decisions themselves. When you know you have to articulate the reasoning, capture the alternatives, and name the trade-offs, you think more carefully. Decisions that would have been made casually in a hallway conversation become more rigorous when they need to be written down. That's not bureaucracy — it's clarity.
There's a second-order benefit that's becoming increasingly relevant, and it extends beyond decision records to every practice in this article.
Your architecture's next reader isn't human
Every practice I've described — decision records, lightweight architecture documentation, explicit domain models, clear reasoning captured alongside the code — was developed to solve a human problem: getting 40 engineers to share a mental model at scale.
It turns out these same practices solve an AI problem too.
AI-assisted development is no longer speculative. Engineers are using AI tools to generate code, triage incidents, review pull requests, and propose design changes. Through my work on the Model Context Protocol, I see what these tools actually need from the systems they interact with: context.
An agent triaging an incident can only reason about the failure if the service boundaries, data ownership, and integration contracts are documented. An agent proposing a design change can only evaluate whether it's consistent with the broader architecture if the reasoning behind existing decisions is explicit.
When that context lives in people's heads — in tribal knowledge, in hallway conversations, in the accumulated intuition of engineers who've been there since the beginning — AI tooling is flying blind. It generates code that works but violates domain boundaries. It proposes designs that are locally sensible but architecturally inconsistent. It becomes another source of the well-intentioned local decisions that erode the system over time.
When the context is written down — in decision records, in architecture documentation, in explicit domain models — AI tooling becomes dramatically more effective. It works within the architecture rather than against it. The investment in legibility that you made for your human engineers compounds again, for every AI tool that reads your codebase.
This isn't a reason to start writing things down. The human reasons are sufficient. But it means that organisations who've been disciplined about making architecture explicit are discovering they've built an AI-readiness advantage they didn't plan for. And organisations that relied on tribal knowledge are discovering that AI adoption exposes the same legibility gaps that made onboarding slow and architectural erosion inevitable.
The tech lead layer
At five to ten engineers, the architect can be involved in every significant design decision. At forty, that's not possible. The bottleneck isn't time — it's context. A single architect can't hold enough context about every part of a large system to make every decision well. They shouldn't try.
The answer I found was investing heavily in the tech lead layer. Each team of five to eight engineers had a tech lead who was responsible for the design decisions within their team's domain. These weren't junior engineers given a title — they were senior engineers who understood the overall architecture well enough to make local decisions that were consistent with it.
Building this layer was the highest-leverage leadership investment I made. It meant spending significant time with tech leads: reviewing their design decisions, explaining the reasoning behind architectural choices, walking through how their domain fit into the broader system. It looked like mentoring, but it was really architecture distribution — creating multiple people who could hold the mental model and apply it locally.
The practical mechanics: weekly architecture syncs with the tech lead group, not to approve their decisions but to share context. What's changing in the system. What constraints have shifted. What patterns are emerging across teams. These weren't governance meetings — they were context-sharing sessions. The tech leads went back to their teams with a current understanding of the broader system, and their teams made better local decisions as a result.
The failure mode I saw in other organisations was centralising design authority in a single architect or architecture team. The intent is consistency, but the effect is bottleneck. Teams wait for architecture approval. The architect becomes a single point of failure for design decisions across the entire system. Decision velocity drops. Worse, the teams stop thinking architecturally because they've learned that those decisions aren't theirs to make. You end up with 40 engineers who can execute but can't design — and an architect who's drowning.
The architecture stayed coherent because the people making decisions understood it. Decisions happened at the speed of the team rather than the speed of a single architect's calendar.
What onboarding reveals about your architecture
I started treating onboarding as an architecture health check. When a new engineer joins and gets productive within two weeks, the architecture is legible. When it takes two months and requires constant hand-holding from senior team members, the architecture has problems that aren't visible in the diagrams.
The gap is almost always the same: the system's behaviour can't be understood from the code and the contracts alone. There's implicit knowledge — conventions, patterns, reasons — that isn't captured anywhere. New engineers stumble not because the system is complex, but because the complexity isn't explained.
Decision records helped with the “why.” But there was a complementary practice that helped with the “how”: lightweight architecture documentation that described the system at the level of data flow, service interaction, and domain responsibility. Not comprehensive design documents — those go stale immediately. Short, high-level descriptions of how the major parts of the system relate to each other, updated when the relationships change.
The test I used: can a senior engineer read this documentation and the relevant decision records, and then correctly predict where a new feature should be built and which services it should touch? If yes, the documentation is sufficient. If no, there's implicit knowledge that needs to be made explicit.
This sounds like overhead. In practice, it reduced overhead dramatically. Every hour spent making the architecture legible saved multiple hours of one-on-one explanations, corrected design decisions, and refactoring work when someone built in the wrong place because they didn't understand the system well enough.
Architecture as a leadership practice
The technical dimension of architecture at scale is well served by existing literature. Domain-driven design, service decomposition, event-driven patterns, API design — the patterns are documented, debated, and broadly understood. What's less well documented is the organisational dimension: how you get 40 engineers, across multiple teams, working inside a coherent architecture over months and years.
What I learned is that architecture at scale is a leadership practice as much as a technical one. The system design matters, but it's the easier problem. The harder problem is creating the conditions where dozens of engineers, most of whom weren't in the room when the decisions were made, can understand the architecture well enough to make good local decisions that serve the whole.
That means writing things down — not as documentation for its own sake, but as context that scales beyond the people who were there. It means investing in tech leads who can hold and apply the mental model locally, rather than centralising design authority and creating a bottleneck. It means treating onboarding as feedback on whether the architecture is legible, not just whether the new hire is capable. And it means accepting that an architecture that can't be explained simply enough for a new team member to understand within weeks is an architecture that will erode, no matter how elegant the original design.