ADRs as Portfolio Pieces: Showing How You Think

Most engineering portfolios are broken. Not the code — the premise.

You’ve got a GitHub profile with some projects, maybe a personal site with screenshots and tech stack badges. The portfolio answers one question really well: what did you build? And for junior and mid-level roles, that’s enough. Can you write code? Can you ship something? Great, hired.

But senior and staff-level hiring doesn’t work that way. At that level, the question isn’t “can you build things.” Everyone in the room can build things. The question is “how do you decide what to build, how to build it, and what tradeoffs you’re willing to accept.” That’s engineering judgment. And a GitHub repo full of code tells me almost nothing about your judgment.

I think Architecture Decision Records — ADRs — are the missing piece. And I think they might be the single best portfolio artifact for senior engineers.

What ADRs Are (and Aren’t)

An ADR is a short document that captures a single architectural decision. Not a design doc. Not an RFC. Not a wiki page that tries to explain everything. Just one decision, with four sections:

• Context — what’s the situation? What problem are you solving? What constraints exist?
• Decision — what did you decide?
• Rationale — why this option over the alternatives?
• Consequences — what are the positive and negative results of this decision?

That’s it. A good ADR is one to two pages. It takes 30-60 minutes to write. And it captures something that almost no other engineering artifact captures: the reasoning behind a technical choice.

Here’s the thing about code: it shows you the what but never the why. I can look at your Kubernetes deployment and see you’re using Cilium as your CNI. But I can’t see that you evaluated Calico, Flannel, and Weave Net, chose Cilium for eBPF performance on resource-constrained ARM64 hardware, accepted the tradeoff of a steeper learning curve for CiliumNetworkPolicy CRDs, and specifically wanted L7-aware policies for IoT segmentation. That reasoning is invisible in the code. It’s visible in an ADR.

Why ADRs Are Perfect Portfolio Pieces

Let me make the case for why ADRs belong in your portfolio, specifically.

They Show Engineering Judgment

Senior engineering is fundamentally about making good decisions under uncertainty. Not perfect decisions — good ones. With incomplete information, competing constraints, and real consequences.

An ADR demonstrates this directly. When I wrote ADR-001: Cilium as CNI over Calico, the decision wasn’t obvious. Calico is mature, well-documented, and the most popular Kubernetes CNI. Choosing Cilium instead required articulating why: eBPF performance on SBCs where every CPU cycle matters, L7-aware network policies for IoT workloads that need more than L3/L4 segmentation, Hubble observability for security monitoring. And then acknowledging the costs: steeper learning curve, kernel dependency, additional resource overhead from Hubble.

That’s what engineering judgment looks like. It’s not “I picked the popular thing.” It’s “I evaluated the options against my specific constraints and made a deliberate choice with documented tradeoffs.”

They Demonstrate Tradeoff Analysis

Every interesting engineering decision involves tradeoffs. The mark of a senior engineer isn’t avoiding tradeoffs — it’s identifying them, evaluating them, and making conscious choices about which ones to accept.

ADRs force you to make tradeoffs explicit. You can’t write a good “Consequences” section without honestly listing both the positive and negative outcomes. When I chose PostgreSQL over SQLite for Home Assistant’s recorder database, the positive consequences were clear: no WAL locking issues on networked storage, better concurrent write handling, standard backup tooling. But the negative consequences were real too: operational complexity of running a separate database, additional resource consumption on constrained hardware, another component to monitor and maintain.

A hiring manager reading that doesn’t just see the decision. They see that you thought about it. That you didn’t just reach for the fancy option without considering the cost.

They Prove Communication Skills

Here’s something that doesn’t get said enough: communication is a core senior engineering competency. Not “nice to have.” Core. Staff engineers spend more time communicating decisions than writing code. And the ability to explain a technical decision clearly — to other engineers, to managers, to future you — is a skill that separates senior engineers from very productive mid-level engineers.

An ADR is a communication artifact. It’s a document that takes a complex technical decision and explains it clearly enough that someone who wasn’t in the room can understand what was decided, why, and what the implications are. If you can write a good ADR, you can write a good design doc, a good RFC, a good engineering blog post, and a good Slack message explaining why the migration is going to take three sprints instead of one.

They’re Low-Effort, High-Signal

