The upgrade senior engineers notice is not your stack. It is your decision trail.
Every team says they care about judgment.
Then the meeting starts and we spend ~40 minutes arguing about tools.
Should we use Laravel queues or move the workload to a separate worker service? Should we deploy with GitHub Actions, a shell script or some bigger platform with a nicer dashboard? Should we keep Nginx plus PHP-FPM or switch to Octane or switch clouds or switch observability vendors, or switch anything else that can be turned into a noun people can defend?
The tool is rarely the real question. The real question is whether anyone can explain the trade-off clearly enough that the rest of the team can live with it later, especially after the person who made the decision is on leave, in another project, or no longer at the company.
That is the part many engineers miss. Good teams do not just want your answer. They want the path you took to get there.
This is why two engineers can recommend the same tool and leave very different impressions. One says, “Pulumi is better.” The other says, “We need previewable infrastructure changes, a review trail in Git and something two backend engineers can maintain without hiring a Terraform specialist. Pulumi gets us there with the least process overhead.” Same conclusion. Completely different signal.
The second engineer is easier to trust because they showed how they decided.
Tool debates become proxy wars when the reasoning is missing
Tool arguments feel technical, but most of the wasted time comes from missing context.
One person is optimizing for speed this quarter. Another is optimizing for reliability during on-call, because they have already seen what a brittle system does to a tired team at 2 a.m. Another is optimizing for hiring, because they know the current team cannot support a clever setup for very long. Someone else is reacting to the last incident and over-correcting. All of them might be smart and all of them might be arguing honestly. If nobody names the constraints out loud, the conversation becomes a proxy war between preferences.
That is why these debates repeat.
The team does not really disagree about the tool. The team disagrees about what problem matters most. Until that is visible, every recommendation sounds like taste.
AWS’s ADR guidance is useful here because it is blunt about what a decision record should contain: context, the decision itself and the consequences. It also points out the anti-pattern we all know too well, even if we do not name it that way: teams keep revisiting the same topic because the reasoning never got captured. That is the expensive part, not the wrong button in the dashboard. The repeated argument is.
Once you notice this, a lot of engineering friction starts to look different.
The frustrating pull request was not frustrating because the author picked Redis. It was frustrating because the author never explained why Redis was a better fit than the database that already existed.
The architecture review did not stall because the team was incapable of choosing between S3 and local storage. It stalled because nobody wrote down the retention rules, expected file sizes, or the operational burden of serving private files from app servers.
The tool is what people point at. The missing reasoning is what actually hurts.
Senior engineers are easier to work with for one reason
It is tempting to say senior engineers are better because they know more tools. Sometimes they do. That is not the main reason they are easier to work with.
The real difference is usually this:
They make the decision legible.
When a strong senior engineer recommends something, you can usually reconstruct the logic even if you disagree with the conclusion. You can see the constraints they prioritized. You can see the alternatives they rejected. You can see the failure mode they are trying to avoid.
That makes collaboration faster because disagreement becomes specific.
You stop arguing in vague sentences like:
- “This does not feel scalable.”
- “That tool is more enterprise.”
- “I think this will be hard to maintain.”
And you start arguing in useful ones:
- “This adds one more stateful service to our deploy path and nobody on the team owns it yet.”
- “This saves us queue code, but it makes local testing much harder.”
- “This looks simpler now, but our rollback path becomes manual once jobs are partially processed.”
That is a completely different level of conversation. One can survive contact with production.
The shift matters in code review too. GitHub’s own pull request docs emphasize that reviews are for discussion, line-level feedback, suggested changes and explicit approval or requested changes. That only works when the author gives reviewers something better than “I changed the auth layer” and a diff with fifty files.
Reviewers do not just need changed code. They need decision context.
What “showing how you decide” actually looks like
This is the part worth copying into a team habit.
If you want your decision-making to be visible, include these five things whenever the choice is non-trivial:
- The constraint
What pressure is driving the decision right now? Cost, latency, staffing, recovery time, security, delivery speed, auditability. - The options you seriously considered
Not every possible option on earth. Just the real candidates. - The rejection reason
Why did the other options lose? This is where future readers save time. - The consequence you are accepting
Every decision buys something and gives something up. Say both. - The revisit trigger
What would make you change your mind later?
Most teams do not need a heavyweight architecture ritual. They need those five things written down consistently.
That is why I am skeptical when people say they want better technical decisions but refuse to write more than two vague lines in a pull request. The decision is not clear if the trade-off is still trapped in one person’s head.
The fastest way to improve this is inside pull requests
You do not need a new tool to start. GitHub already gives teams enough structure to do this well.
Pull request templates can auto-fill the PR body with the information you want every author to provide. Reviews already support line comments, approval and requested changes. So the problem is usually not missing capability. It is that we waste those capabilities on summaries like “refactor queue logic” and hope the diff explains the rest.
Here is the difference.
Before
## Summary
Refactor upload processing
## Notes
- switched worker flow
- updated jobs
- fixed retriesThat PR body tells me almost nothing. I still do not know what changed conceptually, why the previous approach failed, or what new risk I should look for during review.
After
## Problem
Large uploads were tying request time to antivirus scan time, which caused timeouts and duplicate retries from the client.
## Decision
Move virus scanning and thumbnail generation into queued jobs after signed upload completion.
## Alternatives Considered
- Keep synchronous scanning in the request path
Rejected because p95 request time was already too close to the timeout budget.
- Upload directly through the app server
Rejected because it increases memory pressure during spikes and complicates retries.
## Consequences
- Faster user response after upload confirmation
- More queue dependency during incident response
- Need clearer job idempotency rules
## Review Focus
- Retry safety for duplicate upload events
- Cleanup behavior for failed scan jobs
- Tenant isolation in generated file pathsNow the reviewer can help.
That is the real win. Showing your decision process does not make you look thoughtful in some abstract career-development sense. It makes the next conversation shorter and better.
When a small ADR beats another meeting
Some decisions deserve more than a PR description.
AWS Prescriptive Guidance describes ADRs as a way to capture the context, choice and consequences of a significant software decision. The ADR repository that many teams reference says the same thing even more plainly: the point is to capture an important architecture decision along with its context and consequences.
That sounds formal. It does not have to be.
A useful ADR for a small team can be one short Markdown file in git. Not a committee artifact. Not a six-page memo. Just enough that the next engineer understands what was chosen and why.
This is the template I would actually use:
# Use queued image processing after upload
## Context
- Uploads are growing past 25 MB
- App servers should not hold request threads for scanning and resizing
- Current team can operate queues but does not want another persistent service
## Decision
- Keep signed uploads to object storage
- Trigger scanning and resizing asynchronously with queue workers
## Consequences
- Faster request completion for end users
- More operational dependence on queue health
- Need idempotent jobs and dead-letter handling
## Revisit When
- Upload volume grows enough that queue lag becomes user-visible
- Security policy requires in-line scanning before file acceptanceThat is enough for most small-team decisions.
The hidden benefit is onboarding. New engineers do not just inherit the current shape of the system. They inherit the reasons behind it. That lowers the chance that somebody “cleans up” a rough edge which only existed because it solved a production problem they never saw.
Tools matter. They are just not the first signal.
I do not mean tools are irrelevant.
Of course tool choice matters. Some tools are better maintained, some fit the team better, some reduce operational burden and some create it. A few turn a sharp problem into a boring one. That is worth caring about.
What is not worth doing is treating tool selection like the main display of engineering maturity.
I have seen engineers impress people with a fashionable stack and then make life harder for everyone because they could not explain the rollback path. I have also seen engineers choose the boring option and earn immediate trust because they documented the risk clearly, named what they were giving up and left the team with a decision trail that still made sense three months later.
One of those scales socially. The other only looks smart in the meeting.
This is especially obvious on small teams.
If you are a solo lead or one of two backend engineers, your best tool is often the one you can explain, review, debug and revisit without ceremony. The fancy choice may still be right. Fine. But if the reasoning cannot survive a handoff, the decision is weaker than it looks.
That is why I care less about whether an engineer picked Redis or SQS, Octane or PHP-FPM, Terraform or a simpler deployment pat, and more about whether they can answer four plain questions:
- What pressure were you optimizing for?
- What did you reject?
- What pain are we accepting in return?
- What future condition would make us revisit this?
If those answers are missing, the tool recommendation is incomplete.
The habit that changes how people trust your work
If you want one habit to take from this article, it is this:
Before you recommend a tool, write the decision trail in a form another engineer can challenge.
Not mentally. In writing.
The writing matters because it forces specificity. You notice weak reasoning faster when you try to put it in sentences. “This is more scalable” starts sounding suspiciously empty once you have to explain scalable in what dimension, under what load, with what team, at what cost.
This is also why teams that write their reasoning tend to look more aligned than teams that rely on verbal consensus. The written version exposes fuzzy assumptions before they turn into implementation.
And once that becomes normal, something nice happens.
Tool discussions get calmer.
People stop defending identity and start defending trade-offs. Review comments get sharper, handoffs get easier and repeated arguments shrink. Junior engineers learn faster because they can finally see how a decision was made instead of only seeing the final answer.
The team does not become perfect. It becomes legible, which is a much better goal.
Start small if you want this to stick
Do not roll out a grand process. Add one lightweight rule:
Every non-trivial tool recommendation must include context, rejected options, consequences and a revisit trigger.
Put it in your pull request template. Put it in an ADR folder. Put it in an engineering RFC if your team already uses one. The storage format matters less than the habit.
The habit is the point.
Tools come and go. The quality of your decisions stays visible much longer.
