How do you capture WHY engineering decisions were made, not just what?

#1

Post by zain__t » Fri, Mar 13, 2026, 7:48 PM UTC

We onboarded a senior engineer recently strong, 8 years experience. He spent 3 weeks playing code archaeologist just to understand WHY our codebase looks the way it does.

Not what the code does. That was fast. But the reasoning behind decisions:

- 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?

Answers were buried in closed PRs with no descriptions, 18-month-old Slack threads, and the heads of two engineers who left last year.

We tried ADRs. Lasted 6 weeks. Nobody maintained them. We tried PR description templates. Ignored within a month. We have a Notion architecture doc. Last updated 14 months ago.

Every solution requires someone to manually write something. Nobody does.

Curious how teams at HN actually handle this:

1. Do you have a system that actually works long-term? 2. Has anyone automated any part of this? 3. Or is everyone quietly suffering through this on every new hire?

Re: How do you capture WHY engineering decisions were made, not just what?

#2

Post by airspresso » Fri, Mar 13, 2026, 7:55 PM UTC

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.

Re: How do you capture WHY engineering decisions were made, not just what?

#3

Post by [deleted] » Fri, Mar 13, 2026, 7:57 PM UTC

[deleted]

Re: How do you capture WHY engineering decisions were made, not just what?

#4

Post by [deleted] » Fri, Mar 13, 2026, 7:58 PM UTC

airspresso wrote: post #2

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.

[deleted]

Re: How do you capture WHY engineering decisions were made, not just what?

#5

Post by CGMthrowaway » Fri, Mar 13, 2026, 7:58 PM UTC

Put the ADR in the PR as a requirement. Then automate extracting the decision info into an actual ADR.

Re: How do you capture WHY engineering decisions were made, not just what?

#6

Post by zain__t » Fri, Mar 13, 2026, 8:00 PM UTC

CGMthrowaway wrote: post #5

Put the ADR in the PR as a requirement. Then automate extracting the decision info into an actual ADR.

I am already working to automate the process

Re: How do you capture WHY engineering decisions were made, not just what?

#7

Post by CGMthrowaway » Fri, Mar 13, 2026, 8:00 PM UTC

zain__t wrote: post #6

CGMthrowaway wrote: post #5

Put the ADR in the PR as a requirement. Then automate extracting the decision info into an actual ADR.

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

Re: How do you capture WHY engineering decisions were made, not just what?

#8

Post by [deleted] » Fri, Mar 13, 2026, 8:02 PM UTC

CGMthrowaway wrote: post #7

zain__t wrote: post #6

Earlier quoted context omitted.

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

[deleted]

Re: How do you capture WHY engineering decisions were made, not just what?

#9

Post by _moof » Fri, Mar 13, 2026, 8:12 PM UTC

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.

Re: How do you capture WHY engineering decisions were made, not just what?

#10

Post by rustyzig » Fri, Mar 13, 2026, 8:19 PM UTC

> - 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.