A side project with clean code, tests, and CI takes weeks or months. An ADR takes an hour. And for senior hiring, the ADR might actually be more useful.

I’m not saying don’t build things. Build things. But when you make an interesting decision in your project — when you choose one database over another, one framework over another, one architecture over another — take an hour and write down why. The decision is happening anyway. The ADR is just capturing the reasoning that would otherwise evaporate.

What Good Portfolio ADRs Look Like

Not every decision deserves an ADR. “I chose React because I know React” is not interesting. The decisions worth documenting are the ones where you genuinely evaluated alternatives and made a deliberate choice.

Some patterns from my own portfolio:

Infrastructure decisions with competing options. Cilium over Calico — both are legitimate CNIs with different strengths. The interesting part isn’t the choice; it’s the constraint analysis. eBPF matters because SBCs are resource-constrained. L7 policies matter because IoT workloads need granular segmentation. These constraints drive the decision. Without them, you’d probably just pick Calico because it’s popular.

Protocol design decisions. Choosing JSON-RPC 2.0 as the inter-agent message format for the Fiduciary Agent Framework — the rationale involved MCP ecosystem alignment, existing tooling for validation, and the request/response/notification semantics mapping cleanly to agent communication patterns. The alternative (custom protocol) would have been more flexible but less interoperable. Tradeoff documented, decision made.

“Boring” decisions that reveal judgment. Choosing a plain PostgreSQL StatefulSet over CloudNativePG (a Kubernetes operator) for a single database instance. The reasoning: an operator for one instance is like hiring a building superintendent for a studio apartment. The complexity cost exceeds the operational benefit at this scale. This kind of decision — choosing the simpler option and explaining why — often shows better judgment than choosing the complex option.

How to Start

If you’re convinced — or at least curious — here’s how to start writing ADRs for your portfolio.

Pick a Template

The original Michael Nygard format is fine:

# ADR-NNN: [Title]

**Status:** Accepted | Deprecated | Superseded
**Date:** YYYY-MM-DD

## Context
[What's the situation? What problem are you solving?]

## Decision
[What did you decide?]

## Rationale
[Why this over the alternatives?]

## Consequences
### Positive
[What improved?]

### Negative
[What got harder? What's the ongoing cost?]

Don’t overthink the template. The content matters more than the format.

Write ADRs for Decisions You’ve Already Made

You don’t need to start a new project. Look at your existing work — personal or professional (sanitized, obviously) — and identify decisions worth documenting.

Did you choose a database? A hosting platform? A state management library? An authentication approach? A CI/CD tool? Any of these could be an ADR if the decision involved genuine evaluation of alternatives.

Be Honest About Tradeoffs

This is the part most people get wrong. The temptation is to write an ADR that makes your decision sound obviously correct. Resist that. The value of an ADR is in the honest assessment of what you gained and what you gave up.

“Cilium has a steeper learning curve than Calico” isn’t a weakness in my ADR. It’s a strength. It tells the reader I know what the decision costs and I chose it anyway, for specific reasons.

Include the “Alternatives Considered” Section

Don’t just say what you chose. Say what you didn’t choose and why. This is where engineering judgment is most visible. “I considered X, Y, and Z. Here’s why I didn’t pick each one.” That’s a structured evaluation, not a gut feel.

Make Them Accessible

Put them in your portfolio site, your GitHub repo, or wherever you showcase your work. Group them by project. Link them to the relevant code or architecture diagrams. Make it easy for someone to go from “here’s the project” to “here’s how decisions were made.”

The Meta Point

There’s something recursive about this post. I’m writing about ADRs as portfolio pieces, and the ADRs I’m referencing are in my portfolio. The portfolio itself is a demonstration of the argument.

But here’s the real point: senior engineering is about decision-making. Your portfolio should show how you make decisions, not just what you produce. Code shows output. ADRs show process. And at the level where companies are hiring for judgment, process is what matters.

Start writing them. Even for personal projects. Especially for personal projects — because personal projects are the ones where you have complete freedom to make decisions and complete ability to document why.

Your future interviewer will thank you. And honestly? Future you will thank you too. There’s nothing quite like reading your own ADR from six months ago and understanding exactly why you made that choice, instead of staring at a config file and thinking “why the hell did I do it this way?”

Write it down. Show your work. Let people see how you think.