The Architecture of Agreements: Why Great Systems Are Built on Promises, Not Code
We often mistake the map for the territory. In system design, the map is the code, the services, the data models. We think this is the architecture. But the real territory is the messy, human space between teams. The most resilient, scalable systems aren’t built on technology; they’re built on the fragile, critical agreements that allow people to work independently without breaking each other’s work.
For years, I kept finding myself building the substrate on which other teams would build. Decomposing a monolith, designing an event-driven framework—I didn’t have a name for it. I just saw a problem, broke it down, and started building. Looking back, I realize I wasn’t just building technical systems. I was building social systems. The most critical part of my work wasn’t the code; it was the promises between people that the code had to keep.
The real architecture isn’t defined by deployment patterns; it’s defined by the set of promises that allow teams to move with autonomy. The code is just the physical manifestation of a much more important system: the agreements.
From First Principles to Foundational Truths
My approach has always been to work from first principles. When faced with a complex problem, I don’t look at what other companies are doing. I ask, “What is the fundamental problem we are trying to solve, and for whom?” This isn’t a methodology; it’s just how my brain is wired.
When we needed to free ~10 product teams from a serialized release queue, the first-principles answer wasn’t “let’s adopt microfrontends.” The problem was autonomy. The architecture was simply the best tool we had to formalize that agreement. When we needed to prepare for enterprise scale, the answer wasn’t “more servers.” The problem was reliability at scale. The event-driven framework was the mechanism to honor that promise of isolation.
I treated the OpenAPI spec as the source of truth itself. If the contract defines the agreement between two teams, then the contract is the product. The code is just an implementation of that shared promise. It seemed obvious. What’s changed for me isn’t how I think, but my ability to articulate why. I’ve learned to put a label on the instinct. The label is “agreements.”
The Fragility of Trust
An agreement is fundamentally different from a technical system because its foundation isn’t logic; it’s trust. And trust is a notoriously fragile resource.
A broken API endpoint is a technical problem. A broken contract is a social one. If you deploy a change that violates your API’s contract, you haven’t just introduced a bug. You have broken a promise. The downstream team isn’t just dealing with a failed request; they’re dealing with a violation of their understanding of the system. The damage isn’t measured in downtime; it’s measured in lost confidence and increased friction. Every broken promise makes the next one harder to keep.
This is why so many well-intentioned system initiatives fail. They focus on the technical implementation while neglecting the social architecture. They ship the code without shipping the agreement. The result is a system that is technically sound but organizationally brittle. It works until it doesn’t, and when it breaks, the fix isn’t a code patch; it’s a series of meetings and a slow, painful erosion of trust.
Designing for Autonomy
So, if our job is to build these agreements, what makes a good one?
A well-designed agreement creates autonomy. It acts as a “social shaping tool,” creating a predictable environment where teams can make decisions locally without constant coordination.
Think of it like traffic laws. The agreement—that we all stop at red lights—isn’t a technical constraint on your car’s engine. It’s a social contract that allows millions of individual drivers to navigate a complex system safely and efficiently. The rule creates freedom.
Good system agreements do the same. They give teams the confidence to build and deploy features because they trust that the underlying systems will behave as promised. Your design system’s promise of accessibility means a team can build a new form without consulting an expert. Your API’s promise of backward compatibility means a team can upgrade their library without fear of breaking their app. Your CI/CD pipeline’s promise of quality gates means a team can merge a PR at 5 PM on a Friday and sleep soundly.
This is the goal: to create a system where teams don’t have to ask for permission. They just have to follow the agreement.
The Mechanics of Agreement
If this sounds abstract, let’s get concrete. How do you build an architecture of agreements?
Write It Down. An unwritten agreement is just an assumption. The first step is to formalize the contract. Use OpenAPI for APIs, Storybook for components, RFCs for major changes. The medium matters less than the act of making the promise explicit and discoverable.
Make It Easy to Keep. The best agreements are the ones that are easy to follow. If your API contract requires teams to manually version a dozen fields on every change, the contract will fail. Not because teams are malicious, but because you designed a fragile system. Your job is to make the path of compliance the path of least resistance. Automate validation. Generate type definitions from your specs. Make the “right” way the easiest way.
Make Breaking Hard. If keeping the promise is easy, breaking it should be hard. This is where your technical skills finally come into play. Build tooling that enforces your agreements. Use contract tests that fail when the implementation doesn’t match the spec. Make breaking changes a visible, painful, and deliberate process, not an accidental side effect of a refactor.
Evolve with Empathy. Agreements aren’t static. They need to evolve without breaking the trust they’re built on. This means treating your consumers as partners. Talk to them. Understand their pain points. Frame changes as additions, not replacements. And when you do need to break a promise, do it transparently, with a long deprecation window and a clear migration path. You are not just changing code; you are renegotiating a relationship.
Even the mechanism for feedback is part of the agreement. When a team inevitably violates a contract, the conversation that follows either reinforces or erodes the trust. A code review that frames the fix as an impersonal, specific, and temporary blip reinforces the agreement; it treats the broken promise as a temporary deviation from a positive arc. A review that criticizes the person breaks it. The social contract we use to discuss our technical contracts is just as important as the code itself. I’ve written about this specific model for optimistic feedback in code reviews, which provides a practical framework for maintaining these human relationships even when things go wrong.
The Real ROI
When you start thinking this way, you change what you optimize for. You stop measuring system success by adoption rates and start measuring it by team autonomy. You stop celebrating new features and start celebrating frictionless collaboration.
The ultimate return on investment for a foundational engineer isn’t faster builds or smaller bundles. It’s the number of decisions that don’t require a meeting. It’s the confidence a team feels when they ship a feature that touches three different shared systems. It’s the absence of a frantic Slack message at 2 AM.
That’s the architecture you’re really building. It’s an architecture of trust, of predictability, and of human-scale interaction. The code is just the scaffolding. The promises are what hold it all together.