Guides · Architecture decision records
Architecture decision records on a delivery program
Michael Nygard's 2011 practice is to keep short records of architecturally significant decisions — each one a set of forces and a single decision in response — so a later engineer does not have to accept or reverse that decision blindly. On a delivery program that will be audited, staffed, or handed over, that habit is part of leaving the work in a state someone else can continue. This is the delivery-program reading of the same 2011 essay used on PrimusNeo's ADR page. It is not an OSGA process badge.
Michael Nygard, "Documenting Architecture Decisions," 15 November 2011. Documents that assist the team "can have value, but only if they are kept up to date. Large documents are never kept up to date." Without the rationale, a later person can only "blindly accept" or "blindly change" the decision. "We will keep a collection of records for ‘architecturally significant’ decisions: those that affect the structure, non-functional characteristics, dependencies, interfaces, or construction techniques." Each ADR "describes a set of forces and a single decision in response to those forces." Number sequentially; do not reuse numbers; keep superseded records and mark them as such.
The format parts, as Nygard defined them: Title, Context (value-neutral facts), Decision ("We will …"), Status (proposed / accepted / deprecated / superseded), Consequences. Nygard's doc/arch/adr-NNN.md path is quoted as his convention, not as an OSGA repository layout. No extra sections are invented here.
What a delivery program can keep
A later engineer, an auditor, or a handover should be able to read why a structural choice was made, not only what the current code does. This page does not claim a house ADR standard, invent a rework percentage, or name a client. It is not a certification.
Verifiable requirements and a definition of done and Working software in Agile development are the delivery-test siblings. Asking for a software bill of materials is the inventory sibling in this batch.
The first conversation still ends with a yes, a no, or a better idea, at Start. The dashboard remains "opening soon."
The useful next step is to write a short record of the next architecturally significant decision, before the program is handed over. If something on this page is wrong, write to us.