Technical Decision Records
Technical decision records preserve why a choice was made, not just what the code now does. They are most valuable when the decision is expensive to reverse, changes operational risk, affects multiple teams, or sets a precedent for future software architecture.
Status, context, decision, and consequences
A small ADR usually has status, context, decision, alternatives, consequences, and links to evidence. The status is part of the contract: proposed, accepted, deprecated, or superseded. Keep the record near the code or docs it governs so documentation and implementation drift are visible.
ADR example
# ADR-004: Use Hosted Embeddings For First Release
Status: Accepted, 2026-07-11
Context:
- Expected launch traffic: 20 requests/minute, p95 retrieval budget 350 ms.
- Privacy review allows provider processing for support-ticket text with PII masking.
- The team has no GPU serving owner before launch.
Decision:
- Use the hosted embedding API behind the retrieval service interface.
- Store embedding_model, embedding_version, document_version, and trace_id with each indexed chunk.
Alternatives:
- Self-host small embedding model: lower provider dependency, higher operations burden.
- Delay semantic retrieval: lower risk, worse answer quality for paraphrased questions.
Consequences:
- Add provider timeout and fallback to keyword search in production integration.
- Reconsider self-hosting when traffic exceeds 200 requests/minute for four consecutive weeks.This artifact is not runnable because an ADR is a governance object, but it is concrete enough for requirements engineering, api design, and production integration to inspect. It names traffic, latency, privacy, owner, fallback, and a reconsideration trigger.
Failure modes
Decision records fail when they are written only for approvals, omit alternatives, or never get superseded after reality changes. A vague note saying “hosted is simpler” is not an ADR; it does not tell a future engineer which constraint mattered or when to revisit the choice.
References
- Architectural Decision Records
- MADR: Markdown Architectural Decision Records
- arc42 Template Overview
Nav