The Architecture Decision Record: Why Your Team Needs One
Every engineering team has had this conversation. A developer opens a module, stares at an implementation that seems needlessly complex, and asks: "Why was it built this way?" The room goes quiet. The person who made the decision left eight months ago. Someone vaguely recalls a Slack thread. Another remembers a whiteboard session that was never photographed. Nobody can explain the actual reasoning.
So the team does one of two things. They either leave it alone out of fear ("there was probably a reason"), creating permanent technical debt that nobody will touch. Or they refactor it, unknowingly reintroducing the exact problem the original implementation was designed to avoid. I've seen both happen more times than I can count.
Architecture Decision Records fix this. They're one of the simplest, highest-ROI practices an engineering team can adopt, and most teams don't use them.
What an ADR Actually Is
An ADR is a short document -- usually under a page -- that captures a single architectural decision. Not a design document. Not an RFC. Not a specification. Just a record of what was decided, why it was decided, and what the expected consequences are.
The format is deliberately minimal. The most widely used structure, based on Michael Nygard's original proposal, has five sections:
- Title. A short noun phrase. "Use PostgreSQL for transactional data." "Adopt event sourcing for order processing." "Implement JWT-based authentication."
- Status. Proposed, Accepted, Deprecated, or Superseded. If superseded, link to the new ADR.
- Context. What is the situation? What forces are at play? What constraints exist? This is where you capture the state of the world at the time of the decision.
- Decision. What did we decide? State it clearly and directly.
- Consequences. What follows from this decision? Both positive and negative. What becomes easier? What becomes harder? What new constraints does this create?
That's it. No 20-page template. No approval workflow. No committee. A developer writes it, the team reviews it, and it lives in the repo alongside the code it describes.
Why the Context Section Is Everything
The decision itself is usually obvious from looking at the code. You can see that the system uses RabbitMQ. You can see that authentication runs through JWT tokens. You can see that the data layer uses an event-sourced pattern.
What you can't see is why. And the why is where all the value lives.
A good context section captures the decision landscape at the time: the alternatives that existed, the constraints the team was operating under, the trade-offs they weighed. It might read something like:
"We need a message queue for async processing of order events. Current volume is 500 messages/second with projected growth to 5,000/second within 12 months. The team has experience with RabbitMQ but not Kafka. We're a team of four and cannot afford the operational overhead of managing a Kafka cluster. Our cloud provider offers a managed RabbitMQ service but not managed Kafka."
Six months later, when a new engineer asks "why didn't we use Kafka?", the answer is right there. No archaeology required. No pinging someone on Slack who may or may not remember. And critically, when the team does grow to the point where Kafka makes sense, they can create a new ADR that supersedes this one, with full understanding of what changed.
Examples of Good ADR Topics
Not every decision needs an ADR. Choosing between two date-formatting libraries doesn't warrant one. The threshold I use: if the decision is hard to reverse, affects multiple parts of the system, or will be questioned by future team members, write an ADR.
Here are examples of decisions that should always have one:
Choosing a database. "ADR-003: Use PostgreSQL for transactional data and Redis for session storage." Context captures why not MongoDB (schema flexibility wasn't worth the consistency trade-offs for this domain), why not a single database for everything (session data has fundamentally different access patterns), and what the operational implications are.
Authentication approach. "ADR-007: Implement JWT-based stateless authentication with refresh tokens." Context explains why not session-based auth (the system needs to support multiple client types including mobile), the trade-off of not being able to immediately revoke tokens, and the mitigation strategy (short expiry + refresh rotation).
Service communication pattern. "ADR-012: Use synchronous REST between services for reads, async events for writes." Context captures why not fully event-driven (the team doesn't have the expertise yet and the system isn't complex enough to justify the operational overhead), and when to revisit this decision.
Third-party service selection. "ADR-015: Use Stripe for payment processing instead of building a custom integration with the bank API." Context documents the cost comparison, the vendor lock-in trade-off, and the specific capabilities that drove the decision.
Where ADRs Live
This is non-negotiable: ADRs live in the code repository. Not in Confluence. Not in Google Docs. Not in Notion. In the repo, in a directory like /docs/adr/ or /adr/, versioned alongside the code they describe.
The reasons are practical: they're discoverable (right there when a developer is working in the codebase), versioned (Git gives you history and blame for free), they travel with the code (fork the repo and the decisions come with it), and they're reviewed like code (ADRs go through pull requests, adding even more context).
Number them sequentially: 0001-use-postgresql-for-transactional-data.md, 0002-adopt-jwt-authentication.md. The numbering creates a timeline that tells the story of how the architecture evolved.
The Cost of Not Having ADRs
The absence of ADRs creates three specific, measurable problems:
Tribal knowledge. Architectural decisions live in the heads of the people who made them. When those people leave -- and they will leave -- the knowledge goes with them. The remaining team inherits an architecture they don't fully understand, which they either treat as sacred (refusing to change things they don't understand) or treat as disposable (refactoring without understanding the constraints).
Rehashed debates. Without a record of why a decision was made, teams revisit the same discussions every few months. "Should we switch to Kafka?" gets debated three times a year because nobody remembers that the team already evaluated and rejected it for specific, documented reasons. Each debate burns hours of senior engineering time and creates frustration.
Onboarding friction. A new team member joining without ADRs has to reverse-engineer the entire architectural rationale from the code, from scattered Slack messages, and from whatever the existing team can recall in impromptu explanations. I've seen onboarding periods stretch from weeks to months purely because of missing architectural context.
Getting Started Without Overhead
The biggest mistake teams make with ADRs is treating them as a bureaucratic exercise. They create elaborate templates, review committees, and approval workflows. Then nobody writes them because the overhead isn't worth it.
Start simple. The next time your team makes a significant architectural decision, have the person who drove the decision spend 20 minutes writing it up in the five-section format. Put it in a PR. Review it. Merge it. That's your first ADR.
Do this five times. By the fifth ADR, the team will start referencing the earlier ones in discussions. "This is the same trade-off we captured in ADR-003." That's the moment the practice becomes self-sustaining -- when the team sees the value in their own workflow, not because a process document says they should.
At Conectia, we've seen ADRs make a particularly large difference on distributed teams. When our senior engineers join a client's team, existing ADRs let them understand the architectural rationale in days instead of weeks. And when they contribute new ADRs, they're adding to the institutional memory in a way that outlasts any individual's tenure. It's one of those small practices that compounds over time into a serious competitive advantage for the engineering org.
The best time to start writing ADRs was when you made your first architectural decision. The second best time is now.
Building a team that makes strong architectural decisions and documents them? Talk to a CTO -- our senior LATAM engineers bring the discipline of structured decision-making to your codebase from day one.
