My take after running engineering teams at multiple companies: documentation survives when it lives next to the code. File-level header comments explaining each component's purpose and role in the architecture. A good README tying it all together. If you compartmentalize architecture into folders, a README per folder. This works for humans, LLMs, and GitHub search alike.
ADRs, Notion docs, and Confluence pages die because they're separate from the code. Out of sight, out of mind.
If you want to be really disciplined about it, set up an LLM-as-judge git hook that runs on each PR. It checks whether code changes are consistent with the existing documentation and blocks the merge if docs need updating. That way the enforcement is automated and you only need a little human discipline, not a lot.
There's no way to avoid some discipline though. But the less friction you add, the more likely it sticks.
I suppose you are trying to "warm up" the audience before announcing you product, which is... fine, I guess.
I also had a an idea for a solution to this problem long time ago.
I wanted to make a thing that would allow you to record a meeting (in the company I where I worked back then such things where mostly discussed in person), transcribe it and link parts of the conversation to relevant tickets, pull requests and git commits.
Back then the tech wasn't ready yet, but now it actually looks relatively easy to do.
For now, I try to leave such breadcrumbs manually, whenever I can. For example, if the reason why a part of the code exists seems non-obvious to me, I will write an explanation in a comment/docstring and leave a link to a ticket or a ticket comment that provides additional context.
I worked on the problem of recording 'design rationale' ~25 years ago. It is a big problem. Particulalry for long-lived artefacts, such as nuclear reactors. Nobody is quite sure exactly why decisions were made, as the original designers have forgotten, retired or been run over by buses. And this makes changing things difficult and risky. The biggest problem is that there is no real incentive for the people making the decisions to write down why they made them:
* they may see it as reducing their career security
* they may see it as opening them up to potential prosecution
This is incredibly valuable context thank you. The career security point especially is something I hadn't fully articulated but explains why ADRs always die. Nobody wants to document themselves out of a job.
The approach I'm exploring tries to remove the human writing step entirely passively capturing decisions from PRs, Slack threads, and tickets and auto drafting the rationale. The human just approves or dismisses in one click.
The incentive problem flips instead of asking someone to document themselves, you're just asking them to approve something already written. Much lower friction.
Curious from your 25 years on this do you think the passive capture angle addresses the incentive problem or does the resistance run deeper than just the writing effort?
I can't say ADRs work that great, in my experience, but the flaw was more connecting them to other architectural stuff to make them actually discoverable and drawing the boundaries in a logical way (what goes into an ADR and what goes into a living design doc?).
"Not maintained" seems kinda weird to me, because at least as I see an ADR, it's like a point in time decision right? "In this situation, we looked at these options, and chose this for these reasons". You don't go back and update it. If you're making a big change, you make a new ADR with your new reasons.
One place I worked did have an interesting idea of basically forcing (not quite) the new hires to take notes on all their onboarding questions/answers as they went and then sticking it in the company docs. It at least meant that incorrect onboarding docs got fixed quickly. Sometimes you had good reasons for stuff, sometimes the reason is "dunno, that's just what we do and it seems hard to change".
(Don’t take this as advice. Just writing my own experience with this.)
This is the reason why I take the time to summarize all “why” decisions and implementation tradeoffs being made in my (too lengthy) PR descriptions with links, etc. I’ve gotten into the habit of using <detail/> to collapse everything because I’ve gotten feedback multiple times that no one reads my walls of text. However, I still write it (with short <summary/>s now) because I’ve lost track of the number of times I’ve been able to search my PRs and quickly answer mine or someone’s “why” question. I do it mostly for me because I find it invaluable as I prefer writing shit down instead of relying on my flaky memory. People are forgetful and people come and go. What doesn’t disappear is documentation tied to code commits (well… unless you nuke your repo).
Doesn't really answer you question but IME this is sort of unavoidable unless you're massive and you can afford to have people who just document this kind of stuff as their job.
Reason being, a lot of this stuff happens for no good reason, or by accident, or for reasons that no longer apply. Someone liked the tech so used it - then left. Something looked better in a benchmark, but then the requirements drifted and now it's actually worse but no one has the time to rewrite. Something was inefficient but implemented as a stop gap, then stayed and is now too hard to replace.
So you can't explain the reasons when much of the time there aren't any.
The non-solutions are:
- document the high level principles and stick to them. Maybe you value speed of deployment, or stability, or control over codebase. Individual software choices often make sense in light of such principles.
- keep people around and be patient when explaining what happened
- write wiki pages, without that much effort at being systematic and up to date. Yes, they will drift out of sync, but they will provide breadcrumbs to follow.
First, recognize that, for the first time ever, having good docs actually pays dividends. LLMs love reading docs and they're fantastic at keeping them up to date. Just don't go overboard, and don't duplicate anything that can be easily grepped from the codebase.
Second, for #3, it's a new hire's job to make sure the docs are useful for new hires. Whenever they hit friction because the docs are missing or wrong, they go find the info, and then update the docs. No one else remembers what it's like to not know the things they know. And new hires don't yet know that "nobody writes anything" at your company.
In general, like another poster said, docs must live as close as possible to the code. LLMs are fantastic at keeping docs up to date, but only if they're in a place that they'll look. If you have a monorepo, put the docs in a docs/ folder and mention it in CLAUDE.md.
ADRs (architecture decision records) aren't meant to be maintained, are they? They're basically RFCs, a tool for communication of a proposal and a discussion. If someone writes a nontrivial proposal in a slack thread, say "I won't read this until it's in an ADR."
IMHO, PRs and commits are a pretty terrible place to bury this stuff. How would you search through them, dump all commit descriptions longer than 10 words into a giant .md and ask an LLM? No, you shouldn't rely on commits to tell you the "why" for anything larger in scope than that particular commit.
It's not magic, but I maintain a rude Q&A document that basically has answers to all the big questions. Often the questions were asked by someone else at the company, but sometimes they're to remind myself ("Why Kafka?" is one I keep revisiting because I want to ditch Kafka so badly, but it's not easy to replace for our use case). But I enjoy writing. I'm not sure this process scales.
The Q&A doc you're maintaining is fascinating you've essentially hand-built the thing I'm trying to automate. The 'Why Kafka?' entry is exactly the kind of decision that disappears when you leave.
The search problem you raised is the core of what I'm solving — not dumping commits into a .md, but extracting structured decisions from the conversation that surrounded the commit: the Slack debate, the PR review, the ticket context. Then making it queryable by the code it relates to.
You said you're not sure your process scales what happens to that Q&A doc if you leave tomorrow?
If I leave, the Q&A doc probably never gets updated again.
We're in the process of trying to get as much stuff as possible into source control (we use google docs a lot, so we'll set up one way replication for our ADRs and stuff from there to git). That way, as LLM models get better, whatever doc gets materialized from those bits and pieces will also automatically get better.
we've started to document any a/b decision we take in terms of tech and store in our engineering internal docs! have gone back to it once in a whilw but that usually helps keep us grounded
> - Why Redis over in-memory cache? - Why GraphQL for this one service but REST everywhere else? - Why that strange exception in the auth flow for enterprise users?
These are all implementation details that shouldn't actually matter. What does matter is that the properties of your system are accounted for and validated. That goes in your test suite, or type system if your language has a sufficiently advanced type system.
If replacing Redis with an in-memory cache is a problem technically, your tests/compiler should prevent you from switching to an in-memory cache. If you don't have that, that is where you need to start. Once you have those tests/types, many of the questions will also get answered. It won't necessarily answer why Redis over Valkey, but it will demonstrate with clear intent why not an in-memory cache.
Keep the reasoning as close to the code as possible.
1. Code should be self-explanatory, so should vars, function names and the entire shape be.
2. For the remaining non-obvious bigger design decisions, add a comment header (eg jsdoc) above the main section code block, and possibly refactor it out into its own file. Prefer to have a large comment header (and possibly some inline comments) outlining an important architectural part than having that knowledge dissipate with time, separate external docs and your leaving workers.
If it’s something in the code, that’s where I use comments. It’s the only place people have a chance of seeing it. Even when I add these comments some people ask me about the code instead of reading them. This isn’t just for others, I forget as well. Something to the effect of…
# This previously used ${old-solution}, but has moved to ${new-solution} because ${reason}
Or
# This is ugly and doesn’t make sense, but ${clean-logocal-way} doesn’t work due to ${reason}. If you change ${x} it will break.
Or
# This was a requirement from ${person} on ${date}. We want to remove this, but will need to wait until ${person} no longer needs it or leaves the company.
Yeah, this doesn’t solve the “why Redis” problem. What I’m most concerned about with this is stopping someone who might be trying to update the code in the future (including me) from going down a rabbit hole I’ve already been down.
Those comment templates are actually really well structured you've invented a mini decision record format without calling it that.
The problem you're hitting is discoverability the why is there, but only if you happen to read that exact line. What if a new dev could ask 'why does this auth flow work this way?' and your comment was part of the synthesized answer along with the PR, the Slack thread, and the ticket that created it?
Most people where I work use Confluence for the overarching architecture decisions, but that also has a massive discovery issue.
If there is a Confluence doc that relates to my code, I will usually cross reference it. The Confluence link goes at the top of the file, and a link to the repo goes into Confluence. Even with this, the discovery problem remains, as one of those things needs to be found.
Using chat is a non-starter, as our chats are purged after 6 or 12 months. PRs also seem like a very challenging place to keep the information without a lot of systems in place and strict adherence.
Tickets can work, until the ticketing system changes. I’ve been through 3 ITSM platform changes and 3 changes in agile software. Old information is lost in these transitions as it’s usually only in-flight stuff that migrates. Confluence will meet the same fate soon I’m sure.
At the end of the day, the code is the only thing I can trust to be there. Once the code is gone the information matters less. I also try to be pretty diligent about readme files can get pretty wordy. Adding some kind of architecture doc into the repo might be another option, similar to what claude.md has become for a lot of people. I actually might do this for a project I’m starting now, as it’s pretty confusing… though I’m hoping I can come up with a way to make it less confusing.
ADRs but give ownership to the team. They should sit in the repo most relevant, but a central repo called ADRs have issue templates and a readme which links off to all the repos and their ADRs - ADRs can not be approved and the issue closed until all the docs are in place. Everyone can see the open ADRs in the main repo and see issue and comment on them. Accountability is there if an assigned issue is open for days/weeks etc.
GitHub issues templates are perfect for ADR templates. All Hands for engineering is a great place to mention them and for teams to comment on the decision and outcomes.
For context, my engineering team is fairly small – no guarantees this scales well for larger organizations. I capture the reasons for decisions on why code was written a particular way or why a particular architecture was decided upon in commit messages. We follow a squash-and-rebase flow for commits, so each PR is ultimately a single commit before merging. During that squash process, I'll update the commit message to sometimes be a few paragraphs long. Later when I'm curious why we made decision in the past, I can use git blame to navigate back until the point where I can find the answer.
Simple: ask "why" in a PR review, put the answer in a code comment. If there is a bigger / higher level "why", add it to git commit description. This way it's auto-maintained with code, or stays frozen at a point in time in a git commit.
* File issues in a project tracker (Github, jira, asana, etc)
* Use the issue id at the start of every commit message for that issue
* Use a single branch per issue, whose name also starts with the issue id
* Use a single PR to merge that branch and close the issue
* Don't squash merge PRs
You can use `git blame` to get the why.
git blame, gives you the change set and the commit message. Use the issue id in commit message to get to the issue. Issue description and comments provide a part of the story.
Use the issue id, to track the branch and PR. The PR comments give you the rest of the story.
Overall I agree with the approach, but just wondering, why do the first point if you are already doing the last two?
> * Use the issue id at the start of every commit message for that issue
> * Use a single branch per issue, whose name also starts with the issue id
>* Use a single PR to merge that branch and close the issue
To me the noise at the start of every message is unnecessary, and given a lot of interfaces only display 80 chars of the message by default, it's not negligible.
If the pattern is consistent, it gets easier to ignore the noise when you don't need it. Like, a three/four digit number or a 3 letters and 3 numbers separated by a hyphen.
Sometimes, an issue might depend on another issue and contain commits from the other branch. Tagging each commit makes it easier to pinpoint the exact reason for that change.
This seems reasonable to me. Devs and BAs flesh out business processes and ultimately document decisions in our Jira issue comments. When you have an issue id handy, it's not that hard to go read what the rationale was for a feature.
I have been ignoring Jira's AI summary, but I suppose that could be useful if the comments were very long.
Did he write down everything he learned? That way the next person only needs to cover the intervening time period.
Conceivably LLMs might be good at answering questions from an unorganized mass of timestamped documents/tickets/chat logs. All the stuff that exists anyway without any extra continuous effort required to curate it - I think that's key.
Sometime the best way to why a (Chesterton's) fence is blocking the road is... to remove it and see what happens!
Sorry, not really an answer to your problem. But I feel you, this is a genuinely hard problem.
Keep in mind that, pretty often, the reason something is the way it is comes down to "no real reason", "that seemed easier at the time" or "we didnt know better". At least if you don't work on critical systems.
As a counter point, it may be quite subtle and hard to notice what goes wrong when you remove something to see what happens. Imagine you see a large sql query that has a bit of logic that doesn't make sense to you. If you go change it without knowing why it was that way, and users keep on using report output from that query, who is going to notice when they get 982 records in their report instead of 983 one day? It's easy to spot when erroneous data APPEARS, but it's a lot harder to notice when valid data DISAPPEARS. Oh, they really did have a good reason to use outer apply instead of cross apply, there. Oops.
This is called rationale and it goes in the design document. As work proceeds, it goes into tickets and meeting notes, and gets fed back into the design doc.
My masters thesis is wrt to scaffolding ADRs. I draw a fine line between required human input and what's safe to scaffold. There's a lot of tooling which I'll omit most details but involves recursively scaffolding/pruning and maintenance over time.
Sometimes the answer to "why?" is that the dev had a hammer and the codebase was starting to look an awful lot like a nail. In-memory cache isn't considered as a serious option nearly enough imho.
But that's still after the decision was made... I guess it's still useful. But maybe that person didn't actually weigh a decision and tradeoffs when they made the change.
I try to leave as many crumbs as I can in the PR description which becomes the commit message. I link issues, slack threads, articles, docs. Of course also explain the reasoning.
I thought about this too recently. I guess documenting every consideration along the way would take way too much time (would be longer than the documentation of actual implementations), but one of these days this seems likely to change?
That day is now and the reason is that the documentation doesn't have to be written anymore.
The conversation that led to the decision already exists — in your PR comments, Slack threads, and tickets. The reasoning is already there. It just needs to be extracted and structured automatically, not written from scratch.
That's the shift that makes this viable in 2026 when it wasn't in 2020. LLMs can read the noise and surface the signal. Zero extra time from the developer.
I built an agentic framework that distills ADRs from Teams meetings where everyone discusses freely. Works surprisingly well to record the WHY without someone having to do the job.
Also wrestling with this challenge at the moment and curious to hear experiences from others. Even though it requires human input, the capture and the way it's updated has to get automated.
Completely agree the manual capture is exactly where it breaks down every time. Curious, what's your current setup? GitHub + Slack or something different?
ADRs are the only way I've ever seen it done well for a sufficiently large enough project, let alone something like an entire product line or suite of many projects. Sometimes those span multiple organizations. Think of the Internet and the IETF RFCs. Yes, they don't give a complete picture. Implementations may not match the specification. I don't really agree they require maintenance. It's just you have to write up a new one any time you change a decision and give a reason why. Yes, it takes a lot of organizational discipline to do that. You probably can't be in panic mode and it won't work for a startup that needs to ship in five weeks or they can't make payroll. But there isn't really a substitute for discipline.
As maligned as it can be, the single best organization I've ever been a part of for code archaeology, on a huge multi-decade project that spanned many different companies and agencies of the government, simply made diligent use of the full Atlassian suite. Bitbucket, Jira, Confluence, Fish Eye, and Crucible all had the integrations turned on. Commits and PRs had a Jira ticket number in them. Follow that link to the original story, epic, whatever the hell it was, and that had further links to ADRs with peer review comments. I don't know that I ever really had to ask a question. Just find a line of interest and follow a bunch of links and you've got years of history on exactly what a whole bunch of different people (not just the one who committed code) were thinking and why they made the decisions they made.
I've always thought about the tradeoffs involved. They were waterfall. They didn't deliver fast. Their major customers were constantly trying to replace them with cheaper, more agile alternatives. But competitors could never match the strict non-functional requirements for security, reliability, and performance, and non-tolerence of regressions, so it never happened and they've had a several decades monopoly in what they do because of it.
Your company is missing an architect role. An architect would know why redis over in-memory cache and have that pattern documented. They would definitely know why graphql for the one service but REST everywhere else - they would have it documented from design approval meetings.
This is the clearest articulation of the problem I've seen. You've basically described exactly what I'm building.
The passive ingestion angle treating reasoning as a byproduct of work already being done rather than a separate documentation task is the core insight that makes this viable where ADRs failed.
I'm in early development. Would you be open to a 15 min conversation? Your framing here is sharper than anything I've heard from the 20 engineers I've already talked to.
My take after running engineering teams at multiple companies: documentation survives when it lives next to the code. File-level header comments explaining each component's purpose and role in the architecture. A good README tying it all together. If you compartmentalize architecture into folders, a README per folder. This works for humans, LLMs, and GitHub search alike.
ADRs, Notion docs, and Confluence pages die because they're separate from the code. Out of sight, out of mind.
If you want to be really disciplined about it, set up an LLM-as-judge git hook that runs on each PR. It checks whether code changes are consistent with the existing documentation and blocks the merge if docs need updating. That way the enforcement is automated and you only need a little human discipline, not a lot.
There's no way to avoid some discipline though. But the less friction you add, the more likely it sticks.
The git hook idea for enforcing doc updates is really interesting has that actually worked long term for your team or does it eventually get bypassed?
I suppose you are trying to "warm up" the audience before announcing you product, which is... fine, I guess.
I also had a an idea for a solution to this problem long time ago.
I wanted to make a thing that would allow you to record a meeting (in the company I where I worked back then such things where mostly discussed in person), transcribe it and link parts of the conversation to relevant tickets, pull requests and git commits.
Back then the tech wasn't ready yet, but now it actually looks relatively easy to do.
For now, I try to leave such breadcrumbs manually, whenever I can. For example, if the reason why a part of the code exists seems non-obvious to me, I will write an explanation in a comment/docstring and leave a link to a ticket or a ticket comment that provides additional context.
I worked on the problem of recording 'design rationale' ~25 years ago. It is a big problem. Particulalry for long-lived artefacts, such as nuclear reactors. Nobody is quite sure exactly why decisions were made, as the original designers have forgotten, retired or been run over by buses. And this makes changing things difficult and risky. The biggest problem is that there is no real incentive for the people making the decisions to write down why they made them:
* they may see it as reducing their career security
* they may see it as opening them up to potential prosecution
* it takes a lot of time
This is incredibly valuable context thank you. The career security point especially is something I hadn't fully articulated but explains why ADRs always die. Nobody wants to document themselves out of a job. The approach I'm exploring tries to remove the human writing step entirely passively capturing decisions from PRs, Slack threads, and tickets and auto drafting the rationale. The human just approves or dismisses in one click. The incentive problem flips instead of asking someone to document themselves, you're just asking them to approve something already written. Much lower friction. Curious from your 25 years on this do you think the passive capture angle addresses the incentive problem or does the resistance run deeper than just the writing effort?
>The human just approves or dismisses in one click.
A busy engineer trying to hit a deadline is just going to do the easiest thing, aren't they?
Also there is all sorts of tacit knowledge that goes into a decision and I just don't think you are going to capture this automatically.
(I worked on it 25 years ago, rather than for 25 years.)
I can't say ADRs work that great, in my experience, but the flaw was more connecting them to other architectural stuff to make them actually discoverable and drawing the boundaries in a logical way (what goes into an ADR and what goes into a living design doc?).
"Not maintained" seems kinda weird to me, because at least as I see an ADR, it's like a point in time decision right? "In this situation, we looked at these options, and chose this for these reasons". You don't go back and update it. If you're making a big change, you make a new ADR with your new reasons.
One place I worked did have an interesting idea of basically forcing (not quite) the new hires to take notes on all their onboarding questions/answers as they went and then sticking it in the company docs. It at least meant that incorrect onboarding docs got fixed quickly. Sometimes you had good reasons for stuff, sometimes the reason is "dunno, that's just what we do and it seems hard to change".
(Don’t take this as advice. Just writing my own experience with this.)
This is the reason why I take the time to summarize all “why” decisions and implementation tradeoffs being made in my (too lengthy) PR descriptions with links, etc. I’ve gotten into the habit of using <detail/> to collapse everything because I’ve gotten feedback multiple times that no one reads my walls of text. However, I still write it (with short <summary/>s now) because I’ve lost track of the number of times I’ve been able to search my PRs and quickly answer mine or someone’s “why” question. I do it mostly for me because I find it invaluable as I prefer writing shit down instead of relying on my flaky memory. People are forgetful and people come and go. What doesn’t disappear is documentation tied to code commits (well… unless you nuke your repo).
Doesn't really answer you question but IME this is sort of unavoidable unless you're massive and you can afford to have people who just document this kind of stuff as their job.
Reason being, a lot of this stuff happens for no good reason, or by accident, or for reasons that no longer apply. Someone liked the tech so used it - then left. Something looked better in a benchmark, but then the requirements drifted and now it's actually worse but no one has the time to rewrite. Something was inefficient but implemented as a stop gap, then stayed and is now too hard to replace.
So you can't explain the reasons when much of the time there aren't any.
The non-solutions are:
- document the high level principles and stick to them. Maybe you value speed of deployment, or stability, or control over codebase. Individual software choices often make sense in light of such principles.
- keep people around and be patient when explaining what happened
- write wiki pages, without that much effort at being systematic and up to date. Yes, they will drift out of sync, but they will provide breadcrumbs to follow.
First, recognize that, for the first time ever, having good docs actually pays dividends. LLMs love reading docs and they're fantastic at keeping them up to date. Just don't go overboard, and don't duplicate anything that can be easily grepped from the codebase.
Second, for #3, it's a new hire's job to make sure the docs are useful for new hires. Whenever they hit friction because the docs are missing or wrong, they go find the info, and then update the docs. No one else remembers what it's like to not know the things they know. And new hires don't yet know that "nobody writes anything" at your company.
In general, like another poster said, docs must live as close as possible to the code. LLMs are fantastic at keeping docs up to date, but only if they're in a place that they'll look. If you have a monorepo, put the docs in a docs/ folder and mention it in CLAUDE.md.
ADRs (architecture decision records) aren't meant to be maintained, are they? They're basically RFCs, a tool for communication of a proposal and a discussion. If someone writes a nontrivial proposal in a slack thread, say "I won't read this until it's in an ADR."
IMHO, PRs and commits are a pretty terrible place to bury this stuff. How would you search through them, dump all commit descriptions longer than 10 words into a giant .md and ask an LLM? No, you shouldn't rely on commits to tell you the "why" for anything larger in scope than that particular commit.
It's not magic, but I maintain a rude Q&A document that basically has answers to all the big questions. Often the questions were asked by someone else at the company, but sometimes they're to remind myself ("Why Kafka?" is one I keep revisiting because I want to ditch Kafka so badly, but it's not easy to replace for our use case). But I enjoy writing. I'm not sure this process scales.
The Q&A doc you're maintaining is fascinating you've essentially hand-built the thing I'm trying to automate. The 'Why Kafka?' entry is exactly the kind of decision that disappears when you leave. The search problem you raised is the core of what I'm solving — not dumping commits into a .md, but extracting structured decisions from the conversation that surrounded the commit: the Slack debate, the PR review, the ticket context. Then making it queryable by the code it relates to. You said you're not sure your process scales what happens to that Q&A doc if you leave tomorrow?
If I leave, the Q&A doc probably never gets updated again.
We're in the process of trying to get as much stuff as possible into source control (we use google docs a lot, so we'll set up one way replication for our ADRs and stuff from there to git). That way, as LLM models get better, whatever doc gets materialized from those bits and pieces will also automatically get better.
we've started to document any a/b decision we take in terms of tech and store in our engineering internal docs! have gone back to it once in a whilw but that usually helps keep us grounded
> - Why Redis over in-memory cache? - Why GraphQL for this one service but REST everywhere else? - Why that strange exception in the auth flow for enterprise users?
These are all implementation details that shouldn't actually matter. What does matter is that the properties of your system are accounted for and validated. That goes in your test suite, or type system if your language has a sufficiently advanced type system.
If replacing Redis with an in-memory cache is a problem technically, your tests/compiler should prevent you from switching to an in-memory cache. If you don't have that, that is where you need to start. Once you have those tests/types, many of the questions will also get answered. It won't necessarily answer why Redis over Valkey, but it will demonstrate with clear intent why not an in-memory cache.
Keep the reasoning as close to the code as possible.
1. Code should be self-explanatory, so should vars, function names and the entire shape be.
2. For the remaining non-obvious bigger design decisions, add a comment header (eg jsdoc) above the main section code block, and possibly refactor it out into its own file. Prefer to have a large comment header (and possibly some inline comments) outlining an important architectural part than having that knowledge dissipate with time, separate external docs and your leaving workers.
If it’s something in the code, that’s where I use comments. It’s the only place people have a chance of seeing it. Even when I add these comments some people ask me about the code instead of reading them. This isn’t just for others, I forget as well. Something to the effect of…
# This previously used ${old-solution}, but has moved to ${new-solution} because ${reason}
Or
# This is ugly and doesn’t make sense, but ${clean-logocal-way} doesn’t work due to ${reason}. If you change ${x} it will break.
Or
# This was a requirement from ${person} on ${date}. We want to remove this, but will need to wait until ${person} no longer needs it or leaves the company.
Putting decision inside the code is interesting... but scattered. Some decisions are made way higher up and implicitly touch many places
Yeah, this doesn’t solve the “why Redis” problem. What I’m most concerned about with this is stopping someone who might be trying to update the code in the future (including me) from going down a rabbit hole I’ve already been down.
Those comment templates are actually really well structured you've invented a mini decision record format without calling it that. The problem you're hitting is discoverability the why is there, but only if you happen to read that exact line. What if a new dev could ask 'why does this auth flow work this way?' and your comment was part of the synthesized answer along with the PR, the Slack thread, and the ticket that created it?
Most people where I work use Confluence for the overarching architecture decisions, but that also has a massive discovery issue.
If there is a Confluence doc that relates to my code, I will usually cross reference it. The Confluence link goes at the top of the file, and a link to the repo goes into Confluence. Even with this, the discovery problem remains, as one of those things needs to be found.
Using chat is a non-starter, as our chats are purged after 6 or 12 months. PRs also seem like a very challenging place to keep the information without a lot of systems in place and strict adherence.
Tickets can work, until the ticketing system changes. I’ve been through 3 ITSM platform changes and 3 changes in agile software. Old information is lost in these transitions as it’s usually only in-flight stuff that migrates. Confluence will meet the same fate soon I’m sure.
At the end of the day, the code is the only thing I can trust to be there. Once the code is gone the information matters less. I also try to be pretty diligent about readme files can get pretty wordy. Adding some kind of architecture doc into the repo might be another option, similar to what claude.md has become for a lot of people. I actually might do this for a project I’m starting now, as it’s pretty confusing… though I’m hoping I can come up with a way to make it less confusing.
ADRs but give ownership to the team. They should sit in the repo most relevant, but a central repo called ADRs have issue templates and a readme which links off to all the repos and their ADRs - ADRs can not be approved and the issue closed until all the docs are in place. Everyone can see the open ADRs in the main repo and see issue and comment on them. Accountability is there if an assigned issue is open for days/weeks etc.
GitHub issues templates are perfect for ADR templates. All Hands for engineering is a great place to mention them and for teams to comment on the decision and outcomes.
For context, my engineering team is fairly small – no guarantees this scales well for larger organizations. I capture the reasons for decisions on why code was written a particular way or why a particular architecture was decided upon in commit messages. We follow a squash-and-rebase flow for commits, so each PR is ultimately a single commit before merging. During that squash process, I'll update the commit message to sometimes be a few paragraphs long. Later when I'm curious why we made decision in the past, I can use git blame to navigate back until the point where I can find the answer.
Simple: ask "why" in a PR review, put the answer in a code comment. If there is a bigger / higher level "why", add it to git commit description. This way it's auto-maintained with code, or stays frozen at a point in time in a git commit.
More: https://max.engineer/reasons-to-leave-comment
Much more: https://max.engineer/maintainable-code
If you do these things:
* File issues in a project tracker (Github, jira, asana, etc)
* Use the issue id at the start of every commit message for that issue
* Use a single branch per issue, whose name also starts with the issue id
* Use a single PR to merge that branch and close the issue
* Don't squash merge PRs
You can use `git blame` to get the why.
git blame, gives you the change set and the commit message. Use the issue id in commit message to get to the issue. Issue description and comments provide a part of the story.
Use the issue id, to track the branch and PR. The PR comments give you the rest of the story.
Overall I agree with the approach, but just wondering, why do the first point if you are already doing the last two?
> * Use the issue id at the start of every commit message for that issue
> * Use a single branch per issue, whose name also starts with the issue id
>* Use a single PR to merge that branch and close the issue
To me the noise at the start of every message is unnecessary, and given a lot of interfaces only display 80 chars of the message by default, it's not negligible.
If the pattern is consistent, it gets easier to ignore the noise when you don't need it. Like, a three/four digit number or a 3 letters and 3 numbers separated by a hyphen.
Sometimes, an issue might depend on another issue and contain commits from the other branch. Tagging each commit makes it easier to pinpoint the exact reason for that change.
This seems reasonable to me. Devs and BAs flesh out business processes and ultimately document decisions in our Jira issue comments. When you have an issue id handy, it's not that hard to go read what the rationale was for a feature.
I have been ignoring Jira's AI summary, but I suppose that could be useful if the comments were very long.
Did he write down everything he learned? That way the next person only needs to cover the intervening time period.
Conceivably LLMs might be good at answering questions from an unorganized mass of timestamped documents/tickets/chat logs. All the stuff that exists anyway without any extra continuous effort required to curate it - I think that's key.
Sometime the best way to why a (Chesterton's) fence is blocking the road is... to remove it and see what happens!
Sorry, not really an answer to your problem. But I feel you, this is a genuinely hard problem.
Keep in mind that, pretty often, the reason something is the way it is comes down to "no real reason", "that seemed easier at the time" or "we didnt know better". At least if you don't work on critical systems.
As a counter point, it may be quite subtle and hard to notice what goes wrong when you remove something to see what happens. Imagine you see a large sql query that has a bit of logic that doesn't make sense to you. If you go change it without knowing why it was that way, and users keep on using report output from that query, who is going to notice when they get 982 records in their report instead of 983 one day? It's easy to spot when erroneous data APPEARS, but it's a lot harder to notice when valid data DISAPPEARS. Oh, they really did have a good reason to use outer apply instead of cross apply, there. Oops.
This is called rationale and it goes in the design document. As work proceeds, it goes into tickets and meeting notes, and gets fed back into the design doc.
A design doc with a robust "alternatives considered" section.
My masters thesis is wrt to scaffolding ADRs. I draw a fine line between required human input and what's safe to scaffold. There's a lot of tooling which I'll omit most details but involves recursively scaffolding/pruning and maintenance over time.
I have a ton of papers to read wrt making decisions, human-ai interaction, ADRs, etc if you're interested.
we use a service called Briefhq.
First: It’s a MCP/cli you can hook up to Claude code and slack, it integrates with GitHub.
the harness lets you record decision as contextual info you can pull up whenever your start a planning session.
It also makes sure your decisions don’t conflict with each other.
I find myself talking through a decision I made months ago with it, update it with any new decisions and it just figures out how to merge everything.
No extra workflow outside of this.
> Why Redis over in-memory cache?
Sometimes the answer to "why?" is that the dev had a hammer and the codebase was starting to look an awful lot like a nail. In-memory cache isn't considered as a serious option nearly enough imho.
Put the ADR in the PR as a requirement. Then automate extracting the decision info into an actual ADR.
But that's still after the decision was made... I guess it's still useful. But maybe that person didn't actually weigh a decision and tradeoffs when they made the change.
I am already working to automate the process
AI could even analyze the diff and predictively pre-populate the decision info, though that might be counterproductive in practice
I try to leave as many crumbs as I can in the PR description which becomes the commit message. I link issues, slack threads, articles, docs. Of course also explain the reasoning.
I thought about this too recently. I guess documenting every consideration along the way would take way too much time (would be longer than the documentation of actual implementations), but one of these days this seems likely to change?
That day is now and the reason is that the documentation doesn't have to be written anymore. The conversation that led to the decision already exists — in your PR comments, Slack threads, and tickets. The reasoning is already there. It just needs to be extracted and structured automatically, not written from scratch. That's the shift that makes this viable in 2026 when it wasn't in 2020. LLMs can read the noise and surface the signal. Zero extra time from the developer.
I built an agentic framework that distills ADRs from Teams meetings where everyone discusses freely. Works surprisingly well to record the WHY without someone having to do the job.
Sounds pretty cool. Is this published?
No, b/c I did so on company time. And it's old industry, they wouldn't open-source it.
But it took ~2 weeks with the help of Claude, so relatively easy to replicate.
Do people discuss detail on Teams in your company? In my place it turns into calls..
Teams calls. I let Teams transcribe it and parse the transcription via AI.
Also wrestling with this challenge at the moment and curious to hear experiences from others. Even though it requires human input, the capture and the way it's updated has to get automated.
Completely agree the manual capture is exactly where it breaks down every time. Curious, what's your current setup? GitHub + Slack or something different?
> Every solution requires someone to manually write something. Nobody does.
Hot take: hire people that value writing. Create a culture around that.
Oxide is a great example of a company culture that values writing, as shown by their rigorous and prolific RFDs: https://rfd.shared.oxide.computer/rfd/0001
See also: https://oxide-and-friends.transistor.fm/episodes/rfds-the-ba...
Many of these RFDs have hit HN by themselves.
ADRs are the only way I've ever seen it done well for a sufficiently large enough project, let alone something like an entire product line or suite of many projects. Sometimes those span multiple organizations. Think of the Internet and the IETF RFCs. Yes, they don't give a complete picture. Implementations may not match the specification. I don't really agree they require maintenance. It's just you have to write up a new one any time you change a decision and give a reason why. Yes, it takes a lot of organizational discipline to do that. You probably can't be in panic mode and it won't work for a startup that needs to ship in five weeks or they can't make payroll. But there isn't really a substitute for discipline.
As maligned as it can be, the single best organization I've ever been a part of for code archaeology, on a huge multi-decade project that spanned many different companies and agencies of the government, simply made diligent use of the full Atlassian suite. Bitbucket, Jira, Confluence, Fish Eye, and Crucible all had the integrations turned on. Commits and PRs had a Jira ticket number in them. Follow that link to the original story, epic, whatever the hell it was, and that had further links to ADRs with peer review comments. I don't know that I ever really had to ask a question. Just find a line of interest and follow a bunch of links and you've got years of history on exactly what a whole bunch of different people (not just the one who committed code) were thinking and why they made the decisions they made.
I've always thought about the tradeoffs involved. They were waterfall. They didn't deliver fast. Their major customers were constantly trying to replace them with cheaper, more agile alternatives. But competitors could never match the strict non-functional requirements for security, reliability, and performance, and non-tolerence of regressions, so it never happened and they've had a several decades monopoly in what they do because of it.
Cryptic comments left in the code.
LLM post
step one: have you ever heard of a guy named Aristotle
Your company is missing an architect role. An architect would know why redis over in-memory cache and have that pattern documented. They would definitely know why graphql for the one service but REST everywhere else - they would have it documented from design approval meetings.
[flagged]
This is the clearest articulation of the problem I've seen. You've basically described exactly what I'm building. The passive ingestion angle treating reasoning as a byproduct of work already being done rather than a separate documentation task is the core insight that makes this viable where ADRs failed. I'm in early development. Would you be open to a 15 min conversation? Your framing here is sharper than anything I've heard from the 20 engineers I've already talked to.
True. It only works if the "why" is an actual, required deliverable. Maybe NASA? Can someone chime in who worked in an org like that?