Developer · THE NO-PANIC PLAN
Create a software architecture decision log with reviewable ADRs
Use this workflow for software architecture choices that affect system structure, security or other quality attributes, interfaces, dependencies, or are difficult to reverse. It is not a log for every routine implementation choice or a substitute for a design proposal. An architecture decision record (ADR) should make clear what was decided, why, which alternatives were considered and what consequences follow. Keep the accepted history available to the team: when a decision changes, add a new record that supersedes the old one rather than silently rewriting the original. Nirmion's Decision Log Template can structure an entry, but your team repository and review process remain the source of truth.
MISSION Help a software team record architecturally significant decisions with context, alternatives, rationale, consequences, ownership and a traceable status history.
Draft an architecture decision recordTHE REAL-WORLD BIT
What happens outside this browser tab?
Identify decisions that merit an ADR and name an owner; record the context, constraints, options and consequences; circulate a proposed record to the right reviewers; capture the accepted or rejected outcome in a shared decision log; and validate later work against the decision while preserving superseded history.
YOUR CHECKLIST, WITH FEWER DRAMATIC SIGHES
One step at a time.
Follow the order below. If a step names a Nirmion tool, its link is right there with it.
- 01
Confirm the decision belongs in an architecture record
Describe the choice in one sentence and identify the software system, component or interface it affects. Use an ADR when the choice changes system structure, a key quality attribute such as security or availability, an important dependency or published API contract, or when reversing it later would be costly. Routine code details that are easy to change may not need a separate record. Name a decision owner and the sponsor or technical authority who can approve it; identify the engineers and service owners whose systems or operational responsibilities are affected. If a single choice will be delivered in distinct phases, decide whether each phase is a separate decision. Keep this workflow scoped to technical architecture; business policy, employment and legal decisions need their own governance.
- 02
Write the context, options, decision and consequences
Start a concise draft with a stable identifier, date, owner, status and a short title that states the choice. Explain the problem and constraints, such as latency, security, compatibility, cost, team capability or deployment requirements. List the viable options actually considered, including the status quo where relevant, and compare their material trade-offs rather than presenting a preferred option as inevitable. State the proposed or accepted decision plainly, the rationale, expected benefits, known risks, operational implications and confidence or unresolved questions. Link supporting designs, measurements, threat models or requirements instead of turning the ADR into a duplicate design guide. The Microsoft and AWS guidance both emphasize context, alternatives or options, rationale, decision and consequences; the Decision Log Template (tool 11658) can organize an entry, but it does not choose or approve an architecture.
- 03
Review the proposal with accountable stakeholders
Mark the draft Proposed and share it in the team's normal architecture repository or review channel with the owner, approver and affected contributors. Set a review date that fits the project's decision deadline and give reviewers enough time to read the context, options and consequences. Ask them to flag missing constraints, operational impacts, security concerns, migration needs, reversibility and unsupported assumptions. Record each action with an owner and due date, then revise the proposal while it is still proposed. The approver should record whether the ADR is accepted, needs rework or is rejected, with a brief reason for rejection so the same question is not repeatedly reopened. Do not call a proposal accepted because it was posted or because no one replied; follow the team's explicit approval policy.
- 04
Publish the outcome in a durable decision log
After the decision authority resolves the review, record the final state, decision date, approver or stakeholders, rationale, consequences and links to implementation work. Store the ADR with the software project's accessible documentation, commonly in a version-controlled repository or a team wiki, and add it to the log or index with its identifier and status so teammates can find it. Keep the record concise and use the same fields for every ADR. The Decision Log Template can help create a structured entry with dates, owners, rationale and review dates; place the resulting approved record in the team's own system of record because the Nirmion utility does not provide team authorization, repository history or approval evidence. Preserve any rejection and its reasoning according to your team's record-retention policy.
- 05
Check implementation and supersede decisions without erasing history
Before a related design or code change is accepted, have reviewers check whether it follows the current accepted ADR and link the relevant record in the review. If implementation no longer matches the decision, either correct the change or take the discrepancy through the team's change process. Revisit a decision when its assumptions, requirements, constraints or operating conditions materially change. If the team approves a different direction, create and review a new ADR, explain what changed, link it to the prior record and mark the old one Superseded; do not edit an accepted ADR in place. Keep the index current and confirm that the new record and its links are readable to future maintainers. A decision log preserves reasoning, but does not itself guarantee compliance or replace code review, security assessment or architectural approval.
THE HELPER CREW
Tools for the fiddly bits.
These are the currently published Nirmion tools matched to this guide. Open a tool page for its accepted inputs and limits.
RECEIPTS, PLEASE
Sources & review notes
Each source is linked to the steps it supports. Open it to check its scope and current guidance.
Source checked 2026-10-05