ADRs as a personal tool, then a team one
Notes on a habit that kept changing audiences.
Over a decade ago, I read an article by Michael Nygard about Architecture Decision Records and decided to try one. I wrote it on a project I no longer work on, about a problem I no longer remember, for a future version of myself who would eventually forget — which, looking back, was the entire point.
I've been writing ADRs ever since. What's strange is that the document has barely changed across those years, but my reasons for writing it have changed almost beyond recognition. This is a post about that shift, and about what an ADR turned out to be — once I stopped writing it just for myself, and later, once I started writing them with something other than humans in mind.
Writing decisions before anyone else read them
For the first few years, I wrote ADRs alone, for myself. There was no template, no review process, no audience beyond the version of me who would inevitably forget. Most weren't even in shared repositories — they lived in personal notes, side-project folders, scratch directories on machines I no longer own.
The format was whatever I felt like that day. Sometimes a few paragraphs. Sometimes just the question, the answer, and a quick note about what I'd considered and rejected. Nygard's structure was somewhere in my head, but I rarely followed it strictly — I was writing for an audience of one, and that audience already knew the project.
What surprised me was how often I came back to those notes. Sometimes weeks later, sometimes months. A choice about how to structure a small library, made in twenty minutes on a Tuesday, would resurface when I started something similar later. Without the note, I'd have remade the same decision from scratch, probably worse. With the note, I had a starting point — and a record of what I'd already rejected.
Most introductions to ADRs skip this phase. They start with teams, stakeholders, alignment — which is fair, because that's where the practice has the most impact. But I notice now that the habit, for me, started earlier and quieter than that. Before I ever wrote one for someone else, I'd been writing them for myself.
At some point I suggested to the team that we adopt the practice together. The reasoning wasn't dramatic — I'd been writing these notes for myself for years, they'd been useful, and I'd started to notice that some of the discussions we kept rehashing in PR reviews were discussions I'd already resolved on paper, just not on shared paper. Without a written decision, an argument in a review easily turns into a clash of preferences — I'd rather we did it this way. With one, the discussion has an anchor. "We decided this in ADR-X" doesn't end the conversation, but it changes its shape: instead of relitigating the choice in every PR, the discussion either accepts the existing decision or makes a deliberate case for revisiting it.
Writing an ADR meant for the team turned out to be a different exercise than writing one for myself. The reasoning had to be explicit, not just remembered. The alternatives I'd considered and rejected needed to actually appear on the page, because the reader couldn't see them in my head. The tone shifted too — the notes I wrote for myself were sometimes terse to the point of being cryptic, but a shared note needed to make sense without me there to explain it.
On the surface, the document hadn't changed much. Underneath, it was now answering to a different reader.
A practice that worked, until it didn't
The team practice deepened over several years. I wasn't in a formal lead role at the time — I was a senior developer, and ADRs had become a natural part of how I worked with the rest of the team. The format I used became more disciplined, the cadence more regular, and the kinds of decisions worth documenting shifted — fewer small library choices, more architectural calls, more cross-cutting concerns. What surprised me most about that period wasn't how I used ADRs myself, but how the ADRs I didn't write started to matter. A colleague drafting a decision and bringing it to review was no longer a curiosity; it was the goal.
Decisions also started to live longer than I'd anticipated. ADRs from a year earlier showed up in design discussions; "superseded" became a status I used regularly. The document was no longer just a record of what we'd decided — it was a record of how our thinking had moved.
When I changed teams and joined a larger organisation, I came in as a developer, not as a lead. The team I joined had its own way of documenting decisions — a custom format that had been there long before I arrived, and that I won't get into here. For the first couple of years, I made a soft case for switching to standard ADRs — more direct, more recognizable, less idiosyncratic. I didn't push harder than that; I wasn't in a position to, and the existing format still mostly worked. The case never landed.
Some time later I moved into a tech lead role, but the format question didn't immediately resurface. By the time it did, the situation had changed: the existing format was visibly struggling, decisions were getting harder to track, and a significant new architecture project was about to put real pressure on the system. I brought up ADRs again — this time addressed to the engineering managers and tech leads, since the conversation was about how we documented decisions across the organisation. The pitch was less about my preferences and more about preferring a recognized standard over maintaining yet another custom artefact.
The first ADR I wrote in this new context was a cross-platform architecture proposal, co-written with my counterpart on the iOS side. We had pseudocode, architecture diagrams, and what we thought was a clear case. Between us, we had years of experience writing this kind of document. I thought I knew what I was doing.
Not everything in those years went the way I'd have wanted. There's a specific ADR that left me with a lot to chew on — too recent to write about cleanly here, and the people involved deserve more distance before I do. But what I took from it, in the end, was less about the specific decision than about a set of conditions that I've come to recognize since, in my own work and in conversations with others.
The first condition is that ADR review processes rarely define how closure actually happens. A document is drafted, comments accumulate, the comments eventually slow down — and the ADR is marked accepted. But "comments slowing down" can mean two very different things. It can mean people have converged on a shared answer, or it can mean people have run out of energy to keep objecting. The status field doesn't distinguish between the two. From outside the conversation, they look the same.
The second condition is that an ADR doesn't have full control over where the conversation actually happens. The official channel is the document — comments, suggestions, structured review. But the real conversation has a habit of migrating: into DMs, hallway exchanges, side meetings, Slack threads the author isn't in. From inside the ADR, this migration is invisible. The document looks like it's calming down, when in fact the disagreement has simply moved somewhere the author can't see. And when an ADR can't close on its own — when the comments keep going or the author keeps redrafting — the organisation tends to invent another channel to force closure: usually a meeting, often run by someone higher up. The decision that emerges from that meeting isn't really the ADR's decision. It's a separate decision, recorded into the ADR after the fact. The document captures the outcome, but it didn't produce it.
The third condition is subtler, and I think it's the one I underestimated most. A document several people have read appears to produce a shared understanding. In practice, each reader fills the document's ambiguities with their own assumptions, and those completions can diverge significantly without anyone noticing. Two engineers can walk away from the same approved ADR with different mental models of what was decided. The disagreement doesn't show up during review — it shows up later, in the implementation.
What ties these conditions together, I think, is that they all blur a distinction the ADR format implicitly relies on but doesn't enforce: the distinction between approval and decision. Approval is a state of the document. Decision is a state of the people — and the people sometimes decide elsewhere. The ADR format is good at recording the first. It assumes the second has happened, but it can't tell.
The question of formats came up again later, in a different team and a more formal role. The context was complicated — there was already a custom way of documenting decisions in place, with its own history and its own users, and I found myself proposing standard ADRs once more, with no clear outcome yet. That part of the story is still unfolding, and I won't pretend I've resolved it. It deserves more space than I can give it here. I plan to come back to it in another post.
When the readers stopped being only human
The most recent shift came from somewhere I hadn't expected. Over the last couple of years, large language models have changed two things about how I work with ADRs — and they've changed them in opposite directions.
The first change is in how I write them. I've gotten into the habit of running a draft past a model before sending it to human review — first to clean it up, then to push back on it. The model isn't a particularly imaginative reviewer, but it's reliably available, it doesn't carry social cost, and it's perfectly happy to argue with my reasoning without taking anyone else's time. What I've found, mostly, is that the document that goes to human review is better than what I'd have produced alone — not because the model wrote it, but because it disagreed with me first. The humans who review it afterwards spend their attention on the real points of contention, not on the gaps I could have closed myself. I plan to come back to this workflow in more detail in another post.
The second change runs the other way. Once you have a project with a meaningful set of ADRs in its repository, those ADRs stop being just a memory aid for humans — they become context for the models you work alongside. An agent reading the codebase reads the ADRs too, and the suggestions it produces start to take into account decisions that wouldn't be visible from the code alone. On personal projects in particular, I've started using ADRs as explicit checkpoints in an LLM-assisted workflow: less code generated, more documentation produced through dialogue, each significant step pinned down in an ADR before the next one begins. It might look like a slowdown. It hasn't been one. I plan to come back to this workflow in more detail in another post.
What strikes me, looking at these two shifts side by side, is how little the document itself has changed. The same template, the same structure, the same kinds of decisions worth recording. The ADR I write today for an LLM-assisted side project looks remarkably like the ADR I'd have written a few years ago for a team — and not very different from the notes I scribbled to myself a decade earlier.
Still writing them
Across all of this, the document itself has barely changed. The same template, the same kinds of decisions worth recording. What's changed is what writing one costs, who reads them, and what they're for. Three different phases of the same habit, with the audience shifting each time — first myself, then a team, now sometimes a model — and the document quietly adapting underneath.
The first ADR I wrote is gone, and I still couldn't tell you what it was about. I keep writing them anyway. Not because I think I've figured out what they're for — I don't think the answer holds still long enough to be figured out — but because every version of me that's tried them so far has been glad to have them around. That's a thinner argument than I'd have given ten years ago. It's also one I trust more.