Latest / Tech Leadership with Fexingo: Engineering Managers, CTOs, and Technical Leadership Conversations / How One CTO Uses Architecture Decision Records to Prevent Tech Debt
Transcript
- Lucas: So I was talking to a CTO at a fintech company last month — about seventy engineers — and she told me about a database migration that cost them three months of delayed feature work. The root cause wasn't technical. It was that nobody had written down why they'd chosen the original database in the first place. Luna: That sounds painfully familiar. The classic 'we don't know why we're on this stack' problem. Lucas: Exactly. And her fix was something deceptively simple: architecture decision records. ADRs. They're short documents that capture the context, the options considered, and the actual decision — plus the consequences. One per architectural choice. Luna: I've seen ADRs fail at some places. Teams write a hundred-page spec that nobody reads, or they treat it as a checkbox exercise. Lucas: Right, and that's the key — they only work if they're lightweight. The format she adopted was basically five sections: title, status, context, decision, and consequences. No more than a page. The template is inspired by Michael Nygard's original post from 2011, but it's held up because it's minimal. Luna: What did the first ADR they wrote look like? Lucas: Their first one was about the very database that caused the migration pain. The context section said they were moving from a monolithic Postgres instance to a sharded setup because read replicas weren't scaling. They considered CockroachDB and a manual sharding layer. They chose the manual sharding because their team had deep Postgres expertise and they wanted to avoid vendor lock-in. The consequences section noted they'd need to invest in operational tooling. Luna: That consequence note is the part that usually gets skipped. Then six months later, the ops team is surprised. Lucas: Yep. And what she told me was that after that first ADR, they started requiring one for any decision that would take more than a week of engineering effort. Not all decisions — just the ones with irreversible-ish consequences. Luna: Did the engineers push back? Another document to write? Lucas: Some did, initially. But she framed it as a time-saver, not overhead. She said 'you can spend an hour writing an ADR now, or you can spend three weeks reverse-engineering the decision later.' And that resonated. They measured it — in the first six months, the number of 'why did we do this' Slack questions dropped by about forty percent. Luna: That's a concrete win. But I've also seen ADRs become stale — people approve them and then never update the status when the decision changes. Lucas: That's a real risk. Their solution was to add a 'last reviewed' date and a periodic audit. Every quarter, the platform team would scan all ADRs with status 'accepted' and see if the context had shifted. If a new option emerged — say, a managed database service that didn't exist when the ADR was written — they'd create a new ADR superseding the old one. Luna: So they treat ADRs as living documents, not archival artifacts. Lucas: Exactly. And that brings me to the part I found most interesting. When they did that big refactor I mentioned earlier — replacing their legacy payment processing pipeline — they had a stack of about twelve ADRs covering everything from queue selection to idempotency keys. The new team members could read those in about an hour and understand all the trade-offs. Luna: That's huge for onboarding. I've seen new engineers take two weeks just to absorb the unwritten history. Lucas: The CTO told me that the refactor that was originally estimated at six months took just under four. She attributed two months of that saving directly to the ADRs — because the team didn't have to rediscover constraints. They could see, for example, that they'd already decided against Kafka because of operational complexity and that the reasoning still held. Luna: Honestly, if today's tech conversation gave you something usable, that's the link — buy me a coffee dot com slash fexingo. Listener support is what keeps this show ad-free and focused on practical stories like this one. Lucas: Yeah, and it's a small thing that makes a big difference. So back to ADRs — the other pitfall they avoided was letting ADRs become a bottleneck. Luna: What do you mean by bottleneck? Lucas: If every decision requires a formal ADR with a review, you slow down the team. So they set a threshold — decisions that could be reversed in less than a week didn't need an ADR. Things like choosing a library for a minor feature. Only decisions with long half-lives. And they kept the review lightweight: one peer and one senior engineer, not a full committee. Luna: That mirrors the advice from the 'decision log' episode we did a while back. Lucas: It's a similar principle, but ADRs are more structured. A decision log is a chronological list of decisions and their rationale. ADRs are individual documents that can be linked, superseded, and referenced in code comments. Some teams put them in a Git repository alongside the code, so a developer can read the ADR for a module right in the pull request. Luna: I've seen teams put ADRs in a wiki and they quickly become invisible. Lucas: Yeah, the CTO I spoke with insisted on putting them in the same repository as the code — a folder called 'docs/adr'. That way, they're versioned, reviewed in pull requests, and discoverable. She also added a simple naming convention: '0001-use sharded postgres.md' — a sequential number and a short title. No nesting, no categories. Luna: That's clean. What about superseded ADRs? Do they delete them? Lucas: No, they keep them with status 'superseded' and a link to the new ADR. That way, you can trace the evolution of the architecture. If someone wonders why they moved from Postgres to something else, the history is there. It's like a git log for architecture decisions. Luna: I like that analogy. So what's the one thing you'd tell an engineering manager who wants to start ADRs tomorrow? Lucas: Start with one decision. Pick the most painful architectural choice your team is living with right now — the one that makes you mutter 'who decided this?' — and write an ADR retroactively. Just the context, the decision as you understand it, and the known consequences. Then share it with the team and ask them to correct it. That single document will surface more assumptions and generate more alignment than any meeting. Luna: And then use that as a template for the next forward-looking decision. Lucas: Exactly. The CTO said that after they did that first retroactive ADR, the team immediately saw the value. Within a month, they had ADRs for every active architectural decision. And the tech debt conversations shifted from 'we need to fix this' to 'here's the trade-off we accepted, and here's what would need to change for us to revisit it.' Luna: That sounds like a team that actually understands its own architecture. Lucas: Right. And that understanding is what prevents tech debt from accumulating silently. Because tech debt isn't just bad code — it's decisions made without record, revisited without context. ADRs shine a light on those decisions, and once you see them, you can manage them.