Latest / The CTO Podcast with Fexingo: Technical Leadership, Architecture, and Engineering Org / How Figma Killed Technical Debt With Architecture Contracts
Transcript
- Lucas: If these conversations are useful for what you're building or running right now, a couple of dollars a month is genuinely what keeps these going. You can find us at buy me a coffee dot com slash fexingo — that's F. E. X. I. N. G. O. Luna: Yeah, and honestly, it’s the small contributions that let us keep this ad-free and focus on the deep dives you actually want to hear. Lucas: Exactly. It makes a difference. Now, let's get back into the weeds. We've talked a lot about technical debt over the last few weeks, usually framing it as a code problem. But I think we've been looking at it backward. The real issue isn't the code itself; it's the lack of formal agreements between engineering teams about how those pieces fit together. Luna: So you're arguing that technical debt is really just broken communication? That feels like a stretch, even for you. Lucas: Not broken communication. Unwritten expectations. Think about the last time your team had to integrate with another group's API. Did you have a clear understanding of their uptime guarantees? Their deprecation policy? Or did you spend three weeks guessing how they might change things under the hood? Luna: I remember working with a payments provider where their schema changed without notice, and it took our entire sprint to fix the downstream effects. It was a nightmare. Lucas: That is the textbook example of what happens when you don't have an architecture contract. An architecture contract is essentially a service-level agreement between internal teams. It defines the boundary, the inputs, the outputs, and the consequences if one side fails to hold up their end. It turns vague dependencies into enforceable rules. Luna: But doesn't adding contracts slow down development? If I have to sign off on every interface change, aren't I just creating more bureaucracy? Lucas: That's the common fear. But look at how Figma handled this transition. They didn't add contracts to slow people down; they added them to speed people up. By defining the boundaries clearly, they gave each team the autonomy to move fast within those lines. No more waiting for permission to change an internal tool because the contract already said you could. Luna: So the contract acts as a guardrail rather than a gatekeeper. That makes sense, but how do you actually write one of these things? Is it a legal document? Lucas: It's not legal, but it needs to be treated with similar seriousness. At its core, an architecture contract has three parts. First, the functional spec: what exactly does this service do? Second, the non-functional constraints: latency, availability, data retention. And third, the evolution clause: how will changes be communicated and deprecated? Luna: The evolution clause sounds like the hardest part. How do you force a team to respect a deprecation timeline when they're under pressure to ship new features? Lucas: You make it part of their performance metrics. If a team breaks a contract, it's not just a bug; it's a violation of trust. Figma implemented this by linking architectural compliance to their engineering review process. You can't merge a change that violates the contract without explicit, documented override from the owning team. Luna: That sounds powerful. But who owns the contract? Is it the CTO? Or is it the team that built the service? Lucas: The team that built the service. That's crucial. If the central IT department writes the contract, it becomes a bottleneck. The owning team has to define their own boundaries. This shifts the culture from 'compliance' to 'ownership'. They become experts in their own domain, responsible for the reliability of their slice of the pie. Luna: I see. So it's less about policing and more about professionalizing the interfaces between teams. It forces engineers to think about their product as if it were external. Lucas: Precisely. It creates psychological safety too. When I know my contract is solid, I can sleep at night knowing that if my upstream provider fails, I'm covered by the terms. I don't have to constantly monitor their codebase. I just monitor the SLA. Luna: That's a huge relief for senior engineers. But what about smaller companies? Do they need this level of formality before they hit scale? Lucas: This is where it gets tricky. In a ten-person startup, everyone talks face to face. A written contract feels like overkill. But as soon as you hit fifty people, or multiple locations, the oral tradition breaks. That's when the debt starts accumulating. You don't need a lawyer-grade document, but you do need a README that functions as a contract. Luna: So the maturity model is key here. You start with documentation, then you formalize the SLAs, and finally you automate the enforcement through CI/CD pipelines. Lucas: Spot on. Automation is the only way to make this sustainable. Humans will forget to check the SLA. But a pipeline can reject a pull request if the new endpoint violates the defined schema. It removes the human element of conflict. The machine says no, not the manager. Luna: I love that. It depersonalizes the disagreement. It becomes a technical fact rather than an opinion. Lucas: Right. And it scales. You can have hundreds of microservices, each with its own contract, all enforced automatically. This is how large platforms manage complexity without collapsing under the weight of their own dependencies. Luna: Let's talk about the cost of implementation. How long does it take to retrofit this onto an existing messy codebase? Lucas: It's not a big bang project. You start with the highest-traffic interfaces. Identify the three services that cause the most outages. Write contracts for those first. Then iterate. It's an evolutionary process. You'll see immediate wins in stability, which buys you the credibility to expand the program to other areas. Luna: And what happens when two teams disagree on what the contract should say? Like, one team wants strict typing, the other wants flexibility. Lucas: That's a negotiation. It's not uncommon. The key is to have a neutral arbiter, usually a principal engineer or an architect who isn't biased toward either side. They help the teams find the middle ground. But ultimately, both teams have to agree. You can't impose a contract on someone who won't use it. Luna: So it's a diplomatic process as much as a technical one. You're building relationships, not just writing specs. Lucas: Absolutely. The best architecture contracts are born from collaboration. If Team A helps Team B design their interface, they're more likely to respect it later. It fosters a culture of mutual aid rather than siloed hoarding. Luna: That's a nice vision. But in reality, engineering teams are often competing for resources. Would they really collaborate on something that might constrain their future work? Lucas: They will if they understand the alternative. The alternative is spending 40 percent of their time debugging other people's mistakes. Most engineers hate that. If you show them that contracts save them from firefighting, they'll embrace them. It's about self-interest, aligned with the company's interest. Luna: So it's a win-win. Less time fixing bugs, more time building features. Why wouldn't every company adopt this? Lucas: Because it requires discipline. It requires leaders to enforce the standards even when it's inconvenient. It's easy to ignore a contract when you're rushing to launch a feature for a VIP client. But that's exactly when you shouldn't. That's when the debt compounds. Luna: Right. Short-term speed vs. long-term sustainability. It's the classic trade-off. Contracts tip the scale toward sustainability. Lucas: Exactly. And once you tip that scale, the compound interest works in your favor. Velocity increases because you're not blocked by ambiguity. Innovation accelerates because you have stable foundations to build on. Luna: It sounds like the ultimate productivity hack. Stop fighting your infrastructure and start governing it. Lucas: Governing it with clarity. Look, if you're leading a team of more than twenty people, I'd challenge you to write one architecture contract this week. Just one. For your most critical dependency. See how it changes the conversation. Luna: I might just try that with our billing service. It's always been a source of friction. Let's see if a simple agreement can tame the beast. Lucas: Do it. And report back. Because the next time we talk, I want to hear whether that single contract changed the dynamic of your entire engineering org. Luna: Deal. It's worth a shot if it means fewer 3 AM pages. Lucas: Fewer pages, more peace of mind. That's the goal. Thanks for listening, and let's keep building smarter.