Latest / Tech Leadership with Fexingo: Engineering Managers, CTOs, and Technical Leadership Conversations / How a CTO Uses Architecture Decision Records
Transcript
- Lucas: Alright, so today I want to talk about something that sounds boring on paper but is actually one of the highest-leverage things a CTO can do: Architecture Decision Records. ADRs for short. Luna: I've heard the term thrown around. Basically, you write down why you made a specific architectural choice, right? Lucas: Exactly. And it sounds trivial, but the impact is huge. I was talking to a CTO at a fintech company — about 150 engineers, growing fast — and he told me that before they started using ADRs, they had the same debate about their database choice every six months. Luna: Every six months? That's brutal. Lucas: Every single time a new senior engineer joined, someone would question why they were on PostgreSQL instead of something else, and they'd spend three weeks re-litigating a decision that had been made two years earlier. No documentation, no context, just tribal knowledge. Luna: So ADRs are basically insurance against organizational amnesia. Lucas: That's exactly the right framing. An ADR is a one- to two-page document that captures the context, the alternatives considered, the decision, and the rationale. It's not a novel — it's structured and it's short. Luna: What's the typical template? I've seen variations. Lucas: The standard template has a few sections: title with a number and date, context — what's the problem we're solving? — then options, decision, rationale, and consequences. Consequences are key: what trade-offs are you accepting? Luna: And you version them like code? Lucas: Exactly. They live in a folder in your repository, usually called 'docs/adr'. Each ADR gets a unique number, and you can supersede an older ADR with a new one. So you have a complete, auditable history of every major architectural decision. Luna: I can see how that helps onboarding. New engineer joins, reads the ADRs, and immediately understands why things are the way they are. Lucas: It's probably the biggest payoff. That fintech CTO said their onboarding time for new staff engineers dropped from about three weeks to under one week, specifically because they didn't have to re-explain the 'why' behind every system. The ADRs did it for them. Luna: But there's a danger, right? ADRs can become shelfware. People write them once and nobody ever reads them again. Lucas: That's the number one objection I hear. And it's real. But the fix is to make ADRs part of your workflow, not a separate chore. If you treat ADRs as something you do after the decision is made, they'll rot. Instead, you write the ADR as you're making the decision. Luna: So it's a tool for the decision process, not just documentation after the fact. Lucas: Right. The act of writing forces you to articulate your assumptions, surface alternatives you might have overlooked, and be explicit about trade-offs. I've seen teams discover a better option just by writing down what they were about to decide. Luna: Okay, give me a concrete example. What does a good ADR look like? Lucas: So imagine a team deciding between using a relational database and a document store for a new service. Their ADR would start with context: we need to store user profiles with variable attributes, and we expect high read volume but low write volume. Luna: Then the options: PostgreSQL with JSONB, MongoDB, DynamoDB. Lucas: Exactly. And then you evaluate each against specific criteria — consistency requirements, operational overhead, team familiarity. The decision might be PostgreSQL with JSONB because the team knows it well and you don't need horizontal scaling yet. The rationale is concrete, not hand-wavy. Luna: And the consequences section would say something like: we accept that JSONB queries are less performant than native document stores for deeply nested queries, and we'll revisit when volume grows. Lucas: Beautiful. That's the whole point. Now two years later, when someone asks 'why aren't we using MongoDB?' you point them to ADR-0042 and they can see the reasoning. They might disagree, but at least they know the context. Luna: And if conditions change — say, you start doing a lot of deeply nested queries — you can write a new ADR that supersedes the old one. Lucas: Exactly. And that's how you avoid the trap of 'we've always done it this way' — you explicitly acknowledge that the decision was context-dependent and now the context has shifted. Luna: So when should you write an ADR? Every decision? Lucas: No. That's a mistake I see sometimes — people try to ADR everything and they burn out. The rule of thumb is: write an ADR for any decision that is costly to reverse or has significant downstream impact. Choosing a database, choosing an API style, choosing a deployment strategy. Not which color button to use. Luna: There's a term for that — the 'irreversibility threshold'. If it would take more than a week to change your mind, write an ADR. Lucas: That's a great heuristic. The fintech CTO I mentioned actually uses that exact rule. If a decision would take longer than a week to undo, it gets an ADR. Otherwise, it's fine to just make the call and move on. Luna: I also love that ADRs create a culture of written reasoning rather than verbal authority. It's harder to argue with a document than with someone saying 'trust me, I'm the CTO.' Lucas: Yeah, and it flattens the hierarchy. A junior engineer can propose an ADR and have it stand or fall on its reasoning, not on their title. I've seen some of the best architectural decisions come from unexpected places because of that. Luna: Alright, but let's address the elephant in the room. How do you get engineers to actually write them? Engineers hate documentation. Lucas: They hate bad documentation. If you make ADRs a lightweight template that takes 30 minutes to fill out, and you make it part of the pull request review process — the PR for the change must include a link to the ADR — it becomes a habit. Luna: And you have to model the behavior. If the CTO or the lead architect doesn't write ADRs, nobody will. Lucas: Hundred percent. The fintech CTO told me he wrote the first ten ADRs himself, even for small decisions, just to establish the pattern. After that, the senior engineers started writing them, and within a quarter it was just how they operated. Luna: I've also seen teams use ADRs as a way to document not just what they decided, but what they explicitly decided not to do. That can be just as valuable. Lucas: Absolutely. The 'rejected alternatives' section is gold. It saves future teams from exploring the same dead ends. I was at a company once where a team spent three months building a microservice on a certain message queue, only to discover it didn't meet their latency needs. If they'd had an ADR from a previous team that had evaluated that same queue and rejected it, they could have saved those three months. Luna: And that story — three months of wasted work — is exactly why ADRs matter. It's not just about documentation; it's about velocity. Lucas: Right. And it's scalable. As your team grows, you can't rely on everyone knowing the same history. ADRs preserve institutional knowledge without requiring anyone to sit through a two-hour meeting. Luna: You know, speaking of things that preserve value over time — if today's tech conversation gave you something usable, we'd love it if you'd consider supporting the show. It's what keeps this whole thing ad-free and focused on practical stuff like ADRs. Lucas: Yeah, it's a small gesture, but it genuinely helps us keep going. If it was worth a coffee to you, that's the link: buy me a coffee dot com slash fexingo. Luna: And honestly, even just knowing people find it useful — that's the main thing. Okay, back to ADRs. Lucas: So one more thing I want to touch on: ADRs are also great for external audits. If you're in a regulated industry, having a clear record of why you made certain security or compliance decisions can be a lifesaver. Luna: Right, auditors love seeing that you've documented your reasoning, especially around data handling and encryption. Lucas: Exactly. The fintech CTO I mentioned said their SOC 2 audit went much smoother once they had ADRs covering all their key architectural decisions. The auditors could just read the documents instead of interviewing engineers. Luna: So ADRs help with onboarding, decision quality, team alignment, and audits. That's a pretty good ROI for a 30-minute document. Lucas: It's one of those practices that sounds too simple to be powerful, but it really is. The key is just starting. Write one ADR this week for the next architectural decision you face. Don't overthink the template. Just capture the context, options, decision, and rationale. Luna: And if you've already got a system in place, maybe take a look at your last few big decisions and see if you can write ADRs retroactively. It's never too late to start. Lucas: Great point. I'd even argue that retroactive ADRs can be more valuable because you already know the consequences. You can be very precise about why things turned out the way they did. Luna: Alright, so to wrap up: ADRs are a lightweight tool to capture architectural decisions, they prevent recurring debates, speed up onboarding, and create a searchable institutional memory. Start small, make it a habit, and you'll wonder how you ever managed without them. Lucas: And for our listeners, we'd love to hear if you've tried ADRs or if you have a different system. You can find us on the Fexingo Business podcast network. I'm Lucas. Luna: And I'm Luna. See you next time.